ArmPlatformPkg/Include/Drivers/PL011Uart.h

   1 /** @file
   2 *
   3 *  Copyright (c) 2011-2016, ARM Limited. All rights reserved.
   4 *
   5 *  This program and the accompanying materials
   6 *  are licensed and made available under the terms and conditions of the BSD License
   7 *  which accompanies this distribution.  The full text of the license may be found at
   8 *  http://opensource.org/licenses/bsd-license.php
   9 *
  10 *  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 *  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12 *
  13 **/
  14
  15 #ifndef __PL011_UART_H__
  16 #define __PL011_UART_H__
  17
  18 #include <Uefi.h>
  19 #include <Protocol/SerialIo.h>
  20
  21 #define PL011_VARIANT_ZTE 1
  22
  23 // PL011 Registers
  24 #if FixedPcdGet8 (PL011UartRegOffsetVariant) == PL011_VARIANT_ZTE
  25 #define UARTDR                    0x004
  26 #define UARTRSR                   0x010
  27 #define UARTECR                   0x010
  28 #define UARTFR                    0x014
  29 #define UARTIBRD                  0x024
  30 #define UARTFBRD                  0x028
  31 #define UARTLCR_H                 0x030
  32 #define UARTCR                    0x034
  33 #define UARTIFLS                  0x038
  34 #define UARTIMSC                  0x040
  35 #define UARTRIS                   0x044
  36 #define UARTMIS                   0x048
  37 #define UARTICR                   0x04c
  38 #define UARTDMACR                 0x050
  39 #else
  40 #define UARTDR                    0x000
  41 #define UARTRSR                   0x004
  42 #define UARTECR                   0x004
  43 #define UARTFR                    0x018
  44 #define UARTILPR                  0x020
  45 #define UARTIBRD                  0x024
  46 #define UARTFBRD                  0x028
  47 #define UARTLCR_H                 0x02C
  48 #define UARTCR                    0x030
  49 #define UARTIFLS                  0x034
  50 #define UARTIMSC                  0x038
  51 #define UARTRIS                   0x03C
  52 #define UARTMIS                   0x040
  53 #define UARTICR                   0x044
  54 #define UARTDMACR                 0x048
  55 #endif
  56
  57 #define UARTPID0                  0xFE0
  58 #define UARTPID1                  0xFE4
  59 #define UARTPID2                  0xFE8
  60 #define UARTPID3                  0xFEC
  61
  62 // Data status bits
  63 #define UART_DATA_ERROR_MASK      0x0F00
  64
  65 // Status reg bits
  66 #define UART_STATUS_ERROR_MASK    0x0F
  67
  68 // Flag reg bits
  69 #if FixedPcdGet8 (PL011UartRegOffsetVariant) == PL011_VARIANT_ZTE
  70 #define PL011_UARTFR_RI           (1 << 0)  // Ring indicator
  71 #define PL011_UARTFR_TXFE         (1 << 7)  // Transmit FIFO empty
  72 #define PL011_UARTFR_RXFF         (1 << 6)  // Receive  FIFO full
  73 #define PL011_UARTFR_TXFF         (1 << 5)  // Transmit FIFO full
  74 #define PL011_UARTFR_RXFE         (1 << 4)  // Receive  FIFO empty
  75 #define PL011_UARTFR_BUSY         (1 << 8)  // UART busy
  76 #define PL011_UARTFR_DCD          (1 << 2)  // Data carrier detect
  77 #define PL011_UARTFR_DSR          (1 << 3)  // Data set ready
  78 #define PL011_UARTFR_CTS          (1 << 1)  // Clear to send
  79 #else
  80 #define PL011_UARTFR_RI           (1 << 8)  // Ring indicator
  81 #define PL011_UARTFR_TXFE         (1 << 7)  // Transmit FIFO empty
  82 #define PL011_UARTFR_RXFF         (1 << 6)  // Receive  FIFO full
  83 #define PL011_UARTFR_TXFF         (1 << 5)  // Transmit FIFO full
  84 #define PL011_UARTFR_RXFE         (1 << 4)  // Receive  FIFO empty
  85 #define PL011_UARTFR_BUSY         (1 << 3)  // UART busy
  86 #define PL011_UARTFR_DCD          (1 << 2)  // Data carrier detect
  87 #define PL011_UARTFR_DSR          (1 << 1)  // Data set ready
  88 #define PL011_UARTFR_CTS          (1 << 0)  // Clear to send
  89 #endif
  90
  91 // Flag reg bits - alternative names
  92 #define UART_TX_EMPTY_FLAG_MASK   PL011_UARTFR_TXFE
  93 #define UART_RX_FULL_FLAG_MASK    PL011_UARTFR_RXFF
  94 #define UART_TX_FULL_FLAG_MASK    PL011_UARTFR_TXFF
  95 #define UART_RX_EMPTY_FLAG_MASK   PL011_UARTFR_RXFE
  96 #define UART_BUSY_FLAG_MASK       PL011_UARTFR_BUSY
  97
  98 // Control reg bits
  99 #define PL011_UARTCR_CTSEN        (1 << 15) // CTS hardware flow control enable
 100 #define PL011_UARTCR_RTSEN        (1 << 14) // RTS hardware flow control enable
 101 #define PL011_UARTCR_RTS          (1 << 11) // Request to send
 102 #define PL011_UARTCR_DTR          (1 << 10) // Data transmit ready.
 103 #define PL011_UARTCR_RXE          (1 << 9)  // Receive enable
 104 #define PL011_UARTCR_TXE          (1 << 8)  // Transmit enable
 105 #define PL011_UARTCR_LBE          (1 << 7)  // Loopback enable
 106 #define PL011_UARTCR_UARTEN       (1 << 0)  // UART Enable
 107
 108 // Line Control Register Bits
 109 #define PL011_UARTLCR_H_SPS       (1 << 7)  // Stick parity select
 110 #define PL011_UARTLCR_H_WLEN_8    (3 << 5)
 111 #define PL011_UARTLCR_H_WLEN_7    (2 << 5)
 112 #define PL011_UARTLCR_H_WLEN_6    (1 << 5)
 113 #define PL011_UARTLCR_H_WLEN_5    (0 << 5)
 114 #define PL011_UARTLCR_H_FEN       (1 << 4)  // FIFOs Enable
 115 #define PL011_UARTLCR_H_STP2      (1 << 3)  // Two stop bits select
 116 #define PL011_UARTLCR_H_EPS       (1 << 2)  // Even parity select
 117 #define PL011_UARTLCR_H_PEN       (1 << 1)  // Parity Enable
 118 #define PL011_UARTLCR_H_BRK       (1 << 0)  // Send break
 119
 120 #define PL011_UARTPID2_VER(X)     (((X) >> 4) & 0xF)
 121 #define PL011_VER_R1P4            0x2
 122
 123 /**
 124
 125   Initialise the serial port to the specified settings.
 126   All unspecified settings will be set to the default values.
 127
 128   @param[in]  UartBase            The base address of the serial device.
 129   @param[in]  UartClkInHz         The clock in Hz for the serial device.
 130                                   Ignored if the PCD PL011UartInteger is not 0
 131   @param[in out] BaudRate         The baud rate of the serial device. If the
 132                                   baud rate is not supported, the speed will be
 133                                   reduced to the nearest supported one and the
 134                                   variable's value will be updated accordingly.
 135   @param[in out] ReceiveFifoDepth The number of characters the device will
 136                                   buffer on input.  Value of 0 will use the
 137                                   device's default FIFO depth.
 138   @param[in out]  Parity          If applicable, this is the EFI_PARITY_TYPE
 139                                   that is computed or checked as each character
 140                                   is transmitted or received. If the device
 141                                   does not support parity, the value is the
 142                                   default parity value.
 143   @param[in out]  DataBits        The number of data bits in each character.
 144   @param[in out]  StopBits        If applicable, the EFI_STOP_BITS_TYPE number
 145                                   of stop bits per character.
 146                                   If the device does not support stop bits, the
 147                                   value is the default stop bit value.
 148
 149   @retval RETURN_SUCCESS            All attributes were set correctly on the
 150                                     serial device.
 151   @retval RETURN_INVALID_PARAMETER  One or more of the attributes has an
 152                                     unsupported value.
 153
 154 **/
 155 RETURN_STATUS
 156 EFIAPI
 157 PL011UartInitializePort (
 158   IN     UINTN               UartBase,
 159   IN     UINT32              UartClkInHz,
 160   IN OUT UINT64              *BaudRate,
 161   IN OUT UINT32              *ReceiveFifoDepth,
 162   IN OUT EFI_PARITY_TYPE     *Parity,
 163   IN OUT UINT8               *DataBits,
 164   IN OUT EFI_STOP_BITS_TYPE  *StopBits
 165   );
 166
 167 /**
 168
 169   Assert or deassert the control signals on a serial port.
 170   The following control signals are set according their bit settings :
 171   . Request to Send
 172   . Data Terminal Ready
 173
 174   @param[in]  UartBase  UART registers base address
 175   @param[in]  Control   The following bits are taken into account :
 176                         . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the
 177                           "Request To Send" control signal if this bit is
 178                           equal to one/zero.
 179                         . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert
 180                           the "Data Terminal Ready" control signal if this
 181                           bit is equal to one/zero.
 182                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable
 183                           the hardware loopback if this bit is equal to
 184                           one/zero.
 185                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.
 186                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/
 187                           disable the hardware flow control based on CTS (Clear
 188                           To Send) and RTS (Ready To Send) control signals.
 189
 190   @retval  RETURN_SUCCESS      The new control bits were set on the device.
 191   @retval  RETURN_UNSUPPORTED  The device does not support this operation.
 192
 193 **/
 194 RETURN_STATUS
 195 EFIAPI
 196 PL011UartSetControl (
 197   IN UINTN   UartBase,
 198   IN UINT32  Control
 199   );
 200
 201 /**
 202
 203   Retrieve the status of the control bits on a serial device.
 204
 205   @param[in]   UartBase  UART registers base address
 206   @param[out]  Control   Status of the control bits on a serial device :
 207
 208                          . EFI_SERIAL_DATA_CLEAR_TO_SEND,
 209                            EFI_SERIAL_DATA_SET_READY,
 210                            EFI_SERIAL_RING_INDICATE,
 211                            EFI_SERIAL_CARRIER_DETECT,
 212                            EFI_SERIAL_REQUEST_TO_SEND,
 213                            EFI_SERIAL_DATA_TERMINAL_READY
 214                            are all related to the DTE (Data Terminal Equipment)
 215                            and DCE (Data Communication Equipment) modes of
 216                            operation of the serial device.
 217                          . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the
 218                            receive buffer is empty, 0 otherwise.
 219                          . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the
 220                            transmit buffer is empty, 0 otherwise.
 221                          . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if
 222                            the hardware loopback is enabled (the ouput feeds the
 223                            receive buffer), 0 otherwise.
 224                          . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if
 225                            a loopback is accomplished by software, 0 otherwise.
 226                          . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to
 227                            one if the hardware flow control based on CTS (Clear
 228                            To Send) and RTS (Ready To Send) control signals is
 229                            enabled, 0 otherwise.
 230
 231   @retval RETURN_SUCCESS  The control bits were read from the serial device.
 232
 233 **/
 234 RETURN_STATUS
 235 EFIAPI
 236 PL011UartGetControl (
 237   IN UINTN     UartBase,
 238   OUT UINT32  *Control
 239   );
 240
 241 /**
 242   Write data to serial device.
 243
 244   @param  Buffer           Point of data buffer which need to be written.
 245   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 246
 247   @retval 0                Write data failed.
 248   @retval !0               Actual number of bytes written to serial device.
 249
 250 **/
 251 UINTN
 252 EFIAPI
 253 PL011UartWrite (
 254   IN  UINTN       UartBase,
 255   IN  UINT8       *Buffer,
 256   IN  UINTN       NumberOfBytes
 257   );
 258
 259 /**
 260   Read data from serial device and save the data in buffer.
 261
 262   @param  Buffer           Point of data buffer which need to be written.
 263   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 264
 265   @retval 0                Read data failed.
 266   @retval !0               Actual number of bytes read from serial device.
 267
 268 **/
 269 UINTN
 270 EFIAPI
 271 PL011UartRead (
 272   IN  UINTN       UartBase,
 273   OUT UINT8       *Buffer,
 274   IN  UINTN       NumberOfBytes
 275   );
 276
 277 /**
 278   Check to see if any data is available to be read from the debug device.
 279
 280   @retval TRUE       At least one byte of data is available to be read
 281   @retval FALSE      No data is available to be read
 282
 283 **/
 284 BOOLEAN
 285 EFIAPI
 286 PL011UartPoll (
 287   IN  UINTN       UartBase
 288   );
 289
 290 #endif