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