1 /** @file 2 I2C I/O Protocol as defined in the PI 1.3 specification. 3 4 The EFI I2C I/O protocol enables the user to manipulate a single 5 I2C device independent of the host controller and I2C design. 6 7 Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.<BR> 8 This program and the accompanying materials 9 are licensed and made available under the terms and conditions of the BSD License 10 which accompanies this distribution. The full text of the license may be found at 11 http://opensource.org/licenses/bsd-license.php 12 13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 15 16 @par Revision Reference: 17 This protocol is from PI Version 1.3. 18 19 **/ 20 21 #ifndef __I2C_IO_H__ 22 #define __I2C_IO_H__ 23 24 #include <Pi/PiI2c.h> 25 26 #define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }} 27 28 /// 29 /// I2C I/O protocol 30 /// 31 /// The I2C IO protocol enables access to a specific device on the I2C 32 /// bus. 33 /// 34 /// Each I2C device is identified uniquely in the system by the tuple 35 /// DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture 36 /// and part number and is provided by the silicon vendor or the third 37 /// party I2C device driver writer. The DeviceIndex identifies the part 38 /// within the system by using a unique number and is created by the 39 /// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL. 40 /// 41 /// I2C slave addressing is abstracted to validate addresses and limit 42 /// operation to the specified I2C device. The third party providing 43 /// the I2C device support provides an ordered list of slave addresses 44 /// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL. 45 /// The order of the list must be preserved. 46 /// 47 typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL; 48 49 50 /** 51 Queue an I2C transaction for execution on the I2C device. 52 53 This routine must be called at or below TPL_NOTIFY. For synchronous 54 requests this routine must be called at or below TPL_CALLBACK. 55 56 This routine queues an I2C transaction to the I2C controller for 57 execution on the I2C bus. 58 59 When Event is NULL, QueueRequest() operates synchronously and returns 60 the I2C completion status as its return value. 61 62 When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS 63 indicating that the asynchronous I2C transaction was queued. The values 64 above are returned in the buffer pointed to by I2cStatus upon the 65 completion of the I2C transaction when I2cStatus is not NULL. 66 67 The upper layer driver writer provides the following to the platform 68 vendor: 69 70 1. Vendor specific GUID for the I2C part 71 2. Guidance on proper construction of the slave address array when the 72 I2C device uses more than one slave address. The I2C bus protocol 73 uses the SlaveAddressIndex to perform relative to physical address 74 translation to access the blocks of hardware within the I2C device. 75 76 @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure. 77 @param[in] SlaveAddressIndex Index value into an array of slave addresses 78 for the I2C device. The values in the array 79 are specified by the board designer, with the 80 third party I2C device driver writer providing 81 the slave address order. 82 83 For devices that have a single slave address, 84 this value must be zero. If the I2C device 85 uses more than one slave address then the 86 third party (upper level) I2C driver writer 87 needs to specify the order of entries in the 88 slave address array. 89 90 \ref ThirdPartyI2cDrivers "Third Party I2C 91 Drivers" section in I2cMaster.h. 92 @param[in] Event Event to signal for asynchronous transactions, 93 NULL for synchronous transactions 94 @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure 95 describing the I2C transaction 96 @param[out] I2cStatus Optional buffer to receive the I2C transaction 97 completion status 98 99 @retval EFI_SUCCESS The asynchronous transaction was successfully 100 queued when Event is not NULL. 101 @retval EFI_SUCCESS The transaction completed successfully when 102 Event is NULL. 103 @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too 104 large. 105 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the 106 transaction. 107 @retval EFI_INVALID_PARAMETER RequestPacket is NULL. 108 @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the 109 bus configuration required to access this I2C 110 device. 111 @retval EFI_NO_RESPONSE The I2C device is not responding to the slave 112 address selected by SlaveAddressIndex. 113 EFI_DEVICE_ERROR will be returned if the 114 controller cannot distinguish when the NACK 115 occurred. 116 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction 117 @retval EFI_UNSUPPORTED The controller does not support the requested 118 transaction. 119 120 **/ 121 typedef 122 EFI_STATUS 123 (EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST) ( 124 IN CONST EFI_I2C_IO_PROTOCOL *This, 125 IN UINTN SlaveAddressIndex, 126 IN EFI_EVENT Event OPTIONAL, 127 IN EFI_I2C_REQUEST_PACKET *RequestPacket, 128 OUT EFI_STATUS *I2cStatus OPTIONAL 129 ); 130 131 /// 132 /// I2C I/O protocol 133 /// 134 struct _EFI_I2C_IO_PROTOCOL { 135 /// 136 /// Queue an I2C transaction for execution on the I2C device. 137 /// 138 EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST QueueRequest; 139 140 /// 141 /// Unique value assigned by the silicon manufacture or the third 142 /// party I2C driver writer for the I2C part. This value logically 143 /// combines both the manufacture name and the I2C part number into 144 /// a single value specified as a GUID. 145 /// 146 CONST EFI_GUID *DeviceGuid; 147 148 /// 149 /// Unique ID of the I2C part within the system 150 /// 151 UINT32 DeviceIndex; 152 153 /// 154 /// Hardware revision - ACPI _HRV value. See the Advanced Configuration 155 /// and Power Interface Specification, Revision 5.0 for the field format 156 /// and the Plug and play support for I2C web-page for restriction on values. 157 /// 158 UINT32 HardwareRevision; 159 160 /// 161 /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing 162 /// the capabilities of the I2C host controller. 163 /// 164 CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities; 165 }; 166 167 /// 168 /// Reference to variable defined in the .DEC file 169 /// 170 extern EFI_GUID gEfiI2cIoProtocolGuid; 171 172 #endif // __I2C_IO_H__ 173