Crate riot_sys

source ·
Expand description

Bindings for RIOT system calls

This crate contains dynamically generated Rust FFI bindings to the RIOT Operating System.

Those bindings are inherently unsafe; it is recommended that their safe abstractions in the riot-wrappers crate are used in most applications.

For a newcomer’s starting point, see RIOT’s documentation on using it with Rust. This also contains installation instructions / depenendencies.

RIOT integration

Which functions and structs are present in this crate, and sometimes their details, inherently depends on the RIOT configuration this will be used with. For example, RIOT’s thread_t only has a member name if DEVHELP is set for a build, and its flags member is only present if the thread_flags module is in use.

All the relevant information – including the location of the actually used RIOT header files and flags influencing the ABI – is conveyed to riot-sys by passing on the compiler and the CFLAGS. This can either be done by passing in th epath to a “compile commads” file through the RIOT_COMPILE_COMMANDS environment variable (accompanied by a RIOT_USEMODULES, as that part of CFLAGS is missing from the compile commands), or alternatively by passing in the C compiler as RIOT_CC and the CFLAGS (both their CFLAGS_WITH_MACROS and the INCLUDES part from RIOT’s build system) in. When called from within RIOT’s build system, care must be taken to clear CC and CFLAGS, as these would be interpreted by Cargo (Rust’s build system) to refer to the host compiler and flags. The flags will be interpreted by libclang based tools; care must be taken to pass in flags suitable for clang and not for GCC.

These steps are automated in RIOT’s build system.

The RIOT_CC and RIOT_CFLAGS are made available to dependent crates through Cargo (as DEP_RIOT_SYS_CC etc); see riot-wrappers’s for an example. Similarly, custom markers are made available based on the presence of certain defines or features in RIOT as downstream crates require that information (typically to allow a crate to work across a wider range of RIOT versions); see the comments in for details.


Currently, only a subset of all the RIOT headers is processed; all the relevant header files are included in this crate’s riot-headers.h header file. If you need access to more RIOT APIs, more includes can be added there.


riot-sys is versioned using SemVer, and efforts are made to not make breaking changes even while in the 0.x phase. Note that as it passes on RIOT internals, any of the SemVer guarantees only hold when built on the same RIOT – once the underlying C code is changed, all bets are off. Users of riot-rs can introspect its markers (see to influence which symbols to use.


Some decisions of downstream crates need to depend on whether some feature is around in RIOT. For many things that’s best checked on module level, but some minor items have no module to mark the feature, and checking for versions by numers is not fine-grained enough, so it’s easiest to check for concrete strings in the bindgen output.

The of this crate contains a list of marker conditions. These lead to MARKER_foo=1 items emitted that are usable as DEP_RIOT_SYS_MARKER_foo=1 by crates that explicitly links = "riot-sys". They are stable in that they’ll only go away in a breaking riot-sys version; downstream users likely stop using them earlier because they sooner or later stop supporting old RIOT versions.

For example, in PR #17957, an argument to a particular handler function changed fundamentally; no amount of .into() would allow writing sensible abstractions. The marker coap_request_ctx_t was introduced, and is present automatically on all RIOT versions that have that particular pull request merged. Code in riot-wrappers uses conditions like #[cfg(marker_coap_request_ctx_t)] to decide whether to use the old or the new conventions.

These markers are currently checked against bindgen’s output, but could query any property that riot-sys has access to. The markers are defined in terms of some change having happened in RIOT; the way they are tested for can change. (In particular, when riot-sys stops supporting an older RIOT version, it can just always emit that marker).

Crates building on this should preferably not alter their own APIs depending on these, because that would add extra (and hard-to-track) dimensions to them. If they can, they should provide a unified view and degrade gracefully. (For example, riot-wrappers has the unit T of the phydat_unit_t in its enum, but converts it to the generic unspecified unit on RIOT versions that don’t have the T type yet – at least for as long as it supports 2022.01).

The types and constants of RIOT are translated in two forms: through bindgen (to be linked together), and through C2Rust (transpiled, to be inlined). This is necessary because neither can express the full set of useful RIOT APIs.

All bindgen types are reexported in the main module and exclusively public through there. The C2Rust types largely reside in the inline module, with some pub used into the root module as necessary or convenient.


pub use inline::bluetil_ad_add_flags;
pub use inline::coap_get_code_raw;
pub use inline::coap_get_total_hdr_len;
pub use inline::gnrc_netapi_dispatch_send;
pub use inline::gnrc_netif_ipv6_addrs_get;
pub use inline::gpio_is_valid;
pub use inline::irq_disable;
pub use inline::irq_is_enabled;
pub use inline::irq_is_in;
pub use inline::irq_restore;
pub use inline::mutex_trylock;
pub use inline::pid_is_valid;
pub use inline::shell_run_forever;
pub use inline::sock_udp_recv;
pub use inline::sock_udp_send;
pub use inline::thread_get;
pub use inline::thread_getpid;
pub use inline::thread_get_unchecked;
pub use inline::ztimer_spin;
pub use inline::AF_UNSPEC;
pub use inline::AF_UNIX;
pub use inline::AF_PACKET;
pub use inline::AF_INET;
pub use inline::AF_INET6;
pub use inline::macro_SOCK_IPV4_EP_ANY;
pub use inline::macro_SOCK_IPV6_EP_ANY;
pub use inline::macro_MUTEX_INIT;
pub use inline::macro_STATUS_NOT_FOUND;
pub use inline::macro_GPIO_PIN;
pub use inline::macro_LED0_ON;
pub use inline::macro_LED0_OFF;
pub use inline::macro_LED0_TOGGLE;
pub use inline::macro_LED1_ON;
pub use inline::macro_LED1_OFF;
pub use inline::macro_LED1_TOGGLE;
pub use inline::macro_LED2_ON;
pub use inline::macro_LED2_OFF;
pub use inline::macro_LED2_TOGGLE;
pub use inline::macro_LED3_ON;
pub use inline::macro_LED3_OFF;
pub use inline::macro_LED3_TOGGLE;
pub use inline::macro_LED4_ON;
pub use inline::macro_LED4_OFF;
pub use inline::macro_LED4_TOGGLE;
pub use inline::macro_LED5_ON;
pub use inline::macro_LED5_OFF;
pub use inline::macro_LED5_TOGGLE;
pub use inline::macro_LED6_ON;
pub use inline::macro_LED6_OFF;
pub use inline::macro_LED6_TOGGLE;
pub use inline::macro_LED7_ON;
pub use inline::macro_LED7_OFF;
pub use inline::macro_LED7_TOGGLE;


C2Rust transpiled header contents (static inline functions
Types used around and with the exported functions


@brief ACL_ACL [ACL] (Unspecified)
@brief FICR_INFO [INFO] (Device info)
@brief FICR_NFC [NFC] (Unspecified)
@brief FICR_TEMP [TEMP] (Registers storing factory TEMP module linearization coefficients)
@brief FICR_TRNG90B [TRNG90B] (NIST800-90B RNG calibration data)
@brief I2S_CONFIG [CONFIG] (Unspecified)
@brief I2S_PSEL [PSEL] (Unspecified)
@brief I2S_RXD [RXD] (Unspecified)
@brief I2S_RXTXD [RXTXD] (Unspecified)
@brief I2S_TXD [TXD] (Unspecified)
@brief MWU_EVENTS_PREGION [EVENTS_PREGION] (Peripheral events.)
@brief MWU_EVENTS_REGION [EVENTS_REGION] (Peripheral events.)
@brief MWU_PERREGION [PERREGION] (Unspecified)
@brief MWU_PREGION [PREGION] (Unspecified)
@brief MWU_REGION [REGION] (Unspecified)
@brief NFCT_RXD [RXD] (Unspecified)
@brief NFCT_TXD [TXD] (Unspecified)
@brief Accelerated Address Resolver (AAR)
@brief Access control lists (ACL)
@brief AES CCM Mode Encryption (CCM)
@brief Clock control (CLOCK)
@brief Comparator (COMP)
@brief ARM TrustZone CryptoCell register interface (CRYPTOCELL)
@brief AES ECB Mode Encryption (ECB)
@brief Event Generator Unit 0 (EGU0)
@brief Factory information configuration registers (FICR)
@brief FPU (FPU)
@brief GPIO Tasks and Events (GPIOTE)
@brief GPIO Port 1 (P0)
@brief Inter-IC Sound (I2S)
@brief Low Power Comparator (LPCOMP)
@brief Memory Watch Unit (MWU)
@brief NFC-A compatible radio (NFCT)
@brief Non Volatile Memory Controller (NVMC)
@brief Pulse Density Modulation (Digital Microphone) Interface (PDM)
@brief Power control (POWER)
@brief Programmable Peripheral Interconnect (PPI)
@brief Pulse width modulation unit 0 (PWM0)
@brief Quadrature Decoder (QDEC)
@brief External flash interface (QSPI)
@brief 2.4 GHz radio (RADIO)
@brief Random Number Generator (RNG)
@brief Real time counter 0 (RTC0)
@brief Successive approximation register (SAR) analog-to-digital converter (SAADC)
@brief Serial Peripheral Interface Master with EasyDMA 0 (SPIM0)
@brief SPI Slave 0 (SPIS0)
@brief Serial Peripheral Interface 0 (SPI0)
@brief Software interrupt 0 (SWI0)
@brief Temperature Sensor (TEMP)
@brief Timer/Counter 0 (TIMER0)
@brief I2C compatible Two-Wire Master Interface with EasyDMA 0 (TWIM0)
@brief I2C compatible Two-Wire Slave Interface with EasyDMA 0 (TWIS0)
@brief I2C compatible Two-Wire Interface 0 (TWI0)
@brief UART with EasyDMA 0 (UARTE0)
@brief Universal Asynchronous Receiver/Transmitter (UART0)
@brief User information configuration registers (UICR)
@brief Universal serial bus device (USBD)
@brief Watchdog Timer (WDT)
@brief PDM_PSEL [PSEL] (Unspecified)
@brief PDM_SAMPLE [SAMPLE] (Unspecified)
@brief POWER_RAM [RAM] (Unspecified)
@brief PPI_CH [CH] (PPI Channel)
@brief PPI_FORK [FORK] (Fork)
@brief PPI_TASKS_CHG [TASKS_CHG] (Channel group tasks)
@brief PWM_PSEL [PSEL] (Unspecified)
@brief PWM_SEQ [SEQ] (Unspecified)
@brief QDEC_PSEL [PSEL] (Unspecified)
@brief QSPI_ERASE [ERASE] (Unspecified)
@brief QSPI_PSEL [PSEL] (Unspecified)
@brief QSPI_READ [READ] (Unspecified)
@brief QSPI_WRITE [WRITE] (Unspecified)
@brief SAADC_CH [CH] (Unspecified)
@brief SAADC_EVENTS_CH [EVENTS_CH] (Peripheral events.)
@brief SPIM_IFTIMING [IFTIMING] (Unspecified)
@brief SPIM_PSEL [PSEL] (Unspecified)
@brief SPIM_RXD [RXD] (RXD EasyDMA channel)
@brief SPIM_TXD [TXD] (TXD EasyDMA channel)
@brief SPIS_PSEL [PSEL] (Unspecified)
@brief SPIS_RXD [RXD] (Unspecified)
@brief SPIS_TXD [TXD] (Unspecified)
@brief SPI_PSEL [PSEL] (Unspecified)
@brief TWIM_PSEL [PSEL] (Unspecified)
@brief TWIM_RXD [RXD] (RXD EasyDMA channel)
@brief TWIM_TXD [TXD] (TXD EasyDMA channel)
@brief TWIS_PSEL [PSEL] (Unspecified)
@brief TWIS_RXD [RXD] (RXD EasyDMA channel)
@brief TWIS_TXD [TXD] (TXD EasyDMA channel)
@brief TWI_PSEL [PSEL] (Unspecified)
@brief UARTE_PSEL [PSEL] (Unspecified)
@brief UARTE_RXD [RXD] (RXD EasyDMA channel)
@brief UARTE_TXD [TXD] (TXD EasyDMA channel)
@brief UART_PSEL [PSEL] (Unspecified)
@brief USBD_EPIN [EPIN] (Unspecified)
@brief USBD_EPOUT [EPOUT] (Unspecified)
@brief USBD_HALTED [HALTED] (Unspecified)
@brief USBD_ISOIN [ISOIN] (Unspecified)
@brief USBD_ISOOUT [ISOOUT] (Unspecified)
@brief USBD_SIZE [SIZE] (Unspecified)
@brief Type for CoAP resource subtrees
@brief Common IP-based transport layer end point
@brief @c thread_t holds thread’s context data.
Advertising parameters
@brief Connection descriptor
@brief Connection parameters
@brief Advertising report
@brief Discovery parameters
Represents a GAP-related event. When such an event occurs, the host notifies the application by passing an instance of this structure to an application-specified callback.
Represents a connection attempt. Valid for the following event types: o BLE_GAP_EVENT_CONNECT
Represents a terminated connection. Valid for the following event types: o BLE_GAP_EVENT_DISCONNECT
Represents a completed discovery procedure. Valid for the following event types: o BLE_GAP_EVENT_DISC_COMPLETE
Represents a completed advertise procedure. Valid for the following event types: o BLE_GAP_EVENT_ADV_COMPLETE
Represents an attempt to update a connection’s parameters. If the attempt was successful, the connection’s descriptor reflects the updated parameters.
Represents a peer’s request to update the connection parameters. This event is generated when a peer performs any of the following procedures: o L2CAP Connection Parameter Update Procedure o Link-Layer Connection Parameters Request Procedure
Represents a failed attempt to terminate an established connection. Valid for the following event types: o BLE_GAP_EVENT_TERM_FAILURE
Represents an attempt to change the encrypted state of a connection. If the attempt was successful, the connection descriptor reflects the updated encrypted state.
Represents a passkey query needed to complete a pairing procedure.
Represents a received ATT notification or indication.
Represents a transmitted ATT notification or indication, or a completed indication transaction.
Represents a state change in a peer’s subscription status. In this comment, the term “update” is used to refer to either a notification or an indication. This event is triggered by any of the following occurrences: o Peer enables or disables updates via a CCCD write. o Connection is about to be terminated and the peer is subscribed to updates. o Peer is now subscribed to updates after its state was restored from persistence. This happens when bonding is restored.
Represents a change in an L2CAP channel’s MTU.
Represents a change in peer’s identity. This is issued after successful pairing when Identity Address Information was received.
Represents a change of PHY. This is issue after successful change on PHY.
Event listener structure
@brief Extended discovery parameters
@brief Passkey query
Connection security state
@brief Connection parameters update parameters
Context passed to the registration callback; represents the GATT service, characteristic, or descriptor being registered.
Service; valid if op == BLE_GATT_REGISTER_OP_SVC.
Characteristic; valid if op == BLE_GATT_REGISTER_OP_CHR.
Descriptor; valid if op == BLE_GATT_REGISTER_OP_DSC.
@brief Bluetooth Host main configuration structure
@brief Used to report the result of a stop procedure.
Represents a L2CAP-related event. When such an event occurs, the host notifies the application by passing an instance of this structure to an application-specified callback.
Represents a connection attempt. Valid for the following event types: o BLE_L2CAP_EVENT_COC_CONNECTED
Represents a terminated connection. Valid for the following event types: o BLE_L2CAP_EVENT_COC_DISCONNECTED
Represents connection accept. Valid for the following event types: o BLE_L2CAP_EVENT_COC_ACCEPT
Represents received data. Valid for the following event types: o BLE_L2CAP_EVENT_COC_DATA_RECEIVED
Represents tx_unstalled data. Valid for the following event types: o BLE_L2CAP_EVENT_COC_TX_UNSTALLED
Represents reconfiguration done. Valid for the following event types: o BLE_L2CAP_EVENT_COC_RECONFIG_COMPLETED o BLE_L2CAP_EVENT_COC_PEER_RECONFIGURED
Used as a key for lookups of stored client characteristic configuration descriptors (CCCDs). This struct corresponds to the BLE_STORE_OBJ_TYPE_CCCD store object type.
Used as a key for lookups of security material. This struct corresponds to the following store object types: o BLE_STORE_OBJ_TYPE_OUR_SEC o BLE_STORE_OBJ_TYPE_PEER_SEC
Represents a write that failed due to storage exhaustion. Valid for the following event types: o BLE_STORE_EVENT_OVERFLOW
Represents the possibility that a scheduled write will fail due to storage exhaustion. Valid for the following event types: o BLE_STORE_EVENT_FULL
Represents a stored client characteristic configuration descriptor (CCCD). This struct corresponds to the BLE_STORE_OBJ_TYPE_CCCD store object type.
Represents stored security material. This struct corresponds to the following store object types: o BLE_STORE_OBJ_TYPE_OUR_SEC o BLE_STORE_OBJ_TYPE_PEER_SEC
16-bit UUID
32-bit UUID
128-bit UUID
Generic UUID type, to be used only as a pointer
@brief Struct used for returning the contents of a selected field
@brief Descriptor for a buffer containing advertising data
@brief circular integer buffer structure
@brief Block1 helper struct
@brief Blockwise request helper struct
@brief Blockwise transfer helper struct
@brief Raw CoAP PDU header structure
@brief Context information required to write a resource link
@brief CoAP option array entry
@brief CoAP PDU parsing context structure
@brief Type for CoAP resource entry
@name DHCPv6 unique identifier (DUID) definitions @see RFC 8415, section 11 @{ @brief DUID based on link-layer address plus time
@brief Ethernet header
@brief event structure
@brief Callback Event structure definition
@brief event queue structure
@brief Timeout Event structure
@brief Generic event
@brief Message box event definition.
@brief IPC-message event @extends evtimer_event_t
@brief Event timer
@brief A modular collection of resources for a server
@brief Memo for Observe registration and notifications
@brief Memo to handle a response for a request
@brief Extends request memo for resending a confirmable request.
@brief CoAP socket to handle multiple transport types
@brief Authoritative border router list entry view on NIB
@brief Forwarding table entry view on NIB
@brief Neighbor cache entry view on NIB
@brief Prefix list entry view on NIB
@brief Data structure to be send for setting (@ref GNRC_NETAPI_MSG_TYPE_SET) and getting (@ref GNRC_NETAPI_MSG_TYPE_GET) options
@brief Generic network interface header
@brief IPv6 component for @ref gnrc_netif_t
@see gnrc_netif_ops_t
@brief Representation of a network interface
@brief Entry to the @ref net_gnrc_netreg
@brief Callback + Context descriptor @note Only available with @ref net_gnrc_netapi_callbacks.
@brief Type to represent parts (either headers or payload) of a packet, called snips. @details The idea behind the packet snips is that they either can represent protocol-specific headers or payload. A packet can be comprised of multiple pktsnip_t elements.
@brief sock @ref net_gnrc_netreg info @internal
@brief Context for HMAC operations based on sha256
@brief I2C (TWI) configuration options
@brief Echo request and response message format. @extends icmpv6_hdr_t
@brief Destination unreachable message format. @extends icmpv6_hdr_t
@brief Parameter problem message format. @extends icmpv6_hdr_t
@brief Packet too big message format. @extends icmpv6_hdr_t
@brief Time exceeded message format. @extends icmpv6_hdr_t
@brief General ICMPv6 message format.
@brief iolist structure definition
@brief struct iovec anonymous declaration
@brief Fragment header definition
@brief IPv6 routing extension header.
@brief IPv6 extension headers.
@brief Data type to represent an IPv6 packet header
@brief List node structure
@brief Mailbox struct definition
@brief Describes a message object which can be sent between threads.
@brief MTD driver interface
@brief MTD device descriptor
@brief A cancellation structure for use with @ref mutex_lock_cancelable and @ref mutex_cancel
@brief Mutex structure. Must never be modified by the user.
@brief Cache container that holds a @p coap_pkt_t struct.
@brief Neighbor advertisement message format. @extends icmpv6_hdr_t
@brief Neighbor solicitation message format. @extends icmpv6_hdr_t
@brief MTU option format @extends ndp_opt_t
@brief Prefix information option format @extends ndp_opt_t
@brief Recursive DNS server option format with payload @extends ndp_opt_rdnss_t @details Auxiliary struct that contains a zero-length array as convenience pointer to the addresses. Only for use in C, invalid in ISO-C++.
@brief Recursive DNS server option format without payload @extends ndp_opt_t
@brief Redirected header option format @extends ndp_opt_t
@brief Route information option format @extends ndp_opt_t
@brief General NDP option format @see RFC 4861, section 4.6
@brief Redirect message format. @extends icmpv6_hdr_t
@brief Router advertisement message format. @extends icmpv6_hdr_t
@brief Router solicitation message format. @extends icmpv6_hdr_t
@brief Structure to hold driver state
@brief Structure to hold driver interface -> function mapping
@brief Received frame status information for most radios
@brief Network interface descriptor.
Chained memory buffer.
A packet header structure that preceeds the mbuf packet headers.
A mbuf pool from which to allocate mbufs. This contains a pointer to the os mempool to allocate mbufs out of, the total number of elements in the pool, and the amount of “user” data in a non-packet header mbuf. The total pool size, in bytes, should be: os_mbuf_count * (omp_databuf_len + sizeof(struct os_mbuf))
A memory block structure. This simply contains a pointer to the free list chain and is only used when the block is on the free list. When the block has been removed from the free list the entire memory block is usable by the caller.
Memory pool
Information describing a memory pool, used to return OS information to the management layer.
Structure representing a queue of mbufs.
@brief Generic data structure for expressing physical values
@brief Quadrature decoder configuration struct
@brief Ringbuffer. @details Non thread-safe FIFO ringbuffer implementation around a char array.
@brief Mutex structure. Must never be modified by the user.
@brief Definition of the RIOT actuator/sensor interface
@brief SAUL registry entry
@brief Additional data to collect for each entry
@brief A Semaphore.
@brief Structure to hold the SHA-2XX context.
@brief sha256-chain indexed element
@brief A single command in the list of the supported commands. @details The list of commands is NULL terminated, i.e. the last element must be { NULL, NULL, NULL }.
@brief Asynchronous context for @ref net_sock_async_event
@brief Event definition for context scope
@brief Raw IP sock type @internal
@brief Auxiliary data provided when receiving using an IP sock object
@brief Auxiliary data provided when sending using an IP sock object
@brief Abstract IP end point and end point for a raw IP sock object
@brief Transmission control block of GNRC TCP.
@brief Transmission control block queue.
@brief UDP sock type @internal
@brief Auxiliary data provided when receiving using an UDP sock object
@brief Auxiliary data provided when sending using an UDP sock object
@brief SPI configuration values
@brief SPI gpio mode
@brief File system information
@brief Timer configuration options
@brief A timex timestamp
@brief Structure for UART configuration data
@brief UDP header
@brief Unaligned access helper struct (uint16_t version)
@brief Unaligned access helper struct (uint32_t version)
@brief Unaligned access helper struct (uint64_t version)
@brief Internal representation of a file system directory entry
@brief Operations on open directories
@brief User facing directory entry
@brief Operations on open files
@brief Operations on mounted file systems
@brief A file system driver
@brief Information about an open file
@brief A mounted file system
@brief Minimum information for each timer
@brief ztimer device structure
@brief ztimer backend method structure
@brief ztimer periodic structure
@brief ztimer structure


16-bit UUID (BT SIG assigned)
32-bit UUID (BT SIG assigned)
128-bit UUID
< blocking mode
< insufficient memory to write field
< entry not found
< everything went as expected
@brief neighbor state change
@brief route notification
@brief reactive routing query
< Use some automatic bootstrapping (e.g. SLAAC with IPv6)
< Use DHCP(v6)
< no configuration