The Path Towards Stable2018-05-13
Cortex-M library development now possible on beta and the path towards stable embedded Rust
- 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
betarelease 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.
crate-name - link to CHANGELOG - link to stabilization PR - ~removed unstable features~
cortex-m-rt- CHANGELOG - PR - ~asm!~ ~core_intrinsics~ ~global_asm!~ ~lang_items~ ~linkage~ ~naked_functions~ ~used~
svd2rust(output of) - CHANGELOG - PR - ~const_fn~ ~global_asm!~ ~try_from~ ~use_extern_macros~ ~used~
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
cortex-m-rtfm, which needs to be update to work with
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
If you are the author of a driver crate or a HAL implementation, please update your crate to use
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
If you are porting an application to the newest
cortex-m-* crates you may hit these errors:
- "error: requires
startlang_item" on binary crates. You need to switch from the standard
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
const fnis not a stable feature so it's not used in the API by default. The
"const-fn"feature to opt into this unstable feature and expose
constfunctions 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_stdtarget 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:)