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