6. PI PEI PPIs¶

6.1. MM Access PPI¶

6.1.1. EFI_PEI_MM_ACCESS_PPI¶

Summary

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

GUID

#define EFI_PEI_MM_ACCESS_PROTOCOL_GUID { \\
  0x268f33a9, 0xcccd, 0x48be, { 0x88, 0x17, 0x86, 0x5, 0x3a, 0xc3, 0x2e, 0xd6 } \
  }

PPI Structure

typedef struct _EFI_PEI_MM_ACCESS_PPI {
  EFI_PEI_MM_OPEN          Open;
  EFI_PEI_MM_CLOSE         Close;
  EFI_PEI_MM_LOCK          Lock;
  EFI_PEI_MM_CAPABILITIES  GetCapabilities;
  BOOLEAN                  LockState;
  BOOLEAN                  OpenState;
} EFI_PEI_MM_ACCESS_PPI;

Parameters

Open: Opens the MMRAM. See the Open() function description.
Close: Closes th 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_PEI_MM_ACCESS_PPI abstracts the location and characteristics of MMRAM. The principal functionality found in the memory controller includes the following:

Exposing the MMRAM to all non-MM agents, or the “open” state
Shrouding the MMRAM to all but the MM agents, or the “closed” state
Preserving the system integrity, or “locking” the MMRAM, such that the settings cannot be perturbed by either boot service or runtime agents

6.1.2. EFI_PEI_MM_ACCESS_PPI.Open()¶

Summary

Opens the* MMRAM area to be accessible by a PEIM.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_OPEN) (
  IN EFI_PEI_SERVICES             **PeiServices,
  IN PEI_MM_ACCESS_PPI            *This,
  IN UINTN                        DescriptorIndex
  );

Parameters

PeiServices: An indirect pointer to the PEI Services Table published by the PEI Foundation.
This: The EFI_PEI_MM_ACCESS_PPI instance.
DescriptorIndex: The region of MMRAM to Open.

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

6.1.3. EFI_PEI_MM_ACCESS_PPI.Close()¶

Summary

Inhibits access to the MMRAM.

Prototype

typedef
EFI_STATUS
(EFIAPI EFI_PEI_MM_CLOSE)(
  IN EFI_PEI_SERVICES              **PeiServices,
  IN EFI_PEI_MM_ACCESS_PPI         *This
  IN UINTN                         DescriptorIndex
  );

Parameters

PeiServices: An indirect pointer to the PEI Services Table published by the PEI Foundation.
This: The EFI_PEI_MM_ACCESS_PPI instance.
DescriptorIndex: The region of MMRAM to Open.

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

6.1.4. EFI_PEI_MM_ACCESS_PPI.Lock()¶

Summary

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

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_LOCK) (
  IN EFI_PEI_SERVICES           **PeiServices,
  IN EFI_PEI_MM_ACCESS_PPI      *This
  IN UINTN                      DescriptorIndex
  );

Parameters

PeiServices: An indirect pointer to the PEI Services Table published by the PEI Foundation.
This: The EFI_PEI_MM_ACCESS_PPI instance.
DescriptorIndex: The region of MMRAM to Lock.

Description

Inhibits access to the MMRAM.

Status Codes Returned

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

6.1.5. EFI_PEI_MM_ACCESS_PPI.GetCapabilities()¶

Summary

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

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_CAPABILITIES) (
  IN EFI_PEI_SERVICES                   **PeiServices,
  IN CONST EFI_PEI_MM_ACCESS_PPI        *This,
  IN OUT UINTN                          *MmramMapSize,
  IN OUT EFI_MMRAM_DESCRIPTOR           *MmramMap
  );

Parameters

PeiServices: An indirect pointer to the PEI Services Table published by the PEI Foundation.
This: The EFI_PEI_MM_ACCESS_PPI 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_DESCRIPTORs

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 PPI 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 PPI are a subset of the capabilities of the hardware.

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

6.2. MM Control PPI¶

6.2.1. EFI_PEI_MM_CONTROL_PPI¶

Summary

This PPI is used initiate synchronous MMI activations. This PPI could be published by a processor driver to abstract the MMI IPI or a driver which abstracts the ASIC that is supporting the APM port.

Because of the possibility of performing MMI IPI transactions, the ability to generate this event from a platform chipset agent is an optional capability for both IA-32 and x64-based systems.

GUID

#define EFI_PEI_MM_CONTROL_PPI_GUID { \\
  0x61c68702, 0x4d7e, 0x4f43, { 0x8d, 0xef, 0xa7, 0x43, 0x5, 0xce, 0x74, 0xc5 } \
  }

PPI Structure

typedef struct _EFI_PEI_MM_CONTROL_PPI {
  EFI_PEI_MM_ACTIVATE       Trigger;
  EFI_PEI_MM_DEACTIVATE     Clear;
} EFI_PEI_MM_CONTROL_PPI;

Parameters

Trigger: Initiates the MMI activation. See the Trigger() function description.
Clear: Quiesces the MMI activation. See the Clear() function description.

Description

The EFI_PEI_MM_CONTROL_PPI is produced by a PEIM. 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.

6.2.2. EFI_PEI_MM_CONTROL_PPI.Trigger()¶

Summary

Invokes PPI activation from the PI PEI environment.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_ACTIVATE) (
  IN EFI_PEI_SERVICES              **PeiServices,
  IN CONST EFI_PEI_MM_CONTROL_PPI  *This,
  IN OUT INT8                      *ArgumentBuffer     OPTIONAL,
  IN OUT UINTN                     *ArgumentBufferSize OPTIONAL,
  IN BOOLEAN                       Periodic            OPTIONAL,
  IN UINTN                         ActivationInterval  OPTIONAL
);

Parameters

PeiServices: An indirect pointer to the PEI Services Table published by the PEI Foundation.
This: The EFI_PEI_MM_CONTROL_PPI instance.
ArgumentBuffer: The value passed to the MMI handler. 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 section 6.2.
ArgumentBufferSize: The size of the data passed in ArgumentBuffer or NULL if ArgumentBuffer is NULL .
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.

6.2.3. EFI_PEI_MM_CONTROL_PPI.Clear()¶

Summary

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

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_DEACTIVATE) (
  IN EFI_PEI_SERVICES                **PeiServices,
  IN CONST EFI_PEI_MM_CONTROL_PPI    *This,
  IN BOOLEAN                         Periodic OPTIONAL
  );

Parameters

This: The EFI_PEI_MM_CONTROL_PPI 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 PEIM 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) followed the flows engendered by the Trigger and the subsequent non-MM resident PEIM 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

6.3. EFI DELAYED DISPATCH PPI (Required)¶

6.3.1. EFI_DELAYED_DISPATCH_PPI (Required)¶

Summary

Provide timed event service in PEI

GUID

#define EFI_DELAYED_DISPATCH_PPI_GUID \\
  { \
    0x869c711d, 0x649c, 0x44fe, { 0x8b, 0x9e, 0x2c, 0xbb, 0x29,
  0x11, 0xc3, 0xe6} } \
  }

PPI Interface Structure

struct _EFI_DELAYED_DISPATCH_PPI {
  EFI_DELAYED_DISPATCH_REGISTER      Register;
  EFI_DELAYED_DISPATCH WAIT_ON_EVENT WaitOnEvent;
};

Parameters

Register: Register a callback to be called after a minimum delay has occurred.
WaitOnEvent: Pause current process and allow other components to continue to dispatch until all entries with specified “Unique ID” have completed.

Description

Define a time based event mechanism for PEI (Pei Delayed Dispatch):

Eliminate spin loops for timing. Instead of blocking for 50 or 100 ms, the driver would request callbacks after 50ms (or 100ms) and allow other PEIM’s to dispatch. Each loop through the PEI dispatcher will attempt to dispatch each of the queued delayed dispatch requests.

Method to schedule a callback after a minimum delay, not a real time callback. Maintains a 64 bit “State” for use by the callback.

PPI has only one function - Register, to register a function to be called after the required delay with the current value of “State”.

6.3.2. EFI_DELAYED_DISPATCH_PPI.Register()¶

Summary

Register a callback to be called after a minimum delay has occurred.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DELAYED_DISPATCH_REGISTER)(
  IN EFI_DELAYED_DISPATCH_PPI       *This,
  IN EFI_DELAYED_DISPATCH_FUNCTION  Function,
  IN UINT64                         Context,
  IN EFI_GUID                       *UniqueId OPTIONAL,
  IN UINT32                         Delay
  );

Parameters

This: Pointer to the EFI_DELAYED_DISPATCH_PPI instance.
Function: Function to call back. The function prototype is defined in the “Related Definitions” below.
Context: Context data.
UniqueId: GUID for identifying the delayed dispatch request.
Delay: Delay interval. This parameter describes a multiple of microseconds.

Description

This function is invoked by a PEIM to have a handler returned. The handler will be invoked after at the minimum of specified Delay. Note that if the Register service is called with a Delay of zero, then the handler will be dispatched immediately. If the UniqueId is specified, this request will be marked with GUID for WaitOnEvent usage.

Related Definitions

//***********************************************
// EFI_DELAYED_DISPATCH_FUNCTION
//***********************************************

typedef
VOID
(EFIAPI *EFI_DELAYED_DISPATCH_FUNCTION)(
  IN  OUT UINT64     *Context,
      OUT UINT32     *NewDelay
  );

Context: Pointer to Context Data. Can be updated by routine.
NewDelay: The new delay in us. Leave at 0 to unregister this callback. Upon return, if NewDelay is 0, the function is unregistered. If NewDelay is not zero, this routine will be called again after the new delay period.

Status Codes Returned (EFI_DELAYED_DISPATCH_PPI.Register)

EFI_SUCCESS	Function successfully invoked
EFI_INVALID_PARAMETER	One of the arguments is not supported
EFI_OUT_OF_RESOURCES	No more entries

6.3.3. EFI_DELAYED_DISPATCH_PPI.WaitOnEvent()¶

Summary

Pause current process and allow other components to continue to dispatch until all entries with specified “Unique ID” have completed.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DELAYED_DISPATCH_WAIT ON EVENT)(
  IN  EFI_DELAYED_DISPATCH_PPI      *This,
  IN  EFI_GUID                      UniqueId
  );

Parameters

This: Pointer to the EFI_DELAYED_DISPATCH_PPI instance.
UniqueId: Delayed dispatch request ID the caller will wait on.

Description

This function is invoked by a PEIM to wait until all specified UniqueId events have been dispatched. The other events will continue to dispatch while this process is being paused.

Status Codes Returned

EFI_SUCCESS	Function successfully invoked
EFI_INVALID_PARAMETER	One of the arguments is not supported

6.4. MM Configuration PPI¶

6.4.1. EFI_PEI_MM_CONFIGURATION_PPI¶

Summary

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

GUID

#define EFI_PEI_MM_CONFIGURATION_PPI_GUID { \
  0xc109319, 0xc149, 0x450e, 0xa3, 0xe3, 0xb9, 0xba, 0xdd,
0x9d, 0xc3, 0xa4 \
}

PPI Structure

typedef struct _EFI_PEI_MM_CONFIGURATION_PPI {
  EFI_MM_RESERVED_MMRAM_REGION      *MmramReservedRegions* ;
  EFI_PEI_MM_REGISTER_MM_ENTRY      RegisterMmEntry;
} EFI_PEI_MM_CONFIGURATION_PPI;

Members

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

Description

This PPI is a PPI published by a CPU PEIM 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. If a platform chooses to let a CPU PEIM do MMRAM relocation, this PPI must be produced by this CPU PEIM.

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 PEIM to register the MM Foundation entry point with the MM entry vector code.

6.4.2. EFI_PEI_MM_CONFIGURATION_PPI.RegisterMmEntry()¶

Summary

Register the MM Foundation entry point.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_REGISTER_MM_ENTRY) (
  IN CONST EFI_PEI_MM_CONFIGURATION_PPI    *This,
  IN EFI_MM_ENTRY_POINT                    MmEntryPoint
  )

Parameters

This: The EFI_PEI_MM_CONFIGURATION_PPI 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.

6.5. MM Communication PPI¶

6.5.1. EFI_PEI_MM_COMMUNICATION_PPI¶

Summary

This PPI provides a means of communicating between drivers outside of MM and MMI handlers inside of MM in PEI phase.

GUID

#define EFI_PEI_MM_COMMUNICATION_PPI_GUID { \
  0xae933e1c, 0xcc47, 0x4e38, \
  { 0x8f, 0xe, 0xe2, 0xf6, 0x1d, 0x26, 0x5, 0xdf } \
}

PPI Structure

typedef struct _EFI_PEI_MM_COMMUNICATION_PPI {
  EFI_PEI_MM_COMMUNICATE        Communicate;
} EFI_PEI_MM_COMMUNICATION_PPI;

Members

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

Description

This PPI provides services for communicating between PEIM and a registered MMI handler.

6.5.2. EFI_PEI_MM_COMMUNICATION_PPI.Communicate()¶

Summary

Communicates with a registered handler.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_MM_COMMUNICATE) (
  IN CONST EFI_PEI_MM_COMMUNICATION_PPI    *This,
  IN OUT VOID                              *CommBuffer,
  IN OUT UINTN                             *CommSize
  );

Parameters

This: The EFI_PEI_MM_COMMUNICATION_PPI 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.

Description

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

A given implementation of the EFI_PEI_MM_COMMUNICATION_PPI may choose to use the EFI_MM_CONTROL_PPI for effecting the mode transition, or it may use some other method.

The agent invoking the communication interface must be physical/virtually 1:1 mapped.

To avoid confusion in interpreting frames, the CommBuffer parameter should always begin with EFI_MM_COMMUNICATE_HEADER . The header data is mandatory for messages sent into the MM agent.

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.

Status Codes Returned

EFI_SUCCESS	The message was successfully posted
EFI_INVALID_PARAMETER	The buffer was NULL