mirror of https://github.com/acidanthera/audk.git
286 lines
18 KiB
C
286 lines
18 KiB
C
|
/** @file
|
||
|
|
Include file for SMM MP protocol implementation.
|
||
|
|
|
||
|
|
Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
|
||
|
|
|
||
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
||
|
|
|
||
|
|
**/
|
||
|
|
|
||
|
|
#ifndef _SMM_MP_PROTOCOL_H_
|
||
|
|
#define _SMM_MP_PROTOCOL_H_
|
||
|
|
|
||
|
|
//
|
||
|
|
// SMM MP Protocol function prototypes.
|
||
|
|
//
|
||
|
|
|
||
|
|
/**
|
||
|
|
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
|
||
|
|
**/
|
||
|
|
EFI_STATUS
|
||
|
|
EFIAPI
|
||
|
|
SmmMpGetNumberOfProcessors (
|
||
|
|
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
|
||
|
|
@retval EFI_OUT_OF_RESOURCES Could not allocate a required resource.
|
||
|
|
|
||
|
|
**/
|
||
|
|
EFI_STATUS
|
||
|
|
EFIAPI
|
||
|
|
SmmMpDispatchProcedure (
|
||
|
|
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 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
|
||
|
|
@retval EFI_OUT_OF_RESOURCES Could not allocate a required resource.
|
||
|
|
|
||
|
|
**/
|
||
|
|
EFI_STATUS
|
||
|
|
EFIAPI
|
||
|
|
SmmMpBroadcastProcedure (
|
||
|
|
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 but ProcedureArguments not NULL.
|
||
|
|
**/
|
||
|
|
EFI_STATUS
|
||
|
|
EFIAPI
|
||
|
|
SmmMpSetStartupProcedure (
|
||
|
|
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
|
||
|
|
|
||
|
|
**/
|
||
|
|
EFI_STATUS
|
||
|
|
EFIAPI
|
||
|
|
SmmMpCheckForProcedure (
|
||
|
|
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
|
||
|
|
|
||
|
|
**/
|
||
|
|
EFI_STATUS
|
||
|
|
EFIAPI
|
||
|
|
SmmMpWaitForProcedure (
|
||
|
|
IN CONST EFI_MM_MP_PROTOCOL *This,
|
||
|
|
IN MM_COMPLETION Token
|
||
|
|
);
|
||
|
|
|
||
|
|
#endif
|