Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 1 | /** @file |
| 2 | I2C Master Protocol as defined in the PI 1.3 specification. |
| 3 | |
| 4 | This protocol manipulates the I2C host controller to perform transactions as a master |
| 5 | on the I2C bus using the current state of any switches or multiplexers in the I2C bus. |
| 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_MASTER_H__ |
| 16 | #define __I2C_MASTER_H__ |
| 17 | |
| 18 | #include <Pi/PiI2c.h> |
| 19 | |
| 20 | #define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }} |
| 21 | |
| 22 | typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL; |
| 23 | |
| 24 | /** |
| 25 | Set the frequency for the I2C clock line. |
| 26 | |
| 27 | This routine must be called at or below TPL_NOTIFY. |
| 28 | |
| 29 | The software and controller do a best case effort of using the specified |
| 30 | frequency for the I2C bus. If the frequency does not match exactly then |
| 31 | the I2C master protocol selects the next lower frequency to avoid |
| 32 | exceeding the operating conditions for any of the I2C devices on the bus. |
| 33 | For example if 400 KHz was specified and the controller's divide network |
| 34 | only supports 402 KHz or 398 KHz then the I2C master protocol selects 398 |
| 35 | KHz. If there are not lower frequencies available, then return |
| 36 | EFI_UNSUPPORTED. |
| 37 | |
| 38 | @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure |
| 39 | @param[in] BusClockHertz Pointer to the requested I2C bus clock frequency |
| 40 | in Hertz. Upon return this value contains the |
| 41 | actual frequency in use by the I2C controller. |
| 42 | |
| 43 | @retval EFI_SUCCESS The bus frequency was set successfully. |
| 44 | @retval EFI_ALREADY_STARTED The controller is busy with another transaction. |
| 45 | @retval EFI_INVALID_PARAMETER BusClockHertz is NULL |
| 46 | @retval EFI_UNSUPPORTED The controller does not support this frequency. |
| 47 | |
| 48 | **/ |
| 49 | typedef |
| 50 | EFI_STATUS |
| 51 | (EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY)( |
| 52 | IN CONST EFI_I2C_MASTER_PROTOCOL *This, |
| 53 | IN OUT UINTN *BusClockHertz |
| 54 | ); |
| 55 | |
| 56 | /** |
| 57 | Reset the I2C controller and configure it for use |
| 58 | |
| 59 | This routine must be called at or below TPL_NOTIFY. |
| 60 | |
| 61 | The I2C controller is reset. The caller must call SetBusFrequench() after |
| 62 | calling Reset(). |
| 63 | |
| 64 | @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure. |
| 65 | |
| 66 | @retval EFI_SUCCESS The reset completed successfully. |
| 67 | @retval EFI_ALREADY_STARTED The controller is busy with another transaction. |
| 68 | @retval EFI_DEVICE_ERROR The reset operation failed. |
| 69 | |
| 70 | **/ |
| 71 | typedef |
| 72 | EFI_STATUS |
| 73 | (EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET)( |
| 74 | IN CONST EFI_I2C_MASTER_PROTOCOL *This |
| 75 | ); |
| 76 | |
| 77 | /** |
| 78 | Start an I2C transaction on the host controller. |
| 79 | |
| 80 | This routine must be called at or below TPL_NOTIFY. For synchronous |
| 81 | requests this routine must be called at or below TPL_CALLBACK. |
| 82 | |
| 83 | This function initiates an I2C transaction on the controller. To |
| 84 | enable proper error handling by the I2C protocol stack, the I2C |
| 85 | master protocol does not support queuing but instead only manages |
| 86 | one I2C transaction at a time. This API requires that the I2C bus |
| 87 | is in the correct configuration for the I2C transaction. |
| 88 | |
| 89 | The transaction is performed by sending a start-bit and selecting the |
| 90 | I2C device with the specified I2C slave address and then performing |
| 91 | the specified I2C operations. When multiple operations are requested |
| 92 | they are separated with a repeated start bit and the slave address. |
| 93 | The transaction is terminated with a stop bit. |
| 94 | |
| 95 | When Event is NULL, StartRequest operates synchronously and returns |
| 96 | the I2C completion status as its return value. |
| 97 | |
| 98 | When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS |
| 99 | indicating that the I2C transaction was started asynchronously. The |
| 100 | transaction status value is returned in the buffer pointed to by |
| 101 | I2cStatus upon the completion of the I2C transaction when I2cStatus |
| 102 | is not NULL. After the transaction status is returned the Event is |
| 103 | signaled. |
| 104 | |
| 105 | Note: The typical consumer of this API is the I2C host protocol. |
| 106 | Extreme care must be taken by other consumers of this API to prevent |
| 107 | confusing the third party I2C drivers due to a state change at the |
| 108 | I2C device which the third party I2C drivers did not initiate. I2C |
| 109 | platform specific code may use this API within these guidelines. |
| 110 | |
| 111 | @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure. |
| 112 | @param[in] SlaveAddress Address of the device on the I2C bus. Set the |
| 113 | I2C_ADDRESSING_10_BIT when using 10-bit addresses, |
| 114 | clear this bit for 7-bit addressing. Bits 0-6 |
| 115 | are used for 7-bit I2C slave addresses and bits |
| 116 | 0-9 are used for 10-bit I2C slave addresses. |
| 117 | @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET |
| 118 | structure describing the I2C transaction. |
| 119 | @param[in] Event Event to signal for asynchronous transactions, |
| 120 | NULL for asynchronous transactions |
| 121 | @param[out] I2cStatus Optional buffer to receive the I2C transaction |
| 122 | completion status |
| 123 | |
| 124 | @retval EFI_SUCCESS The asynchronous transaction was successfully |
| 125 | started when Event is not NULL. |
| 126 | @retval EFI_SUCCESS The transaction completed successfully when |
| 127 | Event is NULL. |
| 128 | @retval EFI_ALREADY_STARTED The controller is busy with another transaction. |
| 129 | @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too |
| 130 | large. |
| 131 | @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the |
| 132 | transaction. |
| 133 | @retval EFI_INVALID_PARAMETER RequestPacket is NULL |
| 134 | @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter |
| 135 | @retval EFI_NO_RESPONSE The I2C device is not responding to the slave |
| 136 | address. EFI_DEVICE_ERROR will be returned if |
| 137 | the controller cannot distinguish when the NACK |
| 138 | occurred. |
| 139 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction |
| 140 | @retval EFI_UNSUPPORTED The controller does not support the requested |
| 141 | transaction. |
| 142 | |
| 143 | **/ |
| 144 | typedef |
| 145 | EFI_STATUS |
| 146 | (EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST)( |
| 147 | IN CONST EFI_I2C_MASTER_PROTOCOL *This, |
| 148 | IN UINTN SlaveAddress, |
| 149 | IN EFI_I2C_REQUEST_PACKET *RequestPacket, |
| 150 | IN EFI_EVENT Event OPTIONAL, |
| 151 | OUT EFI_STATUS *I2cStatus OPTIONAL |
| 152 | ); |
| 153 | |
| 154 | /// |
| 155 | /// I2C master mode protocol |
| 156 | /// |
| 157 | /// This protocol manipulates the I2C host controller to perform transactions as a |
| 158 | /// master on the I2C bus using the current state of any switches or multiplexers |
| 159 | /// in the I2C bus. |
| 160 | /// |
| 161 | struct _EFI_I2C_MASTER_PROTOCOL { |
| 162 | /// |
| 163 | /// Set the clock frequency for the I2C bus. |
| 164 | /// |
| 165 | EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency; |
| 166 | |
| 167 | /// |
| 168 | /// Reset the I2C host controller. |
| 169 | /// |
| 170 | EFI_I2C_MASTER_PROTOCOL_RESET Reset; |
| 171 | |
| 172 | /// |
| 173 | /// Start an I2C transaction in master mode on the host controller. |
| 174 | /// |
| 175 | EFI_I2C_MASTER_PROTOCOL_START_REQUEST StartRequest; |
| 176 | |
| 177 | /// |
| 178 | /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing |
| 179 | /// the capabilities of the I2C host controller. |
| 180 | /// |
| 181 | CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities; |
| 182 | }; |
| 183 | |
| 184 | extern EFI_GUID gEfiI2cMasterProtocolGuid; |
| 185 | |
| 186 | #endif // __I2C_MASTER_H__ |