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

announcements
1

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:

  • "error: requires start lang_item" on binary crates. You need to switch from the standard main
    interface to #![no_main] + entry!. Use the examples in the quickstart template as a
    reference.
  • "error[E0015]: calls in statics are limited to constant functions, tuple structs and tuple
    variants". const fn is not a stable feature so it's not used in the API by default. The
    cortex-m provides a "const-fn" feature to opt into this unstable feature and expose const
    functions in the API; other dependencies should / probably provide a similar feature.

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:

  • MSP430 being the second oldest embedded / no_std target is the closest one to make it to stable
    (as a tier 2 target) by the edition release. The main blocker is that extern "msp430-interrupt"
    is not available on stable but I think that may be possible to work around using external C /
    assembly files + FFI.

  • Both AVR and RISCV are blocked from being included in the Rust compiler due to either the
    immaturity of the LLVM backend or LLVM backend bugs. Not many (embedded) Rust developers can also
    hack LLVM backends so we are short handed on the AVR front; OTOH, the RISCV is being actively
    developed by third parties so it's probably just a matter of time before we add it to rustc.

  • ARM Cortex-R LLVM backend is probably in good shape due to the similarities between its
    instruction set and the ARM Cortex-M instruction set, so adding the target to the compiler should
    be straightforward. However, the crate ecosystem is nonexistent at this point so there's a lot of
    work to be done on that front.

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

39 Likes
2

Awesome! Very exciting. Also, does this mean we'll have no_std on stable now (in 1.28 or 1.29)? I remember asking @steveklabnik about that ages ago and it seemed like there were some design issues that needed sorted out by the core guys first.

3

Once #[panic_implementation] is stabilized it will be possible to build #![no_std] binaries that use #![no_main] (this is way the program doesn't require the start / termination lang items which are unstable). The Cortex-M ecosystem is already using this approach as of cortex-m-rt v0.5.x.

2 Likes
4

Really excited to hear RISCV support is still being worked on. I am sadly not an expert in LLVM backends, but if there's any way to help or test, I'd love to pitch in.

5

Hello I'm working on CI things for Embedded rust in stable with James Munns and Vaishali Thakkar. (Increasing Rust's Reach - Embedded Project 2018)

I ran the following commands and it failed.

./x.py test --target thumbv7m-none-eabi src/tests/ui

What kind of tests are supposed to work in the current status?

Thanks in advance!