Master Embedded Development with Rust and no_std

Based mostly on my expertise with range-set-blaze, a knowledge construction venture, listed below are the selections I like to recommend, described one by one. To keep away from wishy-washiness, I’ll categorical them as guidelines.

Earlier than porting your Rust code to an embedded atmosphere, guarantee it runs efficiently in WASM WASI and WASM in the Browser. These environments expose points associated to shifting away from the usual library and impose constraints like these of embedded techniques. By addressing these challenges early, you’ll be nearer to working your venture on embedded gadgets.

Run the next instructions to substantiate that your code works in each WASM WASI and WASM within the Browser:

cargo check --target wasm32-wasip1
cargo check --target wasm32-unknown-unknown

If the checks fail or don’t run, revisit the steps from the sooner articles on this collection: WASM WASI and WASM in the Browser.

The WASM WASI article additionally supplies essential background on understanding Rust targets (Rule 2), conditional compilation (Rule 4), and Cargo options (Rule 6).

When you’ve fulfilled these conditions, the subsequent step is to see how (and if) we will get our dependencies engaged on embedded techniques.

To test in case your dependencies are suitable with an embedded atmosphere, compile your venture for an embedded goal. I like to recommend utilizing the thumbv7m-none-eabi goal:

• thumbv7m — Represents the ARM Cortex-M3 microcontroller, a preferred household of embedded processors.
• none — Signifies that there is no such thing as a working system (OS) out there. In Rust, this usually means we will’t depend on the usual library (std), so we use no_std. Recall that the usual library supplies core performance like Vec, String, file enter/output, networking, and time.
• eabi — Embedded Software Binary Interface, a typical defining calling conventions, information varieties, and binary structure for embedded executables.

Since most embedded processors share the no_std constraint, guaranteeing compatibility with this goal helps guarantee compatibility with different embedded targets.

Set up the goal and test your venture:

rustup goal add thumbv7m-none-eabi
cargo test --target thumbv7m-none-eabi

Once I did this on range-set-blaze, I encountered errors complaining about dependencies, resembling:

This reveals that my venture is dependent upon num-traits, which is dependent upon both, in the end relying on std.

The error messages may be complicated. To raised perceive the state of affairs, run this cargo tree command:

cargo tree --edges no-dev --format "{p} {f}"

It shows a recursive listing of your venture’s dependencies and their energetic Cargo options. For instance:

range-set-blaze v0.1.6 (C:deldirbranchesrustconf24.nostd) 
├── gen_ops v0.3.0
├── itertools v0.13.0 default,use_alloc,use_std
│   └── both v1.12.0 use_std
├── num-integer v0.1.46 default,std
│   └── num-traits v0.2.19 default,i128,std
│       [build-dependencies]
│       └── autocfg v1.3.0
└── num-traits v0.2.19 default,i128,std (*)

We see a number of occurrences of Cargo options named use_std and std, strongly suggesting that:

• These Cargo options require the usual library.
• We are able to flip these Cargo options off.

Utilizing the methods defined within the first article, Rule 6, we disable the use_std and std Cargo options. Recall that Cargo options are additive and have defaults. To show off the default options, we use default-features = false. We then allow the Cargo options we need to maintain by specifying, for instance, options = ["use_alloc"]. The Cargo.toml now reads:

[dependencies]
gen_ops = "0.3.0"
itertools = { model = "0.13.0", options=["use_alloc"], default-features = false }
num-integer = { model = "0.1.46", default-features = false }
num-traits = { model = "0.2.19", options=["i128"], default-features = false }

Turning off Cargo options won’t at all times be sufficient to make your dependencies no_std-compatible.

For instance, the favored thiserror crate introduces std into your code and affords no Cargo characteristic to disable it. Nevertheless, the group has created no_std options. You could find these options by looking, for instance, https://crates.io/search?q=thiserror+no_std.

Within the case of range-set-blaze, an issue remained associated to crate gen_ops — an exquisite crate for conveniently defining operators resembling + and &. The crate used std however didn’t have to. I recognized the required one-line change (utilizing the strategies we’ll cowl in Rule 3) and submitted a pull request. The maintainer accepted it, and so they launched an up to date model: 0.4.0.

Typically, our venture can’t disable std as a result of we want capabilities like file entry when working on a full working system. On embedded techniques, nevertheless, we’re prepared—and certainly should—hand over such capabilities. In Rule 4, we’ll see how you can make std utilization non-compulsory by introducing our personal Cargo options.

Utilizing these strategies mounted all of the dependency errors in range-set-blaze. Nevertheless, resolving these errors revealed 281 errors in the principle code. Progress!

On the prime of your venture’s lib.rs (or principal.rs) add:

#![no_std]
extern crate alloc;

This implies we gained’t use the usual library, however we’ll nonetheless allocate reminiscence. For range-set-blaze, this alteration lowered the error depend from 281 to 52.

Most of the remaining errors are because of utilizing objects in std which might be out there in core or alloc. Since a lot of std is only a re-export of core and alloc, we will resolve many errors by switching std references to core or alloc. This enables us to maintain the important performance with out counting on the usual library.

For instance, we get an error for every of those traces:

use std::cmp::max;
use std::cmp::Ordering;
use std::collections::BTreeMap;

Altering std:: to both core:: or (if reminiscence associated) alloc:: fixes the errors:

use core::cmp::max;
use core::cmp::Ordering;
use alloc::collections::BTreeMap;

Some capabilities, resembling file entry, are std-only—that’s, they’re outlined outdoors of core and alloc. Luckily, for range-set-blaze, switching to core and alloc resolved all 52 errors in the principle code. Nevertheless, this repair revealed 89 errors in its check code. Once more, progress!

We’ll tackle errors within the check code in Rule 5, however first, let’s work out what to do if we want capabilities like file entry when working on a full working system.

If we want two variations of our code — one for working on a full working system and one for embedded techniques — we will use Cargo options (see Rule 6 within the first article). For instance, let’s outline a characteristic known as foo, which would be the default. We’ll embody the perform demo_read_ranges_from_file solely when foo is enabled.

In Cargo.toml (preliminary):

[features]
default = ["foo"]
foo = []

In lib.rs (preliminary):

#![no_std]
extern crate alloc;
// ...
#[cfg(feature = "foo")]
pub fn demo_read_ranges_from_file<P, T>(path: P) -> std::io::Consequence<RangeSetBlaze<T>>
the place
P: AsRef<std::path::Path>,
T: FromStr + Integer,
{
todo!("This perform is just not but applied.");
}

This says to outline perform demo_read_ranges_from_file solely when Cargo characteristic foo is enabled. We are able to now test numerous variations of our code:

cargo test # permits "foo", the default Cargo options
cargo test --features foo # additionally permits "foo"
cargo test --no-default-features # permits nothing

Now let’s give our Cargo characteristic a extra significant identify by renaming foo to std. Our Cargo.toml (intermediate) now seems to be like:

[features]
default = ["std"]
std = []

In our lib.rs, we add these traces close to the highest to herald the std library when the std Cargo characteristic is enabled:

#[cfg(feature = "std")]
extern crate std;

So, lib.rs (closing) seems to be like this:

#![no_std]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;
// ...
#[cfg(feature = "std")]
pub fn demo_read_ranges_from_file<P, T>(path: P) -> std::io::Consequence<RangeSetBlaze<T>>
the place
P: AsRef<std::path::Path>,
T: FromStr + Integer,
{
todo!("This perform is just not but applied.");
}

We’d wish to make yet another change to our Cargo.toml. We wish our new Cargo characteristic to manage dependencies and their options. Right here is the ensuing Cargo.toml (closing):

[features]
default = ["std"]
std = ["itertools/use_std", "num-traits/std", "num-integer/std"]
[dependencies]
itertools = { model = "0.13.0", options = ["use_alloc"], default-features = false }
num-integer = { model = "0.1.46", default-features = false }
num-traits = { model = "0.2.19", options = ["i128"], default-features = false }
gen_ops = "0.4.0"

Apart: For those who’re confused by the Cargo.toml format for specifying dependencies and options, see my current article: Nine Rust Cargo.toml Wats and Wat Nots: Master Cargo.toml formatting rules and avoid frustration in In direction of Information Science.

To test that your venture compiles each with the usual library (std) and with out, use the next instructions:

cargo test # std
cargo test --no-default-features # no_std

With cargo test working, you’d suppose that cargo check could be straight ahead. Sadly, it’s not. We’ll have a look at that subsequent.

After we compile our venture with --no-default-features, it operates in a no_std atmosphere. Nevertheless, Rust’s testing framework at all times contains the usual library, even in a no_std venture. It is because cargo check requires std; for instance, the #[test] attribute and the check harness itself are outlined in the usual library.

Because of this, working:

# DOES NOT TEST `no_std`
cargo check --no-default-features

doesn’t truly check the no_std model of your code. Features from std which might be unavailable in a real no_std atmosphere will nonetheless be accessible throughout testing. For example, the next check will compile and run efficiently with --no-default-features, regardless that it makes use of std::fs:

#[test]
fn test_read_file_metadata() {
let metadata = std::fs::metadata("./").unwrap();
assert!(metadata.is_dir());
}

Moreover, when testing in std mode, you might want so as to add specific imports for options from the usual library. It is because, regardless that std is out there throughout testing, your venture remains to be compiled as #![no_std], which means the usual prelude is just not mechanically in scope. For instance, you’ll typically want the next imports in your check code:

#![cfg(test)]
use std::prelude::v1::*;
use std::{format, print, println, vec};

These imports carry within the vital utilities from the usual library in order that they’re out there throughout testing.

To genuinely check your code with out the usual library, you’ll want to make use of various strategies that don’t depend on cargo check. We’ll discover how you can run no_std checks within the subsequent rule.

You’ll be able to’t run your common checks in an embedded atmosphere. Nevertheless, you can — and may — run a minimum of one embedded check. My philosophy is that even a single check is infinitely higher than none. Since “if it compiles, it really works” is mostly true for no_std tasks, one (or a number of) well-chosen check may be fairly efficient.

To run this check, we use QEMU (Fast Emulator, pronounced “cue-em-you”), which permits us to emulate thumbv7m-none-eabi code on our principal working system (Linux, Home windows, or macOS).

Set up QEMU.

See the QEMU download page for full info:

Linux/WSL

• Ubuntu: sudo apt-get set up qemu-system
• Arch: sudo pacman -S qemu-system-arm
• Fedora: sudo dnf set up qemu-system-arm

Home windows

• Technique 1: https://qemu.weilnetz.de/w64. Run the installer (inform Home windows that it’s OK). Add "C:Program Filesqemu" to your path.
• Technique 2: Set up MSYS2 from https://www.msys2.org/. Open MSYS2 UCRT64 terminal. pacman -S mingw-w64-x86_64-qemu. Add C:msys64mingw64bin to your path.

Mac

• brew set up qemu or sudo port set up qemu

Check set up with:

qemu-system-arm --version

Create an embedded subproject.

Create a subproject for the embedded checks:

cargo new checks/embedded

This command generates a brand new subproject, together with the configuration file at checks/embedded/Cargo.toml.

Apart: This command additionally modifies your top-level Cargo.toml so as to add the subproject to your workspace. In Rust, a workspace is a group of associated packages outlined within the [workspace] part of the top-level Cargo.toml. All packages within the workspace share a single Cargo.lock file, guaranteeing constant dependency variations throughout the complete workspace.

Edit checks/embedded/Cargo.toml to appear like this, however substitute "range-set-blaze" with the identify of your top-level venture:

[package]
identify = "embedded"
model = "0.1.0"
version = "2021"
[dependencies]
alloc-cortex-m = "0.4.4"
cortex-m = "0.7.7"
cortex-m-rt = "0.7.3"
cortex-m-semihosting = "0.5.0"
panic-halt = "0.2.0"
# Change to seek advice from your top-level venture
range-set-blaze = { path = "../..", default-features = false }

Replace the check code.

Exchange the contents of checks/embedded/src/principal.rs with:

// Based mostly on https://github.com/rust-embedded/cortex-m-quickstart/blob/grasp/examples/allocator.rs
// and https://github.com/rust-lang/rust/points/51540
#![feature(alloc_error_handler)]
#![no_main]
#![no_std]
extern crate alloc;
use alloc::string::ToString;
use alloc_cortex_m::CortexMHeap;
use core::{alloc::Structure, iter::FromIterator};
use cortex_m::asm;
use cortex_m_rt::entry;
use cortex_m_semihosting::{debug, hprintln};
use panic_halt as _;
#[global_allocator]
static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
const HEAP_SIZE: usize = 1024; // in bytes
#[alloc_error_handler]
fn alloc_error(_layout: Structure) -> ! {
asm::bkpt();
loop {}
}
#[entry]
fn principal() -> ! {
unsafe { ALLOCATOR.init(cortex_m_rt::heap_start() as usize, HEAP_SIZE) }
// Check(s) goes right here. Run solely beneath emulation
use range_set_blaze::RangeSetBlaze;
let range_set_blaze = RangeSetBlaze::from_iter([100, 103, 101, 102, -3, -4]);
hprintln!("{:?}", range_set_blaze.to_string());
if range_set_blaze.to_string() != "-4..=-3, 100..=103" {
debug::exit(debug::EXIT_FAILURE);
}
debug::exit(debug::EXIT_SUCCESS);
loop {}
}

Most of this principal.rs code is embedded system boilerplate. The precise check code is:

use range_set_blaze::RangeSetBlaze;
let range_set_blaze = RangeSetBlaze::from_iter([100, 103, 101, 102, -3, -4]);
hprintln!("{:?}", range_set_blaze.to_string());
if range_set_blaze.to_string() != "-4..=-3, 100..=103" {
debug::exit(debug::EXIT_FAILURE);
}

If the check fails, it returns EXIT_FAILURE; in any other case, it returns EXIT_SUCCESS. We use the hprintln! macro to print messages to the console throughout emulation. Since that is an embedded system, the code ends in an infinite loop to run constantly.

Add supporting information.

Earlier than you possibly can run the check, you have to add two information to the subproject: construct.rs and reminiscence.x from the Cortex-M quickstart repository:

Linux/WSL/macOS

cd checks/embedded
wget https://uncooked.githubusercontent.com/rust-embedded/cortex-m-quickstart/grasp/construct.rs
wget https://uncooked.githubusercontent.com/rust-embedded/cortex-m-quickstart/grasp/reminiscence.

Home windows (Powershell)

cd checks/embedded
Invoke-WebRequest -Uri 'https://uncooked.githubusercontent.com/rust-embedded/cortex-m-quickstart/grasp/construct.rs' -OutFile 'construct.rs'
Invoke-WebRequest -Uri 'https://uncooked.githubusercontent.com/rust-embedded/cortex-m-quickstart/grasp/reminiscence.x' -OutFile 'reminiscence.x'

Additionally, create a checks/embedded/.cargo/config.toml with the next content material:

[target.thumbv7m-none-eabi]
runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config allow=on,goal=native -kernel"
[build]
goal = "thumbv7m-none-eabi"

This configuration instructs Cargo to make use of QEMU to run the embedded code and units thumbv7m-none-eabi because the default goal for the subproject.

Run the check.

Run the check with cargo run (not cargo check):

# Setup
# Make this subproject 'nightly' to assist #![feature(alloc_error_handler)]
rustup override set nightly
rustup goal add thumbv7m-none-eabi
# If wanted, cd checks/embedded
cargo run

You must see log messages, and the method ought to exit with out error. In my case, I see: "-4..=-3, 100..=103".

These steps could seem to be a big quantity of labor simply to run one (or a number of) checks. Nevertheless, it’s primarily a one-time effort involving largely copy and paste. Moreover, it permits working checks in a CI atmosphere (see Rule 9). The choice — claiming that the code works in a no_std atmosphere with out ever truly working it in no_std—dangers overlooking important points.

The subsequent rule is way less complicated.

As soon as your package deal compiles and passes the extra embedded check, you might need to publish it to crates.io, Rust’s package deal registry. To let others know that it’s suitable with WASM and no_std, add the next key phrases and classes to your Cargo.toml file:

[package]
# ... 
classes = ["no-std", "wasm", "embedded"] # + others particular to your package deal
key phrases = ["no_std", "wasm"] # + others particular to your package deal

Observe that for classes, we use a hyphen in no-std. For key phrases, no_std (with an underscore) is extra common than no-std. Your package deal can have a most of 5 key phrases and 5 classes.

Here’s a listing of categories and keywords of attainable curiosity, together with the variety of crates utilizing every time period:

Good classes and key phrases will assist individuals discover your package deal, however the system is casual. There’s no mechanism to test whether or not your classes and key phrases are correct, nor are you required to supply them.

Subsequent, we’ll discover one of the vital restricted environments you’re prone to encounter.

My venture, range-set-blaze, implements a dynamic information construction that requires reminiscence allocation from the heap (by way of alloc). However what in case your venture does not want dynamic reminiscence allocation? In that case, it might probably run in much more restricted embedded environments—particularly these the place all reminiscence is preallocated when this system is loaded.

The explanations to keep away from alloc in case you can:

• Fully deterministic reminiscence utilization
• Lowered threat of runtime failures (typically attributable to reminiscence fragmentation)
• Decrease energy consumption

There are crates out there that may typically show you how to substitute dynamic information constructions like Vec, String, and HashMap. These options usually require you to specify a most measurement. The desk under reveals some common crates for this function:

I like to recommend the heapless crate as a result of it supplies a group of knowledge constructions that work effectively collectively.

Right here is an instance of code — utilizing heapless — associated to an LED show. This code creates a mapping from a byte to a listing of integers. We restrict the variety of objects within the map and the size of the integer listing to DIGIT_COUNT (on this case, 4).

use heapless::{LinearMap, Vec};
// …
let mut map: LinearMap<u8, Vec<usize, DIGIT_COUNT>, DIGIT_COUNT> = LinearMap::new();
// …
let mut vec = Vec::default();
vec.push(index).unwrap();
map.insert(*byte, vec).unwrap(); // truly copies

Full particulars about making a no_alloc venture are past my expertise. Nevertheless, step one is to take away this line (added in Rule 3) out of your lib.rs or principal.rs:

extern crate alloc; // take away this

Your venture is now compiling to no_std and passing a minimum of one embedded-specific check. Are you performed? Not fairly. As I stated within the earlier two articles:

If it’s not in CI, it doesn’t exist.

Recall that steady integration (CI) is a system that may mechanically run checks each time you replace your code. I take advantage of GitHub Actions as my CI platform. Right here’s the configuration I added to .github/workflows/ci.yml to check my venture on embedded platforms:

test_thumbv7m_none_eabi:
identify: Setup and Test Embedded
runs-on: ubuntu-latest
steps:
- identify: Checkout
makes use of: actions/checkout@v4
- identify: Arrange Rust
makes use of: dtolnay/rust-toolchain@grasp
with:
toolchain: secure
goal: thumbv7m-none-eabi
- identify: Set up test secure and nightly
run: |
cargo test --target thumbv7m-none-eabi --no-default-features
rustup override set nightly
rustup goal add thumbv7m-none-eabi
cargo test --target thumbv7m-none-eabi --no-default-features
sudo apt-get replace && sudo apt-get set up qemu qemu-system-arm
- identify: Check Embedded (in nightly)
timeout-minutes: 1
run: |
cd checks/embedded
cargo run

By testing embedded and no_std with CI, I can ensure that my code will proceed to assist embedded platforms sooner or later.