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 - 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
  31 typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL;
  32
  33
  34 ///
  35 /// Backward-compatible with EFI1.1.
  36 ///
  37 typedef 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 ///
  43 typedef enum {
  44   DefaultParity,
  45   NoParity,
  46   EvenParity,
  47   OddParity,
  48   MarkParity,
  49   SpaceParity
  50 } EFI_PARITY_TYPE;
  51
  52 ///
  53 /// Stop bits type
  54 ///
  55 typedef 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 **/
 100 typedef
 101 EFI_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_INVALID_PARAMETER One or more attributes has an unsupported value.
 130   @retval EFI_DEVICE_ERROR      The serial device is not functioning correctly.
 131
 132 **/
 133 typedef
 134 EFI_STATUS
 135 (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES)(
 136   IN EFI_SERIAL_IO_PROTOCOL         *This,
 137   IN UINT64                         BaudRate,
 138   IN UINT32                         ReceiveFifoDepth,
 139   IN UINT32                         Timeout,
 140   IN EFI_PARITY_TYPE                Parity,
 141   IN UINT8                          DataBits,
 142   IN EFI_STOP_BITS_TYPE             StopBits
 143   );
 144
 145 /**
 146   Set the control bits on a serial device
 147
 148   @param  This             Protocol instance pointer.
 149   @param  Control          Set the bits of Control that are settable.
 150
 151   @retval EFI_SUCCESS      The new control bits were set on the serial device.
 152   @retval EFI_UNSUPPORTED  The serial device does not support this operation.
 153   @retval EFI_DEVICE_ERROR The serial device is not functioning correctly.
 154
 155 **/
 156 typedef
 157 EFI_STATUS
 158 (EFIAPI *EFI_SERIAL_SET_CONTROL_BITS)(
 159   IN EFI_SERIAL_IO_PROTOCOL         *This,
 160   IN UINT32                         Control
 161   );
 162
 163 /**
 164   Retrieves the status of thecontrol bits on a serial device
 165
 166   @param  This              Protocol instance pointer.
 167   @param  Control           A pointer to return the current Control signals from the serial device.
 168
 169   @retval EFI_SUCCESS       The control bits were read from the serial device.
 170   @retval EFI_DEVICE_ERROR  The serial device is not functioning correctly.
 171
 172 **/
 173 typedef
 174 EFI_STATUS
 175 (EFIAPI *EFI_SERIAL_GET_CONTROL_BITS)(
 176   IN EFI_SERIAL_IO_PROTOCOL         *This,
 177   OUT UINT32                        *Control
 178   );
 179
 180 /**
 181   Writes data to a serial device.
 182
 183   @param  This              Protocol instance pointer.
 184   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 185                             data actually written.
 186   @param  Buffer            The buffer of data to write
 187
 188   @retval EFI_SUCCESS       The data was written.
 189   @retval EFI_DEVICE_ERROR  The device reported an error.
 190   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 191
 192 **/
 193 typedef
 194 EFI_STATUS
 195 (EFIAPI *EFI_SERIAL_WRITE)(
 196   IN EFI_SERIAL_IO_PROTOCOL         *This,
 197   IN OUT UINTN                      *BufferSize,
 198   IN VOID                           *Buffer
 199   );
 200
 201 /**
 202   Writes data to a serial device.
 203
 204   @param  This              Protocol instance pointer.
 205   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 206                             data returned in Buffer.
 207   @param  Buffer            The buffer to return the data into.
 208
 209   @retval EFI_SUCCESS       The data was read.
 210   @retval EFI_DEVICE_ERROR  The device reported an error.
 211   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 212
 213 **/
 214 typedef
 215 EFI_STATUS
 216 (EFIAPI *EFI_SERIAL_READ)(
 217   IN EFI_SERIAL_IO_PROTOCOL         *This,
 218   IN OUT UINTN                      *BufferSize,
 219   OUT VOID                          *Buffer
 220   );
 221
 222 /**
 223   @par Data Structure Description:
 224   The data values in SERIAL_IO_MODE are read-only and are updated by the code
 225   that produces the SERIAL_IO_PROTOCOL member functions.
 226
 227   @param ControlMask
 228   A mask for the Control bits that the device supports. The device
 229   must always support the Input Buffer Empty control bit.
 230
 231   @param TimeOut
 232   If applicable, the number of microseconds to wait before timing out
 233   a Read or Write operation.
 234
 235   @param BaudRate
 236   If applicable, the current baud rate setting of the device; otherwise,
 237   baud rate has the value of zero to indicate that device runs at the
 238   device's designed speed.
 239
 240   @param ReceiveFifoDepth
 241   The number of characters the device will buffer on input
 242
 243   @param DataBits
 244   The number of characters the device will buffer on input
 245
 246   @param Parity
 247   If applicable, this is the EFI_PARITY_TYPE that is computed or
 248   checked as each character is transmitted or reveived. If the device
 249   does not support parity the value is the default parity value.
 250
 251   @param StopBits
 252   If applicable, the EFI_STOP_BITS_TYPE number of stop bits per
 253   character. If the device does not support stop bits the value is
 254   the default stop bit values.
 255
 256 **/
 257 typedef struct {
 258   UINT32  ControlMask;
 259
 260   //
 261   // current Attributes
 262   //
 263   UINT32  Timeout;
 264   UINT64  BaudRate;
 265   UINT32  ReceiveFifoDepth;
 266   UINT32  DataBits;
 267   UINT32  Parity;
 268   UINT32  StopBits;
 269 } EFI_SERIAL_IO_MODE;
 270
 271 #define EFI_SERIAL_IO_PROTOCOL_REVISION    0x00010000
 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
 298 extern EFI_GUID gEfiSerialIoProtocolGuid;
 299
 300 #endif