[mirror_edk2.git] / EdkCompatibilityPkg / Foundation / Efi / Protocol / SerialIo / SerialIo.h

/*++\r
\r
Copyright (c) 2004, 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
Module Name:\r
\r
  SerialIo.h\r
\r
Abstract:\r
\r
  Serial IO protocol as defined in the EFI 1.0 specification.\r
\r
  Abstraction of a basic serial device. Targeted at 16550 UART, but\r
  could be much more generic.\r
\r
--*/\r
\r
#ifndef _SERIAL_IO_H_\r
#define _SERIAL_IO_H_\r
\r
#define EFI_SERIAL_IO_PROTOCOL_GUID \\r
  { \\r
    0xBB25CF6F, 0xF1D4, 0x11D2, 0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD \\r
  }\r
\r
EFI_FORWARD_DECLARATION (EFI_SERIAL_IO_PROTOCOL);\r
\r
//\r
// Serial IO Data structures\r
//\r
typedef enum {\r
  DefaultParity,\r
  NoParity,\r
  EvenParity,\r
  OddParity,\r
  MarkParity,\r
  SpaceParity\r
} EFI_PARITY_TYPE;\r
\r
typedef enum {\r
  DefaultStopBits,\r
  OneStopBit,\r
  OneFiveStopBits,\r
  TwoStopBits\r
} EFI_STOP_BITS_TYPE;\r
\r
//\r
// define for Control bits, grouped by read only, write only, and read write\r
//\r
//\r
// Read Only\r
//\r
#define EFI_SERIAL_CLEAR_TO_SEND        0x00000010\r
#define EFI_SERIAL_DATA_SET_READY       0x00000020\r
#define EFI_SERIAL_RING_INDICATE        0x00000040\r
#define EFI_SERIAL_CARRIER_DETECT       0x00000080\r
#define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100\r
#define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200\r
\r
//\r
// Write Only\r
//\r
#define EFI_SERIAL_REQUEST_TO_SEND      0x00000002\r
#define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001\r
\r
//\r
// Read Write\r
//\r
#define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x00001000\r
#define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x00002000\r
#define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000\r
\r
//\r
// Serial IO Member Functions\r
//\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SERIAL_RESET) (\r
  IN EFI_SERIAL_IO_PROTOCOL * This\r
  )\r
/*++\r
\r
  Routine Description:\r
    Reset the serial device.\r
\r
  Arguments:\r
    This     - Protocol instance pointer.\r
\r
  Returns:\r
    EFI_SUCCESS      - The device was reset.\r
    EFI_DEVICE_ERROR - The serial device could not be reset.\r
\r
--*/\r
;\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) (\r
  IN EFI_SERIAL_IO_PROTOCOL         * This,\r
  IN UINT64                         BaudRate,\r
  IN UINT32                         ReceiveFifoDepth,\r
  IN UINT32                         Timeout,\r
  IN EFI_PARITY_TYPE                Parity,\r
  IN UINT8                          DataBits,\r
  IN EFI_STOP_BITS_TYPE             StopBits\r
  )\r
/*++\r
\r
  Routine Description:\r
    Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, \r
    data buts, and stop bits on a serial device.\r
\r
  Arguments:\r
    This     - Protocol instance pointer.\r
    BaudRate - The requested baud rate. A BaudRate value of 0 will use the the\r
                device's default interface speed.\r
    ReveiveFifoDepth - The requested depth of the FIFO on the receive side of the\r
                       serial interface. A ReceiveFifoDepth value of 0 will use \r
                       the device's dfault FIFO depth.\r
    Timeout - The requested time out for a single character in microseconds. \r
              This timeout applies to both the transmit and receive side of the\r
              interface. A Timeout value of 0 will use the device's default time\r
              out value.\r
    Parity  - The type of parity to use on this serial device. A Parity value of\r
               DefaultParity will use the device's default parity value. \r
    DataBits - The number of data bits to use on the serial device. A DataBits\r
                vaule of 0 will use the device's default data bit setting.\r
    StopBits - The number of stop bits to use on this serial device. A StopBits\r
                value of DefaultStopBits will use the device's default number of\r
                stop bits. \r
\r
  Returns:\r
    EFI_SUCCESS      - The device was reset.\r
    EFI_DEVICE_ERROR - The serial device could not be reset.\r
\r
--*/\r
;\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SERIAL_SET_CONTROL_BITS) (\r
  IN EFI_SERIAL_IO_PROTOCOL         * This,\r
  IN UINT32                         Control\r
  )\r
/*++\r
\r
  Routine Description:\r
    Set the control bits on a serial device\r
\r
  Arguments:\r
    This    - Protocol instance pointer.\r
    Control - Set the bits of Control that are settable.\r
\r
  Returns:\r
    EFI_SUCCESS      - The new control bits were set on the serial device.\r
    EFI_UNSUPPORTED  - The serial device does not support this operation.\r
    EFI_DEVICE_ERROR - The serial device is not functioning correctly.\r
\r
--*/\r
;\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SERIAL_GET_CONTROL_BITS) (\r
  IN EFI_SERIAL_IO_PROTOCOL         * This,\r
  OUT UINT32                        *Control\r
  )\r
/*++\r
\r
  Routine Description:\r
    Retrieves the status of thecontrol bits on a serial device\r
\r
  Arguments:\r
    This    - Protocol instance pointer.\r
    Control - A pointer to return the current Control signals from the serial\r
               device.\r
\r
  Returns:\r
    EFI_SUCCESS      - The control bits were read from the serial device.\r
    EFI_DEVICE_ERROR - The serial device is not functioning correctly.\r
\r
--*/\r
;\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SERIAL_WRITE) (\r
  IN EFI_SERIAL_IO_PROTOCOL         * This,\r
  IN OUT UINTN                      *BufferSize,\r
  IN VOID                           *Buffer\r
  )\r
/*++\r
\r
  Routine Description:\r
    Writes data to a serial device.\r
\r
  Arguments:\r
    This    - Protocol instance pointer.\r
    BufferSize - On input, the size of the Buffer. On output, the amount of \r
                  data actually written.\r
    Buffer - The buffer of data to write\r
\r
  Returns:\r
    EFI_SUCCESS      - The data was written.\r
    EFI_DEVICE_ERROR - The device reported an error.\r
    EFI_TIMEOUT      - The data write was stopped due to a timeout.\r
\r
--*/\r
;\r
\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SERIAL_READ) (\r
  IN EFI_SERIAL_IO_PROTOCOL         * This,\r
  IN OUT UINTN                      *BufferSize,\r
  OUT VOID                          *Buffer\r
  )\r
/*++\r
\r
  Routine Description:\r
    Writes data to a serial device.\r
\r
  Arguments:\r
    This    - Protocol instance pointer.\r
    BufferSize - On input, the size of the Buffer. On output, the amount of \r
                  data returned in Buffer.\r
    Buffer - The buffer to return the data into.\r
\r
  Returns:\r
    EFI_SUCCESS      - The data was read.\r
    EFI_DEVICE_ERROR - The device reported an error.\r
    EFI_TIMEOUT      - The data write was stopped due to a timeout.\r
\r
--*/\r
;\r
\r
/*++\r
\r
  The data values in SERIAL_IO_MODE are read-only and are updated by the code \r
  that produces the SERIAL_IO_PROTOCOL member functions.\r
\r
  ControlMask - A mask fo the Control bits that the device supports. The device\r
                 must always support the Input Buffer Empty control bit.\r
  TimeOut  - If applicable, the number of microseconds to wait before timing out\r
              a Read or Write operation.\r
  BaudRate - If applicable, the current baud rate setting of the device; otherwise,\r
              baud rate has the value of zero to indicate that device runs at the\r
              device's designed speed.\r
  ReceiveFifoDepth - The number of characters the device will buffer on input\r
  DataBits - The number of characters the device will buffer on input\r
  Parity   - If applicable, this is the EFI_PARITY_TYPE that is computed or \r
             checked as each character is transmitted or reveived. If the device\r
             does not support parity the value is the default parity value.\r
  StopBits - If applicable, the EFI_STOP_BITS_TYPE number of stop bits per\r
              character. If the device does not support stop bits the value is\r
              the default stop bit values.\r
\r
--*/\r
typedef struct {\r
  UINT32  ControlMask;\r
\r
  //\r
  // current Attributes\r
  //\r
  UINT32  Timeout;\r
  UINT64  BaudRate;\r
  UINT32  ReceiveFifoDepth;\r
  UINT32  DataBits;\r
  UINT32  Parity;\r
  UINT32  StopBits;\r
} EFI_SERIAL_IO_MODE;\r
\r
#define SERIAL_IO_INTERFACE_REVISION  0x00010000\r
\r
struct _EFI_SERIAL_IO_PROTOCOL {\r
  UINT32                      Revision;\r
  EFI_SERIAL_RESET            Reset;\r
  EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;\r
  EFI_SERIAL_SET_CONTROL_BITS SetControl;\r
  EFI_SERIAL_GET_CONTROL_BITS GetControl;\r
  EFI_SERIAL_WRITE            Write;\r
  EFI_SERIAL_READ             Read;\r
\r
  EFI_SERIAL_IO_MODE          *Mode;\r
};\r
\r
extern EFI_GUID gEfiSerialIoProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
3eb9473e	1	/*++\r
	2	\r
	3	Copyright (c) 2004, Intel Corporation \r
	4	All rights reserved. This program and the accompanying materials \r
	5	are licensed and made available under the terms and conditions of the BSD License \r
	6	which accompanies this distribution. The full text of the license may be found at \r
	7	http://opensource.org/licenses/bsd-license.php \r
	8	\r
	9	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	10	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	11	\r
	12	Module Name:\r
	13	\r
	14	SerialIo.h\r
	15	\r
	16	Abstract:\r
	17	\r
	18	Serial IO protocol as defined in the EFI 1.0 specification.\r
	19	\r
	20	Abstraction of a basic serial device. Targeted at 16550 UART, but\r
	21	could be much more generic.\r
	22	\r
	23	--*/\r
	24	\r
	25	#ifndef _SERIAL_IO_H_\r
	26	#define _SERIAL_IO_H_\r
	27	\r
	28	#define EFI_SERIAL_IO_PROTOCOL_GUID \\r
	29	{ \\r
	30	0xBB25CF6F, 0xF1D4, 0x11D2, 0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD \\r
	31	}\r
	32	\r
	33	EFI_FORWARD_DECLARATION (EFI_SERIAL_IO_PROTOCOL);\r
	34	\r
	35	//\r
	36	// Serial IO Data structures\r
	37	//\r
	38	typedef enum {\r
	39	DefaultParity,\r
	40	NoParity,\r
	41	EvenParity,\r
	42	OddParity,\r
	43	MarkParity,\r
	44	SpaceParity\r
	45	} EFI_PARITY_TYPE;\r
	46	\r
	47	typedef enum {\r
	48	DefaultStopBits,\r
	49	OneStopBit,\r
	50	OneFiveStopBits,\r
	51	TwoStopBits\r
	52	} EFI_STOP_BITS_TYPE;\r
	53	\r
	54	//\r
	55	// define for Control bits, grouped by read only, write only, and read write\r
	56	//\r
	57	//\r
	58	// Read Only\r
	59	//\r
	60	#define EFI_SERIAL_CLEAR_TO_SEND 0x00000010\r
	61	#define EFI_SERIAL_DATA_SET_READY 0x00000020\r
	62	#define EFI_SERIAL_RING_INDICATE 0x00000040\r
	63	#define EFI_SERIAL_CARRIER_DETECT 0x00000080\r
	64	#define EFI_SERIAL_INPUT_BUFFER_EMPTY 0x00000100\r
65	#define EFI_SERIAL_OUTPUT_BUFFER_EMPTY 0x00000200\r
66	\r
67	//\r
68	// Write Only\r
69	//\r
70	#define EFI_SERIAL_REQUEST_TO_SEND 0x00000002\r
71	#define EFI_SERIAL_DATA_TERMINAL_READY 0x00000001\r
72	\r
73	//\r
74	// Read Write\r
75	//\r
76	#define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE 0x00001000\r
77	#define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE 0x00002000\r
78	#define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000\r
79	\r
80	//\r
81	// Serial IO Member Functions\r
82	//\r
83	typedef\r
84	EFI_STATUS\r
85	(EFIAPI *EFI_SERIAL_RESET) (\r
86	IN EFI_SERIAL_IO_PROTOCOL * This\r
87	)\r
88	/*++\r
89	\r
90	Routine Description:\r
91	Reset the serial device.\r
92	\r
93	Arguments:\r
94	This - Protocol instance pointer.\r
95	\r
96	Returns:\r
97	EFI_SUCCESS - The device was reset.\r
98	EFI_DEVICE_ERROR - The serial device could not be reset.\r
99	\r
100	--*/\r
101	;\r
102	\r
103	typedef\r
104	EFI_STATUS\r
105	(EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) (\r
106	IN EFI_SERIAL_IO_PROTOCOL * This,\r
107	IN UINT64 BaudRate,\r
108	IN UINT32 ReceiveFifoDepth,\r
109	IN UINT32 Timeout,\r
110	IN EFI_PARITY_TYPE Parity,\r
111	IN UINT8 DataBits,\r
112	IN EFI_STOP_BITS_TYPE StopBits\r
113	)\r
114	/*++\r
115	\r
116	Routine Description:\r
117	Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, \r
118	data buts, and stop bits on a serial device.\r
119	\r
120	Arguments:\r
121	This - Protocol instance pointer.\r
122	BaudRate - The requested baud rate. A BaudRate value of 0 will use the the\r
123	device's default interface speed.\r
124	ReveiveFifoDepth - The requested depth of the FIFO on the receive side of the\r
125	serial interface. A ReceiveFifoDepth value of 0 will use \r
126	the device's dfault FIFO depth.\r
127	Timeout - The requested time out for a single character in microseconds. \r
128	This timeout applies to both the transmit and receive side of the\r
129	interface. A Timeout value of 0 will use the device's default time\r
130	out value.\r
131	Parity - The type of parity to use on this serial device. A Parity value of\r
132	DefaultParity will use the device's default parity value. \r
133	DataBits - The number of data bits to use on the serial device. A DataBits\r
134	vaule of 0 will use the device's default data bit setting.\r
135	StopBits - The number of stop bits to use on this serial device. A StopBits\r
136	value of DefaultStopBits will use the device's default number of\r
137	stop bits. \r
138	\r
139	Returns:\r
140	EFI_SUCCESS - The device was reset.\r
141	EFI_DEVICE_ERROR - The serial device could not be reset.\r
142	\r
143	--*/\r
144	;\r
145	\r
146	typedef\r
147	EFI_STATUS\r
148	(EFIAPI *EFI_SERIAL_SET_CONTROL_BITS) (\r
149	IN EFI_SERIAL_IO_PROTOCOL * This,\r
150	IN UINT32 Control\r
151	)\r
152	/*++\r
153	\r
154	Routine Description:\r
155	Set the control bits on a serial device\r
156	\r
157	Arguments:\r
158	This - Protocol instance pointer.\r
159	Control - Set the bits of Control that are settable.\r
160	\r
161	Returns:\r
162	EFI_SUCCESS - The new control bits were set on the serial device.\r
163	EFI_UNSUPPORTED - The serial device does not support this operation.\r
164	EFI_DEVICE_ERROR - The serial device is not functioning correctly.\r
165	\r
166	--*/\r
167	;\r
168	\r
169	typedef\r
170	EFI_STATUS\r
171	(EFIAPI *EFI_SERIAL_GET_CONTROL_BITS) (\r
172	IN EFI_SERIAL_IO_PROTOCOL * This,\r
173	OUT UINT32 *Control\r
174	)\r
175	/*++\r
176	\r
177	Routine Description:\r
178	Retrieves the status of thecontrol bits on a serial device\r
179	\r
180	Arguments:\r
181	This - Protocol instance pointer.\r
182	Control - A pointer to return the current Control signals from the serial\r
183	device.\r
184	\r
185	Returns:\r
186	EFI_SUCCESS - The control bits were read from the serial device.\r
187	EFI_DEVICE_ERROR - The serial device is not functioning correctly.\r
188	\r
189	--*/\r
190	;\r
191	\r
192	typedef\r
193	EFI_STATUS\r
194	(EFIAPI *EFI_SERIAL_WRITE) (\r
195	IN EFI_SERIAL_IO_PROTOCOL * This,\r
196	IN OUT UINTN *BufferSize,\r
197	IN VOID *Buffer\r
198	)\r
199	/*++\r
200	\r
201	Routine Description:\r
202	Writes data to a serial device.\r
203	\r
204	Arguments:\r
205	This - Protocol instance pointer.\r
206	BufferSize - On input, the size of the Buffer. On output, the amount of \r
207	data actually written.\r
208	Buffer - The buffer of data to write\r
209	\r
210	Returns:\r
211	EFI_SUCCESS - The data was written.\r
212	EFI_DEVICE_ERROR - The device reported an error.\r
213	EFI_TIMEOUT - The data write was stopped due to a timeout.\r
214	\r
215	--*/\r
216	;\r
217	\r
218	typedef\r
219	EFI_STATUS\r
220	(EFIAPI *EFI_SERIAL_READ) (\r
221	IN EFI_SERIAL_IO_PROTOCOL * This,\r
222	IN OUT UINTN *BufferSize,\r
223	OUT VOID *Buffer\r
224	)\r
225	/*++\r
226	\r
227	Routine Description:\r
228	Writes data to a serial device.\r
229	\r
230	Arguments:\r
231	This - Protocol instance pointer.\r
232	BufferSize - On input, the size of the Buffer. On output, the amount of \r
233	data returned in Buffer.\r
234	Buffer - The buffer to return the data into.\r
235	\r
236	Returns:\r
237	EFI_SUCCESS - The data was read.\r
238	EFI_DEVICE_ERROR - The device reported an error.\r
239	EFI_TIMEOUT - The data write was stopped due to a timeout.\r
240	\r
241	--*/\r
242	;\r
243	\r
244	/*++\r
245	\r
246	The data values in SERIAL_IO_MODE are read-only and are updated by the code \r
247	that produces the SERIAL_IO_PROTOCOL member functions.\r
248	\r
249	ControlMask - A mask fo the Control bits that the device supports. The device\r
250	must always support the Input Buffer Empty control bit.\r
251	TimeOut - If applicable, the number of microseconds to wait before timing out\r
252	a Read or Write operation.\r
253	BaudRate - If applicable, the current baud rate setting of the device; otherwise,\r
254	baud rate has the value of zero to indicate that device runs at the\r
255	device's designed speed.\r
256	ReceiveFifoDepth - The number of characters the device will buffer on input\r
257	DataBits - The number of characters the device will buffer on input\r
258	Parity - If applicable, this is the EFI_PARITY_TYPE that is computed or \r
259	checked as each character is transmitted or reveived. If the device\r
260	does not support parity the value is the default parity value.\r
261	StopBits - If applicable, the EFI_STOP_BITS_TYPE number of stop bits per\r
262	character. If the device does not support stop bits the value is\r
263	the default stop bit values.\r
264	\r
265	--*/\r
266	typedef struct {\r
267	UINT32 ControlMask;\r
268	\r
269	//\r
270	// current Attributes\r
271	//\r
272	UINT32 Timeout;\r
273	UINT64 BaudRate;\r
274	UINT32 ReceiveFifoDepth;\r
275	UINT32 DataBits;\r
276	UINT32 Parity;\r
277	UINT32 StopBits;\r
278	} EFI_SERIAL_IO_MODE;\r
279	\r
280	#define SERIAL_IO_INTERFACE_REVISION 0x00010000\r
281	\r
e5bce275	282	struct _EFI_SERIAL_IO_PROTOCOL {\r
3eb9473e	283	UINT32 Revision;\r
	284	EFI_SERIAL_RESET Reset;\r
	285	EFI_SERIAL_SET_ATTRIBUTES SetAttributes;\r
	286	EFI_SERIAL_SET_CONTROL_BITS SetControl;\r
	287	EFI_SERIAL_GET_CONTROL_BITS GetControl;\r
	288	EFI_SERIAL_WRITE Write;\r
	289	EFI_SERIAL_READ Read;\r
	290	\r
	291	EFI_SERIAL_IO_MODE *Mode;\r
e5bce275	292	};\r
3eb9473e	293	\r
	294	extern EFI_GUID gEfiSerialIoProtocolGuid;\r
	295	\r
	296	#endif\r