Vlv2DeviceRefCodePkg/ValleyView2Soc/SouthCluster/Include/Protocol/I2cBus.h

   1 /** @file
   2   I2C bus interface
   3
   4   This layer provides I/O access to an I2C device.
   5
   6   Copyright (c) 2012, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __I2C_BUS_H__
  18 #define __I2C_BUS_H__
  19
  20 #include <Protocol/I2cHostMcg.h>
  21
  22 ///
  23 /// I2C bus protocol
  24 ///
  25 typedef struct _EFI_I2C_BUS_PROTOCOL  EFI_I2C_BUS_PROTOCOL;
  26
  27
  28 /**
  29   Perform an I2C operation on the device
  30
  31   This routine must be called at or below TPL_NOTIFY.  For synchronous
  32   requests this routine must be called at or below TPL_CALLBACK.
  33
  34   N.B. The typical consumers of this API are the third party I2C
  35   drivers.  Extreme care must be taken by other consumers of this
  36   API to prevent confusing the third party I2C drivers due to a
  37   state change at the I2C device which the third party I2C drivers
  38   did not initiate.  I2C platform drivers may use this API within
  39   these guidelines.
  40
  41   This routine queues an operation to the I2C controller for execution
  42   on the I2C bus.
  43
  44   As an upper layer driver writer, the following need to be provided
  45   to the platform vendor:
  46
  47   1.  ACPI CID value or string - this is used to connect the upper layer
  48       driver to the device.
  49   2.  Slave address array guidance when the I2C device uses more than one
  50       slave address.  This is used to access the blocks of hardware within
  51       the I2C device.
  52
  53   @param[in] This               Address of an EFI_I2C_BUS_PROTOCOL
  54                                 structure
  55   @param[in] SlaveAddressIndex  Index into an array of slave addresses for
  56                                 the I2C device.  The values in the array are
  57                                 specified by the board designer, with the
  58                                 I2C device driver writer providing the slave
  59                                 address order.
  60
  61                                 For devices that have a single slave address,
  62                                 this value must be zero.  If the I2C device
  63                                 uses more than one slave address then the third
  64                                 party (upper level) I2C driver writer needs to
  65                                 specify the order of entries in the slave address
  66                                 array.
  67
  68                                 \ref ThirdPartyI2cDrivers "Third Party I2C Drivers"
  69                                 section in I2cMaster.h.
  70   @param[in] Event              Event to set for asynchronous operations,
  71                                 NULL for synchronous operations
  72   @param[in] RequestPacket      Address of an EFI_I2C_REQUEST_PACKET
  73                                 structure describing the I2C operation
  74   @param[out] I2cStatus         Optional buffer to receive the I2C operation
  75                                 completion status
  76
  77   @retval EFI_SUCCESS           The operation completed successfully.
  78   @retval EFI_ABORTED           The request did not complete because the driver
  79                                 was shutdown.
  80   @retval EFI_ACCESS_DENIED     Invalid SlaveAddressIndex value
  81   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
  82   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
  83                                 This could indicate the slave device is not present.
  84   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
  85   @retval EFI_INVALID_PARAMETER TPL is too high
  86   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
  87                                 slave address.  EFI_DEVICE_ERROR may also be
  88                                 returned if the controller can not distinguish
  89                                 when the NACK occurred.
  90   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
  91   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
  92                                 the event and then read status pointed to by
  93                                 the request packet.
  94   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
  95   @retval EFI_TIMEOUT           The transaction did not complete within an internally
  96                                 specified timeout period.
  97
  98 **/
  99 typedef
 100 EFI_STATUS
 101 (EFIAPI *EFI_I2C_BUS_START_REQUEST) (
 102   IN CONST EFI_I2C_BUS_PROTOCOL *This,
 103   IN UINTN SlaveAddressIndex,
 104   IN EFI_EVENT Event OPTIONAL,
 105   IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,
 106   OUT EFI_STATUS *I2cStatus OPTIONAL
 107   );
 108
 109 ///
 110 /// The I2C bus protocol enables access to a specific device on the I2C bus.
 111 ///
 112 /// Each I2C device is described as an ACPI node (HID, UID and CID) within the
 113 /// platform layer.  The I2C bus protocol enumerates the I2C devices in the
 114 /// platform and creates a unique handle and device path for each I2C device.
 115 ///
 116 /// I2C slave addressing is abstracted to validate addresses and limit operation
 117 /// to the specified I2C device.  The third party providing the I2C device support
 118 /// provides an ordered list of slave addresses for the I2C device to the team
 119 /// building the platform layer.  The platform team must preserve the order of the
 120 /// supplied list.  SlaveAddressCount is the number of entries in this list or
 121 /// array within the platform layer.  The third party device support references
 122 /// a slave address using an index into the list or array in the range of zero
 123 /// to SlaveAddressCount - 1.
 124 ///
 125 struct _EFI_I2C_BUS_PROTOCOL {
 126   ///
 127   /// Start an I2C operation on the bus
 128   ///
 129   EFI_I2C_BUS_START_REQUEST StartRequest;
 130
 131   ///
 132   /// The maximum number of slave addresses for the I2C device.  The caller may
 133   /// validate this value as a check on the platform layer's configuration.  Slave
 134   /// address selection uses an index value in the range of zero to SlaveAddressCount - 1.
 135   ///
 136   UINTN SlaveAddressCount;
 137
 138   ///
 139   /// Hardware revision - Matches the ACPI _HRV value
 140   ///
 141   /// The HardwareRevision value allows a single driver to support multiple hardware
 142   /// revisions and implement the necessary workarounds for limitations within the
 143   /// hardware.
 144   ///
 145   UINT32 HardwareRevision;
 146
 147   ///
 148   /// The maximum number of bytes the I2C host controller
 149   /// is able to receive from the I2C bus.
 150   ///
 151   UINT32 MaximumReceiveBytes;
 152
 153   ///
 154   /// The maximum number of bytes the I2C host controller
 155   /// is able to send on the I2C bus.
 156   ///
 157   UINT32 MaximumTransmitBytes;
 158
 159   ///
 160   /// The maximum number of bytes in the I2C bus transaction.
 161   ///
 162   UINT32 MaximumTotalBytes;
 163 };
 164
 165 ///
 166 /// GUID for the I2C bus protocol
 167 ///
 168 extern EFI_GUID gEfiI2cBusProtocolGuid;
 169
 170 #endif  //  __I2C_BUS_H__