Vlv2TbltDevicePkg/Include/Protocol/I2cSlave.h

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