ArmPlatformPkg/Include/Library/PL011UartLib.h

   1 /** @file
   2 *
   3 *  Copyright (c) 2011-2016, ARM Limited. All rights reserved.
   4 *
   5 *  SPDX-License-Identifier: BSD-2-Clause-Patent
   6 *
   7 **/
   8
   9 #ifndef __PL011_UART_LIB_H__
  10 #define __PL011_UART_LIB_H__
  11
  12 #include <Uefi/UefiBaseType.h>
  13
  14 #include <Protocol/SerialIo.h>
  15
  16 /**
  17
  18   Initialise the serial port to the specified settings.
  19   All unspecified settings will be set to the default values.
  20
  21   @param[in]  UartBase            The base address of the serial device.
  22   @param[in]  UartClkInHz         The clock in Hz for the serial device.
  23                                   Ignored if the PCD PL011UartInteger is not 0
  24   @param[in out] BaudRate         The baud rate of the serial device. If the
  25                                   baud rate is not supported, the speed will be
  26                                   reduced to the nearest supported one and the
  27                                   variable's value will be updated accordingly.
  28   @param[in out] ReceiveFifoDepth The number of characters the device will
  29                                   buffer on input.  Value of 0 will use the
  30                                   device's default FIFO depth.
  31   @param[in out]  Parity          If applicable, this is the EFI_PARITY_TYPE
  32                                   that is computed or checked as each character
  33                                   is transmitted or received. If the device
  34                                   does not support parity, the value is the
  35                                   default parity value.
  36   @param[in out]  DataBits        The number of data bits in each character.
  37   @param[in out]  StopBits        If applicable, the EFI_STOP_BITS_TYPE number
  38                                   of stop bits per character.
  39                                   If the device does not support stop bits, the
  40                                   value is the default stop bit value.
  41
  42   @retval RETURN_SUCCESS            All attributes were set correctly on the
  43                                     serial device.
  44   @retval RETURN_INVALID_PARAMETER  One or more of the attributes has an
  45                                     unsupported value.
  46
  47 **/
  48 RETURN_STATUS
  49 EFIAPI
  50 PL011UartInitializePort (
  51   IN     UINTN               UartBase,
  52   IN     UINT32              UartClkInHz,
  53   IN OUT UINT64              *BaudRate,
  54   IN OUT UINT32              *ReceiveFifoDepth,
  55   IN OUT EFI_PARITY_TYPE     *Parity,
  56   IN OUT UINT8               *DataBits,
  57   IN OUT EFI_STOP_BITS_TYPE  *StopBits
  58   );
  59
  60 /**
  61
  62   Assert or deassert the control signals on a serial port.
  63   The following control signals are set according their bit settings :
  64   . Request to Send
  65   . Data Terminal Ready
  66
  67   @param[in]  UartBase  UART registers base address
  68   @param[in]  Control   The following bits are taken into account :
  69                         . EFI_SERIAL_REQUEST_TO_SEND : assert/deassert the
  70                           "Request To Send" control signal if this bit is
  71                           equal to one/zero.
  72                         . EFI_SERIAL_DATA_TERMINAL_READY : assert/deassert
  73                           the "Data Terminal Ready" control signal if this
  74                           bit is equal to one/zero.
  75                         . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : enable/disable
  76                           the hardware loopback if this bit is equal to
  77                           one/zero.
  78                         . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : not supported.
  79                         . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : enable/
  80                           disable the hardware flow control based on CTS (Clear
  81                           To Send) and RTS (Ready To Send) control signals.
  82
  83   @retval  RETURN_SUCCESS      The new control bits were set on the device.
  84   @retval  RETURN_UNSUPPORTED  The device does not support this operation.
  85
  86 **/
  87 RETURN_STATUS
  88 EFIAPI
  89 PL011UartSetControl (
  90   IN UINTN   UartBase,
  91   IN UINT32  Control
  92   );
  93
  94 /**
  95
  96   Retrieve the status of the control bits on a serial device.
  97
  98   @param[in]   UartBase  UART registers base address
  99   @param[out]  Control   Status of the control bits on a serial device :
 100
 101                          . EFI_SERIAL_DATA_CLEAR_TO_SEND,
 102                            EFI_SERIAL_DATA_SET_READY,
 103                            EFI_SERIAL_RING_INDICATE,
 104                            EFI_SERIAL_CARRIER_DETECT,
 105                            EFI_SERIAL_REQUEST_TO_SEND,
 106                            EFI_SERIAL_DATA_TERMINAL_READY
 107                            are all related to the DTE (Data Terminal Equipment)
 108                            and DCE (Data Communication Equipment) modes of
 109                            operation of the serial device.
 110                          . EFI_SERIAL_INPUT_BUFFER_EMPTY : equal to one if the
 111                            receive buffer is empty, 0 otherwise.
 112                          . EFI_SERIAL_OUTPUT_BUFFER_EMPTY : equal to one if the
 113                            transmit buffer is empty, 0 otherwise.
 114                          . EFI_SERIAL_HARDWARE_LOOPBACK_ENABLE : equal to one if
 115                            the hardware loopback is enabled (the output feeds the
 116                            receive buffer), 0 otherwise.
 117                          . EFI_SERIAL_SOFTWARE_LOOPBACK_ENABLE : equal to one if
 118                            a loopback is accomplished by software, 0 otherwise.
 119                          . EFI_SERIAL_HARDWARE_FLOW_CONTROL_ENABLE : equal to
 120                            one if the hardware flow control based on CTS (Clear
 121                            To Send) and RTS (Ready To Send) control signals is
 122                            enabled, 0 otherwise.
 123
 124   @retval RETURN_SUCCESS  The control bits were read from the serial device.
 125
 126 **/
 127 RETURN_STATUS
 128 EFIAPI
 129 PL011UartGetControl (
 130   IN UINTN     UartBase,
 131   OUT UINT32  *Control
 132   );
 133
 134 /**
 135   Write data to serial device.
 136
 137   @param  Buffer           Point of data buffer which need to be written.
 138   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 139
 140   @retval 0                Write data failed.
 141   @retval !0               Actual number of bytes written to serial device.
 142
 143 **/
 144 UINTN
 145 EFIAPI
 146 PL011UartWrite (
 147   IN  UINTN       UartBase,
 148   IN  UINT8       *Buffer,
 149   IN  UINTN       NumberOfBytes
 150   );
 151
 152 /**
 153   Read data from serial device and save the data in buffer.
 154
 155   @param  Buffer           Point of data buffer which need to be written.
 156   @param  NumberOfBytes    Number of output bytes which are cached in Buffer.
 157
 158   @retval 0                Read data failed.
 159   @retval !0               Actual number of bytes read from serial device.
 160
 161 **/
 162 UINTN
 163 EFIAPI
 164 PL011UartRead (
 165   IN  UINTN       UartBase,
 166   OUT UINT8       *Buffer,
 167   IN  UINTN       NumberOfBytes
 168   );
 169
 170 /**
 171   Check to see if any data is available to be read from the debug device.
 172
 173   @retval TRUE       At least one byte of data is available to be read
 174   @retval FALSE      No data is available to be read
 175
 176 **/
 177 BOOLEAN
 178 EFIAPI
 179 PL011UartPoll (
 180   IN  UINTN       UartBase
 181   );
 182
 183 #endif