QuarkSocPkg/QuarkSouthCluster/Library/I2cLib/CommonHeader.h

   1 /** @file
   2 Provides definition of entry point to the common I2C module that produces
   3 common I2C Controller functions used by I2C library services.
   4
   5
   6 Copyright (c) 2013-2015 Intel Corporation.
   7
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12
  13 #ifndef _I2CCOMMON_H_
  14 #define _I2CCOMMON_H_
  15
  16 #include <Uefi.h>
  17 #include <Base.h>
  18
  19 #include <Library/DebugLib.h>
  20 #include <Library/TimerLib.h>
  21 #include <Library/I2cLib.h>
  22 #include <IohAccess.h>
  23 #include <IohCommonDefinitions.h>
  24 #include "I2cRegs.h"
  25
  26 //
  27 // Constants that define I2C Controller timeout and max. polling time.
  28 //
  29 #define MAX_T_POLL_COUNT         100
  30 #define TI2C_POLL                25  // microseconds
  31 #define MAX_STOP_DET_POLL_COUNT ((1000 * 1000) / TI2C_POLL)  // Extreme for expected Stop detect.
  32
  33 /**
  34   The GetI2CIoPortBaseAddress() function gets IO port base address of I2C Controller.
  35
  36   Always reads PCI configuration space to get MMIO base address of I2C Controller.
  37
  38   @return The IO port base address of I2C controller.
  39
  40 **/
  41 UINTN
  42 GetI2CIoPortBaseAddress (
  43   VOID
  44   );
  45
  46 /**
  47   The EnableI2CMmioSpace() function enables access to I2C MMIO space.
  48
  49 **/
  50 VOID
  51 EnableI2CMmioSpace (
  52   VOID
  53   );
  54
  55 /**
  56   The DisableI2CController() functions disables I2C Controller.
  57
  58 **/
  59 VOID
  60 DisableI2CController (
  61   VOID
  62   );
  63
  64 /**
  65   The EnableI2CController() function enables the I2C Controller.
  66
  67 **/
  68 VOID
  69 EnableI2CController (
  70   VOID
  71   );
  72
  73 /**
  74   The WaitForStopDet() function waits until I2C STOP Condition occurs,
  75   indicating transfer completion.
  76
  77   @retval EFI_SUCCESS           Stop detected.
  78   @retval EFI_TIMEOUT           Timeout while waiting for stop condition.
  79   @retval EFI_ABORTED           Tx abort signaled in HW status register.
  80   @retval EFI_DEVICE_ERROR      Tx or Rx overflow detected.
  81
  82 **/
  83 EFI_STATUS
  84 WaitForStopDet (
  85   VOID
  86   );
  87
  88 /**
  89
  90   The InitializeInternal() function initialises internal I2C Controller
  91   register values that are commonly required for I2C Write and Read transfers.
  92
  93   @param AddrMode     I2C Addressing Mode: 7-bit or 10-bit address.
  94
  95   @retval EFI_SUCCESS           I2C Operation completed successfully.
  96
  97 **/
  98 EFI_STATUS
  99 InitializeInternal (
 100   IN EFI_I2C_ADDR_MODE  AddrMode
 101   );
 102
 103 /**
 104
 105   The WriteByte() function provides a standard way to execute a
 106   standard single byte write to an IC2 device (without accessing
 107   sub-addresses), as defined in the I2C Specification.
 108
 109   @param  I2CAddress      I2C Slave device address
 110   @param  Value           The 8-bit value to write.
 111
 112   @retval EFI_SUCCESS           Transfer success.
 113   @retval EFI_UNSUPPORTED       Unsupported input param.
 114   @retval EFI_TIMEOUT           Timeout while waiting xfer.
 115   @retval EFI_ABORTED           Controller aborted xfer.
 116   @retval EFI_DEVICE_ERROR      Device error detected by controller.
 117
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 WriteByte (
 122   IN  UINTN          I2CAddress,
 123   IN  UINT8          Value
 124   );
 125
 126 /**
 127
 128   The ReadByte() function provides a standard way to execute a
 129   standard single byte read to an IC2 device (without accessing
 130   sub-addresses), as defined in the I2C Specification.
 131
 132   @param  I2CAddress      I2C Slave device address
 133   @param  ReturnDataPtr   Pointer to location to receive read byte.
 134
 135   @retval EFI_SUCCESS           Transfer success.
 136   @retval EFI_UNSUPPORTED       Unsupported input param.
 137   @retval EFI_TIMEOUT           Timeout while waiting xfer.
 138   @retval EFI_ABORTED           Controller aborted xfer.
 139   @retval EFI_DEVICE_ERROR      Device error detected by controller.
 140
 141 **/
 142 EFI_STATUS
 143 EFIAPI
 144 ReadByte (
 145   IN  UINTN          I2CAddress,
 146   OUT UINT8          *ReturnDataPtr
 147   );
 148
 149 /**
 150
 151   The WriteMultipleByte() function provides a standard way to execute
 152   multiple byte writes to an IC2 device (e.g. when accessing sub-addresses or
 153   when writing block of data), as defined in the I2C Specification.
 154
 155   @param I2CAddress   The I2C slave address of the device
 156                       with which to communicate.
 157
 158   @param WriteBuffer  Contains the value of byte to be written to the
 159                       I2C slave device.
 160
 161   @param Length       No. of bytes to be written.
 162
 163   @retval EFI_SUCCESS           Transfer success.
 164   @retval EFI_UNSUPPORTED       Unsupported input param.
 165   @retval EFI_TIMEOUT           Timeout while waiting xfer.
 166   @retval EFI_ABORTED           Tx abort signaled in HW status register.
 167   @retval EFI_DEVICE_ERROR      Tx overflow detected.
 168
 169 **/
 170 EFI_STATUS
 171 EFIAPI
 172 WriteMultipleByte (
 173   IN  UINTN          I2CAddress,
 174   IN  UINT8          *WriteBuffer,
 175   IN  UINTN          Length
 176   );
 177
 178 /**
 179
 180   The ReadMultipleByte() function provides a standard way to execute
 181   multiple byte writes to an IC2 device (e.g. when accessing sub-addresses or
 182   when reading block of data), as defined in the I2C Specification (I2C combined
 183   write/read protocol).
 184
 185   @param I2CAddress   The I2C slave address of the device
 186                       with which to communicate.
 187
 188   @param Buffer       Contains the value of byte data written or read from the
 189                       I2C slave device.
 190
 191   @param WriteLength  No. of bytes to be written. In this case data
 192                       written typically contains sub-address or sub-addresses
 193                       in Hi-Lo format, that need to be read (I2C combined
 194                       write/read protocol).
 195
 196   @param ReadLength   No. of bytes to be read from I2C slave device.
 197
 198   @retval EFI_SUCCESS           Transfer success.
 199   @retval EFI_UNSUPPORTED       Unsupported input param.
 200   @retval EFI_TIMEOUT           Timeout while waiting xfer.
 201   @retval EFI_ABORTED           Tx abort signaled in HW status register.
 202   @retval EFI_DEVICE_ERROR      Rx underflow or Rx/Tx overflow detected.
 203
 204 **/
 205 EFI_STATUS
 206 EFIAPI
 207 ReadMultipleByte (
 208   IN  UINTN          I2CAddress,
 209   IN  OUT UINT8      *Buffer,
 210   IN  UINTN          WriteLength,
 211   IN  UINTN          ReadLength
 212   );
 213
 214 #endif