MdePkg/Include/Protocol/I2cMaster.h

   1 /** @file
   2   I2C Master Protocol as defined in the PI 1.3 specification.
   3
   4   This protocol manipulates the I2C host controller to perform transactions as a master
   5   on the I2C bus using the current state of any switches or multiplexers in the I2C bus.
   6
   7   Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
   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   @par Revision Reference:
  17   This protocol is from PI Version 1.3.
  18
  19 **/
  20
  21 #ifndef __I2C_MASTER_H__
  22 #define __I2C_MASTER_H__
  23
  24 #include <Pi/PiI2c.h>
  25
  26 #define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}
  27
  28 typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;
  29
  30 /**
  31   Set the frequency for the I2C clock line.
  32
  33   This routine must be called at or below TPL_NOTIFY.
  34
  35   The software and controller do a best case effort of using the specified
  36   frequency for the I2C bus.  If the frequency does not match exactly then
  37   the I2C master protocol selects the next lower frequency to avoid
  38   exceeding the operating conditions for any of the I2C devices on the bus.
  39   For example if 400 KHz was specified and the controller's divide network
  40   only supports 402 KHz or 398 KHz then the I2C master protocol selects 398
  41   KHz.  If there are not lower frequencies available, then return
  42   EFI_UNSUPPORTED.
  43
  44   @param[in] This           Pointer to an EFI_I2C_MASTER_PROTOCOL structure
  45   @param[in] BusClockHertz  Pointer to the requested I2C bus clock frequency
  46                             in Hertz.  Upon return this value contains the
  47                             actual frequency in use by the I2C controller.
  48
  49   @retval EFI_SUCCESS           The bus frequency was set successfully.
  50   @retval EFI_ALREADY_STARTED   The controller is busy with another transaction.
  51   @retval EFI_INVALID_PARAMETER BusClockHertz is NULL
  52   @retval EFI_UNSUPPORTED       The controller does not support this frequency.
  53
  54 **/
  55 typedef
  56 EFI_STATUS
  57 (EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (
  58   IN CONST EFI_I2C_MASTER_PROTOCOL   *This,
  59   IN OUT UINTN                       *BusClockHertz
  60   );
  61
  62 /**
  63   Reset the I2C controller and configure it for use
  64
  65   This routine must be called at or below TPL_NOTIFY.
  66
  67   The I2C controller is reset.  The caller must call SetBusFrequench() after
  68   calling Reset().
  69
  70   @param[in]     This       Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
  71
  72   @retval EFI_SUCCESS         The reset completed successfully.
  73   @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
  74   @retval EFI_DEVICE_ERROR    The reset operation failed.
  75
  76 **/
  77 typedef
  78 EFI_STATUS
  79 (EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (
  80   IN CONST EFI_I2C_MASTER_PROTOCOL *This
  81   );
  82
  83 /**
  84   Start an I2C transaction on the host controller.
  85
  86   This routine must be called at or below TPL_NOTIFY.  For synchronous
  87   requests this routine must be called at or below TPL_CALLBACK.
  88
  89   This function initiates an I2C transaction on the controller.  To
  90   enable proper error handling by the I2C protocol stack, the I2C
  91   master protocol does not support queuing but instead only manages
  92   one I2C transaction at a time.  This API requires that the I2C bus
  93   is in the correct configuration for the I2C transaction.
  94
  95   The transaction is performed by sending a start-bit and selecting the
  96   I2C device with the specified I2C slave address and then performing
  97   the specified I2C operations.  When multiple operations are requested
  98   they are separated with a repeated start bit and the slave address.
  99   The transaction is terminated with a stop bit.
 100
 101   When Event is NULL, StartRequest operates synchronously and returns
 102   the I2C completion status as its return value.
 103
 104   When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS
 105   indicating that the I2C transaction was started asynchronously.  The
 106   transaction status value is returned in the buffer pointed to by
 107   I2cStatus upon the completion of the I2C transaction when I2cStatus
 108   is not NULL.  After the transaction status is returned the Event is
 109   signaled.
 110
 111   Note: The typical consumer of this API is the I2C host protocol.
 112   Extreme care must be taken by other consumers of this API to prevent
 113   confusing the third party I2C drivers due to a state change at the
 114   I2C device which the third party I2C drivers did not initiate.  I2C
 115   platform specific code may use this API within these guidelines.
 116
 117   @param[in] This           Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
 118   @param[in] SlaveAddress   Address of the device on the I2C bus.  Set the
 119                             I2C_ADDRESSING_10_BIT when using 10-bit addresses,
 120                             clear this bit for 7-bit addressing.  Bits 0-6
 121                             are used for 7-bit I2C slave addresses and bits
 122                             0-9 are used for 10-bit I2C slave addresses.
 123   @param[in] RequestPacket  Pointer to an EFI_I2C_REQUEST_PACKET
 124                             structure describing the I2C transaction.
 125   @param[in] Event          Event to signal for asynchronous transactions,
 126                             NULL for asynchronous transactions
 127   @param[out] I2cStatus     Optional buffer to receive the I2C transaction
 128                             completion status
 129
 130   @retval EFI_SUCCESS           The asynchronous transaction was successfully
 131                                 started when Event is not NULL.
 132   @retval EFI_SUCCESS           The transaction completed successfully when
 133                                 Event is NULL.
 134   @retval EFI_ALREADY_STARTED   The controller is busy with another transaction.
 135   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too
 136                                 large.
 137   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
 138                                 transaction.
 139   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 140   @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter
 141   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
 142                                 address.  EFI_DEVICE_ERROR will be returned if
 143                                 the controller cannot distinguish when the NACK
 144                                 occurred.
 145   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
 146   @retval EFI_UNSUPPORTED       The controller does not support the requested
 147                                 transaction.
 148
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST) (
 153   IN CONST EFI_I2C_MASTER_PROTOCOL *This,
 154   IN UINTN                         SlaveAddress,
 155   IN EFI_I2C_REQUEST_PACKET        *RequestPacket,
 156   IN EFI_EVENT                     Event      OPTIONAL,
 157   OUT EFI_STATUS                   *I2cStatus OPTIONAL
 158   );
 159
 160 ///
 161 /// I2C master mode protocol
 162 ///
 163 /// This protocol manipulates the I2C host controller to perform transactions as a
 164 /// master on the I2C bus using the current state of any switches or multiplexers
 165 /// in the I2C bus.
 166 ///
 167 struct _EFI_I2C_MASTER_PROTOCOL {
 168   ///
 169   /// Set the clock frequency for the I2C bus.
 170   ///
 171   EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;
 172
 173   ///
 174   /// Reset the I2C host controller.
 175   ///
 176   EFI_I2C_MASTER_PROTOCOL_RESET             Reset;
 177
 178   ///
 179   /// Start an I2C transaction in master mode on the host controller.
 180   ///
 181   EFI_I2C_MASTER_PROTOCOL_START_REQUEST     StartRequest;
 182
 183   ///
 184   /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
 185   /// the capabilities of the I2C host controller.
 186   ///
 187   CONST EFI_I2C_CONTROLLER_CAPABILITIES     *I2cControllerCapabilities;
 188 };
 189
 190 extern EFI_GUID gEfiI2cMasterProtocolGuid;
 191
 192 #endif  //  __I2C_MASTER_H__