3 Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 #include <Protocol/I2cHostMcg.h>
24 typedef struct _EFI_I2C_BUS_PROTOCOL EFI_I2C_BUS_PROTOCOL
;
27 Perform an I2C operation on the device
29 This routine must be called at or below TPL_NOTIFY. For synchronous
30 requests this routine must be called at or below TPL_CALLBACK.
32 N.B. The typical consumers of this API are the third party I2C
33 drivers. Extreme care must be taken by other consumers of this
34 API to prevent confusing the third party I2C drivers due to a
35 state change at the I2C device which the third party I2C drivers
36 did not initiate. I2C platform drivers may use this API within
39 This routine queues an operation to the I2C controller for execution
42 As an upper layer driver writer, the following need to be provided
43 to the platform vendor:
45 1. ACPI CID value or string - this is used to connect the upper layer
47 2. Slave address array guidance when the I2C device uses more than one
48 slave address. This is used to access the blocks of hardware within
51 @param[in] This Address of an EFI_I2C_BUS_PROTOCOL
53 @param[in] SlaveAddressIndex Index into an array of slave addresses for
54 the I2C device. The values in the array are
55 specified by the board designer, with the
56 I2C device driver writer providing the slave
59 For devices that have a single slave address,
60 this value must be zero. If the I2C device
61 uses more than one slave address then the third
62 party (upper level) I2C driver writer needs to
63 specify the order of entries in the slave address
66 \ref ThirdPartyI2cDrivers "Third Party I2C Drivers"
67 section in I2cMaster.h.
68 @param[in] Event Event to set for asynchronous operations,
69 NULL for synchronous operations
70 @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET
71 structure describing the I2C operation
72 @param[out] I2cStatus Optional buffer to receive the I2C operation
75 @retval EFI_SUCCESS The operation completed successfully.
76 @retval EFI_ABORTED The request did not complete because the driver
78 @retval EFI_ACCESS_DENIED Invalid SlaveAddressIndex value
79 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
80 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
81 This could indicate the slave device is not present.
82 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
83 @retval EFI_INVALID_PARAMETER TPL is too high
84 @retval EFI_NO_RESPONSE The I2C device is not responding to the
85 slave address. EFI_DEVICE_ERROR may also be
86 returned if the controller can not distinguish
87 when the NACK occurred.
88 @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
89 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
90 the event and then read status pointed to by
92 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
93 @retval EFI_TIMEOUT The transaction did not complete within an internally
94 specified timeout period.
99 (EFIAPI
*EFI_I2C_BUS_START_REQUEST
) (
100 IN CONST EFI_I2C_BUS_PROTOCOL
*This
,
101 IN UINTN SlaveAddressIndex
,
102 IN EFI_EVENT Event OPTIONAL
,
103 IN CONST EFI_I2C_REQUEST_PACKET
*RequestPacket
,
104 OUT EFI_STATUS
*I2cStatus OPTIONAL
108 // The I2C bus protocol enables access to a specific device on the I2C bus.
110 // Each I2C device is described as an ACPI node (HID, UID and CID) within the
111 // platform layer. The I2C bus protocol enumerates the I2C devices in the
112 // platform and creates a unique handle and device path for each I2C device.
114 // I2C slave addressing is abstracted to validate addresses and limit operation
115 // to the specified I2C device. The third party providing the I2C device support
116 // provides an ordered list of slave addresses for the I2C device to the team
117 // building the platform layer. The platform team must preserve the order of the
118 // supplied list. SlaveAddressCount is the number of entries in this list or
119 // array within the platform layer. The third party device support references
120 // a slave address using an index into the list or array in the range of zero
121 // to SlaveAddressCount - 1.
123 struct _EFI_I2C_BUS_PROTOCOL
{
125 // Start an I2C operation on the bus
127 EFI_I2C_BUS_START_REQUEST StartRequest
;
130 // The maximum number of slave addresses for the I2C device. The caller may
131 // validate this value as a check on the platform layer's configuration. Slave
132 // address selection uses an index value in the range of zero to SlaveAddressCount - 1.
134 UINTN SlaveAddressCount
;
137 // Hardware revision - Matches the ACPI _HRV value
139 // The HardwareRevision value allows a single driver to support multiple hardware
140 // revisions and implement the necessary workarounds for limitations within the
143 UINT32 HardwareRevision
;
146 // The maximum number of bytes the I2C host controller
147 // is able to receive from the I2C bus.
149 UINT32 MaximumReceiveBytes
;
152 // The maximum number of bytes the I2C host controller
153 // is able to send on the I2C bus.
155 UINT32 MaximumTransmitBytes
;
158 // The maximum number of bytes in the I2C bus transaction.
160 UINT32 MaximumTotalBytes
;
164 // GUID for the I2C bus protocol
166 extern EFI_GUID gEfiI2cBusProtocolGuid
;
168 #endif // __I2C_BUS_H__