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

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