EdkCompatibilityPkg/Foundation/Efi/Protocol/SerialIo/SerialIo.h

   1 /*++
   2
   3 Copyright (c) 2004, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   SerialIo.h
  15
  16 Abstract:
  17
  18   Serial IO protocol as defined in the EFI 1.0 specification.
  19
  20   Abstraction of a basic serial device. Targeted at 16550 UART, but
  21   could be much more generic.
  22
  23 --*/
  24
  25 #ifndef _SERIAL_IO_H_
  26 #define _SERIAL_IO_H_
  27
  28 #define EFI_SERIAL_IO_PROTOCOL_GUID \
  29   { \
  30     0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD} \
  31   }
  32
  33 EFI_FORWARD_DECLARATION (EFI_SERIAL_IO_PROTOCOL);
  34
  35 //
  36 // Serial IO Data structures
  37 //
  38 typedef enum {
  39   DefaultParity,
  40   NoParity,
  41   EvenParity,
  42   OddParity,
  43   MarkParity,
  44   SpaceParity
  45 } EFI_PARITY_TYPE;
  46
  47 typedef enum {
  48   DefaultStopBits,
  49   OneStopBit,
  50   OneFiveStopBits,
  51   TwoStopBits
  52 } EFI_STOP_BITS_TYPE;
  53
  54 //
  55 // define for Control bits, grouped by read only, write only, and read write
  56 //
  57 //
  58 // Read Only
  59 //
  60 #define EFI_SERIAL_CLEAR_TO_SEND        0x00000010
  61 #define EFI_SERIAL_DATA_SET_READY       0x00000020
  62 #define EFI_SERIAL_RING_INDICATE        0x00000040
  63 #define EFI_SERIAL_CARRIER_DETECT       0x00000080
  64 #define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100
  65 #define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200
  66
  67 //
  68 // Write Only
  69 //
  70 #define EFI_SERIAL_REQUEST_TO_SEND      0x00000002
  71 #define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001
  72
  73 //
  74 // Read Write
  75 //
  76 #define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x00001000
  77 #define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x00002000
  78 #define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000
  79
  80 //
  81 // Serial IO Member Functions
  82 //
  83 typedef
  84 EFI_STATUS
  85 (EFIAPI *EFI_SERIAL_RESET) (
  86   IN EFI_SERIAL_IO_PROTOCOL * This
  87   )
  88 /*++
  89
  90   Routine Description:
  91     Reset the serial device.
  92
  93   Arguments:
  94     This     - Protocol instance pointer.
  95
  96   Returns:
  97     EFI_SUCCESS      - The device was reset.
  98     EFI_DEVICE_ERROR - The serial device could not be reset.
  99
 100 --*/
 101 ;
 102
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) (
 106   IN EFI_SERIAL_IO_PROTOCOL         * This,
 107   IN UINT64                         BaudRate,
 108   IN UINT32                         ReceiveFifoDepth,
 109   IN UINT32                         Timeout,
 110   IN EFI_PARITY_TYPE                Parity,
 111   IN UINT8                          DataBits,
 112   IN EFI_STOP_BITS_TYPE             StopBits
 113   )
 114 /*++
 115
 116   Routine Description:
 117     Sets the baud rate, receive FIFO depth, transmit/receice time out, parity,
 118     data buts, and stop bits on a serial device.
 119
 120   Arguments:
 121     This     - Protocol instance pointer.
 122     BaudRate - The requested baud rate. A BaudRate value of 0 will use the the
 123                 device's default interface speed.
 124     ReveiveFifoDepth - The requested depth of the FIFO on the receive side of the
 125                        serial interface. A ReceiveFifoDepth value of 0 will use
 126                        the device's dfault FIFO depth.
 127     Timeout - The requested time out for a single character in microseconds.
 128               This timeout applies to both the transmit and receive side of the
 129               interface. A Timeout value of 0 will use the device's default time
 130               out value.
 131     Parity  - The type of parity to use on this serial device. A Parity value of
 132                DefaultParity will use the device's default parity value.
 133     DataBits - The number of data bits to use on the serial device. A DataBits
 134                 vaule of 0 will use the device's default data bit setting.
 135     StopBits - The number of stop bits to use on this serial device. A StopBits
 136                 value of DefaultStopBits will use the device's default number of
 137                 stop bits.
 138
 139   Returns:
 140     EFI_SUCCESS      - The device was reset.
 141     EFI_DEVICE_ERROR - The serial device could not be reset.
 142
 143 --*/
 144 ;
 145
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_SERIAL_SET_CONTROL_BITS) (
 149   IN EFI_SERIAL_IO_PROTOCOL         * This,
 150   IN UINT32                         Control
 151   )
 152 /*++
 153
 154   Routine Description:
 155     Set the control bits on a serial device
 156
 157   Arguments:
 158     This    - Protocol instance pointer.
 159     Control - Set the bits of Control that are settable.
 160
 161   Returns:
 162     EFI_SUCCESS      - The new control bits were set on the serial device.
 163     EFI_UNSUPPORTED  - The serial device does not support this operation.
 164     EFI_DEVICE_ERROR - The serial device is not functioning correctly.
 165
 166 --*/
 167 ;
 168
 169 typedef
 170 EFI_STATUS
 171 (EFIAPI *EFI_SERIAL_GET_CONTROL_BITS) (
 172   IN EFI_SERIAL_IO_PROTOCOL         * This,
 173   OUT UINT32                        *Control
 174   )
 175 /*++
 176
 177   Routine Description:
 178     Retrieves the status of thecontrol bits on a serial device
 179
 180   Arguments:
 181     This    - Protocol instance pointer.
 182     Control - A pointer to return the current Control signals from the serial
 183                device.
 184
 185   Returns:
 186     EFI_SUCCESS      - The control bits were read from the serial device.
 187     EFI_DEVICE_ERROR - The serial device is not functioning correctly.
 188
 189 --*/
 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   Routine Description:
 202     Writes data to a serial device.
 203
 204   Arguments:
 205     This    - Protocol instance pointer.
 206     BufferSize - On input, the size of the Buffer. On output, the amount of
 207                   data actually written.
 208     Buffer - The buffer of data to write
 209
 210   Returns:
 211     EFI_SUCCESS      - The data was written.
 212     EFI_DEVICE_ERROR - The device reported an error.
 213     EFI_TIMEOUT      - The data write was stopped due to a timeout.
 214
 215 --*/
 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   Routine Description:
 228     Writes data to a serial device.
 229
 230   Arguments:
 231     This    - Protocol instance pointer.
 232     BufferSize - On input, the size of the Buffer. On output, the amount of
 233                   data returned in Buffer.
 234     Buffer - The buffer to return the data into.
 235
 236   Returns:
 237     EFI_SUCCESS      - The data was read.
 238     EFI_DEVICE_ERROR - The device reported an error.
 239     EFI_TIMEOUT      - The data write was stopped due to a timeout.
 240
 241 --*/
 242 ;
 243
 244 /*++
 245
 246   The data values in SERIAL_IO_MODE are read-only and are updated by the code
 247   that produces the SERIAL_IO_PROTOCOL member functions.
 248
 249   ControlMask - A mask fo the Control bits that the device supports. The device
 250                  must always support the Input Buffer Empty control bit.
 251   TimeOut  - If applicable, the number of microseconds to wait before timing out
 252               a Read or Write operation.
 253   BaudRate - If applicable, the current baud rate setting of the device; otherwise,
 254               baud rate has the value of zero to indicate that device runs at the
 255               device's designed speed.
 256   ReceiveFifoDepth - The number of characters the device will buffer on input
 257   DataBits - The number of characters the device will buffer on input
 258   Parity   - If applicable, this is the EFI_PARITY_TYPE that is computed or
 259              checked as each character is transmitted or reveived. If the device
 260              does not support parity the value is the default parity value.
 261   StopBits - If applicable, the EFI_STOP_BITS_TYPE number of stop bits per
 262               character. If the device does not support stop bits the value is
 263               the default stop bit values.
 264
 265 --*/
 266 typedef struct {
 267   UINT32  ControlMask;
 268
 269   //
 270   // current Attributes
 271   //
 272   UINT32  Timeout;
 273   UINT64  BaudRate;
 274   UINT32  ReceiveFifoDepth;
 275   UINT32  DataBits;
 276   UINT32  Parity;
 277   UINT32  StopBits;
 278 } EFI_SERIAL_IO_MODE;
 279
 280 #define SERIAL_IO_INTERFACE_REVISION  0x00010000
 281
 282 struct _EFI_SERIAL_IO_PROTOCOL {
 283   UINT32                      Revision;
 284   EFI_SERIAL_RESET            Reset;
 285   EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;
 286   EFI_SERIAL_SET_CONTROL_BITS SetControl;
 287   EFI_SERIAL_GET_CONTROL_BITS GetControl;
 288   EFI_SERIAL_WRITE            Write;
 289   EFI_SERIAL_READ             Read;
 290
 291   EFI_SERIAL_IO_MODE          *Mode;
 292 };
 293
 294 extern EFI_GUID gEfiSerialIoProtocolGuid;
 295
 296 #endif