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