UART Basic

Data Structures
struct	ALT_16550_HANDLE_s

Typedefs
typedef enum ALT_16550_DEVICE_e	ALT_16550_DEVICE_t
typedef struct ALT_16550_HANDLE_s	ALT_16550_HANDLE_t

Enumerations
enum	ALT_16550_DEVICE_e { ALT_16550_DEVICE_SOCFPGA_UART0 = 0, ALT_16550_DEVICE_SOCFPGA_UART1 = 1, ALT_16550_DEVICE_ALTERA_16550_UART = 0x100 }

Functions
ALT_STATUS_CODE	alt_16550_init (ALT_16550_DEVICE_t device, void *location, alt_freq_t clock_freq, ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_uninit (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_reset (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_enable (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_disable (ALT_16550_HANDLE_t *handle)
ALT_STATUS_CODE	alt_16550_read (ALT_16550_HANDLE_t *handle, char *item)
ALT_STATUS_CODE	alt_16550_write (ALT_16550_HANDLE_t *handle, char item)

Detailed Description

This group of APIs provides basic access to the UART to initialize, uninitialize, read, write, and reset the UART.

Typedef Documentation

ALT_16550_DEVICE_t

typedef enum ALT_16550_DEVICE_e ALT_16550_DEVICE_t

This type definition enumerates the list of UARTs available on the system.

ALT_16550_HANDLE_t

typedef struct ALT_16550_HANDLE_s ALT_16550_HANDLE_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.

Enumeration Type Documentation

ALT_16550_DEVICE_e

enum ALT_16550_DEVICE_e

This type definition enumerates the list of UARTs available on the system.

Enumerator
ALT_16550_DEVICE_SOCFPGA_UART0	This option selects UART0 in the SoC FPGA.
ALT_16550_DEVICE_SOCFPGA_UART1	This option selects UART1 in the SoC FPGA.
ALT_16550_DEVICE_ALTERA_16550_UART	This option selects an Altera 16550 Compatible soft IP UART. The memory location of the device must be provided as part of the initialization.

Function Documentation

alt_16550_disable()

ALT_STATUS_CODE alt_16550_disable

(

ALT_16550_HANDLE_t *

handle

)

Stops the UART. While UART configuration can be done while enabled, it is not recommended.

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

ALT_STATUS_CODE alt_16550_enable

(

ALT_16550_HANDLE_t *

handle

)

Starts the UART after all configuration has been completed.

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

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

Parameters

device	The UART device identifier.
location	The memory of the location for the given UART. For SoCFPGA UARTs, this parameter is ignored.
clock_freq	The clock frequency of the serial clock for the given UART. For SoCFPGA UARTs, this paramter is ignored.
handle	[out] A pointer to a handle that will represent the UART. This handle should subsequently be used when calling other UART APIs.

Return values

ALT_E_SUCCESS	The operation was successful.
ALT_E_ERROR	The operation failed.
ALT_E_BAD_ARG	The given UART device identifier is invalid.
ALT_E_BAD_CLK	The required clock is not yet setup.

alt_16550_read()

ALT_STATUS_CODE alt_16550_read	(	ALT_16550_HANDLE_t *	handle,
		char *	item
	)

Reads a single character from the UART receiver buffer. This API should only be used when FIFOs are disabled.

Parameters

handle	The UART device handle.
item	[out] Pointer to an output parameter that contains the in receiver buffer of the UART.

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

ALT_STATUS_CODE alt_16550_reset

(

ALT_16550_HANDLE_t *

handle

)

Resets the UART to the default configuration. The UART will be reset and reinitialized.

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

ALT_STATUS_CODE alt_16550_uninit

(

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

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

ALT_STATUS_CODE alt_16550_write	(	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.

Parameters

handle	The UART device handle.
item	The character to write to the transmitter buffer of the UART.

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.