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