diff options
| author | Elvin Li <elvin.li@intel.com> | 2013-08-14 01:14:53 +0000 |
|---|---|---|
| committer | li-elvin <li-elvin@6f19259b-4bc3-4df7-8a09-765794883524> | 2013-08-14 01:14:53 +0000 |
| commit | 4006b0b5506bc2ac299fa4bdb7810107fb2c46b2 (patch) | |
| tree | a99fdc5c85a41a112884ee40ea99ea38f68ee6d2 /MdePkg/Include | |
| parent | 39899436d3c60a0b4f0a945413d9beb814eb444a (diff) | |
| download | edk2-platforms-4006b0b5506bc2ac299fa4bdb7810107fb2c46b2.tar.xz | |
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
Diffstat (limited to 'MdePkg/Include')
| -rw-r--r-- | MdePkg/Include/Pi/PiI2c.h | 307 | ||||
| -rw-r--r-- | MdePkg/Include/Ppi/I2cMaster.h | 108 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/I2cBusConfigurationManagement.h | 171 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/I2cEnumerate.h | 110 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/I2cHost.h | 160 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/I2cIo.h | 175 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/I2cMaster.h | 192 |
7 files changed, 1223 insertions, 0 deletions
diff --git a/MdePkg/Include/Pi/PiI2c.h b/MdePkg/Include/Pi/PiI2c.h new file mode 100644 index 0000000000..d7e0e2de45 --- /dev/null +++ b/MdePkg/Include/Pi/PiI2c.h @@ -0,0 +1,307 @@ +/** @file
+ Include file matches things in PI.
+
+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 that 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:
+ PI Version 1.3
+
+**/
+
+#ifndef __PI_I2C_H__
+#define __PI_I2C_H__
+
+///
+/// A 10-bit slave address is or'ed with the following value enabling the
+/// I2C protocol stack to address the duplicated address space between 0
+// and 127 in 10-bit mode.
+///
+#define I2C_ADDRESSING_10_BIT 0x80000000
+
+///
+/// I2C controller capabilities
+///
+/// The EFI_I2C_CONTROLLER_CAPABILITIES specifies the capabilities of the
+/// I2C host controller. The StructureSizeInBytes enables variations of
+/// this structure to be identified if there is need to extend this
+/// structure in the future.
+///
+typedef struct {
+ ///
+ /// Length of this data structure in bytes
+ ///
+ UINT32 StructureSizeInBytes;
+
+ ///
+ /// The maximum number of bytes the I2C host controller is able to
+ /// receive from the I2C bus.
+ ///
+ UINT32 MaximumReceiveBytes;
+
+ ///
+ /// The maximum number of bytes the I2C host controller is able to send
+ /// on the I2C bus.
+ ///
+ UINT32 MaximumTransmitBytes;
+
+ ///
+ /// The maximum number of bytes in the I2C bus transaction.
+ ///
+ UINT32 MaximumTotalBytes;
+} EFI_I2C_CONTROLLER_CAPABILITIES;
+
+///
+/// I2C device description
+///
+/// The EFI_I2C_ENUMERATE_PROTOCOL uses the EFI_I2C_DEVICE to describe
+/// the platform specific details associated with an I2C device. This
+/// description is passed to the I2C bus driver during enumeration where
+/// it is made available to the third party I2C device driver via the
+/// EFI_I2C_IO_PROTOCOL.
+///
+typedef struct {
+ ///
+ /// Unique value assigned by the silicon manufacture or the third
+ /// party I2C driver writer for the I2C part. This value logically
+ /// combines both the manufacture name and the I2C part number into
+ /// a single value specified as a GUID.
+ ///
+ CONST EFI_GUID *DeviceGuid;
+
+ ///
+ /// Unique ID of the I2C part within the system
+ ///
+ UINT32 DeviceIndex;
+
+ ///
+ /// Hardware revision - ACPI _HRV value. See the Advanced
+ /// Configuration and Power Interface Specification, Revision 5.0
+ /// for the field format and the Plug and play support for I2C
+ /// web-page for restriction on values.
+ ///
+ /// http://www.acpi.info/spec.htm
+ /// http://msdn.microsoft.com/en-us/library/windows/hardware/jj131711(v=vs.85).aspx
+ ///
+ UINT32 HardwareRevision;
+
+ ///
+ /// I2C bus configuration for the I2C device
+ ///
+ UINT32 I2cBusConfiguration;
+
+ ///
+ /// Number of slave addresses for the I2C device.
+ ///
+ UINT32 SlaveAddressCount;
+
+ ///
+ /// Pointer to the array of slave addresses for the I2C device.
+ ///
+ CONST UINT32 *SlaveAddressArray;
+} EFI_I2C_DEVICE;
+
+///
+/// Define the I2C flags
+///
+/// I2C read operation when set
+#define I2C_FLAG_READ 0x00000001
+
+///
+/// Define the flags for SMBus operation
+///
+/// The following flags are also present in only the first I2C operation
+/// and are ignored when present in other operations. These flags
+/// describe a particular SMB transaction as shown in the following table.
+///
+
+/// SMBus operation
+#define I2C_FLAG_SMBUS_OPERATION 0x00010000
+
+/// SMBus block operation
+/// The flag I2C_FLAG_SMBUS_BLOCK causes the I2C master protocol to update
+/// the LengthInBytes field of the operation in the request packet with
+/// the actual number of bytes read or written. These values are only
+/// valid when the entire I2C transaction is successful.
+/// This flag also changes the LengthInBytes meaning to be: A maximum
+/// of LengthInBytes is to be read from the device. The first byte
+/// read contains the number of bytes remaining to be read, plus an
+/// optional PEC value.
+#define I2C_FLAG_SMBUS_BLOCK 0x00020000
+
+/// SMBus process call operation
+#define I2C_FLAG_SMBUS_PROCESS_CALL 0x00040000
+
+/// SMBus use packet error code (PEC)
+/// Note that the I2C master protocol may clear the I2C_FLAG_SMBUS_PEC bit
+/// to indicate that the PEC value was checked by the hardware and is
+/// not appended to the returned read data.
+///
+#define I2C_FLAG_SMBUS_PEC 0x00080000
+
+//----------------------------------------------------------------------
+///
+/// QuickRead: OperationCount=1,
+/// LengthInBytes=0, Flags=I2C_FLAG_READ
+/// QuickWrite: OperationCount=1,
+/// LengthInBytes=0, Flags=0
+///
+///
+/// ReceiveByte: OperationCount=1,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_READ
+/// ReceiveByte+PEC: OperationCount=1,
+/// LengthInBytes=2, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_READ
+/// | I2C_FLAG_SMBUS_PEC
+///
+///
+/// SendByte: OperationCount=1,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// SendByte+PEC: OperationCount=1,
+/// LengthInBytes=2, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PEC
+///
+///
+/// ReadDataByte: OperationCount=2,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// LengthInBytes=1, Flags=I2C_FLAG_READ
+/// ReadDataByte+PEC: OperationCount=2,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PEC
+/// LengthInBytes=2, Flags=I2C_FLAG_READ
+///
+///
+/// WriteDataByte: OperationCount=1,
+/// LengthInBytes=2, Flags=I2C_FLAG_SMBUS_OPERATION
+/// WriteDataByte+PEC: OperationCount=1,
+/// LengthInBytes=3, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PEC
+///
+///
+/// ReadDataWord: OperationCount=2,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// LengthInBytes=2, Flags=I2C_FLAG_READ
+/// ReadDataWord+PEC: OperationCount=2,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PEC
+/// LengthInBytes=3, Flags=I2C_FLAG_READ
+///
+///
+/// WriteDataWord: OperationCount=1,
+/// LengthInBytes=3, Flags=I2C_FLAG_SMBUS_OPERATION
+/// WriteDataWord+PEC: OperationCount=1,
+/// LengthInBytes=4, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PEC
+///
+///
+/// ReadBlock: OperationCount=2,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_BLOCK
+/// LengthInBytes=33, Flags=I2C_FLAG_READ
+/// ReadBlock+PEC: OperationCount=2,
+/// LengthInBytes=1, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_BLOCK
+/// | I2C_FLAG_SMBUS_PEC
+/// LengthInBytes=34, Flags=I2C_FLAG_READ
+///
+///
+/// WriteBlock: OperationCount=1,
+/// LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_BLOCK
+/// WriteBlock+PEC: OperationCount=1,
+/// LengthInBytes=N+3, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_BLOCK
+/// | I2C_FLAG_SMBUS_PEC
+///
+///
+/// ProcessCall: OperationCount=2,
+/// LengthInBytes=3, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PROCESS_CALL
+/// LengthInBytes=2, Flags=I2C_FLAG_READ
+/// ProcessCall+PEC: OperationCount=2,
+/// LengthInBytes=3, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PROCESS_CALL
+/// | I2C_FLAG_SMBUS_PEC
+/// LengthInBytes=3, Flags=I2C_FLAG_READ
+///
+///
+/// BlkProcessCall: OperationCount=2,
+/// LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PROCESS_CALL
+/// | I2C_FLAG_SMBUS_BLOCK
+/// LengthInBytes=33, Flags=I2C_FLAG_READ
+/// BlkProcessCall+PEC: OperationCount=2,
+/// LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION
+/// | I2C_FLAG_SMBUS_PROCESS_CALL
+/// | I2C_FLAG_SMBUS_BLOCK
+/// | I2C_FLAG_SMBUS_PEC
+/// LengthInBytes=34, Flags=I2C_FLAG_READ
+///
+//----------------------------------------------------------------------
+
+///
+/// I2C device operation
+///
+/// The EFI_I2C_OPERATION describes a subset of an I2C transaction in which
+/// the I2C controller is either sending or receiving bytes from the bus.
+/// Some transactions will consist of a single operation while others will
+/// be two or more.
+///
+/// Note: Some I2C controllers do not support read or write ping (address
+/// only) operation and will return EFI_UNSUPPORTED status when these
+/// operations are requested.
+///
+/// Note: I2C controllers which do not support complex transactions requiring
+/// multiple repeated start bits return EFI_UNSUPPORTED without processing
+/// any of the transaction.
+///
+typedef struct {
+ ///
+ /// Flags to qualify the I2C operation.
+ ///
+ UINT32 Flags;
+
+ ///
+ /// Number of bytes to send to or receive from the I2C device. A ping
+ /// (address only byte/bytes) is indicated by setting the LengthInBytes
+ /// to zero.
+ ///
+ UINT32 LengthInBytes;
+
+ ///
+ /// Pointer to a buffer containing the data to send or to receive from
+ /// the I2C device. The Buffer must be at least LengthInBytes in size.
+ ///
+ UINT8 *Buffer;
+} EFI_I2C_OPERATION;
+
+///
+/// I2C device request
+///
+/// The EFI_I2C_REQUEST_PACKET describes a single I2C transaction. The
+/// transaction starts with a start bit followed by the first operation
+/// in the operation array. Subsequent operations are separated with
+/// repeated start bits and the last operation is followed by a stop bit
+/// which concludes the transaction. Each operation is described by one
+/// of the elements in the Operation array.
+///
+typedef struct {
+ ///
+ /// Number of elements in the operation array
+ ///
+ UINTN OperationCount;
+
+ ///
+ /// Description of the I2C operation
+ ///
+ EFI_I2C_OPERATION Operation [1];
+} EFI_I2C_REQUEST_PACKET;
+
+#endif // __PI_I2C_H__
diff --git a/MdePkg/Include/Ppi/I2cMaster.h b/MdePkg/Include/Ppi/I2cMaster.h new file mode 100644 index 0000000000..a46b055675 --- /dev/null +++ b/MdePkg/Include/Ppi/I2cMaster.h @@ -0,0 +1,108 @@ +/** @file
+ This PPI manipulates the I2C host controller to perform transactions as a master
+ on the I2C bus using the current state of any switches or multiplexers in the I2C bus.
+
+ 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 PPI is introduced in PI Version 1.3.
+
+**/
+
+#ifndef __I2C_MASTER_PPI_H__
+#define __I2C_MASTER_PPI_H__
+
+#include <Pi/PiI2c.h>
+
+#define EFI_PEI_I2C_MASTER_PPI_GUID \
+ { 0xb3bfab9b, 0x9f9c, 0x4e8b, { 0xad, 0x37, 0x7f, 0x8c, 0x51, 0xfc, 0x62, 0x80 }}
+
+typedef struct _EFI_PEI_I2C_MASTER_PPI EFI_PEI_I2C_MASTER_PPI;
+
+/**
+ Set the frequency for the I2C clock line.
+
+ @param This Pointer to an EFI_PEI_I2C_MASTER_PPI structure.
+ @param BusClockHertz Pointer to the requested I2C bus clock frequency in Hertz.
+ Upon return this value contains the actual frequency
+ in use by the I2C controller.
+
+ @retval EFI_SUCCESS The bus frequency was set successfully.
+ @retval EFI_INVALID_PARAMETER BusClockHertz is NULL
+ @retval EFI_UNSUPPORTED The controller does not support this frequency.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_PEI_I2C_MASTER_PPI_SET_BUS_FREQUENCY) (
+ IN EFI_PEI_I2C_MASTER_PPI *This,
+ IN UINTN *BusClockHertz
+ );
+
+/**
+ Reset the I2C controller and configure it for use.
+
+ @param This Pointer to an EFI_PEI_I2C_MASTER_PPI structure.
+
+ @retval EFI_SUCCESS The reset completed successfully.
+ @retval EFI_DEVICE_ERROR The reset operation failed.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_PEI_I2C_MASTER_PPI_RESET) (
+ IN CONST EFI_PEI_I2C_MASTER_PPI *This
+ );
+
+/**
+ Start an I2C transaction on the host controller.
+
+ @param This Pointer to an EFI_PEI_I2C_MASTER_PPI structure.
+ @param SlaveAddress Address of the device on the I2C bus.
+ Set the I2C_ADDRESSING_10_BIT when using 10-bit addresses,
+ clear this bit for 7-bit addressing.
+ Bits 0-6 are used for 7-bit I2C slave addresses and
+ bits 0-9 are used for 10-bit I2C slave addresses.
+ @param RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure describing the I2C transaction.
+
+ @retval EFI_SUCCESS The transaction completed successfully.
+ @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too large.
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the transaction.
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the slave address.
+ EFI_DEVICE_ERROR will be returned if the controller cannot distinguish when the NACK occurred.
+ @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
+ @retval EFI_UNSUPPORTED The controller does not support the requested transaction.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_PEI_I2C_MASTER_PPI_START_REQUEST) (
+ IN CONST EFI_PEI_I2C_MASTER_PPI *This,
+ IN UINTN SlaveAddress,
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket
+ );
+
+///
+/// This PPI manipulates the I2C host controller to perform transactions as a master on the I2C bus
+/// using the current state of any switches or multiplexers in the I2C bus.
+///
+struct _EFI_PEI_I2C_MASTER_PPI {
+ EFI_PEI_I2C_MASTER_PPI_SET_BUS_FREQUENCY SetBusFrequency;
+ EFI_PEI_I2C_MASTER_PPI_RESET Reset;
+ EFI_PEI_I2C_MASTER_PPI_START_REQUEST StartRequest;
+ CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
+ EFI_GUID Identifier;
+};
+
+extern EFI_GUID gEfiPeiI2cMasterPpiGuid;
+
+#endif
diff --git a/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h b/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h new file mode 100644 index 0000000000..68000cf476 --- /dev/null +++ b/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h @@ -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__
diff --git a/MdePkg/Include/Protocol/I2cEnumerate.h b/MdePkg/Include/Protocol/I2cEnumerate.h new file mode 100644 index 0000000000..45e6a26c69 --- /dev/null +++ b/MdePkg/Include/Protocol/I2cEnumerate.h @@ -0,0 +1,110 @@ +/** @file
+ I2C Device Enumerate Protocol as defined in the PI 1.3 specification.
+
+ This protocol supports the enumerations of device on the I2C bus.
+
+ 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_ENUMERATE_H__
+#define __I2C_ENUMERATE_H__
+
+#include <Pi/PiI2c.h>
+
+#define EFI_I2C_ENUMERATE_PROTOCOL_GUID { 0xda8cd7c4, 0x1c00, 0x49e2, { 0x80, 0x3e, 0x52, 0x14, 0xe7, 0x01, 0x89, 0x4c }}
+
+typedef struct _EFI_I2C_ENUMERATE_PROTOCOL EFI_I2C_ENUMERATE_PROTOCOL;
+
+/**
+ Enumerate the I2C devices
+
+ This function enables the caller to traverse the set of I2C devices
+ on an I2C bus.
+
+ @param[in] This The platform data for the next device on
+ the I2C bus was returned successfully.
+ @param[in, out] Device Pointer to a buffer containing an
+ EFI_I2C_DEVICE structure. Enumeration is
+ started by setting the initial EFI_I2C_DEVICE
+ structure pointer to NULL. The buffer
+ receives an EFI_I2C_DEVICE structure pointer
+ to the next I2C device.
+
+ @retval EFI_SUCCESS The platform data for the next device on
+ the I2C bus was returned successfully.
+ @retval EFI_INVALID_PARAMETER Device is NULL
+ @retval EFI_NO_MAPPING *Device does not point to a valid
+ EFI_I2C_DEVICE structure returned in a
+ previous call Enumerate().
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_ENUMERATE_PROTOCOL_ENUMERATE) (
+ IN CONST EFI_I2C_ENUMERATE_PROTOCOL *This,
+ IN OUT CONST EFI_I2C_DEVICE **Device
+ );
+
+/**
+ Get the requested I2C bus frequency for a specified bus configuration.
+
+ This function returns the requested I2C bus clock frequency for the
+ I2cBusConfiguration. This routine is provided for diagnostic purposes
+ and is meant to be called after calling Enumerate to get the
+ I2cBusConfiguration value.
+
+ @param[in] This Pointer to an EFI_I2C_ENUMERATE_PROTOCOL
+ structure.
+ @param[in] I2cBusConfiguration I2C bus configuration to access the I2C
+ device
+ @param[out] *BusClockHertz Pointer to a buffer to receive the I2C
+ bus clock frequency in Hertz
+
+ @retval EFI_SUCCESS The I2C bus frequency was returned
+ successfully.
+ @retval EFI_INVALID_PARAMETER BusClockHertz was NULL
+ @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_ENUMERATE_PROTOCOL_GET_BUS_FREQUENCY) (
+ IN CONST EFI_I2C_ENUMERATE_PROTOCOL *This,
+ IN UINTN I2cBusConfiguration,
+ OUT UINTN *BusClockHertz
+ );
+
+///
+/// I2C Enumerate protocol
+///
+struct _EFI_I2C_ENUMERATE_PROTOCOL {
+ ///
+ /// Traverse the set of I2C devices on an I2C bus. This routine
+ /// returns the next I2C device on an I2C bus.
+ ///
+ EFI_I2C_ENUMERATE_PROTOCOL_ENUMERATE Enumerate;
+
+ ///
+ /// Get the requested I2C bus frequency for a specified bus
+ /// configuration.
+ ///
+ EFI_I2C_ENUMERATE_PROTOCOL_GET_BUS_FREQUENCY GetBusFrequency;
+};
+
+///
+/// Reference to variable defined in the .DEC file
+///
+extern EFI_GUID gEfiI2cEnumerateProtocolGuid;
+
+#endif // __I2C_ENUMERATE_H__
diff --git a/MdePkg/Include/Protocol/I2cHost.h b/MdePkg/Include/Protocol/I2cHost.h new file mode 100644 index 0000000000..12e77a4cce --- /dev/null +++ b/MdePkg/Include/Protocol/I2cHost.h @@ -0,0 +1,160 @@ +/** @file
+ I2C Host Protocol as defined in the PI 1.3 specification.
+
+ This protocol provides callers with the ability to do I/O transactions
+ to all of the devices on the I2C bus.
+
+ 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_HOST_H__
+#define __I2C_HOST_H__
+
+#include <Pi/PiI2c.h>
+
+#define EFI_I2C_HOST_PROTOCOL_GUID { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}
+
+///
+/// I2C Host Protocol
+///
+/// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL
+/// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C
+/// device on an I2C bus.
+///
+/// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to
+/// callers to perform transactions to any device on the I2C bus.
+/// Internally, the I2C host protocol manages the flow of the I2C
+/// transactions to the host controller, keeping them in FIFO order.
+/// Prior to each transaction, the I2C host protocol ensures that the
+/// switches and multiplexers are properly configured. The I2C host
+/// protocol then starts the transaction on the host controller using
+/// the EFI_I2C_MASTER_PROTOCOL.
+///
+typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;
+
+
+/**
+ Queue an I2C transaction for execution on the I2C controller.
+
+ This routine must be called at or below TPL_NOTIFY. For
+ synchronous requests this routine must be called at or below
+ TPL_CALLBACK.
+
+ The I2C host protocol uses the concept of I2C bus configurations
+ to describe the I2C bus. An I2C bus configuration is defined as
+ a unique setting of the multiplexers and switches in the I2C bus
+ which enable access to one or more I2C devices. When using a
+ switch to divide a bus, due to bus frequency differences, the
+ I2C bus configuration management protocol defines an I2C bus
+ configuration for the I2C devices on each side of the switch.
+ When using a multiplexer, the I2C bus configuration management
+ defines an I2C bus configuration for each of the selector values
+ required to control the multiplexer. See Figure 1 in the I2C -bus
+ specification and user manual for a complex I2C bus configuration.
+
+ The I2C host protocol processes all transactions in FIFO order.
+ Prior to performing the transaction, the I2C host protocol calls
+ EnableI2cBusConfiguration to reconfigure the switches and
+ multiplexers in the I2C bus enabling access to the specified I2C
+ device. The EnableI2cBusConfiguration also selects the I2C bus
+ frequency for the I2C device. After the I2C bus is configured,
+ the I2C host protocol calls the I2C master protocol to start the
+ I2C transaction.
+
+ If the I2C host protocol has pending I2C transactions queued when
+ the driver binding Stop() routine is called then the I2C host
+ protocol completes all of the pending I2C transactions by returning
+ EFI_ABORTED status. This notifies the upper layers allowing them
+ to take corrective action or prepare to stop.
+
+ When Event is NULL, QueueRequest() operates synchronously and
+ returns the I2C completion status as its return value.
+
+ When Event is not NULL, QueueRequest() synchronously returns
+ EFI_SUCCESS indicating that the asynchronously I2C transaction was
+ queued. The values above are returned in the buffer pointed to by
+ I2cStatus upon the completion of the I2C transaction when I2cStatus
+ is not NULL.
+
+ @param[in] This Pointer to an EFI_I2C_HOST_PROTOCOL structure.
+ @param[in] I2cBusConfiguration I2C bus configuration to access the I2C
+ device
+ @param[in] SlaveAddress Address of the device on the I2C bus. Set
+ the I2C_ADDRESSING_10_BIT when using 10-bit
+ addresses, clear this bit for 7-bit addressing.
+ Bits 0-6 are used for 7-bit I2C slave addresses
+ and bits 0-9 are used for 10-bit I2C slave
+ addresses.
+ @param[in] Event Event to signal for asynchronous transactions,
+ NULL for synchronous transactions
+ @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
+ describing the I2C transaction
+ @param[out] I2cStatus Optional buffer to receive the I2C transaction
+ completion status
+
+ @retval EFI_SUCCESS The asynchronous transaction was successfully
+ queued when Event is not NULL.
+ @retval EFI_SUCCESS The transaction completed successfully when
+ Event is NULL.
+ @retval EFI_ABORTED The request did not complete because the
+ driver binding Stop() routine was called.
+ @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is
+ too large.
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
+ transaction.
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL
+ @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
+ @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
+ address. EFI_DEVICE_ERROR will be returned
+ if the controller cannot distinguish when the
+ NACK occurred.
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
+ @retval EFI_UNSUPPORTED The controller does not support the requested
+ transaction.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST) (
+ IN CONST EFI_I2C_HOST_PROTOCOL *This,
+ IN UINTN I2cBusConfiguration,
+ IN UINTN SlaveAddress,
+ IN EFI_EVENT Event OPTIONAL,
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket,
+ OUT EFI_STATUS *I2cStatus OPTIONAL
+ );
+
+///
+/// I2C Host Protocol
+///
+struct _EFI_I2C_HOST_PROTOCOL {
+ ///
+ /// Queue an I2C transaction for execution on the I2C bus
+ ///
+ EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST QueueRequest;
+
+ ///
+ /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure
+ /// containing the capabilities of the I2C host controller.
+ ///
+ CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
+};
+
+///
+/// Reference to variable defined in the .DEC file
+///
+extern EFI_GUID gEfiI2cHostProtocolGuid;
+
+#endif // __I2C_HOST_H__
diff --git a/MdePkg/Include/Protocol/I2cIo.h b/MdePkg/Include/Protocol/I2cIo.h new file mode 100644 index 0000000000..3627d0de38 --- /dev/null +++ b/MdePkg/Include/Protocol/I2cIo.h @@ -0,0 +1,175 @@ +/** @file
+ I2C I/O Protocol as defined in the PI 1.3 specification.
+
+ The EFI I2C I/O protocol enables the user to manipulate a single
+ I2C device independent of the host controller and I2C design.
+
+ 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_IO_H__
+#define __I2C_IO_H__
+
+#include <Pi/PiI2c.h>
+
+#define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}
+
+///
+/// I2C I/O protocol
+///
+/// The I2C IO protocol enables access to a specific device on the I2C
+/// bus.
+///
+/// Each I2C device is identified uniquely in the system by the tuple
+/// DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture
+/// and part number and is provided by the silicon vendor or the third
+/// party I2C device driver writer. The DeviceIndex identifies the part
+/// within the system by using a unique number and is created by the
+/// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.
+///
+/// I2C slave addressing is abstracted to validate addresses and limit
+/// operation to the specified I2C device. The third party providing
+/// the I2C device support provides an ordered list of slave addresses
+/// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.
+/// The order of the list must be preserved.
+///
+typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL;
+
+
+/**
+ Queue an I2C transaction for execution on the I2C device.
+
+ This routine must be called at or below TPL_NOTIFY. For synchronous
+ requests this routine must be called at or below TPL_CALLBACK.
+
+ This routine queues an I2C transaction to the I2C controller for
+ execution on the I2C bus.
+
+ When Event is NULL, QueueRequest() operates synchronously and returns
+ the I2C completion status as its return value.
+
+ When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
+ indicating that the asynchronous I2C transaction was queued. The values
+ above are returned in the buffer pointed to by I2cStatus upon the
+ completion of the I2C transaction when I2cStatus is not NULL.
+
+ The upper layer driver writer provides the following to the platform
+ vendor:
+
+ 1. Vendor specific GUID for the I2C part
+ 2. Guidance on proper construction of the slave address array when the
+ I2C device uses more than one slave address. The I2C bus protocol
+ uses the SlaveAddressIndex to perform relative to physical address
+ translation to access the blocks of hardware within the I2C device.
+
+ @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
+ @param[in] SlaveAddressIndex Index value into an array of slave addresses
+ for the I2C device. The values in the array
+ are specified by the board designer, with the
+ third party I2C device driver writer providing
+ the slave address order.
+
+ For devices that have a single slave address,
+ this value must be zero. If the I2C device
+ uses more than one slave address then the
+ third party (upper level) I2C driver writer
+ needs to specify the order of entries in the
+ slave address array.
+
+ \ref ThirdPartyI2cDrivers "Third Party I2C
+ Drivers" section in I2cMaster.h.
+ @param[in] Event Event to signal for asynchronous transactions,
+ NULL for synchronous transactions
+ @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
+ describing the I2C transaction
+ @param[out] I2cStatus Optional buffer to receive the I2C transaction
+ completion status
+
+ @retval EFI_SUCCESS The asynchronous transaction was successfully
+ queued when Event is not NULL.
+ @retval EFI_SUCCESS The transaction completed successfully when
+ Event is NULL.
+ @retval EFI_ABORTED The request did not complete because the driver
+ binding Stop() routine was called.
+ @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
+ large.
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
+ transaction.
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL
+ @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
+ @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
+ bus configuration required to access this I2C
+ device.
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
+ address selected by SlaveAddressIndex.
+ EFI_DEVICE_ERROR will be returned if the
+ controller cannot distinguish when the NACK
+ occurred.
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
+ @retval EFI_UNSUPPORTED The controller does not support the requested
+ transaction.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST) (
+ IN CONST EFI_I2C_IO_PROTOCOL *This,
+ IN UINTN SlaveAddressIndex,
+ IN EFI_EVENT Event OPTIONAL,
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket,
+ OUT EFI_STATUS *I2cStatus OPTIONAL
+ );
+
+///
+/// I2C I/O protocol
+///
+struct _EFI_I2C_IO_PROTOCOL {
+ ///
+ /// Queue an I2C transaction for execution on the I2C device.
+ ///
+ EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST QueueRequest;
+
+ ///
+ /// Unique value assigned by the silicon manufacture or the third
+ /// party I2C driver writer for the I2C part. This value logically
+ /// combines both the manufacture name and the I2C part number into
+ /// a single value specified as a GUID.
+ ///
+ CONST EFI_GUID *DeviceGuid;
+
+ ///
+ /// Unique ID of the I2C part within the system
+ ///
+ UINT32 DeviceIndex;
+
+ ///
+ /// Hardware revision - ACPI _HRV value. See the Advanced Configuration
+ /// and Power Interface Specification, Revision 5.0 for the field format
+ /// and the Plug and play support for I2C web-page for restriction on values.
+ ///
+ UINT32 HardwareRevision;
+
+ ///
+ /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
+ /// the capabilities of the I2C host controller.
+ ///
+ CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
+};
+
+///
+/// Reference to variable defined in the .DEC file
+///
+extern EFI_GUID gEfiI2cIoProtocolGuid;
+
+#endif // __I2C_IO_H__
diff --git a/MdePkg/Include/Protocol/I2cMaster.h b/MdePkg/Include/Protocol/I2cMaster.h new file mode 100644 index 0000000000..26137344af --- /dev/null +++ b/MdePkg/Include/Protocol/I2cMaster.h @@ -0,0 +1,192 @@ +/** @file
+ I2C Master Protocol as defined in the PI 1.3 specification.
+
+ This protocol manipulates the I2C host controller to perform transactions as a master
+ on the I2C bus using the current state of any switches or multiplexers in the I2C bus.
+
+ 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_MASTER_H__
+#define __I2C_MASTER_H__
+
+#include <Pi/PiI2c.h>
+
+#define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}
+
+typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;
+
+/**
+ Set the frequency for the I2C clock line.
+
+ This routine must be called at or below TPL_NOTIFY.
+
+ The software and controller do a best case effort of using the specified
+ frequency for the I2C bus. If the frequency does not match exactly then
+ the I2C master protocol selects the next lower frequency to avoid
+ exceeding the operating conditions for any of the I2C devices on the bus.
+ For example if 400 KHz was specified and the controller's divide network
+ only supports 402 KHz or 398 KHz then the I2C master protocol selects 398
+ KHz. If there are not lower frequencies available, then return
+ EFI_UNSUPPORTED.
+
+ @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure
+ @param[in] BusClockHertz Pointer to the requested I2C bus clock frequency
+ in Hertz. Upon return this value contains the
+ actual frequency in use by the I2C controller.
+
+ @retval EFI_SUCCESS The bus frequency was set successfully.
+ @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
+ @retval EFI_INVALID_PARAMETER BusClockHertz is NULL
+ @retval EFI_UNSUPPORTED The controller does not support this frequency.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (
+ IN CONST EFI_I2C_MASTER_PROTOCOL *This,
+ IN OUT UINTN *BusClockHertz
+ );
+
+/**
+ Reset the I2C controller and configure it for use
+
+ This routine must be called at or below TPL_NOTIFY.
+
+ The I2C controller is reset. The caller must call SetBusFrequench() after
+ calling Reset().
+
+ @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
+
+ @retval EFI_SUCCESS The reset completed successfully.
+ @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
+ @retval EFI_DEVICE_ERROR The reset operation failed.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (
+ IN CONST EFI_I2C_MASTER_PROTOCOL *This
+ );
+
+/**
+ Start an I2C transaction on the host controller.
+
+ This routine must be called at or below TPL_NOTIFY. For synchronous
+ requests this routine must be called at or below TPL_CALLBACK.
+
+ This function initiates an I2C transaction on the controller. To
+ enable proper error handling by the I2C protocol stack, the I2C
+ master protocol does not support queuing but instead only manages
+ one I2C transaction at a time. This API requires that the I2C bus
+ is in the correct configuration for the I2C transaction.
+
+ The transaction is performed by sending a start-bit and selecting the
+ I2C device with the specified I2C slave address and then performing
+ the specified I2C operations. When multiple operations are requested
+ they are separated with a repeated start bit and the slave address.
+ The transaction is terminated with a stop bit.
+
+ When Event is NULL, StartRequest operates synchronously and returns
+ the I2C completion status as its return value.
+
+ When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS
+ indicating that the I2C transaction was started asynchronously. The
+ transaction status value is returned in the buffer pointed to by
+ I2cStatus upon the completion of the I2C transaction when I2cStatus
+ is not NULL. After the transaction status is returned the Event is
+ signaled.
+
+ Note: The typical consumer of this API is the I2C host protocol.
+ Extreme care must be taken by other consumers of this API to prevent
+ confusing the third party I2C drivers due to a state change at the
+ I2C device which the third party I2C drivers did not initiate. I2C
+ platform specific code may use this API within these guidelines.
+
+ @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
+ @param[in] SlaveAddress Address of the device on the I2C bus. Set the
+ I2C_ADDRESSING_10_BIT when using 10-bit addresses,
+ clear this bit for 7-bit addressing. Bits 0-6
+ are used for 7-bit I2C slave addresses and bits
+ 0-9 are used for 10-bit I2C slave addresses.
+ @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET
+ structure describing the I2C transaction.
+ @param[in] Event Event to signal for asynchronous transactions,
+ NULL for asynchronous transactions
+ @param[out] I2cStatus Optional buffer to receive the I2C transaction
+ completion status
+
+ @retval EFI_SUCCESS The asynchronous transaction was successfully
+ started when Event is not NULL.
+ @retval EFI_SUCCESS The transaction completed successfully when
+ Event is NULL.
+ @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
+ @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
+ large.
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
+ transaction.
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL
+ @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
+ address. EFI_DEVICE_ERROR will be returned if
+ the controller cannot distinguish when the NACK
+ occurred.
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
+ @retval EFI_UNSUPPORTED The controller does not support the requested
+ transaction.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST) (
+ IN CONST EFI_I2C_MASTER_PROTOCOL *This,
+ IN UINTN SlaveAddress,
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket,
+ IN EFI_EVENT Event OPTIONAL,
+ OUT EFI_STATUS *I2cStatus OPTIONAL
+ );
+
+///
+/// I2C master mode protocol
+///
+/// This protocol manipulates the I2C host controller to perform transactions as a
+/// master on the I2C bus using the current state of any switches or multiplexers
+/// in the I2C bus.
+///
+struct _EFI_I2C_MASTER_PROTOCOL {
+ ///
+ /// Set the clock frequency for the I2C bus.
+ ///
+ EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;
+
+ ///
+ /// Reset the I2C host controller.
+ ///
+ EFI_I2C_MASTER_PROTOCOL_RESET Reset;
+
+ ///
+ /// Start an I2C transaction in master mode on the host controller.
+ ///
+ EFI_I2C_MASTER_PROTOCOL_START_REQUEST StartRequest;
+
+ ///
+ /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
+ /// the capabilities of the I2C host controller.
+ ///
+ CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
+};
+
+extern EFI_GUID gEfiI2cMasterProtocolGuid;
+
+#endif // __I2C_MASTER_H__
|