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 784