8. S3 Resume¶
8.1. S3 Overview¶
This specification defines the core code and services that are required for an implementation of the S3 resume boot path in the PI. The S3 resume boot path is a special boot path that causes the system to take actions different from those in the normal boot path. In this special path, the system derives pre-saved data about the platform’s configuration from persistent storage and configures the platform before jumping to the operating system’s waking vector.
This specification does the following:
“Describes the basic components of the S3 resume boot path, how it relates to a normal boot path, and how it interacts with other PI phases and code
“Provides code definitions for the S3-related protocols and PPIs that are architecturally required by the PI Specification .
8.2. Goals¶
This PI S3 resume boot path design has the following goals:
- Extensibility:
The PI S3 resume boot path should easily adapt to different platforms, such as Itanium®-based platforms those based on 32-bit Intel® architecture (IA-32), and x64 platforms by replacing only a few platform-specific modules.
- High performance:
The performance of the PI S3 resume boot path is highly visible to end users and must be optimized.
8.3. Requirements¶
All aspects of this PI S3 resume boot path design must comply with the Advanced Configuration and Power Interface Specification (hereafter referred to as the “ACPI specification”).
The design should emphasize size efficiency, code reuse and maintainability.
8.4. Assumptions¶
8.4.1. Multiple Phases of Platform Initialization¶
The PI Architecture consists of multiple phases. For example:
Pre-EFI Initialization (PEI)
Driver Execution Environment (DXE)
SMM (System Management Mode)
The PEI phase is responsible for initializing enough of the platform’s resources to enable the execution of the DXE phase, which is where the majority of platform configuration is performed by different DXE drivers.
Initialization that is done in PEI is not necessarily preserved in DXE. In other words, a DXE driver can override the configuration settings that were derived from PEI. In light of this fact, the preboot platform state that the S3 resume boot path needs to restore is the DXE snapshot of the platform state, rather than the PEI snapshot of the platform state.
8.4.2. Process of Platform Initialization¶
Platform initialization can be viewed as a flow of the following:
I/O operations
Memory operations
Accessing the PCI configuration space
A collection of platform-specific actions that can be abstracted by Pre-EFI Initialization Module (PEIM) PEIM-to-PEIM Interfaces (PPIs)
The process of restoring hardware settings in different platforms involves different actions or even different instruction sets. These differences, however, can be abstracted behind PEIM PPIs.
8.5. Restoring the Platform¶
The goal of the S3 resume process is to restore the platform to its preboot configuration. However, it is impossible to restore the platform in only one step, without going through all the PI initialization phases, because the PI Architechture cannot have a priori knowledge of the following:
Preboot configuration that is introduced by various PEIMs
Drivers provided by different vendors
As a result, the PI Architechture still needs to restore the platform in a phased fashion as it does in a normal boot path. The figure below shows the phases in an S3 resume boot path. See the following subsections for details of each phase.
Fig. 8.2 PI Architecture S3 Resume¶
8.5.1. Phases in the S3 Resume Boot Path¶
8.5.1.1. SEC and the S3 Resume Boot Path¶
The Security (SEC) phase is the first architectural phase in the PI Architecture. It builds the root of trust for the entire system. As such, the SEC phase remains intact in the S3 resume boot path.
8.5.1.2. PEI¶
8.5.1.2.1. PEI and the S3 Resume Boot Path¶
The PEI phase initializes the platform with the minimum configuration needed to enable the execution of the DXE phase. During the S3 resume boot path, the PI Architechture still needs to restore the PEI portion of configuration.
Each PEIM is “boot path aware” in that the PEIM can call the appropriate PEI service to find out what the current boot path is. This awareness enables the platform to restore more efficiently because the same PEIM can save the configuration during a normal boot path and take advantage of that configuration in the S3 resume boot path. The figure below shows how the PEI phase works in a normal boot path and in an S3 resume boot path.
Fig. 8.3 PEI Phase in S3 Resume Boot Path¶
8.5.1.2.2. Saving Configuration Data in PEI¶
There are different ways to save configuration data, such as the firmware volume variable, for the PEI phase in nonvolatile storage (NVS). One way is to save the data directly in the PEI phase. However, if the PEI phase does not implement the capability to write to a firmware volume, a PEIM can choose to pass the configuration data to the DXE phase using a Hand-Off Block (HOB). The PEIM’s DXE counterpart or another appropriate DXE component can then save the configuration data. The figure below illustrates this mechanism to save the configuration data. See the PI Specification for more details on HOBs.
To achieve higher performance, it is recommended to implement the latter mechanism because code running in the PEI phase is more time consuming than code running in the DXE phase. Note that the way to save the configuration data during the PEI phase is outside the scope of this document.
Fig. 8.4 Configuration Save for PEI Phase¶
8.5.1.3. DXE¶
8.5.1.3.1. DXE and the S3 Resume Boot Path¶
In the DXE phase during a normal boot path, various DXE drivers collectively bring the platform to the preboot state. However, bringing DXE into the S3 resume boot path and making a DXE driver boot-path aware is very risky for the following reasons:
The DXE phase hosts numerous services, which makes it rather large.
Loading DXE from flash is very time consuming.
Even if DXE could be relocated into NVS during a normal boot, the large amount of memory that DXE consumes and the complexity of executing the DXE phase do not justify doing so.
Instead, the PI Architechture provides a boot script that lets the S3 resume boot path avoid the DXE phase altogether, which helps to maximize optimum performance. During a normal boot, DXE drivers record the platform’s configuration in the boot script, which is saved in NVS. During the S3 resume boot path, a boot script engine executes the script, thereby restoring the configuration.
The ACPI specification only requires the BIOS to restore chipset and processor configuration. The chipset configuration can be viewed as a series of memory, I/O, and PCI configuration operations, which DXE drivers record in the PI Architechture boot script. During an S3 resume, a boot script engine executes the boot script to restore the chipset settings. Processor configuration involves the following:
“Basic setup for System Management Mode (SMM)
“Microcode updates
“Processor-specific initialization
“Processor cache setting
DXE drivers register a pointer to a function in the boot script to restore processor configuration. During the S3 resume boot path, the boot script engine can jump to execute the registered code to restore all processor-related configurations.
8.5.1.3.2. S3 Resume PPI and DXE IPL PPI¶
The DXE Initial Program Load (IPL) PPI is architecturally the last PPI that is executed in the PEI phase. It is also made aware of the exact boot path that the PI Architechture is currently using. It discovers the boot mode and initiates the process of restoring the pre-boot platform state and jumping to the operating system (OS) waking vector. The DXE phase is not entered, as it would be during a normal boot.
When resuming from S3, the DXE IPL PEIM will transfer control to the S3 Resume PPI, which is responsible for restoring the platform configuration and jumping to the waking vector.
8.5.1.4. SMM¶
The EFI_S3_SMM_SAVE_STATE_PROTOCOL publishes the PI SMM boot script abstractions
In the S3 boot mode the data stored via this protocol is replayed in the order it was stored.
The order of replay is the order either of the S3 Save State Protocol or S3 SMM Save State Protocol Write() functions were called during the boot process. Insert(), Label() , and Compare() operations are ordered relative other S3 SMM Save State Protocol Write() operations and the order relative to S3 State Save Write() operations is not defined. Due to these ordering restrictions it is recommended that the S3 State Save Protocol be used during the DXE phase when every possible.
The EFI_S3_SMM_SAVE_STATE_PROTOCOL can be called at runtime and EFI_OUT_OF_RESOURCES may be returned from a runtime call. It is the responsibility of the platform to ensure enough memory resource exists to save the system state. It is recommended that runtime calls be minimized by the caller.3
8.6. PEI Boot Script Executer PPI¶
8.6.1. EFI_PEI_S3_RESUME2_PPI¶
Summary
This PPI produces functions to interpret and execute the PI boot script table.
GUID
#define EFI_PEI_S3_RESUME2_PPI_GUID \
{0x6d582dbc, 0xdb85, 0x4514, \
0x8f, 0xcc, 0x5a, 0xdf, 0x62, 0x27, 0xb1,0x47}
PPI Interface Structure
typedef struct \_EFI_PEI_S3_RESUME2_PPI {
EFI_PEI_S3_RESUME_PPI_RESTORE_CONFIG2 *S3RestoreConfig2* ;
} EFI_PEI_S3_RESUME2_PPI;
Parameters
- S3RestoreConfig2
Perform S3 resume operation.
Description
This PPI is published by a PEIM and provides for the restoration of the platform’s configuration when resuming from the ACPI S3 power state. The ability to execute the boot script may depend on the availability of other PPIs. For example, if the boot script includes an SMBus command, this PEIM looks for the relevant PPI that is able to execute that command.
8.6.2. EFI_PEI_S3_RESUME_PPI.S3RestoreConfig()¶
Summary
Restores the platform to its pre-boot configuration for an S3 resume and jumps to the OS waking vector.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_PEI_S3_RESUME_PPI_RESTORE_CONFIG) (
IN EFI_PEI_S3_RESUME_PPI *This
);
Parameters
- This
A pointer to this instance of the PEI_S3_RESUME_PPI.
Description
This function will restore the platform to its pre-boot configuration that was pre-stored in the boot script table and transfer control to OS waking vector.
Upon invocation, this function is responsible for locating the following information before jumping to OS waking vector:
ACPI tables
boot script table
any other information that it needs
The S3RestoreConfig() function then executes the pre-stored boot script table and transitions the platform to the pre-boot state. The boot script is recorded during regular boot using the EFI_S3_SAVE_STATE_PROTOCOL.Write() and EFI_S3_SMM_SAVE_STATE_PROTOCOL.Write() functions. Finally, this function transfers control to the OS waking vector. If the OS supports only a real-mode waking vector, this function will switch from flat mode to real mode before jumping to the waking vector.
If all platform pre-boot configurations are successfully restored and all other necessary information is ready, this function will never return and instead will directly jump to the OS waking vector. If this function returns, it indicates that the attempt to resume from the ACPI S3 sleep state failed.
Status Codes Returned
EFI_ABORTED |
Execution of the S3 resume boot script table failed |
EFI_NOT_FOUND |
Some necessary information that is used for the S3 resume boot path could not be located |
8.7. S3 Save State Protocol¶
This section defines how a DXE PI module can record IO operations to be performed as part of the S3 resume. This is done via the EFI_S3_SAVE_STATE_PROTOCOL and this allows the implementation of the S3 resume boot path to be abstracted from DXE drivers.
8.7.1. EFI_S3_SAVE_STATE_PROTOCOL¶
Summary
Used to store or record various IO operations to be replayed during an S3 resume.
GUID
#define EFI_S3_SAVE_STATE_PROTOCOL_GUID \
{ 0xe857caf6, 0xc046, 0x45dc, { 0xbe, 0x3f, 0xee, 0x7, \
0x65, 0xfb, 0xa8, 0x87 } }
Protocol Interface Structure
typedef struct _EFI_S3_SAVE_STATE_PROTOCOL {
EFI_S3_SAVE_STATE_WRITE Write;
EFI_S3_SAVE_STATE_INSERT Insert;
EFI_S3_SAVE_STATE_LABEL Label;
EFI_S3_SAVE_STATE_COMPARE Compare;
} EFI_S3_SAVE_STATE_PROTOCOL;
Parameters
- Write
Write an opcode at the end of the boot script table. See the Write() function description.
- Insert
Write an opcode at the specified position in the boot script table. See the Insert() function description.
- Label
Find an existing label in the boot script table or, if not present, create it. See the Label() function description.
- Compare
Compare two positions in the boot script table to determine their relative location. See the Compare() function description.
Description
The EFI_S3_SAVE_STATE_PROTOCOL publishes the PI boot script abstractions. This protocol is not required for all platforms.
On an S3 resume boot path the data stored via this protocol is replayed in the order it appears in the boot script table.
8.7.2. Save State Write¶
8.7.3. EFI_S3_SAVE_STATE_PROTOCOL.Write()¶
Summary
Record operations that need to be replayed during an S3 resume.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_S3_SAVE_STATE_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINTN OpCode,
. . .
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
The operation code (opcode) number. See “Related Definitions” below for the defined opcode types.
- …
Argument list that is specific to each opcode. See the following subsections for the definition of each opcode.
Description
This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is assumed this protocol has platform specific mechanism to store the OpCode set and replay them during the S3 resume.
Note
The opcode is inserted at the end of the boot script table
This function has a variable parameter list. The exact parameter list depends on the OpCode that is passed into the function. If an unsupported OpCode or illegal parameter list is passed in, this function returns EFI_INVALID_PARAMETER .
If there are not enough resources available for storing more scripts, this function returns EFI_OUT_OF_RESOURCES .
OpCode values of 0x80 - 0xFE are reserved for implementation-specific functions.
//******************************************\*
// EFI Boot Script Opcode definitions
//******************************************\*
#define EFI_BOOT_SCRIPT_IO_WRITE_OPCODE 0x00
#define EFI_BOOT_SCRIPT_IO_READ_WRITE_OPCODE 0x01
#define EFI_BOOT_SCRIPT_MEM_WRITE_OPCODE 0x02
#define EFI_BOOT_SCRIPT_MEM_READ_WRITE_OPCODE 0x03
#define EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE 0x04
#define EFI_BOOT_SCRIPT_PCI_CONFIG_READ_WRITE_OPCODE 0x05
#define EFI_BOOT_SCRIPT_SMBUS_EXECUTE_OPCODE 0x06
#define EFI_BOOT_SCRIPT_STALL_OPCODE 0x07
#define EFI_BOOT_SCRIPT_DISPATCH_OPCODE 0x08
#define EFI_BOOT_SCRIPT_DISPATCH_2_OPCODE 0x09
#define EFI_BOOT_SCRIPT_INFORMATION_OPCODE 0x0A
#define EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE 0x0B
#define EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE 0x0C
#define EFI_BOOT_SCRIPT_IO_POLL_OPCODE 0x0D
#define EFI_BOOT_SCRIPT_MEM_POLL_OPCODE 0x0E
#define EFI_BOOT_SCRIPT_PCI_CONFIG_POLL_OPCODE 0x0F
#define EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE 0x10
//******************************************\*
// EFI_BOOT_SCRIPT_WIDTH
//******************************************\*
typedef enum {
EfiBootScriptWidthUint8,
EfiBootScriptWidthUint16,
EfiBootScriptWidthUint32,
EfiBootScriptWidthUint64,
EfiBootScriptWidthFifoUint8,
EfiBootScriptWidthFifoUint16,
EfiBootScriptWidthFifoUint32,
EfiBootScriptWidthFifoUint64,
EfiBootScriptWidthFillUint8,
EfiBootScriptWidthFillUint16,
EfiBootScriptWidthFillUint32,
EfiBootScriptWidthFillUint64,
EfiBootScriptWidthMaximum
} EFI_BOOT_SCRIPT_WIDTH;
Status Codes Returned
EFI_SUCCESS |
The operation succeeded A record was added into the specified script table |
EFI_INVALID_PARAMETER |
The parameter is illegal or the given boot script is not supported |
EFI_OUT_OF_RESOURCES |
There is insufficient memory to store the boot script |
8.7.3.1. Opcodes for Write()¶
This section contains the prototypes for variations of the Write() function, based on the Opcode parameter.
8.7.4. EFI_BOOT_SCRIPT_IO_WRITE_OPCODE¶
Summary
Adds a record for an I/O write operation into a specified bootscript table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN UINTN Count,
IN VOID *Buffer
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_IO_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_IO_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the I/O operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Address
The base address of the I/O operations.
- Count
The number of I/O operations to perform. The number of bytes moved is Width size * Count, starting at Address .
- Buffer
The source buffer from which to write data. The buffer size is Width size * Count .
Description
This function adds an I/O write record into a specified boot script table. On script execution, this operation writes the presaved value into the specified I/O ports.
The caller is responsible for complying with any I/O alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
If Width is EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, or EfiBootScriptWidthUint64, then:
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFifoUint8, EfiBootScriptWidthFifoUint16, EfiBootScriptWidthFifoUint32, or EfiBootScriptWidthFifoUint64, then
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is reused unchanged for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, or EfiBootScriptWidthFillUint64, then
Buffer is reused unchanged for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the presaved value is written on script execution.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.5. EFI_BOOT_SCRIPT_IO_READ_WRITE_OPCODE¶
Summary
Adds a record for an I/O modify operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_IO_POLL_OPCODE . Value EFI_BOOT_SCRIPT_IO_POLL_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write()
- Width
The width of the I/O operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() . EfiBootScriptWidthFifoUint8, EfiBootScriptWidthFifoUint16, EfiBootScriptWidthFifoUint32, and EfiBootScriptWidthFifoUint64 are**interpreted identically to EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, and EfiBootScriptWidthUint64, respectively.
EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, and EfiBootScriptWidthFillUint64 are interpreted identically to EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, and EfiBootScriptWidthUint64, respectively.
- Address
The base address of the I/O operations.
- Data
A pointer to the data to be OR-ed.
- DataMask
A pointer to the data mask to be AND-ed with the data read from the register.
Description
This function adds an I/O read and write record into the specified boot script table. When the script is executed, the register at Address is read, AND-ed with DataMask, and OR-ed with Data, and finally the result is written back.
The caller is responsible for complying with any I/O alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.6. EFI_BOOT_SCRIPT_IO_POLL_OPCODE¶
Summary
Adds a record for I/O reads the I/O location and continues when the exit criteria is satisfied or after a defined duration.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask,
IN UINT64 Delay
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_IO_READ_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_IO_READ_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the I/O operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() . EfiBootScriptWidthFifoUint8, EfiBootScriptWidthFifoUint16, EfiBootScriptWidthFifoUint32, and EfiBootScriptWidthFifoUint64 are interpreted identically to EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, and EfiBootScriptWidthUint64, respectively.
EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, and EfiBootScriptWidthFillUint64 are interpreted identically to EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, and EfiBootScriptWidthUint64, respectively.
- Address
The base address of the I/O operations.
- Data
The comparison value used for the polling exit criteria.
- DataMask
Mask used for the polling criteria. The bits in the bytes below Width which are zero in Data are ignored when polling the memory address.
- Delay
The number of 100ns units to poll. Note that timer available may be of poorer granularity so the delay may be longer.
Description
This function adds a delay to the boot script table. The I/O read operation is repeated until either a Delay of at least 100 ns units has expired, or ( Data & DataMask ) is equal to Data . At least one I/O access is always performed regardless of the value of Delay .
The caller is responsible for complying with any I/O alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.7. EFI_BOOT_SCRIPT_MEM_WRITE_OPCODE¶
Summary
Adds a record for a memory write operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This ,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN UINTN Count,
IN VOID *Buffer
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_MEM_WRITE_OPCODE. Value EFI_BOOT_SCRIPT_MEM_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the memory operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Address
The base address of the memory operations. Address needs alignment if required.
- Count
The number of memory operations to perform. The number of bytes moved is Width size * Count, starting at Address.
- Buffer
The source buffer from which to write the data. The buffer size is Width size * Count .
Description
This function adds a memory write record into a specified boot script table. When the script is executed, this operation writes the presaved value into the specified memory location.
The caller is responsible for complying with any memory and MMIO alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
If Width is EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, or EfiBootScriptWidthUint64, then:
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFifoUint8, EfiBootScriptWidthFifoUint16, EfiBootScriptWidthFifoUint32, or EfiBootScriptWidthFifoUint64, then:
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is reused unchanged for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, or EfiBootScriptWidthFillUint64, then:
Buffer is reused unchanged for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the presaved value is written on script execution.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.8. EFI_BOOT_SCRIPT_MEM_READ_WRITE_OPCODE¶
Summary
Adds a record for a memory modify operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_MEM_READ_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_MEM_READ_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the memory operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH. Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() . EfiBootScriptWidthFifoUint8 , EfiBootScriptWidthFifoUint16 , EfiBootScriptWidthFifoUint32 , and EfiBootScriptWidthFifoUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively. *
EfiBootScriptWidthFillUint8* , EfiBootScriptWidthFillUint16 , EfiBootScriptWidthFillUint32 , and EfiBootScriptWidthFillUint64 areinterpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
- Address
The base address of the memory operations. Address needs alignment if required.
- Data
A pointer to the data to be OR -ed.
- DataMask
A pointer to the data mask to be AND -ed with the data read from the register.
Description
This function adds a memory read and write record into a specified boot script table. When the script is executed, the memory at Address is read, AND -ed with DataMask , and OR -ed with Data , and finally the result is written back.
The caller is responsible for complying with any memory and MMIO alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.9. EFI_BOOT_SCRIPT_MEM_POLL_OPCODE¶
Summary
Adds a record for memory reads of the memory location and continues when the exit criteria is satisfied or after a defined duration.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask,
IN UINT64 Delay
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_MEM_POLL_OPCODE . Value EFI_BOOT_SCRIPT_MEM_POLL_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the memory operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
EfiBootScriptWidthFifoUint8 , EfiBootScriptWidthFifoUint16 , EfiBootScriptWidthFifoUint32 , and EfiBootScriptWidthFifoUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64, respectively.
EfiBootScriptWidthFillUint8 , EfiBootScriptWidthFillUint16 , EfiBootScriptWidthFillUint32 , and EfiBootScriptWidthFillUint64 areinterpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
- Address
The base address of the memory operations. Address needs alignment if required.
- Data
The comparison value used for the polling exit criteria.
- DataMask
Mask used for the polling criteria. The bits in the bytes below Width which are zero in Data are ignored when polling the memory address.
- Delay
The number of 100ns units to poll. Note that timer available may be of poorer granularity so the delay may be longer.
Description
This function adds a delay to the boot script table. The memory read operation is repeated until either a timeout of Delay 100 ns units has expired, or ( Data & DataMask ) is equal to Data . At least one I/O access is always performed regardless of the value of Delay .
The caller is responsible for complying with any memory and MMIO alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.10. EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE¶
Summary
Adds a record for a PCI configuration space write operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN UINTN Count,
IN VOID *Buffer
)
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the PCI operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Address
The address within the PCI configuration space. For address format details, see the “PCI Configuration Address” table in the UEFI Specification, under EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() and EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Write(). <http://uefi.org/specifications>`__
- Count
The number of PCI operations to perform. The number of bytes moved is Width size * Count , starting at Address.
- Buffer
The source buffer from which to write the data. The buffer size is Width size * Count .
Description
This function adds a PCI configuration space write record into a specified boot script table. When the script is executed, this operation writes the presaved value into the specified location in PCI configuration space.
The caller is responsible for complying with any PCI configuration space alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
If Width is EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, or EfiBootScriptWidthUint64, then:
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFifoUint8, EfiBootScriptWidthFifoUint16, EfiBootScriptWidthFifoUint32, or EfiBootScriptWidthFifoUint64, then
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is reused unchanged for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, or EfiBootScriptWidthFillUint64, then
Buffer is reused unchanged for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the presaved value is written on script execution.
Incrementing Address (that is, when Width is EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, EfiBootScriptWidthUint64, EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, or EfiBootScriptWidthFillUint64) provides a way to write several registers in the configuration space of the same PCI or PCI Express Bus/Device/Function that is encoded by the initial value of Address, using a single record in the specified boot script table.
If, on script execution, a register write is attempted that is outside of the configuration space of the PCI or PCI Express Bus/Device/Function that was encoded by the initial value of Address, the behavior is undefined.
For PCI Express devices, it is valid to encode an 8-bit starting configuration space offset in byte 0 of Address, and to continue into extended configuration space during the execution of the same EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE.
Status Codes Returned
In addition to the common status codes specified in Write(), Write() may optionally return the following status code when OpCode is EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE:
EFI_INVALID_PARAMETER Performing Count configuration space writes starting at Address, as dictated by Width, would cross the configuration space boundary for the PCI or PCI Express Bus/Device/Function that was encoded in the original value of Address. It is unspecified whether an implementation of Write() recognizes this error.
8.7.11. EFI_BOOT_SCRIPT_PCI_CONFIG_READ_WRITE_OPCODE¶
Summary
Adds a record for a PCI configuration space modify operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_PCI_CONFIG_READ_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_PCI_CONFIG_READ_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the PCI operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
EfiBootScriptWidthFifoUint8 , EfiBootScriptWidthFifoUint16 , EfiBootScriptWidthFifoUint32 , and EfiBootScriptWidthFifoUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
EfiBootScriptWidthFillUint8 , EfiBootScriptWidthFillUint16 , EfiBootScriptWidthFillUint32 , and EfiBootScriptWidthFillUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
- Address
The address within the PCI configuration space. For address format details, see the “PCI Configuration Address” in the UEFI Specification, under EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read() and EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Write() .
- Data
A pointer to the data to be OR -ed. The size depends on Width .
- DataMask
A pointer to the data mask to be AND -ed.
Description
This function adds a PCI configuration read and write record into a specified boot script table. When the script is executed, the PCI configuration space location at Address is read, AND -ed with DataMask , and OR -ed with, and finally the result is written back.
The caller is responsible for complying with any PCI configuration space alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.12. EFI_BOOT_SCRIPT_PCI_CONFIG_POLL_OPCODE¶
Summary
Adds a record for PCI configuration space reads and continues when the exit criteria is satisfied or after a defined duration.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask,
IN UINT64 Delay
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_PCI_CONFIG_POLL_OPCODE . Value EFI_BOOT_SCRIPT_PCI_CONFIG_POLL_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the PCI operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
EfiBootScriptWidthFifoUint8 , EfiBootScriptWidthFifoUint16 , EfiBootScriptWidthFifoUint32 , and EfiBootScriptWidthFifoUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
EfiBootScriptWidthFillUint8 , EfiBootScriptWidthFillUint16 , EfiBootScriptWidthFillUint32 , and EfiBootScriptWidthFillUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
- Address
- Data
The comparison value used for the polling exit criteria.
- DataMask
Mask used for the polling criteria. The bits in the bytes below Width which are zero in Data are ignored when polling the memory address.
- Delay
The number of 100ns units to poll. Note that timer available may be of poorer granularity so the delay may be longer.
Description
This function adds a delay to the boot script table. The PCI configuration read operation is repeated until either a timeout of Delay 100 ns units has expired, or ( Data & DataMask ) is equal to Data . At least one PCI configuration access is always performed regardless of the value of Delay .
The caller is responsible for complying with any PCI configuration space alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.13. EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE¶
Summary
Adds a record for a PCI configuration space write operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT16 Segment,
IN UINT64 Address,
IN UINTN Count,
IN VOID *Buffer
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the PCI operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Segment
The PCI segment number for Address.
- Address
- Count
The number of PCI operations to perform. The number of bytes moved is Width size * Count , starting at Address .
- Buffer
The source buffer from which to write the data. The buffer size is Width size * Count .
Description
This function adds a PCI configuration space write record into a specified boot script table. When the script is executed, this operation writes the presaved value into the specified location in PCI configuration space.
The caller is responsible for complying with any PCI configuration space alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
If Width is EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, or EfiBootScriptWidthUint64, then:
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFifoUint8, EfiBootScriptWidthFifoUint16, EfiBootScriptWidthFifoUint32, or EfiBootScriptWidthFifoUint64, then
Buffer is incremented for each of the Count operations when adding the record to the specified boot script table,
Address is reused unchanged for each of the Count operations when the array of presaved values is written on script execution.
If Width is EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, or EfiBootScriptWidthFillUint64, then
Buffer is reused unchanged for each of the Count operations when adding the record to the specified boot script table,
Address is incremented for each of the Count operations when the presaved value is written on script execution.
Incrementing Address (that is, when Width is EfiBootScriptWidthUint8, EfiBootScriptWidthUint16, EfiBootScriptWidthUint32, EfiBootScriptWidthUint64, EfiBootScriptWidthFillUint8, EfiBootScriptWidthFillUint16, EfiBootScriptWidthFillUint32, or EfiBootScriptWidthFillUint64) provides a way to write several registers in the configuration space of the same PCI or PCI Express
Segment/Bus/Device/Function that is encoded by the Segment parameter and the initial value of Address, using a single record in the specified boot script table.
If, on script execution, a register write is attempted that is outside of the configuration space of the PCI or PCI Express Segment/Bus/Device/Function that was encoded by the Segment parameter and the initial value of Address, the behavior is undefined.
For PCI Express devices, it is valid to encode an 8-bit starting configuration space offset in byte 0 of Address, and to continue into extended configuration space during the execution of the same EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE.
Status Codes Returned
In addition to the common status codes specified in Write(), Write() may optionally return the following status code when OpCode is EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE:
EFI_INVALID_PARAMETER Performing Count configuration space writes starting at Address, as dictated by Width, would cross the configuration space boundary for the PCI or PCI Express Segment/Bus/Device/Function that was encoded in the Segment parameter and the original value of Address. It is unspecified whether an implementation of Write() recognizes this error.
8.7.14. EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE¶
Summary
Adds a record for a PCI configuration space modify operation into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT16 Segment,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask
)
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE . Value EFI_BOOT_SCRIPT_PCI_CONFIG_READ_WRITE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the PCI operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively. EfiBootScriptWidthFillUint8 , EfiBootScriptWidthFillUint16 , EfiBootScriptWidthFillUint32 , and EfiBootScriptWidthFillUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
- Segment
The PCI segment number for Address .
- Address
- Data
A pointer to the data to be OR -ed. The size depends on Width .
- DataMask
A pointer to the data mask to be AND -ed.
Description
This function adds a PCI configuration read and write record into a specified boot script table. When the script is executed, the PCI configuration space location at Address is read, AND -ed with DataMask , and OR -ed with, and finally the result is written back.
The caller is responsible for complying with any PCI configuration space alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.15. EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE¶
Summary
Adds a record for PCI configuration space reads and continues when the exit criteria is satisfied or after a defined duration.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_BOOT_SCRIPT_WIDTH Width,
IN UINT16 Segment,
IN UINT64 Address,
IN VOID *Data,
IN VOID *DataMask,
IN UINT64 Delay
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE . Value EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Width
The width of the PCI operations. Enumerated in EFI_BOOT_SCRIPT_WIDTH . Type EFI_BOOT_SCRIPT_WIDTH is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
EfiBootScriptWidthFifoUint8 , EfiBootScriptWidthFifoUint16 , EfiBootScriptWidthFifoUint32 , and EfiBootScriptWidthFifoUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
EfiBootScriptWidthFillUint8 , EfiBootScriptWidthFillUint16 , EfiBootScriptWidthFillUint32 , and EfiBootScriptWidthFillUint64 are interpreted identically to EfiBootScriptWidthUint8 , EfiBootScriptWidthUint16 , EfiBootScriptWidthUint32 , and EfiBootScriptWidthUint64 , respectively.
- Segment
The PCI segment number for Address .
- Address
- Data
The comparison value used for the polling exit criteria.
- DataMask
Mask used for the polling criteria. The bits in the bytes below Width which are zero in Data are ignored when polling the memory address.
- Delay
The number of 100ns units to poll. Note that timer available may be of poorer granularity so the delay may be longer.
Description
This function adds a delay to the boot script table. The PCI configuration read operation is repeated until either a timeout of Delay 100 ns units has expired, or ( Data & DataMask) is equal to Data . At least one PCI configuration access is always performed regardless of the value of Delay .
The caller is responsible for complying with any PCI configuration space alignment and width requirements presented by the bus, device, or platform. For example, on some platforms, width requests of EfiBootScriptWidthUint64 might not work.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.16. EFI_BOOT_SCRIPT_SMBUS_EXECUTE_OPCODE¶
Summary
Adds a record for an SMBus command execution into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST \_EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
IN EFI_SMBUS_DEVICE_COMMAND Command,
IN EFI_SMBUS_OPERATION Operation,
IN BOOLEAN PecCheck,
IN UINTN *Length,
IN VOID *Buffer
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_SMBUS_EXECUTE_OPCODE . Value EFI_BOOT_SCRIPT_SMBUS_EXECUTE_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- SlaveAddress
The SMBus address for the slave device that the operation is targeting. Type EFI_SMBUS_DEVICE_ADDRESS is defined in EFI_PEI_SMBUS_PPI.Execute() in the PI Specification .
- Command
The command that is transmitted by the SMBus host controller to the SMBus slave device. The interpretation is SMBus slave device specific. It can mean the offset to a list of functions inside an SMBus slave device. Type EFI_SMBUS_DEVICE_COMMAND is defined in EFI_PEI_SMBUS_PPI.Execute() in the PI Specification .
- Operation
Indicates which particular SMBus protocol it will use to execute the SMBus transactions. Type EFI_SMBUS_OPERATION is defined in EFI_PEI_SMBUS_PPI.Execute() in the PI Specification .
- PecCheck
Defines if Packet Error Code (PEC) checking is required for this operation.
- Length
A pointer to signify the number of bytes that this operation will do.
- Buffer
Contains the value of data to execute to the SMBUS slave device.
Description
This function adds an SMBus command execution record into a specified boot script table. When the script is executed, this operation executes a specified SMBus command.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.17. EFI_BOOT_SCRIPT_STALL_OPCODE¶
Summary
Adds a record for an execution stall on the processor into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN UINTN Duration
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_STALL_OPCODE . Value EFI_BOOT_SCRIPT_STALL_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- Duration
Duration in microseconds of the stall.
Description
This function adds a stall record into a specified boot script table. When the script is executed, this operation will stall the system for Duration number of microseconds.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.18. EFI_BOOT_SCRIPT_DISPATCH_OPCODE¶
Summary
Adds a record for dispatching specified arbitrary code into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_PHYSICAL_ADDRESS EntryPoint
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_DISPATCH_OPCODE . Value EFI_BOOT_SCRIPT_DISPATCH_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- EntryPoint
Entry point of the code to be dispatched. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 Specification.
Description
This function adds a dispatch record into a specified boot script table, with which it can run the arbitrary code that is specified. This script can be used to initialize the processor. When the script is executed, the script incurs jumping to the entry point to execute the arbitrary code. After the execution is returned, it goes on executing the next opcode in the table.
The EntryPoint must point to memory of type of EfiRuntimeServicesCode , EfiRuntimeServicesData , or EfiACPIMemoryNVS . The EntryPoint must have the same calling convention as the PI DXE Phase.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.19. EFI_BOOT_SCRIPT_DISPATCH_2_OPCODE¶
Summary
Adds a record for dispatching specified arbitrary code into a specified boot script table.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN EFI_PHYSICAL_ADDRESS EntryPoint,
IN EFI_PHYSICAL_ADDRESS Context
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_DISPATCH_2_OPCODE . Value EFI_BOOT_SCRIPT_DISPATCH_2_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- EntryPoint
Entry point of the code to be dispatched. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI Specification .
- Context
Argument to be passed into the EntryPoint of the code to be dispatched. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI Specification .
Description
This function adds a dispatch record into a specified boot script table, with which it can run the arbitrary code that is specified. This script can be used to initialize the processor. When the script is executed, the script incurs jumping to the entry point to execute the arbitrary code. After the execution is returned, it goes on executing the next opcode in the table.
The EntryPoint and Context must point to memory of type of EfiRuntimeServicesCode , EfiRuntimeServicesData , or EfiACPIMemoryNVS . The EntryPoint must have the same calling convention as the PI DXE Phase.
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.20. EFI_BOOT_SCRIPT_INFORMATION_OPCODE¶
Summary
Store the pointer to the arbitrary information in the boot script table. This opcode is a no-op on dispatch and is only used for debugging script issues.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_BOOT_SCRIPT_WRITE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN UINT16 OpCode,
IN UINT32 InformationLength,
IN EFI_PHYSICAL_ADDRESS Information
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- OpCode
Must be set to EFI_BOOT_SCRIPT_INFORMATION_OPCODE . Value EFI_BOOT_SCRIPT_INFORMATION_OPCODE is defined in “Related Definitions” in EFI_S3_SAVE_STATE_PROTOCOL.Write() .
- InformationLength
Length of the data in bytes.
- Information
Pointer to the information to be logged in the boot script.
Description
This function adds a record that has no impact on the S3 replay. This function is used to store debug information in the S3 data stream.
The Information must point to memory of type of EfiRuntimeServicesCode , EfiRuntimeServicesData , or EfiACPIMemoryNVS .
Status Codes Returned
See “Status Codes Returned” in Write() .
8.7.21. Save State Insert¶
8.7.22. EFI_S3_SAVE_STATE_PROTOCOL.Insert()¶
Summary
Record operations that need to be replayed during an S3 resume.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_S3_SAVE_STATE_INSERT) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN BOOLEAN BeforeOrAfter,
IN OUT EFI_S3_BOOT_SCRIPT_POSITION *Position OPTIONAL,
IN UINTN OpCode,
...
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCO L instance.
- BeforeOrAfter
Specifies whether the opcode is stored before ( TRUE) or after ( FALSE ) the position in the boot script table specified by Position . If Position is NULL or points to NULL then the new opcode is inserted at the beginning of the table (if TRUE) or end of the table (if FALSE ).
- Position
On entry, specifies the position in the boot script table where the opcode will be inserted, either before or after, depending on BeforeOrAfter . On exit, if not NULL, specifies the position of the inserted opcode in the boot script table.
- OpCode
The operation code (opcode) number. See “Related Definitions” in Write() for the defined opcode types.
- …
Argument list that is specific to each opcode. See the following subsections for the definition of each opcode.
Description
This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is assumed this protocol has platform specific mechanism to store the OpCode set and replay them during the S3 resume.
The opcode is stored before ( TRUE ) or after ( FALSE ) the position in the boot script table specified by Position . If Position is NULL or points to NULL then the new opcode is inserted at the beginning of the table (if TRUE ) or end of the table (if FALSE ).
The position which is pointed to by Position upon return can be used for subsequent insertions.
This function has a variable parameter list. The exact parameter list depends on the OpCode that is passed into the function. If an unsupported OpCode or illegal parameter list is passed in, this function returns EFI_INVALID_PARAMETER .
If there are not enough resources available for storing more scripts, this function returns EFI_OUT_OF_RESOURCES .
OpCode values of 0x80 - 0xFE are reserved for implementation specific functions.
typedef VOID \*EFI_S3_BOOT_SCRIPT_POSITION;
Status Codes Returned
EFI_SUCCESS |
The operation succeeded An opcode was added into the script table |
EFI_INVALID_PARAMETER |
The Opcode is an invalid opcode value |
EFI_INVALID_PARAMETER |
The Position is not a valid position in the boot script table |
EFI_OUT_OF_RESOURCES |
There is insufficient memory to store the boot script |
8.7.23. Save State Label¶
8.7.24. EFI_S3_SAVE_STATE_PROTOCOL.Label()¶
Summary
Find a label within the boot script table and, if not present,optionally create it.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_S3_SAVE_STATE_LABEL) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN BOOLEAN BeforeOrAfter,
IN BOOLEAN CreateIfNotFound,
IN OUT EFI_S3_BOOT_SCRIPT_POSITION *Position OPTIONAL,
IN CONST CHAR8 *Label
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- BeforeOrAfter
Specifies whether the label is stored before ( TRUE ) or after ( FALSE ) the position in the boot script table specified by Position . If Position is NULL or points to NULL then the new label is inserted at the beginning of the table (if TRUE ) or end of the table (if FALSE) .
- CreateIfNotFound
Specifies whether the label will be created if the label does not exists ( TRUE ) or not ( FALSE ).
- Position
On entry, specifies the position in the boot script table where the label will be inserted, either before or after, depending on BeforeOrAfter . On exit, if not NULL, specifies the position of the inserted label in the boot script table.
- Label
Points to the NULL terminated label which will be inserted in the boot script table.
Description
If the label Label already exists in the boot script table, then no new label is created, the position of the Label is returned in * Position (if Position is not NULL) and EFI_SUCCESS is returned. If the label already exists, the input value of the Position is ignored.
If the label Label does not already exist and CreateIfNotFound is TRUE , then it will be created before or after the specified position and EFI_SUCCESS is returned.
If the label Label does not already exist and CreateIfNotFound is FALSE , then EFI_NOT_FOUND is returned.
Status Codes Returned
EFI_SUCCESS |
The label already exists or was inserted |
EFI_NOT_FOUND |
The label did not already exist and CreateifNotFound was FALSE |
EFI_INVALID_PARAMETER |
The Label is NULL or points to an empty string |
EFI_INVALID_PARAMETER |
The Position is not a valid position in the boot script table |
EFI_OUT_OF_RESOURCES |
There is insufficient memory to store the boot script |
8.7.25. Save State Compare¶
8.7.26. EFI_S3_SAVE_STATE_PROTOCOL.Compare()¶
Summary
Compare two positions in the boot script table and return their relative position.
Prototype
typedef
EFI_STATUS
(EFIAPI \*EFI_S3_SAVE_STATE_COMPARE) (
IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This,
IN EFI_S3_BOOT_SCRIPT_POSITION Position1,
IN EFI_S3_BOOT_SCRIPT_POSITION Position2,
OUT UINTN *RelativePosition
);
Parameters
- This
A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.
- Position1, Position2
The positions in the boot script table to compare.
- RelativePosition
On return, points to the result of the comparison.
Description
This function compares two positions in the boot script table and returns their relative positions. If Position1 is before Position2 , then -1 is returned. If Position1 is equal to Position2 , then 0 is returned. If Position1 is after Position2 , then 1 is returned.
Status Codes Returned
EFI_SUCCESS |
The operation succeeded |
EFI_INVALID_PARAMETER |
The Position1 or Position2 is not a valid position in the boot script table |
EFI_INVALID_PARAMETER |
The RelativePosition is NULL |
8.8. S3 SMM Save State Protocol¶
This section defines how a SMM PI module can record IO operations to be performed as part of the S3 resume. This is done via the EFI_S3_SMM_SAVE_STATE_PROTOCOL and this allows the implementation of the S3 resume boot path to be abstracted from SMM drivers.
The S3 SMM Save State Protocol shares the interface definition with the S3 Save State Protocol but it has a different GUID. It is an SMM protocol. Having separate protocols for SMM and DXE makes it easier to accommodate the differences in the operating environment between SMM and DXE.
8.8.1. EFI_S3_SMM_SAVE_STATE_PROTOCOL¶
Summary
Used to store or record various IO operations to be replayed during an S3 resume.
GUID
#define EFI_S3_SMM_SAVE_STATE_PROTOCOL_GUID \\
{ 0x320afe62, 0xe593, 0x49cb, { 0xa9, 0xf1, 0xd4, 0xc2, \\
0xf4, 0xaf, 0x1, 0x4c } }
Protocol Interface Structure
typedef struct \_EFI_S3_SMM_SAVE_STATE_PROTOCOL {
EFI_S3_SAVE_STATE_WRITE Write;
EFI_S3_SAVE_STATE_INSERT Insert;
EFI_S3_SAVE_STATE_LABEL Label;
EFI_S3_SAVE_STATE_COMPARE Compare;
} EFI_S3_SMM_SAVE_STATE_PROTOCOL;
Parameters
- Write
Write an opcode at the end of the boot script table. See the Write() function description under the EFI_S3_SAVE_STATE_PROTOCOL definition.
- Insert
Write an opcode at the specified position in the boot script table. See the Insert() function description under the EFI_S3_SAVE_STATE_PROTOCOL definition.
- Label
Find an existing label in the boot script table or, if not present, create it. See the Label() function description under the EFI_S3_SAVE_STATE_PROTOCOL definition.
- Compare
Compare two positions in the boot script table to determine their relative location. See the Compare() function description under the EFI_S3_SAVE_STATE_PROTOCOL definition.
Description
The EFI_S3_SMM_SAVE_STATE_PROTOCOL provides the PI SMMboot script abstraction.
On an S3 resume boot path the data stored via this protocol is replayed in the order it was stored.
The order of replay is the order either of the S3 Save State Protocol or S3 SMM Save State Protocol Write() functions were called during the boot process.
The EFI_S3_SMM_SAVE_STATE_PROTOCOL can be called at runtime and EFI_OUT_OF_RESOURCES may be returned from a runtime call. It is the responsibility of the platform to ensure enough memory resource exists to save the system state. It is recommended that runtime calls be minimized by the caller.