An application can be written in Rust. It is a
no_std crate, built by cargo as a static library and linked into the image
along with PebbleOS, on every board.
rustup. The toolchain is pinned by
rust-toolchain.toml at the root of the checkout, which rustup installs
with the targets the boards need the first time cargo runs.
bindgen 0.71 or later, which generates the bindings to the C API. CI uses 0.73.2:
cargo install bindgen-cli --locked --version 0.73.2
It loads libclang: Xcode’s command line tools have it on macOS,
libclang-dev on Ubuntu and clang-devel on Fedora.
samples/rust/hello_world is the smallest one:
samples/rust/hello_world/
CMakeLists.txt
Cargo.toml
prj.conf
src/lib.rs
cmake_minimum_required(VERSION 3.20)
find_package(PebbleOS REQUIRED HINTS $ENV{PEBBLEOS_BASE})
project(hello_world)
pbl_rust_app()
[package]
name = "hello_world"
version = "0.1.0"
edition = "2024"
license = "Apache-2.0"
publish = false
[lib]
crate-type = ["staticlib"]
[dependencies]
pebbleos = { path = "../../../rust/pebbleos" }
#![no_std]
use pebbleos::println;
#[pebbleos::main]
fn main() {
println!("Hello World! {}", pebbleos::kconfig::BOARD);
}
pbl_rust_app() builds the crate next to CMakeLists.txt.
#[pebbleos::main] marks the function the kernel runs as main(). It is
configured, built and run as any other application:
pbl configure --board qemu_emery samples/rust/hello_world
pbl build
pbl run
An application is a crate of its own, the samples too: the cargo workspace
at the root of the checkout only has the crates of PebbleOS. cargo writes
the application’s Cargo.lock next to its Cargo.toml. The build sets the
profile, so an application needs none.
Crate |
Contents |
|---|---|
|
The C API as bindgen makes it: unsafe functions, C structs, and every Kconfig symbol as a |
|
|
|
The API for applications, safe and in the language’s terms: |
main() returns nothing or a pebbleos::Result, whose error, an Errno,
is printed and returned as a negative error number.
Module |
Contents |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Kernel objects are statics, built by const fn, and need no memory
allocation. A Thread owns its stack, of 1 KiB unless its type says
otherwise, and runs a closure, which waits at the top of the stack buffer
for the thread to start: the closure takes its size out of the stack. A
stack too small for it fails to build.
static WORKER: Thread<2048> = Thread::new();
WORKER.spawn(c"worker", Priority::MAIN.lower(1), || work())?;
WORKER.join(Duration::from_secs(1))?;
The data of a Mutex is only reached through the guard lock() returns,
which unlocks it when dropped. A Timer, Work or DelayedWork holds data
of its own, which its function gets through it, where C embeds the object in
a structure of its own. Calls that block take a Duration, or a Timeout
for NO_WAIT and FOREVER.
The kernel samples are also in Rust, in samples/rust/kernel.
A panic is a kernel panic: its message and location go to the log and the
system stops as a failed assertion does, through
pbl_fatal_error_handler(). Crates are built with panic = "abort".
print! and println! write to the console with pbl_print(), so they
work from any context and do not need CONFIG_CONSOLE_STDOUT.
The C API is generated for each build directory, as its structs follow the
configuration: struct pbl_thread has fields only with
CONFIG_USERSPACE, for instance. rust/pebbleos-sys/wrapper.h lists the
headers. bindgen parses them with the include directories, definitions and
C library headers of the C code, and with -fshort-enums, as the ARM EABI
sizes enums. Ninja tracks the headers it read and runs it again when one
changes.
bindgen also writes C wrappers around the static inline functions of these
headers, which Rust cannot call otherwise; they are compiled into app.
Build directory |
Contents |
|---|---|
|
The bindings |
|
The wrappers of the |
|
cargo’s output |
The configuration decides how the crate is compiled:
Configuration |
Rust |
|---|---|
Cortex-M4 |
|
Cortex-M33, STAR-MC1 |
|
An FPU, without |
The |
|
The host’s target |
|
|
|
|
|
|
Rust follows the float ABI of the C code. With an FPU that is the hard-float
calling convention (-mfloat-abi=hard), so Rust uses the eabihf targets.
Where CONFIG_FP_SOFTFP_ABI is selected, as in the Pebble firmware, the C
code passes floating-point arguments in core registers
(-mfloat-abi=softfp), and Rust uses the eabi targets and only uses the
FPU within functions.
With Emscripten, the firmware is linked as C++ with exception catching on:
Rust’s prebuilt compiler_builtins has landing pads, which need the
exception runtime, though nothing throws.
Generated from PebbleOS 7753e801d. This page is maintained in the pebbleos repository: docs/development/build_system/rust.md.