Loading...
Searching...
No Matches
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 provider struct
Definition stdio_base.h:59
#define XFA_CONST(type, xfa_name, prio)
Define variable in read-only cross-file array.
Definition xfa.h:159

stdio implementation methods

Parameters
_typestdio provider type, for identification
_openattach / init function
_closeclose / disable function
_writewrite 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]bufferbuffer to read into
[in]max_lennr 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]bufferbuffer to read from
[in]lennr of bytes to write
Returns
nr of bytes written
<0 on error