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 can are shown as mdoules in the list below.

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

USEMODULE += stdio_cdc_acm

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

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
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 stdio uart 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 151 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.

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	tdio 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 stdio uart into buffer

Parameters

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

Returns

nr of bytes read

<0 on error

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 active, as not all stdout backends will do a blocking write.

Parameters

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

Returns

nr of bytes written

<0 on error