5. UEFI Protocols

5.1. Introduction

The services described in this Mode chapter describe a series of protocols that locate the MMST, manipulate the Management RAM (MMRAM) apertures, and generate MMIs. Some of these protocols provide only boot services while others have both boot services and runtime services.

The following protocols are defined in this chapter:

EFI_MM_BASE_PROTOCOL

EFI_MM_ACCESS_PROTOCOL

EFI_MM_CONTROL_PROTOCOL

EFI_MM_CONFIGURATION_PROTOCOL

EFI_MM_COMMUNICATION_PROTOCOL

5.2. EFI MM Base Protocol

5.2.1. EFI_MM_BASE_PROTOCOL

Dummary

This protocol is used to locate the MMST during MM Driver Initialization.

GUID

#define EFI_MM_BASE_PROTOCOL_GUID \
  { 0xf4ccbfb7, 0xf6e0, 0x47fd, 0x9d, 0xd4, 0x10, 0xa8, 0xf1, 0x50, 0xc1, 0x91 }

Protocol Interface Structure

typedef struct _EFI_MM_BASE_PROTOCOL {
  EFI_MM_INSIDE_OUT                       InMm;
  EFI_MM_GET_MMST_LOCATION                GetMmstLocation;
} EFI_MM_BASE_PROTOCOL;

Parameters

InMm: Detects whether the caller is inside or outside of MMRAM. See the InMm() function description.
GetMmstLocation: Retrieves the location of the Management Mode System Table (MMST) . See the GetMmstLocation() function description.

Description

The EFI_MM_BASE_PROTOCOL is provided by the MM IPL driver. It is a required protocol. It will be utilized by all MM Drivers to locate the MM infrastructure services and determine whether the driver is being invoked as a DXE or MM Driver.

5.2.2. EFI_MM_BASE_PROTOCOL.InMm()

Summary

Service to indicate whether the driver is currently executing in the MM Driver Initialization phase.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_INSIDE_OUT) (
  IN CONST EFI_MM_BASE_PROTOCOL   *This,
  OUT BOOLEAN                     *InMmram*
)

Parameters

This: The EFI_MM_BASE_PROTOCOL instance.
InMmram: Pointer to a Boolean which, on return, indicates that the driver is currently executing inside of MMRAM (TRUE) or outside of MMRAM (FALSE).

Description

This service returns whether the caller is being executed in the MM Driver Initialization phase. For MM Drivers, this will return TRUE in InMmram while inside the driver’s entry point and otherwise FALSE . For combination MM/DXE drivers, this will return FALSE in the DXE launch. For the MM launch, it behaves as an MM Driver.

Status Codes Returned

EFI_SUCCESS	The call returned successfully.
EFI_INVALID_PARAMETER	InMmram was NULL .

5.2.3. EFI_MM_BASE_PROTOCOL.GetMmstLocation()

Summary

Returns the location of the Management Mode Service Table (MMST) .

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_MM_GET_MMST_LOCATION) (
  IN CONST *EFI_MM_BASE_PROTOCOL* *\*This* ,
  IN OUT *EFI_MM_SYSTEM_TABLE* *\**Mmst*
)

Parameters

This: The EFI_MM_BASE_PROTOCOL instance.
Mmst: On return, points to a pointer to the Management Mode Service Table (MMST).

Description

This function returns the location of the Management Mode Service Table (MMST) . The use of the API is such that a driver can discover the location of the MMST in its entry point and then cache it in some driver global variable so that the MMST can be invoked in subsequent handlers.

Status Codes Returned

EFI_SUCCESS	The memory was returned to the system.
EFI_INVALID_PARAMETER	Mmst was invalid.
EFI_UNSUPPORTED	Not in MM.

5.3. MM Access Protocol

5.3.1. EFI_MM_ACCESS_PROTOCOL

Summary

This protocol is used to control the visibility of the MMRAM on the platform.

GUID

#define EFI_MM_ACCESS_PROTOCOL_GUID \
  { 0xc2702b74, 0x800c, 0x4131, 0x87, 0x46, 0x8f, 0xb5, 0xb8, 0x9c, 0xe4, 0xac }

Protocol Interface Structure

typedef struct _EFI_MM_ACCESS_PROTOCOL {
  EFI_MM_OPEN                             Open;
  EFI_MM_CLOSE                            Close;
  EFI_MM_LOCK                             Lock;
  EFI_MM_CAPABILITIES                     GetCapabilities;
  BOOLEAN                                 LockState ;
  BOOLEAN                                 OpenState ;
} EFI_MM_ACCESS_PROTOCOL;

Parameters

Open: Opens the MMRAM. See the Open() function description.
Close: Closes the MMRAM. See the Close() function description.
Lock: Locks the MMRAM. See the Lock() function description.
GetCapabilities: Gets information about all MMRAM regions. See the GetCapabilities() function description.
LockState: Indicates the current state of the MMRAM. Set to TRUE if MMRAM is locked.
OpenState: Indicates the current state of the MMRAM. Set to TRUE if MMRAM is open.

Description

The EFI_MM_ACCESS_PROTOCOL abstracts the location and characteristics of MMRAM. The platform should report all MMRAM via EFI_MM_ACCESS_PROTOCOL . The principal functionality found in the memory controller includes the following:

Exposing the MMRAM to all non-MM agents, or the “open” state

Hiding the MMRAM to all but the MM agents, or the “closed” state

Securing or “locking” the MMRAM, such that the settings cannot be changed by either boot service or runtime agents

5.3.2. EFI_MM_ACCESS_PROTOCOL.Open()

Summary

Opens the MMRAM area to be accessible by a boot-service driver.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_MM_OPEN) (
  IN *EFI_MM_ACCESS_PROTOCOL    *This
);

Parameters

This: The EFI_MM_ACCESS_PROTOCOL instance.

Description

This function “opens” MMRAM so that it is visible while not inside of MM. The function should return EFI_UNSUPPORTED if the hardware does not support hiding of MMRAM. The function should return EFI_DEVICE_ERROR if the MMRAM configuration is locked.

Status Codes Returned

EFI_SUCCESS	The operation was successful
EFI_UNSUPPORTED	The system does not support opening and closing of MMRAM
EFI_DEVICE_ERROR	MMRAM cannot be opened perhaps because it is locked

5.3.3. EFI_MM_ACCESS_PROTOCOL.Close()

Summary

Inhibits access to the MMRAM.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_CLOSE) (
  IN EFI_MM_ACCESS_PROTOCOL    *This
);

Parameters

This: The EFI_MM_ACCESS_PROTOCOL instance.

Description

This function “closes” MMRAM so that it is not visible while outside of MM. The function should return EFI_UNSUPPORTED if the hardware does not support hiding of MMRAM.

Status Codes Returned

EFI_SUCCESS	The operation was successful
EFI_UNSUPPORTED	The system does not support opening and closing of MMRAM
EFI_DEVICE_ERROR	MMRAM cannot be closed

5.3.4. EFI_MM_ACCESS_PROTOCOL.Lock()

Summary

Inhibits access to the MMRAM.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_LOCK) (
  IN EFI_MM_ACCESS_PROTOCOL    *This
);

Parameters

This: The EFI_MM_ACCESS_PROTOCOL instance.

Description

This function prohibits access to the MMRAM region. This function is usually implemented such that it is a write-once operation.

Status Codes Returned

EFI_SUCCESS	The device was successfully locked.
EFI_UNSUPPORTED	The system does not support locking of MMRAM.

5.3.5. EFI_MM_ACCESS_PROTOCOL.GetCapabilities()

Summary

Queries the memory controller for the regions that will support MMRAM.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_CAPABILITIES) (
  IN CONST EFI_MM_ACCESS_PROTOCOL   *This,
  IN OUT UINTN                      *MmramMapSize,
  IN OUT EFI_MMRAM_DESCRIPTOR       *MmramMap
);

Parameters

This: The EFI_MM_ACCESS_PROTOCOL instance.
MmramMapSize: A pointer to the size, in bytes, of the MmramMemoryMap buffer. On input, this value is the size of the buffer that is allocated by the caller. On output, it is the size of the buffer that was returned by the firmware if the buffer was large enough, or, if the buffer was too small, the size of the buffer that is needed to contain the map.
MmramMap: A pointer to the buffer in which firmware places the current memory map. The map is an array of EFI_MMRAM_DESCRIPTOR s. Type EFI_MMRAM_DESCRIPTOR is defined in “Related Definitions” below.

Description

This function describes the MMRAM regions. This data structure forms the contract between the MM Access and MM IPL drivers. There is an ambiguity when any MMRAM region is remapped. For example, on some chipsets, some MMRAM regions can be initialized at one physical address but is later accessed at another processor address. There is currently no way for the MM IPL driver to know that it must use two different addresses depending on what it is trying to do. As a result, initial configuration and loading can use the physical address PhysicalStart while MMRAM is open. However, once the region has been closed and needs to be accessed by agents in MM, the CpuStart address must be used.

This protocol publishes the available memory that the chipset can shroud for the use of installing code. These regions serve the dual purpose of describing which regions have been open, closed, or locked. In addition, these regions may include overlapping memory ranges, depending on the chipset implementation. The latter might include a chipset that supports T-SEG, where memory near the top of the physical DRAM can be allocated for MMRAM too. The key thing to note is that the regions that are described by the protocol are a subset of the capabilities of the hardware.

Related Definitions

//*******************************************************
//EFI_MMRAM_STATE
//*******************************************************
//
// Hardware state
//
#define EFI_MMRAM_OPEN                        0x00000001
#define EFI_MMRAM_CLOSED                      0x00000002
#define EFI_MMRAM_LOCKED                      0x00000004
//
// Capability
//
#define EFI_CACHEABLE                         0x00000008
//
// Logical usage
//
#define EFI_ALLOCATED                         0x00000010
//
// Directive prior to usage
//
#define EFI_NEEDS_TESTING                     0x00000020
#define EFI_NEEDS_ECC_INITIALIZATION          0x00000040

//*******************************************************
// EFI_MMRAM_DESCRIPTOR
//*******************************************************
typedef struct _EFI_MMRAM_DESCRIPTOR {
  EFI_PHYSICAL_ADDRESS                     PhysicalStart;
  EFI_PHYSICAL_ADDRESS                     CpuStart;
  UINT64                                   PhysicalSize;
  UINT64                                   RegionState;
} EFI_MMRAM_DESCRIPTOR;

Parameters

PhysicalStart: Designates the physical address of the MMRAM in memory. This view of memory is the same as seen by I/O-based agents, for example, but it may not be the address seen by the processors. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI Specification.
CpuStart: Designates the address of the MMRAM, as seen by software executing on the processors. This address may or may not match PhysicalStart.
PhysicalSize: Describes the number of bytes in the MMRAM region.
RegionState: Describes the accessibility attributes of the MMRAM. These attributes include the hardware state (e.g., Open/Closed/Locked), capability (e.g., cacheable), logical allocation (e.g., allocated), and pre-use initialization (e.g., needs testing/ECC initialization).

Status Codes Returned

EFI_SUCCESS	The chipset supported the given resource
EFI_BUFFER_TOO_SMALL	The MmramMap parameter was too small The current buffer size needed to hold the memory map is returned in MmramMapSize

5.4. MM Control Protocol

5.4.1. EFI_MM_CONTROL_PROTOCOL

Summary

This protocol is used initiate synchronous MMIs.

GUID

#define EFI_MM_CONTROL_PROTOCOL_GUID \
  { 0x843dc720, 0xab1e, 0x42cb, 0x93, 0x57, 0x8a, 0x0, 0x78, 0xf3, 0x56, 0x1b }

Protocol Interface Structure

typedef struct _EFI_MM_CONTROL_PROTOCOL {
  EFI_MM_ACTIVATE                            Trigger;
  EFI_MM_DEACTIVATE                          Clear;
  EFI_MM_PERIOD                              MinimumTriggerPeriod;
} EFI_MM_CONTROL_PROTOCOL;

Parameters

Trigger: Initiates the MMI. See the Trigger() function description.
Clear: Quiesces the MMI source. See the Clear() function description.
MinimumTriggerPeriod: Minimum interval at which the platform can set the period. A maximum is not specified. That is, the MM infrastructure code can emulate a maximum interval that is greater than the hardware capabilities by using software emulation in the MM infrastructure code. Type EFI_MM_PERIOD is defined in “Related Definitions” below.

Description

The EFI_MM_CONTROL_PROTOCOL is produced by a runtime driver. It provides an abstraction of the platform hardware that generates an MMI. There are often I/O ports that, when accessed, will generate the MMI. Also, the hardware optionally supports the periodic generation of these signals.

Related Definitions

//***********************************************\*
// EFI_MM_PERIOD
//***********************************************\*
typedef UINTN EFI_MM_PERIOD;

Note

The-period-is-in-increments-of-10-ns.

5.4.2. EFI_MM_CONTROL_PROTOCOL.Trigger()

Summary

Invokes MMI activation from either the preboot or runtime environment.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_MM_ACTIVATE) (
  IN CONST *EFI_MM_CONTROL_PROTOCOL* *\*This* ,
  IN OUT UINT8 *\*CommandPort* OPTIONAL,
  IN OUT UINT8 *\*DataPort* OPTIONAL,
  IN BOOLEAN *Periodic* OPTIONAL,
  IN UINTN *ActivationInterval* OPTIONAL
  );

Parameters

This: The EFI_MM_CONTROL_PROTOCOL instance.
CommandPort: The value written to the command port; this value corresponds to the SwMmiInputValue in the RegisterContext parameter for the Register() function in the EFI_MM_SW_DISPATCH_PROTOCOL and in the Context parameter in the call to the DispatchFunction , see MM Software Dispatch Protocol.
DataPort: The value written to the data port; this value corresponds to the DataPort member in the CommBuffer parameter in the call to the DispatchFunction , see MM Software Dispatch Protocol.
Periodic: Optional mechanism to engender a periodic stream.
ActivationInterval: Optional parameter to repeat at this period one time or, if the Periodic Boolean is set, periodically.

Description

This function generates an MMI.

Status Codes Returned

EFI_SUCCESS	The MMI has been engendered.
EFI_DEVICE_ERROR	The timing is unsupported.
EFI_INVALID_PARAMETER	The activation period is unsupported.
EFI_INVALID_PARAMETER	The last periodic activation has not been cleared.
EFI_NOT_STARTED	The MM base service has not been initialized.

5.4.3. EFI_MM_CONTROL_PROTOCOL.Clear()

Summary

Clears any system state that was created in response to the Trigger() call.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_DEACTIVATE) (
  IN CONST *EFI_MM_CONTROL_PROTOCOL   *This,
  IN BOOLEAN                          Periodic OPTIONAL
);

Parameters

This: The EFI_MM_CONTROL_PROTOCOL instance.
Periodic: Optional parameter to repeat at this period one time or, if the Periodic Boolean is set, periodically.

Description

This function acknowledges and causes the deassertion of the MMI activation source.that was initiated by a preceding Trigger invocation.

The results of this function update the software state of the communication infrastructure in the runtime code, but it is ignorable from the perspective of the hardware state, though. This distinction stems from the fact that many implementations clear the hardware acknowledge in the MM-resident infrastructure itself and may also have other actions using that same activation hardware generated by MM Drivers. This clear-in MM distinction also avoids having the possible pathology of an asynchronous MMI being received in the time window between the RSM instruction (or other means of exiting MM) that followed the flows engendered by the Trigger and the subsequent non-MM resident runtime driver code invocation of the Clear .

Status Codes Returned

EFI_SUCCESS	The MMI has been engendered
EFI_DEVICE_ERROR	The source could not be cleared
EFI_INVALID_PARAMETER	The service did not support the Periodic input argument

5.5. MM Configuration Protocol

5.5.1. EFI_MM_CONFIGURATION_PROTOCOL

Summary

Reports the portions of MMRAM regions which cannot be used for the MMRAM heap.

GUID

#define EFI_MM_CONFIGURATION_PROTOCOL_GUID \
  { 0x26eeb3de, 0xb689, 0x492e, 0x80, 0xf0, 0xbe, 0x8b, 0xd7, 0xda, 0x4b, 0xa7 }

Prototype

typedef struct _EFI_MM_CONFIGURATION_PROTOCOL {
  EFI_MM_RESERVED_MMRAM_REGION                     *MmramReservedRegions;
  EFI_MM_REGISTER_MM_ENTRY                         RegisterMmEntry;
} EFI_MM_CONFIGURATION_PROTOCOL;

Members

MmramReservedRegions: A pointer to an array MMRAM ranges used by the initial MM Entry Point code.
RegisterMmEntry: A function to register the MM Foundation entry point.

Description

This protocol is a mandatory protocol published by a DXE CPU driver to indicate which areas within MMRAM are reserved for use by the CPU for any purpose, such as stack, save state or MM Entry Point.

The MmramReservedRegions points to an array of one or more EFI_MM_RESERVED_MMRAM_REGION structures, with the last structure having the MmramReservedSize set to 0. An empty array would contain only the last structure.

The RegisterMmEntry() function allows the MM IPL DXE driver to register the MM Foundation entry point with the MM entry vector code.

Related Definitions

typedef struct _EFI_MM_RESERVED_MMRAM_REGION {
  EFI_PHYSICAL_ADDRESS                            MmramReservedStart;
  UINT64                                          MmramReservedSize;
} EFI_MM_RESERVED_MMRAM_REGION;

MmramReservedStart: Starting address of the reserved MMRAM area, as it appears while MMRAM is open. Ignored if MmramReservedSize is 0.
MmramReservedSize: Number of bytes occupied by the reserved MMRAM area. A size of zero indicates the last MMRAM area.

5.5.2. EFI_MM_CONFIGURATION_PROTOCOL.RegisterMmEntry()

Summary

Register the MM Foundation entry point.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_MM_REGISTER_MM_ENTRY) (
  IN CONST EFI_MM_CONFIGURATION_PROTOCOL   *This,
  IN EFI_MM_ENTRY_POINT                    MmEntryPoint
)

Parameters

This: The EFI_MM_CONFIGURATION_PROTOCOL instance.
MmEntryPoint: MM Foundation entry point.

Description

This function registers the MM Foundation entry point with the processor code. This entry point will be invoked by the MM Processor entry code as defined in section 2.5.

Status Codes Returned

EFI_SUCCESS

The entry-point was successfully registered.

5.6. DXE MM Ready to Lock Protocol

EFI_DXE_MM_READY_TO_LOCK_PROTOCOL

Summary

Indicates that MM is about to be locked.

GUID

#define EFI_DXE_MM_READY_TO_LOCK_PROTOCOL_GUID \
{ 0x60ff8964, 0xe906, 0x41d0, 0xaf, 0xed, 0xf2, 0x41, 0xe9, 0x74, 0xe0, 0x8e}

Prototype

NULL

Description

This protocol is a mandatory protocol published by PI platform code.

This protocol in tandem with the End of DXE Even t facilitates transition of the platform from the environment where all of the components are under the authority of the platform manufacturer to the environment where third party extensible modules such as UEFI drivers and UEFI applications are executed.

The protocol is published immediately after signaling of the End of DXE Event .

PI modules that need to lock or protect their resources in anticipation of the invocation of 3rd party extensible modules should register for notification on installation of this protocol and effect the appropriate protections in their notification handlers. For example, PI platform code may choose to use notification handler to lock MM by invoking EFI_MM_ACCESS_PROTOCOL.Lock() function.

5.7. MM Communication Protocol

5.7.1. EFI_MM_COMMUNICATION_PROTOCOL

Summary

This protocol provides a means of communicating between drivers outside of MM and MMI handlers inside of MM.

GUID

#define EFI_MM_COMMUNICATION_PROTOCOL_GUID \
  { 0xc68e d8e2, 0x9dc6, 0x4cbd, 0x9d, 0x94, 0xdb, 0x65, 0xac, 0xc5, 0xc3, 0x32 }

Prototype

typedef struct _EFI_MM_COMMUNICATION_PROTOCOL {
EFI_MM_COMMUNICATE *Communicate;*
} EFI_MM_COMMUNICATION_PROTOCOL;

Members

Communicate: Sends/receives a message for a registered handler. See the Communicate() function description.

Description

This protocol provides runtime services for communicating between DXE drivers and a registered MMI handler.

5.7.2. EFI_MM_COMMUNICATION_PROTOCOL.Communicate()

Summary

Communicates with a registered handler.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_COMMUNICATE) (
  IN CONST *EFI_MM_COMMUNICATION_PROTOCOL    *This,
  IN OUT VOID                                *CommBuffer,
  IN OUT UINTN                               *CommSize OPTIONAL
  );

Parameters

This: The EFI_MM_COMMUNICATION_PROTOCOL instance.
CommBuffer: Pointer to the buffer to convey into MMRAM.
CommSize: The size of the data buffer being passed in. On exit, the size of data being returned. Zero if the handler does not wish to reply with any data. This parameter is optional and may be NULL .

Description

This function provides a service to send and receive messages from a registered UEFI service. The EFI_MM_COMMUNICATION_PROTOCOL driver is responsible for doing any of the copies such that the data lives in boot-service-accessible RAM.

A given implementation of the EFI_MM_COMMUNICATION_PROTOCOL may choose to use the EFI_MM_CONTROL_PROTOCOL for effecting the mode transition, or it may use some other method. The agent invoking the communication interface at runtime may be virtually mapped. The MM infrastructure code and handlers, on the other hand, execute in physical mode. As a result, the non- MM agent, which may be executing in the virtual-mode OS context as a result of an OS invocation of the UEFI SetVirtualAddressMap() service, should use a contiguous memory buffer with a physical address before invoking this service. If the virtual address of the buffer is used, the MM Driver may not know how to do the appropriate virtual-to-physical conversion.

To avoid confusion in interpreting frames, the CommunicateBuffer parameter should always begin with EFI_MM_COMMUNICATE_HEADER , which is defined in “Related Definitions” below. The header data is mandatory for messages sent into the MM agent.

If the CommSize parameter is omitted the MessageLength field in the EFI_MM_COMMUNICATE_HEADER , in conjunction with the size of the header itself, can be used to ascertain the total size of the communication payload. If the MessageLength is zero, or too large for the MM implementation to manage, the MM implementation must update the MessageLength to reflect the size of the Data buffer that it can tolerate.

If the CommSize parameter is passed into the call, but the integer it points to, has a value of 0, then this must be updated to reflect the maximum size of the CommBuffer that the implementation can tolerate.

Once inside of MM, the MM infrastructure will call all registered handlers with the same HandlerType as the GUID specified by HeaderGuid and the CommBuffer pointing to Data.

This function is not reentrant.

The standard header is used at the beginning of the EFI_MM_INITIALIATION_HEADER structure during MM initialization. See “Related Definitions” below for more information.

Related Definitions

typedef struct {
  EFI_GUID                    HeaderGuid;
  UINTN                       MessageLength;
  UINT8                       Data[ANYSIZE_ARRAY];
} EFI_MM_COMMUNICATE_HEADER;

HeaderGuid: Allows for disambiguation of the message format. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI Specification.
MessageLength: Describes the size of Data (in bytes) and does not include the size of the header..
Data: Designates an array of bytes that is MessageLength in size.

typedef struct {
  EFI_MM_COMMUNICATE_HEADER      Header;
  EFI_SYSTEM_TABLE               *SystemTable;
} EFI_MM_INITIALIZATION_HEADER;

#define EFI_MM_INITIALIZATION_GUID \
  0x99be0d8f, 0x3548, 0x48aa, {0xb5, 0x77, 0xfc, 0xfb, 0xa5, 0x6a, 0x67, 0xf7}}

Header: A standard MM communication buffer header, where HeaderGuid is set to EFI_MM_INITIALIZATION_GUID .
SystemTable: A pointer to the UEFI System Table. As with DXE driver initialization, there is no guarantee that the entries in this structure which rely on architectural protocols are implemented at the time when this event is generated.

Status Codes Returned

EFI_SUCCESS	The message was successfully posted
EFI_INVALID_PARAMETER	The buffer was NULL
EFI_BAD_BUFFER_SIZE	The buffer is too large for the MM implementation If this error is returned the MessageLength field in the CommBuffer header or the integer pointed by CommSize are updated to reflect the maximum payload size the implementation can accommodate See the function description above for more details
EFI_ACCESS_DENIED	The CommunicateBuffer parameter or CommSize parameter if not omitted are in address range that cannot be accessed by the MM environment

5.7.3. EFI_MM_COMMUNICATION2_PROTOCOL

Summary

This protocol provides a means of communicating between drivers outside of MM and MMI handlers inside of MM, in a way that hides the implementation details regarding whether traditional or standalone MM is being used.

GUID

#define EFI_MM_COMMUNICATION2_PROTOCOL_GUID \
  { 0x378daedc, 0xf06b, 0x4446, 0x83, 0x14, 0x40, 0xab, 0x93, 0x3c, 0x87, 0xa3 }

Prototype

typedef struct _EFI_MM_COMMUNICATION2_PROTOCOL {
EFI_MM_COMMUNICATE2 Communicate;
} EFI_MM_COMMUNICATION2_PROTOCOL;

Members

Communicate: Sends/receives a message for a registered handler. See the Communicate() function description.

Description

This protocol provides runtime services for communicating between DXE drivers and a registered MMI handler.

5.7.4. EFI_MM_COMMUNICATION2_PROTOCOL.Communicate()

Summary

Communicates with a registered handler.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_COMMUNICATE2) (
  IN CONST EFI_MM_COMMNICATION2_PROTOCOL   *This,
  IN OUT VOID                              *CommBufferPhysical,
  IN OUT VOID                              *CommBufferVirtual,
  IN OUT UINTN                             *CommSize OPTIONAL
);

Parameters

This: The EFI_MM_COMMUNICATION2_PROTOCOL instance.
Commbufferphysical: Physical address of the buffer to convey into MMRAM.
Commbuffervirtual: Virtual address of the buffer to convey into MMRAM.
Commsize: The size of the data buffer being passed in. On exit, the size of data being returned. Zero if the handler does not wish to reply with any data. This parameter is optional and may be NULL.

Description

Usage is identical to EFI_MM_COMMUNICATION_PROTOCOL.Communicate() except for the notes below:

Instead of passing just the physical address via the CommBuffer parameter, the caller must pass both the physical and the virtual addresses of the communication buffer.
If no virtual remapping has taken place, the physical address will be equal to the virtual address, and so the caller is required to pass the same value for both parameters.

Status Codes Returned

EFI_SUCCESS	The message was successfully posted
EFI_INVALID_PARAMETER	The CommBuffer parameters do not refer to the same location in memory
EFI_BAD_BUFFER_SIZE	The buffer is too large for the MM implementation If this error is returned the MessageLength field in the CommBuffer header or the integer pointed by CommSize are updated to reflect the maximum payload size the implementation can accommodate See the function description above for more details
EFI_ACCESS_DENIED	The CommunicateBuffer parameter or CommSize parameter if not omitted are in address range that cannot be accessed by the MM environment

5.7.5. EFI_MM_COMMUNICATION3_PROTOCOL

Summary

This protocol provides a means of communicating between drivers outside of MM and MMI handlers inside of MM, for communication buffer that is compliant with EFI_MM_COMMUNICATE_HEADER_V3.

GUID

#define EFI_MM_COMMUNICATION3_PROTOCOL_GUID \
{ \
  0xf7234a14, 0xdf2, 0x46c0, { 0xad, 0x28, 0x90, 0xe6, 0xb8, 0x83, 0xa7, 0x2f } \
}

Prototype

typedef struct _EFI_MM_COMMUNICATION3_PROTOCOL {
  EFI_MM_COMMUNICATE3  Communicate;
} EFI_MM_COMMUNICATION3_PROTOCOL;

Members

Communicate: Sends/receives a message for a registered handler. See the Communicate() function description.

Description

This protocol provides runtime services for communicating between DXE drivers and a registered MMI handler.

5.7.6. EFI_MM_COMMUNICATION3_PROTOCOL.Communicate()

Summary

Communicates with a registered handler.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_MM_COMMUNICATE3)(
  IN CONST EFI_MM_COMMUNICATION3_PROTOCOL   *This,
  IN OUT VOID                               *CommBufferPhysical,
  IN OUT VOID                               *CommBufferVirtual
  );

Parameters

This

The EFI_MM_COMMUNICATION3_PROTOCOL instance.

CommBufferPhysical: Physical address of the buffer to convey into MMRAM, of which content must start with EFI_MM_COMMUNICATE_HEADER_V3.
CommBufferVirtual: Virtual address of the buffer to convey into MMRAM, of which content must start with EFI_MM_COMMUNICATE_HEADER_V3.

Description

Usage is similar to EFI_MM_COMMUNICATION_PROTOCOL.Communicate() except for the notes below:

Communication buffer transfer to MM core should start with EFI_MM_COMMUNICATE_HEADER_V3.

With the updated header, the HeaderGuid field is redefine as header GUID for MM core to differentiate the header format.

The MessageGuid field is moved to be after the HeaderGuid field to allow for decent alignment and message disambiguation.

The MessageData field is replaced with a flexible array to allow users not having to consume extra data during communicate.

Instead of passing just the physical address via the CommBuffer parameter, the caller must pass both the physical and the virtual addresses of the communication buffer.

If no virtual remapping has taken place, the physical address will be equal to the virtual address, and so the caller is required to pass the same value for both parameters.

Related Definitions

typedef struct {
  EFI_GUID  HeaderGuid;
  UINT64    BufferSize;
  UINT64    Reserved;
  EFI_GUID  MessageGuid;
  UINT64    MessageSize;
  UINT8     MessageData[];
} EFI_MM_COMMUNICATE_HEADER_V3;

#define COMMUNICATE_HEADER_V3_GUID \
{ \
  0x68e8c853, 0x2ba9, 0x4dd7, { 0x9a, 0xc0, 0x91, 0xe1, 0x61, 0x55, 0xc9, 0x35 } \
}

HeaderGuid: Indicator GUID for MM core that the communication buffer is compliant with this v3 header. Must be COMMUNICATE_HEADER_V3_GUID.
BufferSize: This is technically a read-only field, which is described by the caller to indicate the size of the entire buffer (in bytes) available for this communication transaction, including this communication header.
Reserved: Reserved for future use.
MessageGuid: Allows for disambiguation of the message format.
MessageSize: Describes the size of MessageData (in bytes) and does not include the size of the header.
MessageData: Designates an array of bytes that is MessageSize in size.

Status Codes Returned

EFI_SUCCESS                 The message was successfully posted.
EFI_INVALID_PARAMETER       CommBufferPhysical was NULL or CommBufferVirtual was NULL.
EFI_BAD_BUFFER_SIZE         The buffer is too large for the MM implementation. If this error is returned, the MessageSize field in the CommBuffer header, are updated to reflect the maximum payload size the implementation can accommodate.
EFI_ACCESS_DENIED           The CommunicateBuffer parameter are in address range that cannot be accessed by the MM environment.