[mirror_edk2.git] / QuarkSocPkg / QuarkSouthCluster / Library / I2cLib / CommonHeader.h

/** @file\r
Provides definition of entry point to the common I2C module that produces\r
common I2C Controller functions used by I2C library services.\r
\r
\r
Copyright (c) 2013-2015 Intel Corporation.\r
\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
\r
#ifndef _I2CCOMMON_H_\r
#define _I2CCOMMON_H_\r
\r
#include <Uefi.h>\r
#include <Base.h>\r
\r
#include <Library/DebugLib.h>\r
#include <Library/TimerLib.h>\r
#include <Library/I2cLib.h>\r
#include <IohAccess.h>\r
#include <IohCommonDefinitions.h>\r
#include "I2cRegs.h"\r
\r
//\r
// Constants that define I2C Controller timeout and max. polling time.\r
//\r
#define MAX_T_POLL_COUNT         100\r
#define TI2C_POLL                25  // microseconds\r
#define MAX_STOP_DET_POLL_COUNT ((1000 * 1000) / TI2C_POLL)  // Extreme for expected Stop detect.\r
\r
/**\r
  The GetI2CIoPortBaseAddress() function gets IO port base address of I2C Controller.\r
\r
  Always reads PCI configuration space to get MMIO base address of I2C Controller.\r
\r
  @return The IO port base address of I2C controller.\r
\r
**/\r
UINTN\r
GetI2CIoPortBaseAddress (\r
  VOID\r
  );\r
\r
/**\r
  The EnableI2CMmioSpace() function enables access to I2C MMIO space.\r
\r
**/\r
VOID\r
EnableI2CMmioSpace (\r
  VOID\r
  );\r
\r
/**\r
  The DisableI2CController() functions disables I2C Controller.\r
\r
**/\r
VOID\r
DisableI2CController (\r
  VOID\r
  );\r
\r
/**\r
  The EnableI2CController() function enables the I2C Controller.\r
\r
**/\r
VOID\r
EnableI2CController (\r
  VOID\r
  );\r
\r
/**\r
  The WaitForStopDet() function waits until I2C STOP Condition occurs,\r
  indicating transfer completion.\r
\r
  @retval EFI_SUCCESS           Stop detected.\r
  @retval EFI_TIMEOUT           Timeout while waiting for stop condition.\r
  @retval EFI_ABORTED           Tx abort signaled in HW status register.\r
  @retval EFI_DEVICE_ERROR      Tx or Rx overflow detected.\r
\r
**/\r
EFI_STATUS\r
WaitForStopDet (\r
  VOID\r
  );\r
\r
/**\r
\r
  The InitializeInternal() function initialises internal I2C Controller\r
  register values that are commonly required for I2C Write and Read transfers.\r
\r
  @param AddrMode     I2C Addressing Mode: 7-bit or 10-bit address.\r
\r
  @retval EFI_SUCCESS           I2C Operation completed successfully.\r
\r
**/\r
EFI_STATUS\r
InitializeInternal (\r
  IN EFI_I2C_ADDR_MODE  AddrMode\r
  );\r
\r
/**\r
\r
  The WriteByte() function provides a standard way to execute a\r
  standard single byte write to an IC2 device (without accessing\r
  sub-addresses), as defined in the I2C Specification.\r
\r
  @param  I2CAddress      I2C Slave device address\r
  @param  Value           The 8-bit value to write.\r
\r
  @retval EFI_SUCCESS           Transfer success.\r
  @retval EFI_UNSUPPORTED       Unsupported input param.\r
  @retval EFI_TIMEOUT           Timeout while waiting xfer.\r
  @retval EFI_ABORTED           Controller aborted xfer.\r
  @retval EFI_DEVICE_ERROR      Device error detected by controller.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
WriteByte (\r
  IN  UINTN          I2CAddress,\r
  IN  UINT8          Value\r
  );\r
\r
/**\r
\r
  The ReadByte() function provides a standard way to execute a\r
  standard single byte read to an IC2 device (without accessing\r
  sub-addresses), as defined in the I2C Specification.\r
\r
  @param  I2CAddress      I2C Slave device address\r
  @param  ReturnDataPtr   Pointer to location to receive read byte.\r
\r
  @retval EFI_SUCCESS           Transfer success.\r
  @retval EFI_UNSUPPORTED       Unsupported input param.\r
  @retval EFI_TIMEOUT           Timeout while waiting xfer.\r
  @retval EFI_ABORTED           Controller aborted xfer.\r
  @retval EFI_DEVICE_ERROR      Device error detected by controller.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
ReadByte (\r
  IN  UINTN          I2CAddress,\r
  OUT UINT8          *ReturnDataPtr\r
  );\r
\r
/**\r
\r
  The WriteMultipleByte() function provides a standard way to execute\r
  multiple byte writes to an IC2 device (e.g. when accessing sub-addresses or\r
  when writing block of data), as defined in the I2C Specification.\r
\r
  @param I2CAddress   The I2C slave address of the device\r
                      with which to communicate.\r
\r
  @param WriteBuffer  Contains the value of byte to be written to the\r
                      I2C slave device.\r
\r
  @param Length       No. of bytes to be written.\r
\r
  @retval EFI_SUCCESS           Transfer success.\r
  @retval EFI_UNSUPPORTED       Unsupported input param.\r
  @retval EFI_TIMEOUT           Timeout while waiting xfer.\r
  @retval EFI_ABORTED           Tx abort signaled in HW status register.\r
  @retval EFI_DEVICE_ERROR      Tx overflow detected.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
WriteMultipleByte (\r
  IN  UINTN          I2CAddress,\r
  IN  UINT8          *WriteBuffer,\r
  IN  UINTN          Length\r
  );\r
\r
/**\r
\r
  The ReadMultipleByte() function provides a standard way to execute\r
  multiple byte writes to an IC2 device (e.g. when accessing sub-addresses or\r
  when reading block of data), as defined in the I2C Specification (I2C combined\r
  write/read protocol).\r
\r
  @param I2CAddress   The I2C slave address of the device\r
                      with which to communicate.\r
\r
  @param Buffer       Contains the value of byte data written or read from the\r
                      I2C slave device.\r
\r
  @param WriteLength  No. of bytes to be written. In this case data\r
                      written typically contains sub-address or sub-addresses\r
                      in Hi-Lo format, that need to be read (I2C combined\r
                      write/read protocol).\r
\r
  @param ReadLength   No. of bytes to be read from I2C slave device.\r
\r
  @retval EFI_SUCCESS           Transfer success.\r
  @retval EFI_UNSUPPORTED       Unsupported input param.\r
  @retval EFI_TIMEOUT           Timeout while waiting xfer.\r
  @retval EFI_ABORTED           Tx abort signaled in HW status register.\r
  @retval EFI_DEVICE_ERROR      Rx underflow or Rx/Tx overflow detected.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
ReadMultipleByte (\r
  IN  UINTN          I2CAddress,\r
  IN  OUT UINT8      *Buffer,\r
  IN  UINTN          WriteLength,\r
  IN  UINTN          ReadLength\r
  );\r
\r
#endif\r
Commit	Line	Data
9b6bbcdb MK	1	/** @file\r
	2	Provides definition of entry point to the common I2C module that produces\r
	3	common I2C Controller functions used by I2C library services.\r
	4	\r
	5	\r
	6	Copyright (c) 2013-2015 Intel Corporation.\r
	7	\r
c9f231d0	8	SPDX-License-Identifier: BSD-2-Clause-Patent\r
9b6bbcdb MK	9	\r
	10	**/\r
	11	\r
	12	\r
	13	#ifndef _I2CCOMMON_H_\r
	14	#define _I2CCOMMON_H_\r
	15	\r
	16	#include <Uefi.h>\r
	17	#include <Base.h>\r
	18	\r
	19	#include <Library/DebugLib.h>\r
	20	#include <Library/TimerLib.h>\r
	21	#include <Library/I2cLib.h>\r
	22	#include <IohAccess.h>\r
	23	#include <IohCommonDefinitions.h>\r
	24	#include "I2cRegs.h"\r
	25	\r
	26	//\r
	27	// Constants that define I2C Controller timeout and max. polling time.\r
	28	//\r
	29	#define MAX_T_POLL_COUNT 100\r
	30	#define TI2C_POLL 25 // microseconds\r
	31	#define MAX_STOP_DET_POLL_COUNT ((1000 * 1000) / TI2C_POLL) // Extreme for expected Stop detect.\r
	32	\r
	33	/**\r
	34	The GetI2CIoPortBaseAddress() function gets IO port base address of I2C Controller.\r
	35	\r
	36	Always reads PCI configuration space to get MMIO base address of I2C Controller.\r
	37	\r
	38	@return The IO port base address of I2C controller.\r
	39	\r
	40	**/\r
	41	UINTN\r
	42	GetI2CIoPortBaseAddress (\r
	43	VOID\r
	44	);\r
	45	\r
	46	/**\r
	47	The EnableI2CMmioSpace() function enables access to I2C MMIO space.\r
	48	\r
	49	**/\r
	50	VOID\r
	51	EnableI2CMmioSpace (\r
	52	VOID\r
	53	);\r
	54	\r
	55	/**\r
	56	The DisableI2CController() functions disables I2C Controller.\r
	57	\r
	58	**/\r
	59	VOID\r
	60	DisableI2CController (\r
	61	VOID\r
	62	);\r
	63	\r
	64	/**\r
	65	The EnableI2CController() function enables the I2C Controller.\r
	66	\r
	67	**/\r
	68	VOID\r
	69	EnableI2CController (\r
	70	VOID\r
	71	);\r
	72	\r
73	/**\r
74	The WaitForStopDet() function waits until I2C STOP Condition occurs,\r
75	indicating transfer completion.\r
76	\r
77	@retval EFI_SUCCESS Stop detected.\r
78	@retval EFI_TIMEOUT Timeout while waiting for stop condition.\r
79	@retval EFI_ABORTED Tx abort signaled in HW status register.\r
80	@retval EFI_DEVICE_ERROR Tx or Rx overflow detected.\r
81	\r
82	**/\r
83	EFI_STATUS\r
84	WaitForStopDet (\r
85	VOID\r
86	);\r
87	\r
88	/**\r
89	\r
90	The InitializeInternal() function initialises internal I2C Controller\r
91	register values that are commonly required for I2C Write and Read transfers.\r
92	\r
93	@param AddrMode I2C Addressing Mode: 7-bit or 10-bit address.\r
94	\r
95	@retval EFI_SUCCESS I2C Operation completed successfully.\r
96	\r
97	**/\r
98	EFI_STATUS\r
99	InitializeInternal (\r
100	IN EFI_I2C_ADDR_MODE AddrMode\r
101	);\r
102	\r
103	/**\r
104	\r
105	The WriteByte() function provides a standard way to execute a\r
106	standard single byte write to an IC2 device (without accessing\r
107	sub-addresses), as defined in the I2C Specification.\r
108	\r
109	@param I2CAddress I2C Slave device address\r
110	@param Value The 8-bit value to write.\r
111	\r
112	@retval EFI_SUCCESS Transfer success.\r
113	@retval EFI_UNSUPPORTED Unsupported input param.\r
114	@retval EFI_TIMEOUT Timeout while waiting xfer.\r
115	@retval EFI_ABORTED Controller aborted xfer.\r
116	@retval EFI_DEVICE_ERROR Device error detected by controller.\r
117	\r
118	**/\r
119	EFI_STATUS\r
120	EFIAPI\r
121	WriteByte (\r
122	IN UINTN I2CAddress,\r
123	IN UINT8 Value\r
124	);\r
125	\r
126	/**\r
127	\r
128	The ReadByte() function provides a standard way to execute a\r
129	standard single byte read to an IC2 device (without accessing\r
130	sub-addresses), as defined in the I2C Specification.\r
131	\r
132	@param I2CAddress I2C Slave device address\r
133	@param ReturnDataPtr Pointer to location to receive read byte.\r
134	\r
135	@retval EFI_SUCCESS Transfer success.\r
136	@retval EFI_UNSUPPORTED Unsupported input param.\r
137	@retval EFI_TIMEOUT Timeout while waiting xfer.\r
138	@retval EFI_ABORTED Controller aborted xfer.\r
139	@retval EFI_DEVICE_ERROR Device error detected by controller.\r
140	\r
141	**/\r
142	EFI_STATUS\r
143	EFIAPI\r
144	ReadByte (\r
145	IN UINTN I2CAddress,\r
146	OUT UINT8 *ReturnDataPtr\r
147	);\r
148	\r
149	/**\r
150	\r
151	The WriteMultipleByte() function provides a standard way to execute\r
152	multiple byte writes to an IC2 device (e.g. when accessing sub-addresses or\r
153	when writing block of data), as defined in the I2C Specification.\r
154	\r
155	@param I2CAddress The I2C slave address of the device\r
156	with which to communicate.\r
157	\r
158	@param WriteBuffer Contains the value of byte to be written to the\r
159	I2C slave device.\r
160	\r
161	@param Length No. of bytes to be written.\r
162	\r
163	@retval EFI_SUCCESS Transfer success.\r
164	@retval EFI_UNSUPPORTED Unsupported input param.\r
165	@retval EFI_TIMEOUT Timeout while waiting xfer.\r
166	@retval EFI_ABORTED Tx abort signaled in HW status register.\r
167	@retval EFI_DEVICE_ERROR Tx overflow detected.\r
168	\r
169	**/\r
170	EFI_STATUS\r
171	EFIAPI\r
172	WriteMultipleByte (\r
173	IN UINTN I2CAddress,\r
174	IN UINT8 *WriteBuffer,\r
175	IN UINTN Length\r
176	);\r
177	\r
178	/**\r
179	\r
180	The ReadMultipleByte() function provides a standard way to execute\r
181	multiple byte writes to an IC2 device (e.g. when accessing sub-addresses or\r
182	when reading block of data), as defined in the I2C Specification (I2C combined\r
183	write/read protocol).\r
184	\r
185	@param I2CAddress The I2C slave address of the device\r
186	with which to communicate.\r
187	\r
188	@param Buffer Contains the value of byte data written or read from the\r
189	I2C slave device.\r
190	\r
191	@param WriteLength No. of bytes to be written. In this case data\r
192	written typically contains sub-address or sub-addresses\r
193	in Hi-Lo format, that need to be read (I2C combined\r
194	write/read protocol).\r
195	\r
196	@param ReadLength No. of bytes to be read from I2C slave device.\r
197	\r
198	@retval EFI_SUCCESS Transfer success.\r
199	@retval EFI_UNSUPPORTED Unsupported input param.\r
200	@retval EFI_TIMEOUT Timeout while waiting xfer.\r
201	@retval EFI_ABORTED Tx abort signaled in HW status register.\r
202	@retval EFI_DEVICE_ERROR Rx underflow or Rx/Tx overflow detected.\r
203	\r
204	**/\r
205	EFI_STATUS\r
206	EFIAPI\r
207	ReadMultipleByte (\r
208	IN UINTN I2CAddress,\r
209	IN OUT UINT8 *Buffer,\r
210	IN UINTN WriteLength,\r
211	IN UINTN ReadLength\r
212	);\r
213	\r
214	#endif\r