Vlv2TbltDevicePkg/Include/Protocol/I2cHostMcg.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 #ifndef __I2C_HOST_H__
  17 #define __I2C_HOST_H__
  18
  19 #include <Protocol/I2cMasterMcg.h>
  20
  21 /**
  22   Declare the forward references
  23
  24 **/
  25 typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;
  26 typedef struct _EFI_I2C_HOST_CALLBACKS EFI_I2C_HOST_CALLBACKS;
  27
  28
  29 /**
  30   Queue an I2C operation for execution on the I2C controller.
  31
  32   This routine must be called at or below TPL_NOTIFY.  For synchronous
  33   requests this routine must be called at or below TPL_CALLBACK.
  34
  35   N.B. The typical consumers of this API are the I2C bus driver and
  36   on rare occasions the I2C test application.  Extreme care must be
  37   taken by other consumers of this API to prevent confusing the
  38   third party I2C drivers due to a state change at the I2C device
  39   which the third party I2C drivers did not initiate.  I2C platform
  40   drivers may use this API within these guidelines.
  41
  42   This layer uses the concept of I2C bus configurations to describe
  43   the I2C bus.  An I2C bus configuration is defined as a unique
  44   setting of the multiplexers and switches in the I2C bus which
  45   enable access to one or more I2C devices.  When using a switch
  46   to divide a bus, due to speed differences, the I2C platform layer
  47   would define an I2C bus configuration for the I2C devices on each
  48   side of the switch.  When using a multiplexer, the I2C platform
  49   layer defines an I2C bus configuration for each of the selector
  50   values required to control the multiplexer.  See Figure 1 in the
  51   <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
  52   Specification</a> for a complex I2C bus configuration.
  53
  54   The I2C host driver processes all operations in FIFO order.  Prior to
  55   performing the operation, the I2C host driver calls the I2C platform
  56   driver to reconfigure the switches and multiplexers in the I2C bus
  57   enabling access to the specified I2C device.  The I2C platform driver
  58   also selects the maximum bus speed for the device.  After the I2C bus
  59   is configured, the I2C host driver calls the I2C port driver to
  60   initialize the I2C controller and start the I2C operation.
  61
  62   @param[in] This             Address of an EFI_I2C_HOST_PROTOCOL instance.
  63   @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C
  64                                   device.
  65   @param[in] SlaveAddress     Address of the device on the I2C bus.
  66   @param[in] Event            Event to set for asynchronous operations,
  67                               NULL for synchronous operations
  68   @param[in] RequestPacket    Address of an EFI_I2C_REQUEST_PACKET
  69                               structure describing the I2C operation
  70   @param[out] I2cStatus       Optional buffer to receive the I2C operation
  71                               completion status
  72
  73   @retval EFI_SUCCESS           The operation completed successfully.
  74   @retval EFI_ABORTED           The request did not complete because the driver
  75                                 was shutdown.
  76   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
  77   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
  78                                 This could indicate the slave device is not present.
  79   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
  80   @retval EFI_INVALID_PARAMETER TPL is too high
  81   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
  82   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
  83                                 slave address.  EFI_DEVICE_ERROR may also be
  84                                 returned if the controller cannot distinguish
  85                                 when the NACK occurred.
  86   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
  87   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
  88                                 the event and then read status pointed to by
  89                                 the request packet.
  90   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
  91   @retval EFI_TIMEOUT           The transaction did not complete within an internally
  92                                 specified timeout period.
  93
  94 **/
  95 typedef
  96 EFI_STATUS
  97 (EFIAPI *EFI_I2C_HOST_QUEUE_REQUEST) (
  98   IN CONST EFI_I2C_HOST_PROTOCOL *This,
  99   IN UINTN I2cBusConfiguration,
 100   IN UINTN SlaveAddress,
 101   IN EFI_EVENT Event OPTIONAL,
 102   IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,
 103   OUT EFI_STATUS *I2cStatus OPTIONAL
 104   );
 105
 106 ///
 107 /// Host access to the I2C bus.
 108 ///
 109 struct _EFI_I2C_HOST_PROTOCOL {
 110   ///
 111   /// Queue an operation for execution on the I2C bus
 112   ///
 113   EFI_I2C_HOST_QUEUE_REQUEST QueueRequest;
 114
 115   ///
 116   /// The maximum number of I2C bus configurations
 117   ///
 118   UINTN I2cBusConfigurationCount;
 119
 120   ///
 121   /// The maximum number of bytes the I2C host controller
 122   /// is able to receive from the I2C bus.
 123   ///
 124   UINT32 MaximumReceiveBytes;
 125
 126   ///
 127   /// The maximum number of bytes the I2C host controller
 128   /// is able to send on the I2C bus.
 129   ///
 130   UINT32 MaximumTransmitBytes;
 131
 132   ///
 133   /// The maximum number of bytes in the I2C bus transaction.
 134   ///
 135   UINT32 MaximumTotalBytes;
 136 };
 137
 138 ///
 139 /// GUID for the EFI_I2C_HOST_PROTOCOL
 140 ///
 141 extern EFI_GUID gEfiI2cHostProtocolGuid;
 142
 143 #endif  //  __I2C_HOST_H__