2 I2C I/O Protocol as defined in the PI 1.3 specification.
4 The EFI I2C I/O protocol enables the user to manipulate a single
5 I2C device independent of the host controller and I2C design.
7 Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
10 @par Revision Reference:
11 This protocol is from PI Version 1.3.
20 #define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}
25 /// The I2C IO protocol enables access to a specific device on the I2C
28 /// Each I2C device is identified uniquely in the system by the tuple
29 /// DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture
30 /// and part number and is provided by the silicon vendor or the third
31 /// party I2C device driver writer. The DeviceIndex identifies the part
32 /// within the system by using a unique number and is created by the
33 /// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.
35 /// I2C slave addressing is abstracted to validate addresses and limit
36 /// operation to the specified I2C device. The third party providing
37 /// the I2C device support provides an ordered list of slave addresses
38 /// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.
39 /// The order of the list must be preserved.
41 typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL
;
44 Queue an I2C transaction for execution on the I2C device.
46 This routine must be called at or below TPL_NOTIFY. For synchronous
47 requests this routine must be called at or below TPL_CALLBACK.
49 This routine queues an I2C transaction to the I2C controller for
50 execution on the I2C bus.
52 When Event is NULL, QueueRequest() operates synchronously and returns
53 the I2C completion status as its return value.
55 When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
56 indicating that the asynchronous I2C transaction was queued. The values
57 above are returned in the buffer pointed to by I2cStatus upon the
58 completion of the I2C transaction when I2cStatus is not NULL.
60 The upper layer driver writer provides the following to the platform
63 1. Vendor specific GUID for the I2C part
64 2. Guidance on proper construction of the slave address array when the
65 I2C device uses more than one slave address. The I2C bus protocol
66 uses the SlaveAddressIndex to perform relative to physical address
67 translation to access the blocks of hardware within the I2C device.
69 @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
70 @param[in] SlaveAddressIndex Index value into an array of slave addresses
71 for the I2C device. The values in the array
72 are specified by the board designer, with the
73 third party I2C device driver writer providing
74 the slave address order.
76 For devices that have a single slave address,
77 this value must be zero. If the I2C device
78 uses more than one slave address then the
79 third party (upper level) I2C driver writer
80 needs to specify the order of entries in the
83 \ref ThirdPartyI2cDrivers "Third Party I2C
84 Drivers" section in I2cMaster.h.
85 @param[in] Event Event to signal for asynchronous transactions,
86 NULL for synchronous transactions
87 @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
88 describing the I2C transaction
89 @param[out] I2cStatus Optional buffer to receive the I2C transaction
92 @retval EFI_SUCCESS The asynchronous transaction was successfully
93 queued when Event is not NULL.
94 @retval EFI_SUCCESS The transaction completed successfully when
96 @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
98 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
100 @retval EFI_INVALID_PARAMETER RequestPacket is NULL.
101 @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
102 bus configuration required to access this I2C
104 @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
105 address selected by SlaveAddressIndex.
106 EFI_DEVICE_ERROR will be returned if the
107 controller cannot distinguish when the NACK
109 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
110 @retval EFI_UNSUPPORTED The controller does not support the requested
116 (EFIAPI
*EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST
)(
117 IN CONST EFI_I2C_IO_PROTOCOL
*This
,
118 IN UINTN SlaveAddressIndex
,
119 IN EFI_EVENT Event OPTIONAL
,
120 IN EFI_I2C_REQUEST_PACKET
*RequestPacket
,
121 OUT EFI_STATUS
*I2cStatus OPTIONAL
127 struct _EFI_I2C_IO_PROTOCOL
{
129 /// Queue an I2C transaction for execution on the I2C device.
131 EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST QueueRequest
;
134 /// Unique value assigned by the silicon manufacture or the third
135 /// party I2C driver writer for the I2C part. This value logically
136 /// combines both the manufacture name and the I2C part number into
137 /// a single value specified as a GUID.
139 CONST EFI_GUID
*DeviceGuid
;
142 /// Unique ID of the I2C part within the system
147 /// Hardware revision - ACPI _HRV value. See the Advanced Configuration
148 /// and Power Interface Specification, Revision 5.0 for the field format
149 /// and the Plug and play support for I2C web-page for restriction on values.
151 UINT32 HardwareRevision
;
154 /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
155 /// the capabilities of the I2C host controller.
157 CONST EFI_I2C_CONTROLLER_CAPABILITIES
*I2cControllerCapabilities
;
161 /// Reference to variable defined in the .DEC file
163 extern EFI_GUID gEfiI2cIoProtocolGuid
;
165 #endif // __I2C_IO_H__