5. SMBus PPI Code Definitions¶

5.1. Introduction¶

This section contains the basic definitions for PEIMs and SMBus devices to use during the PEI phase. The following PPI is defined in this section:

EFI_PEI_SMBUS2_PPI

This section also contains the definitions for additional SMBus-related data types and structures that are subordinate to the structures in which they are called. All of the data structures below except for EFI_PEI_SMBUS_NOTIFY_FUNCTION can be used in the DXE phase as well. The following types or structures can be found in “Related Definitions” of the parent function definition:

EFI_SMBUS_DEVICE_ADDRESS
EFI_SMBUS_DEVICE_COMMAND
EFI_SMBUS_OPERATION
EFI_SMBUS_UDID
EFI_SMBUS_DEVICE_MAP
EFI_PEI_SMBUS_NOTIFY_FUNCTION

5.2. PEI SMBus PPI¶

5.2.1. EFI_PEI_SMBUS2_PPI¶

Summary

Provides the basic I/O interfaces that a PEIM uses to access its SMBus controller and the slave devices attached to it.

GUID

#define EFI_PEI_SMBUS2_PPI_GUID \\
{ 0x9ca93627, 0xb65b, 0x4324, \\
0xa2, 0x2, 0xc0, 0xb4, 0x61, 0x76, 0x45, 0x43 }

PPI Interface Structure

typedef struct \_EFI_PEI_SMBUS2_PPI {
EFI_PEI_SMBUS2_PPI_EXECUTE_OPERATION Execute;
EFI_PEI_SMBUS2_PPI_ARP_DEVICE ArpDevice;
EFI_PEI_SMBUS2_PPI_GET_ARP_MAP GetArpMap;
EFI_PEI_SMBUS2_PPI_NOTIFY Notify;
EFI_GUID Identifier
} EFI_PEI_SMBUS2_PPI;

Parameters

Execute: Executes the SMBus operation to an SMBus slave device. See the Execute() function description.
ArpDevice: Allows an SMBus 2.0 device(s) to be Address Resolution Protocol (ARP). See the ArpDevice() function description.
GetArpMap: Allows a PEIM to retrieve the address that was allocated by the SMBus host controller during enumeration/ARP. See the GetArpMap() function description.
Notify: Allows a PEIM to register for a callback to the SMBus host controller PEIM when the bus issues a notification to the bus controller PEIM. See the Notify() function description.
Identifier: Identifier which uniquely identifies this SMBus controller in a system.

Description

The EFI_PEI_SMBUS2_PPI provides the basic I/O interfaces that are used to abstract accesses to SMBus host controllers. There is one EFI_PEI_SMBUS2_PPI instance for each SMBus host controller in a system. A PEIM that wishes to manage an SMBus slave device in a system will have to retrieve the EFI_PEI_SMBUS2_PPI instance that is associated with its SMBus host controller.

5.2.2. EFI_PEI_SMBUS2_PPI.Execute()¶

Summary

Executes an SMBus operation to an SMBus controller. Returns when either the command has been executed or an error is encountered in doing the operation.

Prototype

typedef
EFI_STATUS
 (EFIAPI \*EFI_PEI_SMBUS2_PPI_EXECUTE_OPERATION) (
  IN CONST EFI_PEI_SMBUS2_PPI \*This,
  IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
  IN EFI_SMBUS_DEVICE_COMMAND Command,
  IN EFI_SMBUS_OPERATION Operation,
  IN BOOLEAN PecCheck,
  IN OUT UINTN \*Length,
  IN OUT VOID \*Buffer
  );

Parameters

This: A pointer to the EFI_PEI_SMBUS2_PPI instance.
SlaveAddress: The SMBUS hardware address to which the SMBUS device is preassigned or allocated. Type EFI_SMBUS_DEVICE_ADDRESS is defined in “Related Definitions” below.
Command: This command is transmitted by the SMBus host controller to the SMBus slave device and the interpretation is SMBus slave device specific. It can mean the offset to a list of functions inside an SMBus slave device. Not all operations or slave devices support this command’s registers. Type EFI_SMBUS_DEVICE_COMMAND is defined in “Related Definitions” below.
Operation: Signifies which particular SMBus hardware protocol instance that it will use to execute the SMBus transactions. This SMBus hardware protocol is defined by the System Management Bus (SMBus) Specification and is not related to UEFI. Type EFI_SMBUS_OPERATION is defined in “Related Definitions” below.
PecCheck: Defines if Packet Error Code (PEC) checking is required for this operation.
Length: Signifies the number of bytes that this operation will do. The maximum number of bytes can be revision specific and operation specific. This parameter will contain the actual number of bytes that are executed for this operation. Not all operations require this argument.
Buffer: Contains the value of data to execute to the SMBus slave device. Not all operations require this argument. The length of this buffer is identified by Length .

Description

The Execute() function provides a standard way to execute an operation as defined in the System Management Bus (SMBus) Specification . The resulting transaction will be either that the SMBus slave devices accept this transaction or that this function returns with error.

//******************************************************\*
// EFI_SMBUS_DEVICE_ADDRESS
//******************************************************\*
typedef struct \_EFI_SMBUS_DEVICE_ADDRESS {
  UINTN SmbusDeviceAddress:7;
} EFI_SMBUS_DEVICE_ADDRESS;

SmbusDeviceAddress: The SMBUS hardware address to which the SMBUS device is preassigned or allocated.

//******************************************************\*
// EFI_SMBUS_DEVICE_COMMAND
//******************************************************\*
typedef UINTN EFI_SMBUS_DEVICE_COMMAND;


//******************************************************\*
// EFI_SMBUS_OPERATION
//******************************************************\*
typedef enum \_EFI_SMBUS_OPERATION {
  EfiSmbusQuickRead,
  EfiSmbusQuickWrite,
  EfiSmbusReceiveByte,
  EfiSmbusSendByte,
  EfiSmbusReadByte,
  EfiSmbusWriteByte,
  EfiSmbusReadWord,
  EfiSmbusWriteWord,
  EfiSmbusReadBlock,
  EfiSmbusWriteBlock,
  EfiSmbusProcessCall,
  EfiSmbusBWBRProcessCall
} EFI_SMBUS_OPERATION;

See the System Management Bus (SMBus) Specification for descriptions of the fields in the above definition.

Status Codes Returned

EFI_SUCCESS	The last data that was returned from the access matched the poll exit criteria
EFI_CRC_ERROR	The checksum is not correct PEC is incorrect
EFI_TIMEOUT	Timeout expired before the operation was completed Timeout is determined by the SMBus host controller device
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources
EFI_DEVICE_ERROR	The request was not completed because a failure reflected 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
EFI_INVALID_PARAMETER	Operation is not defined in EFI_SMBUS_OPERATION
EFI_INVALID_PARAMETER	Length Buffer is NULL for operations except for EfiSmbusQuickRead and EfiSmbusQuickWrite Length is outside the range of valid values
EFI_UNSUPPORTED	The SMBus operation or PEC is not supported
EFI_BUFFER_TOO_SMALL	Buffer is not sufficient for this operation

5.2.3. EFI_PEI_SMBUS2_PPI.ArpDevice()¶

Summary

Sets the SMBus slave device addresses for the device with a given unique ID or enumerates the entire bus.

Prototype

typedef
EFI_STATUS
 (EFIAPI \*EFI_PEI_SMBUS2_PPI_ARP_DEVICE) (
  IN CONST EFI_PEI_SMBUS2_PPI \*This,
  IN BOOLEAN ArpAll,
  IN EFI_SMBUS_UDID \*SmbusUdid, OPTIONAL
  IN OUT EFI_SMBUS_DEVICE_ADDRESS \*SlaveAddress OPTIONAL
  );

Paramaters

This: A pointer to the EFI_PEI_SMBUS2_PPI instance.
ArpAll: A Boolean expression that indicates if the host PEIMs need to enumerate all the devices or enumerate only the device that is identified by SmbusUdid . If ArpAll is TRUE , SmbusUdid and SlaveAddress are optional. If ArpAll is FALSE , ArpDevice will enumerate SmbusUdid and the address will be at SlaveAddress .
SmbusUdid: The targeted SMBus Unique Device Identifier (UDID). The UDID may not exist for SMBus devices with fixed addresses. Type EFI_SMBUS_UDID is defined in “Related Definitions” below.
SlaveAddress: The new SMBus address for the slave device for which the operation is targeted. Type EFI_SMBUS_DEVICE_ADDRESS is defined in EFI_PEI_SMBUS2_PPI.Execute() .

Description

The ArpDevice() function enumerates the entire bus or enumerates a specific device that is identified by SmbusUdid.

//******************************************************\*
// EFI_SMBUS_UDID
//******************************************************\*
typedef struct \_EFI_SMBUS_UDID {
  UINT32 VendorSpecificId;
  UINT16 SubsystemDeviceId;
  UINT16 SubsystemVendorId;
  UINT16 Interface;
  UINT16 DeviceId;
  UINT16 VendorId;
  UINT8 VendorRevision;
  UINT8 DeviceCapabilities;
} EFI_SMBUS_UDID;

VendorSpecificId

A unique number per device.

SubsystemDeviceId

Identifies a specific interface, implementation, or device. The subsystem ID is defined by the party that is identified by the SubsystemVendorId field.

SubsystemVendorId

This field may hold a value that is derived from any of several sources:

The device manufacturer’s ID as assigned by the SBS Implementer’s Forum or the PCI SIG.
The device OEM’s ID as assigned by the SBS Implementer’s Forum or the PCI SIG.
A value that, in combination with the SubsystemDeviceId , can be used to identify an organization or industry group that has defined a particular common device interface specification.

Interface

Identifies the protocol layer interfaces that are supported over the SMBus connection by the device. For example, Alert Standard Format (ASF) and IPMI.

DeviceId

The device ID as assigned by the device manufacturer (identified by the VendorId field).

VendorId

The device manufacturer’s ID as assigned by the SBS Implementer’s Forum or the PCI SIG.

VendorRevision

UDID version number and a silicon revision identification.

DeviceCapabilities

Describes the device’s capabilities.

Status Codes Returned

EFI_SUCCESS	The SMBus slave device address was set
EFI_INVALID_PARAMETER	SlaveAddress is NULL
EFI_OUT_OF_RESOURCES	The request could not be completed due to a lack of resources
EFI_TIMEOUT	The SMBus slave device did not respond
EFI_DEVICE_ERROR	The request was not completed because the transaction failed Device errors are a result of a transaction collision illegal command field or unclaimed cycle host initiated
EFI_UNSUPPORTED	ArpDevice GetArpMap and Notify are not implemented by this PEIM

5.2.4. EFI_PEI_SMBUS2_PPI.GetArpMap()¶

Summary

Returns a pointer to the Address Resolution Protocol (ARP) map that contains the ID/address pair of the slave devices that were enumerated by the SMBus host controller PEIM.

Prototype

typedef
EFI_STATUS
 (EFIAPI \*EFI_PEI_SMBUS2_PPI_GET_ARP_MAP) (
  IN CONST EFI_PEI_SMBUS_PPI \*This,
  IN OUT UINTN \*Length,
  IN OUT EFI_SMBUS_DEVICE_MAP \**SmbusDeviceMap
  );

Parameters

This: A pointer to the EFI_PEI_SMBUS2_PPI instance.
Length: Size of the buffer that contains the SMBus device map.
SmbusDeviceMap: The pointer to the device map as enumerated by the SMBus controller PEIM. Type EFI_SMBUS_DEVICE_MAP is defined in “Related Definitions” below.

Description

The GetArpMap() function returns the mapping of all the SMBus devices that are enumerated by the SMBus host PEIM.

//******************************************************\*
// EFI_SMBUS_DEVICE_MAP
//******************************************************\*
typedef struct \_EFI_SMBUS_DEVICE_MAP {
  EFI_SMBUS_DEVICE_ADDRESS SmbusDeviceAddress;
  EFI_SMBUS_UDID SmbusDeviceUdid;
} EFI_SMBUS_DEVICE_MAP;

SmbusDeviceAddress: The SMBUS hardware address to which the SMBUS device is preassigned or allocated. Type EFI_SMBUS_DEVICE_ADDRESS is defined in EFI_PEI_SMBUS2_PPI.Execute() .
SmbusDeviceUdid: The SMBUS Unique Device Identifier (UDID) as defined in EFI_SMBUS_UDID . Type EFI_SMBUS_UDID is defined in EFI_PEI_SMBUS2_PPI.ArpDevice().

Status Codes Returned

EFI_SUCCESS	The device map was returned correctly in the buffer
EFI_UNSUPPORTED	ArpDevice GetArpMap and Notify are not implemented by this PEIM

5.2.5. EFI_PEI_SMBUS2_PPI.Notify()¶

Summary

Allows a PEIM to register for a callback when the PEIM detects a state that it needs to propagate to other PEIMs that are registered for a callback.

Prototype

typedef
EFI_STATUS
 (EFIAPI \*EFI_PEI_SMBUS2_PPI_NOTIFY) (
  IN CONST EFI_PEI_SMBUS_PPI \*This,
  IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
  IN UINTN Data,
  IN EFI_PEI_SMBUS_NOTIFY2_FUNCTION NotifyFunction
  );

Parameters

This: A pointer to the EFI_PEI_SMBUS2_PPI instance.
SlaveAddress: Address that the host controller detects as sending a message and calls all the registered functions. Type EFI_SMBUS_DEVICE_ADDRESS is defined in EFI_PEI_SMBUS2_PPI.Execute() .
Data: Data that the host controller detects as sending a message and calls all the registered functions.
NotifyFunction: The function to call when the PEIM detects the SlaveAddress and Data pair. Type EFI_PEI_SMBUS_NOTIFY2_FUNCTION is defined in “Related Definitions” below.

Description

The Notify() function registers all the callback functions to allow the PEIM to call these functions when the SlaveAddress / Data pair happens.

//******************************************************\*
// EFI_PEI_SMBUS_NOTIFY2_FUNCTION
//******************************************************\*
typedef
EFI_STATUS
 (EFIAPI \*EFI_PEI_SMBUS_NOTIFY2_FUNCTION) (
  IN CONST EFI_PEI_SMBUS_PPI \*SmbusPpi,
  IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
  IN UINTN Data
  );

SmbusPpi: A pointer to the EFI_PEI_SMBUS2_PPI instance.
SlaveAddress: The SMBUS hardware address to which the SMBUS device is preassigned or allocated. Type EFI_SMBUS_DEVICE_ADDRESS is defined in EFI_PEI_SMBUS2_PPI.Execute() .
Data: Data of the SMBus host notify command that the caller wants to be called.

Status Codes Returned

EFI_SUCCESS	NotifyFunction has been registered
EFI_UNSUPPORTED	ArpDevice GetArpMap and Notify are not implemented by this PEIM