MdePkg/Include/Protocol/SerialIo.h

   1 /** @file
   2   Serial IO protocol as defined in the EFI 1.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, 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   Module Name:  SerialIo.h
  17
  18 **/
  19
  20 #ifndef __SERIAL_IO_PROTOCOL_H__
  21 #define __SERIAL_IO_PROTOCOL_H__
  22
  23 #define EFI_SERIAL_IO_PROTOCOL_GUID \
  24   { \
  25     0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD } \
  26   }
  27
  28 typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL;
  29
  30 //
  31 // Serial IO Data structures
  32 //
  33 typedef enum {
  34   DefaultParity,
  35   NoParity,
  36   EvenParity,
  37   OddParity,
  38   MarkParity,
  39   SpaceParity
  40 } EFI_PARITY_TYPE;
  41
  42 typedef enum {
  43   DefaultStopBits,
  44   OneStopBit,
  45   OneFiveStopBits,
  46   TwoStopBits
  47 } EFI_STOP_BITS_TYPE;
  48
  49 //
  50 // define for Control bits, grouped by read only, write only, and read write
  51 //
  52 //
  53 // Read Only
  54 //
  55 #define EFI_SERIAL_CLEAR_TO_SEND        0x00000010
  56 #define EFI_SERIAL_DATA_SET_READY       0x00000020
  57 #define EFI_SERIAL_RING_INDICATE        0x00000040
  58 #define EFI_SERIAL_CARRIER_DETECT       0x00000080
  59 #define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100
  60 #define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200
  61
  62 //
  63 // Write Only
  64 //
  65 #define EFI_SERIAL_REQUEST_TO_SEND      0x00000002
  66 #define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001
  67
  68 //
  69 // Read Write
  70 //
  71 #define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x00001000
  72 #define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x00002000
  73 #define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000
  74
  75 //
  76 // Serial IO Member Functions
  77 //
  78 /**
  79   Reset the serial device.
  80
  81   @param  This              Protocol instance pointer.
  82
  83   @retval EFI_SUCCESS       The device was reset.
  84   @retval EFI_DEVICE_ERROR  The serial device could not be reset.
  85
  86 **/
  87 typedef
  88 EFI_STATUS
  89 (EFIAPI *EFI_SERIAL_RESET) (
  90   IN EFI_SERIAL_IO_PROTOCOL *This
  91   )
  92 ;
  93
  94 /**
  95   Sets the baud rate, receive FIFO depth, transmit/receice time out, parity,
  96   data buts, and stop bits on a serial device.
  97
  98   @param  This             Protocol instance pointer.
  99   @param  BaudRate         The requested baud rate. A BaudRate value of 0 will use the the
 100                            device's default interface speed.
 101   @param  ReveiveFifoDepth The requested depth of the FIFO on the receive side of the
 102                            serial interface. A ReceiveFifoDepth value of 0 will use
 103                            the device's dfault FIFO depth.
 104   @param  Timeout          The requested time out for a single character in microseconds.
 105                            This timeout applies to both the transmit and receive side of the
 106                            interface. A Timeout value of 0 will use the device's default time
 107                            out value.
 108   @param  Parity           The type of parity to use on this serial device. A Parity value of
 109                            DefaultParity will use the device's default parity value.
 110   @param  DataBits         The number of data bits to use on the serial device. A DataBits
 111                            vaule of 0 will use the device's default data bit setting.
 112   @param  StopBits         The number of stop bits to use on this serial device. A StopBits
 113                            value of DefaultStopBits will use the device's default number of
 114                            stop bits.
 115
 116   @retval EFI_SUCCESS      The device was reset.
 117   @retval EFI_DEVICE_ERROR The serial device could not be reset.
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) (
 123   IN EFI_SERIAL_IO_PROTOCOL         *This,
 124   IN UINT64                         BaudRate,
 125   IN UINT32                         ReceiveFifoDepth,
 126   IN UINT32                         Timeout,
 127   IN EFI_PARITY_TYPE                Parity,
 128   IN UINT8                          DataBits,
 129   IN EFI_STOP_BITS_TYPE             StopBits
 130   )
 131 ;
 132
 133 /**
 134   Set the control bits on a serial device
 135
 136   @param  This             Protocol instance pointer.
 137   @param  Control          Set the bits of Control that are settable.
 138
 139   @retval EFI_SUCCESS      The new control bits were set on the serial device.
 140   @retval EFI_UNSUPPORTED  The serial device does not support this operation.
 141   @retval EFI_DEVICE_ERROR The serial device is not functioning correctly.
 142
 143 **/
 144 typedef
 145 EFI_STATUS
 146 (EFIAPI *EFI_SERIAL_SET_CONTROL_BITS) (
 147   IN EFI_SERIAL_IO_PROTOCOL         *This,
 148   IN UINT32                         Control
 149   )
 150 ;
 151
 152 /**
 153   Retrieves the status of thecontrol bits on a serial device
 154
 155   @param  This              Protocol instance pointer.
 156   @param  Control           A pointer to return the current Control signals from the serial device.
 157
 158   @retval EFI_SUCCESS       The control bits were read from the serial device.
 159   @retval EFI_DEVICE_ERROR  The serial device is not functioning correctly.
 160
 161 **/
 162 typedef
 163 EFI_STATUS
 164 (EFIAPI *EFI_SERIAL_GET_CONTROL_BITS) (
 165   IN EFI_SERIAL_IO_PROTOCOL         *This,
 166   OUT UINT32                        *Control
 167   )
 168 ;
 169
 170 /**
 171   Writes data to a serial device.
 172
 173   @param  This              Protocol instance pointer.
 174   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 175                             data actually written.
 176   @param  Buffer            The buffer of data to write
 177
 178   @retval EFI_SUCCESS       The data was written.
 179   @retval EFI_DEVICE_ERROR  The device reported an error.
 180   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 181
 182 **/
 183 typedef
 184 EFI_STATUS
 185 (EFIAPI *EFI_SERIAL_WRITE) (
 186   IN EFI_SERIAL_IO_PROTOCOL         *This,
 187   IN OUT UINTN                      *BufferSize,
 188   IN VOID                           *Buffer
 189   )
 190 ;
 191
 192 /**
 193   Writes data to a serial device.
 194
 195   @param  This              Protocol instance pointer.
 196   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
 197                             data returned in Buffer.
 198   @param  Buffer            The buffer to return the data into.
 199
 200   @retval EFI_SUCCESS       The data was read.
 201   @retval EFI_DEVICE_ERROR  The device reported an error.
 202   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
 203
 204 **/
 205 typedef
 206 EFI_STATUS
 207 (EFIAPI *EFI_SERIAL_READ) (
 208   IN EFI_SERIAL_IO_PROTOCOL         *This,
 209   IN OUT UINTN                      *BufferSize,
 210   OUT VOID                          *Buffer
 211   )
 212 ;
 213
 214 /**
 215   The data values in SERIAL_IO_MODE are read-only and are updated by the code
 216   that produces the SERIAL_IO_PROTOCOL member functions.
 217
 218   ControlMask - A mask fo the Control bits that the device supports. The device
 219   must always support the Input Buffer Empty control bit.
 220   TimeOut  - If applicable, the number of microseconds to wait before timing out
 221   a Read or Write operation.
 222   BaudRate - If applicable, the current baud rate setting of the device; otherwise,
 223   baud rate has the value of zero to indicate that device runs at the
 224   device's designed speed.
 225   ReceiveFifoDepth - The number of characters the device will buffer on input
 226   DataBits - The number of characters the device will buffer on input
 227   Parity   - If applicable, this is the EFI_PARITY_TYPE that is computed or
 228   checked as each character is transmitted or reveived. If the device
 229   does not support parity the value is the default parity value.
 230   StopBits - If applicable, the EFI_STOP_BITS_TYPE number of stop bits per
 231   character. If the device does not support stop bits the value is
 232   the default stop bit values.
 233
 234 **/
 235 typedef struct {
 236   UINT32  ControlMask;
 237
 238   //
 239   // current Attributes
 240   //
 241   UINT32  Timeout;
 242   UINT64  BaudRate;
 243   UINT32  ReceiveFifoDepth;
 244   UINT32  DataBits;
 245   UINT32  Parity;
 246   UINT32  StopBits;
 247 } EFI_SERIAL_IO_MODE;
 248
 249 #define SERIAL_IO_INTERFACE_REVISION    0x00010000
 250 #define EFI_SERIAL_IO_PROTOCOL_REVISION SERIAL_IO_INTERFACE_REVISION
 251
 252 struct _EFI_SERIAL_IO_PROTOCOL {
 253   UINT32                      Revision;
 254   EFI_SERIAL_RESET            Reset;
 255   EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;
 256   EFI_SERIAL_SET_CONTROL_BITS SetControl;
 257   EFI_SERIAL_GET_CONTROL_BITS GetControl;
 258   EFI_SERIAL_WRITE            Write;
 259   EFI_SERIAL_READ             Read;
 260
 261   EFI_SERIAL_IO_MODE          *Mode;
 262 };
 263
 264 extern EFI_GUID gEfiSerialIoProtocolGuid;
 265
 266 #endif