diff options
Diffstat (limited to 'src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/S3SmbusLib.h')
-rw-r--r-- | src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/S3SmbusLib.h | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/S3SmbusLib.h b/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/S3SmbusLib.h new file mode 100644 index 00000000..47172564 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/S3SmbusLib.h @@ -0,0 +1,448 @@ +/** @file + Smbus Library Services that conduct SMBus transactions and enable the operatation + to be replayed during an S3 resume. This library class maps directly on top + of the SmbusLib class. + + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __S3_SMBUS_LIB_H__ +#define __S3_SMBUS_LIB_H__ + +/** + Executes an SMBUS quick read command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + If Status is not NULL, then the status of the executed command is returned in Status. + If PEC is set in SmBusAddress, then ASSERT(). + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_UNSUPPORTED The SMBus operation is not supported. + +**/ +VOID +EFIAPI +S3SmBusQuickRead ( + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS quick write command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + If Status is not NULL, then the status of the executed command is returned in Status. + If PEC is set in SmBusAddress, then ASSERT(). + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_UNSUPPORTED The SMBus operation is not supported. + +**/ +VOID +EFIAPI +S3SmBusQuickWrite ( + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS receive byte command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address field of SmBusAddress is required. + The byte received from the SMBUS is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The byte received from the SMBUS. + +**/ +UINT8 +EFIAPI +S3SmBusReceiveByte ( + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS send byte command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress. + The byte specified by Value is sent. + Only the SMBUS slave address field of SmBusAddress is required. Value is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Command in SmBusAddress is not zero, then ASSERT(). + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[in] Value The 8-bit value to send. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus errors (collisions). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The parameter of Value. + +**/ +UINT8 +EFIAPI +S3SmBusSendByte ( + IN UINTN SmBusAddress, + IN UINT8 Value, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS read data byte command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + The 8-bit value read from the SMBUS is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The byte read from the SMBUS. + +**/ +UINT8 +EFIAPI +S3SmBusReadDataByte ( + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS write data byte command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress. + The 8-bit value specified by Value is written. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + Value is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[in] Value The 8-bit value to write. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The parameter of Value. + +**/ +UINT8 +EFIAPI +S3SmBusWriteDataByte ( + IN UINTN SmBusAddress, + IN UINT8 Value, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS read data word command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + The 16-bit value read from the SMBUS is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The byte read from the SMBUS. + +**/ +UINT16 +EFIAPI +S3SmBusReadDataWord ( + IN UINTN SmBusAddress, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS write data word command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress. + The 16-bit value specified by Value is written. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + Value is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[in] Value The 16-bit value to write. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The parameter of Value. + +**/ +UINT16 +EFIAPI +S3SmBusWriteDataWord ( + IN UINTN SmBusAddress, + IN UINT16 Value, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS process call command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress. + The 16-bit value specified by Value is written. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + The 16-bit value returned by the process call command is returned. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is not zero, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[in] Value The 16-bit value to write. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The 16-bit value returned by the process call command. + +**/ +UINT16 +EFIAPI +S3SmBusProcessCall ( + IN UINTN SmBusAddress, + IN UINT16 Value, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS read block command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress. + Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. + Bytes are read from the SMBUS and stored in Buffer. + The number of bytes read is returned, and will never return a value larger than 32-bytes. + If Status is not NULL, then the status of the executed command is returned in Status. + It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read. + SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. + If Length in SmBusAddress is not zero, then ASSERT(). + If Buffer is NULL, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Buffer The pointer to the buffer to store the bytes read from the SMBUS. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The number of bytes read. + +**/ +UINTN +EFIAPI +S3SmBusReadBlock ( + IN UINTN SmBusAddress, + OUT VOID *Buffer, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS write block command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress. + The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. + Bytes are written to the SMBUS from Buffer. + The number of bytes written is returned, and will never return a value larger than 32-bytes. + If Status is not NULL, then the status of the executed command is returned in Status. + If Length in SmBusAddress is zero or greater than 32, then ASSERT(). + If Buffer is NULL, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[out] Buffer The pointer to the buffer to store the bytes read from the SMBUS. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The number of bytes written. + +**/ +UINTN +EFIAPI +S3SmBusWriteBlock ( + IN UINTN SmBusAddress, + OUT VOID *Buffer, + OUT RETURN_STATUS *Status OPTIONAL + ); + +/** + Executes an SMBUS block process call command, and saves the value in the S3 script to be replayed + on S3 resume. + + Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress. + The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. + Bytes are written to the SMBUS from WriteBuffer. Bytes are then read from the SMBUS into ReadBuffer. + If Status is not NULL, then the status of the executed command is returned in Status. + It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read. + SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. + If Length in SmBusAddress is zero or greater than 32, then ASSERT(). + If WriteBuffer is NULL, then ASSERT(). + If ReadBuffer is NULL, then ASSERT(). + If any reserved bits of SmBusAddress are set, then ASSERT(). + + @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, + SMBUS Command, SMBUS Data Length, and PEC. + @param[in] WriteBuffer The pointer to the buffer of bytes to write to the SMBUS. + @param[out] ReadBuffer The pointer to the buffer of bytes to read from the SMBUS. + @param[out] Status The return status for the executed command. + This is an optional parameter and may be NULL. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_DEVICE_ERROR The request was not completed because a failure + was recorded in the Host Status Register bit. Device errors are a result + of a transaction collision, illegal command field, unclaimed cycle + (host initiated), or bus error (collision). + RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). + RETURN_UNSUPPORTED The SMBus operation is not supported. + + @return The number of bytes written. + +**/ +UINTN +EFIAPI +S3SmBusBlockProcessCall ( + IN UINTN SmBusAddress, + IN VOID *WriteBuffer, + OUT VOID *ReadBuffer, + OUT RETURN_STATUS *Status OPTIONAL + ); + +#endif |