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