Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 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__ |