From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: mx.groups.io; dkim=missing; spf=fail (domain: intel.com, ip: , mailfrom: eric.dong@intel.com) Received: from mga18.intel.com (mga18.intel.com []) by groups.io with SMTP; Mon, 08 Jul 2019 07:01:36 -0700 X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 08 Jul 2019 07:01:36 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.63,466,1557212400"; d="scan'208";a="167684528" Received: from ydong10-win10.ccr.corp.intel.com ([10.239.158.133]) by orsmga003.jf.intel.com with ESMTP; 08 Jul 2019 07:01:34 -0700 From: "Dong, Eric" To: devel@edk2.groups.io Cc: Ray Ni , Laszlo Ersek Subject: [Patch 1/2] MdePkg: Add new MM MP Protocol definition. Date: Mon, 8 Jul 2019 22:01:29 +0800 Message-Id: <20190708140130.10632-2-eric.dong@intel.com> X-Mailer: git-send-email 2.21.0.windows.1 In-Reply-To: <20190708140130.10632-1-eric.dong@intel.com> References: <20190708140130.10632-1-eric.dong@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit REF: https://bugzilla.tianocore.org/show_bug.cgi?id=1937 EFI MM MP Protocol is defined in the PI 1.5 specification. The MM MP protocol provides a set of functions to allow execution of procedures on processors that have entered MM. This protocol has the following properties: 1. The caller can invoke execution of a procedure on a processor, other than the caller, that has also entered MM. Supports blocking and non-blocking modes of operation. 2. The caller can invoke a procedure on multiple processors. Supports blocking and non-blocking modes of operation. Cc: Ray Ni Cc: Laszlo Ersek Signed-off-by: Eric Dong Reviewed-by: Ray Ni --- MdePkg/Include/Pi/PiMultiPhase.h | 16 ++ MdePkg/Include/Protocol/MmMp.h | 333 +++++++++++++++++++++++++++++++ MdePkg/MdePkg.dec | 3 + 3 files changed, 352 insertions(+) create mode 100644 MdePkg/Include/Protocol/MmMp.h diff --git a/MdePkg/Include/Pi/PiMultiPhase.h b/MdePkg/Include/Pi/PiMultiPhase.h index eb12527767..a5056799e1 100644 --- a/MdePkg/Include/Pi/PiMultiPhase.h +++ b/MdePkg/Include/Pi/PiMultiPhase.h @@ -176,4 +176,20 @@ VOID IN OUT VOID *Buffer ); +/** + The function prototype for invoking a function on an Application Processor. + + This definition is used by the UEFI MM MP Serices Protocol. + + @param[in] ProcedureArgument The pointer to private data buffer. + + @retval EFI_SUCCESS Excutive the procedure successfully + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_AP_PROCEDURE2)( + IN VOID *ProcedureArgument +); + #endif diff --git a/MdePkg/Include/Protocol/MmMp.h b/MdePkg/Include/Protocol/MmMp.h new file mode 100644 index 0000000000..beace1386c --- /dev/null +++ b/MdePkg/Include/Protocol/MmMp.h @@ -0,0 +1,333 @@ +/** @file + EFI MM MP Protocol is defined in the PI 1.5 specification. + + The MM MP protocol provides a set of functions to allow execution of procedures on processors that + have entered MM. This protocol has the following properties: + 1. The caller can only invoke execution of a procedure on a processor, other than the caller, that + has also entered MM. + 2. It is possible to invoke a procedure on multiple processors. Supports blocking and non-blocking + modes of operation. + + Copyright (c) 2019, Intel Corporation. All rights reserved.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _MM_MP_H_ +#define _MM_MP_H_ + +#include + +#define EFI_MM_MP_PROTOCOL_GUID \ + { \ + 0x5d5450d7, 0x990c, 0x4180, {0xa8, 0x3, 0x8e, 0x63, 0xf0, 0x60, 0x83, 0x7 } \ + } + +// +// Revision definition. +// +#define EFI_MM_MP_PROTOCOL_REVISION 0x00 + +// +// Attribute flags +// +#define EFI_MM_MP_TIMEOUT_SUPPORTED 0x01 + +// +// Completion token +// +typedef VOID* MM_COMPLETION; + +typedef struct { + MM_COMPLETION Completion; + EFI_STATUS Status; +} MM_DISPATCH_COMPLETION_TOKEN; + +typedef struct _EFI_MM_MP_PROTOCOL EFI_MM_MP_PROTOCOL; + +/** + Service to retrieves the number of logical processor in the platform. + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[out] NumberOfProcessors Pointer to the total number of logical processors in the system, + including the BSP and all APs. + + @retval EFI_SUCCESS The number of processors was retrieved successfully + @retval EFI_INVALID_PARAMETER NumberOfProcessors is NULL +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_GET_NUMBER_OF_PROCESSORS) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + OUT UINTN *NumberOfProcessors +); + + +/** + This service allows the caller to invoke a procedure one of the application processors (AP). This + function uses an optional token parameter to support blocking and non-blocking modes. If the token + is passed into the call, the function will operate in a non-blocking fashion and the caller can + check for completion with CheckOnProcedure or WaitForProcedure. + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Procedure A pointer to the procedure to be run on the designated target + AP of the system. Type EFI_AP_PROCEDURE2 is defined below in + related definitions. + @param[in] CpuNumber The zero-based index of the processor number of the target + AP, on which the code stream is supposed to run. If the number + points to the calling processor then it will not run the + supplied code. + @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for this AP to + finish execution of Procedure, either for blocking or + non-blocking mode. Zero means infinity. If the timeout + expires before this AP returns from Procedure, then Procedure + on the AP is terminated. If the timeout expires in blocking + mode, the call returns EFI_TIMEOUT. If the timeout expires + in non-blocking mode, the timeout determined can be through + CheckOnProcedure or WaitForProcedure. + Note that timeout support is optional. Whether an + implementation supports this feature, can be determined via + the Attributes data member. + @param[in,out] ProcedureArguments Allows the caller to pass a list of parameters to the code + that is run by the AP. It is an optional common mailbox + between APs and the caller to share information. + @param[in,out] Token This is parameter is broken into two components: + 1.Token->Completion is an optional parameter that allows the + caller to execute the procedure in a blocking or non-blocking + fashion. If it is NULL the call is blocking, and the call will + not return until the AP has completed the procedure. If the + token is not NULL, the call will return immediately. The caller + can check whether the procedure has completed with + CheckOnProcedure or WaitForProcedure. + 2.Token->Status The implementation updates the address pointed + at by this variable with the status code returned by Procedure + when it completes execution on the target AP, or with EFI_TIMEOUT + if the Procedure fails to complete within the optional timeout. + The implementation will update this variable with EFI_NOT_READY + prior to starting Procedure on the target AP. + @param[in,out] CPUStatus This optional pointer may be used to get the status code returned + by Procedure when it completes execution on the target AP, or with + EFI_TIMEOUT if the Procedure fails to complete within the optional + timeout. The implementation will update this variable with + EFI_NOT_READY prior to starting Procedure on the target AP. + + @retval EFI_SUCCESS In the blocking case, this indicates that Procedure has completed + execution on the target AP. + In the non-blocking case this indicates that the procedure has + been successfully scheduled for execution on the target AP. + @retval EFI_INVALID_PARAMETER The input arguments are out of range. Either the target AP is the + caller of the function, or the Procedure or Token is NULL + @retval EFI_NOT_READY If the target AP is busy executing another procedure + @retval EFI_ALREADY_STARTED Token is already in use for another procedure + @retval EFI_TIMEOUT In blocking mode, the timeout expired before the specified AP + has finished +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_DISPATCH_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN EFI_AP_PROCEDURE2 Procedure, + IN UINTN CpuNumber, + IN UINTN TimeoutInMicroseconds, + IN OUT VOID *ProcedureArguments OPTIONAL, + IN OUT MM_COMPLETION *Token, + IN OUT EFI_STATUS *CPUStatus +); + +/** + This service allows the caller to invoke a procedure on all running application processors (AP) + except the caller. This function uses an optional token parameter to support blocking and + nonblocking modes. If the token is passed into the call, the function will operate in a non-blocking + fashion and the caller can check for completion with CheckOnProcedure or WaitForProcedure. + + It is not necessary for the implementation to run the procedure on every processor on the platform. + Processors that are powered down in such a way that they cannot respond to interrupts, may be + excluded from the broadcast. + + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Procedure A pointer to the code stream to be run on the APs that have + entered MM. Type EFI_AP_PROCEDURE is defined below in related + definitions. + @param[in] TimeoutInMicroseconds Indicates the time limit in microseconds for the APs to finish + execution of Procedure, either for blocking or non-blocking mode. + Zero means infinity. If the timeout expires before all APs return + from Procedure, then Procedure on the failed APs is terminated. If + the timeout expires in blocking mode, the call returns EFI_TIMEOUT. + If the timeout expires in non-blocking mode, the timeout determined + can be through CheckOnProcedure or WaitForProcedure. + Note that timeout support is optional. Whether an implementation + supports this feature can be determined via the Attributes data + member. + @param[in,out] ProcedureArguments Allows the caller to pass a list of parameters to the code + that is run by the AP. It is an optional common mailbox + between APs and the caller to share information. + @param[in,out] Token This is parameter is broken into two components: + 1.Token->Completion is an optional parameter that allows the + caller to execute the procedure in a blocking or non-blocking + fashion. If it is NULL the call is blocking, and the call will + not return until the AP has completed the procedure. If the + token is not NULL, the call will return immediately. The caller + can check whether the procedure has completed with + CheckOnProcedure or WaitForProcedure. + 2.Token->Status The implementation updates the address pointed + at by this variable with the status code returned by Procedure + when it completes execution on the target AP, or with EFI_TIMEOUT + if the Procedure fails to complete within the optional timeout. + The implementation will update this variable with EFI_NOT_READY + prior to starting Procedure on the target AP + @param[in,out] CPUStatus This optional pointer may be used to get the individual status + returned by every AP that participated in the broadcast. This + parameter if used provides the base address of an array to hold + the EFI_STATUS value of each AP in the system. The size of the + array can be ascertained by the GetNumberOfProcessors function. + As mentioned above, the broadcast may not include every processor + in the system. Some implementations may exclude processors that + have been powered down in such a way that they are not responsive + to interrupts. Additionally the broadcast excludes the processor + which is making the BroadcastProcedure call. For every excluded + processor, the array entry must contain a value of EFI_NOT_STARTED + + @retval EFI_SUCCESS In the blocking case, this indicates that Procedure has completed + execution on the APs. In the non-blocking case this indicates that + the procedure has been successfully scheduled for execution on the + APs. + @retval EFI_INVALID_PARAMETER Procedure or Token is NULL. + @retval EFI_NOT_READY If a target AP is busy executing another procedure. + @retval EFI_TIMEOUT In blocking mode, the timeout expired before all enabled APs have + finished. + @retval EFI_ALREADY_STARTED Before the AP procedure associated with the Token is finished, the + same Token cannot be used to dispatch or broadcast another procedure. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_BROADCAST_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN EFI_AP_PROCEDURE2 Procedure, + IN UINTN TimeoutInMicroseconds, + IN OUT VOID *ProcedureArguments OPTIONAL, + IN OUT MM_COMPLETION *Token, + IN OUT EFI_STATUS *CPUStatus +); + + +/** + This service allows the caller to set a startup procedure that will be executed when an AP powers + up from a state where core configuration and context is lost. The procedure is execution has the + following properties: + 1. The procedure executes before the processor is handed over to the operating system. + 2. All processors execute the same startup procedure. + 3. The procedure may run in parallel with other procedures invoked through the functions in this + protocol, or with processors that are executing an MM handler or running in the operating system. + + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Procedure A pointer to the code stream to be run on the designated target AP + of the system. Type EFI_AP_PROCEDURE is defined below in Volume 2 + with the related definitions of + EFI_MP_SERVICES_PROTOCOL.StartupAllAPs. + If caller may pass a value of NULL to deregister any existing + startup procedure. + @param[in,out] ProcedureArguments Allows the caller to pass a list of parameters to the code that is + run by the AP. It is an optional common mailbox between APs and + the caller to share information + + @retval EFI_SUCCESS The Procedure has been set successfully. + @retval EFI_INVALID_PARAMETER The Procedure is NULL. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_MM_SET_STARTUP_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN EFI_AP_PROCEDURE Procedure, + IN OUT VOID *ProcedureArguments OPTIONAL +); + +/** + When non-blocking execution of a procedure on an AP is invoked with DispatchProcedure, + via the use of a token, this function can be used to check for completion of the procedure on the AP. + The function takes the token that was passed into the DispatchProcedure call. If the procedure + is complete, and therefore it is now possible to run another procedure on the same AP, this function + returns EFI_SUCESS. In this case the status returned by the procedure that executed on the AP is + returned in the token's Status field. If the procedure has not yet completed, then this function + returns EFI_NOT_READY. + + When a non-blocking execution of a procedure is invoked with BroadcastProcedure, via the + use of a token, this function can be used to check for completion of the procedure on all the + broadcast APs. The function takes the token that was passed into the BroadcastProcedure + call. If the procedure is complete on all broadcast APs this function returns EFI_SUCESS. In this + case the Status field in the token passed into the function reflects the overall result of the + invocation, which may be EFI_SUCCESS, if all executions succeeded, or the first observed failure. + If the procedure has not yet completed on the broadcast APs, the function returns + EFI_NOT_READY. + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Token This parameter describes the token that was passed into + DispatchProcedure or BroadcastProcedure. + + @retval EFI_SUCCESS Procedure has completed. + @retval EFI_NOT_READY The Procedure has not completed. + @retval EFI_INVALID_PARAMETER Token or Token->Completion is NULL + @retval EFI_NOT_FOUND Token is not currently in use for a non-blocking call + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_CHECK_FOR_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN MM_COMPLETION Token +); + +/** + When a non-blocking execution of a procedure on an AP is invoked via DispatchProcedure, + this function will block the caller until the remote procedure has completed on the designated AP. + The non-blocking procedure invocation is identified by the Token parameter, which must match the + token that used when DispatchProcedure was called. Upon completion the status returned by + the procedure that executed on the AP is used to update the token's Status field. + + When a non-blocking execution of a procedure on an AP is invoked via BroadcastProcedure + this function will block the caller until the remote procedure has completed on all of the APs that + entered MM. The non-blocking procedure invocation is identified by the Token parameter, which + must match the token that used when BroadcastProcedure was called. Upon completion the + overall status returned by the procedures that executed on the broadcast AP is used to update the + token's Status field. The overall status may be EFI_SUCCESS, if all executions succeeded, or the + first observed failure. + + + @param[in] This The EFI_MM_MP_PROTOCOL instance. + @param[in] Token This parameter describes the token that was passed into + DispatchProcedure or BroadcastProcedure. + + @retval EFI_SUCCESS Procedure has completed. + @retval EFI_INVALID_PARAMETER Token or Token->Completion is NULL + @retval EFI_NOT_FOUND Token is not currently in use for a non-blocking call + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_WAIT_FOR_PROCEDURE) ( + IN CONST EFI_MM_MP_PROTOCOL *This, + IN MM_COMPLETION Token +); + + + +/// +/// The MM MP protocol provides a set of functions to allow execution of procedures on processors that +/// have entered MM. +/// +struct _EFI_MM_MP_PROTOCOL { + UINT32 Revision; + UINT32 Attributes; + EFI_MM_GET_NUMBER_OF_PROCESSORS GetNumberOfProcessors; + EFI_MM_DISPATCH_PROCEDURE DispatchProcedure; + EFI_MM_BROADCAST_PROCEDURE BroadcastProcedure; + EFI_MM_SET_STARTUP_PROCEDURE SetStartupProcedure; + EFI_CHECK_FOR_PROCEDURE CheckForProcedure; + EFI_WAIT_FOR_PROCEDURE WaitForProcedure; +}; + +extern EFI_GUID gEfiMmMpProtocolGuid; + +#endif diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 6c563375ee..b382efd578 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -1167,6 +1167,9 @@ # Protocols defined in PI 1.5. # + ## Include/Protocol/MmMp.h + gEfiMmMpProtocolGuid = { 0x5d5450d7, 0x990c, 0x4180, { 0xa8, 0x3, 0x8e, 0x63, 0xf0, 0x60, 0x83, 0x7 }} + ## Include/Protocol/MmEndOfDxe.h gEfiMmEndOfDxeProtocolGuid = { 0x24e70042, 0xd5c5, 0x4260, { 0x8c, 0x39, 0xa, 0xd3, 0xaa, 0x32, 0xe9, 0x3d }} -- 2.21.0.windows.1