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