I2cIo.h File Reference

Data Structures
struct	_EFI_I2C_IO_PROTOCOL

Macros
#define	EFI_I2C_IO_PROTOCOL_GUID   { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}

Typedefs
typedef struct _EFI_I2C_IO_PROTOCOL	EFI_I2C_IO_PROTOCOL
typedef IN UINTN	SlaveAddressIndex
typedef IN UINTN IN EFI_EVENT	Event
typedef IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET *	RequestPacket
typedef IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET OUT EFI_STATUS *	I2cStatus

Functions
typedef	EFI_STATUS (EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST)(IN CONST EFI_I2C_IO_PROTOCOL *This

Variables
EFI_GUID	gEfiI2cIoProtocolGuid

Detailed Description

I2C I/O Protocol as defined in the PI 1.3 specification.

The EFI I2C I/O protocol enables the user to manipulate a single I2C device independent of the host controller and I2C design.

Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Revision Reference:

This protocol is from PI Version 1.3.

Macro Definition Documentation

#define EFI_I2C_IO_PROTOCOL_GUID   { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}

Typedef Documentation

typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL

I2C I/O protocol

The I2C IO protocol enables access to a specific device on the I2C bus.

Each I2C device is identified uniquely in the system by the tuple DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture and part number and is provided by the silicon vendor or the third party I2C device driver writer. The DeviceIndex identifies the part within the system by using a unique number and is created by the board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.

I2C slave addressing is abstracted to validate addresses and limit operation to the specified I2C device. The third party providing the I2C device support provides an ordered list of slave addresses for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL. The order of the list must be preserved.

typedef IN UINTN IN EFI_EVENT Event

typedef IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET OUT EFI_STATUS* I2cStatus

typedef IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET* RequestPacket

typedef IN UINTN SlaveAddressIndex

Function Documentation

typedef EFI_STATUS

(

EFIAPI *

EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST

)

Queue an I2C transaction for execution on the I2C device.

This routine must be called at or below TPL_NOTIFY. For synchronous requests this routine must be called at or below TPL_CALLBACK.

This routine queues an I2C transaction to the I2C controller for execution on the I2C bus.

When Event is NULL, QueueRequest() operates synchronously and returns the I2C completion status as its return value.

When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS indicating that the asynchronous I2C transaction was queued. The values above are returned in the buffer pointed to by I2cStatus upon the completion of the I2C transaction when I2cStatus is not NULL.

The upper layer driver writer provides the following to the platform vendor:

1. Vendor specific GUID for the I2C part
2. Guidance on proper construction of the slave address array when the I2C device uses more than one slave address. The I2C bus protocol uses the SlaveAddressIndex to perform relative to physical address translation to access the blocks of hardware within the I2C device.

Parameters

[in]	This	Pointer to an EFI_I2C_IO_PROTOCOL structure.
[in]	SlaveAddressIndex	Index value into an array of slave addresses for the I2C device. The values in the array are specified by the board designer, with the third party I2C device driver writer providing the slave address order.

For devices that have a single slave address, this value must be zero. If the I2C device uses more than one slave address then the third party (upper level) I2C driver writer needs to specify the order of entries in the slave address array.

Third Party I2C Drivers" section in I2cMaster.h.

Parameters

[in]	Event	Event to signal for asynchronous transactions, NULL for synchronous transactions
[in]	RequestPacket	Pointer to an EFI_I2C_REQUEST_PACKET structure describing the I2C transaction
[out]	I2cStatus	Optional buffer to receive the I2C transaction completion status

Return values

EFI_SUCCESS	The asynchronous transaction was successfully queued when Event is not NULL.
EFI_SUCCESS	The transaction completed successfully when Event is NULL.
EFI_BAD_BUFFER_SIZE	The RequestPacket->LengthInBytes value is too large.
EFI_DEVICE_ERROR	There was an I2C error (NACK) during the transaction.
EFI_INVALID_PARAMETER	RequestPacket is NULL.
EFI_NO_MAPPING	The EFI_I2C_HOST_PROTOCOL could not set the bus configuration required to access this I2C device.
EFI_NO_RESPONSE	The I2C device is not responding to the slave address selected by SlaveAddressIndex. EFI_DEVICE_ERROR will be returned if the controller cannot distinguish when the NACK occurred.
EFI_OUT_OF_RESOURCES	Insufficient memory for I2C transaction
EFI_UNSUPPORTED	The controller does not support the requested transaction.

Variable Documentation

EFI_GUID gEfiI2cIoProtocolGuid

Reference to variable defined in the .DEC file