rticx-cortex-m 0.2.0

RTICX distribution for single-core Cortex-M targets (armv6-m and armv7-m and above)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# Single-core Cortex-M RTICX distribution

This distribution targets single-core Cortex-M microcontrollers, mirroring the
upstream RTIC cortex-m backend. It supports two mutually-exclusive locking
strategies selected at crate-feature time:

| Feature   | Architecture          | Locking mechanism                          |
|-----------|-----------------------|--------------------------------------------|
| *(default)* | armv7-m and above    | BASEPRI register (priority threshold)      |
| `armv6m`  | armv6-m (M0/M0+/M23)  | Interrupt source masking via NVIC ISER/ICER|
| `async`  | all  | Async/Await software tasks|
| `swtasks`  | all  | Simple software tasks|


## Layout

```
rticx-cortex-m/
├── src/                 # `rtic` library: re-exports `app` macro and runtime exports
├── rtic-macro/           # proc-macro crate implementing CorePassBackend + SwPassBackend
├── qemu-run.sh           # build + boot an example under QEMU
└── examples-apps/        # one crate for both archs: thumbv7m (BASEPRI) and
                          # thumbv6m (source masking), selected by `--target`
```


## Documentation

Full user guide is available in the [project wiki](https://github.com/rticx-rs/rticx/wiki/User-Guide).

## The QEMU playground

The `hello_rtic` example is a simple RTICX application that runs under QEMU and exercises the core primitives provided by this distribution:

1. `#[init]` configures the SysTick timer (`SYST`) to fire periodically.
2. **Hardware task bound to an exception**: `Tick` is bound to the `SysTick` exception handler. On each tick it spawns the software task.
3. **Software task on an NVIC dispatcher**  `Worker` runs off the `TIM6` NVIC interrupt, acquires the shared `counter` through a resource lock, increments it, and once it reaches `TARGET` calls `debug::exit(EXIT_SUCCESS)`.


### Prerequisites

```bash
# QEMU (Linux/Debian; macOS: `brew install qemu`)
sudo apt-get install -y qemu-system-arm

# Rust targets (CI runs `rustup target add` automatically)
rustup target add thumbv7m-none-eabi thumbv6m-none-eabi
```

### Running the examples

```bash
make qemu-armv7m
make qemu-armv6m
```

Or, per-example (the `.cargo/config.toml` wires up the QEMU runner, so `cargo
run` both builds and boots QEMU):

```bash
# thumbv7m (BASEPRI locking), default target
cd examples-apps && cargo run --example hello_rtic
cd examples-apps && cargo run --example async_ping_pong --features "async"

# thumbv6m (interrupt source masking): the target triple alone selects the
# `armv6m` lock path, no cargo feature flag needed
cd examples-apps && cargo run --target thumbv6m-none-eabi --example hello_rtic
```