MdeModulePkg/Bus/Pci/PciSioSerialDxe/Serial.h

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