STDIO abstraction

Simple standard input/output (STDIO) abstraction for RIOT. More...

Detailed Description

Simple standard input/output (STDIO) abstraction for RIOT.

Abstract

STDIO in RIOT is split into two parts: An interface to the stdio transports consisting mainly of stdio_read and stdio_write provided by RIOT, and the standard C stdio functions (such as printf(), puts(), scanf()) provided by the standard C library.

Configuring STDIO

While the standard features for input and output are enabled by default, some additional features have to be enabled explicitly due to higher memory consumption. This includes the following features:

Module	Features
printf_float	Support for printing floats/doubles
printf_long_long	Support for printing (unsigned) long long
stdin	Support for input (default is output only)

The additional features can be enabled in the application Makefile:

USEMODULE += printf_float

Note

Modules that depend on a certain stdio feature will depend on that. E.g. when using the Shell module, the module stdin is automatically used, as it is a dependency.

Enable STDIO Backends

The various transports supported by RIOT are enabled by selecting the corresponding modules, such as STDIO over UART, STDIO over CDC ACM (usbus), or STDIO over SEGGER RTT. All available options are shown as modules in the list below:

Module	Description
stdio_cdc_acm	USB CDC ACM STDIO, see STDIO over CDC ACM (usbus)
stdio_ethos	Ethernet-over-serial STDIO (legacy, see ethos)
stdio_fb	Framebuffer STDIO
stdio_native	Native board STDIO, forwarded to the host terminal
stdio_nimble	Bluetooth LE STDIO on top of NimBLE
stdio_null	Discards all output, no input support
stdio_rtt	Segger RTT STDIO, see STDIO over SEGGER RTT
stdio_semihosting	ARM/RISC-V semihosting STDIO
stdio_slipdev	SLIP STDIO
stdio_telnet	Telnet STDIO
stdio_tinyusb_cdc_acm	USB CDC ACM STDIO on top of the tinyUSB stack
stdio_uart	UART STDIO, see STDIO over UART
stdio_udp	UDP STDIO
stdio_usb_serial_jtag	USB Serial/JTAG STDIO (e.g. on some ESP32 variants)

As with the additional features, you can specify the STDIO backend to be used in your application Makefile:

USEMODULE += stdio_cdc_acm

Note

More than one backend can be selected at the same time. In that case, stdio_dispatch is pulled in automatically. It forwards stdio_write() to every selected backend and merges the input of all of them into a single stream. A maximum of 9 backends can be selected at the same time.

Not selecting any of the above backends will result in stdio_uart being selected as a fallback, so that a usable STDIO is always available. This happens in a two-stage dependency selection mechanism where first stdio_default is selected, and if no other backend is selected in the second round of dependency resolution, stdio_uart is selected as a fallback. Refer to makefiles/stdio.inc.mk for the details.

Additional features

stdio_available

The pseudomodule stdio_available exists to mark that the selected STDIO backend supports stdio_available, the function used to query how many bytes are currently buffered for reading.

Topics
	Default STDIO provider
	This module selects the default STDIO method of a given board.
	STDIO for native
	Standard input/output backend for native.
	STDIO null driver
	Dummy implementation of the stdio interface.
	STDIO over CDC ACM (usbus)
	Standard input/output backend using usbus CDC ACM.
	STDIO over ESP32 Debug Serial/JTAG
	STDIO via the USB Serial/JTAG debug interface found on some ESP32 SoCs.
	STDIO over NimBLE
	Standard input/output backend using NimBLE.
	STDIO over SEGGER RTT
	STDIO mapping for running the STDIO over SEGGER's RTT interface.
	STDIO over Semihosting
	Standard input/output backend using ARM Semihosting.
	STDIO over UART
	Standard input/output backend using UART.
	STDIO over UDP
	STDIO over UDP implementation.
	STDIO over USB CDC-ACM (tinyUSB)
	Standard input/output backend using tinyUSB CDC ACM.
	STDIO over telnet
	Standard input/output via telnet.
	STDIO via SLIP
	Standard input/output backend multiplexed via SLIP.
	STDIO via ethos
	Standard input/output backend multiplexed via ethernet-over-serial.

Files
file	stdio_base.h

Data Structures
struct	stdio_provider_t
	stdio provider struct More...

Macros
#define	STDIO_RX_BUFSIZE   (64)
	Buffer size for STDIO.
#define	STDIO_PROVIDER(_type, _open, _close, _write)
	stdio implementation methods

Typedefs
typedef void(*	stdio_notify_cb_t) (void *arg)
	Definition of a stdio notify callback.

Enumerations
enum	{   STDIO_NULL , STDIO_UART , STDIO_RTT , STDIO_SEMIHOSTING ,   STDIO_USBUS_CDC_ACM , STDIO_TINYUSB_CDC_ACM , STDIO_ESP32_SERIAL_JTAG , STDIO_NIMBLE ,   STDIO_UDP , STDIO_TELNET , STDIO_ETHOS , STDIO_SLIP }

Functions
int	stdio_rx_write_one (uint8_t c)
	Push a single received byte into stdin.
int	stdio_rx_write (const uint8_t *buf, size_t len)
	Push received bytes into stdin.
void	stdio_set_notify (stdio_notify_cb_t cb, void *arg)
	Register a callback fired when data is available on stdin.
void	stdio_init (void)
	initialize the module
int	stdio_available (void)
	Get the number of bytes available for reading from stdio.
void	stdio_clear_stdin (void)
	Clear the input buffer.
ssize_t	stdio_read (void *buffer, size_t max_len)
	Read len bytes from the STDIN into buffer.
ssize_t	stdio_write (const void *buffer, size_t len)
	Write len bytes from buffer into STDOUT.
void	stdio_close (void)
	Disable stdio and detach stdio providers.

Variables
isrpipe_t	stdin_isrpipe
	isrpipe for writing stdin input to

Macro Definition Documentation

STDIO_PROVIDER

#define STDIO_PROVIDER	(		_type,
			_open,
			_close,
			_write )

Value:

    XFA_CONST(stdio_provider_t, stdio_provider_xfa, 0) stdio_ ##_type = { \
        .open = _open,                                      \
        .close = _close,                                    \
        .write = _write,                                    \
    };

stdio implementation methods

Parameters

_type	stdio provider type, for identification
_open	attach / init function
_close	close / disable function
_write	write function

Definition at line 238 of file stdio_base.h.

STDIO_RX_BUFSIZE

#define STDIO_RX_BUFSIZE   (64)

Buffer size for STDIO.

Definition at line 38 of file stdio_base.h.

Typedef Documentation

stdio_notify_cb_t

typedef void(* stdio_notify_cb_t) (void *arg)

Definition of a stdio notify callback.

Invoked once data becomes available on stdin (see stdio_set_notify), in the (ISR) context of the stdio backend feeding stdin. It must therefore be ISR-safe and non-blocking.

Parameters

[in]

arg

argument registered with the callback

Definition at line 148 of file stdio_base.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
STDIO_NULL	dummy stdio
STDIO_UART	stdio via UART
STDIO_RTT	stdio via Segger RTT
STDIO_SEMIHOSTING	stdio via Semihosting
STDIO_USBUS_CDC_ACM	stdio via USB CDC ACM (usbus)
STDIO_TINYUSB_CDC_ACM	stdio via USB CDC ACM (TinyUSB)
STDIO_ESP32_SERIAL_JTAG	stdio via ESP32 debug Serial/JTAG
STDIO_NIMBLE	stdio via BLE (NimBLE)
STDIO_UDP	stdio via UDP
STDIO_TELNET	stdio via telnet
STDIO_ETHOS	stdio via ethos (mutiplex)
STDIO_SLIP	stdio via SLIP (mutiplex)

Definition at line 41 of file stdio_base.h.

Function Documentation

stdio_available()

int stdio_available

(

void

)

Get the number of bytes available for reading from stdio.

Warning

This function is only available if the implementation supports it and the stdio_available module is enabled.

Returns

number of available bytes

stdio_clear_stdin()

void stdio_clear_stdin

(

void

)

Clear the input buffer.

Note

Requires 'USEMODULE += stdin'

Warning

This function does only work if the stdio implementation supports it.

stdio_read()

ssize_t stdio_read	(	void *	buffer,
		size_t	max_len )

Read len bytes from the STDIN into buffer.

Parameters

[out]	buffer	buffer to read into
[in]	max_len	nr of bytes to read

Returns

nr of bytes read

Return values

<0

on error

stdio_rx_write()

int stdio_rx_write	(	const uint8_t *	buf,
		size_t	len )

Push received bytes into stdin.

This is the entry point stdio backends use to hand received data to stdin. It buffers the data for stdio_read and, when the stdio_notify module is used, invokes the registered notify callback (see stdio_set_notify).

Note

Safe to call from ISR context.

Parameters

[in]	buf	received bytes to push into stdin
[in]	len	number of bytes in buf

Returns

number of bytes pushed into stdin, which may be less than len if the stdin buffer was full

stdio_rx_write_one()

int stdio_rx_write_one

(

uint8_t

c

)

Push a single received byte into stdin.

This is the entry point stdio backends use to hand received data to stdin. It buffers the byte for stdio_read and, when the stdio_notify module is used, invokes the registered notify callback (see stdio_set_notify).

Note

Safe to call from ISR context.

Parameters

[in]

c

received byte to push into stdin

Return values

0	on success
-1	if the stdin buffer was full

stdio_set_notify()

void stdio_set_notify	(	stdio_notify_cb_t	cb,
		void *	arg )

Register a callback fired when data is available on stdin.

The callback is invoked by the stdio backend once new data has been pushed to stdin, in (ISR) context. It must therefore be ISR-safe and non-blocking. This allows a consumer to be woken by means other than a blocking stdio_read (e.g. thread flags), so it can also react to other events.

There can only be one notify callback registered at a time.

Note

Only available with the stdio_notify module.

Parameters

[in]	cb	callback to invoke, or NULL to disable
[in]	arg	argument passed to cb

stdio_write()

ssize_t stdio_write	(	const void *	buffer,
		size_t	len )

Write len bytes from buffer into STDOUT.

Note

Depending on the stdio backend(s) used, not all bytes might be written to stdout and accounted for if multiple backends are

Depending on the stdio backend(s) used and if multiple backends are active, it is possible that not all bytes will be written to stdout as not all backends support blocking writes.

Parameters

[in]	buffer	buffer to read from
[in]	len	nr of bytes to write

Returns

nr of bytes written

Return values

<0

on error

Variable Documentation

stdin_isrpipe

isrpipe_t stdin_isrpipe

extern

isrpipe for writing stdin input to

Deprecated

Use stdio_rx_write or stdio_rx_write_one. This isrpipe will become private and should not be used directly. Using this isrpipe directly will not work with the stdio_notify module. Will be removed after the 2027.01 release.