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.

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 struct _thread 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 – is contained in the RIOT environment variables CFLAGS_WITH_MACROS and INCLUDES; both need to be passed in to the Rust build system as a RIOT_CFLAGS environment variable.

In addition, riot-sys also needs to know the C compiler to properly expand the header files before transpilation; that information is passed in RIOT_CC.

When using riot-sys, it is usually easiest to run from a target within the Make system like this:

target/thumbv7m-none-eabi/debug/libmy_app.a: always
	CC= CFLAGS= CPPFLAGS= RIOT_CC="${CC}" RIOT_CFLAGS="$(CFLAGS_WITH_MACROS) $(INCLUDES)" cargo build --target thumbv7m-none-eabi

.PHONY: always

(CFLAGS etc. need to be cleared, for otherwise Cargo would assume those are host flags.)

The RIOT_CC and RIOT_CFLAGS are made available to dependent modules through Cargo; see riot-wrappers’s build.sh for an example.

As an alternative to passing RIOT_CFLAGS and RIOT_CC, the path to a compile-commands.json file can be passed in RIOT_COMPILE_COMMANDS_JSON, with a RIOT_USEMODULES to go with it containing the list of used modules. The advantage of this approach is that on the RIOT side, LLVM-compativble CFLAGS are produced immaterial of which C compiler is used. Even when this alternative is used, the extracted CC and CFLAGS are still passed down to dependent crates as they were before. (The passed down CC will just always be clang).


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.

External build dependencies

This crate’s operation depends on C2Rust being installed. As right now some of the required fixes to C2Rust are not merged upstream yet, (and as it requires a particular nightly version), it should be installed like this:

$ git clone https://github.com/chrysn-pull-requests/c2rust/ -b for-riot
$ cd c2rust
$ rustup install nightly-2019-12-05
$ rustup component add --toolchain nightly-2019-12-05 rustfmt rustc-dev
$ cargo +nightly-2019-12-05 install --locked --debug --path c2rust

The main contents of this crate (ie. everything not in a module) is generated by bindgen.

Unlike the inline module (which contains the C2Rust transpilate), it is not moved into a dedicated linked module and reexported (in analogy to the inline), for that’d need explicit pub use linked::mutex_t etc for every type that’s present in both and thus not imported for either. As long as this is inlined here, linked types (which are predominantly used so far) take precedence automatically.


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::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 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 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 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 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 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 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 xtimer timer structure

@brief xtimer timestamp (32 bit)

@brief xtimer timestamp (64 bit)

@brief Minimum information for each timer

@brief ztimer device structure

@brief ztimer backend method structure

@brief ztimer periodic structure

@brief ztimer structure


< internetwork address family: UDP, TCP, etc.

< internetwork address family with IPv6: UDP, TCP, etc.

< maximum number of address families on this system

< packet family

< local to host (pipes, portals) address family.

< unspecified address family

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