MdePkg/Include/Protocol/I2cBusConfigurationManagement.h

   1 /** @file
   2   I2C Bus Configuration Management Protocol as defined in the PI 1.3 specification.
   3
   4   The EFI I2C bus configuration management protocol provides platform specific
   5   services that allow the I2C host protocol to reconfigure the switches and multiplexers
   6   and set the clock frequency for the I2C bus. This protocol also enables the I2C host protocol
   7   to reset an I2C device which may be locking up the I2C bus by holding the clock or data line low.
   8
   9   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
  10   SPDX-License-Identifier: BSD-2-Clause-Patent
  11
  12   @par Revision Reference:
  13   This protocol is from PI Version 1.3.
  14
  15 **/
  16
  17 #ifndef __I2C_BUS_CONFIGURATION_MANAGEMENT_H__
  18 #define __I2C_BUS_CONFIGURATION_MANAGEMENT_H__
  19
  20 #define EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_GUID \
  21   { 0x55b71fb5, 0x17c6, 0x410e, { 0xb5, 0xbd, 0x5f, 0xa2, 0xe3, 0xd4, 0x46, 0x6b }}
  22
  23 ///
  24 /// I2C bus configuration management protocol
  25 ///
  26 /// The EFI I2C bus configuration management protocol provides platform
  27 /// specific services that allow the I2C host protocol to reconfigure the
  28 /// switches and multiplexers and set the clock frequency for the I2C bus.
  29 /// This protocol also enables the I2C host protocol to reset an I2C device
  30 /// which may be locking up the I2C bus by holding the clock or data line
  31 /// low.
  32 ///
  33 /// The I2C protocol stack uses the concept of an I2C bus configuration as
  34 /// a way to describe a particular state of the switches and multiplexers
  35 /// in the I2C bus.
  36 ///
  37 /// A simple I2C bus does not have any multiplexers or switches is described
  38 /// to the I2C protocol stack with a single I2C bus configuration which
  39 /// specifies the I2C bus frequency.
  40 ///
  41 /// An I2C bus with switches and multiplexers use an I2C bus configuration
  42 /// to describe each of the unique settings for the switches and multiplexers
  43 /// and the I2C bus frequency.  However the I2C bus configuration management
  44 /// protocol only needs to define the I2C bus configurations that the software
  45 /// uses, which may be a subset of the total.
  46 ///
  47 /// The I2C bus configuration description includes a list of I2C devices
  48 /// which may be accessed when this I2C bus configuration is enabled.  I2C
  49 /// devices before a switch or multiplexer must be included in one I2C bus
  50 /// configuration while I2C devices after a switch or multiplexer are on
  51 /// another I2C bus configuration.
  52 ///
  53 /// The I2C bus configuration management protocol is an optional protocol.
  54 /// When the I2C bus configuration protocol is not defined the I2C host
  55 /// protocol does not start and the I2C master protocol may be used for
  56 /// other purposes such as SMBus traffic.  When the I2C bus configuration
  57 /// protocol is available, the I2C host protocol uses the I2C bus
  58 /// configuration protocol to call into the platform specific code to set
  59 /// the switches and multiplexers and set the maximum I2C bus frequency.
  60 ///
  61 /// The platform designers determine the maximum I2C bus frequency by
  62 /// selecting a frequency which supports all of the I2C devices on the
  63 /// I2C bus for the setting of switches and multiplexers.  The platform
  64 /// designers must validate this against the I2C device data sheets and
  65 /// any limits of the I2C controller or bus length.
  66 ///
  67 /// During I2C device enumeration, the I2C bus driver retrieves the I2C
  68 /// bus configuration that must be used to perform I2C transactions to
  69 /// each I2C device.  This I2C bus configuration value is passed into
  70 /// the I2C host protocol to identify the I2C bus configuration required
  71 /// to access a specific I2C device.  The I2C host protocol calls
  72 /// EnableBusConfiguration() to set the switches and multiplexers in the
  73 /// I2C bus and the I2C clock frequency.  The I2C host protocol may
  74 /// optimize calls to EnableBusConfiguration() by only making the call
  75 /// when the I2C bus configuration value changes between I2C requests.
  76 ///
  77 /// When I2C transactions are required on the same I2C bus to change the
  78 /// state of multiplexers or switches, the I2C master protocol must be
  79 /// used to perform the necessary I2C transactions.
  80 ///
  81 /// It is up to the platform specific code to choose the proper I2C bus
  82 /// configuration when ExitBootServices() is called. Some operating systems
  83 /// are not able to manage the I2C bus configurations and must use the I2C
  84 /// bus configuration that is established by the platform firmware before
  85 /// ExitBootServices() returns.
  86 ///
  87 typedef struct _EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL;
  88
  89
  90 /**
  91   Enable access to an I2C bus configuration.
  92
  93   This routine must be called at or below TPL_NOTIFY.  For synchronous
  94   requests this routine must be called at or below TPL_CALLBACK.
  95
  96   Reconfigure the switches and multiplexers in the I2C bus to enable
  97   access to a specific I2C bus configuration.  Also select the maximum
  98   clock frequency for this I2C bus configuration.
  99
 100   This routine uses the I2C Master protocol to perform I2C transactions
 101   on the local bus.  This eliminates any recursion in the I2C stack for
 102   configuration transactions on the same I2C bus.  This works because the
 103   local I2C bus is idle while the I2C bus configuration is being enabled.
 104
 105   If I2C transactions must be performed on other I2C busses, then the
 106   EFI_I2C_HOST_PROTOCOL, the EFI_I2C_IO_PROTCOL, or a third party I2C
 107   driver interface for a specific device must be used.  This requirement
 108   is because the I2C host protocol controls the flow of requests to the
 109   I2C controller.  Use the EFI_I2C_HOST_PROTOCOL when the I2C device is
 110   not enumerated by the EFI_I2C_ENUMERATE_PROTOCOL.  Use a protocol
 111   produced by a third party driver when it is available or the
 112   EFI_I2C_IO_PROTOCOL when the third party driver is not available but
 113   the device is enumerated with the EFI_I2C_ENUMERATE_PROTOCOL.
 114
 115   When Event is NULL, EnableI2cBusConfiguration operates synchronously
 116   and returns the I2C completion status as its return value.
 117
 118   @param[in]  This            Pointer to an EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL
 119                               structure.
 120   @param[in]  I2cBusConfiguration Index of an I2C bus configuration.  All
 121                                   values in the range of zero to N-1 are
 122                                   valid where N is the total number of I2C
 123                                   bus configurations for an I2C bus.
 124   @param[in]  Event           Event to signal when the transaction is complete
 125   @param[out] I2cStatus       Buffer to receive the transaction status.
 126
 127   @return  When Event is NULL, EnableI2cBusConfiguration operates synchrouously
 128   and returns the I2C completion status as its return value.  In this case it is
 129   recommended to use NULL for I2cStatus.  The values returned from
 130   EnableI2cBusConfiguration are:
 131
 132   @retval EFI_SUCCESS           The asynchronous bus configuration request
 133                                 was successfully started when Event is not
 134                                 NULL.
 135   @retval EFI_SUCCESS           The bus configuration request completed
 136                                 successfully when Event is NULL.
 137   @retval EFI_DEVICE_ERROR      The bus configuration failed.
 138   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
 139
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_ENABLE_I2C_BUS_CONFIGURATION) (
 144   IN CONST EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *This,
 145   IN UINTN                                               I2cBusConfiguration,
 146   IN EFI_EVENT                                           Event      OPTIONAL,
 147   IN EFI_STATUS                                          *I2cStatus OPTIONAL
 148   );
 149
 150 ///
 151 /// I2C bus configuration management protocol
 152 ///
 153 struct _EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL {
 154   ///
 155   /// Enable an I2C bus configuration for use.
 156   ///
 157   EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_ENABLE_I2C_BUS_CONFIGURATION EnableI2cBusConfiguration;
 158 };
 159
 160 ///
 161 /// Reference to variable defined in the .DEC file
 162 ///
 163 extern EFI_GUID gEfiI2cBusConfigurationManagementProtocolGuid;
 164
 165 #endif  //  __I2C_BUS_CONFIGURATION_MANAGEMENT_H__