From 4006b0b5506bc2ac299fa4bdb7810107fb2c46b2 Mon Sep 17 00:00:00 2001 From: Elvin Li Date: Wed, 14 Aug 2013 01:14:53 +0000 Subject: [PATCH] Add I2C related definition in PI 1.3 spec. Signed-off-by: Elvin Li Reviewed-by: Leahy Leroy P git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14548 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Pi/PiI2c.h | 307 ++++++++++++++++++ MdePkg/Include/Ppi/I2cMaster.h | 108 ++++++ .../Protocol/I2cBusConfigurationManagement.h | 171 ++++++++++ MdePkg/Include/Protocol/I2cEnumerate.h | 110 +++++++ MdePkg/Include/Protocol/I2cHost.h | 160 +++++++++ MdePkg/Include/Protocol/I2cIo.h | 175 ++++++++++ MdePkg/Include/Protocol/I2cMaster.h | 192 +++++++++++ MdePkg/MdePkg.dec | 26 ++ 8 files changed, 1249 insertions(+) create mode 100644 MdePkg/Include/Pi/PiI2c.h create mode 100644 MdePkg/Include/Ppi/I2cMaster.h create mode 100644 MdePkg/Include/Protocol/I2cBusConfigurationManagement.h create mode 100644 MdePkg/Include/Protocol/I2cEnumerate.h create mode 100644 MdePkg/Include/Protocol/I2cHost.h create mode 100644 MdePkg/Include/Protocol/I2cIo.h create mode 100644 MdePkg/Include/Protocol/I2cMaster.h 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.
+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.
+ 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 + +#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.
+ 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.
+ 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 + +#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.
+ 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 + +#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.
+ 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 + +#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.
+ 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 + +#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__ diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 7f05d01c77..6ff7ae66f6 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -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 # -- 2.39.5