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