Prerequisites

1. Rustup (https://www.rust-lang.org/tools/install)
2. An IDE (VS Code with Rust Extension, RustRover, Neovim, ...)
3. QEMU (see https://www.qemu.org/download/)
4. defmt-print (install with cargo install defmt-print)
5. flip-link (install with cargo install flip-link)
6. probe-rs for flashing and printing from the board (follow https://probe.rs/docs/getting-started/installation/)
7. (Optional) cargo-expand (install with cargo install cargo-expand)

Getting Started

First setup the proper environment variables depending on whether you want to run it on QEMU or on the actual board. It is only required to set the CARGO_TARGET_MODE variable in .cargo/config.toml to either board or qemu.

To compile the project with debug config:

cargo build --features <rtt|semihosting>

or, with optimized config:

cargo build --features <rtt|semihosting> --release

You also must provide a defmt implementation using either the feature rtt or semihosting (the build will fail if none is selected)

To run the project on a QEMU emulated machine or board (have care to set the CARGO_TARGET_MODE env var to either board or qemu depending on where you want to run it):

cargo run

The runner is set up to either launch a QEMU instance that prints to the host via semihosting, with defmt-print decoding and printing defmt logs; or to use probe-rs to flash and run the executable on the board.

If you want to enable tasks performance profiling using the DWT peripheral, just enable the variouse profiling features (only works on the real board).

Crates and setup

The example is based on the crates cortex-m and cortex-m-rt which provide runtime initialization (vector table, .bss and .data section, stack pointer, etc...), and other useful stuff (eg entrypoint macro and critical section implementation), and the RTIC runtime.

defmt is used for logging, it allows for very efficient data transfer and it lets us use the same code between local QEMU testing and actual hardware (just need to change the global logger).

memory.x is a super basic linker script, just enough to make this basic example boot and work. In order to protect from stack overflow undefined behaviour flip-link linker is used.

Currently the example is set to compile and run on a Cortex-M4 microprocessor, the machine type is netduinoplus2 (since it is implemented in QEMU). The relevant documents (datasheet, reference manual and programming manual) are in the datasheets folder.

It is advised to install cargo-expand to visualize what happens behind the scenes, since RTIC uses a lot of macros and it can be hard to really understand what is happenining.