ArmPlatformPkg/Library/PL011UartLib/PL011UartLib.c

   1 /** @file
   2   Serial I/O Port library functions with no library constructor/destructor
   3
   4   Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>
   5   Copyright (c) 2011 - 2020, Arm Limited. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #include <Uefi.h>
  12
  13 #include <Library/DebugLib.h>
  14 #include <Library/IoLib.h>
  15 #include <Library/PcdLib.h>
  16
  17 #include <Protocol/SerialIo.h>
  18
  19 #include "PL011Uart.h"
  20
  21 #define FRACTION_PART_SIZE_IN_BITS  6
  22 #define FRACTION_PART_MASK          ((1 << FRACTION_PART_SIZE_IN_BITS) - 1)
  23
  24 //
  25 // EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE is the only
  26 // control bit that is not supported.
  27 //
  28 STATIC CONST UINT32  mInvalidControlBits = EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE;
  29
  30 /**
  31
  32   Initialise the serial port to the specified settings.
  33   The serial port is re-configured only if the specified settings
  34   are different from the current settings.
  35   All unspecified settings will be set to the default values.
  36
  37   @param  UartBase                The base address of the serial device.
  38   @param  UartClkInHz             The clock in Hz for the serial device.
  39                                   Ignored if the PCD PL011UartInteger is not 0
  40   @param  BaudRate                The baud rate of the serial device. If the
  41                                   baud rate is not supported, the speed will be
  42                                   reduced to the nearest supported one and the
  43                                   variable's value will be updated accordingly.
  44   @param  ReceiveFifoDepth        The number of characters the device will
  45                                   buffer on input.  Value of 0 will use the
  46                                   device's default FIFO depth.
  47   @param  Parity                  If applicable, this is the EFI_PARITY_TYPE
  48                                   that is computed or checked as each character
  49                                   is transmitted or received. If the device
  50                                   does not support parity, the value is the
  51                                   default parity value.
  52   @param  DataBits                The number of data bits in each character.
  53   @param  StopBits                If applicable, the EFI_STOP_BITS_TYPE number
  54                                   of stop bits per character.
  55                                   If the device does not support stop bits, the
  56                                   value is the default stop bit value.
  57
  58   @retval RETURN_SUCCESS            All attributes were set correctly on the
  59                                     serial device.
  60   @retval RETURN_INVALID_PARAMETER  One or more of the attributes has an
  61                                     unsupported value.
  62
  63 **/
  64 RETURN_STATUS
  65 EFIAPI
  66 PL011UartInitializePort (
  67   IN     UINTN               UartBase,
  68   IN     UINT32              UartClkInHz,
  69   IN OUT UINT64              *BaudRate,
  70   IN OUT UINT32              *ReceiveFifoDepth,
  71   IN OUT EFI_PARITY_TYPE     *Parity,
  72   IN OUT UINT8               *DataBits,
  73   IN OUT EFI_STOP_BITS_TYPE  *StopBits
  74   )
  75 {
  76   UINT32  LineControl;
  77   UINT32  Divisor;
  78   UINT32  Integer;
  79   UINT32  Fractional;
  80   UINT32  HardwareFifoDepth;
  81   UINT32  UartPid2;
  82
  83   HardwareFifoDepth = FixedPcdGet16 (PcdUartDefaultReceiveFifoDepth);
  84   if (HardwareFifoDepth == 0) {
  85     UartPid2          = MmioRead32 (UartBase + UARTPID2);
  86     HardwareFifoDepth = (PL011_UARTPID2_VER (UartPid2) > PL011_VER_R1P4) ? 32 : 16;
  87   }
  88
  89   // The PL011 supports a buffer of 1, 16 or 32 chars. Therefore we can accept
  90   // 1 char buffer as the minimum FIFO size. Because everything can be rounded
  91   // down, there is no maximum FIFO size.
  92   if ((*ReceiveFifoDepth == 0) || (*ReceiveFifoDepth >= HardwareFifoDepth)) {
  93     // Enable FIFO
  94     LineControl       = PL011_UARTLCR_H_FEN;
  95     *ReceiveFifoDepth = HardwareFifoDepth;
  96   } else {
  97     // Disable FIFO
  98     LineControl = 0;
  99     // Nothing else to do. 1 byte FIFO is default.
 100     *ReceiveFifoDepth = 1;
 101   }
 102
 103   //
 104   // Parity
 105   //
 106   switch (*Parity) {
 107     case DefaultParity:
 108       *Parity = NoParity;
 109     case NoParity:
 110       // Nothing to do. Parity is disabled by default.
 111       break;
 112     case EvenParity:
 113       LineControl |= (PL011_UARTLCR_H_PEN | PL011_UARTLCR_H_EPS);
 114       break;
 115     case OddParity:
 116       LineControl |= PL011_UARTLCR_H_PEN;
 117       break;
 118     case MarkParity:
 119       LineControl |= (PL011_UARTLCR_H_PEN \
 120                       | PL011_UARTLCR_H_SPS \
 121                       | PL011_UARTLCR_H_EPS);
 122       break;
 123     case SpaceParity:
 124       LineControl |= (PL011_UARTLCR_H_PEN | PL011_UARTLCR_H_SPS);
 125       break;
 126     default:
 127       return RETURN_INVALID_PARAMETER;
 128   }
 129
 130   //
 131   // Data Bits
 132   //
 133   switch (*DataBits) {
 134     case 0:
 135       *DataBits = 8;
 136     case 8:
 137       LineControl |= PL011_UARTLCR_H_WLEN_8;
 138       break;
 139     case 7:
 140       LineControl |= PL011_UARTLCR_H_WLEN_7;
 141       break;
 142     case 6:
 143       LineControl |= PL011_UARTLCR_H_WLEN_6;
 144       break;
 145     case 5:
 146       LineControl |= PL011_UARTLCR_H_WLEN_5;
 147       break;
 148     default:
 149       return RETURN_INVALID_PARAMETER;
 150   }
 151
 152   //
 153   // Stop Bits
 154   //
 155   switch (*StopBits) {
 156     case DefaultStopBits:
 157       *StopBits = OneStopBit;
 158     case OneStopBit:
 159       // Nothing to do. One stop bit is enabled by default.
 160       break;
 161     case TwoStopBits:
 162       LineControl |= PL011_UARTLCR_H_STP2;
 163       break;
 164     case OneFiveStopBits:
 165     // Only 1 or 2 stop bits are supported
 166     default:
 167       return RETURN_INVALID_PARAMETER;
 168   }
 169
 170   // Don't send the LineControl value to the PL011 yet,
 171   // wait until after the Baud Rate setting.
 172   // This ensures we do not mess up the UART settings halfway through
 173   // in the rare case when there is an error with the Baud Rate.
 174
 175   //
 176   // Baud Rate
 177   //
 178
 179   // If PL011 Integer value has been defined then always ignore the BAUD rate
 180   if (FixedPcdGet32 (PL011UartInteger) != 0) {
 181     Integer    = FixedPcdGet32 (PL011UartInteger);
 182     Fractional = FixedPcdGet32 (PL011UartFractional);
 183   } else {
 184     // If BAUD rate is zero then replace it with the system default value
 185     if (*BaudRate == 0) {
 186       *BaudRate = FixedPcdGet32 (PcdSerialBaudRate);
 187       if (*BaudRate == 0) {
 188         return RETURN_INVALID_PARAMETER;
 189       }
 190     }
 191
 192     if (0 == UartClkInHz) {
 193       return RETURN_INVALID_PARAMETER;
 194     }
 195
 196     Divisor    = (UartClkInHz * 4) / *BaudRate;
 197     Integer    = Divisor >> FRACTION_PART_SIZE_IN_BITS;
 198     Fractional = Divisor & FRACTION_PART_MASK;
 199   }
 200
 201   //
 202   // If PL011 is already initialized, check the current settings
 203   // and re-initialize only if the settings are different.
 204   //
 205   if (((MmioRead32 (UartBase + UARTCR) & PL011_UARTCR_UARTEN) != 0) &&
 206       (MmioRead32 (UartBase + UARTLCR_H) == LineControl) &&
 207       (MmioRead32 (UartBase + UARTIBRD) == Integer) &&
 208       (MmioRead32 (UartBase + UARTFBRD) == Fractional))
 209   {
 210     // Nothing to do - already initialized with correct attributes
 211     return RETURN_SUCCESS;
 212   }
 213
 214   // Wait for the end of transmission
 215   while ((MmioRead32 (UartBase + UARTFR) & PL011_UARTFR_TXFE) == 0) {
 216   }
 217
 218   // Disable UART: "The UARTLCR_H, UARTIBRD, and UARTFBRD registers must not be changed
 219   // when the UART is enabled"
 220   MmioWrite32 (UartBase + UARTCR, 0);
 221
 222   // Set Baud Rate Registers
 223   MmioWrite32 (UartBase + UARTIBRD, Integer);
 224   MmioWrite32 (UartBase + UARTFBRD, Fractional);
 225
 226   // No parity, 1 stop, no fifo, 8 data bits
 227   MmioWrite32 (UartBase + UARTLCR_H, LineControl);
 228
 229   // Clear any pending errors
 230   MmioWrite32 (UartBase + UARTECR, 0);
 231
 232   // Enable Tx, Rx, and UART overall
 233   MmioWrite32 (
 234     UartBase + UARTCR,
 235     PL011_UARTCR_RXE | PL011_UARTCR_TXE | PL011_UARTCR_UARTEN
 236     );
 237
 238   return RETURN_SUCCESS;
 239 }
 240
 241 /**
 242
 243   Assert or deassert the control signals on a serial port.
 244   The following control signals are set according their bit settings :
 245   . Request to Send
 246   . Data Terminal Ready
 247
 248   @param[in]  UartBase  UART registers base address
 249   @param[in]  Control   The following bits are taken into account :
 250                         . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the
 251                           "Request To Send" control signal if this bit is
 252                           equal to one/zero.
 253                         . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert
 254                           the "Data Terminal Ready" control signal if this
 255                           bit is equal to one/zero.
 256                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable
 257                           the hardware loopback if this bit is equal to
 258                           one/zero.
 259                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.
 260                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/
 261                           disable the hardware flow control based on CTS (Clear
 262                           To Send) and RTS (Ready To Send) control signals.
 263
 264   @retval  RETURN_SUCCESS      The new control bits were set on the device.
 265   @retval  RETURN_UNSUPPORTED  The device does not support this operation.
 266
 267 **/
 268 RETURN_STATUS
 269 EFIAPI
 270 PL011UartSetControl (
 271   IN UINTN   UartBase,
 272   IN UINT32  Control
 273   )
 274 {
 275   UINT32  Bits;
 276
 277   if ((Control & mInvalidControlBits) != 0) {
 278     return RETURN_UNSUPPORTED;
 279   }
 280
 281   Bits = MmioRead32 (UartBase + UARTCR);
 282
 283   if ((Control & EFI_SERIAL_REQUEST_TO_SEND) != 0) {
 284     Bits |= PL011_UARTCR_RTS;
 285   } else {
 286     Bits &= ~PL011_UARTCR_RTS;
 287   }
 288
 289   if ((Control & EFI_SERIAL_DATA_TERMINAL_READY) != 0) {
 290     Bits |= PL011_UARTCR_DTR;
 291   } else {
 292     Bits &= ~PL011_UARTCR_DTR;
 293   }
 294
 295   if ((Control & EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE) != 0) {
 296     Bits |= PL011_UARTCR_LBE;
 297   } else {
 298     Bits &= ~PL011_UARTCR_LBE;
 299   }
 300
 301   if ((Control & EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE) != 0) {
 302     Bits |= (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN);
 303   } else {
 304     Bits &= ~(PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN);
 305   }
 306
 307   MmioWrite32 (UartBase + UARTCR, Bits);
 308
 309   return RETURN_SUCCESS;
 310 }
 311
 312 /**
 313
 314   Retrieve the status of the control bits on a serial device.
 315
 316   @param[in]   UartBase  UART registers base address
 317   @param[out]  Control   Status of the control bits on a serial device :
 318
 319                          . EFI_SERIAL_DATA_CLEAR_TO_SEND,
 320                            EFI_SERIAL_DATA_SET_READY,
 321                            EFI_SERIAL_RING_INDICATE,
 322                            EFI_SERIAL_CARRIER_DETECT,
 323                            EFI_SERIAL_REQUEST_TO_SEND,
 324                            EFI_SERIAL_DATA_TERMINAL_READY
 325                            are all related to the DTE (Data Terminal Equipment)
 326                            and DCE (Data Communication Equipment) modes of
 327                            operation of the serial device.
 328                          . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the
 329                            receive buffer is empty, 0 otherwise.
 330                          . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the
 331                            transmit buffer is empty, 0 otherwise.
 332                          . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if
 333                            the hardware loopback is enabled (the output feeds the
 334                            receive buffer), 0 otherwise.
 335                          . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if
 336                            a loopback is accomplished by software, 0 otherwise.
 337                          . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to
 338                            one if the hardware flow control based on CTS (Clear
 339                            To Send) and RTS (Ready To Send) control signals is
 340                            enabled, 0 otherwise.
 341
 342   @retval RETURN_SUCCESS  The control bits were read from the serial device.
 343
 344 **/
 345 RETURN_STATUS
 346 EFIAPI
 347 PL011UartGetControl (
 348   IN UINTN    UartBase,
 349   OUT UINT32  *Control
 350   )
 351 {
 352   UINT32  FlagRegister;
 353   UINT32  ControlRegister;
 354
 355   FlagRegister    = MmioRead32 (UartBase + UARTFR);
 356   ControlRegister = MmioRead32 (UartBase + UARTCR);
 357
 358   *Control = 0;
 359
 360   if ((FlagRegister & PL011_UARTFR_CTS) == PL011_UARTFR_CTS) {
 361     *Control |= EFI_SERIAL_CLEAR_TO_SEND;
 362   }
 363
 364   if ((FlagRegister & PL011_UARTFR_DSR) == PL011_UARTFR_DSR) {
 365     *Control |= EFI_SERIAL_DATA_SET_READY;
 366   }
 367
 368   if ((FlagRegister & PL011_UARTFR_RI) == PL011_UARTFR_RI) {
 369     *Control |= EFI_SERIAL_RING_INDICATE;
 370   }
 371
 372   if ((FlagRegister & PL011_UARTFR_DCD) == PL011_UARTFR_DCD) {
 373     *Control |= EFI_SERIAL_CARRIER_DETECT;
 374   }
 375
 376   if ((ControlRegister & PL011_UARTCR_RTS) == PL011_UARTCR_RTS) {
 377     *Control |= EFI_SERIAL_REQUEST_TO_SEND;
 378   }
 379
 380   if ((ControlRegister & PL011_UARTCR_DTR) == PL011_UARTCR_DTR) {
 381     *Control |= EFI_SERIAL_DATA_TERMINAL_READY;
 382   }
 383
 384   if ((FlagRegister & PL011_UARTFR_RXFE) == PL011_UARTFR_RXFE) {
 385     *Control |= EFI_SERIAL_INPUT_BUFFER_EMPTY;
 386   }
 387
 388   if ((FlagRegister & PL011_UARTFR_TXFE) == PL011_UARTFR_TXFE) {
 389     *Control |= EFI_SERIAL_OUTPUT_BUFFER_EMPTY;
 390   }
 391
 392   if ((ControlRegister & (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN))
 393       == (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN))
 394   {
 395     *Control |= EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE;
 396   }
 397
 398   if ((ControlRegister & PL011_UARTCR_LBE) == PL011_UARTCR_LBE) {
 399     *Control |= EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE;
 400   }
 401
 402   return RETURN_SUCCESS;
 403 }
 404
 405 /**
 406   Write data to serial device.
 407
 408   @param  Buffer           Point of data buffer which need to be written.
 409   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 410
 411   @retval 0                Write data failed.
 412   @retval !0               Actual number of bytes written to serial device.
 413
 414 **/
 415 UINTN
 416 EFIAPI
 417 PL011UartWrite (
 418   IN  UINTN  UartBase,
 419   IN UINT8   *Buffer,
 420   IN UINTN   NumberOfBytes
 421   )
 422 {
 423   UINT8 *CONST  Final = &Buffer[NumberOfBytes];
 424
 425   while (Buffer < Final) {
 426     // Wait until UART able to accept another char
 427     while ((MmioRead32 (UartBase + UARTFR) & UART_TX_FULL_FLAG_MASK)) {
 428     }
 429
 430     MmioWrite8 (UartBase + UARTDR, *Buffer++);
 431   }
 432
 433   return NumberOfBytes;
 434 }
 435
 436 /**
 437   Read data from serial device and save the data in buffer.
 438
 439   @param  Buffer           Point of data buffer which need to be written.
 440   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 441
 442   @retval 0                Read data failed.
 443   @retval !0               Actual number of bytes read from serial device.
 444
 445 **/
 446 UINTN
 447 EFIAPI
 448 PL011UartRead (
 449   IN  UINTN  UartBase,
 450   OUT UINT8  *Buffer,
 451   IN  UINTN  NumberOfBytes
 452   )
 453 {
 454   UINTN  Count;
 455
 456   for (Count = 0; Count < NumberOfBytes; Count++, Buffer++) {
 457     while ((MmioRead32 (UartBase + UARTFR) & UART_RX_EMPTY_FLAG_MASK) != 0) {
 458     }
 459
 460     *Buffer = MmioRead8 (UartBase + UARTDR);
 461   }
 462
 463   return NumberOfBytes;
 464 }
 465
 466 /**
 467   Check to see if any data is available to be read from the debug device.
 468
 469   @retval TRUE       At least one byte of data is available to be read
 470   @retval FALSE      No data is available to be read
 471
 472 **/
 473 BOOLEAN
 474 EFIAPI
 475 PL011UartPoll (
 476   IN  UINTN  UartBase
 477   )
 478 {
 479   return ((MmioRead32 (UartBase + UARTFR) & UART_RX_EMPTY_FLAG_MASK) == 0);
 480 }