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