1 /*++ 2 3 Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR> 4 5 6 This program and the accompanying materials are licensed and made available under 7 8 the terms and conditions of the BSD License that accompanies this distribution. 9 10 The full text of the license may be found at 11 12 http://opensource.org/licenses/bsd-license.php. 13 14 15 16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 17 18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 19 20 21 22 23 24 **/ 25 26 #ifndef __I2C_SLAVE_H__ 27 #define __I2C_SLAVE_H__ 28 29 #include <Protocol/I2cHostMcg.h> 30 31 /** 32 Declare the forward references 33 34 **/ 35 typedef struct _EFI_I2C_SLAVE_PROTOCOL EFI_I2C_SLAVE_PROTOCOL; ///< I2C slave protocol 36 37 /** 38 The I2C controller received a data byte from the 39 I2C msster. 40 41 @param[in] Context The value passed to the slave enable routine. 42 @param[in] NumberOfBytes Number of data bytes received 43 @param[in] Data Buffer containing the received data bytes 44 45 @retval EFI_SUCCESS ACK the data byte 46 @retval EFI_UNSUPPORTED NACK the data byte 47 48 **/ 49 typedef 50 EFI_STATUS 51 (EFIAPI *EFI_I2C_SLAVE_RECEIVE_DATA) ( 52 IN VOID *Context, 53 IN UINTN NumberOfBytes, 54 IN CONST UINT8 *Data 55 ); 56 57 /** 58 The I2C controller received the start bit from the 59 I2C master. 60 61 @param[in] Context The value passed to the slave enable routine. 62 63 **/ 64 typedef 65 VOID 66 (EFIAPI *EFI_I2C_SLAVE_RECEIVE_START) ( 67 IN VOID *Context, 68 IN UINTN BytesSent, 69 IN EFI_STATUS Status 70 ); 71 72 /** 73 The I2C controller received the stop bit from the 74 I2C master. 75 76 @param[in] Context The value passed to the slave enable routine. 77 @param[in] BytesSent Number of bytes successfully ACKed by the 78 I2C master. This is a hint, not all I2C 79 controllers support the ability to return 80 the number of bytes sent. When it is not 81 possible, the port driver returns zero. 82 @param[in] Status <ul> 83 <li>EFI_SUCCESS - All of the data was successfully sent</li> 84 <li>EFI_ABORTED - The controller was reset</li> 85 <li>EFI_DEVICE_ERROR - A NACK was received when sending the data.</li> 86 <li>EFI_END_OF_FILE - The stop bit was received before all of 87 the data was sent.</li> 88 </ul> 89 90 **/ 91 typedef 92 VOID 93 (EFIAPI *EFI_I2C_SLAVE_RECEIVE_STOP) ( 94 IN VOID *Context, 95 IN UINTN BytesSent, 96 IN EFI_STATUS Status 97 ); 98 99 /** 100 Enable or disable I2C slave operation. 101 102 The ReceiveData callback allows the port driver to return data 103 to the driver or application handling slave mode operations. This 104 is data that a remote master has sent to the local I2C controller. 105 The data may be returned one byte at a time if the controller supports 106 the ability to ACK/NACK on each receive byte. If not, a block of 107 data may be returned by the I2C port driver and the ACK/NACK status 108 is used only as a hint for the port driver. 109 110 The slave mode driver or application should buffer the data until 111 either ReceiveStart or ReceiveStop is called. At that time all of 112 the data is received and the command may be processed. 113 114 ReceiveStart is called when the I2C master is expecting a response. 115 After processing the command, but before sending the response the 116 slave driver or application should mark the command as processed to 117 avoid processing it a second time when ReceiveStop is called. The 118 slave driver or application then calls SendData to send to queue the 119 response data for transmission. The data must remain valid in the 120 WriteBuffer until ReceiveStop is called. 121 122 ReceiveStop is called when the stop bit is received on the I2C bus. 123 The slave driver or application starts processing the command if an 124 command data is pending in the slave driver's or application's buffer. 125 The BytesSent value is a hint to the slave driver or application as 126 to how much data was returned to the I2C master. If the controller 127 does not provide this level of support then this value is set to zero. 128 129 @param[in] This Address of an EFI_I2C_SLAVE_PROTOCOL 130 structure 131 @param[in] SlaveAddress Slave address for the I2C controller 132 @param[in] Context Address of a context structure for use when 133 calling ReceiveData or ReceiveStop 134 @param[in] ReceiveData Called by the I2C port driver as data bytes 135 are received from the master. Response status 136 indicates if the byte is ACKed or NACKed. When 137 data is passed back a byte at a time, the port 138 driver must hold the clock until this callback 139 returns. 140 @param[in] ReceiveStart Called when the I2C controller receives a start bit. 141 @param[in] ReceiveStop Called after all of the data bytes are 142 received. 143 144 @retval EFI_SUCCESS Slave operation is enabled on the controller. 145 @retval EFI_UNSUPPORTED The controller does not support this frequency. 146 147 **/ 148 typedef 149 EFI_STATUS 150 (EFIAPI *EFI_I2C_SLAVE_ENABLE) ( 151 IN CONST EFI_I2C_SLAVE_PROTOCOL *This, 152 IN UINT32 SlaveAddress, 153 IN VOID *Context, 154 IN EFI_I2C_SLAVE_RECEIVE_DATA ReceiveData, 155 IN EFI_I2C_SLAVE_RECEIVE_START ReceiveStart, 156 IN EFI_I2C_SLAVE_RECEIVE_STOP ReceiveStop 157 ); 158 159 /** 160 Send data to the I2C master. 161 162 Port drivers may implement this as a blocking or non-blocking call. 163 The data in the write buffer must remain valid until ReceiveStop or 164 ReceiveStart is called indicating that the I2C master has terminated 165 the transfer. 166 167 @param[in] This Address of an EFI_I2C_SLAVE_PROTOCOL 168 structure 169 @param[in] WriteBytes Number of bytes to write 170 @param[in] WriteBuffer Buffer containing the data to send 171 172 @retval EFI_SUCCESS Data waiting for master access. 173 @retval EFI_INVALID_PARAMETER WriteBuffer is NULL or WriteBytes 174 is zero. 175 176 **/ 177 typedef 178 EFI_STATUS 179 (EFIAPI *EFI_I2C_SLAVE_SEND) ( 180 IN CONST EFI_I2C_SLAVE_PROTOCOL *This, 181 IN UINTN WriteBytes, 182 IN CONST UINT8 *WriteBuffer 183 ); 184 185 /// 186 /// I2C slave protocol 187 /// 188 /// The port driver publishes this protocol when slave mode is 189 /// supported by the controller. 190 /// 191 struct _EFI_I2C_SLAVE_PROTOCOL { 192 /// 193 /// Enable or disable I2C slave operation 194 /// 195 EFI_I2C_SLAVE_ENABLE SlaveEnable; 196 197 /// 198 /// Send data to the I2C master 199 /// 200 EFI_I2C_SLAVE_SEND SendData; 201 }; 202 203 /// 204 /// GUID for the EFI_I2C_SLAVE_PROTOCOL 205 /// 206 extern EFI_GUID gEfiI2cSlaveProtocolGuid; 207 208 #endif // __I2C_SLAVE_H__ 209