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     if (0 == UartClkInHz) {
 192       return RETURN_INVALID_PARAMETER;
 193     }
 194
 195     Divisor = (UartClkInHz * 4) / *BaudRate;
 196     Integer = Divisor >> FRACTION_PART_SIZE_IN_BITS;
 197     Fractional = Divisor & FRACTION_PART_MASK;
 198   }
 199
 200   //
 201   // If PL011 is already initialized, check the current settings
 202   // and re-initialize only if the settings are different.
 203   //
 204   if (((MmioRead32 (UartBase + UARTCR) & PL011_UARTCR_UARTEN) != 0) &&
 205        (MmioRead32 (UartBase + UARTLCR_H) == LineControl) &&
 206        (MmioRead32 (UartBase + UARTIBRD) == Integer) &&
 207        (MmioRead32 (UartBase + UARTFBRD) == Fractional)) {
 208     // Nothing to do - already initialized with correct attributes
 209     return RETURN_SUCCESS;
 210   }
 211
 212   // Wait for the end of transmission
 213   while ((MmioRead32 (UartBase + UARTFR) & PL011_UARTFR_TXFE) == 0);
 214
 215   // Disable UART: "The UARTLCR_H, UARTIBRD, and UARTFBRD registers must not be changed
 216   // when the UART is enabled"
 217   MmioWrite32 (UartBase + UARTCR, 0);
 218
 219   // Set Baud Rate Registers
 220   MmioWrite32 (UartBase + UARTIBRD, Integer);
 221   MmioWrite32 (UartBase + UARTFBRD, Fractional);
 222
 223   // No parity, 1 stop, no fifo, 8 data bits
 224   MmioWrite32 (UartBase + UARTLCR_H, LineControl);
 225
 226   // Clear any pending errors
 227   MmioWrite32 (UartBase + UARTECR, 0);
 228
 229   // Enable Tx, Rx, and UART overall
 230   MmioWrite32 (UartBase + UARTCR,
 231                PL011_UARTCR_RXE | PL011_UARTCR_TXE | PL011_UARTCR_UARTEN);
 232
 233   return RETURN_SUCCESS;
 234 }
 235
 236 /**
 237
 238   Assert or deassert the control signals on a serial port.
 239   The following control signals are set according their bit settings :
 240   . Request to Send
 241   . Data Terminal Ready
 242
 243   @param[in]  UartBase  UART registers base address
 244   @param[in]  Control   The following bits are taken into account :
 245                         . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the
 246                           "Request To Send" control signal if this bit is
 247                           equal to one/zero.
 248                         . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert
 249                           the "Data Terminal Ready" control signal if this
 250                           bit is equal to one/zero.
 251                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable
 252                           the hardware loopback if this bit is equal to
 253                           one/zero.
 254                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.
 255                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/
 256                           disable the hardware flow control based on CTS (Clear
 257                           To Send) and RTS (Ready To Send) control signals.
 258
 259   @retval  RETURN_SUCCESS      The new control bits were set on the device.
 260   @retval  RETURN_UNSUPPORTED  The device does not support this operation.
 261
 262 **/
 263 RETURN_STATUS
 264 EFIAPI
 265 PL011UartSetControl (
 266     IN UINTN   UartBase,
 267     IN UINT32  Control
 268   )
 269 {
 270   UINT32  Bits;
 271
 272   if ((Control & mInvalidControlBits) != 0) {
 273     return RETURN_UNSUPPORTED;
 274   }
 275
 276   Bits = MmioRead32 (UartBase + UARTCR);
 277
 278   if ((Control & EFI_SERIAL_REQUEST_TO_SEND) != 0) {
 279     Bits |= PL011_UARTCR_RTS;
 280   } else {
 281     Bits &= ~PL011_UARTCR_RTS;
 282   }
 283
 284   if ((Control & EFI_SERIAL_DATA_TERMINAL_READY) != 0) {
 285     Bits |= PL011_UARTCR_DTR;
 286   } else {
 287     Bits &= ~PL011_UARTCR_DTR;
 288   }
 289
 290   if ((Control & EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE) != 0) {
 291     Bits |= PL011_UARTCR_LBE;
 292   } else {
 293     Bits &= ~PL011_UARTCR_LBE;
 294   }
 295
 296   if ((Control & EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE) != 0) {
 297     Bits |= (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN);
 298   } else {
 299     Bits &= ~(PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN);
 300   }
 301
 302   MmioWrite32 (UartBase + UARTCR, Bits);
 303
 304   return RETURN_SUCCESS;
 305 }
 306
 307 /**
 308
 309   Retrieve the status of the control bits on a serial device.
 310
 311   @param[in]   UartBase  UART registers base address
 312   @param[out]  Control   Status of the control bits on a serial device :
 313
 314                          . EFI_SERIAL_DATA_CLEAR_TO_SEND,
 315                            EFI_SERIAL_DATA_SET_READY,
 316                            EFI_SERIAL_RING_INDICATE,
 317                            EFI_SERIAL_CARRIER_DETECT,
 318                            EFI_SERIAL_REQUEST_TO_SEND,
 319                            EFI_SERIAL_DATA_TERMINAL_READY
 320                            are all related to the DTE (Data Terminal Equipment)
 321                            and DCE (Data Communication Equipment) modes of
 322                            operation of the serial device.
 323                          . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the
 324                            receive buffer is empty, 0 otherwise.
 325                          . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the
 326                            transmit buffer is empty, 0 otherwise.
 327                          . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if
 328                            the hardware loopback is enabled (the output feeds the
 329                            receive buffer), 0 otherwise.
 330                          . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if
 331                            a loopback is accomplished by software, 0 otherwise.
 332                          . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to
 333                            one if the hardware flow control based on CTS (Clear
 334                            To Send) and RTS (Ready To Send) control signals is
 335                            enabled, 0 otherwise.
 336
 337   @retval RETURN_SUCCESS  The control bits were read from the serial device.
 338
 339 **/
 340 RETURN_STATUS
 341 EFIAPI
 342 PL011UartGetControl (
 343     IN UINTN     UartBase,
 344     OUT UINT32  *Control
 345   )
 346 {
 347   UINT32      FlagRegister;
 348   UINT32      ControlRegister;
 349
 350
 351   FlagRegister = MmioRead32 (UartBase + UARTFR);
 352   ControlRegister = MmioRead32 (UartBase + UARTCR);
 353
 354   *Control = 0;
 355
 356   if ((FlagRegister & PL011_UARTFR_CTS) == PL011_UARTFR_CTS) {
 357     *Control |= EFI_SERIAL_CLEAR_TO_SEND;
 358   }
 359
 360   if ((FlagRegister & PL011_UARTFR_DSR) == PL011_UARTFR_DSR) {
 361     *Control |= EFI_SERIAL_DATA_SET_READY;
 362   }
 363
 364   if ((FlagRegister & PL011_UARTFR_RI) == PL011_UARTFR_RI) {
 365     *Control |= EFI_SERIAL_RING_INDICATE;
 366   }
 367
 368   if ((FlagRegister & PL011_UARTFR_DCD) == PL011_UARTFR_DCD) {
 369     *Control |= EFI_SERIAL_CARRIER_DETECT;
 370   }
 371
 372   if ((ControlRegister & PL011_UARTCR_RTS) == PL011_UARTCR_RTS) {
 373     *Control |= EFI_SERIAL_REQUEST_TO_SEND;
 374   }
 375
 376   if ((ControlRegister & PL011_UARTCR_DTR) == PL011_UARTCR_DTR) {
 377     *Control |= EFI_SERIAL_DATA_TERMINAL_READY;
 378   }
 379
 380   if ((FlagRegister & PL011_UARTFR_RXFE) == PL011_UARTFR_RXFE) {
 381     *Control |= EFI_SERIAL_INPUT_BUFFER_EMPTY;
 382   }
 383
 384   if ((FlagRegister & PL011_UARTFR_TXFE) == PL011_UARTFR_TXFE) {
 385     *Control |= EFI_SERIAL_OUTPUT_BUFFER_EMPTY;
 386   }
 387
 388   if ((ControlRegister & (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN))
 389        == (PL011_UARTCR_CTSEN | PL011_UARTCR_RTSEN)) {
 390     *Control |= EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE;
 391   }
 392
 393   if ((ControlRegister & PL011_UARTCR_LBE) == PL011_UARTCR_LBE) {
 394     *Control |= EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE;
 395   }
 396
 397   return RETURN_SUCCESS;
 398 }
 399
 400 /**
 401   Write data to serial device.
 402
 403   @param  Buffer           Point of data buffer which need to be written.
 404   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 405
 406   @retval 0                Write data failed.
 407   @retval !0               Actual number of bytes written to serial device.
 408
 409 **/
 410 UINTN
 411 EFIAPI
 412 PL011UartWrite (
 413   IN  UINTN    UartBase,
 414   IN UINT8     *Buffer,
 415   IN UINTN     NumberOfBytes
 416   )
 417 {
 418   UINT8* CONST Final = &Buffer[NumberOfBytes];
 419
 420   while (Buffer < Final) {
 421     // Wait until UART able to accept another char
 422     while ((MmioRead32 (UartBase + UARTFR) & UART_TX_FULL_FLAG_MASK));
 423
 424     MmioWrite8 (UartBase + UARTDR, *Buffer++);
 425   }
 426
 427   return NumberOfBytes;
 428 }
 429
 430 /**
 431   Read data from serial device and save the data in buffer.
 432
 433   @param  Buffer           Point of data buffer which need to be written.
 434   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 435
 436   @retval 0                Read data failed.
 437   @retval !0               Actual number of bytes read from serial device.
 438
 439 **/
 440 UINTN
 441 EFIAPI
 442 PL011UartRead (
 443   IN  UINTN     UartBase,
 444   OUT UINT8     *Buffer,
 445   IN  UINTN     NumberOfBytes
 446   )
 447 {
 448   UINTN   Count;
 449
 450   for (Count = 0; Count < NumberOfBytes; Count++, Buffer++) {
 451     while ((MmioRead32 (UartBase + UARTFR) & UART_RX_EMPTY_FLAG_MASK) != 0);
 452     *Buffer = MmioRead8 (UartBase + UARTDR);
 453   }
 454
 455   return NumberOfBytes;
 456 }
 457
 458 /**
 459   Check to see if any data is available to be read from the debug device.
 460
 461   @retval TRUE       At least one byte of data is available to be read
 462   @retval FALSE      No data is available to be read
 463
 464 **/
 465 BOOLEAN
 466 EFIAPI
 467 PL011UartPoll (
 468   IN  UINTN     UartBase
 469   )
 470 {
 471   return ((MmioRead32 (UartBase + UARTFR) & UART_RX_EMPTY_FLAG_MASK) == 0);
 472 }