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