I2cHost.h File Reference

Data Structures
struct	_EFI_I2C_HOST_PROTOCOL

Macros
#define	EFI_I2C_HOST_PROTOCOL_GUID   { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}

Typedefs
typedef struct _EFI_I2C_HOST_PROTOCOL	EFI_I2C_HOST_PROTOCOL
typedef IN UINTN	I2cBusConfiguration
typedef IN UINTN IN UINTN	SlaveAddress
typedef IN UINTN IN UINTN IN EFI_EVENT	Event
typedef IN UINTN IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET *	RequestPacket
typedef IN UINTN IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET OUT EFI_STATUS *	I2cStatus

Functions
typedef	EFI_STATUS (EFIAPI *EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST)(IN CONST EFI_I2C_HOST_PROTOCOL *This

Variables
EFI_GUID	gEfiI2cHostProtocolGuid

Detailed Description

I2C Host Protocol as defined in the PI 1.3 specification.

This protocol provides callers with the ability to do I/O transactions to all of the devices on the I2C bus.

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_HOST_PROTOCOL_GUID   { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}

Typedef Documentation

typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL

I2C Host Protocol

The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C device on an I2C bus.

The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to callers to perform transactions to any device on the I2C bus. Internally, the I2C host protocol manages the flow of the I2C transactions to the host controller, keeping them in FIFO order. Prior to each transaction, the I2C host protocol ensures that the switches and multiplexers are properly configured. The I2C host protocol then starts the transaction on the host controller using the EFI_I2C_MASTER_PROTOCOL.

typedef IN UINTN IN UINTN IN EFI_EVENT Event

typedef IN UINTN I2cBusConfiguration

typedef IN UINTN IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET OUT EFI_STATUS* I2cStatus

typedef IN UINTN IN UINTN IN EFI_EVENT IN EFI_I2C_REQUEST_PACKET* RequestPacket

typedef IN UINTN IN UINTN SlaveAddress

Function Documentation

typedef EFI_STATUS

(

EFIAPI *

EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST

)

Queue an I2C transaction for execution on the I2C controller.

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

The I2C host protocol uses the concept of I2C bus configurations to describe the I2C bus. An I2C bus configuration is defined as a unique setting of the multiplexers and switches in the I2C bus which enable access to one or more I2C devices. When using a switch to divide a bus, due to bus frequency differences, the I2C bus configuration management protocol defines an I2C bus configuration for the I2C devices on each side of the switch. When using a multiplexer, the I2C bus configuration management defines an I2C bus configuration for each of the selector values required to control the multiplexer. See Figure 1 in the I2C -bus specification and user manual for a complex I2C bus configuration.

The I2C host protocol processes all transactions in FIFO order. Prior to performing the transaction, the I2C host protocol calls EnableI2cBusConfiguration to reconfigure the switches and multiplexers in the I2C bus enabling access to the specified I2C device. The EnableI2cBusConfiguration also selects the I2C bus frequency for the I2C device. After the I2C bus is configured, the I2C host protocol calls the I2C master protocol to start the I2C transaction.

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 asynchronously 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.

Parameters

[in]	This	Pointer to an EFI_I2C_HOST_PROTOCOL structure.
[in]	I2cBusConfiguration	I2C bus configuration to access the I2C device
[in]	SlaveAddress	Address of the device on the I2C bus. Set the I2C_ADDRESSING_10_BIT when using 10-bit addresses, clear this bit for 7-bit addressing. Bits 0-6 are used for 7-bit I2C slave addresses and bits 0-9 are used for 10-bit I2C slave addresses.
[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_NOT_FOUND	Reserved bit set in the SlaveAddress parameter
EFI_NO_MAPPING	Invalid I2cBusConfiguration value
EFI_NO_RESPONSE	The I2C device is not responding to the slave address. 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 gEfiI2cHostProtocolGuid

Reference to variable defined in the .DEC file