[mirror_edk2.git] / Vlv2TbltDevicePkg / Include / Protocol / I2cMasterMcg.h

/*++\r
\r
  Copyright (c) 2004  - 2014, Intel Corporation. All rights reserved.<BR>\r
                                                                                   \r\r
  This program and the accompanying materials are licensed and made available under\r\r
  the terms and conditions of the BSD License that accompanies this distribution.  \r\r
  The full text of the license may be found at                                     \r\r
  http://opensource.org/licenses/bsd-license.php.                                  \r\r
                                                                                   \r\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,            \r\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.    \r\r
                                                                                   \r\r
\r
\r
  \section I2cDriverStack       I2C Driver Stack\r
\r
  The following is a representation of the I<sup>2</sup>C (I2C)\r
  driver stack and an I2C bus layout.\r
\r
  <code><pre>\r
              +-----------------+\r
              |   Application   |\r
              +-----------------+\r
                       |\r
                       | Third Party or UEFI\r
                       |\r
                       V\r
 +--------+   +-----------------+\r
 | Slave  |   |   Third Party   |\r
 | Driver |   |   I2C Device    |\r
 |        |   |     Driver      |\r
 +--------+   +-----------------+\r
      |                |\r
      |          BUS   |\r
      |                |\r
      |                V\r
      |       +-----------------+\r
      |       | I2C Bus Driver  |------------------.\r
      |       +-----------------+                  |\r
      |                |                           |\r
      |         HOST   |          BUS              |\r
      |                |          CONFIGURATION    |\r
SLAVE |                V          MANAGEMENT       | ACPI\r
      |       +-----------------+                  |\r
      |       | I2C Host Driver |----------.       |\r
      |       +-----------------+          |       |\r
      |                |                   |       |\r
      |        MASTER  |                   V       V\r
      |                |               +-------=-------------+\r
      |                V               | I2C Platform Driver |\r
      |       +-----------------+      +---------------------+\r
      `------>| I2C Port Driver |               |      |\r
              +-----------------+               |      |\r
                       |                        |      |\r
            Software   |                        |      |\r
            --------------------------------------------------\r
            Hardware   |                        |      |\r
                       |                        |      |\r
                       V                        |      |\r
              +-----------------+               |      |\r
              | I2C Controller  |               |      |\r
              +-----------------+               |      |\r
                       |                        |      |\r
            -----------------------             |      |\r
            I2C Bus    |                        |      |\r
                       |    +------------+      |      |\r
                       +----| High speed |      |      |\r
                       |    | I2C device |      |      |\r
                       |    |    0x01    |      |      |\r
                       |    +------------+      |      |\r
                       |                        |      |\r
                  +---------+  0                |      |\r
                  | Switch  |<------------------`      |\r
                  +---------+  1                       |\r
                       |                               |\r
                       |    +------------+             |\r
                       +----| Fast speed |             |\r
                       |    | I2C device |             |\r
                       |    |    0x02    |             |\r
                       |    +------------+             |\r
                       |                               |\r
                +-------------+                        |\r
                | Multiplexer |<-----------------------`\r
                +-------------+\r
                 0 |       | 1\r
                   |       |\r
                   |       |\r
                   |       |    +-------------+\r
                   |       +----| Third Party |\r
                   |       |    | I2C Device  |\r
                   |       |    |  0x03, 0x04 |\r
                   |       |    +-------------+\r
                   |       |\r
                   |\r
                   |            +-------------+\r
                   +------------| Third Party |\r
                   |            | I2C Device  |\r
                   |            |  0x03, 0x04 |\r
                   |            +-------------+\r
                   |\r
  </pre></code>\r
\r
  The platform hardware designer chooses the bus layout based upon\r
  the platform, I2C chip and software requirements.  The design uses\r
  switches to truncate the bus to enable higher speed operation for a\r
  subset of devices which are placed closer to the controller.  When the\r
  switch is on, the extended bus must operate at a lower speed.  The\r
  design uses multiplexer to create separate address spaces enabling\r
  the use of multiple devices which would otherwise have conflicting\r
  addresses. See the\r
  <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C\r
  Specification</a> for more details.\r
\r
  N.B. Some operating systems may prohibit the changing of switches\r
  and multiplexers in the I2C bus.  In this case the platform hardware\r
  and software designers must select a single I2C bus configuration\r
  consisting of constant input values for the switches and multiplexers.\r
  The platform software designer must then ensure that this I2C bus\r
  configuration is enabled prior to passing control to the operating\r
  system.\r
\r
  The platform hardware designer needs to provide the platform software\r
  designer the following data for each I2C bus:\r
\r
  1.  Which controller controls this bus\r
\r
  2.  A list of logic blocks contained in one or more I2C devices:\r
\r
      a.  I2C device which contains this logic block\r
\r
      b.  Logic block slave address\r
\r
      c.  Logic block name\r
\r
  3.  For each configuration of the switches and multiplexer\r
\r
      a.  What is the maximum speed of operation\r
\r
      b.  What devices are accessible\r
\r
  4.  The settings for the switches and multiplexers when control is\r
      given to the operating system.\r
\r
  \section ThirdPartyI2cDrivers   Third Party I2C Drivers\r
\r
  This layer is I2C chip specific but platform and host controller\r
  independent.\r
\r
  Third party I2C driver writers, typically silicon vendors, need\r
  to provide:\r
\r
  1.  The device path node data that is used to select their\r
      driver.\r
\r
  2.  The order for the blocks of logic that get referenced\r
      by the entries in the slave address array.\r
\r
  3.  The hardware version of the I2C device, this value is passed\r
      to the third party I2C driver to enable it to perform work\r
      arounds for the specific hardware version.  This value should\r
      match the value in the ACPI _HRV tag.\r
\r
  The third party I2C driver uses relative addressing to abstract\r
  the platform specific details of the I2C device.  Using an\r
  example I2C device containing an accelerometer and a magnetometer\r
  which consumes two slave addresses, one for each logic block.  The\r
  third party I2C driver writer may choose to write two drivers, one\r
  for each block of logic, in which case each driver refers to the\r
  single I2C slave address using the relative value of zero (0).\r
  However if the third party I2C driver writer chooses to write a\r
  single driver which consumes multiple slave addresses then the\r
  third party I2C driver writer needs to convey the order of the\r
  I2C slave address entries in the slave address array to the\r
  platform software designer.  For the example:\r
\r
      0: Accelerometer\r
\r
      1: Magnetometer\r
\r
  The platform hardware designer picks the actual slave addresses\r
  from the I2C device's data sheet and provides this information\r
  to the platform software designer.  The platform software designer\r
  then places the slave addresses into the slave address array in the\r
  order specified by the third party I2C driver writer.  The third\r
  party driver I2C writer then indirectly references this array by\r
  specifying the index value as the relative slave address.  The\r
  relative value always starts at zero (0) and its maximum value is\r
  the number of entries in slave address array minus one.\r
\r
  The slave address is specified as a 32-bit integer to allow room\r
  for future slave address expansion.  Only the port driver knows\r
  the maximum slave address value.  All other drivers and\r
  applications must look for the EFI_NOT_FOUND status for the\r
  indication that the maximum slave address was exceeded.\r
\r
  \section I2cBusDriver         I2C Bus Driver\r
\r
  This layer is platform, host controller, and I2C chip independent.\r
\r
  The I2C bus driver creates a handle for each of the I2C devices\r
  described within the platform driver.  The I2C controller's device\r
  path is extended with the device path node provided by the platform\r
  driver and attached to the handle.  The third party I2C device driver\r
  uses the device path to determine if it may connect.  For ACPI nodes,\r
  the third party I2C driver should use the CID or CidString value.\r
\r
  The I2C bus driver validates the relative address for the I2C device\r
  and then converts the relative value to an actual I2C slave address.\r
  The request is then passed to the I2C host driver.\r
\r
  \section I2cHostDriver        I2C Host Driver\r
\r
  This layer is platform, host controller, and I2C chip independent.\r
\r
  N.B. For proper operation of the I2C bus, only the I2C bus driver\r
  and the I2C test application should connect to the I2C host driver\r
  via the EFI_I2C_HOST_DRIVER_PROTOCOL.\r
\r
  The I2C host driver may access any device on the I2C bus.  The I2C\r
  host driver has the following responsibilities:\r
\r
  1.  Limits the number of requests to the I2C port driver to one.\r
      The I2C host driver holds on to additional requests until the\r
      I2C port driver is available to process the request.  The I2C\r
      requests are issued in FIFO order to the I2C port driver.\r
\r
  2.  Enable the proper I2C bus configuration before starting the\r
      I2C request on the I2C port driver\r
\r
  I2C devices are addressed as the tuple: BusConfiguration:SlaveAddress.\r
  I2C bus configuration zero (0) is the portion of the I2C bus that\r
  connects to the host controller.  The bus configuration specifies\r
  the control values for the switches and multiplexers in the I2C bus.\r
  After the switches and multiplexers are properly configured, the I2C\r
  controller uses the slave address to access the requested I2C device.\r
\r
  Since the I2C driver stack supports asynchronous operations this\r
  layer maintains a queue of I2C requests until the I2C controller\r
  is available them.  When a request reaches the head of the queue\r
  the necessary bus configuration is enabled and then the request\r
  is sent to the I2C port driver.\r
\r
  \section I2cPortDriver        I2C Port Driver\r
\r
  This layer is I2C controller specific but platform independent.\r
\r
  This layer manipulates the I2C controller to perform an operation\r
  on the I2C bus.  This layer does not configure the I2C bus so it\r
  is up to the caller to ensure that the I2C bus is in the proper\r
  configuration before issuing the I2C request.\r
\r
  This layer typically needs the following information:\r
\r
  1.  Host controller address\r
  2.  Controller's input clock frequency\r
\r
  Depending upon the I2C controller, more data may be necessary.\r
  This layer may use any method to get these values: hard coded\r
  values, PCD values, or may choose to communicate with the platform\r
  layer using an undefined mechanism to get these values.\r
\r
  If the I2C port driver requires data from the platform driver then\r
  the I2C port driver writer needs to provide the platform interface\r
  details to the platform software designer.\r
\r
  \section I2cPlatformDriver    I2C Platform Driver\r
\r
  When enabling access to I2C devices within UEFI, this driver\r
  installs the EFI_I2C_ACPI_PROTOCOL to provide the I2C device\r
  descriptions to the I2C bus driver using the EFI_I2C_DEVICE\r
  structure.  These descriptions include the bus configuration\r
  number required for the I2C device, the slave address array\r
  and the device path.\r
\r
  The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol is optional.\r
  This protocol needs to be specified under the following conditions:\r
\r
  1.  The I2C bus must operate at a frequency greater than 100 KHz\r
  2.  The I2C bus contains switches or multiplexers.\r
\r
  The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol enables the\r
  I2C host driver to call into the I2C platform driver to enable\r
  a specific I2C bus configuration and set its maximum clock speed.\r
\r
  The platform software designer collects the data requirements\r
  from third party I2C driver writers, the I2C controller\r
  driver writer, the EFI_I2C_ACPI_PROTOCOL and\r
  EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL.  The platform\r
  software designer gets the necessary data from the platform\r
  hardware designer.  The platform software designer then builds\r
  the data structures and implements the necessary routines to\r
  construct the I2C platform driver.\r
\r
  \section I2cSwitches          Switches and Multiplexers\r
\r
  There are some I2C switches and I2C multiplexers where the control\r
  is done via I2C commands.  When the control inputs come via the\r
  same I2C bus that is being configured then the platform driver must\r
  use the EFI_I2C_MASTER_PROTOCOL that is passed to the platform\r
  driver.  While the I2C host driver makes the call to the I2C\r
  platform driver to configure the bus, the host driver keeps the\r
  I2C port driver idle, to allow the I2C platform driver preform\r
  the necessary configuration operations.\r
\r
  If however the configuration control is done via and I2C device\r
  connected to a different I2C bus (host controller), then it is\r
  possible for the platform software designer may choose between\r
  the following:\r
\r
  1.  Call into a third party I2C driver to manipulate the I2C\r
      bus control device.\r
  2.  Call into the EFI_I2C_BUS_PROTOCOL if no third party I2C\r
      driver exists for the I2C bus control device\r
  3.  Call into the EFI_I2C_HOST_PROTOCOL if the platform does\r
      not expose the I2C bus control device.\r
\r
**/\r
\r
#ifndef __I2C_MASTER_H__\r
#define __I2C_MASTER_H__\r
\r
/**\r
  Declare the forward references\r
\r
**/\r
typedef struct _EFI_I2C_MASTER_PROTOCOL   EFI_I2C_MASTER_PROTOCOL;  ///<  I2C master protocol\r
\r
///\r
/// I2C device operation\r
///\r
/// This structure provides the information necessary for an operation\r
/// on an I2C device\r
///\r
typedef struct {\r
  ///\r
  /// Number of bytes to send to the I2C device\r
  ///\r
  UINT32 WriteBytes;\r
\r
  ///\r
  /// Number of bytes to read, set to zero for write only operations\r
  ///\r
  UINT32 ReadBytes;\r
\r
  ///\r
  /// Address of the buffer containing the data to send to the I2C device.\r
  /// The WriteBuffer must be at least WriteBytes in length.\r
  ///\r
  UINT8 *WriteBuffer;\r
\r
  ///\r
  /// Address of the buffer to receive data from the I2C device. Use NULL\r
  /// for write only operations.  The ReadBuffer must be at least ReadBytes\r
  /// in length.\r
  ///\r
  UINT8 *ReadBuffer;\r
\r
  ///\r
  /// Timeout for the I2C operation in 100 ns units\r
  ///\r
  UINT32 Timeout;\r
} EFI_I2C_REQUEST_PACKET;\r
\r
\r
/**\r
  Set the I2C controller bus clock frequency.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
\r
  The software and controller do a best case effort of using the specified\r
  frequency for the I2C bus.  If the frequency does not match exactly then\r
  the controller will use a slightly lower frequency to avoid\r
  exceeding the operating conditions for any of the I2C devices on the bus.\r
  For example if 400 KHz was specified and the controller's divide network\r
  only supports 402 KHz or 398 KHz then the controller would be set to 398\r
  KHz.  However if the desired frequency is 400 KHz and the controller only\r
  supports 1 MHz and 100 KHz then this routine would return EFI_UNSUPPORTED.\r
\r
  @param[in] This           Address of an EFI_I2C_MASTER_PROTOCOL\r
                            structure\r
  @param[in] BusClockHertz  New I2C bus clock frequency in Hertz\r
\r
  @retval EFI_SUCCESS       The bus frequency was set successfully.\r
  @retval EFI_UNSUPPORTED   The controller does not support this frequency.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_MASTER_BUS_FREQUENCY_SET) (\r
  IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
  IN UINTN BusClockHertz\r
  );\r
\r
/**\r
  Reset the I2C controller and configure it for use\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
\r
  The I2C controller is reset and the I2C bus frequency is set to 100 KHz.\r
\r
  @param[in]     This       Address of an EFI_I2C_MASTER_PROTOCOL\r
                            structure\r
\r
**/\r
typedef\r
VOID\r
(EFIAPI *EFI_I2C_MASTER_RESET) (\r
  IN CONST EFI_I2C_MASTER_PROTOCOL *This\r
  );\r
\r
/**\r
  Start an I2C operation on the host controller\r
\r
  This routine must be called at or below TPL_NOTIFY.  For synchronous\r
  requests this routine must be called at or below TPL_CALLBACK.\r
\r
  This function initiates an I2C operation on the controller.\r
\r
  The operation is performed by selecting the I2C device with its slave\r
  address and then sending all write data to the I2C device.  If read data\r
  is requested, a restart is sent followed by the slave address and then\r
  the read data is clocked into the I2C controller and placed in the read\r
  buffer.  When the operation completes, the status value is returned and\r
  then the event is set.\r
\r
  N.B. The typical consumer of this API is the I2C host driver.\r
  Extreme care must be taken by other consumers of this API to\r
  prevent confusing the third party I2C drivers due to a state\r
  change at the I2C device which the third party I2C drivers did\r
  not initiate.  I2C platform drivers may use this API within\r
  these guidelines.\r
\r
  N.B. This API supports only one operation, no queuing support\r
  exists at this layer.  This API assumes that the I2C bus is in\r
  the correct configuration for the I2C request.\r
\r
  @param[in] This           Address of an EFI_I2C_MASTER_PROTOCOL\r
                            structure\r
  @param[in] SlaveAddress   Address of the device on the I2C bus.\r
  @param[in] Event          Event to set for asynchronous operations,\r
                            NULL for synchronous operations\r
  @param[in] RequestPacket  Address of an EFI_I2C_REQUEST_PACKET\r
                            structure describing the I2C operation\r
  @param[out] I2cStatus     Optional buffer to receive the I2C operation\r
                            completion status\r
\r
  @retval EFI_SUCCESS           The operation completed successfully.\r
  @retval EFI_ABORTED           The request did not complete because the driver\r
                                was shutdown.\r
  @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.\r
  @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.\r
                                This could indicate the slave device is not present.\r
  @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
  @retval EFI_INVALID_PARAMETER TPL is too high\r
  @retval EFI_NOT_FOUND         SlaveAddress exceeds maximum address\r
  @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for\r
                                the event and then read status pointed to by\r
                                the request packet.\r
  @retval EFI_NO_RESPONSE       The I2C device is not responding to the\r
                                slave address.  EFI_DEVICE_ERROR may also be\r
                                returned if the controller cannot distinguish\r
                                when the NACK occurred.\r
  @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation\r
  @retval EFI_TIMEOUT           The transaction did not complete within an internally\r
                                specified timeout period.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_MASTER_START_REQUEST) (\r
  IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
  IN UINTN SlaveAddress,\r
  IN EFI_EVENT Event OPTIONAL,\r
  IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,\r
  OUT EFI_STATUS *I2cStatus OPTIONAL\r
  );\r
\r
///\r
/// I2C master mode protocol\r
///\r
/// This protocol manipulates the I2C host controller to perform transactions as a\r
/// master on the I2C bus using the current state of any switches or multiplexers\r
/// in the I2C bus.\r
///\r
struct _EFI_I2C_MASTER_PROTOCOL {\r
  ///\r
  /// Set the clock frequency for the I2C bus\r
  ///\r
  EFI_I2C_MASTER_BUS_FREQUENCY_SET BusFrequencySet;\r
\r
  ///\r
  /// Reset the I2C host controller\r
  ///\r
  EFI_I2C_MASTER_RESET Reset;\r
\r
  ///\r
  /// Start an I2C transaction in master mode on the host controller\r
  ///\r
  EFI_I2C_MASTER_START_REQUEST StartRequest;\r
\r
  ///\r
  /// The maximum number of bytes the I2C host controller\r
  /// is able to receive from the I2C bus.\r
  ///\r
  UINT32 MaximumReceiveBytes;\r
\r
  ///\r
  /// The maximum number of bytes the I2C host controller\r
  /// is able to send on the I2C bus.\r
  ///\r
  UINT32 MaximumTransmitBytes;\r
\r
  ///\r
  /// The maximum number of bytes in the I2C bus transaction.\r
  ///\r
  UINT32 MaximumTotalBytes;\r
};\r
\r
///\r
/// GUID for the EFI_I2C_MASTER_PROTOCOL\r
///\r
extern EFI_GUID gEfiI2cMasterProtocolGuid;\r
\r
#endif  //  __I2C_MASTER_H__\r
Commit	Line	Data
3cbfba02 DW	1	/*++\r
	2	\r
	3	Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR>\r
	4	\r\r
	5	This program and the accompanying materials are licensed and made available under\r\r
	6	the terms and conditions of the BSD License that accompanies this distribution. \r\r
	7	The full text of the license may be found at \r\r
	8	http://opensource.org/licenses/bsd-license.php. \r\r
	9	\r\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r\r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r\r
	12	\r\r
	13	\r
	14	\r
	15	\section I2cDriverStack I2C Driver Stack\r
	16	\r
	17	The following is a representation of the I<sup>2</sup>C (I2C)\r
	18	driver stack and an I2C bus layout.\r
	19	\r
	20	<code><pre>\r
	21	+-----------------+\r
	22	\| Application \|\r
	23	+-----------------+\r
	24	\|\r
	25	\| Third Party or UEFI\r
	26	\|\r
	27	V\r
	28	+--------+ +-----------------+\r
	29	\| Slave \| \| Third Party \|\r
	30	\| Driver \| \| I2C Device \|\r
	31	\| \| \| Driver \|\r
	32	+--------+ +-----------------+\r
	33	\| \|\r
	34	\| BUS \|\r
	35	\| \|\r
	36	\| V\r
	37	\| +-----------------+\r
	38	\| \| I2C Bus Driver \|------------------.\r
	39	\| +-----------------+ \|\r
	40	\| \| \|\r
	41	\| HOST \| BUS \|\r
	42	\| \| CONFIGURATION \|\r
	43	SLAVE \| V MANAGEMENT \| ACPI\r
	44	\| +-----------------+ \|\r
	45	\| \| I2C Host Driver \|----------. \|\r
	46	\| +-----------------+ \| \|\r
	47	\| \| \| \|\r
	48	\| MASTER \| V V\r
	49	\| \| +-------=-------------+\r
	50	\| V \| I2C Platform Driver \|\r
	51	\| +-----------------+ +---------------------+\r
	52	`------>\| I2C Port Driver \| \| \|\r
	53	+-----------------+ \| \|\r
	54	\| \| \|\r
	55	Software \| \| \|\r
	56	--------------------------------------------------\r
	57	Hardware \| \| \|\r
	58	\| \| \|\r
	59	V \| \|\r
	60	+-----------------+ \| \|\r
	61	\| I2C Controller \| \| \|\r
	62	+-----------------+ \| \|\r
	63	\| \| \|\r
	64	----------------------- \| \|\r
65	I2C Bus \| \| \|\r
66	\| +------------+ \| \|\r
67	+----\| High speed \| \| \|\r
68	\| \| I2C device \| \| \|\r
69	\| \| 0x01 \| \| \|\r
70	\| +------------+ \| \|\r
71	\| \| \|\r
72	+---------+ 0 \| \|\r
73	\| Switch \|<------------------` \|\r
74	+---------+ 1 \|\r
75	\| \|\r
76	\| +------------+ \|\r
77	+----\| Fast speed \| \|\r
78	\| \| I2C device \| \|\r
79	\| \| 0x02 \| \|\r
80	\| +------------+ \|\r
81	\| \|\r
82	+-------------+ \|\r
83	\| Multiplexer \|<-----------------------`\r
84	+-------------+\r
85	0 \| \| 1\r
86	\| \|\r
87	\| \|\r
88	\| \| +-------------+\r
89	\| +----\| Third Party \|\r
90	\| \| \| I2C Device \|\r
91	\| \| \| 0x03, 0x04 \|\r
92	\| \| +-------------+\r
93	\| \|\r
94	\|\r
95	\| +-------------+\r
96	+------------\| Third Party \|\r
97	\| \| I2C Device \|\r
98	\| \| 0x03, 0x04 \|\r
99	\| +-------------+\r
100	\|\r
101	</pre></code>\r
102	\r
103	The platform hardware designer chooses the bus layout based upon\r
104	the platform, I2C chip and software requirements. The design uses\r
105	switches to truncate the bus to enable higher speed operation for a\r
106	subset of devices which are placed closer to the controller. When the\r
107	switch is on, the extended bus must operate at a lower speed. The\r
108	design uses multiplexer to create separate address spaces enabling\r
109	the use of multiple devices which would otherwise have conflicting\r
110	addresses. See the\r
111	<a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C\r
112	Specification</a> for more details.\r
113	\r
114	N.B. Some operating systems may prohibit the changing of switches\r
115	and multiplexers in the I2C bus. In this case the platform hardware\r
116	and software designers must select a single I2C bus configuration\r
117	consisting of constant input values for the switches and multiplexers.\r
118	The platform software designer must then ensure that this I2C bus\r
119	configuration is enabled prior to passing control to the operating\r
120	system.\r
121	\r
122	The platform hardware designer needs to provide the platform software\r
123	designer the following data for each I2C bus:\r
124	\r
125	1. Which controller controls this bus\r
126	\r
127	2. A list of logic blocks contained in one or more I2C devices:\r
128	\r
129	a. I2C device which contains this logic block\r
130	\r
131	b. Logic block slave address\r
132	\r
133	c. Logic block name\r
134	\r
135	3. For each configuration of the switches and multiplexer\r
136	\r
137	a. What is the maximum speed of operation\r
138	\r
139	b. What devices are accessible\r
140	\r
141	4. The settings for the switches and multiplexers when control is\r
142	given to the operating system.\r
143	\r
144	\section ThirdPartyI2cDrivers Third Party I2C Drivers\r
145	\r
146	This layer is I2C chip specific but platform and host controller\r
147	independent.\r
148	\r
149	Third party I2C driver writers, typically silicon vendors, need\r
150	to provide:\r
151	\r
152	1. The device path node data that is used to select their\r
153	driver.\r
154	\r
155	2. The order for the blocks of logic that get referenced\r
156	by the entries in the slave address array.\r
157	\r
158	3. The hardware version of the I2C device, this value is passed\r
159	to the third party I2C driver to enable it to perform work\r
160	arounds for the specific hardware version. This value should\r
161	match the value in the ACPI _HRV tag.\r
162	\r
163	The third party I2C driver uses relative addressing to abstract\r
164	the platform specific details of the I2C device. Using an\r
165	example I2C device containing an accelerometer and a magnetometer\r
166	which consumes two slave addresses, one for each logic block. The\r
167	third party I2C driver writer may choose to write two drivers, one\r
168	for each block of logic, in which case each driver refers to the\r
169	single I2C slave address using the relative value of zero (0).\r
170	However if the third party I2C driver writer chooses to write a\r
171	single driver which consumes multiple slave addresses then the\r
172	third party I2C driver writer needs to convey the order of the\r
173	I2C slave address entries in the slave address array to the\r
174	platform software designer. For the example:\r
175	\r
176	0: Accelerometer\r
177	\r
178	1: Magnetometer\r
179	\r
180	The platform hardware designer picks the actual slave addresses\r
181	from the I2C device's data sheet and provides this information\r
182	to the platform software designer. The platform software designer\r
183	then places the slave addresses into the slave address array in the\r
184	order specified by the third party I2C driver writer. The third\r
185	party driver I2C writer then indirectly references this array by\r
186	specifying the index value as the relative slave address. The\r
187	relative value always starts at zero (0) and its maximum value is\r
188	the number of entries in slave address array minus one.\r
189	\r
190	The slave address is specified as a 32-bit integer to allow room\r
191	for future slave address expansion. Only the port driver knows\r
192	the maximum slave address value. All other drivers and\r
193	applications must look for the EFI_NOT_FOUND status for the\r
194	indication that the maximum slave address was exceeded.\r
195	\r
196	\section I2cBusDriver I2C Bus Driver\r
197	\r
198	This layer is platform, host controller, and I2C chip independent.\r
199	\r
200	The I2C bus driver creates a handle for each of the I2C devices\r
201	described within the platform driver. The I2C controller's device\r
202	path is extended with the device path node provided by the platform\r
203	driver and attached to the handle. The third party I2C device driver\r
204	uses the device path to determine if it may connect. For ACPI nodes,\r
205	the third party I2C driver should use the CID or CidString value.\r
206	\r
207	The I2C bus driver validates the relative address for the I2C device\r
208	and then converts the relative value to an actual I2C slave address.\r
209	The request is then passed to the I2C host driver.\r
210	\r
211	\section I2cHostDriver I2C Host Driver\r
212	\r
213	This layer is platform, host controller, and I2C chip independent.\r
214	\r
215	N.B. For proper operation of the I2C bus, only the I2C bus driver\r
216	and the I2C test application should connect to the I2C host driver\r
217	via the EFI_I2C_HOST_DRIVER_PROTOCOL.\r
218	\r
219	The I2C host driver may access any device on the I2C bus. The I2C\r
220	host driver has the following responsibilities:\r
221	\r
222	1. Limits the number of requests to the I2C port driver to one.\r
223	The I2C host driver holds on to additional requests until the\r
224	I2C port driver is available to process the request. The I2C\r
225	requests are issued in FIFO order to the I2C port driver.\r
226	\r
227	2. Enable the proper I2C bus configuration before starting the\r
228	I2C request on the I2C port driver\r
229	\r
230	I2C devices are addressed as the tuple: BusConfiguration:SlaveAddress.\r
231	I2C bus configuration zero (0) is the portion of the I2C bus that\r
232	connects to the host controller. The bus configuration specifies\r
233	the control values for the switches and multiplexers in the I2C bus.\r
234	After the switches and multiplexers are properly configured, the I2C\r
235	controller uses the slave address to access the requested I2C device.\r
236	\r
237	Since the I2C driver stack supports asynchronous operations this\r
238	layer maintains a queue of I2C requests until the I2C controller\r
239	is available them. When a request reaches the head of the queue\r
240	the necessary bus configuration is enabled and then the request\r
241	is sent to the I2C port driver.\r
242	\r
243	\section I2cPortDriver I2C Port Driver\r
244	\r
245	This layer is I2C controller specific but platform independent.\r
246	\r
247	This layer manipulates the I2C controller to perform an operation\r
248	on the I2C bus. This layer does not configure the I2C bus so it\r
249	is up to the caller to ensure that the I2C bus is in the proper\r
250	configuration before issuing the I2C request.\r
251	\r
252	This layer typically needs the following information:\r
253	\r
254	1. Host controller address\r
255	2. Controller's input clock frequency\r
256	\r
257	Depending upon the I2C controller, more data may be necessary.\r
258	This layer may use any method to get these values: hard coded\r
259	values, PCD values, or may choose to communicate with the platform\r
260	layer using an undefined mechanism to get these values.\r
261	\r
262	If the I2C port driver requires data from the platform driver then\r
263	the I2C port driver writer needs to provide the platform interface\r
264	details to the platform software designer.\r
265	\r
266	\section I2cPlatformDriver I2C Platform Driver\r
267	\r
268	When enabling access to I2C devices within UEFI, this driver\r
269	installs the EFI_I2C_ACPI_PROTOCOL to provide the I2C device\r
270	descriptions to the I2C bus driver using the EFI_I2C_DEVICE\r
271	structure. These descriptions include the bus configuration\r
272	number required for the I2C device, the slave address array\r
273	and the device path.\r
274	\r
275	The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol is optional.\r
276	This protocol needs to be specified under the following conditions:\r
277	\r
278	1. The I2C bus must operate at a frequency greater than 100 KHz\r
279	2. The I2C bus contains switches or multiplexers.\r
280	\r
281	The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol enables the\r
282	I2C host driver to call into the I2C platform driver to enable\r
283	a specific I2C bus configuration and set its maximum clock speed.\r
284	\r
285	The platform software designer collects the data requirements\r
286	from third party I2C driver writers, the I2C controller\r
287	driver writer, the EFI_I2C_ACPI_PROTOCOL and\r
288	EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL. The platform\r
289	software designer gets the necessary data from the platform\r
290	hardware designer. The platform software designer then builds\r
291	the data structures and implements the necessary routines to\r
292	construct the I2C platform driver.\r
293	\r
294	\section I2cSwitches Switches and Multiplexers\r
295	\r
296	There are some I2C switches and I2C multiplexers where the control\r
297	is done via I2C commands. When the control inputs come via the\r
298	same I2C bus that is being configured then the platform driver must\r
299	use the EFI_I2C_MASTER_PROTOCOL that is passed to the platform\r
300	driver. While the I2C host driver makes the call to the I2C\r
301	platform driver to configure the bus, the host driver keeps the\r
302	I2C port driver idle, to allow the I2C platform driver preform\r
303	the necessary configuration operations.\r
304	\r
305	If however the configuration control is done via and I2C device\r
306	connected to a different I2C bus (host controller), then it is\r
307	possible for the platform software designer may choose between\r
308	the following:\r
309	\r
310	1. Call into a third party I2C driver to manipulate the I2C\r
311	bus control device.\r
312	2. Call into the EFI_I2C_BUS_PROTOCOL if no third party I2C\r
313	driver exists for the I2C bus control device\r
314	3. Call into the EFI_I2C_HOST_PROTOCOL if the platform does\r
315	not expose the I2C bus control device.\r
316	\r
317	**/\r
318	\r
319	#ifndef __I2C_MASTER_H__\r
320	#define __I2C_MASTER_H__\r
321	\r
322	/**\r
323	Declare the forward references\r
324	\r
325	**/\r
326	typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL; ///< I2C master protocol\r
327	\r
328	///\r
329	/// I2C device operation\r
330	///\r
331	/// This structure provides the information necessary for an operation\r
332	/// on an I2C device\r
333	///\r
334	typedef struct {\r
335	///\r
336	/// Number of bytes to send to the I2C device\r
337	///\r
338	UINT32 WriteBytes;\r
339	\r
340	///\r
341	/// Number of bytes to read, set to zero for write only operations\r
342	///\r
343	UINT32 ReadBytes;\r
344	\r
345	///\r
346	/// Address of the buffer containing the data to send to the I2C device.\r
347	/// The WriteBuffer must be at least WriteBytes in length.\r
348	///\r
349	UINT8 *WriteBuffer;\r
350	\r
351	///\r
352	/// Address of the buffer to receive data from the I2C device. Use NULL\r
353	/// for write only operations. The ReadBuffer must be at least ReadBytes\r
354	/// in length.\r
355	///\r
356	UINT8 *ReadBuffer;\r
357	\r
358	///\r
359	/// Timeout for the I2C operation in 100 ns units\r
360	///\r
361	UINT32 Timeout;\r
362	} EFI_I2C_REQUEST_PACKET;\r
363	\r
364	\r
365	/**\r
366	Set the I2C controller bus clock frequency.\r
367	\r
368	This routine must be called at or below TPL_NOTIFY.\r
369	\r
370	The software and controller do a best case effort of using the specified\r
371	frequency for the I2C bus. If the frequency does not match exactly then\r
372	the controller will use a slightly lower frequency to avoid\r
373	exceeding the operating conditions for any of the I2C devices on the bus.\r
374	For example if 400 KHz was specified and the controller's divide network\r
375	only supports 402 KHz or 398 KHz then the controller would be set to 398\r
376	KHz. However if the desired frequency is 400 KHz and the controller only\r
377	supports 1 MHz and 100 KHz then this routine would return EFI_UNSUPPORTED.\r
378	\r
379	@param[in] This Address of an EFI_I2C_MASTER_PROTOCOL\r
380	structure\r
381	@param[in] BusClockHertz New I2C bus clock frequency in Hertz\r
382	\r
383	@retval EFI_SUCCESS The bus frequency was set successfully.\r
384	@retval EFI_UNSUPPORTED The controller does not support this frequency.\r
385	\r
386	**/\r
387	typedef\r
388	EFI_STATUS\r
389	(EFIAPI *EFI_I2C_MASTER_BUS_FREQUENCY_SET) (\r
390	IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
391	IN UINTN BusClockHertz\r
392	);\r
393	\r
394	/**\r
395	Reset the I2C controller and configure it for use\r
396	\r
397	This routine must be called at or below TPL_NOTIFY.\r
398	\r
399	The I2C controller is reset and the I2C bus frequency is set to 100 KHz.\r
400	\r
401	@param[in] This Address of an EFI_I2C_MASTER_PROTOCOL\r
402	structure\r
403	\r
404	**/\r
405	typedef\r
406	VOID\r
407	(EFIAPI *EFI_I2C_MASTER_RESET) (\r
408	IN CONST EFI_I2C_MASTER_PROTOCOL *This\r
409	);\r
410	\r
411	/**\r
412	Start an I2C operation on the host controller\r
413	\r
414	This routine must be called at or below TPL_NOTIFY. For synchronous\r
415	requests this routine must be called at or below TPL_CALLBACK.\r
416	\r
417	This function initiates an I2C operation on the controller.\r
418	\r
419	The operation is performed by selecting the I2C device with its slave\r
420	address and then sending all write data to the I2C device. If read data\r
421	is requested, a restart is sent followed by the slave address and then\r
422	the read data is clocked into the I2C controller and placed in the read\r
423	buffer. When the operation completes, the status value is returned and\r
424	then the event is set.\r
425	\r
426	N.B. The typical consumer of this API is the I2C host driver.\r
427	Extreme care must be taken by other consumers of this API to\r
428	prevent confusing the third party I2C drivers due to a state\r
429	change at the I2C device which the third party I2C drivers did\r
430	not initiate. I2C platform drivers may use this API within\r
431	these guidelines.\r
432	\r
433	N.B. This API supports only one operation, no queuing support\r
434	exists at this layer. This API assumes that the I2C bus is in\r
435	the correct configuration for the I2C request.\r
436	\r
437	@param[in] This Address of an EFI_I2C_MASTER_PROTOCOL\r
438	structure\r
439	@param[in] SlaveAddress Address of the device on the I2C bus.\r
440	@param[in] Event Event to set for asynchronous operations,\r
441	NULL for synchronous operations\r
442	@param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET\r
443	structure describing the I2C operation\r
444	@param[out] I2cStatus Optional buffer to receive the I2C operation\r
445	completion status\r
446	\r
447	@retval EFI_SUCCESS The operation completed successfully.\r
448	@retval EFI_ABORTED The request did not complete because the driver\r
449	was shutdown.\r
450	@retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.\r
451	@retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.\r
452	This could indicate the slave device is not present.\r
453	@retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
454	@retval EFI_INVALID_PARAMETER TPL is too high\r
455	@retval EFI_NOT_FOUND SlaveAddress exceeds maximum address\r
456	@retval EFI_NOT_READY I2C bus is busy or operation pending, wait for\r
457	the event and then read status pointed to by\r
458	the request packet.\r
459	@retval EFI_NO_RESPONSE The I2C device is not responding to the\r
460	slave address. EFI_DEVICE_ERROR may also be\r
461	returned if the controller cannot distinguish\r
462	when the NACK occurred.\r
463	@retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation\r
464	@retval EFI_TIMEOUT The transaction did not complete within an internally\r
465	specified timeout period.\r
466	\r
467	**/\r
468	typedef\r
469	EFI_STATUS\r
470	(EFIAPI *EFI_I2C_MASTER_START_REQUEST) (\r
471	IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
472	IN UINTN SlaveAddress,\r
473	IN EFI_EVENT Event OPTIONAL,\r
474	IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,\r
475	OUT EFI_STATUS *I2cStatus OPTIONAL\r
476	);\r
477	\r
478	///\r
479	/// I2C master mode protocol\r
480	///\r
481	/// This protocol manipulates the I2C host controller to perform transactions as a\r
482	/// master on the I2C bus using the current state of any switches or multiplexers\r
483	/// in the I2C bus.\r
484	///\r
485	struct _EFI_I2C_MASTER_PROTOCOL {\r
486	///\r
487	/// Set the clock frequency for the I2C bus\r
488	///\r
489	EFI_I2C_MASTER_BUS_FREQUENCY_SET BusFrequencySet;\r
490	\r
491	///\r
492	/// Reset the I2C host controller\r
493	///\r
494	EFI_I2C_MASTER_RESET Reset;\r
495	\r
496	///\r
497	/// Start an I2C transaction in master mode on the host controller\r
498	///\r
499	EFI_I2C_MASTER_START_REQUEST StartRequest;\r
500	\r
501	///\r
502	/// The maximum number of bytes the I2C host controller\r
503	/// is able to receive from the I2C bus.\r
504	///\r
505	UINT32 MaximumReceiveBytes;\r
506	\r
507	///\r
508	/// The maximum number of bytes the I2C host controller\r
509	/// is able to send on the I2C bus.\r
510	///\r
511	UINT32 MaximumTransmitBytes;\r
512	\r
513	///\r
514	/// The maximum number of bytes in the I2C bus transaction.\r
515	///\r
516	UINT32 MaximumTotalBytes;\r
517	};\r
518	\r
519	///\r
520	/// GUID for the EFI_I2C_MASTER_PROTOCOL\r
521	///\r
522	extern EFI_GUID gEfiI2cMasterProtocolGuid;\r
523	\r
524	#endif // __I2C_MASTER_H__\r