MdeModulePkg/Bus/Pci/PciSioSerialDxe/Serial.h

   1 /** @file
   2   Header file for PciSioSerial Driver
   3
   4 Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _SERIAL_H_
  16 #define _SERIAL_H_
  17
  18
  19 #include <Uefi.h>
  20
  21 #include <IndustryStandard/Pci.h>
  22
  23 #include <Protocol/SuperIo.h>
  24 #include <Protocol/PciIo.h>
  25 #include <Protocol/SerialIo.h>
  26 #include <Protocol/DevicePath.h>
  27
  28 #include <Library/DebugLib.h>
  29 #include <Library/UefiDriverEntryPoint.h>
  30 #include <Library/UefiLib.h>
  31 #include <Library/DevicePathLib.h>
  32 #include <Library/BaseMemoryLib.h>
  33 #include <Library/MemoryAllocationLib.h>
  34 #include <Library/UefiBootServicesTableLib.h>
  35 #include <Library/ReportStatusCodeLib.h>
  36 #include <Library/PcdLib.h>
  37 #include <Library/IoLib.h>
  38 #include <Library/PrintLib.h>
  39
  40 //
  41 // Driver Binding Externs
  42 //
  43 extern EFI_DRIVER_BINDING_PROTOCOL  gSerialControllerDriver;
  44 extern EFI_COMPONENT_NAME_PROTOCOL  gPciSioSerialComponentName;
  45 extern EFI_COMPONENT_NAME2_PROTOCOL gPciSioSerialComponentName2;
  46
  47 #define SIO_SERIAL_PORT_NAME L"SIO Serial Port #%d"
  48 #define PCI_SERIAL_PORT_NAME L"PCI Serial Port #%d"
  49 #define SERIAL_PORT_NAME_LEN (sizeof (SIO_SERIAL_PORT_NAME) / sizeof (CHAR16) + MAXIMUM_VALUE_CHARACTERS)
  50
  51 //
  52 // Internal Data Structures
  53 //
  54 #define TIMEOUT_STALL_INTERVAL  10
  55
  56 #pragma pack(1)
  57 ///
  58 /// PcdPciSerialParameters contains zero or more instances of the below structure.
  59 /// If a PCI device contains multiple UARTs, PcdPciSerialParameters needs to contain
  60 /// two instances of the below structure, with the VendorId and DeviceId equals to the
  61 /// device ID and vendor ID of the device. If the PCI device uses the first two BARs
  62 /// to support multiple UARTs, BarIndex of first instance equals to 0 and BarIndex of
  63 /// second one equals to 1; if the PCI device uses the first BAR to support multiple
  64 /// UARTs, BarIndex of both instance equals to 0 and Offset of first instance equals
  65 /// to 0 while Offset of second one equals to some value bigger or equal to 8.
  66 /// For certain UART whose register needs to be accessed in DWORD aligned address,
  67 /// RegisterStride equals to 4.
  68 ///
  69 typedef struct {
  70   UINT16  VendorId;          ///< Vendor ID to match the PCI device.  The value 0xFFFF terminates the list of entries.
  71   UINT16  DeviceId;          ///< Device ID to match the PCI device
  72   UINT32  ClockRate;         ///< UART clock rate.  Set to 0 for default clock rate of 1843200 Hz
  73   UINT64  Offset;            ///< The byte offset into to the BAR
  74   UINT8   BarIndex;          ///< Which BAR to get the UART base address
  75   UINT8   RegisterStride;    ///< UART register stride in bytes.  Set to 0 for default register stride of 1 byte.
  76   UINT16  ReceiveFifoDepth;  ///< UART receive FIFO depth in bytes. Set to 0 for a default FIFO depth of 16 bytes.
  77   UINT16  TransmitFifoDepth; ///< UART transmit FIFO depth in bytes. Set to 0 for a default FIFO depth of 16 bytes.
  78   UINT8   Reserved[2];
  79 } PCI_SERIAL_PARAMETER;
  80 #pragma pack()
  81
  82 #define SERIAL_MAX_FIFO_SIZE 17       ///< Actual FIFO size is 16. FIFO based on circular wastes one unit.
  83 typedef struct {
  84   UINT16  Head;                       ///< Head pointer of the FIFO. Empty when (Head == Tail).
  85   UINT16  Tail;                       ///< Tail pointer of the FIFO. Full when ((Tail + 1) % SERIAL_MAX_FIFO_SIZE == Head).
  86   UINT8   Data[SERIAL_MAX_FIFO_SIZE]; ///< Store the FIFO data.
  87 } SERIAL_DEV_FIFO;
  88
  89 typedef union {
  90   EFI_PCI_IO_PROTOCOL       *PciIo;
  91   EFI_SIO_PROTOCOL          *Sio;
  92 } PARENT_IO_PROTOCOL_PTR;
  93
  94 typedef struct {
  95   EFI_PCI_IO_PROTOCOL      *PciIo;        // Pointer to parent PciIo instance.
  96   UINTN                    ChildCount;    // Count of child SerialIo instance.
  97   UINT64                   PciAttributes; // Original PCI attributes.
  98 } PCI_DEVICE_INFO;
  99
 100 typedef struct {
 101   UINT32                   Signature;
 102   EFI_HANDLE               Handle;
 103   EFI_SERIAL_IO_PROTOCOL   SerialIo;
 104   EFI_SERIAL_IO_MODE       SerialMode;
 105   EFI_DEVICE_PATH_PROTOCOL *DevicePath;
 106
 107   EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;
 108   UART_DEVICE_PATH         UartDevicePath;
 109
 110   EFI_PHYSICAL_ADDRESS     BaseAddress;       ///< UART base address
 111   BOOLEAN                  MmioAccess;        ///< TRUE for MMIO, FALSE for IO
 112   UINT8                    RegisterStride;    ///< UART Register Stride
 113   UINT32                   ClockRate;         ///< UART clock rate
 114
 115   UINT16                   ReceiveFifoDepth;  ///< UART receive FIFO depth in bytes.
 116   SERIAL_DEV_FIFO          Receive;           ///< The FIFO used to store received data
 117
 118   UINT16                   TransmitFifoDepth; ///< UART transmit FIFO depth in bytes.
 119   SERIAL_DEV_FIFO          Transmit;          ///< The FIFO used to store to-transmit data
 120
 121   BOOLEAN                  SoftwareLoopbackEnable;
 122   BOOLEAN                  HardwareFlowControl;
 123   EFI_UNICODE_STRING_TABLE *ControllerNameTable;
 124   BOOLEAN                  ContainsControllerNode; ///< TRUE if the device produced contains Controller node
 125   UINT32                   Instance;
 126   PCI_DEVICE_INFO          *PciDeviceInfo;
 127 } SERIAL_DEV;
 128
 129 #define SERIAL_DEV_SIGNATURE    SIGNATURE_32 ('s', 'e', 'r', 'd')
 130 #define SERIAL_DEV_FROM_THIS(a) CR (a, SERIAL_DEV, SerialIo, SERIAL_DEV_SIGNATURE)
 131
 132 //
 133 // Serial Driver Defaults
 134 //
 135 #define SERIAL_PORT_DEFAULT_TIMEOUT             1000000
 136 #define SERIAL_PORT_SUPPORT_CONTROL_MASK        (EFI_SERIAL_CLEAR_TO_SEND                | \
 137                                                  EFI_SERIAL_DATA_SET_READY               | \
 138                                                  EFI_SERIAL_RING_INDICATE                | \
 139                                                  EFI_SERIAL_CARRIER_DETECT               | \
 140                                                  EFI_SERIAL_REQUEST_TO_SEND              | \
 141                                                  EFI_SERIAL_DATA_TERMINAL_READY          | \
 142                                                  EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE     | \
 143                                                  EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE     | \
 144                                                  EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE | \
 145                                                  EFI_SERIAL_OUTPUT_BUFFER_EMPTY          | \
 146                                                  EFI_SERIAL_INPUT_BUFFER_EMPTY)
 147
 148 #define SERIAL_PORT_MIN_TIMEOUT             1         // 1 uS
 149 #define SERIAL_PORT_MAX_TIMEOUT             100000000 // 100 seconds
 150 //
 151 // UART Registers
 152 //
 153 #define SERIAL_REGISTER_THR 0  ///< WO   Transmit Holding Register
 154 #define SERIAL_REGISTER_RBR 0  ///< RO   Receive Buffer Register
 155 #define SERIAL_REGISTER_DLL 0  ///< R/W  Divisor Latch LSB
 156 #define SERIAL_REGISTER_DLM 1  ///< R/W  Divisor Latch MSB
 157 #define SERIAL_REGISTER_IER 1  ///< R/W  Interrupt Enable Register
 158 #define SERIAL_REGISTER_IIR 2  ///< RO   Interrupt Identification Register
 159 #define SERIAL_REGISTER_FCR 2  ///< WO   FIFO Cotrol Register
 160 #define SERIAL_REGISTER_LCR 3  ///< R/W  Line Control Register
 161 #define SERIAL_REGISTER_MCR 4  ///< R/W  Modem Control Register
 162 #define SERIAL_REGISTER_LSR 5  ///< R/W  Line Status Register
 163 #define SERIAL_REGISTER_MSR 6  ///< R/W  Modem Status Register
 164 #define SERIAL_REGISTER_SCR 7  ///< R/W  Scratch Pad Register
 165 #pragma pack(1)
 166
 167 ///
 168 /// Interrupt Enable Register
 169 ///
 170 typedef union {
 171   struct {
 172     UINT8 Ravie : 1;   ///< Receiver Data Available Interrupt Enable
 173     UINT8 Theie : 1;   ///< Transmistter Holding Register Empty Interrupt Enable
 174     UINT8 Rie : 1;     ///< Receiver Interrupt Enable
 175     UINT8 Mie : 1;     ///< Modem Interrupt Enable
 176     UINT8 Reserved : 4;
 177   } Bits;
 178   UINT8 Data;
 179 } SERIAL_PORT_IER;
 180
 181 ///
 182 /// FIFO Control Register
 183 ///
 184 typedef union {
 185   struct {
 186     UINT8 TrFIFOE : 1;   ///< Transmit and Receive FIFO Enable
 187     UINT8 ResetRF : 1;   ///< Reset Reciever FIFO
 188     UINT8 ResetTF : 1;   ///< Reset Transmistter FIFO
 189     UINT8 Dms : 1;       ///< DMA Mode Select
 190     UINT8 Reserved : 1;
 191     UINT8 TrFIFO64 : 1;  ///< Enable 64 byte FIFO
 192     UINT8 Rtb : 2;       ///< Receive Trigger Bits
 193   } Bits;
 194   UINT8 Data;
 195 } SERIAL_PORT_FCR;
 196
 197 ///
 198 /// Line Control Register
 199 ///
 200 typedef union {
 201   struct {
 202     UINT8 SerialDB : 2;   ///< Number of Serial Data Bits
 203     UINT8 StopB : 1;      ///< Number of Stop Bits
 204     UINT8 ParEn : 1;      ///< Parity Enable
 205     UINT8 EvenPar : 1;    ///< Even Parity Select
 206     UINT8 SticPar : 1;    ///< Sticky Parity
 207     UINT8 BrCon : 1;      ///< Break Control
 208     UINT8 DLab : 1;       ///< Divisor Latch Access Bit
 209   } Bits;
 210   UINT8 Data;
 211 } SERIAL_PORT_LCR;
 212
 213 ///
 214 /// Modem Control Register
 215 ///
 216 typedef union {
 217   struct {
 218     UINT8 DtrC : 1;  ///< Data Terminal Ready Control
 219     UINT8 Rts : 1;   ///< Request To Send Control
 220     UINT8 Out1 : 1;  ///< Output1
 221     UINT8 Out2 : 1;  ///< Output2, used to disable interrupt
 222     UINT8 Lme : 1;   ///< Loopback Mode Enable
 223     UINT8 Reserved : 3;
 224   } Bits;
 225   UINT8 Data;
 226 } SERIAL_PORT_MCR;
 227
 228 ///
 229 /// Line Status Register
 230 ///
 231 typedef union {
 232   struct {
 233     UINT8 Dr : 1;     ///< Receiver Data Ready Status
 234     UINT8 Oe : 1;     ///< Overrun Error Status
 235     UINT8 Pe : 1;     ///< Parity Error Status
 236     UINT8 Fe : 1;     ///< Framing Error Status
 237     UINT8 Bi : 1;     ///< Break Interrupt Status
 238     UINT8 Thre : 1;   ///< Transmistter Holding Register Status
 239     UINT8 Temt : 1;   ///< Transmitter Empty Status
 240     UINT8 FIFOe : 1;  ///< FIFO Error Status
 241   } Bits;
 242   UINT8 Data;
 243 } SERIAL_PORT_LSR;
 244
 245 ///
 246 /// Modem Status Register
 247 ///
 248 typedef union {
 249   struct {
 250     UINT8 DeltaCTS : 1;         ///< Delta Clear To Send Status
 251     UINT8 DeltaDSR : 1;         ///< Delta Data Set Ready Status
 252     UINT8 TrailingEdgeRI : 1;   ///< Trailing Edge of Ring Indicator Status
 253     UINT8 DeltaDCD : 1;         ///< Delta Data Carrier Detect Status
 254     UINT8 Cts : 1;              ///< Clear To Send Status
 255     UINT8 Dsr : 1;              ///< Data Set Ready Status
 256     UINT8 Ri : 1;               ///< Ring Indicator Status
 257     UINT8 Dcd : 1;              ///< Data Carrier Detect Status
 258   } Bits;
 259   UINT8 Data;
 260 } SERIAL_PORT_MSR;
 261
 262 #pragma pack()
 263 //
 264 // Define serial register I/O macros
 265 //
 266 #define READ_RBR(S)     SerialReadRegister (S, SERIAL_REGISTER_RBR)
 267 #define READ_DLL(S)     SerialReadRegister (S, SERIAL_REGISTER_DLL)
 268 #define READ_DLM(S)     SerialReadRegister (S, SERIAL_REGISTER_DLM)
 269 #define READ_IER(S)     SerialReadRegister (S, SERIAL_REGISTER_IER)
 270 #define READ_IIR(S)     SerialReadRegister (S, SERIAL_REGISTER_IIR)
 271 #define READ_LCR(S)     SerialReadRegister (S, SERIAL_REGISTER_LCR)
 272 #define READ_MCR(S)     SerialReadRegister (S, SERIAL_REGISTER_MCR)
 273 #define READ_LSR(S)     SerialReadRegister (S, SERIAL_REGISTER_LSR)
 274 #define READ_MSR(S)     SerialReadRegister (S, SERIAL_REGISTER_MSR)
 275 #define READ_SCR(S)     SerialReadRegister (S, SERIAL_REGISTER_SCR)
 276
 277 #define WRITE_THR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_THR, D)
 278 #define WRITE_DLL(S, D) SerialWriteRegister (S, SERIAL_REGISTER_DLL, D)
 279 #define WRITE_DLM(S, D) SerialWriteRegister (S, SERIAL_REGISTER_DLM, D)
 280 #define WRITE_IER(S, D) SerialWriteRegister (S, SERIAL_REGISTER_IER, D)
 281 #define WRITE_FCR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_FCR, D)
 282 #define WRITE_LCR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_LCR, D)
 283 #define WRITE_MCR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_MCR, D)
 284 #define WRITE_LSR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_LSR, D)
 285 #define WRITE_MSR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_MSR, D)
 286 #define WRITE_SCR(S, D) SerialWriteRegister (S, SERIAL_REGISTER_SCR, D)
 287
 288 //
 289 // Prototypes
 290 // Driver model protocol interface
 291 //
 292 /**
 293   Check to see if this driver supports the given controller
 294
 295   @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 296   @param  Controller           The handle of the controller to test.
 297   @param  RemainingDevicePath  A pointer to the remaining portion of a device path.
 298
 299   @return EFI_SUCCESS          This driver can support the given controller
 300
 301 **/
 302 EFI_STATUS
 303 EFIAPI
 304 SerialControllerDriverSupported (
 305   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 306   IN EFI_HANDLE                     Controller,
 307   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 308   );
 309
 310 /**
 311   Start to management the controller passed in
 312
 313   @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 314   @param  Controller           The handle of the controller to test.
 315   @param  RemainingDevicePath  A pointer to the remaining portion of a device path.
 316
 317   @return EFI_SUCCESS          Driver is started successfully
 318 **/
 319 EFI_STATUS
 320 EFIAPI
 321 SerialControllerDriverStart (
 322   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 323   IN EFI_HANDLE                     Controller,
 324   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 325   );
 326
 327 /**
 328   Disconnect this driver with the controller, uninstall related protocol instance
 329
 330   @param  This                  A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 331   @param  Controller            The handle of the controller to test.
 332   @param  NumberOfChildren      Number of child device.
 333   @param  ChildHandleBuffer     A pointer to the remaining portion of a device path.
 334
 335   @retval EFI_SUCCESS           Operation successfully
 336   @retval EFI_DEVICE_ERROR      Cannot stop the driver successfully
 337
 338 **/
 339 EFI_STATUS
 340 EFIAPI
 341 SerialControllerDriverStop (
 342   IN  EFI_DRIVER_BINDING_PROTOCOL   *This,
 343   IN  EFI_HANDLE                    Controller,
 344   IN  UINTN                         NumberOfChildren,
 345   IN  EFI_HANDLE                    *ChildHandleBuffer
 346   );
 347
 348 //
 349 // Serial I/O Protocol Interface
 350 //
 351 /**
 352   Reset serial device.
 353
 354   @param This               Pointer to EFI_SERIAL_IO_PROTOCOL
 355
 356   @retval EFI_SUCCESS        Reset successfully
 357   @retval EFI_DEVICE_ERROR   Failed to reset
 358
 359 **/
 360 EFI_STATUS
 361 EFIAPI
 362 SerialReset (
 363   IN EFI_SERIAL_IO_PROTOCOL         *This
 364   );
 365
 366 /**
 367   Set new attributes to a serial device.
 368
 369   @param This                     Pointer to EFI_SERIAL_IO_PROTOCOL
 370   @param  BaudRate                 The baudrate of the serial device
 371   @param  ReceiveFifoDepth         The depth of receive FIFO buffer
 372   @param  Timeout                  The request timeout for a single char
 373   @param  Parity                   The type of parity used in serial device
 374   @param  DataBits                 Number of databits used in serial device
 375   @param  StopBits                 Number of stopbits used in serial device
 376
 377   @retval  EFI_SUCCESS              The new attributes were set
 378   @retval  EFI_INVALID_PARAMETERS   One or more attributes have an unsupported value
 379   @retval  EFI_UNSUPPORTED          Data Bits can not set to 5 or 6
 380   @retval  EFI_DEVICE_ERROR         The serial device is not functioning correctly (no return)
 381
 382 **/
 383 EFI_STATUS
 384 EFIAPI
 385 SerialSetAttributes (
 386   IN EFI_SERIAL_IO_PROTOCOL         *This,
 387   IN UINT64                         BaudRate,
 388   IN UINT32                         ReceiveFifoDepth,
 389   IN UINT32                         Timeout,
 390   IN EFI_PARITY_TYPE                Parity,
 391   IN UINT8                          DataBits,
 392   IN EFI_STOP_BITS_TYPE             StopBits
 393   );
 394
 395 /**
 396   Set Control Bits.
 397
 398   @param This              Pointer to EFI_SERIAL_IO_PROTOCOL
 399   @param Control           Control bits that can be settable
 400
 401   @retval EFI_SUCCESS       New Control bits were set successfully
 402   @retval EFI_UNSUPPORTED   The Control bits wanted to set are not supported
 403
 404 **/
 405 EFI_STATUS
 406 EFIAPI
 407 SerialSetControl (
 408   IN EFI_SERIAL_IO_PROTOCOL         *This,
 409   IN UINT32                         Control
 410   );
 411
 412 /**
 413   Get ControlBits.
 414
 415   @param This          Pointer to EFI_SERIAL_IO_PROTOCOL
 416   @param Control       Control signals of the serial device
 417
 418   @retval EFI_SUCCESS   Get Control signals successfully
 419
 420 **/
 421 EFI_STATUS
 422 EFIAPI
 423 SerialGetControl (
 424   IN EFI_SERIAL_IO_PROTOCOL         *This,
 425   OUT UINT32                        *Control
 426   );
 427
 428 /**
 429   Write the specified number of bytes to serial device.
 430
 431   @param This                Pointer to EFI_SERIAL_IO_PROTOCOL
 432   @param  BufferSize         On input the size of Buffer, on output the amount of
 433                              data actually written
 434   @param  Buffer             The buffer of data to write
 435
 436   @retval EFI_SUCCESS        The data were written successfully
 437   @retval EFI_DEVICE_ERROR   The device reported an error
 438   @retval EFI_TIMEOUT        The write operation was stopped due to timeout
 439
 440 **/
 441 EFI_STATUS
 442 EFIAPI
 443 SerialWrite (
 444   IN EFI_SERIAL_IO_PROTOCOL         *This,
 445   IN OUT UINTN                      *BufferSize,
 446   IN VOID                           *Buffer
 447   );
 448
 449 /**
 450   Read the specified number of bytes from serial device.
 451
 452   @param This               Pointer to EFI_SERIAL_IO_PROTOCOL
 453   @param BufferSize         On input the size of Buffer, on output the amount of
 454                             data returned in buffer
 455   @param Buffer             The buffer to return the data into
 456
 457   @retval EFI_SUCCESS        The data were read successfully
 458   @retval EFI_DEVICE_ERROR   The device reported an error
 459   @retval EFI_TIMEOUT        The read operation was stopped due to timeout
 460
 461 **/
 462 EFI_STATUS
 463 EFIAPI
 464 SerialRead (
 465   IN EFI_SERIAL_IO_PROTOCOL         *This,
 466   IN OUT UINTN                      *BufferSize,
 467   OUT VOID                          *Buffer
 468   );
 469
 470 //
 471 // Internal Functions
 472 //
 473 /**
 474   Use scratchpad register to test if this serial port is present.
 475
 476   @param SerialDevice   Pointer to serial device structure
 477
 478   @return if this serial port is present
 479 **/
 480 BOOLEAN
 481 SerialPresent (
 482   IN SERIAL_DEV                     *SerialDevice
 483   );
 484
 485 /**
 486   Detect whether specific FIFO is full or not.
 487
 488   @param Fifo    A pointer to the Data Structure SERIAL_DEV_FIFO
 489
 490   @return whether specific FIFO is full or not
 491
 492 **/
 493 BOOLEAN
 494 SerialFifoFull (
 495   IN SERIAL_DEV_FIFO                *Fifo
 496   );
 497
 498 /**
 499   Detect whether specific FIFO is empty or not.
 500
 501   @param  Fifo    A pointer to the Data Structure SERIAL_DEV_FIFO
 502
 503   @return whether specific FIFO is empty or not
 504
 505 **/
 506 BOOLEAN
 507 SerialFifoEmpty (
 508   IN SERIAL_DEV_FIFO                *Fifo
 509   );
 510
 511 /**
 512   Add data to specific FIFO.
 513
 514   @param Fifo                  A pointer to the Data Structure SERIAL_DEV_FIFO
 515   @param Data                  the data added to FIFO
 516
 517   @retval EFI_SUCCESS           Add data to specific FIFO successfully
 518   @retval EFI_OUT_OF_RESOURCE   Failed to add data because FIFO is already full
 519
 520 **/
 521 EFI_STATUS
 522 SerialFifoAdd (
 523   IN SERIAL_DEV_FIFO                *Fifo,
 524   IN UINT8                          Data
 525   );
 526
 527 /**
 528   Remove data from specific FIFO.
 529
 530   @param Fifo                  A pointer to the Data Structure SERIAL_DEV_FIFO
 531   @param Data                  the data removed from FIFO
 532
 533   @retval EFI_SUCCESS           Remove data from specific FIFO successfully
 534   @retval EFI_OUT_OF_RESOURCE   Failed to remove data because FIFO is empty
 535
 536 **/
 537 EFI_STATUS
 538 SerialFifoRemove (
 539   IN  SERIAL_DEV_FIFO               *Fifo,
 540   OUT UINT8                         *Data
 541   );
 542
 543 /**
 544   Reads and writes all avaliable data.
 545
 546   @param SerialDevice           The device to flush
 547
 548   @retval EFI_SUCCESS           Data was read/written successfully.
 549   @retval EFI_OUT_OF_RESOURCE   Failed because software receive FIFO is full.  Note, when
 550                                 this happens, pending writes are not done.
 551
 552 **/
 553 EFI_STATUS
 554 SerialReceiveTransmit (
 555   IN SERIAL_DEV                     *SerialDevice
 556   );
 557
 558 /**
 559   Read serial port.
 560
 561   @param SerialDev     Pointer to serial device
 562   @param Offset        Offset in register group
 563
 564   @return Data read from serial port
 565 **/
 566 UINT8
 567 SerialReadRegister (
 568   IN SERIAL_DEV                            *SerialDev,
 569   IN UINT32                                Offset
 570   );
 571
 572 /**
 573   Write serial port.
 574
 575   @param  SerialDev     Pointer to serial device
 576   @param  Offset        Offset in register group
 577   @param  Data          data which is to be written to some serial port register
 578 **/
 579 VOID
 580 SerialWriteRegister (
 581   IN SERIAL_DEV                            *SerialDev,
 582   IN UINT32                                Offset,
 583   IN UINT8                                 Data
 584   );
 585
 586
 587 //
 588 // EFI Component Name Functions
 589 //
 590 /**
 591   Retrieves a Unicode string that is the user readable name of the driver.
 592
 593   This function retrieves the user readable name of a driver in the form of a
 594   Unicode string. If the driver specified by This has a user readable name in
 595   the language specified by Language, then a pointer to the driver name is
 596   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 597   by This does not support the language specified by Language,
 598   then EFI_UNSUPPORTED is returned.
 599
 600   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 601                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 602
 603   @param  Language[in]          A pointer to a Null-terminated ASCII string
 604                                 array indicating the language. This is the
 605                                 language of the driver name that the caller is
 606                                 requesting, and it must match one of the
 607                                 languages specified in SupportedLanguages. The
 608                                 number of languages supported by a driver is up
 609                                 to the driver writer. Language is specified
 610                                 in RFC 4646 or ISO 639-2 language code format.
 611
 612   @param  DriverName[out]       A pointer to the Unicode string to return.
 613                                 This Unicode string is the name of the
 614                                 driver specified by This in the language
 615                                 specified by Language.
 616
 617   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 618                                 This and the language specified by Language was
 619                                 returned in DriverName.
 620
 621   @retval EFI_INVALID_PARAMETER Language is NULL.
 622
 623   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 624
 625   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 626                                 the language specified by Language.
 627
 628 **/
 629 EFI_STATUS
 630 EFIAPI
 631 SerialComponentNameGetDriverName (
 632   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 633   IN  CHAR8                        *Language,
 634   OUT CHAR16                       **DriverName
 635   );
 636
 637
 638 /**
 639   Retrieves a Unicode string that is the user readable name of the controller
 640   that is being managed by a driver.
 641
 642   This function retrieves the user readable name of the controller specified by
 643   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 644   driver specified by This has a user readable name in the language specified by
 645   Language, then a pointer to the controller name is returned in ControllerName,
 646   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 647   managing the controller specified by ControllerHandle and ChildHandle,
 648   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 649   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 650
 651   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 652                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 653
 654   @param  ControllerHandle[in]  The handle of a controller that the driver
 655                                 specified by This is managing.  This handle
 656                                 specifies the controller whose name is to be
 657                                 returned.
 658
 659   @param  ChildHandle[in]       The handle of the child controller to retrieve
 660                                 the name of.  This is an optional parameter that
 661                                 may be NULL.  It will be NULL for device
 662                                 drivers.  It will also be NULL for a bus drivers
 663                                 that wish to retrieve the name of the bus
 664                                 controller.  It will not be NULL for a bus
 665                                 driver that wishes to retrieve the name of a
 666                                 child controller.
 667
 668   @param  Language[in]          A pointer to a Null-terminated ASCII string
 669                                 array indicating the language.  This is the
 670                                 language of the driver name that the caller is
 671                                 requesting, and it must match one of the
 672                                 languages specified in SupportedLanguages. The
 673                                 number of languages supported by a driver is up
 674                                 to the driver writer. Language is specified in
 675                                 RFC 4646 or ISO 639-2 language code format.
 676
 677   @param  ControllerName[out]   A pointer to the Unicode string to return.
 678                                 This Unicode string is the name of the
 679                                 controller specified by ControllerHandle and
 680                                 ChildHandle in the language specified by
 681                                 Language from the point of view of the driver
 682                                 specified by This.
 683
 684   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 685                                 the language specified by Language for the
 686                                 driver specified by This was returned in
 687                                 DriverName.
 688
 689   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 690
 691   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 692                                 EFI_HANDLE.
 693
 694   @retval EFI_INVALID_PARAMETER Language is NULL.
 695
 696   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 697
 698   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 699                                 managing the controller specified by
 700                                 ControllerHandle and ChildHandle.
 701
 702   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 703                                 the language specified by Language.
 704
 705 **/
 706 EFI_STATUS
 707 EFIAPI
 708 SerialComponentNameGetControllerName (
 709   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 710   IN  EFI_HANDLE                                      ControllerHandle,
 711   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 712   IN  CHAR8                                           *Language,
 713   OUT CHAR16                                          **ControllerName
 714   );
 715
 716 /**
 717   Add the component name for the serial io device
 718
 719   @param SerialDevice     A pointer to the SERIAL_DEV instance.
 720   @param Uid              Unique ID for the serial device.
 721 **/
 722 VOID
 723 AddName (
 724   IN  SERIAL_DEV                               *SerialDevice,
 725   IN  UINT32                                   Uid
 726   );
 727
 728 /**
 729   Checks whether the UART parameters are valid and computes the Divisor.
 730
 731   @param  ClockRate      The clock rate of the serial device used to verify
 732                          the BaudRate. Do not verify the BaudRate if it's 0.
 733   @param  BaudRate       The requested baudrate of the serial device.
 734   @param  DataBits       Number of databits used in serial device.
 735   @param  Parity         The type of parity used in serial device.
 736   @param  StopBits       Number of stopbits used in serial device.
 737   @param  Divisor        Return the divisor if ClockRate is not 0.
 738   @param  ActualBaudRate Return the actual supported baudrate without
 739                          exceeding BaudRate. NULL means baudrate degradation
 740                          is not allowed.
 741                          If the requested BaudRate is not supported, the routine
 742                          returns TRUE and the Actual Baud Rate when ActualBaudRate
 743                          is not NULL, returns FALSE when ActualBaudRate is NULL.
 744
 745   @retval TRUE   The UART parameters are valid.
 746   @retval FALSE  The UART parameters are not valid.
 747 **/
 748 BOOLEAN
 749 VerifyUartParameters (
 750   IN     UINT32                  ClockRate,
 751   IN     UINT64                  BaudRate,
 752   IN     UINT8                   DataBits,
 753   IN     EFI_PARITY_TYPE         Parity,
 754   IN     EFI_STOP_BITS_TYPE      StopBits,
 755      OUT UINT64                  *Divisor,
 756      OUT UINT64                  *ActualBaudRate
 757   );
 758
 759 /**
 760   Skip the optional Controller device path node and return the
 761   pointer to the next device path node.
 762
 763   @param DevicePath             Pointer to the device path.
 764   @param ContainsControllerNode Returns TRUE if the Controller device path exists.
 765   @param ControllerNumber       Returns the Controller Number if Controller device path exists.
 766
 767   @return     Pointer to the next device path node.
 768 **/
 769 UART_DEVICE_PATH *
 770 SkipControllerDevicePathNode (
 771   EFI_DEVICE_PATH_PROTOCOL          *DevicePath,
 772   BOOLEAN                           *ContainsControllerNode,
 773   UINT32                            *ControllerNumber
 774   );
 775
 776 /**
 777   Check the device path node whether it's the Flow Control node or not.
 778
 779   @param[in] FlowControl    The device path node to be checked.
 780
 781   @retval TRUE              It's the Flow Control node.
 782   @retval FALSE             It's not.
 783
 784 **/
 785 BOOLEAN
 786 IsUartFlowControlDevicePathNode (
 787   IN UART_FLOW_CONTROL_DEVICE_PATH *FlowControl
 788   );
 789 #endif