[mirror_edk2.git] / Vlv2DeviceRefCodePkg / ValleyView2Soc / SouthCluster / Include / Protocol / I2cBus.h

/** @file\r
  I2C bus interface\r
\r
  This layer provides I/O access to an I2C device.\r
\r
  Copyright (c) 2012, Intel Corporation\r
  All rights reserved. This program and the accompanying materials\r
  are licensed and made available under the terms and conditions of the BSD License\r
  which accompanies this distribution.  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license.php\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef __I2C_BUS_H__\r
#define __I2C_BUS_H__\r
\r
#include <Protocol/I2cHostMcg.h>\r
\r
///\r
/// I2C bus protocol\r
///\r
typedef struct _EFI_I2C_BUS_PROTOCOL  EFI_I2C_BUS_PROTOCOL;\r
\r
\r
/**\r
  Perform an I2C operation on the device\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
  N.B. The typical consumers of this API are the third party I2C\r
  drivers.  Extreme care must be taken by other consumers of this\r
  API to prevent confusing the third party I2C drivers due to a\r
  state change at the I2C device which the third party I2C drivers\r
  did not initiate.  I2C platform drivers may use this API within\r
  these guidelines.\r
\r
  This routine queues an operation to the I2C controller for execution\r
  on the I2C bus.\r
\r
  As an upper layer driver writer, the following need to be provided\r
  to the platform vendor:\r
\r
  1.  ACPI CID value or string - this is used to connect the upper layer\r
      driver to the device.\r
  2.  Slave address array guidance when the I2C device uses more than one\r
      slave address.  This is used to access the blocks of hardware within\r
      the I2C device.\r
\r
  @param[in] This               Address of an EFI_I2C_BUS_PROTOCOL\r
                                structure\r
  @param[in] SlaveAddressIndex  Index into an array of slave addresses for\r
                                the I2C device.  The values in the array are\r
                                specified by the board designer, with the\r
                                I2C device driver writer providing the slave\r
                                address order.\r
\r
                                For devices that have a single slave address,\r
                                this value must be zero.  If the I2C device\r
                                uses more than one slave address then the third\r
                                party (upper level) I2C driver writer needs to\r
                                specify the order of entries in the slave address\r
                                array.\r
\r
                                \ref ThirdPartyI2cDrivers "Third Party I2C Drivers"\r
                                section in I2cMaster.h.\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_ACCESS_DENIED     Invalid SlaveAddressIndex value\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_NO_RESPONSE       The I2C device is not responding to the\r
                                slave address.  EFI_DEVICE_ERROR may also be\r
                                returned if the controller can not distinguish\r
                                when the NACK occurred.\r
  @retval EFI_NOT_FOUND         I2C slave address 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_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_BUS_START_REQUEST) (\r
  IN CONST EFI_I2C_BUS_PROTOCOL *This,\r
  IN UINTN SlaveAddressIndex,\r
  IN EFI_EVENT Event OPTIONAL,\r
  IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,\r
  OUT EFI_STATUS *I2cStatus OPTIONAL\r
  );\r
\r
///\r
/// The I2C bus protocol enables access to a specific device on the I2C bus.\r
///\r
/// Each I2C device is described as an ACPI node (HID, UID and CID) within the\r
/// platform layer.  The I2C bus protocol enumerates the I2C devices in the\r
/// platform and creates a unique handle and device path for each I2C device.\r
///\r
/// I2C slave addressing is abstracted to validate addresses and limit operation\r
/// to the specified I2C device.  The third party providing the I2C device support\r
/// provides an ordered list of slave addresses for the I2C device to the team\r
/// building the platform layer.  The platform team must preserve the order of the\r
/// supplied list.  SlaveAddressCount is the number of entries in this list or\r
/// array within the platform layer.  The third party device support references\r
/// a slave address using an index into the list or array in the range of zero\r
/// to SlaveAddressCount - 1.\r
///\r
struct _EFI_I2C_BUS_PROTOCOL {\r
  ///\r
  /// Start an I2C operation on the bus\r
  ///\r
  EFI_I2C_BUS_START_REQUEST StartRequest;\r
\r
  ///\r
  /// The maximum number of slave addresses for the I2C device.  The caller may\r
  /// validate this value as a check on the platform layer's configuration.  Slave\r
  /// address selection uses an index value in the range of zero to SlaveAddressCount - 1.\r
  ///\r
  UINTN SlaveAddressCount;\r
\r
  ///\r
  /// Hardware revision - Matches the ACPI _HRV value\r
  ///\r
  /// The HardwareRevision value allows a single driver to support multiple hardware\r
  /// revisions and implement the necessary workarounds for limitations within the\r
  /// hardware.\r
  ///\r
  UINT32 HardwareRevision;\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 I2C bus protocol\r
///\r
extern EFI_GUID gEfiI2cBusProtocolGuid;\r
\r
#endif  //  __I2C_BUS_H__\r
Commit	Line	Data
3cbfba02 DW	1	/** @file\r
	2	I2C bus interface\r
	3	\r
	4	This layer provides I/O access to an I2C device.\r
	5	\r
	6	Copyright (c) 2012, Intel Corporation\r
	7	All rights reserved. This program and the accompanying materials\r
	8	are licensed and made available under the terms and conditions of the BSD License\r
	9	which accompanies this distribution. The full text of the license may be found at\r
	10	http://opensource.org/licenses/bsd-license.php\r
	11	\r
	12	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	13	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	14	\r
	15	**/\r
	16	\r
	17	#ifndef __I2C_BUS_H__\r
	18	#define __I2C_BUS_H__\r
	19	\r
	20	#include <Protocol/I2cHostMcg.h>\r
	21	\r
	22	///\r
	23	/// I2C bus protocol\r
	24	///\r
	25	typedef struct _EFI_I2C_BUS_PROTOCOL EFI_I2C_BUS_PROTOCOL;\r
	26	\r
	27	\r
	28	/**\r
	29	Perform an I2C operation on the device\r
	30	\r
	31	This routine must be called at or below TPL_NOTIFY. For synchronous\r
	32	requests this routine must be called at or below TPL_CALLBACK.\r
	33	\r
	34	N.B. The typical consumers of this API are the third party I2C\r
	35	drivers. Extreme care must be taken by other consumers of this\r
	36	API to prevent confusing the third party I2C drivers due to a\r
	37	state change at the I2C device which the third party I2C drivers\r
	38	did not initiate. I2C platform drivers may use this API within\r
	39	these guidelines.\r
	40	\r
	41	This routine queues an operation to the I2C controller for execution\r
	42	on the I2C bus.\r
	43	\r
	44	As an upper layer driver writer, the following need to be provided\r
	45	to the platform vendor:\r
	46	\r
	47	1. ACPI CID value or string - this is used to connect the upper layer\r
	48	driver to the device.\r
	49	2. Slave address array guidance when the I2C device uses more than one\r
	50	slave address. This is used to access the blocks of hardware within\r
	51	the I2C device.\r
	52	\r
	53	@param[in] This Address of an EFI_I2C_BUS_PROTOCOL\r
	54	structure\r
	55	@param[in] SlaveAddressIndex Index into an array of slave addresses for\r
	56	the I2C device. The values in the array are\r
	57	specified by the board designer, with the\r
	58	I2C device driver writer providing the slave\r
	59	address order.\r
	60	\r
	61	For devices that have a single slave address,\r
	62	this value must be zero. If the I2C device\r
	63	uses more than one slave address then the third\r
	64	party (upper level) I2C driver writer needs to\r
65	specify the order of entries in the slave address\r
66	array.\r
67	\r
68	\ref ThirdPartyI2cDrivers "Third Party I2C Drivers"\r
69	section in I2cMaster.h.\r
70	@param[in] Event Event to set for asynchronous operations,\r
71	NULL for synchronous operations\r
72	@param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET\r
73	structure describing the I2C operation\r
74	@param[out] I2cStatus Optional buffer to receive the I2C operation\r
75	completion status\r
76	\r
77	@retval EFI_SUCCESS The operation completed successfully.\r
78	@retval EFI_ABORTED The request did not complete because the driver\r
79	was shutdown.\r
80	@retval EFI_ACCESS_DENIED Invalid SlaveAddressIndex value\r
81	@retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.\r
82	@retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.\r
83	This could indicate the slave device is not present.\r
84	@retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
85	@retval EFI_INVALID_PARAMETER TPL is too high\r
86	@retval EFI_NO_RESPONSE The I2C device is not responding to the\r
87	slave address. EFI_DEVICE_ERROR may also be\r
88	returned if the controller can not distinguish\r
89	when the NACK occurred.\r
90	@retval EFI_NOT_FOUND I2C slave address exceeds maximum address\r
91	@retval EFI_NOT_READY I2C bus is busy or operation pending, wait for\r
92	the event and then read status pointed to by\r
93	the request packet.\r
94	@retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation\r
95	@retval EFI_TIMEOUT The transaction did not complete within an internally\r
96	specified timeout period.\r
97	\r
98	**/\r
99	typedef\r
100	EFI_STATUS\r
101	(EFIAPI *EFI_I2C_BUS_START_REQUEST) (\r
102	IN CONST EFI_I2C_BUS_PROTOCOL *This,\r
103	IN UINTN SlaveAddressIndex,\r
104	IN EFI_EVENT Event OPTIONAL,\r
105	IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,\r
106	OUT EFI_STATUS *I2cStatus OPTIONAL\r
107	);\r
108	\r
109	///\r
110	/// The I2C bus protocol enables access to a specific device on the I2C bus.\r
111	///\r
112	/// Each I2C device is described as an ACPI node (HID, UID and CID) within the\r
113	/// platform layer. The I2C bus protocol enumerates the I2C devices in the\r
114	/// platform and creates a unique handle and device path for each I2C device.\r
115	///\r
116	/// I2C slave addressing is abstracted to validate addresses and limit operation\r
117	/// to the specified I2C device. The third party providing the I2C device support\r
118	/// provides an ordered list of slave addresses for the I2C device to the team\r
119	/// building the platform layer. The platform team must preserve the order of the\r
120	/// supplied list. SlaveAddressCount is the number of entries in this list or\r
121	/// array within the platform layer. The third party device support references\r
122	/// a slave address using an index into the list or array in the range of zero\r
123	/// to SlaveAddressCount - 1.\r
124	///\r
125	struct _EFI_I2C_BUS_PROTOCOL {\r
126	///\r
127	/// Start an I2C operation on the bus\r
128	///\r
129	EFI_I2C_BUS_START_REQUEST StartRequest;\r
130	\r
131	///\r
132	/// The maximum number of slave addresses for the I2C device. The caller may\r
133	/// validate this value as a check on the platform layer's configuration. Slave\r
134	/// address selection uses an index value in the range of zero to SlaveAddressCount - 1.\r
135	///\r
136	UINTN SlaveAddressCount;\r
137	\r
138	///\r
139	/// Hardware revision - Matches the ACPI _HRV value\r
140	///\r
141	/// The HardwareRevision value allows a single driver to support multiple hardware\r
142	/// revisions and implement the necessary workarounds for limitations within the\r
143	/// hardware.\r
144	///\r
145	UINT32 HardwareRevision;\r
146	\r
147	///\r
148	/// The maximum number of bytes the I2C host controller\r
149	/// is able to receive from the I2C bus.\r
150	///\r
151	UINT32 MaximumReceiveBytes;\r
152	\r
153	///\r
154	/// The maximum number of bytes the I2C host controller\r
155	/// is able to send on the I2C bus.\r
156	///\r
157	UINT32 MaximumTransmitBytes;\r
158	\r
159	///\r
160	/// The maximum number of bytes in the I2C bus transaction.\r
161	///\r
162	UINT32 MaximumTotalBytes;\r
163	};\r
164	\r
165	///\r
166	/// GUID for the I2C bus protocol\r
167	///\r
168	extern EFI_GUID gEfiI2cBusProtocolGuid;\r
169	\r
170	#endif // __I2C_BUS_H__\r