7. MM Child Dispatch Protocols¶
7.1. Introduction¶
The services described in this chapter describe a series of protocols that abstract installation of handlers for a chipset-specific MM design. These services are all scoped to be usable only from within MMRAM.
The following protocols are defined in this chapter:
EFI_MM_SW_DISPATCH_PROTOCOL
EFI_MM_SX_DISPATCH_PROTOCOL
EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL
EFI_MM_USB_DISPATCH_PROTOCOL
EFI_MM_GPI_DISPATCH_PROTOCOL
EFI_MM_STANDBY_BUTTON_DISPATCH_PROTOCOL
EFI_MM_POWER_BUTTON_DISPATCH_PROTOCOL
EFI_MM_IO_TRAP_DISPATCH_PROTOCOL
MM Drivers which create instances of these protocols should install an instance of the EFI_DEVICE_PATH_PROTOCOL on the same handle. This allows other MM Drivers to distinguish between multiple instances of the same child dispatch protocol
7.2. MM Software Dispatch Protocol¶
7.2.1. EFI_MM_SW_DISPATCH_PROTOCOL¶
Summary
Provides the parent dispatch service for a given MMI source generator.
GUID
#define EFI_MM_SW_DISPATCH_PROTOCOL_GUID \
{ 0x18a3c6dc, 0x5eea, 0x48c8, \
0xa1, 0xc1, 0xb5, 0x33, 0x89, 0xf9, 0x89, 0x99}
Protocol Interface Structure
typedef struct _EFI_MM_SW_DISPATCH_PROTOCOL {
EFI_MM_SW_REGISTER Register;
EFI_MM_SW_UNREGISTER UnRegister;
UINTN MaximumSwiValue;
} EFI_MM_SW_DISPATCH_PROTOCOL;
Parameters
- Register
Installs a child service to be dispatched by this protocol. See the Register() function description.
- UnRegister
Removes a child service dispatched by this protocol. See the UnRegister() function description.
- MaximumSwiValue
A read-only field that describes the maximum value that can be used in the EFI_MM_SW_DISPATCH_PROTOCOL.Register() service.
Description
The EFI_MM_SW_DISPATCH_PROTOCOL provides the ability to install child handlers for the given software. These handlers will respond to software-generated MMI,s, and the maximum software-generated MMI value in the EFI_MM_SW_REGISTER_CONTEXT is denoted by MaximumSwiValue.
7.2.2. EFI_MM_SW_DISPATCH_PROTOCOL.Register()¶
Summary
Provides the parent dispatch service for a given MMI source generator.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_SW_REGISTER) (
IN CONST EFI_MM_SW_DISPATCH_PROTOCOL *This,
IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction,
IN EFI_MM_SW_REGISTER_CONTEXT *RegisterContext,
OUT EFI_HANDLE *DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_SW_DISPATCH_PROTOCOL instance.
- DispatchFunction
Function to register for handler when the specified software MMI is generated. Type EFI_MM_HANDLER_ENTRY_POINT is defined in “Related Definitions” in MmiHandlerRegister() .
- RegisterContext
Pointer to the dispatch function’s context. The caller fills in this context before calling the Register() function to indicate to the Register() function the software MMI input value for which the dispatch function should be invoked. Type EFI_MM_SW_REGISTER_CONTEXT is defined in “Related Definitions” below.
- DispatchHandle
Handle generated by the dispatcher to track the function instance. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service registers a function ( DispatchFunction ) which will be called when the software MMI source specified by RegisterContext->SwMmiCpuIndex is detected. On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister().
If SwMmiInputValue is set to (UINTN) -1 then a unique
value will be assigned and returned in the structure. If no
unique value can be assigned then EFI_OUT_OF_RESOURCES
will be returned.
The DispatchFunction will be called with Context set to the same value as was passed into this function in RegisterContext and with CommBuffer (and CommBufferSize ) pointing to an instance of EFI_MM_SW_CONTEXT indicating the index of the CPU which generated the software MMI.
//******************************************************
// EFI_MM_SW_CONTEXT
//******************************************************
typedef struct {
UINTN SwMmiCpuIndex;
UINT8 CommandPort;
UINT8 DataPort;
} EFI_MM_SW_CONTEXT;
- SwMmiCpuIndex
The 0-based index of the CPU which generated the software MMI.
- CommandPort
This value corresponds directly to the CommandPort parameter used in the call to Trigger() , see MM Control Protocol .
- DataPort
This value corresponds directly to the DataPort parameter used in the call to Trigger() , see MM Control Protocol.
//******************************************************
// EFI_MM_SW_REGISTER_CONTEXT
//******************************************************
typedef struct {
UINTN SwMmiInputValue;
} EFI_MM_SW_REGISTER_CONTEXT;
- SwMmiInputValue
A number that is used during the registration process to tell the dispatcher which software input value to use to invoke the given handler.
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully registered and the MMI source has been enabled |
EFI_DEVICE_ERROR |
The driver was unable to enable the MMI source |
EFI_INVALID_PARAMETER |
RegisterContext is invalid The SW MMI input value is not within a valid range or is already in use |
EFI_OUT_OF_RESOURCES |
There is not enough memory system or SM to manage this child |
EFI_OUT_OF_RESOURCES |
A unique software MMI value could not be assigned for this dispatch |
7.2.3. EFI_MM_SW_DISPATCH_PROTOCOL.UnRegister()¶
Summary
Unregisters a software service.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_SW_UNREGISTER) (
IN CONST EFI_MM_SW_DISPATCH_PROTOCOL *This,
IN EFI_HANDLE DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_SW_DISPATCH_PROTOCOL instance.
- DispatchHandle
Handle of the service to remove. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service removes the handler associated with DispatchHandle so that it will no longer be called in response to a software MMI.
Status Codes Returned
EFI_SUCCESS |
The service has been successfully removed. |
EFI_INVALID_PARAMETER |
The DispatchHandle was not valid. |
7.3. MM Sx Dispatch Protocol¶
7.3.1. EFI_MM_SX_DISPATCH_PROTOCOL¶
Summary
Provides the parent dispatch service for a given Sx-state source generator.
GUID
#define EFI_MM_SX_DISPATCH_PROTOCOL_GUID \
{ 0x456d2859, 0xa84b, 0x4e47, \
0xa2, 0xee, 0x32, 0x76, 0xd8, 0x86, 0x99, 0x7d }
Protocol Interface Structure
typedef struct _EFI_MM_SX_DISPATCH_PROTOCOL {
EFI_MM_SX_REGISTER Register;
EFI_MM_SX_UNREGISTER UnRegister;
} EFI_MM_SX_DISPATCH_PROTOCOL;
Parameters
- Register
Installs a child service to be dispatched by this protocol. See the Register() function description.
- UnRegister
Removes a child service dispatched by this protocol. See the UnRegister() function description.
Description
The EFI_MM_SX_DISPATCH_PROTOCOL provides the ability to install child handlers to respond to sleep state related events.
7.3.2. EFI_MM_SX_DISPATCH_PROTOCOL.Register()¶
Summary
Provides the parent dispatch service for a given Sx source generator.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_SX_REGISTER) (
IN CONST EFI_MM_SX_DISPATCH_PROTOCOL *This,
IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction,
IN CONST EFI_MM_SX_REGISTER_CONTEXT* *RegisterContext,
OUT EFI_HANDLE *DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_SX_DISPATCH_PROTOCOL instance.
- DispatchFunction
Function to register for handler when the specified sleep state event occurs. Type EFI_MM_HANDLER_ENTRY_POINT is defined in “Related Definitions” in MmiHandlerRegister() in the MMST.
- RegisterContext
Pointer to the dispatch function’s context. The caller in fills this context before calling the Register() function to indicate to the Register() function on which Sx state type and phase the caller wishes to be called back.
- DispatchHandle
Handle of the dispatch function, for when interfacing with the parent Sx state MM Driver. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service registers a function ( DispatchFunction ) which will be called when the sleep state event specified by RegisterContext is detected. On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister() .
The DispatchFunction will be called with Context set to the same value as was passed into this function in RegisterContext and with CommBuffer and CommBufferSize set to NULL and 0 respectively
The DispatchFunction will be called with Context set to the same value as was passed into this function in RegisterContext and with CommBuffer and CommBufferSize set to NULL and 0 respectively.
//****************************************************
// EFI_MM_SX_REGISTER_CONTEXT
//****************************************************
typedef struct {
EFI_SLEEP_TYPE Type;
EFI_SLEEP_PHASE Phase;
} EFI_MM_SX_REGISTER_CONTEXT;
//****************************************************
// EFI_SLEEP_TYPE
//****************************************************
typedef enum {
SxS0,
SxS1,
SxS2,
SxS3,
SxS4,
SxS5,
EfiMaximumSleepType
} EFI_SLEEP_TYPE;
//****************************************************
// EFI_SLEEP_PHASE
//****************************************************
typedef enum {
SxEntry,
SxExit,
EfiMaximumPhase
} EFI_SLEEP_PHASE;
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully registered and the MMI source has been enabled |
EFI_UNSUPPORTED |
The Sx driver or hardware does not support that Sx Type Phase |
EFI_DEVICE_ERROR |
The Sx driver was unable to enable the MMI source |
EFI_INVALID_PARAMETER |
RegisterContext is invalid The ICHN input value is not within a valid range |
EFI_OUT_OF_RESOURCES |
There is not enough memory system or SM to manage this child |
7.3.3. EFI_MM_SX_DISPATCH_PROTOCOL.UnRegister()¶
Summary
Unregisters an Sx-state service.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_SX_UNREGISTER) (
IN CONST EFI_MM_SX_DISPATCH_PROTOCOL *This,
IN EFI_HANDLE DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_SX_DISPATCH_PROTOCOL instance.
- DispatchHandle
Handle of the service to remove. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service removes the handler associated with DispatchHandle so that it will no longer be called in response to sleep event.
Status Codes Returned
EFI_SUCCESS |
The service has been successfully removed. |
EFI_INVALID_PARAMETER |
The DispatchHandle was not valid. |
7.4. MM Periodic Timer Dispatch Protocol¶
7.4.1. EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL¶
Summary
Provides the parent dispatch service for the periodical timer MMI source generator.
GUID
#define EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL_GUID \
{ 0x4cec368e, 0x8e8e, 0x4d71, \
0x8b, 0xe1, 0x95, 0x8c, 0x45, 0xfc, 0x8a, 0x53}
Protocol Interface Structure
typedef struct _EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL {
EFI_MM_PERIODIC_TIMER_REGISTER Register;
EFI_MM_PERIODIC_TIMER_UNREGISTER UnRegister;
EFI_MM_PERIODIC_TIMER_INTERVAL GetNextShorterInterval;
} EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL;
Parameters
- Register
Installs a child service to be dispatched by this protocol. See the Register() function description.
- UnRegister
Removes a child service dispatched by this protocol. See the UnRegister() function description.
- GetNextShorterInterval
Returns the next MMI tick period that is supported by the chipset. See the GetNextShorterInterval() function description.
Description
The EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL provides the ability to install child handlers for the given event types.
7.4.2. EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL.Register()¶
Summary
Provides the parent dispatch service for a given MMI source generator.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_PERIODIC_TIMER_REGISTER) (
IN CONST EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL *This,
IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction,
IN CONST EFI_MM_PERIODIC_TIMER_REGISTER_CONTEXT *RegisterContext,
OUT EFI_HANDLE *DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance.
- DispatchFunction
Function to register for handler when at least the specified amount of time has elapsed. Type EFI_MM_HANDLER_ENTRY_POINT is defined in “Related Definitions” in MmiHandlerRegister() in theMMST.
- RegisterContext
Pointer to the dispatch function’s context. The caller fills this context in before calling the Register() function to indicate to the Register() function the period at which the dispatch function should be invoked. Type EFI_MM_PERIODIC_TIMER_REGISTER_CONTEXT is defined in “Related Definitions” below.
- DispatchHandle
Handle generated by the dispatcher to track the function instance. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service registers a function ( DispatchFunction ) which will be called when at least the amount of time specified by RegisterContext has elapsed. On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister() .
The DispatchFunction will be called with Context set to the same value as was passed into this function in RegisterContext and with CommBuffer pointing to an instance of EFI_MM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size.
//*******************************************************
// EFI_MM_PERIODIC_TIMER_REGISTER_CONTEXT
//*******************************************************
typedef struct {
UINT64 Period;
UINT64 MmiTickInterval;
} EFI_MM_PERIODIC_TIMER_REGISTER_CONTEXT;
- Period
The minimum period of time in 100 nanosecond units that the child gets called. The child will be called back after a time greater than the time Period .
- MmiTickInterval
The period of time interval between MMIs. Children of this interface should use this field when registering for periodic timer intervals when a finer granularity periodic MMI is desired.
Example: A chipset supports periodic MMIs on every 64 ms or 2 seconds. A child wishes to schedule a periodic MMI to fire on a period of 3 seconds. There are several ways to approach the problem:
The child may accept a 4 second periodic rate, in which case it registers with the following:
Period = 40000
MmiTickInterval = 20000
The resulting MMI will occur every 2 seconds with the child called back on every second MMI.
Note
The same result would occur if the child set MmiTickInterval = 0 .
The child may choose the finer granularity MMI (64 ms):
Period = 30000
MmiTickInterval = 640
The resulting MMI will occur every 64 ms with the child called back on every 47th MMI.
Note
The child driver should be aware that this will result in more MMIs occurring during system runtime, which can negatively impact system performance.
typedef struct _EFI_MM_PERIODIC_TIMER_CONTEXT {
UINT64 ElapsedTime;
} EFI_MM_PERIODIC_TIMER_CONTEXT;
- ElapsedTime
The actual time in 100 nanosecond units elapsed since last called. A value of 0 indicates an unknown amount of time.
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully registered and the MMI source has been enabled |
EFI_DEVICE_ERROR |
The driver was unable to enable the MMI source |
EFI_INVALID_PARAMETER |
RegisterContext is invalid The ICHN input value is not within a valid range |
EFI_OUT_OF_RESOURCES |
There is not enough memory system or SM to manage this child |
7.4.3. EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL.UnRegister()¶
Summary
Unregisters a periodic timer service.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_PERIODIC_TIMER_UNREGISTER) (
IN CONST EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL *This,
IN EFI_HANDLE DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance.
- DispatchHandle
Handle of the service to remove. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service removes the handler associated with DispatchHandle so that it will no longer be called when the time has elapsed.
Status Codes Returned
EFI_SUCCESS |
The service has been successfully removed. |
EFI_INVALID_PARAMETER |
The DispatchHandle was not valid. |
7.4.4. EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL.GetNextShorterInterval()¶
Summary
Returns the next MMI tick period that is supported by the chipset.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_PERIODIC_TIMER_INTERVAL) (
IN CONST EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL *This,
IN OUT UINT64 **MmiTickInterval
);
Parameters
- This
Pointer to the EFI_MM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance.
- MmiTickInterval
Pointer to pointer of the next shorter MMI interval period that is supported by the child. This parameter works as a get-first, get-next field. The first time that this function is called, *MmiTickInterval should be set to NULL to get the longest MMI interval. The returned *MmiTickInterval should be passed in on subsequent calls to get the next shorter interval period until *MmiTickInterval = NULL .
Description
This service returns the next MMI tick period that is supported by the device. The order returned is from longest to shortest interval period.
Status Codes Returned
EFI_SUCCESS |
The service returned successfully. |
7.5. MM USB Dispatch Protocol¶
7.5.1. EFI_MM_USB_DISPATCH_PROTOCOL¶
Summary
Provides the parent dispatch service for the USB MMI source generator.
GUID
#define EFI_MM_USB_DISPATCH_PROTOCOL_GUID \
{ 0xee9b8d90, 0xc5a6, 0x40a2, \
0xbd, 0xe2, 0x52, 0x55, 0x8d, 0x33, 0xcc, 0xa1 }
Protocol Interface Structure
typedef struct _EFI_MM_USB_DISPATCH_PROTOCOL {
EFI_MM_USB_REGISTER Register;
EFI_MM_USB_UNREGISTER UnRegister;
} EFI_MM_USB_DISPATCH_PROTOCOL;
Parameters
- Register
Installs a child service to be dispatched by this protocol. See the Register() function description.
- UnRegister
Removes a child service dispatched by this protocol. See the UnRegister() function description.
Description
The EFI_MM_USB_DISPATCH_PROTOCOL provides the ability to install child handlers for the given event types.
7.5.2. EFI_MM_USB_DISPATCH_PROTOCOL.Register()¶
Summary
Provides the parent dispatch service for the USB MMI source generator.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_USB_REGISTER) (
IN CONST EFI_MM_USB_DISPATCH_PROTOCOL *This,
IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction,
IN CONST EFI_MM_USB_REGISTER_CONTEXT *RegisterContext,
OUT EFI_HANDLE *DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_USB_DISPATCH_PROTOCOL instance.
- DispatchFunction
Function to register for handler when a USB-related MMI occurs. Type EFI_MM_HANDLER_ENTRY_POINT is defined in “Related Definitions” in MmiHandlerRegister() in the MMST.
- RegisterContext
Pointer to the dispatch function’s context. The caller fills this context in before calling the Register() function to indicate to the Register() function the USB MMI source for which the dispatch function should be invoked. Type EFI_MM_USB_REGISTER_CONTEXT is defined in “Related Definitions” below.
- DispatchHandle
Handle generated by the dispatcher to track the function instance. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFISpecification.
Description
This service registers a function ( DispatchFunction ) which will be called when the USB-related MMI specified by RegisterContext has occurred. On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister() .
The DispatchFunction will be called with Context set to the same value as was passed into this function in RegisterContext and with CommBuffer containing NULL and CommBufferSize containing zero.
//********************************************************
// EFI_MM_USB_REGISTER_CONTEXT
//********************************************************
typedef struct {
EFI_USB_MMI_TYPE Type;
EFI_DEVICE_PATH_PROTOCOL *Device;
} EFI_MM_USB_REGISTER_CONTEXT;
- Type
Describes whether this child handler will be invoked in response to a USB legacy emulation event, such as port-trap on the PS/2* keyboard control registers, or to a USB wake event, such as resumption from a sleep state. Type EFI_USB_MMI_TYPE is defined below.
- Device
The device path is part of the context structure and describes the location of the particular USB host controller in the system for which this register event will occur. This location is important because of the possible integration of several USB host controllers in a system. Type EFI_DEVICE_PATH is defined in the UEFI Specification.
//********************************************************
// EFI_USB_MMI_TYPE
//********************************************************
typedef enum {
UsbLegacy,
UsbWake
} EFI_USB_MMI_TYPE;
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully registered and the MMI source has been enabled |
EFI_DEVICE_ERROR |
The driver was unable to enable the MMI source |
EFI_INVALID_PARAMETER |
RegisterContext is invalid The ICHN input value is not within valid range |
EFI_OUT_OF_RESOURCES |
There is not enough memory system or MM to manage this child |
7.5.3. EFI_MM_USB_DISPATCH_PROTOCOL.UnRegister()¶
Summary
Unregisters a USB service.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_USB_UNREGISTER) (
IN CONST EFI_MM_USB_DISPATCH_PROTOCOL *This,
IN EFI_HANDLE DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_USB_DISPATCH_PROTOCOL instance.
- DispatchHandle
Handle of the service to remove. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service removes the handler associated with DispatchHandle so that it will no longer be called when the USB event occurs.
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully unregistered and the MMI source has been disabled if there are no other registered child dispatch functions for this MMI source |
EFI_INVALID_PARAMETER |
The DispatchHandle was not valid |
7.6. MM General Purpose Input (GPI) Dispatch Protocol¶
7.6.1. EFI_MM_GPI_DISPATCH_PROTOCOL¶
Summary
Provides the parent dispatch service for the General Purpose Input (GPI) MMI source generator.
GUID
#define EFI_MM_GPI_DISPATCH_PROTOCOL_GUID \
{ 0x25566b03, 0xb577, 0x4cbf, \
0x95, 0x8c, 0xed, 0x66, 0x3e, 0xa2, 0x43, 0x80 }
Protocol Interface Structure
typedef struct _EFI_MM_GPI_DISPATCH_PROTOCOL {
EFI_MM_GPI_REGISTER Register;
EFI_MM_GPI_UNREGISTER UnRegister;
UINTN NumSupportedGpis;
} EFI_MM_GPI_DISPATCH_PROTOCOL;
Parameters
- Register
Installs a child service to be dispatched by this protocol. See the Register() function description.
- UnRegister
Removes a child service dispatched by this protocol. See the UnRegister() function description.
- NumSupportedGpis
Denotes the maximum value of inputs that can have handlers attached.
Description
The EFI_MM_GPI_DISPATCH_PROTOCOL provides the ability to install child handlers for the given event types. Several inputs can be enabled. This purpose of this interface is to generate an MMI in response to any of these inputs having a true value provided.
7.6.2. EFI_MM_GPI_DISPATCH_PROTOCOL.Register()¶
Summary
Registers a child MMI source dispatch function with a parent MM driver.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_GPI_REGISTER) (
IN CONST EFI_MM_GPI_DISPATCH_PROTOCOL *This,
IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction,
IN CONST EFI_MM_GPI_REGISTER_CONTEXT *RegisterContext,
OUT EFI_HANDLE *DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_GPI_DISPATCH_PROTOCOL instance.
- DispatchFunction
Function to register for handler when the specified GPI causes an MMI. Type EFI_MM_HANDLER_ENTRY_POINT is defined in “Related Definitions” in MmiHandlerRegister() in the MMST.
- RegisterContext
Pointer to the dispatch function’s context. The caller fills in this context before calling the Register() function to indicate to the Register() function the GPI MMI source for which the dispatch function should be invoked. Type EFI_MM_GPI_REGISTER_CONTEXT is defined in “Related Definitions” below.
- DispatchHandle
Handle generated by the dispatcher to track the function instance. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service registers a function ( DispatchFunction ) which will be called when an MMI is generated because of one or more of the GPIs specified by RegisterContext . On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister() .
The DispatchFunction will be called with Context set to the same value as was passed into this function in RegisterContext and with CommBuffer pointing to another instance of EFI_MM_GPI_REGISTER_CONTEXT describing the GPIs which actually caused the MMI and CommBufferSize pointing to the size of the structure.
//**********************************************
// EFI_MM_GPI_REGISTER_CONTEXT
//**********************************************
typedef struct {
UINT64 GpiNum;
} EFI_MM_GPI_REGISTER_CONTEXT;
- GpiNum
A number from one of 2^64 possible GPIs that can generate an MMI. A 0 corresponds to logical GPI[0]; 1 corresponds to logical GPI[1]; and GpiNum of N corresponds to GPI[N], where N can span from 0 to 2^64-1.
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully registered and the MMI source has been enabled |
EFI_DEVICE_ERROR |
The driver was unable to enable the MMI source |
EFI_INVALID_PARAMETER |
RegisterContext is invalid The GPI input value is not within valid range |
EFI_OUT_OF_RESOURCES |
There is not enough memory system or SM to manage this child |
7.6.3. EFI_MM_GPI_DISPATCH_PROTOCOL.UnRegister()¶
Summary
Unregisters a General Purpose Input (GPI) service.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_MM_GPI_UNREGISTER) (
IN CONST EFI_MM_GPI_DISPATCH_PROTOCOL *This,
IN EFI_HANDLE DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_GPI_DISPATCH_PROTOCOL instance.
- DispatchHandle
Handle of the service to remove. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service removes the handler associated with DispatchHandle so that it will no longer be called when the GPI triggers an MMI.
Status Codes Returned
EFI_SUCCESS |
The service has been successfully removed. |
EFI_INVALID_PARAMETER |
The DispatchHandle was not valid. |
7.9. MM IO Trap Dispatch Protocol¶
7.9.1. EFI_MM_IO_TRAP_DISPATCH_PROTOCOL¶
Summary
This protocol provides a parent dispatch service for IO trap MMI sources.
GUID
#define EFI_MM_IO_TRAP_DISPATCH_PROTOCOL_GUID \
{ 0x58dc368d, 0x7bfa, 0x4e77, \
0xab, 0xbc, 0xe, 0x29, 0x41, 0x8d, 0xf9, 0x30 }
Protocol Interface Structure
struct _EFI_MM_IO_TRAP_DISPATCH_PROTOCOL {
EFI_MM_IO_TRAP_DISPATCH_REGISTER Register;
EFI_MM_IO_TRAP_DISPATCH_UNREGISTER UnRegister;
} EFI_MM_IO_TRAP_DISPATCH_PROTOCOL;
Parameters
- Register
Installs a child service to be dispatched when the requested IO trap MMI occurs. See the Register() function description.
- UnRegister
Removes a previously registered child service. See the Register() and UnRegister() function descriptions.
Description
This protocol provides the ability to install child handlers for IO trap MMI. These handlers will be invoked to respond to specific IO trap MMI. IO trap MMI would typically be generated on reads or writes to specific processor IO space addresses or ranges. This protocol will typically abstract a limited hardware resource, so callers should handle errors gracefully.
7.9.2. EFI_MM_IO_TRAP_DISPATCH_PROTOCOL.Register ()¶
Summary
Register an IO trap MMI child handler for a specified MMI.
Prototype
EFI_STATUS
(EFIAPI *EFI_MM_IO_TRAP_DISPATCH_REGISTER) (
IN CONST EFI_MM_IO_TRAP_DISPATCH_PROTOCOL *This,
IN EFI_MM_HANDLER_ENTRY_POINT DispatchFunction,
IN OUT EFI_MM_IO_TRAP_REGISTER_CONTEXT *RegisterContext,
OUT EFI_HANDLE *DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_IO_TRAP_DISPATCH_PROTOCOL instance.
- DispatchFunction
Function to register for handler when I/O trap location is accessed. Type EFI_MM_HANDLER_ENTRY_POINT is defined in “Related Definitions” in MmiHandlerRegister() in the MMST.
- RegisterContext
Pointer to the dispatch function’s context. The caller fills this context in before calling the register function to indicate to the register function the IO trap MMI source for which the dispatch function should be sinvoked.
- DispatchHandle
Handle of the dispatch function, for when interfacing with the parent MM Driver. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI Specification.
Description
This service registers a function ( DispatchFunction ) which will be called when an MMI is generated because of an access to an I/O port specified by RegisterContext . On return, DispatchHandle contains a unique handle which may be used later to unregister the function using UnRegister() . If the base of the I/O range specified is zero, then an I/O range with the specified length and characteristics will be allocated and the Address field in RegisterContext updated. If no range could be allocated, then EFI_OUT_OF_RESOURCES will be returned.
The service will not perform GCD allocation if the base address is non-zero or EFI_MM_READY_TO_LOCK has been installed. In this case, the caller is responsible for the existence and allocation of the specific IO range.
An error may be returned if some or all of the requested resources conflict with an existing IO trap child handler.
It is not required that implementations will allow multiple children for a single IO trap MMI source. Some implementations may support multiple children.
The DispatchFunction will be called with Context updated to contain information concerning the I/O action that actually happened and is passed in RegisterContext, with CommBuffer pointing to the data actually written and CommBufferSize pointing to the size of the data in CommBuffer .
//
// IO Trap valid types
//
typedef enum {
WriteTrap,
ReadTrap,
ReadWriteTrap,
IoTrapTypeMaximum
} EFI_MM_IO_TRAP_DISPATCH_TYPE;
//
// IO Trap context structure containing information about the
// IO trap event that should invoke the handler
//
typedef struct {
UINT16 Address;
UINT16 Length;
EFI_MM_IO_TRAP_DISPATCH_TYPE Type;
} EFI_MM_IO_TRAP_REGISTER_CONTEXT;
//
// IO Trap context structure containing information about the IO trap that occurred
//
typedef struct {
UINT32 WriteData;
} EFI_MM_IO_TRAP_CONTEXT;
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully registered |
EFI_DEVICE_ERROR |
The driver was unable to complete due to hardware error |
EFI_OUT_OF_RESOURCES |
Insufficient resources are available to fulfill the IO trap range request |
EFI_INVALID_PARAMETER |
RegisterContext is invalid The input value is not within a valid range |
7.9.3. EFI_MM_IO_TRAP_DISPATCH_PROTOCOL.UnRegister ()¶
Summary
Unregister a child MMI source dispatch function with a parent MM Driver.
Prototype
EFI_STATUS
(EFIAPI *EFI_MM_IO_TRAP_DISPATCH_UNREGISTER) (
IN CONST EFI_MM_IO_TRAP_DISPATCH_PROTOCOL *This,
IN EFI_HANDLE DispatchHandle
);
Parameters
- This
Pointer to the EFI_MM_IO_TRAP_DISPATCH_PROTOCOL instance.
- DispatchHandle
Handle of the child service to remove. Type EFI_HANDLE is defined in InstallProtocolInterface() in the EFI 1.10 Specification.
Description
This service removes a previously installed child dispatch handler. This does not guarantee that the system resources will be freed from the GCD.
None
Status Codes Returned
EFI_SUCCESS |
The dispatch function has been successfully unregistered |
EFI_INVALID_PARAMETER |
The DispatchHandle was not valid |
7.10. HOBs¶
7.10.1. EFI_PEI_MM_CORE_GUID¶
Summary
A GUIDed HOB that indicates whether the MM Core has been loaded.
GUID
#define EFI_PEI_MM_CORE_GUID \
{0x8d1b3618, 0x111b, 0x4cba, \
{0xb7, 0x9a, 0x55, 0xb3, 0x2f, 0x60, 0xf0, 0x29} }
HOB Structure
typedef struct _EFI_PEI_MM_CORE_HOB {
EFI_HOB_GENERIC_HEADER Header;
EFI_GUID Name;
UINT32 Flags;
} EFI_PEI_MM_CORE_HOB;
Members
- Header
The HOB generic header with Header.HobType set to EFI_HOB_TYPE_GUID_EXTENSION.
- Name
The GUID that specifies this particular HOB structure. Set to EFI_PEI_MM_CORE_GUID .
- flags
Bitmask that specifies which MM features have been initialized in SEC. All other bits must be set to 0.
# define EFI_PEI_MM_CORE_LOADED 0x00000001
# MM Core Loaded
Description
This HOB is consumed by the MM IPL driver to understand which portions of MM initialization have been completed. For example the DXE MM IPL driver can determine whether MMRAM has been initialized and the MM Core loaded.