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