mirror of https://github.com/acidanthera/audk.git
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
parent
39899436d3
commit
4006b0b550
|
|
@ -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__
|
||||
|
|
@ -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
|
||||
|
|
@ -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__
|
||||
|
|
@ -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__
|
||||
|
|
@ -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__
|
||||
|
|
@ -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__
|
||||
|
|
@ -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__
|
||||
|
|
@ -686,6 +686,13 @@
|
|||
## Include/Ppi/PiPcd.h
|
||||
gEfiPeiPcdPpiGuid = { 0x1f34d25, 0x4de2, 0x23ad, { 0x3f, 0xf3, 0x36, 0x35, 0x3f, 0xf3, 0x23, 0xf1 } }
|
||||
|
||||
#
|
||||
# PPIs defined in PI 1.3.
|
||||
#
|
||||
|
||||
## Include/Ppi/I2cMaster.h
|
||||
gEfiPeiI2cMasterPpiGuid = { 0xb3bfab9b, 0x9f9c, 0x4e8b, { 0xad, 0x37, 0x7f, 0x8c, 0x51, 0xfc, 0x62, 0x80 }}
|
||||
|
||||
[Protocols]
|
||||
#
|
||||
# Protocols defined in PI1.0.
|
||||
|
|
@ -908,6 +915,25 @@
|
|||
## Include/Protocol/SmmEndOfDxe.h
|
||||
gEfiSmmEndOfDxeProtocolGuid = { 0x24e70042, 0xd5c5, 0x4260, { 0x8c, 0x39, 0xa, 0xd3, 0xaa, 0x32, 0xe9, 0x3d }}
|
||||
|
||||
#
|
||||
# Protocols defined in PI 1.3.
|
||||
#
|
||||
|
||||
## Include/Protocol/I2cMaster.h
|
||||
gEfiI2cMasterProtocolGuid = { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}
|
||||
|
||||
## Include/Protocol/I2cIo.h
|
||||
gEfiI2cIoProtocolGuid = { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}
|
||||
|
||||
## Include/Protocol/I2cEnumerate.h
|
||||
gEfiI2cEnumerateProtocolGuid = { 0xda8cd7c4, 0x1c00, 0x49e2, { 0x80, 0x3e, 0x52, 0x14, 0xe7, 0x01, 0x89, 0x4c }}
|
||||
|
||||
## Include/Protocol/I2cHost.h
|
||||
gEfiI2cHostProtocolGuid = { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}
|
||||
|
||||
## Include/Protocol/I2cBusConfigurationManagement.h
|
||||
gEfiI2cBusConfigurationManagementProtocolGuid = { 0x55b71fb5, 0x17c6, 0x410e, { 0xb5, 0xbd, 0x5f, 0xa2, 0xe3, 0xd4, 0x46, 0x6b }}
|
||||
|
||||
#
|
||||
# Protocols defined in UEFI2.1/UEFI2.0/EFI1.1
|
||||
#
|
||||
|
|
|
|||
Loading…
Reference in New Issue