--- /dev/null
+/** @file\r
+ I2C Bus Configuration Management Protocol as defined in the PI 1.3 specification.\r
+\r
+ The EFI I2C bus configuration management protocol provides platform specific \r
+ services that allow the I2C host protocol to reconfigure the switches and multiplexers \r
+ and set the clock frequency for the I2C bus. This protocol also enables the I2C host protocol \r
+ to reset an I2C device which may be locking up the I2C bus by holding the clock or data line low.\r
+\r
+ Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials \r
+ are licensed and made available under the terms and conditions of the BSD License \r
+ which accompanies this distribution. The full text of the license may be found at \r
+ http://opensource.org/licenses/bsd-license.php \r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+\r
+ @par Revision Reference:\r
+ This protocol is from PI Version 1.3.\r
+\r
+**/\r
+\r
+#ifndef __I2C_BUS_CONFIGURATION_MANAGEMENT_H__\r
+#define __I2C_BUS_CONFIGURATION_MANAGEMENT_H__\r
+\r
+#define EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_GUID \\r
+ { 0x55b71fb5, 0x17c6, 0x410e, { 0xb5, 0xbd, 0x5f, 0xa2, 0xe3, 0xd4, 0x46, 0x6b }}\r
+\r
+///\r
+/// I2C bus configuration management protocol\r
+///\r
+/// The EFI I2C bus configuration management protocol provides platform\r
+/// specific services that allow the I2C host protocol to reconfigure the\r
+/// switches and multiplexers and set the clock frequency for the I2C bus.\r
+/// This protocol also enables the I2C host protocol to reset an I2C device\r
+/// which may be locking up the I2C bus by holding the clock or data line\r
+/// low.\r
+///\r
+/// The I2C protocol stack uses the concept of an I2C bus configuration as\r
+/// a way to describe a particular state of the switches and multiplexers\r
+/// in the I2C bus.\r
+///\r
+/// A simple I2C bus does not have any multiplexers or switches is described\r
+/// to the I2C protocol stack with a single I2C bus configuration which\r
+/// specifies the I2C bus frequency.\r
+///\r
+/// An I2C bus with switches and multiplexers use an I2C bus configuration\r
+/// to describe each of the unique settings for the switches and multiplexers\r
+/// and the I2C bus frequency. However the I2C bus configuration management\r
+/// protocol only needs to define the I2C bus configurations that the software\r
+/// uses, which may be a subset of the total.\r
+///\r
+/// The I2C bus configuration description includes a list of I2C devices\r
+/// which may be accessed when this I2C bus configuration is enabled. I2C\r
+/// devices before a switch or multiplexer must be included in one I2C bus\r
+/// configuration while I2C devices after a switch or multiplexer are on\r
+/// another I2C bus configuration.\r
+///\r
+/// The I2C bus configuration management protocol is an optional protocol.\r
+/// When the I2C bus configuration protocol is not defined the I2C host\r
+/// protocol does not start and the I2C master protocol may be used for\r
+/// other purposes such as SMBus traffic. When the I2C bus configuration\r
+/// protocol is available, the I2C host protocol uses the I2C bus\r
+/// configuration protocol to call into the platform specific code to set\r
+/// the switches and multiplexers and set the maximum I2C bus frequency.\r
+///\r
+/// The platform designers determine the maximum I2C bus frequency by\r
+/// selecting a frequency which supports all of the I2C devices on the\r
+/// I2C bus for the setting of switches and multiplexers. The platform\r
+/// designers must validate this against the I2C device data sheets and\r
+/// any limits of the I2C controller or bus length.\r
+///\r
+/// During I2C device enumeration, the I2C bus driver retrieves the I2C\r
+/// bus configuration that must be used to perform I2C transactions to\r
+/// each I2C device. This I2C bus configuration value is passed into\r
+/// the I2C host protocol to identify the I2C bus configuration required\r
+/// to access a specific I2C device. The I2C host protocol calls\r
+/// EnableBusConfiguration() to set the switches and multiplexers in the\r
+/// I2C bus and the I2C clock frequency. The I2C host protocol may\r
+/// optimize calls to EnableBusConfiguration() by only making the call\r
+/// when the I2C bus configuration value changes between I2C requests.\r
+///\r
+/// When I2C transactions are required on the same I2C bus to change the\r
+/// state of multiplexers or switches, the I2C master protocol must be\r
+/// used to perform the necessary I2C transactions.\r
+///\r
+/// It is up to the platform specific code to choose the proper I2C bus\r
+/// configuration when ExitBootServices() is called. Some operating systems\r
+/// are not able to manage the I2C bus configurations and must use the I2C\r
+/// bus configuration that is established by the platform firmware before\r
+/// ExitBootServices() returns.\r
+///\r
+typedef struct _EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL;\r
+\r
+\r
+/**\r
+ Enable access to an I2C bus configuration.\r
+\r
+ This routine must be called at or below TPL_NOTIFY. For synchronous\r
+ requests this routine must be called at or below TPL_CALLBACK.\r
+\r
+ Reconfigure the switches and multiplexers in the I2C bus to enable\r
+ access to a specific I2C bus configuration. Also select the maximum\r
+ clock frequency for this I2C bus configuration.\r
+\r
+ This routine uses the I2C Master protocol to perform I2C transactions\r
+ on the local bus. This eliminates any recursion in the I2C stack for\r
+ configuration transactions on the same I2C bus. This works because the\r
+ local I2C bus is idle while the I2C bus configuration is being enabled.\r
+\r
+ If I2C transactions must be performed on other I2C busses, then the\r
+ EFI_I2C_HOST_PROTOCOL, the EFI_I2C_IO_PROTCOL, or a third party I2C\r
+ driver interface for a specific device must be used. This requirement\r
+ is because the I2C host protocol controls the flow of requests to the\r
+ I2C controller. Use the EFI_I2C_HOST_PROTOCOL when the I2C device is\r
+ not enumerated by the EFI_I2C_ENUMERATE_PROTOCOL. Use a protocol\r
+ produced by a third party driver when it is available or the\r
+ EFI_I2C_IO_PROTOCOL when the third party driver is not available but\r
+ the device is enumerated with the EFI_I2C_ENUMERATE_PROTOCOL.\r
+\r
+ When Event is NULL, EnableI2cBusConfiguration operates synchronously\r
+ and returns the I2C completion status as its return value.\r
+\r
+ @param[in] This Pointer to an EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL\r
+ structure.\r
+ @param[in] I2cBusConfiguration Index of an I2C bus configuration. All\r
+ values in the range of zero to N-1 are\r
+ valid where N is the total number of I2C\r
+ bus configurations for an I2C bus.\r
+ @param[in] Event Event to signal when the transaction is complete\r
+ @param[out] I2cStatus Buffer to receive the transaction status.\r
+\r
+ @return When Event is NULL, EnableI2cBusConfiguration operates synchrouously\r
+ and returns the I2C completion status as its return value. In this case it is\r
+ recommended to use NULL for I2cStatus. The values returned from\r
+ EnableI2cBusConfiguration are:\r
+\r
+ @retval EFI_SUCCESS The asynchronous bus configuration request\r
+ was successfully started when Event is not\r
+ NULL.\r
+ @retval EFI_SUCCESS The bus configuration request completed\r
+ successfully when Event is NULL.\r
+ @retval EFI_DEVICE_ERROR The bus configuration failed.\r
+ @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_ENABLE_I2C_BUS_CONFIGURATION) (\r
+ IN CONST EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *This,\r
+ IN UINTN I2cBusConfiguration,\r
+ IN EFI_EVENT Event OPTIONAL,\r
+ IN EFI_STATUS *I2cStatus OPTIONAL\r
+ );\r
+\r
+///\r
+/// I2C bus configuration management protocol\r
+///\r
+struct _EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL {\r
+ ///\r
+ /// Enable an I2C bus configuration for use.\r
+ ///\r
+ EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_ENABLE_I2C_BUS_CONFIGURATION EnableI2cBusConfiguration;\r
+};\r
+\r
+///\r
+/// Reference to variable defined in the .DEC file\r
+///\r
+extern EFI_GUID gEfiI2cBusConfigurationManagementProtocolGuid;\r
+\r
+#endif // __I2C_BUS_CONFIGURATION_MANAGEMENT_H__\r
projects / mirror_edk2.git / blobdiff