12. DXE Architectural Protocols¶

12.1. Introduction¶

The DXE Foundation is abstracted from the platform hardware through a set of architectural protocols. These protocols function just like other protocols in every way. The only difference is that these architectural protocols are the protocols that the DXE Foundation itself consumes to produce the UEFI Boot Services, UEFI Runtime Services, and DXE Services. DXE drivers that are loaded from firmware volumes produce the DXE Architectural Protocols. This means that the DXE Foundation must have enough services to load and start DXE drivers before even a single DXE driver is executed.

The DXE Foundation is passed a HOB list that must contain a description of some amount of system memory and at least one firmware volume. The system memory descriptors in the HOB list are used to initialize the UEFI services that require only memory to function correctly. The system is also guaranteed to be running on only one processor in flat physical mode with interrupts disabled. The firmware volume is passed to the DXE Dispatcher, and the DXE Dispatcher must contain a read-only firmware file system driver to search for the a priori file and any DXE drivers in the firmware volumes. When a driver is discovered that needs to be loaded and executed, the DXE Dispatcher will use a PE/COFF loader to load and invoke the DXE driver. The early DXE drivers will produce the DXE Architectural Protocols, so the DXE Foundation can produce the full complement of UEFI Boot Services and UEFI Runtime Services.

The following figure shows the HOB list being passed to the DXE Foundation.

_images/V2_DXE_Architectural_Protocols-2.png — Fig. 12.4 **DXE Architectural Protocols**¶

The DXE Foundation consumes the services of the DXE Architectural Protocols and produces the following:

UEFI System Table
UEFI Boot Services Table
UEFI Runtime Services Table
DXE Services Table

The UEFI Boot Services Table and DXE Services Table are allocated from UEFI boot services memory, which means that the UEFI Boot Services Table and DXE Services Table are freed when the OS runtime phase is entered. The UEFI System Table and UEFI Runtime Services Table are allocated from UEFI runtime services memory, and they persist into the OS runtime phase.

When executing upon an UEFI-compliant system, UEFI drivers, applications, and UEFI-aware operating systems can discern if the platform is built upon the Foundation by searching for the DXE Services Table GUID in the UEFI System configuration table. The DXE Architectural Protocols shown on the left of the figure are used to produce the UEFI Boot Services and DXE Services.

The DXE Foundation and these protocols will be freed when the system transitions to the OS runtime phase. The DXE Architectural Protocols shown on the right are used to produce the UEFI Runtime Services. These services will persist in the OS runtime phase. The Runtime Architectural Protocol in the middle is unique. This protocol provides the services that are required to transition the runtime services from physical mode to virtual mode under the direction of an OS. Once this transition is complete, the services of the Runtime Architectural Protocol can no longer be used. The following topics describe all of the DXE Architectural Protocols in detail.

12.2. Boot Device Selection (BDS) Architectural Protocol¶

12.2.1. EFI_BDS_ARCH_PROTOCOL¶

Summary

Transfers control from the DXE phase to an operating system or system utility. This protocol must be produced by a boot service or runtime DXE driver and may only be consumed by the DXE Foundation.

GUID

#define EFI_BDS_ARCH_PROTOCOL_GUID \
{0x665E3FF6,0x46CC,0x11d4,
0x9A,0x38,0x00,0x90,0x27,0x3F,0xC1,0x4D}

Protocol Interface Structure

typedef struct {
EFI_BDS_ENTRY   Entry;
} EFI_BDS_ARCH_PROTOCOL;

Parameters

Entry: The entry point to BDS. See the Entry() function description. This call does not take any parameters, and the return value can be ignored. If it returns, then the dispatcher must be invoked again, if it never returns, then an operating system or a system utility have been invoked.

Description

The EFI_BDS_ARCH_PROTOCOL transfers control from DXE to an operating system or a system utility. If there are not enough drivers initialized when this protocol is used to access the required boot device(s), then this protocol should add drivers to the dispatch queue and return control back to the dispatcher. Once the required boot devices are available, then the boot device can be used to load and invoke an OS or a system utility.

12.2.2. EFI_BDS_ARCH_PROTOCOL.Entry()¶

Summary

Performs Boot Device Selection (BDS) and transfers control from the DXE Foundation to the selected boot device. The implementation of the boot policy must follow the rules outlined in the Boot Manager chapter of the UEFI 2.0 specification. This boot policy allows for flexibility, so the platform vendor will typically customize the implementation of this service.

Prototype

typedef
VOID
(EFIAPI *EFI_BDS_ENTRY) (
  IN CONST EFI_BDS_ARCH_PROTOCOL   *This
  );

Parameters

This: The EFI_BDS_ARCH_PROTOCOL instance.

Description

This function uses policy data from the platform to determine what operating system or system utility should be loaded and invoked. This function call also optionally uses the user’s input to determine the operating system or system utility to be loaded and invoked. When the DXE Foundation has dispatched all the drivers on the dispatch queue, this function is called. This function will attempt to connect the boot devices required to load and invoke the selected operating system or system utility. During this process, additional firmware volumes may be discovered that may contain addition DXE drivers that can be dispatched by the DXE Foundation. If a boot device cannot be fully connected, this function calls the DXE Service Dispatch() to allow the DXE drivers from any newly discovered firmware volumes to be dispatched. Then the boot device connection can be attempted again. If the same boot device connection operation fails twice in a row, then that boot device has failed, and should be skipped. This function should never return.

12.3. CPU Architectural Protocol¶

12.3.1. EFI_CPU_ARCH_PROTOCOL¶

Summary

Abstracts the processor services that are required to implement some of the DXE services. This protocol must be produced by a boot service or runtime DXE driver and may only be consumed by the DXE Foundation and DXE drivers that produce architectural protocols.

GUID

#define EFI_CPU_ARCH_PROTOCOL_GUID \
  {0x26baccb1,0x6f42,0x11d4,0xbc,\
  0xe7,0x0,0x80,0xc7,0x3c,0x88,0x81}

Protocol Interface Structure

typedef struct _EFI_CPU_ARCH_PROTOCOL {
  EFI_CPU_FLUSH_DATA_CACHE            FlushDataCache;
  EFI_CPU_ENABLE_INTERRUPT            EnableInterrupt;
  EFI_CPU_DISABLE_INTERRUPT           DisableInterrupt;
  EFI_CPU_GET_INTERRUPT_STATE         GetInterruptState;
  EFI_CPU_INIT                        Init;
  EFI_CPU_REGISTER_INTERRUPT_HANDLER  RegisterInterruptHandler;
  EFI_CPU_GET_TIMER_VALUE             GetTimerValue;
  EFI_CPU_SET_ATTRIBUTES              SetMemoryAttributes;
  UINT32                              NumberOfTimers;
  UINT32                              DmaBufferAlignment;
} EFI_CPU_ARCH_PROTOCOL;

Parameters

FlushDataCache: Flushes a range of the processor’s data cache. See the FlushDataCache() function description. If the processor does not contain a data cache, or the data cache is fully coherent, then this function can just return EFI_SUCCESS . If the processor does not support flushing a range of addresses from the data cache, then the entire data cache must be flushed. This function is used by the root bridge I/O abstractions to flush data caches for DMA operations.

EnableInterrupt: Enables interrupt processing by the processor. See the EnableInterrupt() function description. This function is used by the Boot Service RaiseTPL() and RestoreTPL() .

DisableInterrupt: Disables interrupt processing by the processor. See the DisableInterrupt() function description. This function is used by the Boot Service RaiseTPL() and RestoreTPL() .

GetInterruptState: Retrieves the processor’s current interrupt state. See the GetInterruptState() function description.

Init: Generates an INIT on the processor. See the Init() function description. This function may be used by the EFI_RESET Protocol depending upon a specified boot path. If a processor cannot programmatically generate an INIT without help from external hardware, then this function returns EFI_UNSUPPORTED .

RegisterInterruptHandler: Associates an interrupt service routine with one of the processor’s interrupt vectors. See the RegisterInterruptHandler() function description. This function is typically used by the EFI_TIMER_ARCH_PROTOCOL to hook the timer interrupt in a system. It can also be used by the debugger to hook exception vectors.

GetTimerValue: Returns the value of one of the processor’s internal timers. See the GetTimerValue() function description.

SetMemoryAttributes: Change a memory region to support specified memory attributes. See the SetMemoryAttributes() function description.

NumberOfTimers: The number of timers that are available in a processor. The value in this field is a constant that must not be modified after the CPU Architectural Protocol is installed. All consumers must treat this as a read-only field.

DmaBufferAlignment: The size, in bytes, of the alignment required for DMA buffer allocations. This is typically the size of the largest data cache line in the platform. This value can be determined by looking at the data cache line sizes of all the caches present in the platform, and returning the largest. This is used by the root bridge I/O abstraction protocols to guarantee that no two DMA buffers ever share the same cache line. The value in this field is a constant that must not be modified after the CPU Architectural Protocol is installed. All consumers must treat this as a read-only field.

Description

The EFI_CPU_ARCH_PROTOCOL is used to abstract processor-specific functions from the DXE Foundation. This includes flushing caches, enabling and disabling interrupts, hooking interrupt vectors and exception vectors, reading internal processor timers, resetting the processor, and determining the processor frequency.

The GCD memory space map is initialized by the DXE Foundation based on the contents of the HOB list. The HOB list contains the capabilities of the different memory regions, but it does not contain their current attributes. The DXE driver that produces the EFI_CPU_ARCH_PROTOCOL is responsible for maintaining the current attributes of the memory regions visible to the processor. This means that the DXE driver that produces the EFI_CPU_ARCH_PROTOCOL must seed the GCD memory space map with the initial state of the attributes for all the memory regions visible to the processor. The DXE Service SetMemorySpaceAttributes() allows the attributes of a memory range to be modified. The SetMemorySpaceAttributes() DXE Service is implemented using the SetMemoryAttributes() service of the EFI_CPU_ARCH_PROTOCOL.

To initialize the state of the attributes in the GCD memory space map, the DXE driver that produces the EFI_CPU_ARCH_PROTOCOL must call the DXE Service SetMemorySpaceAttributes() for all the different memory regions visible to the processor passing in the current attributes. If the CPU does not support certain memory region attributes in the UEFI Specification, then these should always be reported as disabled or not present. If the CPU supports additional memory region attributes, then the reported attributes should be those which most closely match but not exceed those described in the specification. This, in turn, will call back to the SetMemoryAttributes() service of the EFI_CPU_ARCH_PROTOCOL , and all of these calls must return EFI_SUCCESS , since the DXE Foundation is only requesting that the attributes of the memory region be set to their current settings. This will force the current attributes in the GCD memory space map to be set to these current settings. After this initialization is complete, the next call to the DXE Service GetMemorySpaceMap() will correctly show the current attributes of all the memory regions. In addition, any future calls to the DXE Service SetMemorySpaceAttributes() will in turn call the EFI_CPU_ARCH_PROTOCOL to see if those attributes can be modified, and if they can, the GCD memory space map will be updated accordingly.

12.3.2. EFI_CPU_ARCH_PROTOCOL.FlushDataCache()¶

Summary

Flushes a range of the processor’s data cache. If the processor does not contain a data cache, or the data cache is fully coherent, then this function can just return EFI_SUCCESS . If the processor does not support flushing a range of addresses from the data cache, then the entire data cache must be flushed. This function is used by the root bridge I/O abstractions to flush caches for DMA operations.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_FLUSH_DATA_CACHE) (
  IN CONST EFI_CPU_ARCH_PROTOCOL   *This,
  IN EFI_PHYSICAL_ADDRESS          Start,
  IN UINT64                        Length,
  IN EFI_CPU_FLUSH_TYPE            FlushType
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

Start: The beginning physical address to flush from the processor’s data cache.

Length: The number of bytes to flush from the processor’s data cache. This function may flush more bytes than Length specifies depending upon the granularity of the flush operation that the processor supports.

FlushType: Specifies the type of flush operation to perform. Type EFI_CPU_FLUSH_TYPE is defined in “Related Definitions” below.

Description

This function flushes the range of addresses from Start to Start+Length from the processor’s data cache. If Start is not aligned to a cache line boundary, then the bytes before Start to the preceding cache line boundary are also flushed. If Start+Length is not aligned to a cache line boundary, then the bytes past Start+Length to the end of the next cache line boundary are also flushed. If the address range is flushed, then EFI_SUCCESS is returned. If the address range cannot be flushed, then EFI_DEVICE_ERROR is returned. If the processor does not support the flush type specified by FlushType , then EFI_UNSUPPORTED is returned. The FlushType of EfiCpuFlushTypeWriteBackInvalidate must be supported. If the data cache is fully coherent with all DMA operations, then this function can just return EFI_SUCCESS . If the processor does not support flushing a range of the data cache, then the entire data cache can be flushed.

typedef enum {
  EfiCpuFlushTypeWriteBackInvalidate,
  EfiCpuFlushTypeWriteBack,
  EfiCpuFlushTypeInvalidate,
  EfiCpuMaxFlushType
} EFI_CPU_FLUSH_TYPE;

Status Codes Returned

Table 12.1 Status Codes Returned¶
EFI_SUCCESS	The address range from `Start` to `Start+Length` was flushed from the processor’s data cache.
EFI_UNSUPPORTED	The processor does not support the cache flush type specified by `FlushType`.
EFI_DEVICE_ERROR	The address range from `Start` to `Start+Length` could not be flushed from the processor s data cache.

12.3.3. EFI_CPU_ARCH_PROTOCOL.EnableInterrupt()¶

Summary

Enables interrupt processing by the processor. This function is used to implement the Boot Services RaiseTPL() and RestoreTPL().

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_ENABLE_INTERRUPT) (
  IN CONST EFI_CPU_ARCH_PROTOCOL  *This
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

Description

This function enables interrupt processing by the processor. If interrupts are enabled, then EFI_SUCCESS is returned. Otherwise, EFI_DEVICE_ERROR is returned.

Status Codes Returned

Table 12.2 Status Codes Returned¶
EFI_SUCCESS	Interrupts are enabled on the processor.
EFI_DEVICE_ERROR	Interrupts could not be enabled on the processor.

12.3.4. EFI_CPU_ARCH_PROTOCOL.DisableInterrupt()¶

Summary

Disables interrupt processing by the processor. This function is used to implement the Boot Services RaiseTPL() and RestoreTPL().

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_DISABLE_INTERRUPT) (
  IN CONST EFI_CPU_ARCH_PROTOCOL   *This
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

Description

This function disables interrupt processing by the processor. If interrupts are disabled, then EFI_SUCCESS is returned. Otherwise, EFI_DEVICE_ERROR is returned.

Status Codes Returned

Table 12.3 Status Codes Returned¶
EFI_SUCCESS	Interrupts are disabled on the processor.
EFI_DEVICE_ERROR	Interrupts could not be disabled on the processor.

12.3.5. EFI_CPU_ARCH_PROTOCOL.GetInterruptState()¶

Summary

Retrieves the processor’s current interrupt state.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_GET_INTERRUPT_STATE) (
  IN CONST EFI_CPU_ARCH_PROTOCOL   *This,
  OUT BOOLEAN                      *State
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

State: A pointer to the processor’s current interrupt state. Set to TRUE if interrupts are enabled and FALSE if interrupts are disabled.

Description

This function retrieves the processor’s current interrupt state a returns it in State . If interrupts are currently enabled, then TRUE is returned. If interrupts are currently disabled, then FALSE is returned. If State is NULL , then EFI_INVALID_PARAMETER is returned. Otherwise, EFI_SUCCESS is returned.

Status Codes Returned

Table 12.4 Status Codes Returned¶
EFI_SUCCESS	The processor’s current interrupt state was returned in `State`.
EFI_INVALID_PARAMETER	`State` is `NULL`.

12.3.6. EFI_CPU_ARCH_PROTOCOL.Init()¶

Summary

Generates an INIT on the processor.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_INIT) (
  IN CONST EFI_CPU_ARCH_PROTOCOL   *This,
  IN EFI_CPU_INIT_TYPE             InitType
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

InitType: The type of processor INIT to perform. Type EFI_CPU_INIT_TYPE is defined in “Related Definitions” below.

Description

This function generates an INIT on the processor. If this function succeeds, then the processor will be reset, and control will not be returned to the caller. If InitType is not supported by this processor, or the processor cannot programmatically generate an INIT without help from external hardware, then EFI_UNSUPPORTED is returned. If an error occurs attempting to generate an INIT, then EFI_DEVICE_ERROR is returned.

typedef enum {
  EfiCpuInit,
  EfiCpuMaxInitType
} EFI_CPU_INIT_TYPE;

Status Codes Returned

Table 12.5 Status Codes Returned¶
EFI_SUCCESS	The processor INIT was performed. This return code should never be seen.
EFI_UNSUPPORTED	The processor INIT operation specified by `InitType` is not supported by this processor.
EFI_DEVICE_ERROR	The processor INIT failed.

12.3.7. EFI_CPU_ARCH_PROTOCOL.RegisterInterruptHandler()¶

Summary

Registers a function to be called from the processor interrupt handler.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_REGISTER_INTERRUPT_HANDLER) (
  IN CONST EFI_CPU_ARCH_PROTOCOL       *This,
  IN EFI_EXCEPTION_TYPE                InterruptType,
  IN EFI_CPU_INTERRUPT_HANDLER         InterruptHandler
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

InterruptType: Defines which interrupt or exception to hook. Type EFI_EXCEPTION_TYPE and the valid values for this parameter are defined in EFI_DEBUG_SUPPORT_PROTOCOL of the UEFI 2.0 specification.

InterruptHandler: A pointer to a function of type EFI_CPU_INTERRUPT_HANDLER that is called when a processor interrupt occurs. If this parameter is NULL , then the handler will be uninstalled. Type EFI_CPU_INTERRUPT_HANDLER is defined in “Related Definitions” below.

Description

The RegisterInterruptHandler() function registers and enables the handler specified by InterruptHandler for a processor interrupt or exception type specified by InterruptType . If InterruptHandler is NULL , then the handler for the processor interrupt or exception type specified by InterruptType is uninstalled. The installed handler is called once for each processor interrupt or exception.

If the interrupt handler is successfully installed or uninstalled, then EFI_SUCCESS is returned.

If InterruptHandler is not NULL , and a handler for InterruptType has already been installed, then EFI_ALREADY_STARTED is returned.

If InterruptHandler is NULL , and a handler for InterruptType has not been installed, then EFI_INVALID_PARAMETER is returned.

If InterruptType is not supported, then EFI_UNSUPPORTED is returned.

The EFI_CPU_ARCH_PROTOCOL implementation of this function must handle saving and restoring system context to the system context record around calls to the interrupt handler. It must also perform the necessary steps to return to the context that was interrupted by the interrupt. No chaining of interrupt handlers is allowed.

typedef
VOID
(*EFI_CPU_INTERRUPT_HANDLER) (
  IN EFI_EXCEPTION_TYPE  InterruptType,
  IN EFI_SYSTEM_CONTEXT  SystemContext
  );

InterruptType: Defines the type of interrupt or exception that occurred on the processor. This parameter is processor architecture specific. The type EFI_EXCEPTION_TYPE and the valid values for this parameter are defined in EFI_DEBUG_SUPPORT_PROTOCOL of the UEFI 2.0 specification.

SystemContext: A pointer to the processor context when the interrupt occurred on the processor. Type EFI_SYSTEM_CONTEXT is defined in the EFI_DEBUG_SUPPORT_PROTOCOL of the UEFI 2.0 specification.

Status Codes Returned

Table 12.6 Status Codes Returned¶
EFI_SUCCESS	The handler for the processor interrupt was successfully installed or uninstalled.
EFI_ALREADY_STARTED	`InterruptHandler` is not `NULL` and a handler for `InterruptType` was previously installed.
EFI_INVALID_PARAMETER	`InterruptHandler` is `NULL` and a handler for `InterruptType` was not previously installed.
EFI_UNSUPPORTED	The interrupt specified by `InterruptType` is not supported.

12.3.8. EFI_CPU_ARCH_PROTOCOL.GetTimerValue()¶

Summary

Returns a timer value from one of the processor’s internal timers.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_GET_TIMER_VALUE) (
  IN CONST EFI_CPU_ARCH_PROTOCOL     *This,
  IN UINT32                          TimerIndex,
  OUT UINT64                         *TimerValue,
  OUT UINT64                         *TimerPeriod OPTIONAL
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

TimerIndex: Specifies which processor timer is to be returned in TimerValue . This parameter must be between 0 and NumberOfTimers-1 .

TimerValue: Pointer to the returned timer value.

TimerPeriod: A pointer to the amount of time that passes in femtoseconds (10^15) for each increment of TimerValue . If TimerValue does not increment at a predictable rate, then 0 is returned. The amount of time that has passed between two calls to GetTimerValue() can be calculated with the formula ( TimerValue2 - TimerValue1 ) * TimerPeriod. This parameter is optional and may be NULL.

Description

This function reads the processor timer specified by TimerIndex and returns it in TimerValue . If TimerValue is NULL , then EFI_INVALID_PARAMETER is returned. If TimerPeriod is not NULL , then the amount of time that passes in femtoseconds (10^15) for each increment if TimerValue is returned in TimerPeriod . If the timer does not run at a predictable rate, then a TimerPeriod of 0 is returned. If TimerIndex does not specify a valid timer in this processor, then EFI_INVALID_PARAMETER is returned. The valid range for TimerIndex is 0..``NumberOfTimers``-1. If the processor does not contain any readable timers, then this function returns EFI_UNSUPPORTED . If an error occurs attempting to read one of the processor’s timers, then EFI_DEVICE_ERROR is returned.

Status Codes Returned

Table 12.7 Status Codes Returned¶
EFI_SUCCESS	The processor timer value specified by `TimerIndex` was returned in `TimerValue`.
EFI_INVALID_PARAMETER	`TimerValue` is `NULL`.
EFI_INVALID_PARAMETER	`TimerIndex` is not valid.
EFI_UNSUPPORTED	The processor does not have any readable timers.
EFI_DEVICE_ERROR	An error occurred attempting to read one of the processor s timers.

12.3.9. EFI_CPU_ARCH_PROTOCOL.SetMemoryAttributes()¶

Summary

Change a memory region to support specified memory attributes.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CPU_SET_MEMORY_ATTRIBUTES) (
  IN CONST EFI_CPU_ARCH_PROTOCOL   *This,
  IN EFI_PHYSICAL_ADDRESS          BaseAddress,
  IN UINT64                        Length,
  IN UINT64                        Attributes
  );

Parameters

This: The EFI_CPU_ARCH_PROTOCOL instance.

BaseAddress: The physical address that is the start address of a memory region. Type EFI_PHYSICAL_ADDRESS is defined in the AllocatePages() function description in the UEFI 2.0 specification.

Length: The size in bytes of the memory region.

Attributes: A bit mask that specifies the memory region attributes. See the UEFI Boot Service GetMemoryMap() for the set of legal attribute bits.

Description

This function changes the attributes for the memory region specified by BaseAddress and Length to support those specified by Attributes . If the memory region attributes are changed so that they do not conflict with those specified by Attributes , then EFI_SUCCESS is returned.

This function modifies the attributes for the memory region specified by BaseAddress and Length from their current attributes to the attributes specified by Attributes . If this modification of attributes succeeds, then EFI_SUCCESS is returned.

If Length is zero, then EFI_INVALID_PARAMETER is returned.

If the processor does not support one or more bytes of the memory range specified by BaseAddress and Length , then EFI_UNSUPPORTED is returned.

If the attributes specified by Attributes are not supported for the memory region specified by BaseAddress and Length , then EFI_UNSUPPORTED is returned.

If the attributes for one or more bytes of the memory range specified by BaseAddress and Length cannot be modified because the current system policy does not allow them to be modified, then EFI_ACCESS_DENIED is returned.

If there are not enough system resources available to modify the attributes of the memory range, then EFI_OUT_OF_RESOURCES is returned.

If Attributes specifies a combination of memory attributes that cannot be set together, then EFI_INVALID_PARAMETER is returned. For example, if both EFI_MEMORY_UC and EFI_MEMORY_WT are set.

Status Codes Returned

Table 12.8 Status Codes Returned¶
EFI_SUCCESS	The attributes were set for the memory region.
EFI_INVALID_PARAMETER	`Length` is zero.
EFI_INVALID_PARAMETER	`Attributes` specified an illegal combination of attributes that cannot be set together.
EFI_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by `BaseAddress` and `Length`.
EFI_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by `BaseAddress` and `Length`.
EFI_ACCESS_DENIED	The attributes for the memory resource range specified by `BaseAddress` and `Length` cannot be modified.
EFI_OUT_OF_RESOURCES	There are not enough system resources to modify the attributes of the memory resource range.

12.4. Metronome Architectural Protocol¶

12.4.1. EFI_METRONOME_ARCH_PROTOCOL¶

Summary

Used to wait for ticks from a known time source in a platform. This protocol may be used to implement a simple version of the Stall() Boot Service. This protocol must be produced by a boot service or runtime DXE driver and may only be consumed by the DXE Foundation and DXE drivers that produce DXE Architectural Protocols.

GUID

#define EFI_METRONOME_ARCH_PROTOCOL_GUID \
  {0x26baccb2,0x6f42,0x11d4,0xbc,\
  0xe7,0x0,0x80,0xc7,0x3c,0x88,0x81}

Protocol Interface Structure

typedef struct _EFI_METRONOME_ARCH_PROTOCOL {
  EFI_METRONOME_WAIT_FOR_TICK  WaitForTick;
  UINT32                       TickPeriod;
} EFI_METRONOME_ARCH_PROTOCOL;

Parameters

WaitForTick: Waits for a specified number of ticks from a known time source in the platform. See the WaitForTick() function description. The actual time passed between entry of this function and the first tick is between 0 and TickPeriod 100 ns units. To guarantee that at least TickPeriod time has elapsed, wait for two ticks.

TickPeriod: The period of platform’s known time source in 100 ns units. This value on any platform must not exceed 200 µs. The value in this field is a constant that must not be modified after the Metronome architectural protocol is installed. All consumers must treat this as a read-only field.

Description

This protocol provides access to a known time source in the platform to the DXE Foundation. The DXE Foundation uses this known time source to produce DXE Foundation services that require calibrated delays.

12.4.2. EFI_METRONOME_ARCH_PROTOCOL.WaitForTick()¶

Summary

Waits for a specified number of ticks from a known time source in a platform.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_METRONOME_WAIT_FOR_TICK) (
  IN CONST EFI_METRONOME_ARCH_PROTOCOL   *This,
  IN UINT32                              TickNumber
  );

Parameters

This: The EFI_METRONOME_ARCH_PROTOCOL instance.

TickNumber: Number of ticks to wait.

Description

The WaitForTick() function waits for the number of ticks specified by TickNumber from a known time source in the platform. If TickNumber of ticks are detected, then EFI_SUCCESS is returned. The actual time passed between entry of this function and the first tick is between 0 and TickPeriod 100 ns units. If you want to guarantee that at least TickPeriod time has elapsed, wait for two ticks. This function waits for a hardware event to determine when a tick occurs. It is possible for interrupt processing, or exception processing to interrupt the execution of the WaitForTick() function. Depending on the hardware source for the ticks, it is possible for a tick to be missed. This function cannot guarantee that ticks will not be missed. If a timeout occurs waiting for the specified number of ticks, then EFI_TIMEOUT is returned.

Status Codes Returned

Table 12.9 Status Codes Returned¶
EFI_SUCCESS	The wait for the number of ticks specified by `TickNumber` succeeded.
EFI_TIMEOUT	A timeout occurred waiting for the specified number of ticks.

12.5. Monotonic Counter Architectural Protocol¶

12.5.1. EFI_MONOTONIC_COUNTER_ARCH_PROTOCOL¶

Summary

Provides the services required to access the system’s monotonic counter. This protocol must be produced by a runtime DXE driver and may only be consumed by the DXE Foundation and DXE drivers that produce DXE Architectural Protocols.

GUID

#define EFI_MONOTONIC_COUNTER_ARCH_PROTOCOL_GUID \
  {0x1da97072,0xbddc,0x4b30,0x99,\
  0xf1,0x72,0xa0,0xb5,0x6f,0xff,0x2a}

Description

The DXE driver that produces this protocol must be a runtime driver. This driver is responsible for initializing the GetNextHighMonotonicCount() field of the UEFI Runtime Services Table and the GetNextMonotonicCount() field of the UEFI Boot Services Table. See :ref: Services—Boot-Services for details on these services. After the field of the UEFI Runtime Services Table and the field of the UEFI Boot Services Table have been initialized, the driver must install the EFI_MONOTONIC_COUNTER_ARCH_PROTOCOL_GUID on a new handle with a NULL interface pointer. The installation of this protocol informs the DXE Foundation that the monotonic counter services are now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table and the 32-bit CRC of the UEFI Boot Services Table.

12.6. Real Time Clock Architectural Protocol¶

12.6.1. EFI_REAL_TIME_CLOCK_ARCH_PROTOCOL¶

Summary

Provides the services required to access a system’s real time clock hardware. This protocol must be produced by a runtime DXE driver and may only be consumed by the DXE Foundation.

GUID

#define EFI_REAL_TIME_CLOCK_ARCH_PROTOCOL_GUID \
  {0x27CFAC87,0x46CC,0x11d4,0x9A,\
  0x38,0x00,0x90,0x27,0x3F,0xC1,0x4D}

Description

The DXE driver that produces this protocol must be a runtime driver. This driver is responsible for initializing the GetTime() , SetTime(), GetWakeupTime() , and SetWakeupTime() fields of the UEFI Runtime Services Table. See Runtime Capabilities for details on these services. After the four fields of the UEFI Runtime Services Table have been initialized, the driver must install the EFI_REAL_TIME_CLOCK_ARCH_PROTOCOL_GUID on a new handle with a NULL interface pointer. The installation of this protocol informs the DXE Foundation that the real time clock-related services are now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table.

12.7. Reset Architectural Protocol¶

12.7.1. EFI_RESET_ARCH_PROTOCOL¶

Summary

Provides the service required to reset a platform. This protocol must be produced by a runtime DXE driver and may only be consumed by the DXE Foundation.

GUID

#define EFI_RESET_ARCH_PROTOCOL_GUID \
  {0x27CFAC88,0x46CC,0x11d4,0x9A,\
  0x38,0x00,0x90,0x27,0x3F,0xC1,0x4D}

Description

The DXE driver that produces this protocol must be a runtime driver. This driver is responsible for initializing the ResetSystem() field of the UEFI Runtime Services Table. See Runtime Capabilities for details on this service. After this field of the UEFI Runtime Services Table has been initialized, the driver must install the EFI_RESET_ARCH_PROTOCOL_GUID on a new handle with a NULL interface pointer. The installation of this protocol informs the DXE Foundation that the reset system service is now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table.

12.8. Runtime Architectural Protocol¶

The following topics provide a detailed description of the EFI_RUNTIME_ARCH_PROTOCOL . The DXE Foundation contains no runtime code, so all runtime code is contained in DXE Architectural Protocols. This is due to the fact that runtime code must be callable in physical or virtual mode. The Runtime Architectural Protocol contains the UEFI runtime services that are callable only in physical mode. The Runtime Architectural Protocol can be thought of as the runtime portion of the DXE Foundation.

The Runtime Architectural Protocol contains support for transition of runtime drivers from physical mode calling to virtual mode calling.

12.8.1. EFI_RUNTIME_ARCH_PROTOCOL¶

Summary

Allows the runtime functionality of the DXE Foundation to be contained in a separate driver. It also provides hooks for the DXE Foundation to export information that is needed at runtime. As such, this protocol allows services to the DXE Foundation to manage runtime drivers and events. This protocol also implies that the runtime services required to transition to virtual mode, SetVirtualAddressMap() and ConvertPointer() , have been registered into the UEFI Runtime Table in the UEFI System Table. This protocol must be produced by a runtime DXE driver and may only be consumed by the DXE Foundation.

GUID

#define EFI_RUNTIME_ARCH_PROTOCOL_GUID \
  {0xb7dfb4e1,0x52f,0x449f,0x87,\
  0xbe,0x98,0x18,0xfc,0x91,0xb7,0x33}

Protocol Interface Structure

typedef struct _EFI_RUNTIME_ARCH_PROTOCOL {
EFI_LIST_ENTRY          ImageHead;
EFI_LIST_ENTRY          EventHead;
UINTN                   MemoryDescriptorSize;
UINT32                  MemoryDesciptorVersion;
UINTN                   MemoryMapSize;
EFI_MEMORY_DESCRIPTOR   *MemoryMapPhysical;
EFI_MEMORY_DESCRIPTOR   *MemoryMapVirtual;
BOOLEAN                 VirtualMode;
BOOLEAN                 AtRuntime;
} EFI_RUNTIME_ARCH_PROTOCOL;

Parameters

ImageHead: A list of type EFI_RUNTIME_IMAGE_ENTRY where the DXE Foundation inserts items into the list and the Runtime AP consumes the data to implement the SetVirtualAddressMap() call.

EventHead: A list of type EFI_RUNTIME_EVENT_ENTRY where the DXE Foundation inserts items into the list and the Runtime AP consumes the data to implement the SetVirtualAddressMap() call.

MemoryDescriptorSize: Size of a memory descriptor that is returned by GetMemoryMap() . This value is updated by the DXE Foundation.

MemoryDescriptorVersion: Version of a memory descriptor that is return by GetMemoryMap() . This value is updated by the DXE Foundation.

MemoryMapSize: Size of the memory map in bytes contained in MemoryMapPhysical and MemoryMapVirtual . This value is updated by the DXE Foundation when memory for MemoryMapPhysical gets allocated.

MemoryMapPhysical: Pointer to a runtime buffer that contains a copy of the memory map returned via GetMemoryMap() . The memory must be allocated by the DXE Foundation so that it is accounted for in the memory map.

MemoryMapVirtual: Pointer to MemoryMapPhysical that is updated to virtual mode after SetVirtualAddressMap() . The DXE Foundation updates this value when it updates MemoryMapPhysical with the same physical address. The Runtime AP is responsible for converting MemoryMapVirtual to a virtual pointer.

VirtualMode: Boolean that is TRUE if SetVirtualAddressMap() has been called. This field is set by the Runtime AP. When VirtualMode is TRUE MemoryMapVirtual pointer contains the virtual address of the MemoryMapPhysical .

AtRuntime: Boolean that is TRUE if ExitBootServices() has been called. This field is set by the Runtime AP.

//*************************************************************
// EFI_LIST_ENTRY
//*************************************************************
struct _EFI_LIST_ENTRY {
  struct _EFI_LIST_ENTRY   *ForwardLink;
  struct _EFI_LIST_ENTRY   *BackLink;
} EFI_LIST_ENTRY;

ForwardLink: A pointer next node in the doubly linked list.

BackLink: A pointer previous node in the doubly linked list.

//*************************************************************
// EFI_RUNTIME_IMAGE_ENTRY
//*************************************************************
typedef struct {
  VOID              *ImageBase;
  UINT64            ImageSize;
  VOID              *RelocationData;
  EFI_HANDLE        Handle;
  EFI_LIST_ENTRY    Link;
} EFI_RUNTIME_IMAGE_ENTRY;

ImageBase: Start of image that has been loaded in memory. It is a pointer to either the DOS header or PE header of the image. Type EFI_PHYSICAL_ADDRESS is defined in the AllocatePages() UEFI 2.0 specification.

ImageSize: Size in bytes of the image represented by ImageBase .

RelocationData: Information about the fix-ups that were performed on ImageBase when it was loaded into memory. This information is needed when the virtual mode fix-ups are reapplied so that data that has been programmatically updated will not be fixed up. If code updates a global variable the code is responsible for fixing up the variable for virtual mode.

Handle: The ImageHandle passed into ImageBase when it was loaded. See EFI_IMAGE_ENTRY_POINT for the definition of ImageHandle .

Link: Entry for this node in the EFI_RUNTIME_ARCHITECTURE_PROTOCOL.ImageHead list.

//*************************************************************
// EFI_RUNTIME_EVENT_ENTRY
//*************************************************************
typedef struct {
  UINT32                    Type;
  EFI_TPL                   NotifyTpl;
  EFI_EVENT_NOTIFY          NotifyFunction;
  VOID                      *NotifyContext;
  EFI_EVENT                 *Event;
  EFI_LIST_ENTRY            Link;
} EFI_RUNTIME_EVENT_ENTRY;

Note: the (EFI_EVENT*) type of EFI_RUNTIME_EVENT_ENTRY.Event is an historical mistake in the Platform Initialization specification. Implementations are expected to assign EFI_EVENT values (as returned by CreateEvent()), cast to (EFI_EVENT*), to the field, and to cast values read from the field to EFI_EVENT.

Parameters

Type: The same as Type passed into CreateEvent() .

NotifyTpl: The same as NotifyTpl passed into CreateEvent() . Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

NotifyFunction: The same as NotifyFunction passed into CreateEvent() . Type EFI_EVENT_NOTIFY is defined in the CreateEvent() function description.

NotifyContext: The same as NotifyContext passed into CreateEvent() .

Event: The EFI_EVENT returned by CreateEvent() . Event must be in runtime memory. Type EFI_EVENT is defined in the CreateEvent() function description.

Link: Entry for this node in the EFI_RUNTIME_ARCHITECTURE_PROTOCOL.EventHead list.

Description

The DXE driver that produces this protocol must be a runtime driver. This driver is responsible for initializing the SetVirtualAddressMap() and ConvertPointer() fields of the UEFI Runtime Services Table and the CalculateCrc32() field of the UEFI Boot Services Table. See Runtime Capabilities and Services - Boot Services. for details on these services. After the two fields of the UEFI Runtime Services Table and the one field of the UEFI Boot Services Table have been initialized, the driver must install the EFI_RUNTIME_ARCH_PROTOCOL_GUID on a new handle with an EFI_RUNTIME_ARCH_PROTOCOL interface pointer. The installation of this protocol informs the DXE Foundation that the virtual memory services and the 32-bit CRC services are now available, and the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table and the 32-bit CRC of the UEFI Boot Services Table.

All runtime DXE Foundation services are provided by the EFI_RUNTIME_ARCH_PROTOCOL . This includes the support for registering runtime images that must be fixed up again when a transition is made from physical mode to virtual mode. This protocol also supports all events that are defined to fire at runtime. This protocol also contains a CRC-32 function that will be used by the DXE Foundation as a boot service. The EFI_RUNTIME_ARCH_PROTOCOL needs the CRC-32 function when a transition is made from physical mode to virtual mode and the UEFI System Table and UEFI Runtime Table are fixed up with virtual pointers.

12.9. Security Architectural Protocols¶

The EFI_SECURITY_ARCH_PROTOCOL and EFI_SECURITY2_ARCH_PROTOCOL abstract policy actions on image invocation and other security controls from the DXE core to a security driver.

12.9.1. Security Architectural Protocol¶

12.9.1.1. EFI_SECURITY_ARCH_PROTOCOL¶

Summary

Abstracts security-specific functions from the DXE Foundation for purposes of handling GUIDed section encapsulations. This protocol must be produced by a boot service or runtime DXE driver and may only be consumed by the DXE Foundation and any other DXE drivers that need to validate the authentication of files.

See also Security2 Architectural Protocol section below.

GUID

#define EFI_SECURITY_ARCH_PROTOCOL_GUID \
  {0xA46423E3,0x4617,0x49f1,0xB9,\
  0xFF,0xD1,0xBF,0xA9,0x11,0x58,0x39}

Protocol Interface Structure

typedef struct _EFI_SECURITY_ARCH_PROTOCOL {
  EFI_SECURITY_FILE_AUTHENTICATION_STATE
                                FileAuthenticationState;
} EFI_SECURITY_ARCH_PROTOCOL;

Parameters

FileAuthenticationState: This service is called upon fault with respect to the authentication of a section of a file. See the FileAuthenticationState() function description.

Description

The EFI_SECURITY_ARCH_PROTOCOL is used to abstract platform-specific policy from the DXE Foundation. This includes locking flash upon failure to authenticate, attestation logging, and other exception operations.

The driver that produces the EFI_SECURITY_ARCH_PROTOCOL may also optionally install the EFI_SECURITY_POLICY_PROTOCOL_GUID onto a new handle with a NULL interface. The existence of this GUID in the protocol database means that the GUIDed Section Extraction Protocol should authenticate the contents of an Authentication Section. The expectation is that the GUIDed Section Extraction protocol will look for the existence of the EFI_SECURITY_POLICY_PROTOCOL_GUID in the protocol database. If it exists, then the publication thereof is taken as an injunction to attempt an authentication of any section wrapped in an Authentication Section. See the Platform Initialization Specification, Volume 3, for details on the GUIDed Section Extraction Protocol and Authentication Sections.

Addition GUID Definitions

#define EFI_SECURITY_POLICY_PROTOCOL_GUID \

{0x78E4D245,0xCD4D,0x4a05,0xA2,0xBA,0x47,0x43,0xE8,0x6C,0xFC,0xAB}

12.9.1.2. EFI_SECURITY_ARCH_PROTOCOL.FileAuthenticationState()¶

Summary

The DXE Foundation uses this service to check the authentication status of a file. This allows the system to execute a platform-specific policy in response the different authentication status values.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SECURITY_FILE_AUTHENTICATION_STATE) (
  IN CONST EFI_SECURITY_ARCH_PROTOCOL    *This,
  IN UINT32                              AuthenticationStatus,
  IN CONST EFI_DEVICE_PATH_PROTOCOL      *File
  );

Parameters

This: The EFI_SECURITY_ARCH_PROTOCOL instance.

AuthenticationStatus: The authentication type returned from the Section Extraction Protocol. See the Platform Initialization Specification , Volume 3, for details on this type.

File: A pointer to the device path of the file that is being dispatched. This will optionally be used for logging. Type EFI_DEVICE_PATH_PROTOCOL is defined Chapter 8 of the UEFI 2.0 specification.

Description

The EFI_SECURITY_ARCH_PROTOCOL (SAP) is used to abstract platform-specific policy from the DXE Foundation response to an attempt to use a file that returns a given status for the authentication check from the section extraction protocol.

The possible responses in a given SAP implementation may include locking flash upon failure to authenticate, attestation logging for all signed drivers, and other exception operations. The File parameter allows for possible logging within the SAP of the driver.

If File is NULL , then EFI_INVALID_PARAMETER is returned.

If the file specified by File with an authentication status specified by AuthenticationStatus is safe for the DXE Foundation to use, then EFI_SUCCESS is returned.

If the file specified by File with an authentication status specified by AuthenticationStatus is not safe for the DXE Foundation to use under any circumstances, then EFI_ACCESS_DENIED is returned.

If the file specified by File with an authentication status specified by AuthenticationStatus is not safe for the DXE Foundation to use right now, but it might be possible to use it at a future time, then EFI_SECURITY_VIOLATION is returned.

Status Codes Returned

Table 12.10 Status Codes Returned¶
EFI_SUCCESS	The file specified by `File` did authenticate, and the platform policy dictates that the DXE Foundation may use `File`.
EFI_INVALID_PARAMETER	`File` is `NULL`.
EFI_SECURITY_VIOLATION	The file specified by `File` did not authenticate, and the platform policy dictates that `File` should be placed in the untrusted state. A file may be promoted from the untrusted to the trusted state at a future time with a call to the `Trust()` DXE Service.
EFI_ACCESS_DENIED	The file specified by `File` did not authenticate, and the platform policy dictates that `File` should not be used for any purpose.

12.9.2. Security2 Architectural Protocol¶

Summary

Abstracts security-specific functions from the DXE Foundation of UEFI Image Verification, Trusted Computing Group (TCG) measured boot, and User Identity policy for image loading and consoles. This protocol must be produced by a boot service or runtime DXE driver.

This protocol is optional and must be published prior to the EFI_SECURITY_ARCH_PROTOCOL . As a result, the same driver must publish both of these interfaces.

When both Security and Security2 Architectural Protocols are published, LoadImage must use them in accordance with the following rules:

The Security2 protocol must be used on every image being loaded.
The Security protocol must be used after the Securiy2 protocol and only on images that have been read using Firmware Volume protocol.

When only Security architectural protocol is published, LoadImage must use it on every image being loaded.

GUID

#define EFI_SECURITY2_ARCH_PROTOCOL_GUID \
  {0x94ab2f58, 0x1438, 0x4ef1, 0x91, \
  0x52, 0x18, 0x94, 0x1a, 0x3a, 0xe, 0x68}

Protocol Interface Structure

typedef struct _EFI_SECURITY2_ARCH_PROTOCOL {
  EFI_SECURITY2_FILE_AUTHENTICATION   FileAuthentication;
} EFI_SECURITY2_ARCH_PROTOCOL;

Parameters

FileAuthentication: This service is called by DXE Foundation from the LoadImage service to verify and/or measure the image and from the ConnectController service to probe whether a specific device path can be connected.

Description

The EFI_SECURITY2_ARCH_PROTOCOL is used to abstract platform-specific policy from the DXE Foundation. This includes measuring the PE/COFF image prior to invoking, comparing the image against a policy (whether a white-list/black-list of public image verification keys or registered hashes).

12.9.2.1. EFI_SECURITY2_ARCH_PROTOCOL.FileAuthentication()¶

Summary

The DXE Foundation uses this service to measure and/or verify a UEFI image.

Prototype

typedef EFI_STATUS (EFIAPI
*EFI_SECURITY_FILE_AUTHENTICATION_STATE) (
    IN CONST EFI_SECURITY2_ARCH_PROTOCOL *This,
    IN CONST EFI_DEVICE_PATH_PROTOCOL    *DevicePat ,
    IN VOID                              *FileBuffer,
    IN UINTN                             FileSize,
    IN BOOLEAN                           BootPolicy
);

Parameters

This: The EFI_SECURITY2_ARCH_PROTOCOL instance.

DevicePath: A pointer to the device path of the file that is being dispatched or the location that is being connected. This will optionally be used for logging. Type EFI_DEVICE_PATH_PROTOCOL is defined Chapter 9 of the UEFI Specification.

FileBuffer: A pointer to the buffer with the UEFI file image

FileSize: The size of the file.

BootPolicy: A boot policy that was used to call LoadImage() UEFI service. If FileAuthentication() is invoked not from the LoadImage() , BootPolicy must be set to FALSE.

Description

This service abstracts the invocation of Trusted Computing Group (TCG) measured boot, UEFI Secure boot, and UEFI User Identity infrastructure. For the former two, the DXE Foundation invokes the FileAuthentication() with a DevicePath and corresponding image in FileBuffer memory. The TCG measurement code will record the FileBuffer contents into the appropriate PCR. The image verification logic will confirm the integrity and provenance of the image in FileBuffer of length FileSize . The origin of the image will be DevicePath in these cases.

If DevicePath is NULL, the origin of the image is unknown. Implementation of this service must apply to such image security policy that is applied to the image with the least trusted origin.

If the FileBuffer is NULL, the interface will determine if the DevicePath can be connected in order to support the User Identification policy.

Status Codes Returned

Table 12.11 Status Codes Returned¶
EFI_SUCCESS	The file specified by `DevicePath` and non NULL `FileBuffer` did authenticate, and the platform policy dictates that the DXE Foundation may use the file.
EFI_SUCCESS	The device path specified by NULL device path `DevicePath` and non NULL `FileBuffer` did authenticate, and the platform policy dictates that the DXE Foundation may execute the image in `FileBuffer`.
EFI_SUCCESS	`FileBuffer` is NULL and current user has permission to start UEFI device drivers on the device path specified by `DevicePath`.
EFI_SECURITY_VIOLATION	The file specified by `DevicePath` and `FileBuffer` did not authenticate and the platform policy dictates that the file should be placed in the untrusted state. The image has been added tothe file execution table.
EFI_ACCESS_DENIED	The file specified by `File` and `FileBuffer` did not authenticate and the platform policy dictates that the DXE Foundation many not use `File`.
EFI_SECURITY_VIOLATION	`FileBuffer` is NULL and the user has no permission to start UEFI device drivers on the device path specified by `DevicePath`.
EFI_SECURITY_VIOLATION	`FileBuffer` is not NULL and the user has no permission to load drivers from the device path specified by `DevicePath`. The image has been added into the list of the deferred images.

12.10. Timer Architectural Protocol¶

12.10.1. EFI_TIMER_ARCH_PROTOCOL¶

Summary

Used to set up a periodic timer interrupt using a platform specific timer, and a processor-specific interrupt vector. This protocol enables the use of the SetTimer() Boot Service. This protocol must be produce by a boot service or runtime DXE driver and may only be consumed by the DXE Foundation or DXE drivers that produce other DXE Architectural Protocols.

GUID

#define EFI_TIMER_ARCH_PROTOCOL_GUID \
  {0x26baccb3,0x6f42,0x11d4,0xbc,\
  0xe7,0x0,0x80,0xc7,0x3c,0x88,0x81}

Protocol Interface Structure

typedef struct _EFI_TIMER_ARCH_PROTOCOL {
  EFI_TIMER_REGISTER_HANDLER          RegisterHandler;
  EFI_TIMER_SET_TIMER_PERIOD          SetTimerPeriod;
  EFI_TIMER_GET_TIMER_PERIOD          GetTimerPeriod;
  EFI_TIMER_GENERATE_SOFT_INTERRUPT   GenerateSoftInterrupt;
} EFI_TIMER_ARCH_PROTOCOL;

Parameters

RegisterHandler: Registers a handler that will be called each time the timer interrupt fires. See the RegisterHandler() function description. TimerPeriod defines the minimum time between timer interrupts, so TimerPeriod will also be the minimum time between calls to the registered handler.

SetTimerPeriod: Sets the period of the timer interrupt in 100 ns units. See the SetTimerPeriod() function description. This function is optional and may return EFI_UNSUPPORTED . If this function is supported, then the timer period will be rounded up to the nearest supported timer period.

GetTimerPeriod: Retrieves the period of the timer interrupt in 100 ns units. See the GetTimerPeriod() function description.

GenerateSoftInterrupt: Generates a soft timer interrupt that simulates the firing of the timer interrupt. This service can be used to invoke the registered handler if the timer interrupt has been masked for a period of time. See the GenerateSoftInterrupt() function description.

Description

This protocol provides the services to initialize a periodic timer interrupt and to register a handler that is called each time the timer interrupt fires. It may also provide a service to adjust the rate of the periodic timer interrupt. When a timer interrupt occurs, the handler is passed the amount of time that has passed since the previous timer interrupt.

12.10.2. EFI_TIMER_ARCH_PROTOCOL.RegisterHandler()¶

Summary

Registers a handler that is called each timer the timer interrupt fires.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_TIMER_REGISTER_HANDLER) (
  IN CONST EFI_TIMER_ARCH_PROTOCOL  *This,
  IN EFI_TIMER_NOTIFY               NotifyFunction
  );

Parameters

This: The EFI_TIMER_ARCH_PROTOCOL instance.

NotifyFunction: The function to call when a timer interrupt fires. This function executes at EFI_TPL_HIGH_LEVEL . The DXE Foundation will register a handler for the timer interrupt, so it can know how much time has passed. This information is used to signal timer based events. NULL will unregister the handler. Type EFI_TIMER_NOTIFY is defined in “Related Definitions” below.

Description

This function registers the handler NotifyFunction so it is called every time the timer interrupt fires. It also passes the amount of time since the last handler call to the NotifyFunction . If NotifyFunction is NULL , then the handler is unregistered. If the handler is registered, then EFI_SUCCESS is returned. If the processor does not support registering a timer interrupt handler, then EFI_UNSUPPORTED is returned. If an attempt is made to register a handler when a handler is already registered, then EFI_ALREADY_STARTED is returned. If an attempt is made to unregister a handler when a handler is not registered, then EFI_INVALID_PARAMETER is returned. If an error occurs attempting to register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR is returned.

typedef
VOID
(EFIAPI *EFI_TIMER_NOTIFY) (
  IN UINT64  Time
  );

Parameters

Time: Time since the last timer interrupt in 100 ns units. This will typically be TimerPeriod , but if a timer interrupt is missed, and the EFI_TIMER_ARCH_PROTOCOL driver can detect missed interrupts, then Time will contain the actual amount of time since the last interrupt.

Status Codes Returned

Table 12.12 Status Codes Returned¶
EFI_SUCCESS	The timer handler was registered.
EFI_UNSUPPORTED	The platform does not support timer interrupts.
EFI_ALREADY_STARTED	`NotifyFunction` is not `NULL`, and a handler is already registered.
EFI_INVALID_PARAMETER	`NotifyFunction` is `NULL`, and a handler was not previously registered.
EFI_DEVICE_ERROR	The timer handler could not be registered.

12.10.3. EFI_TIMER_ARCH_PROTOCOL.SetTimerPeriod()¶

Summary

Sets the rate of the periodic timer interrupt.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_TIMER_SET_TIMER_PERIOD) (
  IN CONST EFI_TIMER_ARCH_PROTOCOL   *This,
  IN UINT64                          TimerPeriod
  );

Parameters

This: The EFI_TIMER_ARCH_PROTOCOL instance.

TimerPeriod: The rate to program the timer interrupt in 100 ns units. If the timer hardware is not programmable, then EFI_UNSUPPORTED is returned. If the timer is programmable, then the timer period will be rounded up to the nearest timer period that is supported by the timer hardware. If TimerPeriod is set to 0, then the timer interrupts will be disabled.

Description

This function adjusts the period of timer interrupts to the value specified by TimerPeriod . If the timer period is updated, then EFI_SUCCESS is returned. If the timer hardware is not programmable, then EFI_UNSUPPORTED is returned. If an error occurs while attempting to update the timer period, then the timer hardware will be put back in its state prior to this call, and EFI_DEVICE_ERROR is returned. If TimerPeriod is 0, then the timer interrupt is disabled. This is not the same as disabling the processor’s interrupts. Instead, it must either turn off the timer hardware, or it must adjust the interrupt controller so that a processor interrupt is not generated when the timer interrupt fires.

Status Codes Returned

Table 12.13 Status Codes Returned¶
EFI_SUCCESS	The timer period was changed.
EFI_UNSUPPORTED	The platform cannot change the period of the timer interrupt.
EFI_DEVICE_ERROR	The timer period could not be changed due to a device error.

12.10.4. EFI_TIMER_ARCH_PROTOCOL.GetTimerPeriod()¶

Summary

Retrieves the rate of the periodic timer interrupt.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_TIMER_GET_TIMER_PERIOD) (
  IN CONST EFI_TIMER_ARCH_PROTOCOL   *This,
  OUT UINT64                         *TimerPeriod
  );

Parameters

This: The EFI_TIMER_ARCH_PROTOCOL instance.

TimerPeriod: A pointer to the timer period to retrieve in 100 ns units. If 0 is returned, then the timer is currently disabled.

Description

This function retrieves the period of timer interrupts in 100 ns units, returns that value in TimerPeriod , and returns EFI_SUCCESS . If TimerPeriod is NULL , then EFI_INVALID_PARAMETER is returned. If a TimerPeriod of 0 is returned, then the timer is currently disabled.

Status Codes Returned

Table 12.14 Status Codes Returned¶
EFI_SUCCESS	The timer period was returned in `TimerPeriod` .
EFI_INVALID_PARAMETER	`TimerPeriod` is `NULL` .

12.10.5. EFI_TIMER_ARCH_PROTOCOL.GenerateSoftInterrupt()¶

Summary

Generates a soft timer interrupt.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_TIMER_GENERATE_SOFT_INTERRUPT) (
  IN CONST EFI_TIMER_ARCH_PROTOCOL         *This
  );

Parameters

This: The EFI_TIMER_ARCH_PROTOCOL instance.

Description

This function generates a soft timer interrupt. If the platform does not support soft timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned. If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler() service, then a soft timer interrupt will be generated. If the timer interrupt is enabled when this service is called, then the registered handler will be invoked. The registered handler should not be able to distinguish a hardware-generated timer interrupt from a software-generated timer interrupt.

Status Codes Returned

Table 12.15 Status Codes Returned¶
EFI_SUCCESS	The soft timer interrupt was generated.
EFI_UNSUPPORTED	The platform does not support the generation of soft timer interrupts.

12.11. Variable Architectural Protocol¶

12.11.1. EFI_VARIABLE_ARCH_PROTOCOL¶

Summary

Provides the services required to get and set environment variables. This protocol must be produced by a runtime DXE driver and may be consumed only by the DXE Foundation.

GUID

#define EFI_VARIABLE_ARCH_PROTOCOL_GUID \
  {0x1e5668e2,0x8481,0x11d4,0xbc,\
  0xf1,0x0,0x80,0xc7,0x3c,0x88,0x81}

Description

The DXE driver that produces this protocol must be a runtime driver. This driver is responsible for initializing the GetVariable() , GetNextVariableName() , SetVariable() and QueryVariableInfo() fields of the UEFI Runtime Services Table. See Runtime Capabilities for details on these services. After the three fields of the UEFI Runtime Services Table have been initialized, the driver must install the EFI_VARIABLE_ARCH_PROTOCOL_GUID on a new handle with a NULL interface pointer. The installation of this protocol informs the DXE Foundation that the read-only and the volatile environment variable related services are now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table. The full complement of environment variable services are not available until both this protocol and EFI_VARIABLE_WRITE_ARCH_PROTOCOL are installed. DXE drivers that require read-only access or read/write access to volatile environment variables must have this architectural protocol in their dependency expressions. DXE drivers that require write access to nonvolatile environment variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency expressions.

12.12. Variable Write Architectural Protocol¶

12.12.1. EFI_VARIABLE_WRITE_ARCH_PROTOCOL¶

Summary

Provides the services required to set nonvolatile environment variables. This protocol must be produced by a runtime DXE driver and may be consumed only by the DXE Foundation.

GUID

#define EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID \
  {0x6441f818,0x6362,0x4e44,0xb5,\
  0x70,0x7d,0xba,0x31,0xdd,0x24,0x53}

Description

The DXE driver that produces this protocol must be a runtime driver. This driver may update the SetVariable() field of the UEFI Runtime Services Table. See Runtime Capabilities for details on this service. After the UEFI Runtime Services Table has been initialized, the driver must install the EFI_VARIABLE_WRITE_ARCH_PROTOCOL_GUID on a new handle with a NULL interface pointer. The installation of this protocol informs the DXE Foundation that the write services for nonvolatile environment variables are now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table. The full complement of environment variable services are not available until both this protocol and EFI_VARIABLE_ARCH_PROTOCOL are installed. DXE drivers that require read-only access or read/write access to volatile environment variables must have the EFI_VARIABLE_WRITE_ARCH_PROTOCOL in their dependency expressions. DXE drivers that require write access to nonvolatile environment variables must have this architectural protocol in their dependency expressions.

12.13. EFI Capsule Architectural Protocol¶

12.13.1. EFI_CAPSULE_ARCH_PROTOCOL¶

Summary

Provides the services for capsule update.

GUID

#define EFI_CAPSULE_ARCH_PROTOCOL_GUID \
  { 0x5053697e, 0x2cbc, 0x4819, 0x90, \
  0xd9, 0x5, 0x80, 0xde, 0xee, 0x57, 0x54 }

Description

The DXE Driver that produces this protocol must be a runtime driver. The driver is responsible for initializing the CapsuleUpdate() and QueryCapsuleCapabilities() fields of the UEFI Runtime Services Table. After the two fields of the UEFI Runtime Services Table have been initialized, the driver must install the EFI_CAPSULE_ARCH_PROTOCOL_GUID on a new handle with a NULL interface pointer. The installation of this protocol informs the DXE Foundation that the Capsule related services are now available and that the DXE Foundation must update the 32-bit CRC of the UEFI Runtime Services Table.

12.14. Watchdog Timer Architectural Protocol¶

The following topics provide a detailed description of the EFI_WATCHDOG_TIMER_ARCH_PROTOCOL . This protocol is used to implement the Boot Service SetWatchdogTimer() . The watchdog timer may be implemented in software using Boot Services, or it may be implemented with specialized hardware. The protocol provides a service to register a handler when the watchdog timer fires and a service to set the amount of time to wait before the watchdog timer is fired.

12.14.1. EFI_WATCHDOG_TIMER_ARCH_PROTOCOL¶

Summary

Used to program the watchdog timer and optionally register a handler when the watchdog timer fires. This protocol must be produced by a boot service or runtime DXE driver and may be consumed only by the DXE Foundation or DXE drivers that produce other DXE Architectural Protocols. If a platform wishes to perform a platform-specific action when the watchdog timer expires, then the DXE driver that contains the implementation of the EFI_BDS_ARCH_PROTOCOL should use this protocol’s RegisterHandler() service.

GUID

#define EFI_WATCHDOG_TIMER_ARCH_PROTOCOL_GUID \
  {0x665E3FF5,0x46CC,0x11d4,0x9A,\
  0x38,0x00,0x90,0x27,0x3F,0xC1,0x4D}

Protocol Interface Structure

typedef struct _EFI_WATCHDOG_TIMER_ARCH_PROTOCOL {
  EFI_WATCHDOG_TIMER_REGISTER_HANDLER   RegisterHandler;
  EFI_WATCHDOG_TIMER_SET_TIMER_PERIOD   SetTimerPeriod;
  EFI_WATCHDOG_TIMER_GET_TIMER_PERIOD   GetTimerPeriod;
} EFI_WATCHDOG_TIMER_ARCH_PROTOCOL;

Parameters

RegisterHandler: Registers a handler that is invoked when the watchdog timer fires. See the RegisterHandler() function description.

SetTimerPeriod: Sets the amount of time in 100 ns units to wait before the watchdog timer is fired. See the SetTimerPeriod() function description. If this function is supported, then the watchdog timer period will be rounded up to the nearest supported watchdog timer period.

GetTimerPeriod: Retrieves the amount of time in 100 ns units that the system will wait before the watchdog timer is fired. See the GetTimerPeriod() function description.

Description

This protocol provides the services required to implement the Boot Service SetWatchdogTimer() . It provides a service to set the amount of time to wait before firing the watchdog timer, and it also provides a service to register a handler that is invoked when the watchdog timer fires. This protocol can implement the watchdog timer by using the event and timer Boot Services, or it can make use of custom hardware. When the watchdog timer fires, control will be passed to a handler if one has been registered. If no handler has been registered, or the registered handler returns, then the system will be reset by calling the Runtime Service ResetSystem().

12.14.2. EFI_WATCHDOG_TIMER_ARCH_PROTOCOL.RegisterHandler()¶

Summary

Registers a handler that is to be invoked when the watchdog timer fires.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_WATCHDOG_TIMER_REGISTER_HANDLER) (
  IN CONST EFI_WATCHDOG_TIMER_ARCH_PROTOCOL  *This,
  IN EFI_WATCHDOG_TIMER_NOTIFY               NotifyFunction
  );

Parameters

This: The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.

NotifyFunction: The function to call when the watchdog timer fires. If this is NULL , then the handler will be unregistered. Type EFI_WATCHDOG_TIMER_NOTIFY is defined in “Related Definitions” below.

Description

This function registers a handler that is to be invoked when the watchdog timer fires. By default, EFI_WATCHDOG_TIMER_ARCH_PROTOCOL will call the Runtime Service ResetSystem() when the watchdog timer fires. If a NotifyFunction is registered, then NotifyFunction will be called before the Runtime Service ResetSystem() is called. If NotifyFunction is NULL , then the watchdog handler is unregistered. If a watchdog handler is registered, then EFI_SUCCESS is returned. If an attempt is made to register a handler when a handler is already registered, then EFI_ALREADY_STARTED is returned. If an attempt is made to uninstall a handler when a handler is not installed, then return EFI_INVALID_PARAMETER .

typedef
VOID
(EFIAPI *EFI_WATCHDOG_TIMER_NOTIFY) (
  IN UINT64 Time
  );

Time: The time in 100 ns units that has passed since the watchdog timer was armed. For the notify function to be called, this must be greater than TimerPeriod .

Status Codes Returned

Table 12.16 Status Codes Returned¶
EFI_SUCCESS	The watchdog timer handler was registered or unregistered
EFI_ALREADY_STARTED	`NotifyFunction` is not `NULL`, and a handler is already registered.
EFI_INVALID_PARAMETER	`NotifyFunction` is `NULL`, and a handler was not previously registered.

12.14.3. EFI_WATCHDOG_TIMER_ARCH_PROTOCOL.SetTimerPeriod()¶

Summary

Sets the amount of time in the future to fire the watchdog timer.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_WATCHDOG_TIMER_SET_TIMER_PERIOD) (
  IN CONST EFI_WATCHDOG_TIMER_ARCH_PROTOCOL *This,
  IN UINT64 TimerPeriod
  );

Parameters

This: The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.

TimerPeriod: The amount of time in 100 ns units to wait before the watchdog timer is fired. If TimerPeriod is zero, then the watchdog timer is disabled.

Description

This function sets the amount of time to wait before firing the watchdog timer to TimerPeriod 100 ns units. If TimerPeriod is zero, then the watchdog timer is disabled.

Status Codes Returned

Table 12.17 Status Codes Returned¶
EFI_SUCCESS	The watchdog timer has been programmed to fire in `Time` 100 ns units.
EFI_DEVICE_ERROR	A watchdog timer could not be programmed due to a device error.

12.14.4. EFI_WATCHDOG_TIMER_ARCH_PROTOCOL.GetTimerPeriod()¶

Retrieves the amount of time in 100 ns units that the system will wait before firing the watchdog timer.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_WATCHDOG_TIMER_GET_TIMER_PERIOD) (
  IN CONST EFI_WATCHDOG_TIMER_ARCH_PROTOCOL  *This,
  OUT UINT64                                 *TimerPeriod
  );

Parameters

This: The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.

TimerPeriod: A pointer to the amount of time in 100 ns units that the system will wait before the watchdog timer is fired. If TimerPeriod of zero is returned, then the watchdog timer is disabled.

Description

This function retrieves the amount of time the system will wait before firing the watchdog timer. This period is returned in TimerPeriod , and EFI_SUCCESS is returned. If TimerPeriod is NULL , then EFI_INVALID_PARAMETER is returned.

Status Codes Returned

Table 12.18 Status Codes Returned¶
EFI_SUCCESS	The amount of time that the system will wait before firing the watchdog timer was returned in `TimerPeriod`.
EFI_INVALID_PARAMETER	`TimerPeriod` is `NULL`.