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

5 files changed, 808 insertions, 0 deletions

diff --git a/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h b/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h
new file mode 100644
index 0000000000..68000cf476
--- /dev/null
+++ b/MdePkg/Include/Protocol/I2cBusConfigurationManagement.h
@@ -0,0 +1,171 @@
+/** @file

+  I2C Bus Configuration Management Protocol as defined in the PI 1.3 specification.

+

+  The EFI I2C bus configuration management protocol provides platform specific 

+  services that allow the I2C host protocol to reconfigure the switches and multiplexers 

+  and set the clock frequency for the I2C bus. This protocol also enables the I2C host protocol 

+  to reset an I2C device which may be locking up the I2C bus by holding the clock or data line low.

+

+  Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials                          

+  are licensed and made available under the terms and conditions of the BSD License         

+  which accompanies this distribution.  The full text of the license may be found at        

+  http://opensource.org/licenses/bsd-license.php                                            

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

+

+  @par Revision Reference:

+  This protocol is from PI Version 1.3.

+

+**/

+

+#ifndef __I2C_BUS_CONFIGURATION_MANAGEMENT_H__

+#define __I2C_BUS_CONFIGURATION_MANAGEMENT_H__

+

+#define EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_GUID \

+  { 0x55b71fb5, 0x17c6, 0x410e, { 0xb5, 0xbd, 0x5f, 0xa2, 0xe3, 0xd4, 0x46, 0x6b }}

+

+///

+/// I2C bus configuration management protocol

+///

+/// The EFI I2C bus configuration management protocol provides platform

+/// specific services that allow the I2C host protocol to reconfigure the

+/// switches and multiplexers and set the clock frequency for the I2C bus.

+/// This protocol also enables the I2C host protocol to reset an I2C device

+/// which may be locking up the I2C bus by holding the clock or data line

+/// low.

+///

+/// The I2C protocol stack uses the concept of an I2C bus configuration as

+/// a way to describe a particular state of the switches and multiplexers

+/// in the I2C bus.

+///

+/// A simple I2C bus does not have any multiplexers or switches is described

+/// to the I2C protocol stack with a single I2C bus configuration which

+/// specifies the I2C bus frequency.

+///

+/// An I2C bus with switches and multiplexers use an I2C bus configuration

+/// to describe each of the unique settings for the switches and multiplexers

+/// and the I2C bus frequency.  However the I2C bus configuration management

+/// protocol only needs to define the I2C bus configurations that the software

+/// uses, which may be a subset of the total.

+///

+/// The I2C bus configuration description includes a list of I2C devices

+/// which may be accessed when this I2C bus configuration is enabled.  I2C

+/// devices before a switch or multiplexer must be included in one I2C bus

+/// configuration while I2C devices after a switch or multiplexer are on

+/// another I2C bus configuration.

+///

+/// The I2C bus configuration management protocol is an optional protocol.

+/// When the I2C bus configuration protocol is not defined the I2C host

+/// protocol does not start and the I2C master protocol may be used for

+/// other purposes such as SMBus traffic.  When the I2C bus configuration

+/// protocol is available, the I2C host protocol uses the I2C bus

+/// configuration protocol to call into the platform specific code to set

+/// the switches and multiplexers and set the maximum I2C bus frequency.

+///

+/// The platform designers determine the maximum I2C bus frequency by

+/// selecting a frequency which supports all of the I2C devices on the

+/// I2C bus for the setting of switches and multiplexers.  The platform

+/// designers must validate this against the I2C device data sheets and

+/// any limits of the I2C controller or bus length.

+///

+/// During I2C device enumeration, the I2C bus driver retrieves the I2C

+/// bus configuration that must be used to perform I2C transactions to

+/// each I2C device.  This I2C bus configuration value is passed into

+/// the I2C host protocol to identify the I2C bus configuration required

+/// to access a specific I2C device.  The I2C host protocol calls

+/// EnableBusConfiguration() to set the switches and multiplexers in the

+/// I2C bus and the I2C clock frequency.  The I2C host protocol may

+/// optimize calls to EnableBusConfiguration() by only making the call

+/// when the I2C bus configuration value changes between I2C requests.

+///

+/// When I2C transactions are required on the same I2C bus to change the

+/// state of multiplexers or switches, the I2C master protocol must be

+/// used to perform the necessary I2C transactions.

+///

+/// It is up to the platform specific code to choose the proper I2C bus

+/// configuration when ExitBootServices() is called. Some operating systems

+/// are not able to manage the I2C bus configurations and must use the I2C

+/// bus configuration that is established by the platform firmware before

+/// ExitBootServices() returns.

+///

+typedef struct _EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL;

+

+

+/**

+  Enable access to an I2C bus configuration.

+

+  This routine must be called at or below TPL_NOTIFY.  For synchronous

+  requests this routine must be called at or below TPL_CALLBACK.

+

+  Reconfigure the switches and multiplexers in the I2C bus to enable

+  access to a specific I2C bus configuration.  Also select the maximum

+  clock frequency for this I2C bus configuration.

+

+  This routine uses the I2C Master protocol to perform I2C transactions

+  on the local bus.  This eliminates any recursion in the I2C stack for

+  configuration transactions on the same I2C bus.  This works because the

+  local I2C bus is idle while the I2C bus configuration is being enabled.

+

+  If I2C transactions must be performed on other I2C busses, then the

+  EFI_I2C_HOST_PROTOCOL, the EFI_I2C_IO_PROTCOL, or a third party I2C

+  driver interface for a specific device must be used.  This requirement

+  is because the I2C host protocol controls the flow of requests to the

+  I2C controller.  Use the EFI_I2C_HOST_PROTOCOL when the I2C device is

+  not enumerated by the EFI_I2C_ENUMERATE_PROTOCOL.  Use a protocol

+  produced by a third party driver when it is available or the

+  EFI_I2C_IO_PROTOCOL when the third party driver is not available but

+  the device is enumerated with the EFI_I2C_ENUMERATE_PROTOCOL.

+

+  When Event is NULL, EnableI2cBusConfiguration operates synchronously

+  and returns the I2C completion status as its return value.

+

+  @param[in]  This            Pointer to an EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL

+                              structure.

+  @param[in]  I2cBusConfiguration Index of an I2C bus configuration.  All

+                                  values in the range of zero to N-1 are

+                                  valid where N is the total number of I2C

+                                  bus configurations for an I2C bus.

+  @param[in]  Event           Event to signal when the transaction is complete

+  @param[out] I2cStatus       Buffer to receive the transaction status.

+

+  @return  When Event is NULL, EnableI2cBusConfiguration operates synchrouously

+  and returns the I2C completion status as its return value.  In this case it is

+  recommended to use NULL for I2cStatus.  The values returned from

+  EnableI2cBusConfiguration are:

+

+  @retval EFI_SUCCESS           The asynchronous bus configuration request

+                                was successfully started when Event is not

+                                NULL.

+  @retval EFI_SUCCESS           The bus configuration request completed

+                                successfully when Event is NULL.

+  @retval EFI_DEVICE_ERROR      The bus configuration failed.

+  @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_ENABLE_I2C_BUS_CONFIGURATION) (

+  IN CONST EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *This,

+  IN UINTN                                               I2cBusConfiguration,

+  IN EFI_EVENT                                           Event      OPTIONAL,

+  IN EFI_STATUS                                          *I2cStatus OPTIONAL

+  );

+

+///

+/// I2C bus configuration management protocol

+///

+struct _EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL {

+  ///

+  /// Enable an I2C bus configuration for use.

+  ///

+  EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL_ENABLE_I2C_BUS_CONFIGURATION EnableI2cBusConfiguration;

+};

+

+///

+/// Reference to variable defined in the .DEC file

+///

+extern EFI_GUID gEfiI2cBusConfigurationManagementProtocolGuid;

+

+#endif  //  __I2C_BUS_CONFIGURATION_MANAGEMENT_H__

diff --git a/MdePkg/Include/Protocol/I2cEnumerate.h b/MdePkg/Include/Protocol/I2cEnumerate.h
new file mode 100644
index 0000000000..45e6a26c69
--- /dev/null
+++ b/MdePkg/Include/Protocol/I2cEnumerate.h
@@ -0,0 +1,110 @@
+/** @file

+  I2C Device Enumerate Protocol as defined in the PI 1.3 specification.

+

+  This protocol supports the enumerations of device on the I2C bus.

+

+  Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials                          

+  are licensed and made available under the terms and conditions of the BSD License         

+  which accompanies this distribution.  The full text of the license may be found at        

+  http://opensource.org/licenses/bsd-license.php                                            

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

+

+  @par Revision Reference:

+  This protocol is from PI Version 1.3.

+

+**/

+

+#ifndef __I2C_ENUMERATE_H__

+#define __I2C_ENUMERATE_H__

+

+#include <Pi/PiI2c.h>

+

+#define EFI_I2C_ENUMERATE_PROTOCOL_GUID   { 0xda8cd7c4, 0x1c00, 0x49e2, { 0x80, 0x3e, 0x52, 0x14, 0xe7, 0x01, 0x89, 0x4c }}

+

+typedef struct _EFI_I2C_ENUMERATE_PROTOCOL  EFI_I2C_ENUMERATE_PROTOCOL;

+

+/**

+  Enumerate the I2C devices

+

+  This function enables the caller to traverse the set of I2C devices

+  on an I2C bus.

+

+  @param[in]  This              The platform data for the next device on

+                                the I2C bus was returned successfully.

+  @param[in, out] Device        Pointer to a buffer containing an

+                                EFI_I2C_DEVICE structure.  Enumeration is

+                                started by setting the initial EFI_I2C_DEVICE

+                                structure pointer to NULL.  The buffer

+                                receives an EFI_I2C_DEVICE structure pointer

+                                to the next I2C device.

+

+  @retval EFI_SUCCESS           The platform data for the next device on

+                                the I2C bus was returned successfully.

+  @retval EFI_INVALID_PARAMETER Device is NULL

+  @retval EFI_NO_MAPPING        *Device does not point to a valid

+                                EFI_I2C_DEVICE structure returned in a

+                                previous call Enumerate().

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_ENUMERATE_PROTOCOL_ENUMERATE) (

+  IN CONST EFI_I2C_ENUMERATE_PROTOCOL *This,

+  IN OUT CONST EFI_I2C_DEVICE         **Device

+  );

+

+/**

+  Get the requested I2C bus frequency for a specified bus configuration.

+

+  This function returns the requested I2C bus clock frequency for the

+  I2cBusConfiguration.  This routine is provided for diagnostic purposes

+  and is meant to be called after calling Enumerate to get the

+  I2cBusConfiguration value.

+

+  @param[in] This                 Pointer to an EFI_I2C_ENUMERATE_PROTOCOL

+                                  structure.

+  @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C

+                                  device

+  @param[out] *BusClockHertz      Pointer to a buffer to receive the I2C

+                                  bus clock frequency in Hertz

+

+  @retval EFI_SUCCESS           The I2C bus frequency was returned

+                                successfully.

+  @retval EFI_INVALID_PARAMETER BusClockHertz was NULL

+  @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_ENUMERATE_PROTOCOL_GET_BUS_FREQUENCY) (

+  IN CONST EFI_I2C_ENUMERATE_PROTOCOL *This,

+  IN UINTN                            I2cBusConfiguration,

+  OUT UINTN                           *BusClockHertz

+  );

+

+///

+/// I2C Enumerate protocol

+///

+struct _EFI_I2C_ENUMERATE_PROTOCOL {

+  ///

+  /// Traverse the set of I2C devices on an I2C bus.  This routine

+  /// returns the next I2C device on an I2C bus.

+  ///

+  EFI_I2C_ENUMERATE_PROTOCOL_ENUMERATE         Enumerate;

+

+  ///

+  /// Get the requested I2C bus frequency for a specified bus

+  /// configuration.

+  ///

+  EFI_I2C_ENUMERATE_PROTOCOL_GET_BUS_FREQUENCY GetBusFrequency;

+};

+

+///

+/// Reference to variable defined in the .DEC file

+///

+extern EFI_GUID gEfiI2cEnumerateProtocolGuid;

+

+#endif  //  __I2C_ENUMERATE_H__

diff --git a/MdePkg/Include/Protocol/I2cHost.h b/MdePkg/Include/Protocol/I2cHost.h
new file mode 100644
index 0000000000..12e77a4cce
--- /dev/null
+++ b/MdePkg/Include/Protocol/I2cHost.h
@@ -0,0 +1,160 @@
+/** @file

+  I2C Host Protocol as defined in the PI 1.3 specification.

+

+  This protocol provides callers with the ability to do I/O transactions 

+  to all of the devices on the I2C bus.

+

+  Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials                          

+  are licensed and made available under the terms and conditions of the BSD License         

+  which accompanies this distribution.  The full text of the license may be found at        

+  http://opensource.org/licenses/bsd-license.php                                            

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

+

+  @par Revision Reference:

+  This protocol is from PI Version 1.3.

+

+**/

+

+#ifndef __I2C_HOST_H__

+#define __I2C_HOST_H__

+

+#include <Pi/PiI2c.h>

+

+#define EFI_I2C_HOST_PROTOCOL_GUID  { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}

+

+///

+/// I2C Host Protocol

+///

+/// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL

+/// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C

+/// device on an I2C bus.

+///

+/// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to

+/// callers to perform transactions to any device on the I2C bus.

+/// Internally, the I2C host protocol manages the flow of the I2C

+/// transactions to the host controller, keeping them in FIFO order.

+/// Prior to each transaction, the I2C host protocol ensures that the

+/// switches and multiplexers are properly configured.  The I2C host

+/// protocol then starts the transaction on the host controller using

+/// the EFI_I2C_MASTER_PROTOCOL.

+///

+typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;

+

+

+/**

+  Queue an I2C transaction for execution on the I2C controller.

+

+  This routine must be called at or below TPL_NOTIFY.  For

+  synchronous requests this routine must be called at or below

+  TPL_CALLBACK.

+  

+  The I2C host protocol uses the concept of I2C bus configurations

+  to describe the I2C bus.  An I2C bus configuration is defined as

+  a unique setting of the multiplexers and switches in the I2C bus

+  which enable access to one or more I2C devices.  When using a

+  switch to divide a bus, due to bus frequency differences, the

+  I2C bus configuration management protocol defines an I2C bus

+  configuration for the I2C devices on each side of the switch.

+  When using a multiplexer, the I2C bus configuration management

+  defines an I2C bus configuration for each of the selector values

+  required to control the multiplexer.  See Figure 1 in the I2C -bus

+  specification and user manual for a complex I2C bus configuration.

+

+  The I2C host protocol processes all transactions in FIFO order.

+  Prior to performing the transaction, the I2C host protocol calls

+  EnableI2cBusConfiguration to reconfigure the switches and

+  multiplexers in the I2C bus enabling access to the specified I2C

+  device.  The EnableI2cBusConfiguration also selects the I2C bus

+  frequency for the I2C device.  After the I2C bus is configured,

+  the I2C host protocol calls the I2C master protocol to start the

+  I2C transaction.

+

+  If the I2C host protocol has pending I2C transactions queued when

+  the driver binding Stop() routine is called then the I2C host

+  protocol completes all of the pending I2C transactions by returning

+  EFI_ABORTED status.  This notifies the upper layers allowing them

+  to take corrective action or prepare to stop.

+

+  When Event is NULL, QueueRequest() operates synchronously and

+  returns the I2C completion status as its return value.

+

+  When Event is not NULL, QueueRequest() synchronously returns

+  EFI_SUCCESS indicating that the asynchronously I2C transaction was

+  queued.  The values above are returned in the buffer pointed to by

+  I2cStatus upon the completion of the I2C transaction when I2cStatus

+  is not NULL.

+

+  @param[in] This             Pointer to an EFI_I2C_HOST_PROTOCOL structure.

+  @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C

+                                  device

+  @param[in] SlaveAddress     Address of the device on the I2C bus.  Set

+                              the I2C_ADDRESSING_10_BIT when using 10-bit

+                              addresses, clear this bit for 7-bit addressing.

+                              Bits 0-6 are used for 7-bit I2C slave addresses

+                              and bits 0-9 are used for 10-bit I2C slave

+                              addresses.

+  @param[in] Event            Event to signal for asynchronous transactions,

+                              NULL for synchronous transactions

+  @param[in] RequestPacket    Pointer to an EFI_I2C_REQUEST_PACKET structure

+                              describing the I2C transaction

+  @param[out] I2cStatus       Optional buffer to receive the I2C transaction

+                              completion status

+

+  @retval EFI_SUCCESS           The asynchronous transaction was successfully

+                                queued when Event is not NULL.

+  @retval EFI_SUCCESS           The transaction completed successfully when

+                                Event is NULL.

+  @retval EFI_ABORTED           The request did not complete because the

+                                driver binding Stop() routine was called.

+  @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is

+                                too large.

+  @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the

+                                transaction.

+  @retval EFI_INVALID_PARAMETER RequestPacket is NULL

+  @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter

+  @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value

+  @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave

+                                address.  EFI_DEVICE_ERROR will be returned

+                                if the controller cannot distinguish when the

+                                NACK occurred.

+  @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction

+  @retval EFI_UNSUPPORTED       The controller does not support the requested

+                                transaction.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST) (

+  IN CONST EFI_I2C_HOST_PROTOCOL *This,

+  IN UINTN                       I2cBusConfiguration,

+  IN UINTN                       SlaveAddress,

+  IN EFI_EVENT                   Event      OPTIONAL,

+  IN EFI_I2C_REQUEST_PACKET      *RequestPacket,

+  OUT EFI_STATUS                 *I2cStatus OPTIONAL

+  );

+

+///

+/// I2C Host Protocol

+///

+struct _EFI_I2C_HOST_PROTOCOL {

+  ///

+  /// Queue an I2C transaction for execution on the I2C bus

+  ///

+  EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST     QueueRequest;

+

+  ///

+  /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure

+  /// containing the capabilities of the I2C host controller.

+  ///

+  CONST EFI_I2C_CONTROLLER_CAPABILITIES   *I2cControllerCapabilities;

+};

+

+///

+/// Reference to variable defined in the .DEC file

+///

+extern EFI_GUID gEfiI2cHostProtocolGuid;

+

+#endif  //  __I2C_HOST_H__

diff --git a/MdePkg/Include/Protocol/I2cIo.h b/MdePkg/Include/Protocol/I2cIo.h
new file mode 100644
index 0000000000..3627d0de38
--- /dev/null
+++ b/MdePkg/Include/Protocol/I2cIo.h
@@ -0,0 +1,175 @@
+/** @file

+  I2C I/O Protocol as defined in the PI 1.3 specification.

+

+  The EFI I2C I/O protocol enables the user to manipulate a single 

+  I2C device independent of the host controller and I2C design.

+

+  Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials                          

+  are licensed and made available under the terms and conditions of the BSD License         

+  which accompanies this distribution.  The full text of the license may be found at        

+  http://opensource.org/licenses/bsd-license.php                                            

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

+

+  @par Revision Reference:

+  This protocol is from PI Version 1.3.

+

+**/

+

+#ifndef __I2C_IO_H__

+#define __I2C_IO_H__

+

+#include <Pi/PiI2c.h>

+

+#define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}

+

+///

+/// I2C I/O protocol

+///

+/// The I2C IO protocol enables access to a specific device on the I2C

+/// bus.

+///

+/// Each I2C device is identified uniquely in the system by the tuple

+/// DeviceGuid:DeviceIndex.  The DeviceGuid represents the manufacture

+/// and part number and is provided by the silicon vendor or the third

+/// party I2C device driver writer.  The DeviceIndex identifies the part

+/// within the system by using a unique number and is created by the

+/// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.

+///

+/// I2C slave addressing is abstracted to validate addresses and limit

+/// operation to the specified I2C device.  The third party providing

+/// the I2C device support provides an ordered list of slave addresses

+/// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.

+/// The order of the list must be preserved.

+///

+typedef struct _EFI_I2C_IO_PROTOCOL  EFI_I2C_IO_PROTOCOL;

+

+

+/**

+  Queue an I2C transaction for execution on the I2C device.

+

+  This routine must be called at or below TPL_NOTIFY.  For synchronous

+  requests this routine must be called at or below TPL_CALLBACK.

+

+  This routine queues an I2C transaction to the I2C controller for

+  execution on the I2C bus.

+

+  When Event is NULL, QueueRequest() operates synchronously and returns

+  the I2C completion status as its return value.

+

+  When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS

+  indicating that the asynchronous I2C transaction was queued.  The values

+  above are returned in the buffer pointed to by I2cStatus upon the

+  completion of the I2C transaction when I2cStatus is not NULL.

+

+  The upper layer driver writer provides the following to the platform

+  vendor:

+  

+  1.  Vendor specific GUID for the I2C part

+  2.  Guidance on proper construction of the slave address array when the

+      I2C device uses more than one slave address.  The I2C bus protocol

+      uses the SlaveAddressIndex to perform relative to physical address

+      translation to access the blocks of hardware within the I2C device.

+

+  @param[in] This               Pointer to an EFI_I2C_IO_PROTOCOL structure.

+  @param[in] SlaveAddressIndex  Index value into an array of slave addresses

+                                for the I2C device.  The values in the array

+                                are specified by the board designer, with the

+                                third party I2C device driver writer providing

+                                the slave address order.

+

+                                For devices that have a single slave address,

+                                this value must be zero.  If the I2C device

+                                uses more than one slave address then the

+                                third party (upper level) I2C driver writer

+                                needs to specify the order of entries in the

+                                slave address array.

+

+                                \ref ThirdPartyI2cDrivers "Third Party I2C

+                                Drivers" section in I2cMaster.h.

+  @param[in] Event              Event to signal for asynchronous transactions,

+                                NULL for synchronous transactions

+  @param[in] RequestPacket      Pointer to an EFI_I2C_REQUEST_PACKET structure

+                                describing the I2C transaction

+  @param[out] I2cStatus         Optional buffer to receive the I2C transaction

+                                completion status

+

+  @retval EFI_SUCCESS           The asynchronous transaction was successfully

+                                queued when Event is not NULL.

+  @retval EFI_SUCCESS           The transaction completed successfully when

+                                Event is NULL.

+  @retval EFI_ABORTED           The request did not complete because the driver

+                                binding Stop() routine was called.

+  @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too

+                                large.

+  @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the

+                                transaction.

+  @retval EFI_INVALID_PARAMETER RequestPacket is NULL

+  @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter

+  @retval EFI_NO_MAPPING        The EFI_I2C_HOST_PROTOCOL could not set the

+                                bus configuration required to access this I2C

+                                device.

+  @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave

+                                address selected by SlaveAddressIndex.

+                                EFI_DEVICE_ERROR will be returned if the

+                                controller cannot distinguish when the NACK

+                                occurred.

+  @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction

+  @retval EFI_UNSUPPORTED       The controller does not support the requested

+                                transaction.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST) (

+  IN CONST EFI_I2C_IO_PROTOCOL  *This,

+  IN UINTN                      SlaveAddressIndex,

+  IN EFI_EVENT                  Event      OPTIONAL,

+  IN EFI_I2C_REQUEST_PACKET     *RequestPacket,

+  OUT EFI_STATUS                *I2cStatus OPTIONAL

+  );

+

+///

+/// I2C I/O protocol

+///

+struct _EFI_I2C_IO_PROTOCOL {

+  ///

+  /// Queue an I2C transaction for execution on the I2C device.

+  ///

+  EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST         QueueRequest;

+

+  ///

+  /// Unique value assigned by the silicon manufacture or the third

+  /// party I2C driver writer for the I2C part.  This value logically

+  /// combines both the manufacture name and the I2C part number into

+  /// a single value specified as a GUID.

+  ///

+  CONST EFI_GUID                            *DeviceGuid;

+

+  ///

+  /// Unique ID of the I2C part within the system

+  ///

+  UINT32                                    DeviceIndex;

+

+  ///

+  /// Hardware revision - ACPI _HRV value.  See the Advanced Configuration

+  /// and Power Interface Specification, Revision 5.0  for the field format

+  /// and the Plug and play support for I2C web-page for restriction on values.

+  ///

+  UINT32                                    HardwareRevision;

+

+  ///

+  /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing

+  /// the capabilities of the I2C host controller.

+  ///

+  CONST EFI_I2C_CONTROLLER_CAPABILITIES     *I2cControllerCapabilities;

+};

+

+///

+/// Reference to variable defined in the .DEC file

+///

+extern EFI_GUID gEfiI2cIoProtocolGuid;

+

+#endif  //  __I2C_IO_H__

diff --git a/MdePkg/Include/Protocol/I2cMaster.h b/MdePkg/Include/Protocol/I2cMaster.h
new file mode 100644
index 0000000000..26137344af
--- /dev/null
+++ b/MdePkg/Include/Protocol/I2cMaster.h
@@ -0,0 +1,192 @@
+/** @file

+  I2C Master Protocol as defined in the PI 1.3 specification.

+

+  This protocol manipulates the I2C host controller to perform transactions as a master 

+  on the I2C bus using the current state of any switches or multiplexers in the I2C bus.

+

+  Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>

+  This program and the accompanying materials                          

+  are licensed and made available under the terms and conditions of the BSD License         

+  which accompanies this distribution.  The full text of the license may be found at        

+  http://opensource.org/licenses/bsd-license.php                                            

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     

+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             

+

+  @par Revision Reference:

+  This protocol is from PI Version 1.3.

+

+**/

+

+#ifndef __I2C_MASTER_H__

+#define __I2C_MASTER_H__

+

+#include <Pi/PiI2c.h>

+

+#define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}

+

+typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;

+

+/**

+  Set the frequency for the I2C clock line.

+

+  This routine must be called at or below TPL_NOTIFY.

+

+  The software and controller do a best case effort of using the specified

+  frequency for the I2C bus.  If the frequency does not match exactly then

+  the I2C master protocol selects the next lower frequency to avoid

+  exceeding the operating conditions for any of the I2C devices on the bus.

+  For example if 400 KHz was specified and the controller's divide network

+  only supports 402 KHz or 398 KHz then the I2C master protocol selects 398

+  KHz.  If there are not lower frequencies available, then return

+  EFI_UNSUPPORTED.

+

+  @param[in] This           Pointer to an EFI_I2C_MASTER_PROTOCOL structure

+  @param[in] BusClockHertz  Pointer to the requested I2C bus clock frequency

+                            in Hertz.  Upon return this value contains the

+                            actual frequency in use by the I2C controller.

+

+  @retval EFI_SUCCESS           The bus frequency was set successfully.

+  @retval EFI_ALREADY_STARTED   The controller is busy with another transaction.

+  @retval EFI_INVALID_PARAMETER BusClockHertz is NULL

+  @retval EFI_UNSUPPORTED       The controller does not support this frequency.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (

+  IN CONST EFI_I2C_MASTER_PROTOCOL   *This,

+  IN OUT UINTN                       *BusClockHertz

+  );

+

+/**

+  Reset the I2C controller and configure it for use

+

+  This routine must be called at or below TPL_NOTIFY.

+

+  The I2C controller is reset.  The caller must call SetBusFrequench() after

+  calling Reset().

+

+  @param[in]     This       Pointer to an EFI_I2C_MASTER_PROTOCOL structure.

+

+  @retval EFI_SUCCESS         The reset completed successfully.

+  @retval EFI_ALREADY_STARTED The controller is busy with another transaction.

+  @retval EFI_DEVICE_ERROR    The reset operation failed.

+  

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (

+  IN CONST EFI_I2C_MASTER_PROTOCOL *This

+  );

+

+/**

+  Start an I2C transaction on the host controller.

+

+  This routine must be called at or below TPL_NOTIFY.  For synchronous

+  requests this routine must be called at or below TPL_CALLBACK.

+

+  This function initiates an I2C transaction on the controller.  To

+  enable proper error handling by the I2C protocol stack, the I2C

+  master protocol does not support queuing but instead only manages

+  one I2C transaction at a time.  This API requires that the I2C bus

+  is in the correct configuration for the I2C transaction.

+

+  The transaction is performed by sending a start-bit and selecting the

+  I2C device with the specified I2C slave address and then performing

+  the specified I2C operations.  When multiple operations are requested

+  they are separated with a repeated start bit and the slave address.

+  The transaction is terminated with a stop bit.

+

+  When Event is NULL, StartRequest operates synchronously and returns

+  the I2C completion status as its return value.

+

+  When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS

+  indicating that the I2C transaction was started asynchronously.  The

+  transaction status value is returned in the buffer pointed to by

+  I2cStatus upon the completion of the I2C transaction when I2cStatus

+  is not NULL.  After the transaction status is returned the Event is

+  signaled.

+

+  Note: The typical consumer of this API is the I2C host protocol.

+  Extreme care must be taken by other consumers of this API to prevent

+  confusing the third party I2C drivers due to a state change at the

+  I2C device which the third party I2C drivers did not initiate.  I2C

+  platform specific code may use this API within these guidelines.

+

+  @param[in] This           Pointer to an EFI_I2C_MASTER_PROTOCOL structure.

+  @param[in] SlaveAddress   Address of the device on the I2C bus.  Set the

+                            I2C_ADDRESSING_10_BIT when using 10-bit addresses,

+                            clear this bit for 7-bit addressing.  Bits 0-6

+                            are used for 7-bit I2C slave addresses and bits

+                            0-9 are used for 10-bit I2C slave addresses.

+  @param[in] RequestPacket  Pointer to an EFI_I2C_REQUEST_PACKET

+                            structure describing the I2C transaction.

+  @param[in] Event          Event to signal for asynchronous transactions,

+                            NULL for asynchronous transactions

+  @param[out] I2cStatus     Optional buffer to receive the I2C transaction

+                            completion status

+

+  @retval EFI_SUCCESS           The asynchronous transaction was successfully

+                                started when Event is not NULL.

+  @retval EFI_SUCCESS           The transaction completed successfully when

+                                Event is NULL.

+  @retval EFI_ALREADY_STARTED   The controller is busy with another transaction.

+  @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too

+                                large.

+  @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the

+                                transaction.

+  @retval EFI_INVALID_PARAMETER RequestPacket is NULL

+  @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter

+  @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave

+                                address.  EFI_DEVICE_ERROR will be returned if

+                                the controller cannot distinguish when the NACK

+                                occurred.

+  @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction

+  @retval EFI_UNSUPPORTED       The controller does not support the requested

+                                transaction.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST) (

+  IN CONST EFI_I2C_MASTER_PROTOCOL *This,

+  IN UINTN                         SlaveAddress,

+  IN EFI_I2C_REQUEST_PACKET        *RequestPacket,

+  IN EFI_EVENT                     Event      OPTIONAL,

+  OUT EFI_STATUS                   *I2cStatus OPTIONAL

+  );

+

+///

+/// I2C master mode protocol

+///

+/// This protocol manipulates the I2C host controller to perform transactions as a

+/// master on the I2C bus using the current state of any switches or multiplexers

+/// in the I2C bus.

+///

+struct _EFI_I2C_MASTER_PROTOCOL {

+  ///

+  /// Set the clock frequency for the I2C bus.

+  ///

+  EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;

+

+  ///

+  /// Reset the I2C host controller.

+  ///

+  EFI_I2C_MASTER_PROTOCOL_RESET             Reset;

+

+  ///

+  /// Start an I2C transaction in master mode on the host controller.

+  ///

+  EFI_I2C_MASTER_PROTOCOL_START_REQUEST     StartRequest;

+

+  ///

+  /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing

+  /// the capabilities of the I2C host controller.

+  ///

+  CONST EFI_I2C_CONTROLLER_CAPABILITIES     *I2cControllerCapabilities;

+};

+

+extern EFI_GUID gEfiI2cMasterProtocolGuid;

+

+#endif  //  __I2C_MASTER_H__