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 - 2018, Intel Corporation. All rights reserved.<BR>
8   SPDX-License-Identifier: BSD-2-Clause-Patent
9 
10 **/
11 
12 #ifndef __SERIAL_IO_PROTOCOL_H__
13 #define __SERIAL_IO_PROTOCOL_H__
14 
15 #define EFI_SERIAL_IO_PROTOCOL_GUID \
16   { \
17     0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD } \
18   }
19 
20 #define EFI_SERIAL_TERMINAL_DEVICE_TYPE_GUID \
21   { \
22     0X6AD9A60F, 0X5815, 0X4C7C, { 0X8A, 0X10, 0X50, 0X53, 0XD2, 0XBF, 0X7A, 0X1B } \
23   }
24 
25 ///
26 /// Protocol GUID defined in EFI1.1.
27 ///
28 #define SERIAL_IO_PROTOCOL  EFI_SERIAL_IO_PROTOCOL_GUID
29 
30 typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL;
31 
32 ///
33 /// Backward-compatible with EFI1.1.
34 ///
35 typedef EFI_SERIAL_IO_PROTOCOL SERIAL_IO_INTERFACE;
36 
37 ///
38 /// Parity type that is computed or checked as each character is transmitted or received. If the
39 /// device does not support parity, the value is the default parity value.
40 ///
41 typedef enum {
42   DefaultParity,
43   NoParity,
44   EvenParity,
45   OddParity,
46   MarkParity,
47   SpaceParity
48 } EFI_PARITY_TYPE;
49 
50 ///
51 /// Stop bits type
52 ///
53 typedef enum {
54   DefaultStopBits,
55   OneStopBit,
56   OneFiveStopBits,
57   TwoStopBits
58 } EFI_STOP_BITS_TYPE;
59 
60 //
61 // define for Control bits, grouped by read only, write only, and read write
62 //
63 //
64 // Read Only
65 //
66 #define EFI_SERIAL_CLEAR_TO_SEND        0x00000010
67 #define EFI_SERIAL_DATA_SET_READY       0x00000020
68 #define EFI_SERIAL_RING_INDICATE        0x00000040
69 #define EFI_SERIAL_CARRIER_DETECT       0x00000080
70 #define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100
71 #define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200
72 
73 //
74 // Write Only
75 //
76 #define EFI_SERIAL_REQUEST_TO_SEND      0x00000002
77 #define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001
78 
79 //
80 // Read Write
81 //
82 #define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE      0x00001000
83 #define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE      0x00002000
84 #define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE  0x00004000
85 
86 //
87 // Serial IO Member Functions
88 //
89 
90 /**
91   Reset the serial device.
92 
93   @param  This              Protocol instance pointer.
94 
95   @retval EFI_SUCCESS       The device was reset.
96   @retval EFI_DEVICE_ERROR  The serial device could not be reset.
97 
98 **/
99 typedef
100 EFI_STATUS
101 (EFIAPI *EFI_SERIAL_RESET)(
102   IN EFI_SERIAL_IO_PROTOCOL *This
103   );
104 
105 /**
106   Sets the baud rate, receive FIFO depth, transmit/receice time out, parity,
107   data bits, and stop bits on a serial device.
108 
109   @param  This             Protocol instance pointer.
110   @param  BaudRate         The requested baud rate. A BaudRate value of 0 will use the
111                            device's default interface speed.
112   @param  ReveiveFifoDepth The requested depth of the FIFO on the receive side of the
113                            serial interface. A ReceiveFifoDepth value of 0 will use
114                            the device's default FIFO depth.
115   @param  Timeout          The requested time out for a single character in microseconds.
116                            This timeout applies to both the transmit and receive side of the
117                            interface. A Timeout value of 0 will use the device's default time
118                            out value.
119   @param  Parity           The type of parity to use on this serial device. A Parity value of
120                            DefaultParity will use the device's default parity value.
121   @param  DataBits         The number of data bits to use on the serial device. A DataBits
122                            vaule of 0 will use the device's default data bit setting.
123   @param  StopBits         The number of stop bits to use on this serial device. A StopBits
124                            value of DefaultStopBits will use the device's default number of
125                            stop bits.
126 
127   @retval EFI_SUCCESS           The device was reset.
128   @retval EFI_INVALID_PARAMETER One or more attributes has an unsupported value.
129   @retval EFI_DEVICE_ERROR      The serial device is not functioning correctly.
130 
131 **/
132 typedef
133 EFI_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 **/
155 typedef
156 EFI_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 **/
172 typedef
173 EFI_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 **/
192 typedef
193 EFI_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 **/
213 typedef
214 EFI_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 **/
256 typedef 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 EFI_SERIAL_IO_PROTOCOL_REVISION1p1  0x00010001
272 #define SERIAL_IO_INTERFACE_REVISION        EFI_SERIAL_IO_PROTOCOL_REVISION
273 
274 ///
275 /// The Serial I/O protocol is used to communicate with UART-style serial devices.
276 /// These can be standard UART serial ports in PC-AT systems, serial ports attached
277 /// to a USB interface, or potentially any character-based I/O device.
278 ///
279 struct _EFI_SERIAL_IO_PROTOCOL {
280   ///
281   /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions
282   /// must be backwards compatible. If a future version is not backwards compatible,
283   /// it is not the same GUID.
284   ///
285   UINT32                         Revision;
286   EFI_SERIAL_RESET               Reset;
287   EFI_SERIAL_SET_ATTRIBUTES      SetAttributes;
288   EFI_SERIAL_SET_CONTROL_BITS    SetControl;
289   EFI_SERIAL_GET_CONTROL_BITS    GetControl;
290   EFI_SERIAL_WRITE               Write;
291   EFI_SERIAL_READ                Read;
292   ///
293   /// Pointer to SERIAL_IO_MODE data.
294   ///
295   EFI_SERIAL_IO_MODE             *Mode;
296   ///
297   /// Pointer to a GUID identifying the device connected to the serial port.
298   /// This field is NULL when the protocol is installed by the serial port
299   /// driver and may be populated by a platform driver for a serial port
300   /// with a known device attached. The field will remain NULL if there is
301   /// no platform serial device identification information available.
302   ///
303   CONST EFI_GUID                 *DeviceTypeGuid; // Revision 1.1
304 };
305 
306 extern EFI_GUID  gEfiSerialIoProtocolGuid;
307 extern EFI_GUID  gEfiSerialTerminalDeviceTypeGuid;
308 
309 #endif
310