MdePkg/Include/Protocol/SerialIo.h

   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 ///
  34 /// Backward-compatible with EFI1.1.
  35 ///
  36 typedef EFI_SERIAL_IO_PROTOCOL  SERIAL_IO_INTERFACE;
  37
  38 ///
  39 /// Parity type that is computed or checked as each character is transmitted or received. If the
  40 /// device does not support parity, the value is the default parity value.
  41 ///
  42 typedef enum {
  43   DefaultParity,
  44   NoParity,
  45   EvenParity,
  46   OddParity,
  47   MarkParity,
  48   SpaceParity
  49 } EFI_PARITY_TYPE;
  50
  51 ///
  52 /// Stop bits type
  53 ///
  54 typedef enum {
  55   DefaultStopBits,
  56   OneStopBit,
  57   OneFiveStopBits,
  58   TwoStopBits
  59 } EFI_STOP_BITS_TYPE;
  60
  61 //
  62 // define for Control bits, grouped by read only, write only, and read write
  63 //
  64 //
  65 // Read Only
  66 //
  67 #define EFI_SERIAL_CLEAR_TO_SEND        0x00000010
  68 #define EFI_SERIAL_DATA_SET_READY       0x00000020
  69 #define EFI_SERIAL_RING_INDICATE        0x00000040
  70 #define EFI_SERIAL_CARRIER_DETECT       0x00000080
  71 #define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100
  72 #define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200
  73
  74 //
  75 // Write Only
  76 //
  77 #define EFI_SERIAL_REQUEST_TO_SEND      0x00000002
  78 #define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001
  79
  80 //
  81 // Read Write
  82 //
  83 #define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x00001000
  84 #define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x00002000
  85 #define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000
  86
  87 //
  88 // Serial IO Member Functions
  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