LXR 6.1/​bsps/​arm/​altera-cyclone-v/​include/​bsp/​alt_16550_uart.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:22:44

 /**
  * @file
  *
  * @ingroup RTEMSBSPsARMCycVContrib
  */
 
 /*
  * Altera - SoC UART Manager
  */
 
 /*****************************************************************************
  *
  * Copyright 2013 Altera Corporation. All Rights Reserved.
  * 
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
  * 
  * 1. Redistributions of source code must retain the above copyright notice,
  * this list of conditions and the following disclaimer.
  * 
  * 2. Redistributions in binary form must reproduce the above copyright notice,
  * this list of conditions and the following disclaimer in the documentation
  * and/or other materials provided with the distribution.
  * 
  * 3. The name of the author may not be used to endorse or promote products
  * derived from this software without specific prior written permission.
  * 
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  * 
  *****************************************************************************/
 
 #ifndef __ALT_16550_UART_H__
 #define __ALT_16550_UART_H__
 
 #include "hwlib.h"
 #include "alt_clock_manager.h"
 
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
 /*!
  * \addtogroup UART UART Driver API
  *
  * This module defines the Universal Asynchronous Receiver/Transmitter (UART)
  * API for accessing and using the UART resources. The API allows for general
  * control of a 16550 compatible UART controller.
  *
  * This implementation can control the following UARTs:
  *  * SoCFPGA On-board UARTs
  *  * Altera 16550 Compatible Soft IP UART
  *
  * The following reference materials were used in the design of this API:
  *  * Synopsys® DesignWare DW_apb_uart Databook v3.10a
  *
  * @{
  */
 
 /*!
  * \addtogroup UART_BASIC UART Basic
  *
  * This group of APIs provides basic access to the UART to initialize,
  * uninitialize, read, write, and reset the UART.
  *
  * @{
  */
 
 /*!
  * This type definition enumerates the list of UARTs available on the system.
  */
 typedef enum ALT_16550_DEVICE_e
 {
     /*!
      * This option selects UART0 in the SoC FPGA.
      */
     ALT_16550_DEVICE_SOCFPGA_UART0 = 0,
 
     /*!
      * This option selects UART1 in the SoC FPGA.
      */
     ALT_16550_DEVICE_SOCFPGA_UART1 = 1,
 
     /*!
      * This option selects an Altera 16550 Compatible soft IP UART. The memory
      * location of the device must be provided as part of the initialization.
      */
     ALT_16550_DEVICE_ALTERA_16550_UART = 0x100
 }
 ALT_16550_DEVICE_t;
 
 /*!
  * This structure is used to represent a handle to a specific UART on the
  * system. The internal members are undocumented and should be not altered
  * outside of this API.
  */
 typedef struct ALT_16550_HANDLE_s
 {
     ALT_16550_DEVICE_t device;
     void *             location;
     alt_freq_t         clock_freq;
     uint32_t           data;
     uint32_t           fcr;
 }
 ALT_16550_HANDLE_t;
 
 /*!
  * Performs the initialization steps needed by the UART. This should be the
  * first API call made when accessing a particular UART
  *
  * The default UART setting is 8 databits, no parity, 1 stopbit, and 57600
  * baud.
  *
  * For the SoCFPGA UARTs, The ALT_CLK_L4_SP clock needs to be setup before
  * initialization.
  *
  * \param       device
  *              The UART device identifier.
  *
  * \param       location
  *              The memory of the location for the given UART. For SoCFPGA
  *              UARTs, this parameter is ignored.
  *
  * \param       clock_freq
  *              The clock frequency of the serial clock for the given UART.
  *              For SoCFPGA UARTs, this paramter is ignored.
  *
  * \param       handle
  *              [out] A pointer to a handle that will represent the UART. This
  *              handle should subsequently be used when calling other UART
  *              APIs.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device identifier is invalid.
  * \retval      ALT_E_BAD_CLK   The required clock is not yet setup.
  */
 ALT_STATUS_CODE alt_16550_init(ALT_16550_DEVICE_t device,
                                void * location,
                                alt_freq_t clock_freq,
                                ALT_16550_HANDLE_t * handle);
 
 /*!
  * Performs the uninitialization steps for the UART. This should be the last
  * API call made to cleanup the UART.
  *
  * After calling this function, the handle will need to be initialized again
  * before being used by calling alt_16550_init().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_uninit(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Resets the UART to the default configuration. The UART will be reset and
  * reinitialized.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_reset(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Starts the UART after all configuration has been completed.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_enable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Stops the UART. While UART configuration can be done while enabled, it is
  * not recommended.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_disable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Reads a single character from the UART receiver buffer. This API should
  * only be used when FIFOs are disabled.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       item
  *              [out] Pointer to an output parameter that contains the in
  *              receiver buffer of the UART.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_read(ALT_16550_HANDLE_t * handle,
                                char * item);
 
 /*!
  * Writes a single character to the UART transmitter buffer. This API should
  * only be used when FIFOs are disabled.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       item
  *              The character to write to the transmitter buffer of the UART.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_write(ALT_16550_HANDLE_t * handle,
                                 char item);
 
 /*!
  * @}
  */
 
 /*!
  * \addtogroup UART_FIFO UART FIFO Interface
  *
  * This group of APIs provides access, configuration, and control of the UART
  * FIFO. The FIFO allows the UART to buffer received data and data to be
  * transmitted.
  *
  * @{
  */
 
 /*!
  * This type definition enumerates the receiver FIFO level conditions that
  * will trigger the receiver FIFO to issue a receiver FIFO full event.
  */
 typedef enum ALT_16550_FIFO_TRIGGER_RX_e
 {
     /*!
      * 1 or more character(s) in the receiver FIFO will trigger an event.
      */
     ALT_16550_FIFO_TRIGGER_RX_ANY = 0,
 
     /*!
      * 25% or higher capacity usage in the receiver FIFO will trigger an
      * event.
      */
     ALT_16550_FIFO_TRIGGER_RX_QUARTER_FULL = 1,
 
     /*!
      * 50% or higher capacity usage in the receiver FIFO will trigger an
      * event.
      */
     ALT_16550_FIFO_TRIGGER_RX_HALF_FULL = 2,
 
     /*!
      * 2 characters less than the receiver FIFO capacity will trigger an
      * event.
      */
     ALT_16550_FIFO_TRIGGER_RX_ALMOST_FULL = 3
 }
 ALT_16550_FIFO_TRIGGER_RX_t;
 
 /*!
  * This type definition enumerates the transmitter FIFO level conditions that
  * will trigger the transmitter FIFO to issue a transmitter FIFO empty event.
  */
 typedef enum ALT_16550_FIFO_TRIGGER_TX_e
 {
     /*!
      * Transmitter FIFO being completely empty will trigger an event.
      */
     ALT_16550_FIFO_TRIGGER_TX_EMPTY = 0,
 
     /*!
      * 2 or less character(s) in the transmitter FIFO will trigger an event.
      */
     ALT_16550_FIFO_TRIGGER_TX_ALMOST_EMPTY = 1,
 
     /*!
      * 25% or less capacity usage in the transmitter FIFO will trigger an
      * event.
      */
     ALT_16550_FIFO_TRIGGER_TX_QUARTER_FULL = 2,
 
     /*!
      * 50% or less capacity usage in the transmitter FIFO will trigger an
      * event.
      */
     ALT_16550_FIFO_TRIGGER_TX_HALF_FULL = 3
 }
 ALT_16550_FIFO_TRIGGER_TX_t;
 
 /*!
  * Enables FIFO on the UART. This will enable both the receiver FIFO and
  * transmitter FIFO. Both FIFOs will be cleared.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_enable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables FIFOs on the UART. This will disable both the receiver FIFO and
  * transmitter FIFO. Any data left in the FIFOs will be lost.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_disable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Reads the given buffer from the receiver FIFO in the UART.
  *
  * The available characters in the FIFO can be determined by a few ways. Users
  * can determine the number of items by calling alt_16550_fifo_level_get_rx().
  *
  * Another way is by using the RX trigger and RX interrupt. First determine the
  * RX FIFO size by calling alt_16550_fifo_size_get_rx(). Then set the desired
  * trigger level by calling alt_16550_fifo_trigger_set_rx(). Calculate the
  * triggering point by applying trigger description on the FIFO size. Enable RX
  * interrupts by calling alt_16550_int_enable_rx(). When the RX interrupt fires
  * due to the ALT_16550_INT_STATUS_RX_DATA condition, the calculated triggering
  * point value can be used to determine the RX FIFO level. If the interrupt
  * fires due to the ALT_16550_INT_STATUS_RX_TIMEOUT, the RX FIFO can be
  * completely emptied by repeatedly polling the Line Status
  * ALT_16550_LINE_STATUS_DR condition by calling alt_16550_line_status_get().
  * These steps are necessary if the UART does not implement FIFO level query
  * functionality. As of 13.0sp1, this applies to the Altera 16550 Compatible
  * Soft UART.
  *
  * Reading more data than that which is available can result in invalid data
  * appearing like valid data.
  *
  * The FIFO must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       buffer
  *              [out] Pointer to a buffer where the specified count of
  *              characters from the receiver FIFO will be copied to.
  *
  * \param       count
  *              The count of characters from the receiver FIFO to be copied.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_read(ALT_16550_HANDLE_t * handle,
                                     char * buffer,
                                     size_t count);
 
 /*!
  * Writes the given buffer to the transmitter FIFO in the UART.
  *
  * The available space in the FIFO can be determined by a few ways. Users can
  * determine the number of items by calculating the FIFO capacity minus the
  * FIFO level. This can be done by calling  alt_16550_fifo_size_get_tx() and
  * alt_16550_fifo_level_get_tx() respectively.
  *
  * Another way is by using the TX trigger and TX interrupt. First determine the
  * TX FIFO size by calling alt_16550_fifo_size_get_tx(). The set the desired
  * trigger level by calling alt_16550_fifo_trigger_set_tx(). Calculate the
  * triggering point by applying the trigger description on the FIFO size.
  * Enable TX interrupts by calling alt_16550_int_enable_tx(). When the TX
  * interrupt fires, calculate the empty entries in the FIFO by subtracting the
  * TX FIFO size and the calculated value. These steps are necessary if the UART
  * does not implement FIFO level query functionality. As of 13.0sp1, this
  * applies to the Altera 16550 Compatible Soft UART.
  *
  * Writing more data that there is space can result in data lost due to
  * overflowing.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       buffer
  *              Pointer to a buffer from where the specified count of
  *              characters will be copied to the transmitter FIFO.
  *
  * \param       count
  *              The count of characters from the given buffer to be copied.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_write(ALT_16550_HANDLE_t * handle,
                                      const char * buffer,
                                      size_t count);
 
 /*!
  * Clears the contents of the receiver FIFO. Any characters which were
  * previously contained in that FIFO will be discarded.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_clear_rx(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Clears the contents of the transmitter FIFO. Any characters which were
  * previously contained in that FIFO will be discarded.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_clear_tx(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Clears the contents of the receiver and transmitter FIFO. Any characters
  * which were previously contained on those FIFOs will be discarded.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_clear_all(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Queries the size of the receiver FIFO. 
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       size
  *              [out] Pointer to an output parameter that contains the size of
  *              the receiver FIFO.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_size_get_rx(ALT_16550_HANDLE_t * handle,
                                            uint32_t * size);
 
 /*!
  * Queries the size of the transmitter FIFO. 
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       size
  *              [out] Pointer to an output parameter that contains the size of
  *              the transmitter FIFO.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_size_get_tx(ALT_16550_HANDLE_t * handle,
                                            uint32_t * size);
 
 /*!
  * Queries the current level of the receiver FIFO.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * For the Altera 16550 Compatible UART, it may not be possible to read the
  * FIFO level and this function may always report 0. For more information on
  * interacting with the FIFO in this situation, see documentation for
  * alt_16550_fifo_read().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       level
  *              [out] Pointer to an output parameter that contains the level
  *              or number of characters in the receiver FIFO.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_level_get_rx(ALT_16550_HANDLE_t * handle,
                                             uint32_t * level);
 
 /*!
  * Queries the current level of the transmitter FIFO.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * For the Altera 16550 Compatible UART, it may not be possible to read the
  * FIFO level and this function may always report 0. For more information on
  * interacting with the FIFO in this situation, see documentation for
  * alt_16550_fifo_write().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       level
  *              [out] Pointer to an output parameter that contains the level
  *              or number of characters in the transmitter FIFO.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_level_get_tx(ALT_16550_HANDLE_t * handle,
                                             uint32_t * level);
 
 /*!
  * Sets the receiver FIFO level which will trigger the receiver FIFO to issue
  * receiver FIFO full event. For the list of available receiver FIFO trigger
  * levels, see the documentation for ALT_16550_FIFO_TRIGGER_RX_t.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       trigger
  *              The level of the receiver FIFO which is needed to trigger a
  *              receiver FIFO full event.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_trigger_set_rx(ALT_16550_HANDLE_t * handle,
                                               ALT_16550_FIFO_TRIGGER_RX_t trigger);
 
 /*!
  * Sets the transmitter FIFO level which will trigger the transmitter FIFO to
  * transmitter FIFO empty event. For the list of available transmitter FIFO
  * trigger levels, see the documentation for ALT_16550_FIFO_TRIGGER_TX_t.
  *
  * The FIFOs must first be enabled before calling this function by calling
  * alt_16550_fifo_enable().
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       trigger
  *              The level of the transmitter FIFO which is needed to trigger a
  *              transmitter FIFO empty event.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_fifo_trigger_set_tx(ALT_16550_HANDLE_t * handle,
                                               ALT_16550_FIFO_TRIGGER_TX_t trigger);
 
 /*!
  * @}
  */
 
 /*!
  * \addtogroup UART_BAUD UART Baudrate Interface
  *
  * This group of APIs allows for the configuration of the UART's baudrate
  * generation related functions.
  *
  * The UART baudrate is determined by dividing the ALT_CLK_L4_SP clock with
  * the configured divisor.
  *
  * @{
  */
 
 /*!
  * This enumeration lists out the common baudrates used with modem and serial
  * ports. Not every baudrate is available for the UART due to the limits of
  * the serial clock frequency and divisor value.
  */
 typedef enum ALT_16550_BAUDRATE_e
 {
     ALT_16550_BAUDRATE_50     =     50, /*!< 50 bps baudrate. */
     ALT_16550_BAUDRATE_75     =     75, /*!< 75 bps baudrate. */
     ALT_16550_BAUDRATE_150    =    150, /*!< 150 bps baudrate. */
     ALT_16550_BAUDRATE_300    =    300, /*!< 300 bps baudrate. */
     ALT_16550_BAUDRATE_600    =    600, /*!< 600 bps baudrate. */
     ALT_16550_BAUDRATE_900    =    900, /*!< 900 bps baudrate. */
     ALT_16550_BAUDRATE_1200   =   1200, /*!< 1200 bps baudrate. */
     ALT_16550_BAUDRATE_1800   =   1800, /*!< 1800 bps baudrate. */
     ALT_16550_BAUDRATE_2400   =   2400, /*!< 2400 bps baudrate. */
     ALT_16550_BAUDRATE_3600   =   3600, /*!< 3600 bps baudrate. */
     ALT_16550_BAUDRATE_4800   =   4800, /*!< 4800 bps baudrate. */
     ALT_16550_BAUDRATE_7200   =   7200, /*!< 7200 bps baudrate. */
     ALT_16550_BAUDRATE_9600   =   9600, /*!< 9600 bps baudrate. */
     ALT_16550_BAUDRATE_14400  =  14400, /*!< 14400 bps baudrate. */
     ALT_16550_BAUDRATE_19200  =  19200, /*!< 19200 bps baudrate. */
     ALT_16550_BAUDRATE_28800  =  28800, /*!< 28800 bps baudrate. */
     ALT_16550_BAUDRATE_38400  =  38400, /*!< 38400 bps baudrate. */
     ALT_16550_BAUDRATE_57600  =  57600, /*!< 57600 bps baudrate. */
     ALT_16550_BAUDRATE_115200 = 115200  /*!< 115200 bps baudrate. */
 }
 ALT_16550_BAUDRATE_t;
 
 /*!
  * Gets the baudrate for the UART.
  *
  * This is done by calculating the baudrate from the divisor and the serial
  * clock. The reported baudrate may not correspond exactly to the request
  * baudrate.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       baudrate
  *              [out] Pointer to an output paramter that contains the current
  *              baudrate of the UART.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_baudrate_get(ALT_16550_HANDLE_t * handle,
                                        uint32_t * baudrate);
 
 /*!
  * Sets the baudrate for the UART. This change will take effect when the UART
  * moves from disabled to enabled.
  *
  * This is done by calculating the correct divisor using the request baudrate
  * and the known serial clock.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       baudrate
  *              The requested baudrate for the UART.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  * \retval      ALT_E_ARG_RANGE The given baudrate is not possible due to
  *                              limitations of the baudrate divisor and/or
  *                              serial clock.
  */
 ALT_STATUS_CODE alt_16550_baudrate_set(ALT_16550_HANDLE_t * handle,
                                        uint32_t baudrate);
 
 /*!
  * Gets the baudrate divisor for the UART.
  *
  * The baudrate is determined by the following formula:
  *  * Baudrate = (serial clock frequency) / (16 * divisor)
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       divisor
  *              [out] Pointer to an output parameter that contains the current
  *              divisor used for baudrate generation.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_divisor_get(ALT_16550_HANDLE_t * handle,
                                       uint32_t * divisor);
 
 /*!
  * Sets the baudrate divisor for the UART. This change will take effect when
  * the UART moves from disabled to enabled.
  *
  * The baudrate is determined by the following formula:
  *  * Baudrate = (serial clock frequency) / (16 * divisor)
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       divisor
  *              The specified divisor value to use for baudrate generation.
  *              Valid values are 1 - 65535.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART identifier is invalid or the
  *                              specified divisor is not supported by the
  *                              UART.
  */
 ALT_STATUS_CODE alt_16550_divisor_set(ALT_16550_HANDLE_t * handle,
                                       uint32_t divisor);
 
 /*!
  * @}
  */
 
 /*!
  * \addtogroup UART_INT UART Interrupt Interface
  *
  * This group of APIs provides access, configuration, and control of the 
  * UART interrupts. 
  *
  * @{
  */
 
 /*!
  * This type definition enumerates the different interrupt conditions that can
  * be generated by the UART controller.
  *
  * Interrupts are listed in highest to lowest priority order.
  */
 typedef enum ALT_16550_INT_STATUS_e
 {
     /*!
      * This interrupt signals that a overrun, parity, or framing error 
      * occurred, or a break event occured. The interrupt is cleared by reading
      * the line status by calling alt_16550_line_status_get() or by disabling
      * line status interrupts by calling alt_16550_int_disable_line().
      */
     ALT_16550_INT_STATUS_LINE = 0x6,
 
     /*!
      * This interrupt signals that some data is available to be read from the
      * UART. The definition of some depends on whether FIFOs are enabled or
      * not.
      *
      * If FIFOs are disabled, this interrupt signals that the receiver
      * contains data. In this case, the interrupt is cleared by reading the
      * data from the UART by calling alt_16550_read().
      *
      * If FIFOs are enabled, this interrupt signals that the receiver FIFO
      * level is above the receiver trigger level specified. In this case, the
      * interrupt is cleared by reading a sufficiently large buffer from the
      * receiver FIFO such that the FIFO is filled below the receiver trigger
      * level specified by calling alt_16550_fifo_read() or by adjusting the
      * receiver trigger level appropriately by calling
      * alt_16550_fifo_trigger_set_rx().
      *
      * In either case, this interrupt can also be cleared by disabling
      * receiver interrupts by calling alt_16550_int_disable_rx().
      */
     ALT_16550_INT_STATUS_RX_DATA = 0x4,
 
     /*!
      * This interrupt signals that data is available in the receiver FIFO and
      * that there has been no activity with the receiver FIFO for the last 4
      * character frames. In essence, the receiver FIFO has temporarily settled
      * thus it may be a good time to empty the receiver FIFO. This interrupt
      * is only available if FIFOs are enabled. The interrupt is cleared by
      * reading from the receiver FIFO by calling alt_16550_fifo_read() or by
      * disabling receiver interrupts by calling alt_16550_int_disable_rx().
      */
     ALT_16550_INT_STATUS_RX_TIMEOUT = 0xC,
 
     /*!
      * This interrupt signals that the transmitter is idling. The definition
      * of idling depends on whether FIFOs are enabled or not.
      *
      * If FIFOs are disabled, this interrupt signals that the transmitter
      * shift register is empty. In this case, the interrupt is cleared by
      * writing data to the UART by calling alt_16550_write().
      *
      * If FIFO are enabled, this interrupt signals that the transmitter FIFO
      * level is below the transmitter trigger level specified. In this case,
      * the interrupt is cleared by writing a sufficiently large buffer to the
      * transmitter FIFO such that the FIFO is filled above the transmitter
      * trigger level specified by calling alt_16550_fifo_write() or by
      * adjusting the transmitter trigger level appropriately by calling
      * alt_16550_fifo_trigger_set_tx().
      *
      * In either case, this interrupt can also be cleared by disabling
      * transmitter interrupts by calling alt_16550_int_disable_tx().
      */
     ALT_16550_INT_STATUS_TX_IDLE = 0x2,
 
     /*!
      * Modem status interrupt pending. The interrupt is cleared by reading the
      * modem status by calling alt_16550_modem_status_get() or by disabling
      * modem status interrupts by calling alt_16550_int_disable_modem().
      */
     ALT_16550_INT_STATUS_MODEM = 0x0,
 
     /*!
      * No interrupts pending.
      */
     ALT_16550_INT_STATUS_NONE = 0x1
 }
 ALT_16550_INT_STATUS_t;
 
 /*!
  * Enables the receiver FIFO to generate interrupts. Enabling this interrupt
  * allows for the following interrupt signal(s):
  *  * ALT_16550_INT_STATUS_RX_DATA
  *  * ALT_16550_INT_STATUS_RX_TIMEOUT
  *
  * This interrupt is disabled by default.
  *
  * The FIFOs must also be enabled for this interrupt to actually be generated.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_enable_rx(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables the receiver FIFO from generating interrupts.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_disable_rx(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Enables the transmitter FIFO to generate interrupts. Enabling this
  * interrupt allows for the following interrupt signal(s):
  *  * ALT_16550_INT_STATUS_TX_IDLE
  *
  * This interrupt is disabled by default.
  *
  * The FIFOs must also be enabled for this interrupt to actually be generated.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_enable_tx(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables the transmitter FIFO from generating interrupts.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_disable_tx(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Enables the receiver to generate line status interrupts. Enabling this
  * interrupt allows for the following interrupt signal(s):
  *  * ALT_16550_INT_STATUS_LINE
  *
  * This interrupt is disabled by default.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_enable_line(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables the receiver from generating line status interrupts.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_disable_line(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Enables the UART to generate modem status interrupts. Enabling this
  * interrupt allows for the following interrupt signal(s):
  *  * ALT_16550_INT_STATUS_MODEM
  *
  * This interrupt is disabled by default.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_enable_modem(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables the UART from generate modem status interrupts.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_disable_modem(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables all interrupts on the UART.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_int_disable_all(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Queries the interrupt status of the UART. This returns the highest priority
  * interrupt pending. The appropriate interrupts must be enabled for them be
  * generated in the UART.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       status
  *              [out] Pointer to an output parameter that contains the current
  *              interrupt status of the UART.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE  alt_16550_int_status_get(ALT_16550_HANDLE_t * handle,
                                           ALT_16550_INT_STATUS_t * status);
 
 /*!
  * @}
  */
 
 /*!
  * \addtogroup UART_MODEM UART Modem Interface
  *
  * This group of APIs provides access, configuration, and control of the UART
  * Modem interface.
  *
  * @{
  */
 
 /*!
  * This type definition enumerates the set of UART modem status conditions as
  * register mask values.
  */
 typedef enum ALT_16550_MODEM_STATUS_e
 {
     /*!
      * Data Carrier Detect. This status indicates that the carrier has been
      * detected by the modem. It corresponds to an inverted dcd_n input. DCD
      * is unasserted when dcd_n is logic 1 and asserted when dcd_n is logic 0.
      */
     ALT_16550_MODEM_STATUS_DCD = 1 << 7,
 
     /*!
      * Ring Indicator. This status indicates that the telephone ringing signal
      * has been redeived by the modem. It corresponds to an inverted ri_n
      * input. RI is unasserted when ri_n is logic 1 and asserted when ri_n is
      * logic 0.
      */
     ALT_16550_MODEM_STATUS_RI = 1 << 6,
 
     /*!
      * Data Set Ready. This status indicates that the modem is ready to
      * establish communications with the UART. It corresponds to an inverted
      * dsr_n input. DSR is unasserted when dsr_n is logic 1 and asserted when
      * dsr_n is logic 0.
      */
     ALT_16550_MODEM_STATUS_DSR = 1 << 5,
 
     /*!
      * Clear To Send. This status indicates the current state of the modem
      * cts_n line. It corresponds to an inverted cts_n input. CTS is
      * unasserted when cts_n is logic 1 and asserted when cts_n is logic 0.
      */
     ALT_16550_MODEM_STATUS_CTS = 1 << 4,
 
     /*!
      * Delta Data Carrier Detect. This status condition indicates that the
      * Data Carrier Detect has changed since the last time the modem status
      * was read. Reading the modem status clears this status. For more
      * information about the Data Carrier Detect status, see
      * ALT_16550_MODEM_STATUS_DCD.
      */
     ALT_16550_MODEM_STATUS_DDCD = 1 << 3,
 
     /*!
      * Trailing Edge of Ring Indicator. This status indicates that the Ring
      * Indicator has changed from asserted to unasserted. Reading the modem
      * status will clear this status. For more information about the Ring
      * Indicator status, reference ALT_16550_MODEM_STATUS_RI.
      */
     ALT_16550_MODEM_STATUS_TERI = 1 << 2,
 
     /*!
      * Delta Data Set Ready. This status condition indicates that the Data Set
      * Ready has changed since the last time the modem status was read.
      * Reading the modem status will clear this status. For more information
      * about the Data Set Ready status, see ALT_16550_MODEM_STATUS_DSR.
      */
     ALT_16550_MODEM_STATUS_DDSR = 1 << 1,
 
     /*!
      * Delta Clear To Send. This status condition indicates that the Clear To
      * Send has changed since the last time the modem status was read. Reading
      * the modem status will clear this status. For more information about the
      * Clear To Send status, see ALT_16550_MODEM_STATUS_CTS.
      */
     ALT_16550_MODEM_STATUS_DCTS = 1 << 0
 }
 ALT_16550_MODEM_STATUS_t;
 
 /*!
  * Enables automatic flow control in the UART modem. When in this mode, the
  * rts_n is gated with the threshold trigger condition of the receiver FIFO.
  *
  * The Altera 16550 Compatible Soft IP UART may not have this option enabled.
  *
  * The FIFOs must be enabled for flow control to be used.
  *
  * The recommended bring up for flow control is as follows:
  *  * Enable automatic flow control by calling alt_16550_flowcontrol_enable().
  *    This will allow both the receiver FIFO and user RTS to control the rts_n
  *    output. Because the user RTS is not enabled, the rts_n will be inactive
  *    high.
  *  * Enable RTS by calling alt_16550_modem_enable_rts(). This will give the
  *    receiver FIFO to have full control of the rts_n output.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_flowcontrol_enable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Disables automatic flow control in the UART modem.
  *
  * The recommended bring down for flow control is as follows:
  *  * Disable RTS by calling alt_16550_modem_disable_rts(). This will disable
  *    generation of the rts_n ouput.
  *  * Disable automatic flow control by calling
  *    alt_16550_flowcontrol_disable().
  *
  * The receiver FIFO will still be active after these steps.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_flowcontrol_disable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Puts the UART in loopback mode. This is used for diagnostic and test
  * purposes.
  *
  * The SoCFPGA UARTs does not support automatic flow control when in loopback
  * mode.
  *
  * The Altera 16550 Compatible Soft IP UART implements this in 13.0sp1 and
  * later. Setting this has no effect with 13.0.
  *
  * When in this mode, the modem control inputs (dsr_n, cts_n, ri_n, dcd_n) are
  * disconnected and the modem control outputs (dtr_n, rts_n, out1_n, out2_n)
  * are held inactive high externally and internally looped back to the inputs.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_loopback_enable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Takes the UART out of loopback mode.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_loopback_disable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Asserts the OUT1 output. OUT1 is inverted then driven out to out1_n.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_enable_out1(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Unasserts the OUT1 output.  OUT1 is inverted then driven out to out1_n.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_disable_out1(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Asserts the OUT2 output. OUT2 is inverted then driven out to out2_n.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_enable_out2(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Unasserts the OUT2 output. OUT2 is inverted then driven out to out2_n.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_disable_out2(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Asserts the RTS (Request To Send) output. RTS is inverted then driven out
  * to rts_n. RTS is used to inform the modem that the UART is ready to receive
  * data.
  *
  * There are special considerations when the UART is in automatic flow control
  * mode. See alt_16550_flowcontrol_enable() for more information.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_enable_rts(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Deaserts the RTS (Request To Send) output. RTS is inverted then driven out
  * to rts_n.
  *
  * There are special considerations when the UART is in automatic flow control
  * mode. See alt_16550_flowcontrol_enable() for more information.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_disable_rts(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Asserts the DTR (Data Terminal Ready) output. DTR is inverted then driven
  * out to dtr_n. DTR is used to inform the modem that UART is ready to
  * establish communications.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_enable_dtr(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Deasserts the DTR (Data Terminal Ready) output. DTR is inverted then driven
  * out to dtr_n.
  *
  * There are special considerations when the UART is in loopback mode. See
  * alt_16550_loopback_enable() for more information.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_disable_dtr(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Reads the modem status from the UART.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       status
  *              [out] Pointer to an output parameter that contains the current
  *              modem status of the UART as a register mask.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_modem_status_get(ALT_16550_HANDLE_t * handle,
                                            uint32_t * status);
 
 /*!
  * @}
  */
 
 /*!
  * \addtogroup UART_LINE UART Line Interface
  *
  * This group of APIs provides access, configuration, and control of the UART
  * Line interface.
  *
  * @{
  */
 
 /*!
  * This type definition enumerates the supported databits per frame.
  */
 typedef enum ALT_16550_DATABITS_e
 {
     /*!
      * This option selects 5 databits per frame.
      */
     ALT_16550_DATABITS_5 = 0,
 
     /*!
      * This option selects 6 databits per frame.
      */
     ALT_16550_DATABITS_6 = 1,
 
     /*!
      * This option selects 7 databits per frame.
      */
     ALT_16550_DATABITS_7 = 2,
 
     /*!
      * This option selects 8 databits per frame.
      */
     ALT_16550_DATABITS_8 = 3
 }
 ALT_16550_DATABITS_t;
 
 /*!
  * This type definition enumerates the supported stopbits per frame.
  */
 typedef enum ALT_16550_STOPBITS_e
 {
     /*!
      * This options specifies 1 stopbit per frame.
      */
     ALT_16550_STOPBITS_1 = 0,
 
     /*!
      * This options specifies 2 stopbits per frame. If the frame is
      * configured with 5 databits, 1.5 stopbits is used instead.
      */
     ALT_16550_STOPBITS_2 = 1
 }
 ALT_16550_STOPBITS_t;
 
 /*!
  * This type definition enumerates the possible parity to use per frame.
  */
 typedef enum ALT_16550_PARITY_e
 {
     /*!
      * This option disables the parity error detection bit in the data frame.
      */
     ALT_16550_PARITY_DISABLE = 0,
 
     /*!
      * This option enables the odd parity error detection bit in the data
      * frame.
      */
     ALT_16550_PARITY_ODD = 1,
 
     /*!
      * This option enables the even parity error detection bit in the data
      * frame.
      */
     ALT_16550_PARITY_EVEN = 2
 }
 ALT_16550_PARITY_t;
 
 /*!
  * This type definition enumerates the set of UART line status conditions as
  * register mask values.
  */
 typedef enum ALT_16550_LINE_STATUS_e
 {
     /*!
      * Receiver FIFO Error. This status indicates that one or more parity
      * error, framing error, or break indication exists in the receiver FIFO.
      * It is only set when FIFO is enabled. This status cleared when line
      * status is read, the character with the issue is at the top of the FIFO,
      * and when no other issues exist in the FIFO.
      */
     ALT_16550_LINE_STATUS_RFE = 1 << 7,
 
     /*!
      * Transmitter EMpTy (Empty). This status indicates that transmitter shift
      * register is empty. If FIFOs are enabled, the status is set when the
      * transmitter FIFO is also empty. This status is cleared when the
      * transmitter shift registers is loaded by writing to the UART
      * transmitter buffer or transmitter FIFO if FIFOs are enabled. This is
      * done by calling alt_16550_write() and alt_16550_fifo_write()
      * respectively.
      */
     ALT_16550_LINE_STATUS_TEMT = 1 << 6,
 
     /*!
      * Transmitter Holding Register Empty. This status indicates that the 
      * transmitter will run out of data soon. The definition of soon depends
      * on whether the FIFOs are enabled.
      *
      * If FIFOs are disabled, this status indicates that the transmitter will
      * run out of data to send after the current transmit shift register
      * completes. In this case, this status is cleared when the data is
      * written to the UART. This can be done by calling alt_16550_write().
      *
      * If FIFOs are enabled, this status indicates that the transmitter FIFO
      * level is below the transmitter trigger level specified. In this case,
      * this status is cleared by writing a sufficiently large buffer to the
      * transmitter FIFO such that the FIFO is filled above the transmitter
      * trigger level specified by calling alt_16550_fifo_write() or by
      * adjusting the transmitter trigger level appropriately by calling 
      * alt_16550_fifo_trigger_set_tx().
      *
      * \internal
      * The implementation of the UART driver always ensures that IER[7] is
      * set. This means that the UART always has Programmable THRE (Transmitter
      * Holding Register Empty) Interrupt Mode Enable (PTIME) enabled.
      * \endinternal
      */
     ALT_16550_LINE_STATUS_THRE = 1 << 5,
 
     /*!
      * Break Interrupt. This status indicates that a break interrupt sequence
      * is detected in the incoming serial data. This happens when the the data
      * is 0 for longer than a frame would normally be transmitted. The break
      * interrupt status is cleared by reading the line status by calling
      * alt_16550_line_status_get().
      *
      * If FIFOs are enabled, this status will be set when the character with
      * the break interrupt status is at the top of the receiver FIFO.
      */
     ALT_16550_LINE_STATUS_BI = 1 << 4,
 
     /*!
      * Framing Error. This status indicates that a framing error occurred in
      * the receiver. This happens when the receiver detects a missing or
      * incorrect number of stopbit(s).
      *
      * If FIFOs are enabled, this status will be set when the character with
      * the framing error is at the top of the FIFO. When a framing error
      * occurs, the UART attempts to resynchronize with the transmitting UART.
      * This status is also set if break interrupt occurred.
      */
     ALT_16550_LINE_STATUS_FE = 1 << 3,
 
     /*!
      * Parity Error. This status indicates that a parity error occurred in the
      * receiver.
      *
      * If FIFOs are enabled, this status will be set when the character with
      * the parity error is at the top of the receiver FIFO. This status is
      * also set if a break interrupt occurred.
      */
     ALT_16550_LINE_STATUS_PE = 1 << 2,
 
     /*!
      * Overrun Error. This status indicates that an overrun occurred in the
      * receiver.
      *
      * If FIFOs are disabled, the arriving character will overwrite the
      * existing character in the receiver. Any previously existing
      * character(s) will be lost.
      *
      * If FIFOs are disabled, the arriving character will be discarded. The
      * buffer will continue to contain the preexisting characters.
      */
     ALT_16550_LINE_STATUS_OE = 1 << 1,
 
     /*!
      * Data Ready. This status indicates that the receiver or receiver FIFO
      * contains at least one character.
      */
     ALT_16550_LINE_STATUS_DR = 1 << 0
 }
 ALT_16550_LINE_STATUS_t;
 
 /*!
  * Sets the configuration for a given character frame.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       databits
  *              The number of databits for each character frame.
  *
  * \param       parity
  *              The parity to use for each character frame.
  *
  * \param       stopbits
  *              The number of stopbits for each character frame.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_line_config_set(ALT_16550_HANDLE_t * handle,
                                           ALT_16550_DATABITS_t databits,
                                           ALT_16550_PARITY_t parity,
                                           ALT_16550_STOPBITS_t stopbits);
 
 /*!
  * Starts transmitting a break condition by transmitting a logic 0 state
  * longer than a frame would normally be transmitted.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_line_break_enable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Stops transmitting a break condition.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_line_break_disable(ALT_16550_HANDLE_t * handle);
 
 /*!
  * Reads the line status from the UART.
  *
  * \param       handle
  *              The UART device handle.
  *
  * \param       status
  *              [out] Pointer to an output parameter that contains the current
  *              line status of the UART.
  *
  * \retval      ALT_E_SUCCESS   The operation was successful.
  * \retval      ALT_E_ERROR     The operation failed.
  * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
  */
 ALT_STATUS_CODE alt_16550_line_status_get(ALT_16550_HANDLE_t * handle,
                                           uint32_t * status);
 
 /*!
  * @}
  */
 
 /*!
  * @}
  */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* __ALT_16550_UART_H__ */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team