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 baud rate, receive FIFO depth, transmit/receice time out, parity,
 108   data buts, 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 **/
 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 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 ///
 278 struct _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
 297 extern EFI_GUID gEfiSerialIoProtocolGuid;
 298
 299 #endif