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