[mirror_edk2.git] / Vlv2TbltDevicePkg / Include / Protocol / I2cSlave.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
**/\r
\r
#ifndef __I2C_SLAVE_H__\r
#define __I2C_SLAVE_H__\r
\r
#include <Protocol/I2cHostMcg.h>\r
\r
/**\r
  Declare the forward references\r
\r
**/\r
typedef struct _EFI_I2C_SLAVE_PROTOCOL    EFI_I2C_SLAVE_PROTOCOL;   ///<  I2C slave protocol\r
\r
/**\r
  The I2C controller received a data byte from the\r
  I2C msster.\r
\r
  @param[in] Context        The value passed to the slave enable routine.\r
  @param[in] NumberOfBytes  Number of data bytes received\r
  @param[in] Data           Buffer containing the received data bytes\r
\r
  @retval EFI_SUCCESS       ACK the data byte\r
  @retval EFI_UNSUPPORTED   NACK the data byte\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_SLAVE_RECEIVE_DATA) (\r
  IN VOID *Context,\r
  IN UINTN NumberOfBytes,\r
  IN CONST UINT8 *Data\r
  );\r
\r
/**\r
  The I2C controller received the start bit from the\r
  I2C master.\r
\r
  @param[in] Context        The value passed to the slave enable routine.\r
\r
**/\r
typedef\r
VOID\r
(EFIAPI *EFI_I2C_SLAVE_RECEIVE_START) (\r
  IN VOID *Context,\r
  IN UINTN BytesSent,\r
  IN EFI_STATUS Status\r
  );\r
\r
/**\r
  The I2C controller received the stop bit from the\r
  I2C master.\r
\r
  @param[in] Context        The value passed to the slave enable routine.\r
  @param[in] BytesSent      Number of bytes successfully ACKed by the\r
                            I2C master.  This is a hint, not all I2C\r
                            controllers support the ability to return\r
                            the number of bytes sent.  When it is not\r
                            possible, the port driver returns zero.\r
  @param[in] Status         <ul>\r
                              <li>EFI_SUCCESS - All of the data was successfully sent</li>\r
                              <li>EFI_ABORTED - The controller was reset</li>\r
                              <li>EFI_DEVICE_ERROR - A NACK was received when sending the data.</li>\r
                              <li>EFI_END_OF_FILE - The stop bit was received before all of\r
                                the data was sent.</li>\r
                            </ul>\r
\r
**/\r
typedef\r
VOID\r
(EFIAPI *EFI_I2C_SLAVE_RECEIVE_STOP) (\r
  IN VOID *Context,\r
  IN UINTN BytesSent,\r
  IN EFI_STATUS Status\r
  );\r
\r
/**\r
  Enable or disable I2C slave operation.\r
\r
  The ReceiveData callback allows the port driver to return data\r
  to the driver or application handling slave mode operations.  This\r
  is data that a remote master has sent to the local I2C controller.\r
  The data may be returned one byte at a time if the controller supports\r
  the ability to ACK/NACK on each receive byte.  If not, a block of\r
  data may be returned by the I2C port driver and the ACK/NACK status\r
  is used only as a hint for the port driver.\r
\r
  The slave mode driver or application should buffer the data until\r
  either ReceiveStart or ReceiveStop is called.  At that time all of\r
  the data is received and the command may be processed.\r
\r
  ReceiveStart is called when the I2C master is expecting a response.\r
  After processing the command, but before sending the response the\r
  slave driver or application should mark the command as processed to\r
  avoid processing it a second time when ReceiveStop is called.  The\r
  slave driver or application then calls SendData to send to queue the\r
  response data for transmission.  The data must remain valid in the\r
  WriteBuffer until ReceiveStop is called.\r
\r
  ReceiveStop is called when the stop bit is received on the I2C bus.\r
  The slave driver or application starts processing the command if an\r
  command data is pending in the slave driver's or application's buffer.\r
  The BytesSent value is a hint to the slave driver or application as\r
  to how much data was returned to the I2C master.  If the controller\r
  does not provide this level of support then this value is set to zero.\r
\r
  @param[in] This           Address of an EFI_I2C_SLAVE_PROTOCOL\r
                            structure\r
  @param[in] SlaveAddress   Slave address for the I2C controller\r
  @param[in] Context        Address of a context structure for use when\r
                            calling ReceiveData or ReceiveStop\r
  @param[in] ReceiveData    Called by the I2C port driver as data bytes\r
                            are received from the master.  Response status\r
                            indicates if the byte is ACKed or NACKed. When\r
                            data is passed back a byte at a time, the port\r
                            driver must hold the clock until this callback\r
                            returns.\r
  @param[in] ReceiveStart   Called when the I2C controller receives a start bit.\r
  @param[in] ReceiveStop    Called after all of the data bytes are\r
                            received.\r
\r
  @retval EFI_SUCCESS       Slave operation is enabled on the controller.\r
  @retval EFI_UNSUPPORTED   The controller does not support this frequency.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_SLAVE_ENABLE) (\r
  IN CONST EFI_I2C_SLAVE_PROTOCOL *This,\r
  IN UINT32 SlaveAddress,\r
  IN VOID *Context,\r
  IN EFI_I2C_SLAVE_RECEIVE_DATA ReceiveData,\r
  IN EFI_I2C_SLAVE_RECEIVE_START ReceiveStart,\r
  IN EFI_I2C_SLAVE_RECEIVE_STOP ReceiveStop\r
  );\r
\r
/**\r
  Send data to the I2C master.\r
\r
  Port drivers may implement this as a blocking or non-blocking call.\r
  The data in the write buffer must remain valid until ReceiveStop or\r
  ReceiveStart is called indicating that the I2C master has terminated\r
  the transfer.\r
\r
  @param[in] This         Address of an EFI_I2C_SLAVE_PROTOCOL\r
                          structure\r
  @param[in] WriteBytes   Number of bytes to write\r
  @param[in] WriteBuffer  Buffer containing the data to send\r
\r
  @retval EFI_SUCCESS           Data waiting for master access.\r
  @retval EFI_INVALID_PARAMETER WriteBuffer is NULL or WriteBytes\r
                                is zero.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_I2C_SLAVE_SEND) (\r
  IN CONST EFI_I2C_SLAVE_PROTOCOL *This,\r
  IN UINTN WriteBytes,\r
  IN CONST UINT8 *WriteBuffer\r
  );\r
\r
///\r
/// I2C slave protocol\r
///\r
/// The port driver publishes this protocol when slave mode is\r
/// supported by the controller.\r
///\r
struct _EFI_I2C_SLAVE_PROTOCOL {\r
  ///\r
  /// Enable or disable I2C slave operation\r
  ///\r
  EFI_I2C_SLAVE_ENABLE SlaveEnable;\r
\r
  ///\r
  /// Send data to the I2C master\r
  ///\r
  EFI_I2C_SLAVE_SEND SendData;\r
};\r
\r
///\r
/// GUID for the EFI_I2C_SLAVE_PROTOCOL\r
///\r
extern EFI_GUID gEfiI2cSlaveProtocolGuid;\r
\r
#endif  //  __I2C_SLAVE_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	**/\r
	16	\r
	17	#ifndef __I2C_SLAVE_H__\r
	18	#define __I2C_SLAVE_H__\r
	19	\r
	20	#include <Protocol/I2cHostMcg.h>\r
	21	\r
	22	/**\r
	23	Declare the forward references\r
	24	\r
	25	**/\r
	26	typedef struct _EFI_I2C_SLAVE_PROTOCOL EFI_I2C_SLAVE_PROTOCOL; ///< I2C slave protocol\r
	27	\r
	28	/**\r
	29	The I2C controller received a data byte from the\r
	30	I2C msster.\r
	31	\r
	32	@param[in] Context The value passed to the slave enable routine.\r
	33	@param[in] NumberOfBytes Number of data bytes received\r
	34	@param[in] Data Buffer containing the received data bytes\r
	35	\r
	36	@retval EFI_SUCCESS ACK the data byte\r
	37	@retval EFI_UNSUPPORTED NACK the data byte\r
	38	\r
	39	**/\r
	40	typedef\r
	41	EFI_STATUS\r
	42	(EFIAPI *EFI_I2C_SLAVE_RECEIVE_DATA) (\r
	43	IN VOID *Context,\r
	44	IN UINTN NumberOfBytes,\r
	45	IN CONST UINT8 *Data\r
	46	);\r
	47	\r
	48	/**\r
	49	The I2C controller received the start bit from the\r
	50	I2C master.\r
	51	\r
	52	@param[in] Context The value passed to the slave enable routine.\r
	53	\r
	54	**/\r
	55	typedef\r
	56	VOID\r
	57	(EFIAPI *EFI_I2C_SLAVE_RECEIVE_START) (\r
	58	IN VOID *Context,\r
	59	IN UINTN BytesSent,\r
	60	IN EFI_STATUS Status\r
	61	);\r
	62	\r
	63	/**\r
	64	The I2C controller received the stop bit from the\r
65	I2C master.\r
66	\r
67	@param[in] Context The value passed to the slave enable routine.\r
68	@param[in] BytesSent Number of bytes successfully ACKed by the\r
69	I2C master. This is a hint, not all I2C\r
70	controllers support the ability to return\r
71	the number of bytes sent. When it is not\r
72	possible, the port driver returns zero.\r
73	@param[in] Status <ul>\r
74	<li>EFI_SUCCESS - All of the data was successfully sent</li>\r
75	<li>EFI_ABORTED - The controller was reset</li>\r
76	<li>EFI_DEVICE_ERROR - A NACK was received when sending the data.</li>\r
77	<li>EFI_END_OF_FILE - The stop bit was received before all of\r
78	the data was sent.</li>\r
79	</ul>\r
80	\r
81	**/\r
82	typedef\r
83	VOID\r
84	(EFIAPI *EFI_I2C_SLAVE_RECEIVE_STOP) (\r
85	IN VOID *Context,\r
86	IN UINTN BytesSent,\r
87	IN EFI_STATUS Status\r
88	);\r
89	\r
90	/**\r
91	Enable or disable I2C slave operation.\r
92	\r
93	The ReceiveData callback allows the port driver to return data\r
94	to the driver or application handling slave mode operations. This\r
95	is data that a remote master has sent to the local I2C controller.\r
96	The data may be returned one byte at a time if the controller supports\r
97	the ability to ACK/NACK on each receive byte. If not, a block of\r
98	data may be returned by the I2C port driver and the ACK/NACK status\r
99	is used only as a hint for the port driver.\r
100	\r
101	The slave mode driver or application should buffer the data until\r
102	either ReceiveStart or ReceiveStop is called. At that time all of\r
103	the data is received and the command may be processed.\r
104	\r
105	ReceiveStart is called when the I2C master is expecting a response.\r
106	After processing the command, but before sending the response the\r
107	slave driver or application should mark the command as processed to\r
108	avoid processing it a second time when ReceiveStop is called. The\r
109	slave driver or application then calls SendData to send to queue the\r
110	response data for transmission. The data must remain valid in the\r
111	WriteBuffer until ReceiveStop is called.\r
112	\r
113	ReceiveStop is called when the stop bit is received on the I2C bus.\r
114	The slave driver or application starts processing the command if an\r
115	command data is pending in the slave driver's or application's buffer.\r
116	The BytesSent value is a hint to the slave driver or application as\r
117	to how much data was returned to the I2C master. If the controller\r
118	does not provide this level of support then this value is set to zero.\r
119	\r
120	@param[in] This Address of an EFI_I2C_SLAVE_PROTOCOL\r
121	structure\r
122	@param[in] SlaveAddress Slave address for the I2C controller\r
123	@param[in] Context Address of a context structure for use when\r
124	calling ReceiveData or ReceiveStop\r
125	@param[in] ReceiveData Called by the I2C port driver as data bytes\r
126	are received from the master. Response status\r
127	indicates if the byte is ACKed or NACKed. When\r
128	data is passed back a byte at a time, the port\r
129	driver must hold the clock until this callback\r
130	returns.\r
131	@param[in] ReceiveStart Called when the I2C controller receives a start bit.\r
132	@param[in] ReceiveStop Called after all of the data bytes are\r
133	received.\r
134	\r
135	@retval EFI_SUCCESS Slave operation is enabled on the controller.\r
136	@retval EFI_UNSUPPORTED The controller does not support this frequency.\r
137	\r
138	**/\r
139	typedef\r
140	EFI_STATUS\r
141	(EFIAPI *EFI_I2C_SLAVE_ENABLE) (\r
142	IN CONST EFI_I2C_SLAVE_PROTOCOL *This,\r
143	IN UINT32 SlaveAddress,\r
144	IN VOID *Context,\r
145	IN EFI_I2C_SLAVE_RECEIVE_DATA ReceiveData,\r
146	IN EFI_I2C_SLAVE_RECEIVE_START ReceiveStart,\r
147	IN EFI_I2C_SLAVE_RECEIVE_STOP ReceiveStop\r
148	);\r
149	\r
150	/**\r
151	Send data to the I2C master.\r
152	\r
153	Port drivers may implement this as a blocking or non-blocking call.\r
154	The data in the write buffer must remain valid until ReceiveStop or\r
155	ReceiveStart is called indicating that the I2C master has terminated\r
156	the transfer.\r
157	\r
158	@param[in] This Address of an EFI_I2C_SLAVE_PROTOCOL\r
159	structure\r
160	@param[in] WriteBytes Number of bytes to write\r
161	@param[in] WriteBuffer Buffer containing the data to send\r
162	\r
163	@retval EFI_SUCCESS Data waiting for master access.\r
164	@retval EFI_INVALID_PARAMETER WriteBuffer is NULL or WriteBytes\r
165	is zero.\r
166	\r
167	**/\r
168	typedef\r
169	EFI_STATUS\r
170	(EFIAPI *EFI_I2C_SLAVE_SEND) (\r
171	IN CONST EFI_I2C_SLAVE_PROTOCOL *This,\r
172	IN UINTN WriteBytes,\r
173	IN CONST UINT8 *WriteBuffer\r
174	);\r
175	\r
176	///\r
177	/// I2C slave protocol\r
178	///\r
179	/// The port driver publishes this protocol when slave mode is\r
180	/// supported by the controller.\r
181	///\r
182	struct _EFI_I2C_SLAVE_PROTOCOL {\r
183	///\r
184	/// Enable or disable I2C slave operation\r
185	///\r
186	EFI_I2C_SLAVE_ENABLE SlaveEnable;\r
187	\r
188	///\r
189	/// Send data to the I2C master\r
190	///\r
191	EFI_I2C_SLAVE_SEND SendData;\r
192	};\r
193	\r
194	///\r
195	/// GUID for the EFI_I2C_SLAVE_PROTOCOL\r
196	///\r
197	extern EFI_GUID gEfiI2cSlaveProtocolGuid;\r
198	\r
199	#endif // __I2C_SLAVE_H__\r