[mirror_edk2.git] / MdePkg / Include / Protocol / I2cMaster.h

/** @file\r
  I2C Master Protocol as defined in the PI 1.3 specification.\r
\r
  This protocol manipulates the I2C host controller to perform transactions as a master \r
  on the I2C bus using the current state of any switches or multiplexers in the I2C bus.\r
\r
  Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>\r
  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
  @par Revision Reference:\r
  This protocol is from PI Version 1.3.\r
\r
**/\r
\r
#ifndef __I2C_MASTER_H__\r
#define __I2C_MASTER_H__\r
\r
#include <Pi/PiI2c.h>\r
\r
#define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}\r
\r
typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;\r
\r
/**\r
  Set the frequency for the I2C clock line.\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 I2C master protocol selects the next 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 I2C master protocol selects 398\r
  KHz.  If there are not lower frequencies available, then return\r
  EFI_UNSUPPORTED.\r
\r
  @param[in] This           Pointer to an EFI_I2C_MASTER_PROTOCOL structure\r
  @param[in] BusClockHertz  Pointer to the requested I2C bus clock frequency\r
                            in Hertz.  Upon return this value contains the\r
                            actual frequency in use by the I2C controller.\r
\r
  @retval EFI_SUCCESS           The bus frequency was set successfully.\r
  @retval EFI_ALREADY_STARTED   The controller is busy with another transaction.\r
  @retval EFI_INVALID_PARAMETER BusClockHertz is NULL\r
  @retval EFI_UNSUPPORTED       The controller does not support this frequency.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (\r
  IN CONST EFI_I2C_MASTER_PROTOCOL   *This,\r
  IN OUT 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.  The caller must call SetBusFrequench() after\r
  calling Reset().\r
\r
  @param[in]     This       Pointer to an EFI_I2C_MASTER_PROTOCOL structure.\r
\r
  @retval EFI_SUCCESS         The reset completed successfully.\r
  @retval EFI_ALREADY_STARTED The controller is busy with another transaction.\r
  @retval EFI_DEVICE_ERROR    The reset operation failed.\r
  \r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (\r
  IN CONST EFI_I2C_MASTER_PROTOCOL *This\r
  );\r
\r
/**\r
  Start an I2C transaction 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 transaction on the controller.  To\r
  enable proper error handling by the I2C protocol stack, the I2C\r
  master protocol does not support queuing but instead only manages\r
  one I2C transaction at a time.  This API requires that the I2C bus\r
  is in the correct configuration for the I2C transaction.\r
\r
  The transaction is performed by sending a start-bit and selecting the\r
  I2C device with the specified I2C slave address and then performing\r
  the specified I2C operations.  When multiple operations are requested\r
  they are separated with a repeated start bit and the slave address.\r
  The transaction is terminated with a stop bit.\r
\r
  When Event is NULL, StartRequest operates synchronously and returns\r
  the I2C completion status as its return value.\r
\r
  When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS\r
  indicating that the I2C transaction was started asynchronously.  The\r
  transaction status value is returned in the buffer pointed to by\r
  I2cStatus upon the completion of the I2C transaction when I2cStatus\r
  is not NULL.  After the transaction status is returned the Event is\r
  signaled.\r
\r
  Note: The typical consumer of this API is the I2C host protocol.\r
  Extreme care must be taken by other consumers of this API to prevent\r
  confusing the third party I2C drivers due to a state change at the\r
  I2C device which the third party I2C drivers did not initiate.  I2C\r
  platform specific code may use this API within these guidelines.\r
\r
  @param[in] This           Pointer to an EFI_I2C_MASTER_PROTOCOL structure.\r
  @param[in] SlaveAddress   Address of the device on the I2C bus.  Set the\r
                            I2C_ADDRESSING_10_BIT when using 10-bit addresses,\r
                            clear this bit for 7-bit addressing.  Bits 0-6\r
                            are used for 7-bit I2C slave addresses and bits\r
                            0-9 are used for 10-bit I2C slave addresses.\r
  @param[in] RequestPacket  Pointer to an EFI_I2C_REQUEST_PACKET\r
                            structure describing the I2C transaction.\r
  @param[in] Event          Event to signal for asynchronous transactions,\r
                            NULL for asynchronous transactions\r
  @param[out] I2cStatus     Optional buffer to receive the I2C transaction\r
                            completion status\r
\r
  @retval EFI_SUCCESS           The asynchronous transaction was successfully\r
                                started when Event is not NULL.\r
  @retval EFI_SUCCESS           The transaction completed successfully when\r
                                Event is NULL.\r
  @retval EFI_ALREADY_STARTED   The controller is busy with another transaction.\r
  @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too\r
                                large.\r
  @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the\r
                                transaction.\r
  @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
  @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter\r
  @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave\r
                                address.  EFI_DEVICE_ERROR will be returned if\r
                                the controller cannot distinguish when the NACK\r
                                occurred.\r
  @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction\r
  @retval EFI_UNSUPPORTED       The controller does not support the requested\r
                                transaction.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST) (\r
  IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
  IN UINTN                         SlaveAddress,\r
  IN EFI_I2C_REQUEST_PACKET        *RequestPacket,\r
  IN EFI_EVENT                     Event      OPTIONAL,\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_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;\r
\r
  ///\r
  /// Reset the I2C host controller.\r
  ///\r
  EFI_I2C_MASTER_PROTOCOL_RESET             Reset;\r
\r
  ///\r
  /// Start an I2C transaction in master mode on the host controller.\r
  ///\r
  EFI_I2C_MASTER_PROTOCOL_START_REQUEST     StartRequest;\r
\r
  ///\r
  /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing\r
  /// the capabilities of the I2C host controller.\r
  ///\r
  CONST EFI_I2C_CONTROLLER_CAPABILITIES     *I2cControllerCapabilities;\r
};\r
\r
extern EFI_GUID gEfiI2cMasterProtocolGuid;\r
\r
#endif  //  __I2C_MASTER_H__\r
Commit	Line	Data
4006b0b5 EL	1	/** @file\r
	2	I2C Master Protocol as defined in the PI 1.3 specification.\r
	3	\r
	4	This protocol manipulates the I2C host controller to perform transactions as a master \r
	5	on the I2C bus using the current state of any switches or multiplexers in the I2C bus.\r
	6	\r
	7	Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>\r
	8	This program and the accompanying materials \r
	9	are licensed and made available under the terms and conditions of the BSD License \r
	10	which accompanies this distribution. The full text of the license may be found at \r
	11	http://opensource.org/licenses/bsd-license.php \r
	12	\r
	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	14	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	15	\r
	16	@par Revision Reference:\r
	17	This protocol is from PI Version 1.3.\r
	18	\r
	19	**/\r
	20	\r
	21	#ifndef __I2C_MASTER_H__\r
	22	#define __I2C_MASTER_H__\r
	23	\r
	24	#include <Pi/PiI2c.h>\r
	25	\r
	26	#define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}\r
	27	\r
	28	typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;\r
	29	\r
	30	/**\r
	31	Set the frequency for the I2C clock line.\r
	32	\r
	33	This routine must be called at or below TPL_NOTIFY.\r
	34	\r
	35	The software and controller do a best case effort of using the specified\r
	36	frequency for the I2C bus. If the frequency does not match exactly then\r
	37	the I2C master protocol selects the next lower frequency to avoid\r
	38	exceeding the operating conditions for any of the I2C devices on the bus.\r
	39	For example if 400 KHz was specified and the controller's divide network\r
	40	only supports 402 KHz or 398 KHz then the I2C master protocol selects 398\r
	41	KHz. If there are not lower frequencies available, then return\r
	42	EFI_UNSUPPORTED.\r
	43	\r
	44	@param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure\r
	45	@param[in] BusClockHertz Pointer to the requested I2C bus clock frequency\r
	46	in Hertz. Upon return this value contains the\r
	47	actual frequency in use by the I2C controller.\r
	48	\r
	49	@retval EFI_SUCCESS The bus frequency was set successfully.\r
	50	@retval EFI_ALREADY_STARTED The controller is busy with another transaction.\r
	51	@retval EFI_INVALID_PARAMETER BusClockHertz is NULL\r
	52	@retval EFI_UNSUPPORTED The controller does not support this frequency.\r
	53	\r
	54	**/\r
	55	typedef\r
	56	EFI_STATUS\r
	57	(EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (\r
	58	IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
	59	IN OUT UINTN *BusClockHertz\r
	60	);\r
	61	\r
	62	/**\r
	63	Reset the I2C controller and configure it for use\r
	64	\r
65	This routine must be called at or below TPL_NOTIFY.\r
66	\r
67	The I2C controller is reset. The caller must call SetBusFrequench() after\r
68	calling Reset().\r
69	\r
70	@param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.\r
71	\r
72	@retval EFI_SUCCESS The reset completed successfully.\r
73	@retval EFI_ALREADY_STARTED The controller is busy with another transaction.\r
74	@retval EFI_DEVICE_ERROR The reset operation failed.\r
75	\r
76	**/\r
77	typedef\r
78	EFI_STATUS\r
79	(EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (\r
80	IN CONST EFI_I2C_MASTER_PROTOCOL *This\r
81	);\r
82	\r
83	/**\r
84	Start an I2C transaction on the host controller.\r
85	\r
86	This routine must be called at or below TPL_NOTIFY. For synchronous\r
87	requests this routine must be called at or below TPL_CALLBACK.\r
88	\r
89	This function initiates an I2C transaction on the controller. To\r
90	enable proper error handling by the I2C protocol stack, the I2C\r
91	master protocol does not support queuing but instead only manages\r
92	one I2C transaction at a time. This API requires that the I2C bus\r
93	is in the correct configuration for the I2C transaction.\r
94	\r
95	The transaction is performed by sending a start-bit and selecting the\r
96	I2C device with the specified I2C slave address and then performing\r
97	the specified I2C operations. When multiple operations are requested\r
98	they are separated with a repeated start bit and the slave address.\r
99	The transaction is terminated with a stop bit.\r
100	\r
101	When Event is NULL, StartRequest operates synchronously and returns\r
102	the I2C completion status as its return value.\r
103	\r
104	When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS\r
105	indicating that the I2C transaction was started asynchronously. The\r
106	transaction status value is returned in the buffer pointed to by\r
107	I2cStatus upon the completion of the I2C transaction when I2cStatus\r
108	is not NULL. After the transaction status is returned the Event is\r
109	signaled.\r
110	\r
111	Note: The typical consumer of this API is the I2C host protocol.\r
112	Extreme care must be taken by other consumers of this API to prevent\r
113	confusing the third party I2C drivers due to a state change at the\r
114	I2C device which the third party I2C drivers did not initiate. I2C\r
115	platform specific code may use this API within these guidelines.\r
116	\r
117	@param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.\r
118	@param[in] SlaveAddress Address of the device on the I2C bus. Set the\r
119	I2C_ADDRESSING_10_BIT when using 10-bit addresses,\r
120	clear this bit for 7-bit addressing. Bits 0-6\r
121	are used for 7-bit I2C slave addresses and bits\r
122	0-9 are used for 10-bit I2C slave addresses.\r
123	@param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET\r
124	structure describing the I2C transaction.\r
125	@param[in] Event Event to signal for asynchronous transactions,\r
126	NULL for asynchronous transactions\r
127	@param[out] I2cStatus Optional buffer to receive the I2C transaction\r
128	completion status\r
129	\r
130	@retval EFI_SUCCESS The asynchronous transaction was successfully\r
131	started when Event is not NULL.\r
132	@retval EFI_SUCCESS The transaction completed successfully when\r
133	Event is NULL.\r
134	@retval EFI_ALREADY_STARTED The controller is busy with another transaction.\r
135	@retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too\r
136	large.\r
137	@retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the\r
138	transaction.\r
139	@retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
140	@retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter\r
141	@retval EFI_NO_RESPONSE The I2C device is not responding to the slave\r
142	address. EFI_DEVICE_ERROR will be returned if\r
143	the controller cannot distinguish when the NACK\r
144	occurred.\r
145	@retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction\r
146	@retval EFI_UNSUPPORTED The controller does not support the requested\r
147	transaction.\r
148	\r
149	**/\r
150	typedef\r
151	EFI_STATUS\r
152	(EFIAPI *EFI_I2C_MASTER_PROTOCOL_START_REQUEST) (\r
153	IN CONST EFI_I2C_MASTER_PROTOCOL *This,\r
154	IN UINTN SlaveAddress,\r
155	IN EFI_I2C_REQUEST_PACKET *RequestPacket,\r
156	IN EFI_EVENT Event OPTIONAL,\r
157	OUT EFI_STATUS *I2cStatus OPTIONAL\r
158	);\r
159	\r
160	///\r
161	/// I2C master mode protocol\r
162	///\r
163	/// This protocol manipulates the I2C host controller to perform transactions as a\r
164	/// master on the I2C bus using the current state of any switches or multiplexers\r
165	/// in the I2C bus.\r
166	///\r
167	struct _EFI_I2C_MASTER_PROTOCOL {\r
168	///\r
169	/// Set the clock frequency for the I2C bus.\r
170	///\r
171	EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;\r
172	\r
173	///\r
174	/// Reset the I2C host controller.\r
175	///\r
176	EFI_I2C_MASTER_PROTOCOL_RESET Reset;\r
177	\r
178	///\r
179	/// Start an I2C transaction in master mode on the host controller.\r
180	///\r
181	EFI_I2C_MASTER_PROTOCOL_START_REQUEST StartRequest;\r
182	\r
183	///\r
184	/// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing\r
185	/// the capabilities of the I2C host controller.\r
186	///\r
187	CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;\r
188	};\r
189	\r
190	extern EFI_GUID gEfiI2cMasterProtocolGuid;\r
191	\r
192	#endif // __I2C_MASTER_H__\r