RTEMS  5.0.0
Typedefs | Enumerations | Functions

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

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

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

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

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
handleThe UART device handle.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe 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_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe 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_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
buffer[out] Pointer to a buffer where the specified count of characters from the receiver FIFO will be copied to.
countThe count of characters from the receiver FIFO to be copied.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
size[out] Pointer to an output parameter that contains the size of the receiver FIFO.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
size[out] Pointer to an output parameter that contains the size of the transmitter FIFO.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
triggerThe level of the receiver FIFO which is needed to trigger a receiver FIFO full event.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
triggerThe level of the transmitter FIFO which is needed to trigger a transmitter FIFO empty event.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe 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
handleThe UART device handle.
bufferPointer to a buffer from where the specified count of characters will be copied to the transmitter FIFO.
countThe count of characters from the given buffer to be copied.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe given UART device handle is invalid.