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