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 - 2008, Intel Corporation
   8   All rights reserved. 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 following attributes for a serial device:
 108   * baud rate
 109   * receive FIFO depth
 110   * transmit/receive time out
 111   * parity
 112   * data bits
 113   * stop bits
 114
 115   @param  This             Protocol instance pointer.
 116   @param  BaudRate         The requested baud rate. A BaudRate value of 0 will use the
 117                            device's default interface speed.
 118   @param  ReveiveFifoDepth The requested depth of the FIFO on the receive side of the
 119                            serial interface. A ReceiveFifoDepth value of 0 will use
 120                            the device's default FIFO depth.
 121   @param  Timeout          The requested time out for a single character in microseconds.
 122                            This timeout applies to both the transmit and receive side of the
 123                            interface. A Timeout value of 0 will use the device's default time
 124                            out value.
 125   @param  Parity           The type of parity to use on this serial device. A Parity value of
 126                            DefaultParity will use the device's default parity value.
 127   @param  DataBits         The number of data bits to use on the serial device. A DataBits
 128                            vaule of 0 will use the device's default data bit setting.
 129   @param  StopBits         The number of stop bits to use on this serial device. A StopBits
 130                            value of DefaultStopBits will use the device's default number of
 131                            stop bits.
 132
 133   @retval EFI_SUCCESS      The device was reset.
 134   @retval EFI_DEVICE_ERROR The serial device could not be reset.
 135
 136 **/
 137 typedef
 138 EFI_STATUS
 139 (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES)(
 140   IN EFI_SERIAL_IO_PROTOCOL         *This,
 141   IN UINT64                         BaudRate,
 142   IN UINT32                         ReceiveFifoDepth,
 143   IN UINT32                         Timeout,
 144   IN EFI_PARITY_TYPE                Parity,
 145   IN UINT8                          DataBits,
 146   IN EFI_STOP_BITS_TYPE             StopBits
 147   );
 148
 149 /**
 150   Set the control bits on a serial device
 151
 152   @param  This             Protocol instance pointer.
 153   @param  Control          Set the bits of Control that are settable.
 154
 155   @retval EFI_SUCCESS      The new control bits were set on the serial device.
 156   @retval EFI_UNSUPPORTED  The serial device does not support this operation.
 157   @retval EFI_DEVICE_ERROR The serial device is not functioning correctly.
 158
 159 **/
 160 typedef
 161 EFI_STATUS
 162 (EFIAPI *EFI_SERIAL_SET_CONTROL_BITS)(
 163   IN EFI_SERIAL_IO_PROTOCOL         *This,
 164   IN UINT32                         Control
 165   );
 166
 167 /**
 168   Retrieves the status of thecontrol bits on a serial device
 169
 170   @param  This              Protocol instance pointer.
 171   @param  Control           A pointer to return the current Control signals from the serial device.
 172
 173   @retval EFI_SUCCESS       The control bits were read from the serial device.
 174   @retval EFI_DEVICE_ERROR  The serial device is not functioning correctly.
 175
 176 **/
 177 typedef
 178 EFI_STATUS
 179 (EFIAPI *EFI_SERIAL_GET_CONTROL_BITS)(
 180   IN EFI_SERIAL_IO_PROTOCOL         *This,
 181   OUT UINT32                        *Control
 182   );
 183
 184 /**
 185   Writes data to a serial device.
 186
 187   @param  This              Protocol instance pointer.
 188   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 189                             data actually written.
 190   @param  Buffer            The buffer of data to write
 191
 192   @retval EFI_SUCCESS       The data was written.
 193   @retval EFI_DEVICE_ERROR  The device reported an error.
 194   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 195
 196 **/
 197 typedef
 198 EFI_STATUS
 199 (EFIAPI *EFI_SERIAL_WRITE)(
 200   IN EFI_SERIAL_IO_PROTOCOL         *This,
 201   IN OUT UINTN                      *BufferSize,
 202   IN VOID                           *Buffer
 203   );
 204
 205 /**
 206   Writes data to a serial device.
 207
 208   @param  This              Protocol instance pointer.
 209   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 210                             data returned in Buffer.
 211   @param  Buffer            The buffer to which to return the data.
 212
 213   @retval EFI_SUCCESS       The data was read.
 214   @retval EFI_DEVICE_ERROR  The device reported an error.
 215   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 216
 217 **/
 218 typedef
 219 EFI_STATUS
 220 (EFIAPI *EFI_SERIAL_READ)(
 221   IN EFI_SERIAL_IO_PROTOCOL         *This,
 222   IN OUT UINTN                      *BufferSize,
 223   OUT VOID                          *Buffer
 224   );
 225
 226 /**
 227   @par Data Structure Description:
 228   The data values in SERIAL_IO_MODE are read-only and are updated by the code
 229   that produces the SERIAL_IO_PROTOCOL member functions.
 230
 231   @param ControlMask
 232   A mask for the Control bits that the device supports. The device
 233   must always support the Input Buffer Empty control bit.
 234
 235   @param TimeOut
 236   If applicable, the number of microseconds to wait before timing out
 237   a Read or Write operation.
 238
 239   @param BaudRate
 240   If applicable, the current baud rate setting of the device; otherwise,
 241   baud rate has the value of zero to indicate that device runs at the
 242   device's designed speed.
 243
 244   @param ReceiveFifoDepth
 245   The number of characters the device will buffer on input
 246
 247   @param DataBits
 248   The number of characters the device will buffer on input
 249
 250   @param Parity
 251   If applicable, this is the EFI_PARITY_TYPE that is computed or
 252   checked as each character is transmitted or reveived. If the device
 253   does not support parity the value is the default parity value.
 254
 255   @param StopBits
 256   If applicable, the EFI_STOP_BITS_TYPE number of stop bits per
 257   character. If the device does not support stop bits the value is
 258   the default stop bit values.
 259
 260 **/
 261 typedef struct {
 262   UINT32  ControlMask;
 263
 264   //
 265   // current Attributes
 266   //
 267   UINT32  Timeout;
 268   UINT64  BaudRate;
 269   UINT32  ReceiveFifoDepth;
 270   UINT32  DataBits;
 271   UINT32  Parity;
 272   UINT32  StopBits;
 273 } EFI_SERIAL_IO_MODE;
 274
 275 #define EFI_SERIAL_IO_PROTOCOL_REVISION    0x00010000
 276 #define SERIAL_IO_INTERFACE_REVISION  EFI_SERIAL_IO_PROTOCOL_REVISION
 277
 278 ///
 279 /// The Serial I/O protocol is used to communicate with UART-style serial devices.
 280 /// These can be standard UART serial ports in PC-AT systems, or serial ports attached
 281 /// to a USB interface or any character-based I/O device.
 282 ///
 283 struct _EFI_SERIAL_IO_PROTOCOL {
 284   ///
 285   /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions
 286   /// must be backwards compatible. If a future version is not backwards compatible,
 287   /// it is not the same GUID.
 288   ///
 289   UINT32                      Revision;
 290   EFI_SERIAL_RESET            Reset;
 291   EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;
 292   EFI_SERIAL_SET_CONTROL_BITS SetControl;
 293   EFI_SERIAL_GET_CONTROL_BITS GetControl;
 294   EFI_SERIAL_WRITE            Write;
 295   EFI_SERIAL_READ             Read;
 296   ///
 297   /// Pointer to SERIAL_IO_MODE data.
 298   ///
 299   EFI_SERIAL_IO_MODE          *Mode;
 300 };
 301
 302 extern EFI_GUID gEfiSerialIoProtocolGuid;
 303
 304 #endif