Vlv2TbltDevicePkg/Include/Protocol/I2cSlave.h

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