X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FLibrary%2FS3BootScriptLib.h;h=89a4a5666983dc95e9b46698b917252130d2c5d7;hp=3f43da8794693900de49f7121c597475ca13439f;hb=9095d37b8fe5bfc3d02adad6ba7fd7359ebc0107;hpb=d1102dba7210b95e41d06c2338a22ba6af248645
diff --git a/MdePkg/Include/Library/S3BootScriptLib.h b/MdePkg/Include/Library/S3BootScriptLib.h
index 3f43da8794..89a4a56669 100644
--- a/MdePkg/Include/Library/S3BootScriptLib.h
+++ b/MdePkg/Include/Library/S3BootScriptLib.h
@@ -1,11 +1,11 @@
-/** @file
- Defines library APIs used by modules to save EFI Boot Script Opcodes.
- These OpCode will be restored by S3 related modules.
- Note that some of the API defined in the Library class may not
- be provided in the Framework version library instance, which means some of these
+/** @file
+ Defines library APIs used by modules to save EFI Boot Script Opcodes.
+ These OpCode will be restored by S3 related modules.
+ Note that some of the API defined in the Library class may not
+ be provided in the Framework version library instance, which means some of these
APIs cannot be used if the underlying firmware is Framework and not PI.
- Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
This program and the accompanying materials
are licensed and made available under the terms and conditions
@@ -43,14 +43,14 @@
(((UINTN) Device) << 16) | \
(((UINTN) Function) << 8) | \
(((UINTN) (Register)) < 256 ? ((UINTN) (Register)) : (UINT64) (LShiftU64 ((UINT64) (Register), 32))))
-
+
///
/// S3 Boot Script Width.
///
typedef enum {
S3BootScriptWidthUint8, ///< 8-bit operation.
S3BootScriptWidthUint16, ///< 16-bit operation.
- S3BootScriptWidthUint32, ///< 32-bit operation.
+ S3BootScriptWidthUint32, ///< 32-bit operation.
S3BootScriptWidthUint64, ///< 64-bit operation.
S3BootScriptWidthFifoUint8, ///< 8-bit FIFO operation.
S3BootScriptWidthFifoUint16, ///< 16-bit FIFO operation.
@@ -71,7 +71,7 @@ typedef enum {
@param[in] Count The number of I/O operations to perform.
@param[in] Buffer The source buffer from which to write data.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
@@ -94,7 +94,7 @@ S3BootScriptSaveIoWrite (
@param[in] DataMask A pointer to the data mask to be AND-ed with the data
read from the register.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
@@ -116,7 +116,7 @@ S3BootScriptSaveIoReadWrite (
@param[in] Count The number of memory operations to perform.
@param[in] Buffer The source buffer from which to write the data.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -133,13 +133,13 @@ S3BootScriptSaveMemWrite (
Adds a record for a memory modify operation into a specified boot script table.
@param[in] Width The width of the I/O operations.
- @param[in] Address The base address of the memory operations. Address needs
+ @param[in] Address The base address of the memory operations. Address needs
alignment, if required
@param[in] Data A pointer to the data to be OR-ed.
- @param[in] DataMask A pointer to the data mask to be AND-ed with the data
+ @param[in] DataMask A pointer to the data mask to be AND-ed with the data
read from the register.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -160,7 +160,7 @@ S3BootScriptSaveMemReadWrite (
@param[in] Count The number of PCI operations to perform.
@param[in] Buffer The source buffer from which to write the data.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -181,7 +181,7 @@ S3BootScriptSavePciCfgWrite (
@param[in] Data A pointer to the data to be OR-ed.The size depends on Width.
@param[in] DataMask A pointer to the data mask to be AND-ed.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN__SUCCESS The opcode was added.
**/
@@ -203,7 +203,7 @@ S3BootScriptSavePciCfgReadWrite (
@param[in] Count The number of PCI operations to perform.
@param[in] Buffer The source buffer from which to write the data.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -226,7 +226,7 @@ S3BootScriptSavePciCfg2Write (
@param[in] Data A pointer to the data to be OR-ed. The size depends on Width.
@param[in] DataMask A pointer to the data mask to be AND-ed.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -243,23 +243,23 @@ S3BootScriptSavePciCfg2ReadWrite (
/**
Adds a record for an SMBus command execution into a specified boot script table.
- @param[in] SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS
+ @param[in] SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS
Command, SMBUS Data Length, and PEC.
- @param[in] Operation Indicates which particular SMBus protocol it will use
+ @param[in] Operation Indicates which particular SMBus protocol it will use
to execute the SMBus transactions.
- @param[in] Length A pointer to signify the number of bytes that this
+ @param[in] Length A pointer to signify the number of bytes that this
operation will do.
- @param[in] Buffer Contains the value of data to execute to the SMBUS
+ @param[in] Buffer Contains the value of data to execute to the SMBUS
slave device.
-
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
RETURN_STATUS
EFIAPI
S3BootScriptSaveSmbusExecute (
- IN UINTN SmBusAddress,
+ IN UINTN SmBusAddress,
IN EFI_SMBUS_OPERATION Operation,
IN UINTN *Length,
IN VOID *Buffer
@@ -269,8 +269,8 @@ S3BootScriptSaveSmbusExecute (
Adds a record for an execution stall on the processor into a specified boot script table.
@param[in] Duration The duration in microseconds of the stall.
-
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -284,10 +284,10 @@ S3BootScriptSaveStall (
Adds a record for dispatching specified arbitrary code into a specified boot script table.
@param[in] EntryPoint The entry point of the code to be dispatched.
- @param[in] Context The argument to be passed into the EntryPoint of the code
+ @param[in] Context The argument to be passed into the EntryPoint of the code
to be dispatched.
-
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -302,8 +302,8 @@ S3BootScriptSaveDispatch2 (
Adds a record for dispatching specified arbitrary code into a specified boot script table.
@param[in] EntryPoint The entry point of the code to be dispatched.
-
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
**/
@@ -314,7 +314,7 @@ S3BootScriptSaveDispatch (
);
/**
- Adds a record for memory reads of the memory location and continues when the exit
+ Adds a record for memory reads of the memory location and continues when the exit
criteria is satisfied, or after a defined duration.
Please aware, below interface is different with PI specification, Vol 5:
@@ -324,13 +324,13 @@ S3BootScriptSaveDispatch (
@param[in] Width The width of the memory operations.
@param[in] Address The base address of the memory operations.
- @param[in] BitMask A pointer to the bit mask to be AND-ed with the data read
+ @param[in] BitMask A pointer to the bit mask to be AND-ed with the data read
from the register.
@param[in] BitValue A pointer to the data value after to be Masked.
@param[in] Duration The duration in microseconds of the stall.
@param[in] LoopTimes The times of the register polling.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
@@ -347,13 +347,13 @@ S3BootScriptSaveMemPoll (
);
/**
- Store arbitrary information in the boot script table. This opcode is a no-op on
+ Store arbitrary information in the boot script table. This opcode is a no-op on
dispatch and is only used for debugging script issues.
-
+
@param[in] InformationLength Length of the data in bytes
@param[in] Information Information to be logged in the boot scrpit
-
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
@@ -361,27 +361,27 @@ S3BootScriptSaveMemPoll (
RETURN_STATUS
EFIAPI
S3BootScriptSaveInformation (
- IN UINT32 InformationLength,
+ IN UINT32 InformationLength,
IN VOID *Information
);
/**
Adds a record for I/O reads the I/O location and continues when the exit criteria
is satisfied, or after a defined duration.
-
- @param Width The width of the I/O operations.
+
+ @param Width The width of the I/O operations.
@param Address The base address of the I/O operations.
@param Data The comparison value used for the polling exit criteria.
- @param DataMask The mask used for the polling criteria. The bits in
- the bytes below Width which are zero in Data are
+ @param DataMask The 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.
- @param Delay The number of 100ns units to poll. Note that timer
- available may be of insufficient granularity, so the
+ @param Delay The number of 100ns units to poll. Note that timer
+ available may be of insufficient granularity, so the
delay may be longer.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
operation.
@retval RETURN_SUCCESS The opcode was added.
- @note The FRAMEWORK version implementation does not support this API
+ @note The FRAMEWORK version implementation does not support this API
**/
RETURN_STATUS
EFIAPI
@@ -389,29 +389,29 @@ S3BootScriptSaveIoPoll (
IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
IN UINT64 Address,
IN VOID *Data,
- IN VOID *DataMask,
- IN UINT64 Delay
+ IN VOID *DataMask,
+ IN UINT64 Delay
);
/**
- Adds a record for PCI configuration space reads and continues when the exit
+ Adds a record for PCI configuration space reads and continues when the exit
criteria is satisfied ,or after a defined duration.
- @param Width The width of the I/O operations.
+ @param Width The width of the I/O operations.
@param Address The address within the PCI configuration space.
- @param Data The comparison value used for the polling exit
+ @param Data The comparison value used for the polling exit
criteria.
- @param DataMask Mask used for the polling criteria. The bits in
+ @param 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.
- @param Delay The number of 100ns units to poll. Note that timer
- available may be of insufficient granularity, so the
+ @param Delay The number of 100ns units to poll. Note that timer
+ available may be of insufficient granularity, so the
delay may be longer.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
operation.
@retval RETURN_SUCCESS The opcode was added.
- @note The FRAMEWORK version implementation does not support this API
+ @note The FRAMEWORK version implementation does not support this API
**/
RETURN_STATUS
EFIAPI
@@ -423,27 +423,27 @@ S3BootScriptSavePciPoll (
IN UINT64 Delay
);
/**
- Adds a record for PCI configuration space reads and continues when the exit criteria
+ Adds a record for PCI configuration space reads and continues when the exit criteria
is satisfied, or after a defined duration.
- @param Width The width of the I/O operations.
+ @param Width The width of the I/O operations.
@param Segment The PCI segment number for Address.
@param Address The address within the PCI configuration space.
- @param Data The comparison value used for the polling exit
+ @param Data The comparison value used for the polling exit
criteria.
- @param DataMask Mask used for the polling criteria. The bits in
+ @param 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
- @param Delay The number of 100ns units to poll. Note that timer
- available may be of insufficient granularity so the delay
+ @param Delay The number of 100ns units to poll. Note that timer
+ available may be of insufficient granularity so the delay
may be longer.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
operation.
@retval RETURN_SUCCESS The opcode was added.
- @note A known Limitations in the implementation: When interpreting the opcode
+ @note A known Limitations in the implementation: When interpreting the opcode
EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE, EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE
- and EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE, the 'Segment' parameter is assumed as
+ and EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE, the 'Segment' parameter is assumed as
Zero, or else, assert.
The FRAMEWORK version implementation does not support this API.
@@ -459,13 +459,13 @@ S3BootScriptSavePci2Poll (
IN UINT64 Delay
);
/**
- Save ASCII string information specified by Buffer to boot script with opcode
+ Save ASCII string information specified by Buffer to boot script with opcode
EFI_BOOT_SCRIPT_INFORMATION_OPCODE.
- @param[in] String The Null-terminated ASCII string to store into the S3 boot
+ @param[in] String The Null-terminated ASCII string to store into the S3 boot
script table.
- @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
+ @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
the operation.
@retval RETURN_SUCCESS The opcode was added.
@@ -477,27 +477,27 @@ S3BootScriptSaveInformationAsciiString (
);
/**
- This is an function to close the S3 boot script table. The function could only
- be called in BOOT time phase. To comply with the Framework spec definition on
+ This is an function to close the S3 boot script table. The function could only
+ be called in BOOT time phase. To comply with the Framework spec definition on
EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable(), this function will fulfill following things:
1. Closes the specified boot script table
- 2. It allocates a new memory pool to duplicate all the boot scripts in the specified table.
- Once this function is called, the table maintained by the library will be destroyed
+ 2. It allocates a new memory pool to duplicate all the boot scripts in the specified table.
+ Once this function is called, the table maintained by the library will be destroyed
after it is copied into the allocated pool.
- 3. Any attempts to add a script record after calling this function will cause a
+ 3. Any attempts to add a script record after calling this function will cause a
new table to be created by the library.
- 4. The base address of the allocated pool will be returned in Address. Note that
- after using the boot script table, the CALLER is responsible for freeing the
- pool that is allocated by this function.
+ 4. The base address of the allocated pool will be returned in Address. Note that
+ after using the boot script table, the CALLER is responsible for freeing the
+ pool that is allocated by this function.
- In Spec PI1.1, this EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable() is retired. This
+ In Spec PI1.1, this EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable() is retired. This
API is supplied here to meet the requirements of the Framework Spec.
-
+
If anyone does call CloseTable() on a real platform, then the caller is responsible
- for figuring out how to get the script to run on an S3 resume because the boot script
+ for figuring out how to get the script to run on an S3 resume because the boot script
maintained by the lib will be destroyed.
-
- @return the base address of the new copy of the boot script table.
+
+ @return the base address of the new copy of the boot script table.
**/
UINT8*
@@ -510,7 +510,7 @@ S3BootScriptCloseTable (
Executes the S3 boot script table.
@retval RETURN_SUCCESS The boot script table was executed successfully.
- @retval RETURN_UNSUPPORTED Invalid script table or opcode.
+ @retval RETURN_UNSUPPORTED Invalid script table or opcode.
**/
RETURN_STATUS
@@ -519,25 +519,25 @@ S3BootScriptExecute (
VOID
);
/**
- Move the last boot script entry to the position
+ Move the last boot script entry to the position
- @param BeforeOrAfter Specifies whether the opcode is stored before
- (TRUE) or after (FALSE) the positionin 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)
+ @param BeforeOrAfter Specifies whether the opcode is stored before
+ (TRUE) or after (FALSE) the positionin 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).
- @param 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, specifies the position of the inserted opcode
+ @param 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, specifies the position of the inserted opcode
in the boot script table.
@retval RETURN_OUT_OF_RESOURCES The table is not available.
- @retval RETURN_INVALID_PARAMETER The Position is not a valid position in the
+ @retval RETURN_INVALID_PARAMETER The Position is not a valid position in the
boot script table.
@retval RETURN_SUCCESS The opcode was inserted.
- @note The FRAMEWORK version implementation does not support this API.
+ @note The FRAMEWORK version implementation does not support this API.
**/
RETURN_STATUS
EFIAPI
@@ -549,28 +549,28 @@ S3BootScriptMoveLastOpcode (
Find a label within the boot script table and, if not present, optionally create it.
@param BeforeOrAfter Specifies whether the opcode is stored before (TRUE)
- or after (FALSE) the position in the boot script table
+ or after (FALSE) the position in the boot script table
specified by Position.
- @param CreateIfNotFound Specifies whether the label will be created if the
+ @param CreateIfNotFound Specifies whether the label will be created if the
label does not exists (TRUE) or not (FALSE).
- @param 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,
- specifies the positionof the inserted opcode in
+ @param 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,
+ specifies the positionof the inserted opcode in
the boot script table.
- @param Label Points to the label which will be inserted in the
+ @param Label Points to the label which will be inserted in the
boot script table.
- @retval EFI_SUCCESS The operation succeeded. A record was added into
+ @retval EFI_SUCCESS The operation succeeded. A record was added into
the specified script table.
- @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script
- is not supported. If the opcode is unknow or not
+ @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script
+ is not supported. If the opcode is unknow or not
supported because of the PCD Feature Flags.
@retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script.
- @note The FRAMEWORK version implementation does not support this API
+ @note The FRAMEWORK version implementation does not support this API
**/
RETURN_STATUS
-EFIAPI
+EFIAPI
S3BootScriptLabel (
IN BOOLEAN BeforeOrAfter,
IN BOOLEAN CreateIfNotFound,
@@ -585,14 +585,14 @@ S3BootScriptLabel (
@retval EFI_SUCCESS The operation succeeded. A record was added into the
specified script table.
- @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script
+ @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script
is not supported. If the opcode is unknow or not s
upported because of the PCD Feature Flags.
@retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script.
- @note The FRAMEWORK version implementation does not support this API
+ @note The FRAMEWORK version implementation does not support this API
**/
RETURN_STATUS
-EFIAPI
+EFIAPI
S3BootScriptCompare (
IN UINT8 *Position1,
IN UINT8 *Position2,