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