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