/* | |
* 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__ */ |