Zephyr API Documentation 4.0.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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
devUART device instance.
user_dataArbitrary 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
devUART 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
devUART device instance.
tx_dataData to transmit.
sizeNumber of bytes to send.
Returns
Number of bytes sent.
Return values
-ENOSYSif this function is not supported
-ENOTSUPIf 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
devUART device instance.
tx_dataWide data to transmit.
sizeNumber of datum to send.
Returns
Number of datum sent.
Return values
-ENOSYSIf this function is not implemented
-ENOTSUPIf 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
devUART device instance.
rx_dataData container.
sizeContainer size.
Returns
Number of bytes read.
Return values
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.
rx_dataWide data container.
sizeContainer size.
Returns
Number of datum read.
Return values
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.
cbPointer to the callback function.
Return values
0On success.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.
cbPointer to the callback function.
user_dataData to pass to callback function.
Return values
0On success.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.

◆ uart_irq_err_enable()

void uart_irq_err_enable ( const struct device * dev)

#include <zephyr/drivers/uart.h>

Enable error interrupt.

Parameters
devUART 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
devUART device instance.
Return values
1If an IRQ is pending.
0If an IRQ is not pending.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.

◆ uart_irq_rx_enable()

void uart_irq_rx_enable ( const struct device * dev)

#include <zephyr/drivers/uart.h>

Enable RX interrupt.

Parameters
devUART 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
devUART device instance.
Return values
1If a received char is ready.
0If a received char is not ready.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.
Return values
1If nothing remains to be transmitted.
0If transmission is not completed.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART 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
devUART 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
devUART device instance.
Return values
0If device is not ready to write a new byte.
>0Minimum 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.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf 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
devUART device instance.
Return values
1On success.
-ENOSYSIf this function is not implemented.
-ENOTSUPIf API is not enabled.