Interrupt-driven UART API

Typedefs
typedef void(*	uart_irq_callback_user_data_t) (const struct device *dev, void *user_data)
	Define the application callback function signature for uart_irq_callback_user_data_set() function.
typedef void(*	uart_irq_config_func_t) (const struct device *dev)
	For configuring IRQ on each individual UART device.

Functions
static int	uart_fifo_fill (const struct device *dev, const uint8_t *tx_data, int size)
	Fill FIFO with data.
static int	uart_fifo_fill_u16 (const struct device *dev, const uint16_t *tx_data, int size)
	Fill FIFO with wide data.
static int	uart_fifo_read (const struct device *dev, uint8_t *rx_data, const int size)
	Read data from FIFO.
static int	uart_fifo_read_u16 (const struct device *dev, uint16_t *rx_data, const int size)
	Read wide data from FIFO.
void	uart_irq_tx_enable (const struct device *dev)
	Enable TX interrupt in IER.
void	uart_irq_tx_disable (const struct device *dev)
	Disable TX interrupt in IER.
static int	uart_irq_tx_ready (const struct device *dev)
	Check if UART TX buffer can accept bytes.
void	uart_irq_rx_enable (const struct device *dev)
	Enable RX interrupt.
void	uart_irq_rx_disable (const struct device *dev)
	Disable RX interrupt.
static int	uart_irq_tx_complete (const struct device *dev)
	Check if UART TX block finished transmission.
static int	uart_irq_rx_ready (const struct device *dev)
	Check if UART RX buffer has a received char.
void	uart_irq_err_enable (const struct device *dev)
	Enable error interrupt.
void	uart_irq_err_disable (const struct device *dev)
	Disable error interrupt.
int	uart_irq_is_pending (const struct device *dev)
	Check if any IRQs is pending.
int	uart_irq_update (const struct device *dev)
	Start processing interrupts in ISR.
static int	uart_irq_callback_user_data_set (const struct device *dev, uart_irq_callback_user_data_t cb, void *user_data)
	Set the IRQ callback function pointer.
static int	uart_irq_callback_set (const struct device *dev, uart_irq_callback_user_data_t cb)
	Set the IRQ callback function pointer (legacy).

Detailed Description

Typedef Documentation

uart_irq_callback_user_data_t

typedef void(* uart_irq_callback_user_data_t) (const struct device *dev, void *user_data)

#include <zephyr/drivers/uart.h>

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

Parameters

dev	UART device instance.
user_data	Arbitrary user data.

uart_irq_config_func_t

typedef void(* uart_irq_config_func_t) (const struct device *dev)

#include <zephyr/drivers/uart.h>

For configuring IRQ on each individual UART device.

Parameters

dev	UART device instance.

Function Documentation

uart_fifo_fill()

static int uart_fifo_fill ( const struct device * dev, const uint8_t * tx_data, int size )

inlinestatic

#include <zephyr/drivers/uart.h>

Fill FIFO with data.

This function is expected to be called from UART interrupt handler (ISR), if uart_irq_tx_ready() returns true. Result of calling this function not from an ISR is undefined (hardware-dependent). Likewise, not calling this function from an ISR if uart_irq_tx_ready() returns true may lead to undefined behavior, e.g. infinite interrupt loops. It's mandatory to test return value of this function, as different hardware has different FIFO depth (oftentimes just 1).

Parameters

dev	UART device instance.
tx_data	Data to transmit.
size	Number of bytes to send.

Returns

Number of bytes sent.

Return values

-ENOSYS	if this function is not supported
-ENOTSUP	If API is not enabled.

uart_fifo_fill_u16()

static int uart_fifo_fill_u16 ( const struct device * dev, const uint16_t * tx_data, int size )

inlinestatic

#include <zephyr/drivers/uart.h>

Fill FIFO with wide data.

This function is expected to be called from UART interrupt handler (ISR), if uart_irq_tx_ready() returns true. Result of calling this function not from an ISR is undefined (hardware-dependent). Likewise, not calling this function from an ISR if uart_irq_tx_ready() returns true may lead to undefined behavior, e.g. infinite interrupt loops. It's mandatory to test return value of this function, as different hardware has different FIFO depth (oftentimes just 1).

Parameters

dev	UART device instance.
tx_data	Wide data to transmit.
size	Number of datum to send.

Returns

Number of datum sent.

Return values

-ENOSYS	If this function is not implemented
-ENOTSUP	If API is not enabled.

uart_fifo_read()

static int uart_fifo_read ( const struct device * dev, uint8_t * rx_data, const int size )

inlinestatic

#include <zephyr/drivers/uart.h>

Read data from FIFO.

This function is expected to be called from UART interrupt handler (ISR), if uart_irq_rx_ready() returns true. Result of calling this function not from an ISR is undefined (hardware-dependent). It's unspecified whether "RX ready" condition as returned by uart_irq_rx_ready() is level- or edge- triggered. That means that once uart_irq_rx_ready() is detected, uart_fifo_read() must be called until it reads all available data in the FIFO (i.e. until it returns less data than was requested).

Parameters

dev	UART device instance.
rx_data	Data container.
size	Container size.

Returns

Number of bytes read.

Return values

-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_fifo_read_u16()

static int uart_fifo_read_u16 ( const struct device * dev, uint16_t * rx_data, const int size )

inlinestatic

#include <zephyr/drivers/uart.h>

Read wide data from FIFO.

This function is expected to be called from UART interrupt handler (ISR), if uart_irq_rx_ready() returns true. Result of calling this function not from an ISR is undefined (hardware-dependent). It's unspecified whether "RX ready" condition as returned by uart_irq_rx_ready() is level- or edge- triggered. That means that once uart_irq_rx_ready() is detected, uart_fifo_read() must be called until it reads all available data in the FIFO (i.e. until it returns less data than was requested).

Parameters

dev	UART device instance.
rx_data	Wide data container.
size	Container size.

Returns

Number of datum read.

Return values

-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_callback_set()

static int uart_irq_callback_set ( const struct device * dev, uart_irq_callback_user_data_t cb )

inlinestatic

#include <zephyr/drivers/uart.h>

Set the IRQ callback function pointer (legacy).

This sets up the callback for IRQ. When an IRQ is triggered, the specified function will be called with the device pointer.

Parameters

dev	UART device instance.
cb	Pointer to the callback function.

Return values

0	On success.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_callback_user_data_set()

static int uart_irq_callback_user_data_set ( const struct device * dev, uart_irq_callback_user_data_t cb, void * user_data )

inlinestatic

#include <zephyr/drivers/uart.h>

Set the IRQ callback function pointer.

This sets up the callback for IRQ. When an IRQ is triggered, the specified function will be called with specified user data. See description of uart_irq_update() for the requirements on ISR.

Parameters

dev	UART device instance.
cb	Pointer to the callback function.
user_data	Data to pass to callback function.

Return values

0	On success.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_err_disable()

void uart_irq_err_disable

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Disable error interrupt.

Parameters

dev	UART device instance.

uart_irq_err_enable()

void uart_irq_err_enable

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Enable error interrupt.

Parameters

dev	UART device instance.

uart_irq_is_pending()

int uart_irq_is_pending

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Check if any IRQs is pending.

Parameters

dev	UART device instance.

Return values

1	If an IRQ is pending.
0	If an IRQ is not pending.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_rx_disable()

void uart_irq_rx_disable

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Disable RX interrupt.

Parameters

dev	UART device instance.

uart_irq_rx_enable()

void uart_irq_rx_enable

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Enable RX interrupt.

Parameters

dev	UART device instance.

uart_irq_rx_ready()

static int uart_irq_rx_ready ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/uart.h>

Check if UART RX buffer has a received char.

Check if UART RX buffer has at least one pending character (i.e. uart_fifo_read() will succeed and return non-zero). This function must be called in a UART interrupt handler, or its result is undefined. Before calling this function in the interrupt handler, uart_irq_update() must be called once per the handler invocation. It's unspecified whether condition as returned by this function is level- or edge- triggered (i.e. if this function returns true when RX FIFO is non-empty, or when a new char was received since last call to it). See description of uart_fifo_read() for implication of this.

Parameters

dev	UART device instance.

Return values

1	If a received char is ready.
0	If a received char is not ready.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_tx_complete()

static int uart_irq_tx_complete ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/uart.h>

Check if UART TX block finished transmission.

Check if any outgoing data buffered in UART TX block was fully transmitted and TX block is idle. When this condition is true, UART device (or whole system) can be power off. Note that this function is not useful to check if UART TX can accept more data, use uart_irq_tx_ready() for that. This function must be called in a UART interrupt handler, or its result is undefined. Before calling this function in the interrupt handler, uart_irq_update() must be called once per the handler invocation.

Parameters

dev	UART device instance.

Return values

1	If nothing remains to be transmitted.
0	If transmission is not completed.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_tx_disable()

void uart_irq_tx_disable

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Disable TX interrupt in IER.

Parameters

dev	UART device instance.

uart_irq_tx_enable()

void uart_irq_tx_enable

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Enable TX interrupt in IER.

Parameters

dev	UART device instance.

uart_irq_tx_ready()

static int uart_irq_tx_ready ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/uart.h>

Check if UART TX buffer can accept bytes.

Check if UART TX buffer can accept more bytes for transmission (i.e. uart_fifo_fill() will succeed and return non-zero). This function must be called in a UART interrupt handler, or its result is undefined. Before calling this function in the interrupt handler, uart_irq_update() must be called once per the handler invocation.

Parameters

dev	UART device instance.

Return values

0	If device is not ready to write a new byte.
>0	Minimum number of bytes that can be written in a single call to uart_fifo_fill. It may be possible to write more bytes, but the actual number written must be checked in the return code from uart_fifo_fill.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.

uart_irq_update()

int uart_irq_update

(

const struct device *

dev

)

#include <zephyr/drivers/uart.h>

Start processing interrupts in ISR.

This function should be called the first thing in the ISR. Calling uart_irq_rx_ready(), uart_irq_tx_ready(), uart_irq_tx_complete() allowed only after this.

The purpose of this function is:

• For devices with auto-acknowledge of interrupt status on register read to cache the value of this register (rx_ready, etc. then use this case).
• For devices with explicit acknowledgment of interrupts, to ack any pending interrupts and likewise to cache the original value.
• For devices with implicit acknowledgment, this function will be empty. But the ISR must perform the actions needs to ack the interrupts (usually, call uart_fifo_read() on rx_ready, and uart_fifo_fill() on tx_ready).

Parameters

dev	UART device instance.

Return values

1	On success.
-ENOSYS	If this function is not implemented.
-ENOTSUP	If API is not enabled.