MdePkg/Include/Protocol/I2cHost.h

   1 /** @file
   2   I2C Host Protocol as defined in the PI 1.3 specification.
   3
   4   This protocol provides callers with the ability to do I/O transactions
   5   to all of the devices on the I2C bus.
   6
   7   Copyright (c) 2013 - 2018, 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_HOST_H__
  22 #define __I2C_HOST_H__
  23
  24 #include <Pi/PiI2c.h>
  25
  26 #define EFI_I2C_HOST_PROTOCOL_GUID  { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}
  27
  28 ///
  29 /// I2C Host Protocol
  30 ///
  31 /// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL
  32 /// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C
  33 /// device on an I2C bus.
  34 ///
  35 /// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to
  36 /// callers to perform transactions to any device on the I2C bus.
  37 /// Internally, the I2C host protocol manages the flow of the I2C
  38 /// transactions to the host controller, keeping them in FIFO order.
  39 /// Prior to each transaction, the I2C host protocol ensures that the
  40 /// switches and multiplexers are properly configured.  The I2C host
  41 /// protocol then starts the transaction on the host controller using
  42 /// the EFI_I2C_MASTER_PROTOCOL.
  43 ///
  44 typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;
  45
  46
  47 /**
  48   Queue an I2C transaction for execution on the I2C controller.
  49
  50   This routine must be called at or below TPL_NOTIFY.  For
  51   synchronous requests this routine must be called at or below
  52   TPL_CALLBACK.
  53
  54   The I2C host protocol uses the concept of I2C bus configurations
  55   to describe the I2C bus.  An I2C bus configuration is defined as
  56   a unique setting of the multiplexers and switches in the I2C bus
  57   which enable access to one or more I2C devices.  When using a
  58   switch to divide a bus, due to bus frequency differences, the
  59   I2C bus configuration management protocol defines an I2C bus
  60   configuration for the I2C devices on each side of the switch.
  61   When using a multiplexer, the I2C bus configuration management
  62   defines an I2C bus configuration for each of the selector values
  63   required to control the multiplexer.  See Figure 1 in the I2C -bus
  64   specification and user manual for a complex I2C bus configuration.
  65
  66   The I2C host protocol processes all transactions in FIFO order.
  67   Prior to performing the transaction, the I2C host protocol calls
  68   EnableI2cBusConfiguration to reconfigure the switches and
  69   multiplexers in the I2C bus enabling access to the specified I2C
  70   device.  The EnableI2cBusConfiguration also selects the I2C bus
  71   frequency for the I2C device.  After the I2C bus is configured,
  72   the I2C host protocol calls the I2C master protocol to start the
  73   I2C transaction.
  74
  75   When Event is NULL, QueueRequest() operates synchronously and
  76   returns the I2C completion status as its return value.
  77
  78   When Event is not NULL, QueueRequest() synchronously returns
  79   EFI_SUCCESS indicating that the asynchronously I2C transaction was
  80   queued.  The values above are returned in the buffer pointed to by
  81   I2cStatus upon the completion of the I2C transaction when I2cStatus
  82   is not NULL.
  83
  84   @param[in] This             Pointer to an EFI_I2C_HOST_PROTOCOL structure.
  85   @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C
  86                                   device
  87   @param[in] SlaveAddress     Address of the device on the I2C bus.  Set
  88                               the I2C_ADDRESSING_10_BIT when using 10-bit
  89                               addresses, clear this bit for 7-bit addressing.
  90                               Bits 0-6 are used for 7-bit I2C slave addresses
  91                               and bits 0-9 are used for 10-bit I2C slave
  92                               addresses.
  93   @param[in] Event            Event to signal for asynchronous transactions,
  94                               NULL for synchronous transactions
  95   @param[in] RequestPacket    Pointer to an EFI_I2C_REQUEST_PACKET structure
  96                               describing the I2C transaction
  97   @param[out] I2cStatus       Optional buffer to receive the I2C transaction
  98                               completion status
  99
 100   @retval EFI_SUCCESS           The asynchronous transaction was successfully
 101                                 queued when Event is not NULL.
 102   @retval EFI_SUCCESS           The transaction completed successfully when
 103                                 Event is NULL.
 104   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is
 105                                 too large.
 106   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
 107                                 transaction.
 108   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 109   @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter
 110   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
 111   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
 112                                 address.  EFI_DEVICE_ERROR will be returned
 113                                 if the controller cannot distinguish when the
 114                                 NACK occurred.
 115   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
 116   @retval EFI_UNSUPPORTED       The controller does not support the requested
 117                                 transaction.
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST) (
 123   IN CONST EFI_I2C_HOST_PROTOCOL *This,
 124   IN UINTN                       I2cBusConfiguration,
 125   IN UINTN                       SlaveAddress,
 126   IN EFI_EVENT                   Event      OPTIONAL,
 127   IN EFI_I2C_REQUEST_PACKET      *RequestPacket,
 128   OUT EFI_STATUS                 *I2cStatus OPTIONAL
 129   );
 130
 131 ///
 132 /// I2C Host Protocol
 133 ///
 134 struct _EFI_I2C_HOST_PROTOCOL {
 135   ///
 136   /// Queue an I2C transaction for execution on the I2C bus
 137   ///
 138   EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST     QueueRequest;
 139
 140   ///
 141   /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure
 142   /// containing the capabilities of the I2C host controller.
 143   ///
 144   CONST EFI_I2C_CONTROLLER_CAPABILITIES   *I2cControllerCapabilities;
 145 };
 146
 147 ///
 148 /// Reference to variable defined in the .DEC file
 149 ///
 150 extern EFI_GUID gEfiI2cHostProtocolGuid;
 151
 152 #endif  //  __I2C_HOST_H__