[mp] Define an API for multiprocessor functions

Define an API for executing very limited functions on application
processors in a multiprocessor system, along with an x86-only
implementation.

The normal iPXE runtime environment is effectively non-existent on
application processors.  There is no ability to make firmware calls
(e.g. to write to a console), and there may be no stack space
available.

Signed-off-by: Michael Brown <mcb30@ipxe.org>

src/include/ipxe/mp.h

@@ -0,0 +1,154 @@
+#ifndef _IPXE_MP_H
+#define _IPXE_MP_H
+
+/** @file
+ *
+ * Multiprocessor functions
+ *
+ */
+
+FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
+
+#include <stdint.h>
+#include <ipxe/api.h>
+#include <config/defaults.h>
+
+/**
+ * An address within the address space for a multiprocessor function
+ *
+ * Application processors may be started in a different address space
+ * from the normal iPXE runtime environment.  For example: under
+ * legacy BIOS the application processors will use flat 32-bit
+ * physical addressing (with no paging or virtual address offset).
+ */
+typedef unsigned long mp_addr_t;
+
+/** A multiprocessor function
+ *
+ * @v opaque		Opaque data pointer
+ * @v cpuid		CPU identifier
+ *
+ * iPXE does not set up a normal multiprocessor environment.  In
+ * particular, there is no support for dispatching code to individual
+ * processors and there is no per-CPU stack allocation.
+ *
+ * Multiprocessor code must be prepared to run wth no stack space (and
+ * with a zero stack pointer).  Functions may use the CPU identifier
+ * to construct a pointer to per-CPU result storage.
+ *
+ * Multiprocessor functions are permitted to overwrite all registers
+ * apart from the stack pointer.  On exit, the function should check
+ * the stack pointer value: if zero then the function should halt the
+ * CPU, if non-zero then the function should return in the normal way.
+ *
+ * Multiprocessor functions do not have access to any capabilities
+ * typically provided by the firmware: they cannot, for example, write
+ * any console output.
+ *
+ * All parameters are passed in registers, since there may be no stack
+ * available.  These functions cannot be called directly from C code.
+ */
+typedef void ( mp_func_t ) ( mp_addr_t opaque, unsigned int cpuid );
+
+/**
+ * Call a multiprocessor function from C code on the current CPU
+ *
+ * @v func		Multiprocessor function
+ * @v opaque		Opaque data pointer
+ *
+ * This function must be provided for each CPU architecture to bridge
+ * the normal C ABI to the iPXE multiprocessor function ABI.  It must
+ * therefore preserve any necessary registers, determine the CPU
+ * identifier, call the multiprocessor function (which may destroy any
+ * registers other than the stack pointer), restore registers, and
+ * return to the C caller.
+ *
+ * This function must be called from within the multiprocessor address
+ * space (e.g. with flat 32-bit physical addressing for BIOS).  It can
+ * be called directly from C code if the multiprocessor address space
+ * is identical to the address space used for C code (e.g. under EFI,
+ * where everything uses flat physical addresses).
+ */
+extern void __asmcall mp_call ( mp_addr_t func, mp_addr_t opaque );
+
+/**
+ * Calculate static inline multiprocessor API function name
+ *
+ * @v _prefix		Subsystem prefix
+ * @v _api_func		API function
+ * @ret _subsys_func	Subsystem API function
+ */
+#define MPAPI_INLINE( _subsys, _api_func ) \
+	SINGLE_API_INLINE ( MPAPI_PREFIX_ ## _subsys, _api_func )
+
+/**
+ * Provide a multiprocessor API implementation
+ *
+ * @v _prefix		Subsystem prefix
+ * @v _api_func		API function
+ * @v _func		Implementing function
+ */
+#define PROVIDE_MPAPI( _subsys, _api_func, _func ) \
+	PROVIDE_SINGLE_API ( MPAPI_PREFIX_ ## _subsys, _api_func, _func )
+
+/**
+ * Provide a static inline multiprocessor API implementation
+ *
+ * @v _prefix		Subsystem prefix
+ * @v _api_func		API function
+ */
+#define PROVIDE_MPAPI_INLINE( _subsys, _api_func ) \
+	PROVIDE_SINGLE_API_INLINE ( MPAPI_PREFIX_ ## _subsys, _api_func )
+
+/* Include all architecture-independent multiprocessor API headers */
+#include <ipxe/null_mp.h>
+
+/* Include all architecture-dependent multiprocessor API headers */
+#include <bits/mp.h>
+
+/**
+ * Calculate address as seen by a multiprocessor function
+ *
+ * @v address		Address in normal iPXE address space
+ * @ret address		Address in application processor address space
+ */
+mp_addr_t mp_address ( void *address );
+
+/**
+ * Execute a multiprocessor function on the boot processor
+ *
+ * @v func		Multiprocessor function
+ * @v opaque		Opaque data pointer
+ *
+ * This is a blocking operation: the call will return only when the
+ * multiprocessor function exits.
+ */
+void mp_exec_boot ( mp_func_t func, void *opaque );
+
+/**
+ * Start a multiprocessor function on all application processors
+ *
+ * @v func		Multiprocessor function
+ * @v opaque		Opaque data pointer
+ *
+ * This is a non-blocking operation: it is the caller's responsibility
+ * to provide a way to determine when the multiprocessor function has
+ * finished executing and halted its CPU.
+ */
+void mp_start_all ( mp_func_t func, void *opaque );
+
+/**
+ * Update maximum observed CPU identifier
+ *
+ * @v opaque		Opaque data pointer
+ * @v cpuid		CPU identifier
+ *
+ * This may be invoked on each processor to update a shared maximum
+ * CPU identifier value.
+ */
+extern mp_func_t mp_update_max_cpuid;
+
+extern unsigned int mp_boot_cpuid ( void );
+extern unsigned int mp_max_cpuid ( void );
+
+#endif /* _IPXE_MP_H */

src/include/ipxe/null_mp.h

@@ -0,0 +1,36 @@
+#ifndef _IPXE_NULL_MP_H
+#define _IPXE_NULL_MP_H
+
+/** @file
+ *
+ * Null multiprocessor API implementation
+ *
+ */
+
+FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
+
+#ifdef MPAPI_NULL
+#define MPAPI_PREFIX_null
+#else
+#define MPAPI_PREFIX_null __null_
+#endif
+
+static inline __attribute__ (( always_inline )) mp_addr_t
+MPAPI_INLINE ( null, mp_address ) ( void *address ) {
+
+	return ( ( mp_addr_t ) address );
+}
+
+static inline __attribute__ (( always_inline )) void
+MPAPI_INLINE ( null, mp_exec_boot ) ( mp_func_t func __unused,
+				      void *opaque __unused ) {
+	/* Do nothing */
+}
+
+static inline __attribute__ (( always_inline )) void
+MPAPI_INLINE ( null, mp_start_all ) ( mp_func_t func __unused,
+				      void *opaque __unused ) {
+	/* Do nothing */
+}
+
+#endif /* _IPXE_NULL_MP_H */