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  UartBase                The base address of the serial device.
  98   @param  BaudRate                The baud rate of the serial device. If the
  99                                   baud rate is not supported, the speed will be
 100                                   reduced to the nearest supported one and the
 101                                   variable's value will be updated accordingly.
 102   @param  ReceiveFifoDepth        The number of characters the device will
 103                                   buffer on input.  Value of 0 will use the
 104                                   device's default FIFO depth.
 105   @param  Parity                  If applicable, this is the EFI_PARITY_TYPE
 106                                   that is computed or checked as each character
 107                                   is transmitted or received. If the device
 108                                   does not support parity, the value is the
 109                                   default parity value.
 110   @param  DataBits                The number of data bits in each character.
 111   @param  StopBits                If applicable, the EFI_STOP_BITS_TYPE number
 112                                   of stop bits per character.
 113                                   If the device does not support stop bits, the
 114                                   value is the default stop bit value.
 115
 116   @retval RETURN_SUCCESS            All attributes were set correctly on the
 117                                     serial device.
 118   @retval RETURN_INVALID_PARAMETER  One or more of the attributes has an
 119                                     unsupported value.
 120
 121 **/
 122 RETURN_STATUS
 123 EFIAPI
 124 PL011UartInitializePort (
 125   IN     UINTN               UartBase,
 126   IN OUT UINT64              *BaudRate,
 127   IN OUT UINT32              *ReceiveFifoDepth,
 128   IN OUT EFI_PARITY_TYPE     *Parity,
 129   IN OUT UINT8               *DataBits,
 130   IN OUT EFI_STOP_BITS_TYPE  *StopBits
 131   );
 132
 133 /**
 134
 135   Assert or deassert the control signals on a serial port.
 136   The following control signals are set according their bit settings :
 137   . Request to Send
 138   . Data Terminal Ready
 139
 140   @param[in]  UartBase  UART registers base address
 141   @param[in]  Control   The following bits are taken into account :
 142                         . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the
 143                           "Request To Send" control signal if this bit is
 144                           equal to one/zero.
 145                         . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert
 146                           the "Data Terminal Ready" control signal if this
 147                           bit is equal to one/zero.
 148                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable
 149                           the hardware loopback if this bit is equal to
 150                           one/zero.
 151                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.
 152                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/
 153                           disable the hardware flow control based on CTS (Clear
 154                           To Send) and RTS (Ready To Send) control signals.
 155
 156   @retval  RETURN_SUCCESS      The new control bits were set on the device.
 157   @retval  RETURN_UNSUPPORTED  The device does not support this operation.
 158
 159 **/
 160 RETURN_STATUS
 161 EFIAPI
 162 PL011UartSetControl (
 163   IN UINTN   UartBase,
 164   IN UINT32  Control
 165   );
 166
 167 /**
 168
 169   Retrieve the status of the control bits on a serial device.
 170
 171   @param[in]   UartBase  UART registers base address
 172   @param[out]  Control   Status of the control bits on a serial device :
 173
 174                          . EFI_SERIAL_DATA_CLEAR_TO_SEND,
 175                            EFI_SERIAL_DATA_SET_READY,
 176                            EFI_SERIAL_RING_INDICATE,
 177                            EFI_SERIAL_CARRIER_DETECT,
 178                            EFI_SERIAL_REQUEST_TO_SEND,
 179                            EFI_SERIAL_DATA_TERMINAL_READY
 180                            are all related to the DTE (Data Terminal Equipment)
 181                            and DCE (Data Communication Equipment) modes of
 182                            operation of the serial device.
 183                          . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the
 184                            receive buffer is empty, 0 otherwise.
 185                          . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the
 186                            transmit buffer is empty, 0 otherwise.
 187                          . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if
 188                            the hardware loopback is enabled (the ouput feeds the
 189                            receive buffer), 0 otherwise.
 190                          . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if
 191                            a loopback is accomplished by software, 0 otherwise.
 192                          . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to
 193                            one if the hardware flow control based on CTS (Clear
 194                            To Send) and RTS (Ready To Send) control signals is
 195                            enabled, 0 otherwise.
 196
 197   @retval RETURN_SUCCESS  The control bits were read from the serial device.
 198
 199 **/
 200 RETURN_STATUS
 201 EFIAPI
 202 PL011UartGetControl (
 203   IN UINTN     UartBase,
 204   OUT UINT32  *Control
 205   );
 206
 207 /**
 208   Write data to serial device.
 209
 210   @param  Buffer           Point of data buffer which need to be written.
 211   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 212
 213   @retval 0                Write data failed.
 214   @retval !0               Actual number of bytes written to serial device.
 215
 216 **/
 217 UINTN
 218 EFIAPI
 219 PL011UartWrite (
 220   IN  UINTN       UartBase,
 221   IN  UINT8       *Buffer,
 222   IN  UINTN       NumberOfBytes
 223   );
 224
 225 /**
 226   Read data from serial device and save the data in buffer.
 227
 228   @param  Buffer           Point of data buffer which need to be written.
 229   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 230
 231   @retval 0                Read data failed.
 232   @retval !0               Actual number of bytes read from serial device.
 233
 234 **/
 235 UINTN
 236 EFIAPI
 237 PL011UartRead (
 238   IN  UINTN       UartBase,
 239   OUT UINT8       *Buffer,
 240   IN  UINTN       NumberOfBytes
 241   );
 242
 243 /**
 244   Check to see if any data is available to be read from the debug device.
 245
 246   @retval EFI_SUCCESS       At least one byte of data is available to be read
 247   @retval EFI_NOT_READY     No data is available to be read
 248   @retval EFI_DEVICE_ERROR  The serial device is not functioning properly
 249
 250 **/
 251 BOOLEAN
 252 EFIAPI
 253 PL011UartPoll (
 254   IN  UINTN       UartBase
 255   );
 256
 257 #endif