Universal Asynchronous Receiver-Transmitter adapter. More...

Files
file	ad_uart.h
	UART adapter API.

Data Structures
struct	ad_uart_io_conf_t
	UART I/O configuration. More...

struct	ad_uart_driver_conf_t
	UART driver configuration. More...

struct	ad_uart_controller_conf_t
	UART controller configuration. More...

Macros
#define	CONFIG_UART_USE_ASYNC_TRANSACTIONS (1)
	Controls whether UART asynchronous transaction API will be used.

#define	CONFIG_UART_USE_SYNC_TRANSACTIONS (1)
	Controls whether UART synchronous transaction API will be used. More...

Typedefs
typedef void(*	ad_uart_user_cb) (void *user_data, uint16_t transferred)
	Asynchronous callback function. More...

Enumerations
enum	AD_UART_RES_TYPE { AD_UART_RES_TYPE_CONFIG, AD_UART_RES_TYPE_WRITE, AD_UART_RES_TYPE_READ, AD_UART_RES_TYPES }
	UART resource types. More...

enum	AD_UART_ERROR { , AD_UART_ERROR_CONFIG_RX_SIZE = -8, AD_UART_ERROR_IO_CFG_INVALID = -7, AD_UART_ERROR_RESOURCE_NOT_AVAILABLE = -6, AD_UART_ERROR_CONTROLLER_BUSY = -5, AD_UART_ERROR_DEVICE_CLOSED = -4, AD_UART_ERROR_CONTROLLER_CONF_INVALID = -3, AD_UART_ERROR_AUTOFLOW_CONF_INVALID = -2, AD_UART_ERROR_HANDLE_INVALID = -1, AD_UART_ERROR_NONE = 0 }
	UART adapter error codes. More...

Functions
void	ad_uart_init (void)
	Initialize UART adapter. More...

ad_uart_handle_t	ad_uart_open (const ad_uart_controller_conf_t *ad_uart_ctrl_conf)
	Open UART controller. More...

int	ad_uart_close (ad_uart_handle_t handle, bool force)
	Close UART controller. More...

int	ad_uart_reconfig (ad_uart_handle_t handle, const ad_uart_driver_conf_t *ad_drv)
	Reconfigure UART controller. More...

int	ad_uart_write (ad_uart_handle_t handle, const char *wbuf, size_t wlen)
	Perform a blocking write transaction. More...

int	ad_uart_read (ad_uart_handle_t handle, char *rbuf, size_t rlen, OS_TICK_TIME timeout)
	Perform a blocking read transaction. More...

int	ad_uart_write_async (ad_uart_handle_t handle, const char wbuf, size_t wlen, ad_uart_user_cb cb, void user_data)
	Perform a non blocking write transaction. More...

int	ad_uart_read_async (ad_uart_handle_t handle, char rbuf, size_t rlen, ad_uart_user_cb cb, void user_data)
	Perform a non blocking read transaction. More...

int	ad_uart_complete_async_read (ad_uart_handle_t handle)
	Finish asynchronous read. More...

int	ad_uart_complete_async_write (ad_uart_handle_t handle)
	Finish asynchronous write. More...

HW_UART_ID	ad_uart_get_hw_uart_id (ad_uart_handle_t handle)
	Get UART controller id. More...

int	ad_uart_io_config (HW_UART_ID id, const ad_uart_io_conf_t *io, AD_IO_CONF_STATE state)
	Initialize controller pins to on / off io configuration. More...

Detailed Description

Universal Asynchronous Receiver-Transmitter adapter.

Macro Definition Documentation

◆ CONFIG_UART_USE_SYNC_TRANSACTIONS

#define CONFIG_UART_USE_SYNC_TRANSACTIONS (1)

Controls whether UART synchronous transaction API will be used.

UART synchronous transaction API maintains state in retention RAM for every UART bus declared. If the API is not to be used, setting this macro to 0 will save retention RAM.

Typedef Documentation

◆ ad_uart_user_cb

typedef void(* ad_uart_user_cb) (void *user_data, uint16_t transferred)

Asynchronous callback function.

Enumeration Type Documentation

◆ AD_UART_ERROR

enum AD_UART_ERROR

UART adapter error codes.

Enumerator
AD_UART_ERROR_CONFIG_RX_SIZE	Invalid TX size
AD_UART_ERROR_IO_CFG_INVALID	Invalid RX size
AD_UART_ERROR_RESOURCE_NOT_AVAILABLE	Invalid IO configuration
AD_UART_ERROR_CONTROLLER_BUSY	The Resource (Rx, Tx, Config) is not available.
AD_UART_ERROR_DEVICE_CLOSED	The UART controller is not available.
AD_UART_ERROR_CONTROLLER_CONF_INVALID	The device is closed.
AD_UART_ERROR_AUTOFLOW_CONF_INVALID	The controller configuration is invalid.
AD_UART_ERROR_HANDLE_INVALID	The auto flow control configuration is invalid.
AD_UART_ERROR_NONE	The handle returned from ad_uart_open() is not valid.

◆ AD_UART_RES_TYPE

enum AD_UART_RES_TYPE

UART resource types.

Enumerator
AD_UART_RES_TYPE_CONFIG	Configuration resource. Acquiring this resource will block calls to ad_uart_open() for the same UART bus.
AD_UART_RES_TYPE_WRITE	Tx (write) resource. Acquiring this resource will block write operations on the same bus.
AD_UART_RES_TYPE_READ	Rx (read) resource. Acquiring this resource will block read operations on the same bus.
AD_UART_RES_TYPES	Enumeration end.

Function Documentation

◆ ad_uart_close()

int ad_uart_close	(	ad_uart_handle_t	handle,
		bool	force
	)

Close UART controller.

This function:

Aborts ongoing transactions
De-initializes the drivers associated with the controller
Resets controller interface IOs (as specified in ad_uart_open())
Releases the controller resources

Note: If DMA circular buffer is used, then UART SHOULD be closed using force=true

This can be done in either of the two ways (based on the force parameter):

Only on the condition that the controller is not busy. In this case it returns true. Otherwise it does not close and returns false.
Regardless of whether the controller is busy or not. In this case it always closes and returns true.

Parameters

[in]	handle	handle returned from ad_uart_open()
[in]	force	true: Close even if busy. false: do not close if controller is busy

See also: ad_uart_open()

Returns: 0: success, <0: error code

Warning: If force = false, then, in order to close the controller as soon as any ongoing transactions are finished, the application has to call the function repeatedly until the function returns true.

◆ ad_uart_complete_async_read()

int ad_uart_complete_async_read ( ad_uart_handle_t handle )

Finish asynchronous read.

Asynchronous reads allow to create reads with timeouts, after requested number of characters arrive user callback is executed from ISR. At any moment after read is started application can decide that if less than requested characters were received, read request should end. In such case application code should call ad_uart_complete_async_read() to get number of characters read.

Parameters

[in] handle handle returned from ad_uart_open()

Returns: number for successfully read characters

See also: ad_uart_read_async()

◆ ad_uart_complete_async_write()

int ad_uart_complete_async_write ( ad_uart_handle_t handle )

Finish asynchronous write.

This function allows to abort a write request, even if less than the requested characters have been written. After a ad_uart_write_async() call, and before the requested wlen characters of the write-buffer have launched a callback execution through ISR, an application call to this function will stop the write operation and return the number of the characters successfully written so far.

Parameters

[in] handle handle returned from ad_uart_open()

Returns: number for successfully written characters

See also: ad_uart_write_async()

◆ ad_uart_get_hw_uart_id()

HW_UART_ID ad_uart_get_hw_uart_id ( ad_uart_handle_t handle )

Get UART controller id.

This function returns id that can be used to get UART controller id. This id is argument for lower level functions starting with hw_uart_ prefix.

Parameters

[in] handle handle returned from ad_uart_open()

Returns: id that can be used with hw_uart_... functions

◆ ad_uart_init()

void ad_uart_init ( void )

Initialize UART adapter.

Note: It should ONLY be called by the system.

◆ ad_uart_io_config()

int ad_uart_io_config	(	HW_UART_ID	id,
		const ad_uart_io_conf_t *	io,
		AD_IO_CONF_STATE	state
	)

Initialize controller pins to on / off io configuration.

This function should be called for setting pins to the correct level before external devices are powered up (e.g on system init). It does not need to be called before every ad_uart_open() call.

Parameters

[in]	id	controller instance
[in]	io	controller io configuration
[in]	state	on/off io configuration

Returns: 0: success, <0: error code

◆ ad_uart_open()

ad_uart_handle_t ad_uart_open ( const ad_uart_controller_conf_t * ad_uart_ctrl_conf )

Open UART controller.

This function:

Acquires the resources needed for using the controller
Configures the controller interface IOs
Initializes the drivers associated with the controller

Parameters

[in] ad_uart_ctrl_conf controller configuration

Returns: >0: handle that should be used in subsequent API calls, NULL: error

Note: The function will block until it acquires all controller resources

◆ ad_uart_read()

int ad_uart_read	(	ad_uart_handle_t	handle,
		char *	rbuf,
		size_t	rlen,
		OS_TICK_TIME	timeout
	)

Perform a blocking read transaction.

This function performs a synchronous read only transaction

Parameters

[in]	handle	handle returned from ad_uart_open()
[out]	rbuf	buffer for incoming data
[in]	rlen	number of bytes to read
[in]	timeout	timeout time in ticks to wait for data

See also: ad_uart_open()

Note: If timeout is OS_EVENT_FOREVER, exactly rlen bytes must be received. If timeout is specified, function can exit after timeout with less bytes than requested.

Returns: Number of transferred bytes on success, <0: error

◆ ad_uart_read_async()

int ad_uart_read_async	(	ad_uart_handle_t	handle,
		char *	rbuf,
		size_t	rlen,
		ad_uart_user_cb	cb,
		void *	user_data
	)

Perform a non blocking read transaction.

This function performs an asynchronous read only transaction Caller task should retry until function returns no error Callback will be called when transaction is completed

Parameters

[in]	handle	handle returned from ad_uart_open()
[out]	rbuf	buffer for incoming data
[in]	rlen	number of bytes to read
[in]	cb	callback to call after transaction is over (from ISR context)
[in]	user_data	user data passed to cb callback

See also: ad_uart_open()

Warning: Do not call this function consecutively without guaranteeing that the previous async transaction has been completed.; After the callback is called, it is not guaranteed that the scheduler will give control to the task waiting for this transaction to complete. This is important to consider if more than one tasks are using this API.

Returns: 0 on success, <0: error

◆ ad_uart_reconfig()

int ad_uart_reconfig	(	ad_uart_handle_t	handle,
		const ad_uart_driver_conf_t *	ad_drv
	)

Reconfigure UART controller.

This function will apply a new UART driver configuration.

Parameters

[in]	handle	handle returned from ad_uart_open()
[in]	ad_drv	new driver configuration

See also: ad_uart_open()

Returns: 0: success, <0: error code

◆ ad_uart_write()

int ad_uart_write	(	ad_uart_handle_t	handle,
		const char *	wbuf,
		size_t	wlen
	)

Perform a blocking write transaction.

This function performs a synchronous write only transaction

Parameters

[in]	handle	handle returned from ad_uart_open()
[in]	wbuf	buffer containing the data to be sent to the device
[in]	wlen	size of data to be sent to the device

See also: ad_uart_open()

Returns: 0 on success, <0: error

◆ ad_uart_write_async()

int ad_uart_write_async	(	ad_uart_handle_t	handle,
		const char *	wbuf,
		size_t	wlen,
		ad_uart_user_cb	cb,
		void *	user_data
	)

Perform a non blocking write transaction.

This function performs an asynchronous write only transaction Caller task should retry until function returns no error Callback will be called when transaction is completed

Parameters

[in]	handle	handle returned from ad_uart_open()
[in]	wbuf	buffer containing the data to be sent to the device
[in]	wlen	size of data to be sent to the device
[in]	cb	callback to call after transaction is over (from ISR context)
[in]	user_data	user data passed to cb callback

See also: ad_uart_open()

Warning: Do not call this function consecutively without guaranteeing that the previous async transaction has been completed.; After the callback is called, it is not guaranteed that the scheduler will give control to the task waiting for this transaction to complete. This is important to consider if more than one tasks are using this API.

Returns: 0 on success, <0: error

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CONFIG_UART_USE_SYNC_TRANSACTIONS

Typedef Documentation

◆ ad_uart_user_cb

Enumeration Type Documentation

◆ AD_UART_ERROR

◆ AD_UART_RES_TYPE

Function Documentation

◆ ad_uart_close()

◆ ad_uart_complete_async_read()

◆ ad_uart_complete_async_write()

◆ ad_uart_get_hw_uart_id()

◆ ad_uart_init()

◆ ad_uart_io_config()

◆ ad_uart_open()

◆ ad_uart_read()

◆ ad_uart_read_async()

◆ ad_uart_reconfig()

◆ ad_uart_write()

◆ ad_uart_write_async()