EFI RUNTIME SERVICES

From PhoenixWiki

Revision as of 23:46, 25 August 2009 by Tim Lewis (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

Contains a table header and pointers to all of the runtime services.

Contents

Prototype

typedef struct {
  EFI_TABLE_HEADER               Hdr;
  EFI_GET_TIME                   GetTime;
  EFI_SET_TIME                   SetTime;
  EFI_GET_WAKEUP_TIME            GetWakeupTime;
  EFI_SET_WAKEUP_TIME            SetWakeupTime;
  EFI_SET_VIRTUAL_ADDRESS_MAP    SetVirtualAddressMap;
  EFI_CONVERT_POINTER            ConvertPointer;
  EFI_GET_VARIABLE               GetVariable;
  EFI_GET_NEXT_VARIABLE_NAME     GetNextVariableName;
  EFI_SET_VARIABLE               SetVariable;
  EFI_GET_NEXT_HIGH_MONO_COUNT   GetNextHighMonotonicCount;
  EFI_RESET_SYSTEM               ResetSystem;
  EFI_UPDATE_CAPSULE             UpdateCapsule;
  EFI_QUERY_CAPSULE_CAPABILITIES QueryCapsuleCapabilities;
  EFI_QUERY_VARIABLE_INFO        QueryVariableInfo;
} EFI_RUNTIME_SERVICES;

Parameters

Member Description
Hdr The table header for the EFI Runtime Services Table. This header contains the EFI_RUNTIME_SERVICES_ SIGNATURE and EFI_RUNTIME_SERVICES_REVISION values along with the size of the EFI_RUNTIME_SERVICES structure and a 32-bit CRC to verify that the contents of the EFI Runtime Services Table are valid.
GetTime Returns the current time and date, and the time-keeping capabilities of the platform.
SetTime Sets the current local time and date information.
GetWakeupTime Returns the current wakeup alarm clock setting.
SetWakeupTime Sets the system wakeup alarm clock time.
SetVirtualAddressMap Used by an OS loader to convert from physical addressing to virtual addressing.
ConvertPointer Used by EFI components to convert internal pointers when switching to virtual addressing.
GetVariable Returns the value of a variable.
GetNextVariableName Enumerates the current variable names.
SetVariable Sets the value of a variable.
GetNextHighMonotonicCount Returns the next high 32 bits of the platform’s monotonic counter.
ResetSystem Resets the entire platform.
UpdateCapsule Passes capsules to the firmware with both virtual and physical mapping.
QueryCapsuleCapabilities Returns if the capsule can be supported via UpdateCapsule().
QueryVariableInfo Returns information about the EFI variable store.

Related Definitions

#define EFI_RUNTIME_SERVICES_SIGNATURE 0x56524553544e5552 
#define EFI_RUNTIME_SERVICES_REVISION  EFI_SPECIFICATION_VERSION

Description

UEFI uses the EFI Runtime Services Table, which contains a table header and pointers to all of the runtime services. The definition for this table is shown in the following code fragments. Unlike the EFI Boot Services Table, this table, and the function pointers it contains are valid after the operating system has taken control of the platform with a call to ExitBootServices(). If a call to SetVirtualAddressMap() is made by the OS, then the function pointers in this table are fixed up to point to the new virtually mapped entry points.


Runtime Services Rules and Restrictions

All of the Runtime Services may be called with interrupts enabled if desired. The Runtime Service functions will internally disable interrupts when it is required to protect access to hardware resources. The interrupt enable control bit will be returned to its entry state after the access to the critical hardware resources is complete. All callers of Runtime Services are restricted from calling the same or certain other Runtime Service functions prior to the completion and return of a previous Runtime Service call. These restrictions apply to:

  • Runtime Services that have been interrupted
  • Runtime Services that are active on another processor.

Callers are prohibited from using certain other services from another processor or on the same processor following an interrupt as specified in Table 27. For this table ‘Busy’ is defined as the state when a Runtime Service has been entered and has not returned to the caller.

The consequence of a caller violating these restrictions is undefined except for certain special cases described below.

Table: Rules for Reentry Into Runtime Services

If previous call is busy in Forbidden to call
Any SetVirtualAddressMap()
ConvertPointer() ConvertPointer()
SetVariable(), UpdateCapsule(), SetTime(), SetWakeupTime(),GetNextHighMonotonicCount() ResetSystem()
GetVariable(), GetNextVariableName(), SetVariable(), QueryVariableInfo(), UpdateCapsule(), QueryCapsuleCapabilities(), GetNextHighMonotonicCount() GetVariable(), GetNextVariableName(), SetVariable(), QueryVariableInfo(), UpdateCapsule(), QueryCapsuleCapabilities(), GetNextHighMonotonicCount()
GetTime(), SetTime(), GetWakeupTime(), SetWakeupTime() GetTime(), SetTime(), GetWakeupTime(), SetWakeupTime()

Exception for Machine Check, INIT, and NMI.

Certain asynchronous events (e.g., NMI on IA-32 and x64 systems, Machine Check and INIT on Itanium systems) can not be masked and may occur with any setting of interrupt enabled. These events also may require OS level handler's involvement that may involve the invocation of some of the runtime services (see below).

If SetVirtualAddressMap() has been called, all calls to runtime services after Machine Check, INIT, or NMI, must be made using the virtual address map set by that call.

Machine Check is recoverable, the OS level handler must follow the normal restrictions in the table above.

If the OS determines that the Machine Check is non-recoverable, the OS level handler may ignore the normal restrictions and may invoke the runtime services described in Table 28 even in the case where a previous call was busy. The system firmware will honor the new runtime service call(s) and the operation of the previous interrupted call is not guaranteed. Any interrupted runtime functions will not be restarted.

The INIT and NMI events follow the same restrictions. Note: On Itanium systems, the OS Machine Check Handler must not call ResetSystem(). If a reset is required, the OS Machine Check Handler may request SAL to reset upon return to SAL_CHECK.

The platform implementations are required to clear any runtime services in progress in order to enable the OS handler to invoke these runtime services even in the case where a previous call was busy. In this case, the proper operation of the original interrupted call is not guaranteed.

Function Called after Machine Check, INIT and NMI
GetTime() Yes, even if previously busy.
GetVariable() Yes, even if previously busy
GetNextVariableName() Yes, even if previously busy
QueryVariableInfo() Yes, even if previously busy
SetVariable() Yes, even if previously busy
UpdateCapsule() Yes, even if previously busy
QueryCapsuleCapabilities() Yes, even if previously busy
ResetSystem() Yes, even if previously busy

Members

GetNextVariableName()

Enumerates the current variable names.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_GET_NEXT_VARIABLE_NAME)(
  IN OUT UINTN    *VariableNameSize,
  IN OUT CHAR16   *VariableName,
  IN OUT EFI_GUID *VendorGuid
  );

Parameters

Parameter Description
VariableNameSize The size of the VariableName buffer.
VariableName On input, supplies the last VariableName that was returned by GetNextVariableName(). On output, returns the Null-terminated string of the current variable.
VendorGuid On input, supplies the last VendorGuid that was returned by GetNextVariableName(). On output, returns the VendorGuid of the current variable.

Description
GetNextVariableName() is called multiple times to retrieve the VariableName and VendorGuid of all variables currently available in the system. On each call to GetNextVariableName() the previous results are passed into the interface, and on output the interface returns the next variable name data. When the entire variable list has been returned, the error EFI_NOT_FOUND is returned.

Note that if EFI_BUFFER_TOO_SMALL is returned, the VariableName buffer was too small for the next variable. When such an error occurs, the VariableNameSize is updated to reflect the size of buffer needed. In all cases when calling GetNextVariableName() the VariableNameSize must not exceed the actual buffer size that was allocated for VariableName.

To start the search, a Null-terminated string is passed in VariableName; that is, VariableName is a pointer to a Null Unicode character. This is always done on the initial call to GetNextVariableName(). When VariableName is a pointer to a Null Unicode character, VendorGuid is ignored. GetNextVariableName() cannot be used as a filter to return variable names with a specific GUID. Instead, the entire list of variables must be retrieved, and the caller may act as a filter if it chooses. Calls to SetVariable() between calls to GetNextVariableName() may produce unpredictable results. Passing in a VariableName parameter that is neither a Null-terminated string nor a value that was returned on the previous call to GetNextVariableName() may also produce unpredictable results.

Once ExitBootServices() is performed, variables that are only visible during boot services will no longer be returned. To obtain the data contents or attribute for a variable returned by GetNextVariableName(), the GetVariable() interface is used.

Status Codes Returned

Status Code Description
EFI_SUCCESS The function completed successfully.
EFI_NOT_FOUND The next variable was not found.
EFI_BUFFER_TOO_SMALL The VariableNameSize is too small for the result. VariableNameSize has been updated with the size needed to complete the request.
EFI_INVALID_PARAMETER VariableNameSize is NULL.
EFI_INVALID_PARAMETER VariableName is NULL.
EFI_INVALID_PARAMETER VendorGuid is NULL.
EFI_DEVICE_ERROR The variable name could not be retrieved due to a hardware error.

GetVariable()

Returns the value of a variable.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_GET_VARIABLE)(
  IN     CHAR16   *VariableName,
  IN     EFI_GUID *VendorGuid,
  OUT    UINT32   *Attributes OPTIONAL,
  IN OUT UINTN    *DataSize,
  OUT    VOID     *Data
);

Parameters

Parameter Description
VariableName A Null-terminated Unicode string that is the name of the vendor’s variable.
VendorGuid A unique identifier for the vendor.
Attributes If not NULL, a pointer to the memory location to return the attributes bitmask for the variable.
DataSize On input, the size in bytes of the return Data buffer. On output the size of data returned in Data.
Data The buffer to return the contents of the variable. Related Definitions

Related Definitions

#define EFI_VARIABLE_NON_VOLATILE               0x00000001
#define EFI_VARIABLE_BOOTSERVICE_ACCESS         0x00000002
#define EFI_VARIABLE_RUNTIME_ACCESS             0x00000004
#define EFI_VARIABLE_HARDWARE_ERROR_RECORD      0x00000008
#define EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS 0x00000010

Description
Each vendor may create and manage its own variables without the risk of name conflicts by using a unique VendorGuid. When a variable is set its Attributes are supplied to indicate how the data variable should be stored and maintained by the system. The attributes affect when the variable may be accessed and volatility of the data. Any attempts to access a variable that does not have the attribute set for runtime access will yield the EFI_NOT_FOUND error.

If the Data buffer is too small to hold the contents of the variable, the error EFI_BUFFER_TOO_SMALL is returned and DataSize is set to the required buffer size to obtain the data.

Status Codes Returned

Status Code Description
EFI_SUCCESS The function completed successfully.
EFI_NOT_FOUND The variable was not found.
EFI_BUFFER_TOO_SMALL The DataSize is too small for the result. DataSize has been updated with the size needed to complete the request.
EFI_INVALID_PARAMETER VariableName is NULL.
EFI_INVALID_PARAMETER VendorGuid is NULL.
EFI_INVALID_PARAMETER DataSize is NULL.
EFI_INVALID_PARAMETER The DataSize is not too small and Data is NULL.
EFI_DEVICE_ERROR The variable could not be retrieved due to a hardware error.
EFI_SECURITY_VIOLATION The variable could not be retrieved due to an authentication failure.

SetVariable()

Sets the value of a variable.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SET_VARIABLE)(
  IN CHAR16   *VariableName, 
  IN EFI_GUID *VendorGuid,
  IN UINT32   Attributes,
  IN UINTN    DataSize,
  IN VOID     *Data
  );

Parameters

Parameter Description
VariableName A Null-terminated Unicode string that is the name of the vendor’s variable. Each VariableName is unique for each VendorGuid. VariableName must contain 1 or more Unicode characters. If VariableName is an empty Unicode string, then EFI_INVALID_PARAMETER is returned.
VendorGuid A unique identifier for the vendor.
Attributes Attributes bitmask to set for the variable. Refer to the GetVariable() function description.
DataSize The size in bytes of the Data buffer. A size of zero causes the variable to be deleted.
Data The contents for the variable.


Description
Variables are stored by the firmware and may maintain their values across power cycles. Each vendor may create and manage its own variables without the risk of name conflicts by using a unique VendorGuid.

Each variable has Attributes that define how the firmware stores and maintains the data value. If the EFI_VARIABLE_NON_VOLATILE attribute is not set, the firmware stores the variable in normal memory and it is not maintained across a power cycle. Such variables are used to pass information from one component to another. An example of this is the firmware’s language code support variable. It is created at firmware initialization time for access by EFI components that may need the information, but does not need to be backed up to nonvolatile storage.

EFI_VARIABLE_NON_VOLATILE variables are stored in fixed hardware that has a limited storage capacity; sometimes a severely limited capacity. Software should only use a nonvolatile variable when absolutely necessary. In addition, if software uses a nonvolatile variable it should use a variable that is only accessible at boot services time if possible. A variable must contain one or more bytes of Data. Using SetVariable() with a DataSize of zero causes the entire variable to be deleted. The space consumed by the deleted variable may not be available until the next power cycle.

The Attributes have the following usage rules:

  • Storage attributes are only applied to a variable when creating the variable. If a preexisting variable is rewritten with different attributes, the result is indeterminate and may vary between implementations. The correct method of changing the attributes of a variable is to delete the variable and recreate it with different attributes. There is one exception to this rule. If a preexisting variable is rewritten with no access attributes specified, the variable will be deleted.
  • Setting a data variable with no access attributes, or zero DataSize specified, causes it to be deleted.
  • Runtime access to a data variable implies boot service access. Attributes that have EFI_VARIABLE_RUNTIME_ACCESS set must also have EFI_VARIABLE_BOOTSERVICE_ACCESS set. The caller is responsible for following this rule.
  • Once ExitBootServices() is performed, data variables that did not have EFI_VARIABLE_RUNTIME_ACCESS set are no longer visible to GetVariable().
  • Once ExitBootServices() is performed, only variables that have EFI_VARIABLE_RUNTIME_ACCESS and EFI_VARIABLE_NON_VOLATILE set can be set with SetVariable(). Variables that have runtime access but that are not nonvolatile are read-only data variables once ExitBootServices() is performed.

The only rules the firmware must implement when saving a nonvolatile variable is that it has actually been saved to nonvolatile storage before returning EFI_SUCCESS, and that a partial save is not performed. If power fails during a call to SetVariable() the variable may contain its previous value, or its new value. In addition there is no read, write, or delete security protection.

AuthInfo is a WIN_CERTIFICATE using the wCertificateType WIN_CERTIFICATE_UEFI_GUID and the CertType EFI_CERT_TYPE_RSA2048_SHA256.

If the EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS is set, then the Data buffer should begin with an authentication descriptor prior to the data payload and DataSize should reflect the the data.and descriptor size. The caller shall digest the Monotonic Count value and the associated data for the variable update using the SHA-256 1-way hash algorithm. The ensuing the 32-byte digest will be signed using the private key associated w/ the public/private 2048-bit RSA key-pair. The WIN_CERTIFICATE shall be used to describe the signature of the Variable data *Data. In addition, the signature will also include the MonotonicCount value to guard against replay attacks.

From the WIN_CERTIFICATE, the HashType will be EFI_SHA256_HASH and the ANYSIZE_ARRAY of Signature will be 256. RSASSA-PSS padding will be used during the signature block [see RSA]. The WIN_CERTIFICATE_PKCS1_15 could have been used but was not for the following reason: There are possibly various different principals to create authenticated variables, so the public key corresponding to a given principal is added to the EFI_CERT_BLOCK_RSA_2048_SHA256 within the WIN_CERTIFICATE. This does not lend cryptographic value so much as it provides something akin to a handle for the platform firmware to use during its verification operation (see security model picture).

The MonotonicCount value must be strictly greater for each successive variable update operation. This allows for ensuring freshness of the update operation and defense against replay attacks (i.e., if someone had the value of a former AuthInfo, they could not re-invoke that same update session).

Status Codes Returned

Status Code Description
EFI_SUCCESS The firmware has successfully stored the variable and its data as defined by the Attributes.
EFI_INVALID_PARAMETER An invalid combination of attribute bits was supplied, or the DataSize exceeds the maximum allowed.
EFI_INVALID_PARAMETER VariableName is an empty Unicode string.
EFI_OUT_OF_RESOURCES Not enough storage is available to hold the variable and its data.
EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.
EFI_WRITE_PROTECTED The variable in question is read-only.
EFI_WRITE_PROTECTED The variable in question cannot be deleted.
EFI_SECURITY_VIOLATION The variable could not be retrieved due to an authentication failure.
EFI_NOT_FOUND The variable trying to be updated or deleted was not found.

SetVirtualAddressMap()

Changes the runtime addressing mode of EFI firmware from physical to virtual.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SET_VIRTUAL_ADDRESS_MAP)(
  IN UINTN                 MemoryMapSize,
  IN UINTN                 DescriptorSize,
  IN UINT32                DescriptorVersion,
  IN EFI_MEMORY_DESCRIPTOR *VirtualMap
  );

Parameters

Parameter Description
MemoryMapSize The size in bytes of VirtualMap.
DescriptorSize The size in bytes of an entry in the VirtualMap.
DescriptorVersion The version of the structure entries in VirtualMap.
VirtualMap An array of memory descriptors which contain new virtual address mapping information for all runtime ranges.

Description
The SetVirtualAddressMap() function is used by the OS loader. The function can only be called at runtime, and is called by the owner of the system’s memory map. I.e., the component which called ExitBootServices(). All events of type EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE must be signaled before SetVirtualAddressMap() returns.

This call changes the addresses of the runtime components of the EFI firmware to the new virtual addresses supplied in the VirtualMap. The supplied VirtualMap must provide a new virtual address for every entry in the memory map at ExitBootServices() that is marked as being needed for runtime usage. All of the virtual address fields in the VirtualMap must be aligned on 4 KB boundaries.

The call to SetVirtualAddressMap() must be done with the physical mappings. On successful return from this function, the system must then make any future calls with the newly assigned virtual mappings. All address space mappings must be done in accordance to the cacheability flags as specified in the original address map.

When this function is called, all events that were registered to be signaled on an address map change are notified. Each component that is notified must update any internal pointers for their new addresses. This can be done with the ConvertPointer() function. Once all events have been notified, the EFI firmware reapplies image “fix-up” information to virtually relocate all runtime images to their new addresses. In addition, all of the fields of the EFI Runtime Services Table except SetVirtualAddressMap and ConvertPointer must be converted from physical pointers to virtual pointers using the ConvertPointer() service. The SetVirtualAddressMap() and ConvertPointer() services are only callable in physical mode, so they do not need to be converted from physical pointers to virtual pointers.

Several fields of the EFI System Table must be converted from physical pointers to virtual pointers using the ConvertPointer() service. These fields include FirmwareVendor, RuntimeServices, and ConfigurationTable. Because contents of both the EFI Runtime Services Table and the EFI System Table are modified by this service, the 32-bit CRC for the EFI_RUNTIME_SERVICES and the EFI_SYSTEM_TABLE must be recomputed.

A virtual address map may only be applied one time. Once the runtime system is in virtual mode, calls to this function return EFI_UNSUPPORTED.

Status Codes Returned

Status Code Description
EFI_SUCCESS The virtual address map has been applied.
EFI_UNSUPPORTED EFI firmware is not at runtime, or the EFI firmware is already in virtual address mapped mode.
EFI_INVALID_PARAMETER DescriptorSize or DescriptorVersion is invalid.
EFI_NO_MAPPING A virtual address was not supplied for a range in the memory map that requires a mapping.
EFI_NOT_FOUND A virtual address was supplied for an address that is not found in the memory map.

GetTime()

Returns the current time and date information, and the time-keeping capabilities of the hardware platform.

Prototype

typedef
EFI_STATUS
GetTime (
  OUT EFI_TIME              *Time,
  OUT EFI_TIME_CAPABILITIES *Capabilities OPTIONAL
  );

Parameters

Parameter Descriptin Time A pointer to storage to receive a snapshot of the current time.
Capabilities An optional pointer to a buffer to receive the real time clock device’s capabilities.


Description
The GetTime() function returns a time that was valid sometime during the call to the function. While the returned EFI_TIME structure contains TimeZone and Daylight savings time information, the actual clock does not maintain these values. The current time zone and daylight saving time information returned by GetTime() are the values that were last set via SetTime().

The GetTime() function should take approximately the same amount of time to read the time each time it is called. All reported device capabilities are to be rounded up.

During runtime, if a PC-AT CMOS device is present in the platform the caller must synchronize access to the device before calling GetTime().

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_INVALID_PARAMETER Time is NULL.
EFI_DEVICE_ERROR The time could not be retrieved due to a hardware error.

SetTime()

Sets the current local time and date information.

Prototype

typedef
EFI_STATUS
SetTime (
  IN EFI_TIME *Time
  );

Parameters

Parameter Description
Time A pointer to the current time. Full error checking is performed on the different fields of the EFI_TIME structure (refer to the EFI_TIME definition in the GetTime() function description for full details), and EFI_INVALID_PARAMETER is returned if any field is out of range.

Description
The SetTime() function sets the real time clock device to the supplied time, and records the current time zone and daylight savings time information. The SetTime() function is not allowed to loop based on the current time. For example, if the device does not support a hardware reset for the sub-resolution time, the code is not to implement the feature by waiting for the time to wrap.

During runtime, if a PC-AT CMOS device is present in the platform the caller must synchronize access to the device before calling SetTime().

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_INVALID_PARAMETER A time field is out of range.
EFI_DEVICE_ERROR The time could not be set due to a hardware error.

GetWakeupTime()

Returns the current wakeup alarm clock setting.

Prototype

typedef
EFI_STATUS
GetWakeupTime (
  OUT BOOLEAN  *Enabled,
  OUT BOOLEAN  *Pending,
  OUT EFI_TIME *Time
  );

Parameters

Parameter Description
Enabled Indicates if the alarm is currently enabled or disabled.
Pending Indicates if the alarm signal is pending and requires acknowledgement.
Time The current alarm setting.

Description
The alarm clock time may be rounded from the set alarm clock time to be within the resolution of the alarm clock device. The resolution of the alarm clock device is defined to be one second.

During runtime, if a PC-AT CMOS device is present in the platform the caller must synchronize access to the device before calling GetWakeupTime().

Status Codes Returned

Status Code Description
EFI_SUCCESS The alarm settings were returned.
EFI_INVALID_PARAMETER Enabled is NULL.
EFI_INVALID_PARAMETER Pending is NULL.
EFI_INVALID_PARAMETER Time is NULL.
EFI_DEVICE_ERROR The wakeup time could not be retrieved due to a hardware error.
EFI_UNSUPPORTED A wakeup timer is not supported on this platform.

SetWakeupTime()

Sets the system wakeup alarm clock time.

Prototype

typedef
EFI_STATUS
SetWakeupTime (
  IN BOOLEAN  Enable,
  IN EFI_TIME *Time OPTIONAL
  );

Parameters

Parameter Description
Enable Enable or disable the wakeup alarm.
Time If Enable is TRUE, the time to set the wakeup alarm for. If Enable is FALSE, then this parameter is optional, and may be NULL.

Description
Setting a system wakeup alarm causes the system to wake up or power on at the set time. When the alarm fires, the alarm signal is latched until it is acknowledged by calling SetWakeupTime() to disable the alarm. If the alarm fires before the system is put into a sleeping or off state, since the alarm signal is latched the system will immediately wake up. If the alarm fires while the system is off and there is insufficient power to power on the system, the system is powered on when power is restored. For an ACPI-aware operating system, this function only handles programming the wakeup alarm for the desired wakeup time. The operating system still controls the wakeup event as it normally would through the ACPI Power Management register set. The resolution for the wakeup alarm is defined to be 1 second.

During runtime, if a PC-AT CMOS device is present in the platform the caller must synchronize access to the device before calling SetWakeupTime().

Status Codes Returned

Status Code Description
EFI_SUCCESS If Enable is TRUE, then the wakeup alarm was enabled. If Enable is FALSE, then the wakeup alarm was disabled.
EFI_INVALID_PARAMETER A time field is out of range.
EFI_DEVICE_ERROR The wakeup time could not be set due to a hardware error.
EFI_UNSUPPORTED A wakeup timer is not supported on this platform.

ConvertPointer()

Determines the new virtual address that is to be used on subsequent memory accesses.

Prototype

typedef
EFI_STATUS
ConvertPointer (
  IN UINTN DebugDisposition,
  IN VOID  **Address
  );

Parameters

Parameter Description
DebugDisposition Supplies type information for the pointer being converted.
#define EFI_OPTIONAL_PTR 0x00000001
Address A pointer to a pointer that is to be fixed to be the value needed for the new virtual address mappings being applied.

Description
The ConvertPointer() function is used by an EFI component during the SetVirtualAddressMap() operation. ConvertPointer()must be called using physical address pointers during the execution of SetVirtualAddressMap().

The ConvertPointer() function updates the current pointer pointed to by Address to be the proper value for the new address map. Only runtime components need to perform this operation. The CreateEvent() function is used to create an event that is to be notified when the address map is changing. All pointers the component has allocated or assigned must be updated.

If the EFI_OPTIONAL_PTR flag is specified, the pointer being converted is allowed to be NULL. Once all components have been notified of the address map change, firmware fixes any compiled in pointers that are embedded in any runtime image.

Status Codes Returned

Status Code Description
EFI_SUCCESS The pointer pointed to by Address was modified.
EFI_NOT_FOUND The pointer pointed to by Address was not found to be part of the current memory map. This is normally fatal.
EFI_INVALID_PARAMETER Address is NULL.
EFI_INVALID_PARAMETER *Address is NULL and DebugDisposition does not have the EFI_OPTIONAL_PTR bit set.

ResetSystem()

Resets the entire platform.

Prototype

typedef
VOID
ResetSystem (
  IN EFI_RESET_TYPE ResetType,
  IN EFI_STATUS     ResetStatus,
  IN UINTN          DataSize,
  IN VOID           *ResetData OPTIONAL
  );

Parameters
ResetType The type of reset to perform. ResetStatus The status code for the reset. If the system reset is part of a normal operation, the status code would be EFI_SUCCESS. If the system reset is due to some type of failure the most appropriate EFI Status code would be used. DataSize The size, in bytes, of ResetData. ResetData For a ResetType of EfiResetCold, EfiResetWarm, or EfiResetShutdown the data buffer starts with a Null-terminated Unicode string, optionally followed by additional binary data. The string is a description that the caller may use to further indicate the reason for the system reset. ResetData is only valid if ResetStatus is something other then EFI_SUCCESS. This pointer must be a physical address. For a ResetType of EfiRestUpdate the data buffer also starts with a Null-terminated string that is followed by a physical VOID * to an EFI_CAPSULE_HEADER (UEFI 2.10+).

Description
The ResetSystem()function resets the entire platform, including all processors and devices, and reboots the system.

Calling this interface with ResetType of EfiResetCold causes a system-wide reset. This sets all circuitry within the system to its initial state. This type of reset is asynchronous to system operation and operates without regard to cycle boundaries. EfiResetCold is tantamount to a system power cycle.

Calling this interface with ResetType of EfiResetWarm causes a system-wide initialization. The processors are set to their initial state, and pending cycles are not corrupted. If the system does not support this reset type, then an EfiResetCold must be performed.

Calling this interface with ResetType of EfiResetShutdown causes the system to enter a power state equivalent to the ACPI G2/S5 or G3 states. If the system does not support this reset type, then when the system is rebooted, it should exhibit the EfiResetCold attributes.

The platform may optionally log the parmeters from any non-normal reset that occurs.

The ResetSystem() function does not return.

GetNextHighMonotonicCount()

Returns the next high 32 bits of the platform’s monotonic counter.

Prototype

typedef
EFI_STATUS
GetNextHighMonotonicCount (
  OUT UINT32 *HighCount
  );

Parameters

Parameter Description
HighCount Pointer to returned value.

Description
The GetNextHighMonotonicCount() function returns the next high 32 bits of the platform’s monotonic counter.

The platform’s monotonic counter is comprised of two 32-bit quantities: the high 32 bits and the low 32 bits. During boot service time the low 32-bit value is volatile: it is reset to zero on every system reset and is increased by 1 on every call to GetNextMonotonicCount(). The high 32-bit value is nonvolatile and is increased by 1 whenever the system resets or whenever the low 32-bit count (returned by GetNextMonoticCount()) overflows.

The GetNextMonotonicCount() function is only available at boot services time. If the operating system wishes to extend the platform monotonic counter to runtime, it may do so by utilizing GetNextHighMonotonicCount(). To do this, before calling ExitBootServices() the operating system would call GetNextMonotonicCount() to obtain the current platform monotonic count. The operating system would then provide an interface that returns the next count by:

  • Adding 1 to the last count.
  • Before the lower 32 bits of the count overflows, call GetNextHighMonotonicCount().

This will increase the high 32 bits of the platform’s nonvolatile portion of the monotonic count by 1.

This function may only be called at Runtime.

Status Codes Returned

Status Code Description
EFI_SUCCESS The next high monotonic count was returned.
EFI_DEVICE_ERROR The device is not functioning properly.
EFI_INVALID_PARAMETER HighCount is NULL.

UpdateCapsule()

Passes capsules to the firmware with both virtual and physical mapping. Depending on the intended consumption, the firmware may process the capsule immediately. If the payload should persist across a system reset, the reset value returned from EFI_QueryCapsuleCapabilities must be passed into ResetSystem() and will cause the capsule to be processed by the firmware as part of the reset process.

Prototype

typedef
EFI_STATUS
UpdateCapsule (
  IN EFI_CAPSULE_HEADER   **CapsuleHeaderArray,
  IN UINTN                CapsuleCount,
  IN EFI_PHYSICAL_ADDRESS ScatterGatherList OPTIONAL
  );

Parameters

Parameter Description
CapsuleHeaderArray Virtual pointer to an array of virtual pointers to the capsules being passed into update capsule. Each capsules is assumed to stored in contiguous virtual memory. The capsules in the CapsuleHeaderArray must be the same capsules as the ScatterGatherList. The CapsuleHeaderArray must have the capsules in the same order as the ScatterGatherList.
CapsuleCount Number of pointers to EFI_CAPSULE_HEADER in CaspuleHeaderArray.
ScatterGatherList Physical pointer to a set of EFI_CAPSULE_BLOCK_DESCRIPTOR that describes the location in physical memory of a set of capsules. The capsules in the ScatterGatherList must be in the same order as the CapsuleHeaderArray. This parameter is only referenced if the capsules are defined to persist across system reset.


Description
The UpdateCapsule()function allows the operating system to pass information to firmware. The UpdateCapsule() function supports passing capsules in operating system virtual memory back to firmware. Each capsule is contained in a contiguous virtual memory range in the operating system, but both a virtual and physical mapping for the capsules are passed to the firmware.

If a capsule has the CAPSULE_FLAGS_PERSIST_ACROSS_RESET Flag set in its header, the firmware will process the capsules after system reset. The caller must ensure to reset the system using the required reset value obtained from QueryCapsuleCapabilities. If this flag is not set, the firmware will process the capsules immediately.

A capsule which has the CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE Flag must have CAPSULE_FLAGS_PERSIST_ACROSS_RESET set in its header as well. Firmware that processes a capsule that has the CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE Flag set in its header will coalesce the contents of the capsule from the ScatterGatherList into a contiguous buffer and must then place a pointer to this coalesced capsule in the EFI System Table after the system has been reset. Agents searching for this capsule will look in the EFI_CONFIGURATION_TABLE and search for the capsule’s GUID and associated pointer to retrieve the data after the reset.

Flags Firmware Behavior
No Specification defined flags Firmware attempts to immediately processes or launch the capsule. If capsule is not recognized, can expect an error.
CAPSULE_FLAGS_PERSIST_ACROSS_RESET Firmware will attempt to process or launch the capsule across a reset. If capsule is not recognized, can expect an error. If the processing requires a reset which is unsupported by the platform, expect an error.
CAPSULE_FLAGS_PERSIST_ACROSS_RESET + CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE Firmware will coalesce the capsule from the ScatterGatherList into a contiguous buffer and place a pointer to the coalesced capsule in the EFI System Table. Platform recognition of the capsule type is not required. If the action requires a reset which is unsupported by the platform, expect an error.
CAPSULE_FLAGS_PERSIST_ACROSS_RESET + CAPSULE_FLAGS_INITIATE_RESET Firmware will attempt to process or launch the capsule across a reset. The firmware will initiate a reset which is compatible with the passed-in capsule request and will not return back to the caller. If the capsule is not recognized, can expect an error. If the processing requires a reset which is unsupported by the platform, expect an error.

The EFI System Table entry must use the GUID from the CapsuleGuid field of the EFI_CAPSULE_HEADER. The EFI System Table entry must point to an array of capsules that contain the same CapsuleGuid value. The array must be prefixed by a UINT32 that represents the size of the array of capsules.

The set of capsules is pointed to by ScatterGatherList and CapsuleHeaderArray so the firmware will know both the physical and virtual addresses of the operating system allocated buffers. The scatter-gather list supports the situation where the virtual address range of a capsule is contiguous, but the physical addresses are not.

If any of the capsules that are passed into this function encounter an error, the entire set of capsules will not be processed and the error encountered will be returned to the caller.

Status Codes Returned

Status Code Description
EFI_SUCCESS Valid capsule was passed. If CAPSULE_FLAGS_PERSIST_ACROSS_RESET is not set, the capsule has been successfully processed by the firmware.
EFI_INVALID_PARAMETER CapsuleSize , or an incompatible set of flags were set in the capsule header.
EFI_INVALID_PARAMETER CapsuleCount is 0
EFI_DEVICE_ERROR The capsule update was started, but failed due to a device error.
EFI_UNSUPPORTED The capsule type is not supported on this platform.
EFI_OUT_OF_RESOURCES There were insufficient resources to process the capsule.

QueryCapsuleCapabilities()

Returns if the capsule can be supported via UpdateCapsule().

Prototype

typedef
EFI_STATUS
QueryCapsuleCapabilities (
  IN  EFI_CAPSULE_HEADER **CapsuleHeaderArray,
  IN  UINTN              CapsuleCount,
  OUT UINT64             *MaximumCapsuleSize,
  OUT EFI_RESET_TYPE     *ResetType
  );

Parameters

Parameter Description
CapsuleHeaderArray Virtual pointer to an array of virtual pointers to the capsules being passed into update capsule. The capsules are assumed to stored in contiguous virtual memory.
CapsuleCount Number of pointers to EFI_CAPSULE_HEADER in CaspuleHeaderArray.
MaximumCapsuleSize On output the maximum size in bytes that UpdateCapsule() can support as an argument to UpdateCapsule() via CapsuleHeaderArray and ScatterGatherList. Undefined on input.
ResetType Returns the type of reset required for the capsule update. Undefined on input.

Description
The QueryCapsuleCapabilities() function allows a caller to test to see if a capsule or capsules can be updated via UpdateCapsule(). The Flags values in the capsule header and size of the entire capsule is checked.

If the caller needs to query for generic capsule capability a fake EFI_CAPSULE_HEADER can be constructed where CapsuleImageSize is equal to HeaderSize that is equal to sizeof (EFI_CAPSULE_HEADER). To determine reset requirements, CAPSULE_FLAGS_PERSIST_ACROSS_RESET should be set in the Flags field of the EFI_CAPSULE_HEADER.

Status Codes Returned

Status Code Description
EFI_SUCCESS Valid answer returned.
EFI_INVALID_PARAMETER MaximumCapsuleSize is NULL.
EFI_UNSUPPORTED The capsule type is not supported on this platform, and MaximumCapsuleSize and ResetType are undefined.
EFI_OUT_OF_RESOURCES There were insufficient resources to process the query request.

QueryVariableInfo()

Returns information about the EFI variables.

Prototype

typedef
EFI_STATUS
QueryVariableInfo (
  IN  UINT32 Attributes,
  OUT UINT64 *MaximumVariableStorageSize,
  OUT UINT64 *RemainingVariableStorageSize,
  OUT UINT64 *MaximumVariableSize
  );

Parameters

Parameter Description
Attributes Attributes bitmask to specify the type of variables on which to return information. Refer to the GetVariable() function description.
MaximumVariableStorageSize On output the maximum size of the storage space available for the EFI variables associated with the attributes specified.
RemainingVariableStorageSize Returns the remaining size of the storage space available for EFI variables associated with the attributes specified.
MaximumVariableSize Returns the maximum size of an individual EFI variable associated with the attributes specified.

Description
The QueryVariableInfo() function allows a caller to obtain the information about the maximum size of the storage space available for the EFI variables, the remaining size of the storage space available for the EFI variables and the maximum size of each individual EFI variable, associated with the attributes specified.

The MaximumVariableSize value will reflect the overhead associated with the saving of a single EFI variable with the exception of the overhead associated with the length of the string name of the EFI variable. The returned MaximumVariableStorageSize, RemainingVariableStorageSize, MaximumVariableSize information may change immediately after the call based on other runtime activities including asynchronous error events. Also, these values associated with different attributes are not additive in nature.

After the system has transitioned into runtime (after ExitBootServices() is called), an implementation may not be able to accurately return information about the Boot Services variable store. In such cases, EFI_INVALID_PARAMETER should be returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS Valid answer returned.
EFI_INVALID_PARAMETER An invalid combination of attribute bits was supplied
EFI_UNSUPPORTED The attribute is not supported on this platform, and the MaximumVariableStorageSize, RemainingVariableStorageSize, MaximumVariableSize are undefined.

Copyright (C) 2009 Phoenix Technologies, Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools