Async UART API

Data Structures
struct	uart_event_tx
	UART TX event data. More...
struct	uart_event_rx
	UART RX event data. More...
struct	uart_event_rx_buf
	UART RX buffer released event data. More...
struct	uart_event_rx_stop
	UART RX stopped data. More...
struct	uart_event
	Structure containing information about current event. More...

Typedefs
typedef void(*	uart_callback_t) (const struct device *dev, struct uart_event *evt, void *user_data)
	Define the application callback function signature for uart_callback_set() function.

Enumerations
enum	uart_event_type {   UART_TX_DONE , UART_TX_ABORTED , UART_RX_RDY , UART_RX_BUF_REQUEST ,   UART_RX_BUF_RELEASED , UART_RX_DISABLED , UART_RX_STOPPED }
	Types of events passed to callback in UART_ASYNC_API. More...

Functions
static int	uart_callback_set (const struct device *dev, uart_callback_t callback, void *user_data)
	Set event handler function.
int	uart_tx (const struct device *dev, const uint8_t *buf, size_t len, int32_t timeout)
	Send given number of bytes from buffer through UART.
int	uart_tx_u16 (const struct device *dev, const uint16_t *buf, size_t len, int32_t timeout)
	Send given number of datum from buffer through UART.
int	uart_tx_abort (const struct device *dev)
	Abort current TX transmission.
int	uart_rx_enable (const struct device *dev, uint8_t *buf, size_t len, int32_t timeout)
	Start receiving data through UART.
int	uart_rx_enable_u16 (const struct device *dev, uint16_t *buf, size_t len, int32_t timeout)
	Start receiving wide data through UART.
static int	uart_rx_buf_rsp (const struct device *dev, uint8_t *buf, size_t len)
	Provide receive buffer in response to UART_RX_BUF_REQUEST event.
static int	uart_rx_buf_rsp_u16 (const struct device *dev, uint16_t *buf, size_t len)
	Provide wide data receive buffer in response to UART_RX_BUF_REQUEST event.
int	uart_rx_disable (const struct device *dev)
	Disable RX.

Detailed Description

Since

1.14

Version

0.8.0

Typedef Documentation

uart_callback_t

uart_callback_t

#include <include/zephyr/drivers/uart.h>

Define the application callback function signature for uart_callback_set() function.

Parameters

dev	UART device instance.
evt	Pointer to uart_event instance.
user_data	Pointer to data specified by user.

Enumeration Type Documentation

uart_event_type

enum uart_event_type

#include <include/zephyr/drivers/uart.h>

Types of events passed to callback in UART_ASYNC_API.

Receiving:

1. To start receiving, uart_rx_enable has to be called with first buffer
2. When receiving starts to current buffer, UART_RX_BUF_REQUEST will be generated, in response to that user can either:
   • Provide second buffer using uart_rx_buf_rsp, when first buffer is filled, receiving will automatically start to second buffer.
   • Ignore the event, this way when current buffer is filled UART_RX_RDY event will be generated and receiving will be stopped.
3. If some data was received and timeout occurred UART_RX_RDY event will be generated. It can happen multiples times for the same buffer. RX timeout is counted from last byte received i.e. if no data was received, there won't be any timeout event.
4. UART_RX_BUF_RELEASED event will be generated when the current buffer is no longer used by the driver. It will immediately follow UART_RX_RDY event. Depending on the implementation buffer may be released when it is completely or partially filled.
5. If there was second buffer provided, it will become current buffer and we start again at point 2. If no second buffer was specified receiving is stopped and UART_RX_DISABLED event is generated. After that whole process can be repeated.

Any time during reception UART_RX_STOPPED event can occur. if there is any data received, UART_RX_RDY event will be generated. It will be followed by UART_RX_BUF_RELEASED event for every buffer currently passed to driver and finally by UART_RX_DISABLED event.

Receiving can be disabled using uart_rx_disable, after calling that function, if there is any data received, UART_RX_RDY event will be generated. UART_RX_BUF_RELEASED event will be generated for every buffer currently passed to driver and finally UART_RX_DISABLED event will occur.

Transmitting:

1. Transmitting starts by uart_tx function.
2. If whole buffer was transmitted UART_TX_DONE is generated. If timeout occurred UART_TX_ABORTED will be generated.

Transmitting can be aborted using uart_tx_abort, after calling that function UART_TX_ABORTED event will be generated.

Enumerator
UART_TX_DONE	Whole TX buffer was transmitted.
UART_TX_ABORTED	Transmitting aborted due to timeout or uart_tx_abort call. When flow control is enabled, there is a possibility that TX transfer won't finish in the allotted time. Some data may have been transferred, information about it can be found in event data.
UART_RX_RDY	Received data is ready for processing. This event is generated in the following cases: When RX timeout occurred, and data was stored in provided buffer. This can happen multiple times in the same buffer. When provided buffer is full. After uart_rx_disable(). After stopping due to external event (UART_RX_STOPPED).
UART_RX_BUF_REQUEST	Driver requests next buffer for continuous reception. This event is triggered when receiving has started for a new buffer, i.e. it's time to provide a next buffer for a seamless switchover to it. For continuous reliable receiving, user should provide another RX buffer in response to this event, using uart_rx_buf_rsp function If uart_rx_buf_rsp is not called before current buffer is filled up, receiving will stop.
UART_RX_BUF_RELEASED	Buffer is no longer used by UART driver.
UART_RX_DISABLED	RX has been disabled and can be reenabled. This event is generated whenever receiver has been stopped, disabled or finished its operation and can be enabled again using uart_rx_enable
UART_RX_STOPPED	RX has stopped due to external event. Reason is one of uart_rx_stop_reason.

Function Documentation

uart_callback_set()

static int uart_callback_set ( const struct device *  dev, uart_callback_t  callback, void *  user_data  )

inlinestatic

#include <include/zephyr/drivers/uart.h>

Set event handler function.

Since it is mandatory to set callback to use other asynchronous functions, it can be used to detect if the device supports asynchronous API. Remaining API does not have that detection.

Parameters

dev	UART device instance.
callback	Event handler.
user_data	Data to pass to event handler function.

Return values

0	If successful.
-ENOSYS	If not supported by the device.
-ENOTSUP	If API not enabled.

uart_rx_buf_rsp()

static int uart_rx_buf_rsp ( const struct device *  dev, uint8_t *  buf, size_t  len  )

inlinestatic

#include <include/zephyr/drivers/uart.h>

Provide receive buffer in response to UART_RX_BUF_REQUEST event.

Provide pointer to RX buffer, which will be used when current buffer is filled.

Note

Providing buffer that is already in usage by driver leads to undefined behavior. Buffer can be reused when it has been released by driver.

Parameters

dev	UART device instance.
buf	Pointer to receive buffer.
len	Buffer length.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EBUSY	Next buffer already set.
-EACCES	Receiver is already disabled (function called too late?).
-errno	Other negative errno value in case of failure.

uart_rx_buf_rsp_u16()

static int uart_rx_buf_rsp_u16 ( const struct device *  dev, uint16_t *  buf, size_t  len  )

inlinestatic

#include <include/zephyr/drivers/uart.h>

Provide wide data receive buffer in response to UART_RX_BUF_REQUEST event.

Provide pointer to RX buffer, which will be used when current buffer is filled.

Note

Providing buffer that is already in usage by driver leads to undefined behavior. Buffer can be reused when it has been released by driver.

Parameters

dev	UART device instance.
buf	Pointer to wide data receive buffer.
len	Buffer length.

Return values

0	If successful.
-ENOTSUP	If API is not enabled
-EBUSY	Next buffer already set.
-EACCES	Receiver is already disabled (function called too late?).
-errno	Other negative errno value in case of failure.

uart_rx_disable()

int uart_rx_disable

(

const struct device *

dev

)

#include <include/zephyr/drivers/uart.h>

Disable RX.

UART_RX_BUF_RELEASED event will be generated for every buffer scheduled, after that UART_RX_DISABLED event will be generated. Additionally, if there is any pending received data, the UART_RX_RDY event for that data will be generated before the UART_RX_BUF_RELEASED events.

Parameters

dev	UART device instance.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EFAULT	There is no active reception.
-errno	Other negative errno value in case of failure.

uart_rx_enable()

int uart_rx_enable	(	const struct device *	dev,
		uint8_t *	buf,
		size_t	len,
		int32_t	timeout
	)

#include <include/zephyr/drivers/uart.h>

Start receiving data through UART.

Function sets given buffer as first buffer for receiving and returns immediately. After that event handler, set using uart_callback_set, is called with UART_RX_RDY or UART_RX_BUF_REQUEST events.

Parameters

dev	UART device instance.
buf	Pointer to receive buffer.
len	Buffer length.
timeout	Inactivity period after receiving at least a byte which triggers UART_RX_RDY event. Given in microseconds. SYS_FOREVER_US disables timeout. See uart_event_type for details.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EBUSY	RX already in progress.
-errno	Other negative errno value in case of failure.

uart_rx_enable_u16()

int uart_rx_enable_u16	(	const struct device *	dev,
		uint16_t *	buf,
		size_t	len,
		int32_t	timeout
	)

#include <include/zephyr/drivers/uart.h>

Start receiving wide data through UART.

Function sets given buffer as first buffer for receiving and returns immediately. After that event handler, set using uart_callback_set, is called with UART_RX_RDY or UART_RX_BUF_REQUEST events.

Parameters

dev	UART device instance.
buf	Pointer to wide data receive buffer.
len	Buffer length.
timeout	Inactivity period after receiving at least a byte which triggers UART_RX_RDY event. Given in milliseconds. SYS_FOREVER_MS disables timeout. See uart_event_type for details.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EBUSY	RX already in progress.
-errno	Other negative errno value in case of failure.

uart_tx()

int uart_tx	(	const struct device *	dev,
		const uint8_t *	buf,
		size_t	len,
		int32_t	timeout
	)

#include <include/zephyr/drivers/uart.h>

Send given number of bytes from buffer through UART.

Function returns immediately and event handler, set using uart_callback_set, is called after transfer is finished.

Parameters

dev	UART device instance.
buf	Pointer to transmit buffer.
len	Length of transmit buffer.
timeout	Timeout in microseconds. Valid only if flow control is enabled. SYS_FOREVER_US disables timeout.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EBUSY	If There is already an ongoing transfer.
-errno	Other negative errno value in case of failure.

uart_tx_abort()

int uart_tx_abort

(

const struct device *

dev

)

#include <include/zephyr/drivers/uart.h>

Abort current TX transmission.

UART_TX_DONE event will be generated with amount of data sent.

Parameters

dev	UART device instance.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EFAULT	There is no active transmission.
-errno	Other negative errno value in case of failure.

uart_tx_u16()

int uart_tx_u16	(	const struct device *	dev,
		const uint16_t *	buf,
		size_t	len,
		int32_t	timeout
	)

#include <include/zephyr/drivers/uart.h>

Send given number of datum from buffer through UART.

Function returns immediately and event handler, set using uart_callback_set, is called after transfer is finished.

Parameters

dev	UART device instance.
buf	Pointer to wide data transmit buffer.
len	Length of wide data transmit buffer.
timeout	Timeout in milliseconds. Valid only if flow control is enabled. SYS_FOREVER_MS disables timeout.

Return values

0	If successful.
-ENOTSUP	If API is not enabled.
-EBUSY	If there is already an ongoing transfer.
-errno	Other negative errno value in case of failure.