Rust Development Notes on XWOS

Integration and Build

Mon, 01 Jan 0001 00:00:00 +0000

Concept

Compile as staticlib via cargo, then link with XWOS;
Since XWOS supports ARM/PowerPC/RISC-V, cross-compilation for multiple platforms is required via the --target= option.

Approach

XWOS starts an independent thread that calls Rust’s main function, thus entering the world of Rust;
Rust’s main function and middleware are an independently compiled XWOS module;
Since Rust compilation depends on the cargo tool, a new XWOS module build rule can be designed to invoke cargo build;
The Rust XWOS module is compiled as staticlib and ultimately statically linked with XWOS;
Since some unstable features are used, the nightly version of Rust must be installed.

Build Approach

The cargo build target should be set to PHONY, so that cargo build is invoked every time make is run, and cargo manages the compilation of rust source code;
The environment variable $(RUST_TARGET) is defined in cpu.mk;
Other build options are defined in .cargo/config or build.rs;
After cargo build completes, copy the output .a file to the output directory;

Installing the Rust Toolchain

Install Rust according to the official guide;
Switch mirror sources:
- Ubuntu configuration file path: ~/.cargo/config
- Windows configuration file path: C:\Users\username\.cargo\config

[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"
replace-with = 'sjtu'

[source.ustc]
registry = "http://mirrors.ustc.edu.cn/crates.io-index"

[source.sjtu]
registry = "http://mirrors.sjtug.sjtu.edu.cn/git/crates.io-index"

Ubuntu: Install unstable version

rustup install nightly
rustup +nightly target add thumbv8m.main-none-eabihf
rustup +nightly target add thumbv8m.main-none-eabi
rustup +nightly target add thumbv8m.base-none-eabi
rustup +nightly target add thumbv7m-none-eabi
rustup +nightly target add thumbv7em-none-eabihf
rustup +nightly target add thumbv7em-none-eabi
rustup +nightly target add thumbv6m-none-eabi
rustup +nightly target add riscv32imac-unknown-none-elf
rustup +nightly component add rust-src

Windows: Install unstable version

Note: Windows only supports using the gnu version of the toolchain

Rust Initial Validation

Mon, 01 Jan 0001 00:00:00 +0000

Rust std Library

The Rust standard library includes:

In embedded systems, core and alloc are the most useful.

Although in embedded environments you can forcibly use Rust’s std library through #![feature(restricted_std)], as functionality increases, problems also increase, so we switched to using #![no_std].

Build

Add the following build configuration in .cargo/config.toml:

[unstable]
build-std = ["core", "alloc"]

global_allocator

An attribute that can be used to implement your own memory allocation functions. Refer to the documentation std::alloc.

Rust Development Environment Installation Notes

Mon, 01 Jan 0001 00:00:00 +0000

Installing LSP

LSP (Language Server Protocol) is a new generation tool for browsing source code. For Rust, rust-analyzer is the recommended LSP.

git clone https://github.com/rust-analyzer/rust-analyzer.git
cd rust-analyzer
cargo xtask install

VScode

After installing VSCode, you also need to install rust-analyzer. Once installed, VSCode works out of the box.

STM32CubeIDE

STM32CubeIDE is Eclipse-based, so you only need to install the Rust plugin.

Rust Plugin

A relatively new version of the Rust plugin must be installed, otherwise it cannot support rust-analyzer.

Supporting Multiple Crates

Mon, 01 Jan 0001 00:00:00 +0000

Limitations

During the development of XWOS Rust, it became necessary to separate library and application code into different crates. In practice, the following Rust limitations were discovered:

Two crates cannot both be compiled as staticlib. A staticlib crate cannot be listed in [dependencies], indicating that staticlib is meant to be called by C/C++;
Only rlib crates can be listed in [dependencies]. When compiling staticlib, all crates in [dependencies] will be packaged within the staticlib;
When linking with C/C++ code, there cannot be two or more staticlibs, unless these staticlibs’ dependencies are completely unrelated (which is difficult to achieve in practice), otherwise duplicate definition linker errors will occur.

Solution

Through practice, the following solution was developed: