Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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

typedef void(* uart_callback_t) (const struct device *dev, struct uart_event *evt, void *user_data)

#include <zephyr/drivers/uart.h>

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

Parameters
devUART device instance.
evtPointer to uart_event instance.
user_dataPointer to data specified by user.

Enumeration Type Documentation

◆ uart_event_type

#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 <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
devUART device instance.
callbackEvent handler.
user_dataData to pass to event handler function.
Return values
0If successful.
-ENOSYSIf not supported by the device.
-ENOTSUPIf 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 <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
devUART device instance.
bufPointer to receive buffer.
lenBuffer length.
Return values
0If successful.
-ENOTSUPIf API is not enabled.
-EBUSYNext buffer already set.
-EACCESReceiver is already disabled (function called too late?).
-errnoOther 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 <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
devUART device instance.
bufPointer to wide data receive buffer.
lenBuffer length.
Return values
0If successful.
-ENOTSUPIf API is not enabled
-EBUSYNext buffer already set.
-EACCESReceiver is already disabled (function called too late?).
-errnoOther negative errno value in case of failure.

◆ uart_rx_disable()

int uart_rx_disable ( const struct device * dev)

#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
devUART device instance.
Return values
0If successful.
-ENOTSUPIf API is not enabled.
-EFAULTThere is no active reception.
-errnoOther 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 <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
devUART device instance.
bufPointer to receive buffer.
lenBuffer length.
timeoutInactivity 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
0If successful.
-ENOTSUPIf API is not enabled.
-EBUSYRX already in progress.
-errnoOther 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 <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
devUART device instance.
bufPointer to wide data receive buffer.
lenBuffer length.
timeoutInactivity 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
0If successful.
-ENOTSUPIf API is not enabled.
-EBUSYRX already in progress.
-errnoOther 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 <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
devUART device instance.
bufPointer to transmit buffer.
lenLength of transmit buffer.
timeoutTimeout in microseconds. Valid only if flow control is enabled. SYS_FOREVER_US disables timeout.
Return values
0If successful.
-ENOTSUPIf API is not enabled.
-EBUSYIf There is already an ongoing transfer.
-errnoOther negative errno value in case of failure.

◆ uart_tx_abort()

int uart_tx_abort ( const struct device * dev)

#include <zephyr/drivers/uart.h>

Abort current TX transmission.

UART_TX_DONE event will be generated with amount of data sent.

Parameters
devUART device instance.
Return values
0If successful.
-ENOTSUPIf API is not enabled.
-EFAULTThere is no active transmission.
-errnoOther 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 <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
devUART device instance.
bufPointer to wide data transmit buffer.
lenLength of wide data transmit buffer.
timeoutTimeout in milliseconds. Valid only if flow control is enabled. SYS_FOREVER_MS disables timeout.
Return values
0If successful.
-ENOTSUPIf API is not enabled.
-EBUSYIf there is already an ongoing transfer.
-errnoOther negative errno value in case of failure.