iPXE
SerialIo.h
Go to the documentation of this file.
00001 /** @file
00002   Serial IO protocol as defined in the UEFI 2.0 specification.
00003 
00004   Abstraction of a basic serial device. Targeted at 16550 UART, but
00005   could be much more generic.
00006 
00007   Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>
00008   This program and the accompanying materials
00009   are licensed and made available under the terms and conditions of the BSD License
00010   which accompanies this distribution.  The full text of the license may be found at
00011   http://opensource.org/licenses/bsd-license.php
00012 
00013   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00014   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00015 
00016 **/
00017 
00018 #ifndef __SERIAL_IO_PROTOCOL_H__
00019 #define __SERIAL_IO_PROTOCOL_H__
00020 
00021 FILE_LICENCE ( BSD3 );
00022 
00023 #define EFI_SERIAL_IO_PROTOCOL_GUID \
00024   { \
00025     0xBB25CF6F, 0xF1D4, 0x11D2, {0x9A, 0x0C, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0xFD } \
00026   }
00027 
00028 ///
00029 /// Protocol GUID defined in EFI1.1.
00030 ///
00031 #define SERIAL_IO_PROTOCOL  EFI_SERIAL_IO_PROTOCOL_GUID
00032 
00033 typedef struct _EFI_SERIAL_IO_PROTOCOL EFI_SERIAL_IO_PROTOCOL;
00034 
00035 
00036 ///
00037 /// Backward-compatible with EFI1.1.
00038 ///
00039 typedef EFI_SERIAL_IO_PROTOCOL  SERIAL_IO_INTERFACE;
00040 
00041 ///
00042 /// Parity type that is computed or checked as each character is transmitted or received. If the
00043 /// device does not support parity, the value is the default parity value.
00044 ///
00045 typedef enum {
00046   DefaultParity,
00047   NoParity,
00048   EvenParity,
00049   OddParity,
00050   MarkParity,
00051   SpaceParity
00052 } EFI_PARITY_TYPE;
00053 
00054 ///
00055 /// Stop bits type
00056 ///
00057 typedef enum {
00058   DefaultStopBits,
00059   OneStopBit,
00060   OneFiveStopBits,
00061   TwoStopBits
00062 } EFI_STOP_BITS_TYPE;
00063 
00064 //
00065 // define for Control bits, grouped by read only, write only, and read write
00066 //
00067 //
00068 // Read Only
00069 //
00070 #define EFI_SERIAL_CLEAR_TO_SEND        0x00000010
00071 #define EFI_SERIAL_DATA_SET_READY       0x00000020
00072 #define EFI_SERIAL_RING_INDICATE        0x00000040
00073 #define EFI_SERIAL_CARRIER_DETECT       0x00000080
00074 #define EFI_SERIAL_INPUT_BUFFER_EMPTY   0x00000100
00075 #define EFI_SERIAL_OUTPUT_BUFFER_EMPTY  0x00000200
00076 
00077 //
00078 // Write Only
00079 //
00080 #define EFI_SERIAL_REQUEST_TO_SEND      0x00000002
00081 #define EFI_SERIAL_DATA_TERMINAL_READY  0x00000001
00082 
00083 //
00084 // Read Write
00085 //
00086 #define EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     0x00001000
00087 #define EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     0x00002000
00088 #define EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE 0x00004000
00089 
00090 //
00091 // Serial IO Member Functions
00092 //
00093 /**
00094   Reset the serial device.
00095 
00096   @param  This              Protocol instance pointer.
00097 
00098   @retval EFI_SUCCESS       The device was reset.
00099   @retval EFI_DEVICE_ERROR  The serial device could not be reset.
00100 
00101 **/
00102 typedef
00103 EFI_STATUS
00104 (EFIAPI *EFI_SERIAL_RESET)(
00105   IN EFI_SERIAL_IO_PROTOCOL *This
00106   );
00107 
00108 /**
00109   Sets the baud rate, receive FIFO depth, transmit/receice time out, parity,
00110   data bits, and stop bits on a serial device.
00111 
00112   @param  This             Protocol instance pointer.
00113   @param  BaudRate         The requested baud rate. A BaudRate value of 0 will use the
00114                            device's default interface speed.
00115   @param  ReveiveFifoDepth The requested depth of the FIFO on the receive side of the
00116                            serial interface. A ReceiveFifoDepth value of 0 will use
00117                            the device's default FIFO depth.
00118   @param  Timeout          The requested time out for a single character in microseconds.
00119                            This timeout applies to both the transmit and receive side of the
00120                            interface. A Timeout value of 0 will use the device's default time
00121                            out value.
00122   @param  Parity           The type of parity to use on this serial device. A Parity value of
00123                            DefaultParity will use the device's default parity value.
00124   @param  DataBits         The number of data bits to use on the serial device. A DataBits
00125                            vaule of 0 will use the device's default data bit setting.
00126   @param  StopBits         The number of stop bits to use on this serial device. A StopBits
00127                            value of DefaultStopBits will use the device's default number of
00128                            stop bits.
00129 
00130   @retval EFI_SUCCESS      The device was reset.
00131   @retval EFI_DEVICE_ERROR The serial device could not be reset.
00132 
00133 **/
00134 typedef
00135 EFI_STATUS
00136 (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES)(
00137   IN EFI_SERIAL_IO_PROTOCOL         *This,
00138   IN UINT64                         BaudRate,
00139   IN UINT32                         ReceiveFifoDepth,
00140   IN UINT32                         Timeout,
00141   IN EFI_PARITY_TYPE                Parity,
00142   IN UINT8                          DataBits,
00143   IN EFI_STOP_BITS_TYPE             StopBits
00144   );
00145 
00146 /**
00147   Set the control bits on a serial device
00148 
00149   @param  This             Protocol instance pointer.
00150   @param  Control          Set the bits of Control that are settable.
00151 
00152   @retval EFI_SUCCESS      The new control bits were set on the serial device.
00153   @retval EFI_UNSUPPORTED  The serial device does not support this operation.
00154   @retval EFI_DEVICE_ERROR The serial device is not functioning correctly.
00155 
00156 **/
00157 typedef
00158 EFI_STATUS
00159 (EFIAPI *EFI_SERIAL_SET_CONTROL_BITS)(
00160   IN EFI_SERIAL_IO_PROTOCOL         *This,
00161   IN UINT32                         Control
00162   );
00163 
00164 /**
00165   Retrieves the status of thecontrol bits on a serial device
00166 
00167   @param  This              Protocol instance pointer.
00168   @param  Control           A pointer to return the current Control signals from the serial device.
00169 
00170   @retval EFI_SUCCESS       The control bits were read from the serial device.
00171   @retval EFI_DEVICE_ERROR  The serial device is not functioning correctly.
00172 
00173 **/
00174 typedef
00175 EFI_STATUS
00176 (EFIAPI *EFI_SERIAL_GET_CONTROL_BITS)(
00177   IN EFI_SERIAL_IO_PROTOCOL         *This,
00178   OUT UINT32                        *Control
00179   );
00180 
00181 /**
00182   Writes data to a serial device.
00183 
00184   @param  This              Protocol instance pointer.
00185   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
00186                             data actually written.
00187   @param  Buffer            The buffer of data to write
00188 
00189   @retval EFI_SUCCESS       The data was written.
00190   @retval EFI_DEVICE_ERROR  The device reported an error.
00191   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
00192 
00193 **/
00194 typedef
00195 EFI_STATUS
00196 (EFIAPI *EFI_SERIAL_WRITE)(
00197   IN EFI_SERIAL_IO_PROTOCOL         *This,
00198   IN OUT UINTN                      *BufferSize,
00199   IN VOID                           *Buffer
00200   );
00201 
00202 /**
00203   Writes data to a serial device.
00204 
00205   @param  This              Protocol instance pointer.
00206   @param  BufferSize        On input, the size of the Buffer. On output, the amount of
00207                             data returned in Buffer.
00208   @param  Buffer            The buffer to return the data into.
00209 
00210   @retval EFI_SUCCESS       The data was read.
00211   @retval EFI_DEVICE_ERROR  The device reported an error.
00212   @retval EFI_TIMEOUT       The data write was stopped due to a timeout.
00213 
00214 **/
00215 typedef
00216 EFI_STATUS
00217 (EFIAPI *EFI_SERIAL_READ)(
00218   IN EFI_SERIAL_IO_PROTOCOL         *This,
00219   IN OUT UINTN                      *BufferSize,
00220   OUT VOID                          *Buffer
00221   );
00222 
00223 /**
00224   @par Data Structure Description:
00225   The data values in SERIAL_IO_MODE are read-only and are updated by the code
00226   that produces the SERIAL_IO_PROTOCOL member functions.
00227 
00228   @param ControlMask
00229   A mask for the Control bits that the device supports. The device
00230   must always support the Input Buffer Empty control bit.
00231 
00232   @param TimeOut
00233   If applicable, the number of microseconds to wait before timing out
00234   a Read or Write operation.
00235 
00236   @param BaudRate
00237   If applicable, the current baud rate setting of the device; otherwise,
00238   baud rate has the value of zero to indicate that device runs at the
00239   device's designed speed.
00240 
00241   @param ReceiveFifoDepth
00242   The number of characters the device will buffer on input
00243 
00244   @param DataBits
00245   The number of characters the device will buffer on input
00246 
00247   @param Parity
00248   If applicable, this is the EFI_PARITY_TYPE that is computed or
00249   checked as each character is transmitted or reveived. If the device
00250   does not support parity the value is the default parity value.
00251 
00252   @param StopBits
00253   If applicable, the EFI_STOP_BITS_TYPE number of stop bits per
00254   character. If the device does not support stop bits the value is
00255   the default stop bit values.
00256 
00257 **/
00258 typedef struct {
00259   UINT32  ControlMask;
00260 
00261   //
00262   // current Attributes
00263   //
00264   UINT32  Timeout;
00265   UINT64  BaudRate;
00266   UINT32  ReceiveFifoDepth;
00267   UINT32  DataBits;
00268   UINT32  Parity;
00269   UINT32  StopBits;
00270 } EFI_SERIAL_IO_MODE;
00271 
00272 #define EFI_SERIAL_IO_PROTOCOL_REVISION    0x00010000
00273 #define SERIAL_IO_INTERFACE_REVISION  EFI_SERIAL_IO_PROTOCOL_REVISION
00274 
00275 ///
00276 /// The Serial I/O protocol is used to communicate with UART-style serial devices.
00277 /// These can be standard UART serial ports in PC-AT systems, serial ports attached
00278 /// to a USB interface, or potentially any character-based I/O device.
00279 ///
00280 struct _EFI_SERIAL_IO_PROTOCOL {
00281   ///
00282   /// The revision to which the EFI_SERIAL_IO_PROTOCOL adheres. All future revisions
00283   /// must be backwards compatible. If a future version is not backwards compatible,
00284   /// it is not the same GUID.
00285   ///
00286   UINT32                      Revision;
00287   EFI_SERIAL_RESET            Reset;
00288   EFI_SERIAL_SET_ATTRIBUTES   SetAttributes;
00289   EFI_SERIAL_SET_CONTROL_BITS SetControl;
00290   EFI_SERIAL_GET_CONTROL_BITS GetControl;
00291   EFI_SERIAL_WRITE            Write;
00292   EFI_SERIAL_READ             Read;
00293   ///
00294   /// Pointer to SERIAL_IO_MODE data.
00295   ///
00296   EFI_SERIAL_IO_MODE          *Mode;
00297 };
00298 
00299 extern EFI_GUID gEfiSerialIoProtocolGuid;
00300 
00301 #endif