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