MdePkg/Include/Ppi/I2cMaster.h

   1 /** @file
   2   This PPI manipulates the I2C host controller to perform transactions as a master
   3   on the I2C bus using the current state of any switches or multiplexers in the I2C bus.
   4
   5   Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14   @par Revision Reference:
  15   This PPI is introduced in PI Version 1.3.
  16
  17 **/
  18
  19 #ifndef __I2C_MASTER_PPI_H__
  20 #define __I2C_MASTER_PPI_H__
  21
  22 #include <Pi/PiI2c.h>
  23
  24 #define EFI_PEI_I2C_MASTER_PPI_GUID \
  25   { 0xb3bfab9b, 0x9f9c, 0x4e8b, { 0xad, 0x37, 0x7f, 0x8c, 0x51, 0xfc, 0x62, 0x80 }}
  26
  27 typedef struct _EFI_PEI_I2C_MASTER_PPI EFI_PEI_I2C_MASTER_PPI;
  28
  29 /**
  30   Set the frequency for the I2C clock line.
  31
  32   @param This                   Pointer to an EFI_PEI_I2C_MASTER_PPI structure.
  33   @param BusClockHertz          Pointer to the requested I2C bus clock frequency in Hertz.
  34                                 Upon return this value contains the actual frequency
  35                                 in use by the I2C controller.
  36
  37   @retval EFI_SUCCESS           The bus frequency was set successfully.
  38   @retval EFI_INVALID_PARAMETER BusClockHertz is NULL
  39   @retval EFI_UNSUPPORTED       The controller does not support this frequency.
  40
  41 **/
  42 typedef
  43 EFI_STATUS
  44 (EFIAPI *EFI_PEI_I2C_MASTER_PPI_SET_BUS_FREQUENCY) (
  45   IN EFI_PEI_I2C_MASTER_PPI   *This,
  46   IN UINTN                    *BusClockHertz
  47   );
  48
  49 /**
  50   Reset the I2C controller and configure it for use.
  51
  52   @param  This                  Pointer to an EFI_PEI_I2C_MASTER_PPI structure.
  53
  54   @retval EFI_SUCCESS           The reset completed successfully.
  55   @retval EFI_DEVICE_ERROR      The reset operation failed.
  56
  57 **/
  58 typedef
  59 EFI_STATUS
  60 (EFIAPI *EFI_PEI_I2C_MASTER_PPI_RESET) (
  61   IN CONST EFI_PEI_I2C_MASTER_PPI  *This
  62   );
  63
  64 /**
  65   Start an I2C transaction on the host controller.
  66
  67   @param  This                   Pointer to an EFI_PEI_I2C_MASTER_PPI structure.
  68   @param  SlaveAddress           Address of the device on the I2C bus.
  69                                  Set the I2C_ADDRESSING_10_BIT when using 10-bit addresses,
  70                                  clear this bit for 7-bit addressing.
  71                                  Bits 0-6 are used for 7-bit I2C slave addresses and
  72                                  bits 0-9 are used for 10-bit I2C slave addresses.
  73   @param  RequestPacket          Pointer to an EFI_I2C_REQUEST_PACKET structure describing the I2C transaction.
  74
  75   @retval EFI_SUCCESS              The transaction completed successfully.
  76   @retval EFI_BAD_BUFFER_SIZE      The RequestPacket->LengthInBytes value is too large.
  77   @retval EFI_DEVICE_ERROR           There was an I2C error (NACK) during the transaction.
  78   @retval EFI_INVALID_PARAMETER  RequestPacket is NULL
  79   @retval EFI_NO_RESPONSE              The I2C device is not responding to the slave address.
  80                                  EFI_DEVICE_ERROR will be returned if the controller cannot distinguish when the NACK occurred.
  81   @retval EFI_NOT_FOUND          Reserved bit set in the SlaveAddress parameter
  82   @retval EFI_OUT_OF_RESOURCES   Insufficient memory for I2C transaction
  83   @retval EFI_UNSUPPORTED              The controller does not support the requested transaction.
  84
  85 **/
  86 typedef
  87 EFI_STATUS
  88 (EFIAPI *EFI_PEI_I2C_MASTER_PPI_START_REQUEST) (
  89   IN CONST EFI_PEI_I2C_MASTER_PPI     *This,
  90   IN UINTN                            SlaveAddress,
  91   IN EFI_I2C_REQUEST_PACKET           *RequestPacket
  92   );
  93
  94 ///
  95 /// This PPI manipulates the I2C host controller to perform transactions as a master on the I2C bus
  96 /// using the current state of any switches or multiplexers in the I2C bus.
  97 ///
  98 struct _EFI_PEI_I2C_MASTER_PPI {
  99   EFI_PEI_I2C_MASTER_PPI_SET_BUS_FREQUENCY   SetBusFrequency;
 100   EFI_PEI_I2C_MASTER_PPI_RESET               Reset;
 101   EFI_PEI_I2C_MASTER_PPI_START_REQUEST       StartRequest;
 102   CONST EFI_I2C_CONTROLLER_CAPABILITIES      *I2cControllerCapabilities;
 103   EFI_GUID                                   Identifier;
 104 };
 105
 106 extern EFI_GUID gEfiPeiI2cMasterPpiGuid;
 107
 108 #endif