UART FIFO Interface

Typedefs
typedef enum ALT_16550_FIFO_TRIGGER_RX_e	ALT_16550_FIFO_TRIGGER_RX_t
typedef enum ALT_16550_FIFO_TRIGGER_TX_e	ALT_16550_FIFO_TRIGGER_TX_t

Enumerations
enum	ALT_16550_FIFO_TRIGGER_RX_e { ALT_16550_FIFO_TRIGGER_RX_ANY = 0 , ALT_16550_FIFO_TRIGGER_RX_QUARTER_FULL = 1 , ALT_16550_FIFO_TRIGGER_RX_HALF_FULL = 2 , ALT_16550_FIFO_TRIGGER_RX_ALMOST_FULL = 3 }
enum	ALT_16550_FIFO_TRIGGER_TX_e { ALT_16550_FIFO_TRIGGER_TX_EMPTY = 0 , ALT_16550_FIFO_TRIGGER_TX_ALMOST_EMPTY = 1 , ALT_16550_FIFO_TRIGGER_TX_QUARTER_FULL = 2 , ALT_16550_FIFO_TRIGGER_TX_HALF_FULL = 3 }

Functions
ALT_STATUS_CODE	alt_16550_fifo_enable (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_fifo_disable (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_fifo_read (ALT_16550_HANDLE_t *handle, char *buffer, size_t count)
ALT_STATUS_CODE	alt_16550_fifo_write (ALT_16550_HANDLE_t *handle, const char *buffer, size_t count)
ALT_STATUS_CODE	alt_16550_fifo_clear_rx (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_fifo_clear_tx (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_fifo_clear_all (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_fifo_size_get_rx (ALT_16550_HANDLE_t *handle, uint32_t *size)
ALT_STATUS_CODE	alt_16550_fifo_size_get_tx (ALT_16550_HANDLE_t *handle, uint32_t *size)
ALT_STATUS_CODE	alt_16550_fifo_level_get_rx (ALT_16550_HANDLE_t *handle, uint32_t *level)
ALT_STATUS_CODE	alt_16550_fifo_level_get_tx (ALT_16550_HANDLE_t *handle, uint32_t *level)
ALT_STATUS_CODE	alt_16550_fifo_trigger_set_rx (ALT_16550_HANDLE_t *handle, ALT_16550_FIFO_TRIGGER_RX_t trigger)
ALT_STATUS_CODE	alt_16550_fifo_trigger_set_tx (ALT_16550_HANDLE_t *handle, ALT_16550_FIFO_TRIGGER_TX_t trigger)

Detailed Description

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.

Typedef Documentation

ALT_16550_FIFO_TRIGGER_RX_t

typedef enum ALT_16550_FIFO_TRIGGER_RX_e ALT_16550_FIFO_TRIGGER_RX_t

This type definition enumerates the receiver FIFO level conditions that will trigger the receiver FIFO to issue a receiver FIFO full event.

ALT_16550_FIFO_TRIGGER_TX_t

typedef enum ALT_16550_FIFO_TRIGGER_TX_e ALT_16550_FIFO_TRIGGER_TX_t

This type definition enumerates the transmitter FIFO level conditions that will trigger the transmitter FIFO to issue a transmitter FIFO empty event.

Enumeration Type Documentation

ALT_16550_FIFO_TRIGGER_RX_e

enum ALT_16550_FIFO_TRIGGER_RX_e

This type definition enumerates the receiver FIFO level conditions that will trigger the receiver FIFO to issue a receiver FIFO full event.

Enumerator
ALT_16550_FIFO_TRIGGER_RX_ANY	1 or more character(s) in the receiver FIFO will trigger an event.
ALT_16550_FIFO_TRIGGER_RX_QUARTER_FULL	25% or higher capacity usage in the receiver FIFO will trigger an event.
ALT_16550_FIFO_TRIGGER_RX_HALF_FULL	50% or higher capacity usage in the receiver FIFO will trigger an event.
ALT_16550_FIFO_TRIGGER_RX_ALMOST_FULL	2 characters less than the receiver FIFO capacity will trigger an event.

ALT_16550_FIFO_TRIGGER_TX_e

enum ALT_16550_FIFO_TRIGGER_TX_e

This type definition enumerates the transmitter FIFO level conditions that will trigger the transmitter FIFO to issue a transmitter FIFO empty event.

Enumerator
ALT_16550_FIFO_TRIGGER_TX_EMPTY	Transmitter FIFO being completely empty will trigger an event.
ALT_16550_FIFO_TRIGGER_TX_ALMOST_EMPTY	2 or less character(s) in the transmitter FIFO will trigger an event.
ALT_16550_FIFO_TRIGGER_TX_QUARTER_FULL	25% or less capacity usage in the transmitter FIFO will trigger an event.
ALT_16550_FIFO_TRIGGER_TX_HALF_FULL	50% or less capacity usage in the transmitter FIFO will trigger an event.

Function Documentation

alt_16550_fifo_clear_all()

ALT_STATUS_CODE alt_16550_fifo_clear_all

(

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().

Parameters

handle

The UART device handle.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_clear_rx()

ALT_STATUS_CODE alt_16550_fifo_clear_rx

(

ALT_16550_HANDLE_t *

handle

)

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().

Parameters

handle

The UART device handle.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_clear_tx()

ALT_STATUS_CODE alt_16550_fifo_clear_tx

(

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().

Parameters

handle

The UART device handle.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_disable()

ALT_STATUS_CODE alt_16550_fifo_disable

(

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.

Parameters

handle

The UART device handle.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_enable()

ALT_STATUS_CODE alt_16550_fifo_enable

(

ALT_16550_HANDLE_t *

handle

)

Enables FIFO on the UART. This will enable both the receiver FIFO and transmitter FIFO. Both FIFOs will be cleared.

Parameters

handle

The UART device handle.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_level_get_rx()

ALT_STATUS_CODE alt_16550_fifo_level_get_rx	(	ALT_16550_HANDLE_t *	handle,
		uint32_t *	level
	)

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().

Parameters

handle	The UART device handle.
level	[out] Pointer to an output parameter that contains the level or number of characters in the receiver FIFO.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_level_get_tx()

ALT_STATUS_CODE alt_16550_fifo_level_get_tx	(	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().

Parameters

handle	The UART device handle.
level	[out] Pointer to an output parameter that contains the level or number of characters in the transmitter FIFO.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_read()

ALT_STATUS_CODE alt_16550_fifo_read	(	ALT_16550_HANDLE_t *	handle,
		char *	buffer,
		size_t	count
	)

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().

Parameters

handle	The UART device handle.
buffer	[out] Pointer to a buffer where the specified count of characters from the receiver FIFO will be copied to.
count	The count of characters from the receiver FIFO to be copied.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_size_get_rx()

ALT_STATUS_CODE alt_16550_fifo_size_get_rx	(	ALT_16550_HANDLE_t *	handle,
		uint32_t *	size
	)

Queries the size of the receiver FIFO.

Parameters

handle	The UART device handle.
size	[out] Pointer to an output parameter that contains the size of the receiver FIFO.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_size_get_tx()

ALT_STATUS_CODE alt_16550_fifo_size_get_tx	(	ALT_16550_HANDLE_t *	handle,
		uint32_t *	size
	)

Queries the size of the transmitter FIFO.

Parameters

handle	The UART device handle.
size	[out] Pointer to an output parameter that contains the size of the transmitter FIFO.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_trigger_set_rx()

ALT_STATUS_CODE alt_16550_fifo_trigger_set_rx	(	ALT_16550_HANDLE_t *	handle,
		ALT_16550_FIFO_TRIGGER_RX_t	trigger
	)

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().

Parameters

handle	The UART device handle.
trigger	The level of the receiver FIFO which is needed to trigger a receiver FIFO full event.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_trigger_set_tx()

ALT_STATUS_CODE alt_16550_fifo_trigger_set_tx	(	ALT_16550_HANDLE_t *	handle,
		ALT_16550_FIFO_TRIGGER_TX_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().

Parameters

handle	The UART device handle.
trigger	The level of the transmitter FIFO which is needed to trigger a transmitter FIFO empty event.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.

alt_16550_fifo_write()

ALT_STATUS_CODE alt_16550_fifo_write	(	ALT_16550_HANDLE_t *	handle,
		const 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().

Parameters

handle	The UART device handle.
buffer	Pointer to a buffer from where the specified count of characters will be copied to the transmitter FIFO.
count	The count of characters from the given buffer to be copied.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device handle is invalid.