Blog of the Embedded Rust Working Group

The Path Towards Stable

2018-05-13

Cortex-M library development now possible on beta and the path towards stable embedded Rust

TL;DR

  • 1.27 = embedded (Cortex-M) library development on stable
  • 1.28 or 1.29 = embedded (Cortex-M) application development on stable
  • We are making breaking changes in the ecosystem in order to move towards development on the stable channel
  • If you are a crate maintainer / author, make sure you test your crates with the new versions of cortex-m (and similar) on the current beta release of Rust
  • If the latest version of a dependency doesn't compile on beta, file an issue and/or ping us on the #rust-embedded IRC channel
  • Thanks for your patience!

We are happy to announce that library development for the Cortex-M targets is now possible on the beta channel! :tada:

For example, to cross compile a library crate for the Cortex-M3 you would run these commands:

$ # switch to the beta channel
$ rustup default beta

$ # install the rust-std component (pre-compiled core) for the target
$ rustup target add thumbv7m-none-eabi

$ # get some source to build
$ cargo clone cortex-m --vers 0.5.0 && cd cortex-m

$ # then It Just Works
$ cargo build --target thumbv7m-none-eabi

What about embedded application development? There is just a single unstable feature that prevents us from building a no_std binary on stable: the panic_fmt lang item. This unstable feature will soon be removed in favor of the #[panic_implementation] feature (implementation PR), which is slated for stabilization in time for the edition release (we are hoping to stabilize it as early as 1.28 but we'll see).

Making the Cortex-M ecosystem work on stable

"no_std binaries are possible on stable" is very different from "my embedded application builds on stable". The later requires all the dependencies to also compile on stable. So we are starting to migrate the Cortex-M ecosystem to work on stable. All the crates listed below are now compiling on the beta channel.

Legend: crate-name - link to CHANGELOG - link to stabilization PR - ~removed unstable features~

There's a lot of breaking changes there but the most visible one is cortex-m-rt because it changes how applications are structured. Check the cortex-m-quickstart template for instructions on how to set up an embedded application using the latest versions of everything.

There are still a lot of crates that will need to be updated to work on beta. Among the more general purpose ones we have heapless and cortex-m-rtfm, which needs to be update to work with cortex-m-rt v0.5.0.

How you can help us

Try to compile your Cortex-M crate using the beta channel! If your crate is an application the build will certainly fail, but check if all the dependencies, excluding the panic handler crate, compile on beta. If any dependency doesn't compile on the beta channel let the author know, but first check if there's a new version of the crate that already compiles on the beta channel. And if you feel up to the task you could even send a PR to the dependency to make it compile on beta -- the list of stabilization PRs in the previous section may give you a clue on how to move the crate to beta.

If you are the author of a Cortex-M device crate, a crate generated using svd2rust, moving it to stable only requires regenerating it using svd2rust v0.13.0. Do note that the generation process has changed for the Cortex-M target; also make sure you bump the minor version when you publish a new version.

If you are the author of a driver crate or a HAL implementation, please update your crate to use v0.2.0 of embedded-hal and test that it builds on beta. Make sure you bump the minor version when you publish a new version of your crate -- bumping the version of the embedded-hal dependency is a breaking change (drivers that depend on embedded-hal v0.1.0 can't be used with HAL implementation crates that depend on embedded-hal v0.2.0).

If you are porting an application to the newest cortex-m-* crates you may hit these errors:

What does this all mean for you?

To those of you who have been doing embedded development on nightly: things will get much easier from now on. We have reduced the number of unstable features in core crates of the Cortex-M ecosystem to zero. Although you will have to continue to use nightly for application development you can expect zero breakage from these crates when updating the nightly compiler. There is one expected breakage coming soon though: panic_fmt will be removed as announced above. This will break the panic handler crates; however, the breakage will be isolated to those crates and the fix will consist of simply updating the dependency version.

To those of you who have been meaning to dive into embedded Rust development: we'll soon be done with our "embedded Rust on stable" tasks and we'll move our focus to documenting the embedded development process, tooling and ecosystem. The embedded Rust book will become the resource to get started on embedded Rust, but it doesn't quite exist right now.

What about architectures other than ARM Cortex-M?

The path carved for ARM Cortex-M can be followed by the other architectures (ARM Cortex-R, AVR, MSP430, RISCV, etc.). Each architecture presents its own extra set of challenges though:

This work is part of the embedded WG effort towards making embedded development possible on the stable channel. (We are almost done! :tada:)