4 This layer provides I/O access to an I2C device.
6 Copyright (c) 2012, Intel Corporation. All rights reserved.
7 SPDX-License-Identifier: BSD-2-Clause-Patent
14 #include <Protocol/I2cHostMcg.h>
19 typedef struct _EFI_I2C_BUS_PROTOCOL EFI_I2C_BUS_PROTOCOL
;
23 Perform an I2C operation on the device
25 This routine must be called at or below TPL_NOTIFY. For synchronous
26 requests this routine must be called at or below TPL_CALLBACK.
28 N.B. The typical consumers of this API are the third party I2C
29 drivers. Extreme care must be taken by other consumers of this
30 API to prevent confusing the third party I2C drivers due to a
31 state change at the I2C device which the third party I2C drivers
32 did not initiate. I2C platform drivers may use this API within
35 This routine queues an operation to the I2C controller for execution
38 As an upper layer driver writer, the following need to be provided
39 to the platform vendor:
41 1. ACPI CID value or string - this is used to connect the upper layer
43 2. Slave address array guidance when the I2C device uses more than one
44 slave address. This is used to access the blocks of hardware within
47 @param[in] This Address of an EFI_I2C_BUS_PROTOCOL
49 @param[in] SlaveAddressIndex Index into an array of slave addresses for
50 the I2C device. The values in the array are
51 specified by the board designer, with the
52 I2C device driver writer providing the slave
55 For devices that have a single slave address,
56 this value must be zero. If the I2C device
57 uses more than one slave address then the third
58 party (upper level) I2C driver writer needs to
59 specify the order of entries in the slave address
62 \ref ThirdPartyI2cDrivers "Third Party I2C Drivers"
63 section in I2cMaster.h.
64 @param[in] Event Event to set for asynchronous operations,
65 NULL for synchronous operations
66 @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET
67 structure describing the I2C operation
68 @param[out] I2cStatus Optional buffer to receive the I2C operation
71 @retval EFI_SUCCESS The operation completed successfully.
72 @retval EFI_ABORTED The request did not complete because the driver
74 @retval EFI_ACCESS_DENIED Invalid SlaveAddressIndex value
75 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
76 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
77 This could indicate the slave device is not present.
78 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
79 @retval EFI_INVALID_PARAMETER TPL is too high
80 @retval EFI_NO_RESPONSE The I2C device is not responding to the
81 slave address. EFI_DEVICE_ERROR may also be
82 returned if the controller can not distinguish
83 when the NACK occurred.
84 @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
85 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
86 the event and then read status pointed to by
88 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
89 @retval EFI_TIMEOUT The transaction did not complete within an internally
90 specified timeout period.
95 (EFIAPI
*EFI_I2C_BUS_START_REQUEST
) (
96 IN CONST EFI_I2C_BUS_PROTOCOL
*This
,
97 IN UINTN SlaveAddressIndex
,
98 IN EFI_EVENT Event OPTIONAL
,
99 IN CONST EFI_I2C_REQUEST_PACKET
*RequestPacket
,
100 OUT EFI_STATUS
*I2cStatus OPTIONAL
104 /// The I2C bus protocol enables access to a specific device on the I2C bus.
106 /// Each I2C device is described as an ACPI node (HID, UID and CID) within the
107 /// platform layer. The I2C bus protocol enumerates the I2C devices in the
108 /// platform and creates a unique handle and device path for each I2C device.
110 /// I2C slave addressing is abstracted to validate addresses and limit operation
111 /// to the specified I2C device. The third party providing the I2C device support
112 /// provides an ordered list of slave addresses for the I2C device to the team
113 /// building the platform layer. The platform team must preserve the order of the
114 /// supplied list. SlaveAddressCount is the number of entries in this list or
115 /// array within the platform layer. The third party device support references
116 /// a slave address using an index into the list or array in the range of zero
117 /// to SlaveAddressCount - 1.
119 struct _EFI_I2C_BUS_PROTOCOL
{
121 /// Start an I2C operation on the bus
123 EFI_I2C_BUS_START_REQUEST StartRequest
;
126 /// The maximum number of slave addresses for the I2C device. The caller may
127 /// validate this value as a check on the platform layer's configuration. Slave
128 /// address selection uses an index value in the range of zero to SlaveAddressCount - 1.
130 UINTN SlaveAddressCount
;
133 /// Hardware revision - Matches the ACPI _HRV value
135 /// The HardwareRevision value allows a single driver to support multiple hardware
136 /// revisions and implement the necessary workarounds for limitations within the
139 UINT32 HardwareRevision
;
142 /// The maximum number of bytes the I2C host controller
143 /// is able to receive from the I2C bus.
145 UINT32 MaximumReceiveBytes
;
148 /// The maximum number of bytes the I2C host controller
149 /// is able to send on the I2C bus.
151 UINT32 MaximumTransmitBytes
;
154 /// The maximum number of bytes in the I2C bus transaction.
156 UINT32 MaximumTotalBytes
;
160 /// GUID for the I2C bus protocol
162 extern EFI_GUID gEfiI2cBusProtocolGuid
;
164 #endif // __I2C_BUS_H__