Develop resources for Rust integration with RTOSs

[adamgreig]

Related to #1.

We won't block the book on this, but it would be great to have some examples to point at and documentation around integrating Rust with common RTOSs. We can collect links and resources in this issue, and add them to the interoperability chapter.

Suggestions for RTOSs to consider:

• FreeRTOS
• ChibiOS
• mbed
• TockOS
• Zephyr
• MyNewt
• ?

[thenewwazoo]

The main components to getting Rust working with an existing RTOS are, imo:

• building an RTOS as a library: this might be slightly out of scope, but if we assume a reasonably sophisticated audience, we can explain how static libraries are linked in and draw the conceptual relationship between a kernel-as-collection-of-functions (from the view of the Rust code)
• using bindgen to actually generate the Rust bindings: fairly straightforward with one pitfall: inline functions that exist only in header files. getting ChibiOS working required some editing for that reason
• writing a shim to turn C types into types useful to Rust: reasonably straightforward once you understand FFI types

I can get my ChibiOS repo cleaned up (it's rotted quite a bit) if we want something to point to. I've never used FreeRTOS in this way, but there are a few repos out there. I feel like my approach (a more "pure" one that only uses build.rs to build ChibiOS as a static lib, and then bindgen for bindings) is easier to understand than some of the more complicated approaches I've seen elsewhere, but comparisons may be educational.

[eddyp]

* using bindgen to actually generate the Rust bindings: fairly straightforward with one pitfall: inline functions that exist only in header files. getting ChibiOS working required some editing for that reason

* writing a shim to turn C types into types useful to Rust: reasonably straightforward once you understand FFI types

A similar issue to the inline functions are the "polymorphic" C APIs which, for reasons of size optimizations, rely on one of macros, inline functions and non-inlined functions to implement any given public APIs, depending on the OS configuration.

If the inline functions are difficult, but solvable, for macros, I would consider them extremely difficult to bind to, without maybe doing some analysis of the RTOS interface sources, before the preprocessor.

OTOH, I am thinking that for such cases, since typically the #define-s on which the particular choice of "backend implementation" are part of an application specific config files, it might make some sense to investigate generating some wrapper FFIs based on the static APIs and the configuration interface.

Still, I am unsure how we could make sure the Rust caller code of an RTOS API would be identified before the generation of the object files, so Rust bindings can be correctly generated for all the RTOS APIs implemented as macros.

[chrysn]

There is a working RIOT-OS integration library that can become a candidate for inclusion here once it's matured a bit further and gathered some reviews.

Build system integration is interesting there because a typical RIOT application receives quite some configuration in its Makefile, and the RIOT API changes subtly in response to that (additional fields in structs, presence of functions etc).

Static inline functions are a pain point as with other OSes.

[eddyp]

@chrysn I suppose RIOT has similar optimizations and macro abuse as the ones listed by me, right?

[chrysn]

I'd call none of them abuse, but there are some complex areas. Preprocessor functions are not so much used for a polymorphic C API but more for triggering various other optimizations (many of which, in my impression, would be moot if LTO were universally implemented, but AFAIR some of the targeted compilers can't do that), eg. around the conversion of times to ticks.

On the other hand, most workarounds I do are for static inline functions that are classic one-liners, either accessing a global variable or handing right off to a different function (eg. mutex_lock and mutex_trylock call to _mutex_lock with an additional boolean block parameter).

[eddyp]

To clarify, by "polymorphic API" I mean something similar to what you said, the API signature will look the same, but it is possible the types are defined differently, some function calls might be turned into function-like macros or inline functions.

All of these are problematic for any bindgen-like tool and have to be taken into account.

[AJGherardi]

Zephyr is another rtos that is getting popular rust support for it would be nice.

[Bashe]

My 2 cents:
Zephyr + MyNewt

[JOE1994]

This repo uses freertos-rust to run FreeRTOS tasks written in Rust.
By slightly modifying hardware-specific configs in the repo, I was able to run FreeRTOS on my stm32f407g-disc board.

[mash-graz]

rttrust is a [still incomplete] attempt to realize rust bindings for the rt-thread RTOS.

[d3zd3z]

I have just started playing with doing this on top of Zephyr. Basics of building aren't too difficult, so I started with log. There is a bit of a semantic mismatch between rust's logging and Zephyr's logging system, mostly because the Zephyr one is built around C-style format strings.

[mcscholtz]

In regards to Zephyr, this project looks really promising: https://github.com/tylerwhall/zephyr-rust

[svdHero]

Could you also consider ThreadX for the book, please?

Thanks a lot for all your work.

[jiahaoxiang2000]

The drone-os can be considered. You can find the repository here.

[wllenyj]

I think we should have a wrapper to bind the CMSIS-RTOS2 api.
The CMSIS-RTOS provides generic RTOS interfaces, and masks different rtos implementation details.