Serial API. More...

#include <serial/frame.h>
#include <serial/serial_common.h>
#include <stdbool.h>
#include <stddef.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/util.h>
#include <serial/serial_backend.h>

Include dependency graph for serial.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ares_serial_transport_api
	Unified serial transport interface. More...
struct	ares_serial_transport
	Transfer interface. More...
struct	ares_buf
	Unified buffer structure for serial. More...
struct	ares_serial_command
	Ares frame handler descriptor. More...
struct	ares_serial_ctx
	Ares serial instance context. More...
struct	ares_serial
	Ares serial internals. More...

Macros
#define	ARES_SERIAL_TRX_BUF_SIZE MAX(SERIAL_BACKEND_TX_RINGBUF_SIZE, SERIAL_BACKEND_RX_RINGBUF_SIZE)
#define	ARES_SERIAL_DEFINE(_name, _transport)
	Macro for defining an ares_serial instance.

Typedefs
typedef void(*	serial_transport_handler_t) (enum serial_transport_evt evt, void *ctx)
	Serial transport event handler prototype.

Enumerations
enum	serial_transport_evt { SERIAL_TRANSPORT_EVT_RX_RDY , SERIAL_TRANSPORT_EVT_TX_RDY }
	Serial transport events. More...
enum	ares_serial_signal { ARES_SIGNAL_RXRDY , ARES_SIGNAL_TXDONE , ARES_SIGNALS }
	Signals for the serial interface. More...

Functions
int	ares_serial_init (const struct ares_serial serial, const void transport_config)
	Function for initiating a transport layer and internal serial state.
int	ares_serial_register_command_callbacks (const struct ares_serial serial, const struct ares_serial_command commands, size_t num_commands)
	Function for registering frame handlers.
int	ares_serial_write_frame (const struct ares_serial serial, const struct ares_frame frame)
	Function to write a frame to the serial transfer layer.
void	ares_serial_flush_out (const struct ares_serial *serial, k_timeout_t timeout)
	Function to flush the serial transfer layer transmit buffer.
int	wait_serial_ready (const struct ares_serial *serial)
	Block current thread execution until a connection is established with a host.
int	set_wait_usb_host (const struct ares_serial *serial, bool block)
	Function to configure the transport layer to block transmissions if no host is connected.
bool	ares_serial_check_rx_error (const struct ares_serial *serial)
	Function to check if there was a reception error in the transfer layer.

Detailed Description

Serial API.

Date: 3/20/26

Author: Tom Schmitz <tschm.nosp@m.itz@.nosp@m.andre.nosp@m.w.cm.nosp@m.u.edu>

Macro Definition Documentation

◆ ARES_SERIAL_DEFINE

#define ARES_SERIAL_DEFINE	(		_name,
			_transport )

Value:

    static struct ares_serial_ctx UTIL_CAT(_name, _ctx);                       \
    static K_KERNEL_STACK_DEFINE(UTIL_CAT(_name, _stack),                      \
                                 CONFIG_ARES_SERIAL_STACK_SIZE);               \
    static struct k_thread UTIL_CAT(_name, _thread);                           \
    static const struct ares_serial _name = {.iface = (_transport),            \
                                             .ctx = &UTIL_CAT(_name, _ctx),    \
                                             .name = STRINGIFY(_name),         \
                                             .thread =                         \
                                                 &UTIL_CAT(_name, _thread),    \
                                             .stack = UTIL_CAT(_name, _stack)}

Macro for defining an ares_serial instance.

Parameters

_name	Instance name.
_transport	Pointer to the transport interface.

◆ ARES_SERIAL_TRX_BUF_SIZE

#define ARES_SERIAL_TRX_BUF_SIZE MAX(SERIAL_BACKEND_TX_RINGBUF_SIZE, SERIAL_BACKEND_RX_RINGBUF_SIZE)

Unified serial buffer size for transmitting and receiving.

Typedef Documentation

◆ serial_transport_handler_t

typedef void(* serial_transport_handler_t) (enum serial_transport_evt evt, void *ctx)

Serial transport event handler prototype.

Parameters

[in]	evt	The event that occurred.
[in]	ctx	Pointer to the event context.

Enumeration Type Documentation

◆ ares_serial_signal

enum ares_serial_signal

Signals for the serial interface.

Enumerator
ARES_SIGNAL_RXRDY	Rx data ready.
ARES_SIGNAL_TXDONE	Done transmitting. Must be last one before ARES_SIGNALS.
ARES_SIGNALS	Last enumerator.

◆ serial_transport_evt

enum serial_transport_evt

Serial transport events.

Enumerator
SERIAL_TRANSPORT_EVT_RX_RDY	Rx ready.
SERIAL_TRANSPORT_EVT_TX_RDY	Tx ready.

Function Documentation

◆ ares_serial_check_rx_error()

bool ares_serial_check_rx_error ( const struct ares_serial * serial )

Function to check if there was a reception error in the transfer layer.

Parameters

[in] serial Pointer to serial instance.

Returns: true if invalid parameters passed in or if there was a reception error.; false otherwise.

◆ ares_serial_flush_out()

void ares_serial_flush_out	(	const struct ares_serial *	serial,
		k_timeout_t	timeout )

Function to flush the serial transfer layer transmit buffer.

Parameters

[in]	serial	Pointer to serial instance.
[in]	timeout	The maximum amount of time to wait for the flush to occur. Use K_FOREVER to wait indefinitely.

◆ ares_serial_init()

int ares_serial_init	(	const struct ares_serial *	serial,
		const void *	transport_config )

Function for initiating a transport layer and internal serial state.

Parameters

[in]	serial	Pointer to serial instance.
[in]	transport_config	Transport configuration during initialization.

Returns: 0 on success.; negative error code otherwise.

◆ ares_serial_register_command_callbacks()

int ares_serial_register_command_callbacks	(	const struct ares_serial *	serial,
		const struct ares_serial_command *	commands,
		size_t	num_commands )

Function for registering frame handlers.

Parameters

[in]	serial	Pointer to serial instance.
[in]	commands	The array of frame handlers.
[in]	num_commands	The number of frame handlers in the array.

Returns: 0 on success.; -EINVAL if parameters are invalid.

◆ ares_serial_write_frame()

int ares_serial_write_frame	(	const struct ares_serial *	serial,
		const struct ares_frame *	frame )

Function to write a frame to the serial transfer layer.

Parameters

[in]	serial	Pointer to serial instance.
[in]	frame	The frame to write to the serial transport.

Returns: 0 on success.; -EINVAL if parameters are invalid.; negative error code otherwise.

◆ set_wait_usb_host()

int set_wait_usb_host	(	const struct ares_serial *	serial,
		bool	block )

Function to configure the transport layer to block transmissions if no host is connected.

Parameters

[in]	serial	Pointer to serial instance.
[in]	block	Tell transfer layer to block transmissions until host is connected.

Returns: 0 on success.; -EINVAL if parameters are invalid.

◆ wait_serial_ready()

int wait_serial_ready ( const struct ares_serial * serial )

Block current thread execution until a connection is established with a host.

Parameters

[in] serial Pointer to serial instance.

Returns: 0 on success.; -EINVAL on invalid parameters.; -ENOTSUP if API is not supported.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ARES_SERIAL_DEFINE

◆ ARES_SERIAL_TRX_BUF_SIZE

Typedef Documentation

◆ serial_transport_handler_t

Enumeration Type Documentation

◆ ares_serial_signal

◆ serial_transport_evt

Function Documentation

◆ ares_serial_check_rx_error()

◆ ares_serial_flush_out()

◆ ares_serial_init()

◆ ares_serial_register_command_callbacks()

◆ ares_serial_write_frame()

◆ set_wait_usb_host()

◆ wait_serial_ready()