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