-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: update add_board_support.md (#291)
- Loading branch information
Showing
1 changed file
with
91 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,30 +1,100 @@ | ||
# How to add a board | ||
# RIOT-rs adding hardware support | ||
|
||
This assumes the board is already supported by RIOT(-c). | ||
Currently, each board needs special support in RIOT-rs, as not RIOT(-c)'s | ||
bringup and linking code is used, but RIOT-rs Rust code. | ||
This document serves as a guide as to what's currently needed for adding support | ||
for a board/device to RIOT-rs. | ||
|
||
## nrf528xx based | ||
Feel free to report anything that's unclear! | ||
|
||
This is fairly straight forward. Currently, RIOT-rs doesn't do anything with | ||
peripherals itself (only through the riot-wrappers), so all nrf528xx based | ||
should work with the same code, apart from flashing. | ||
## Adding a board | ||
|
||
1. choose a suitable base board (nrf52dk for nrf52832 based board, nrf52840dk | ||
for nrf52840) | ||
1. copy `src/riot-rs-boards/<base board>` to `src/riot-rs-boards/<board>` | ||
1. replace all base board names in string literals with the new board name | ||
1. add the new board to the features at src/riot-rs-boards/Cargo.toml, e.g., | ||
The more similar a board is to one that is already supported, the easier. | ||
It is usually best to copy & adapt an existing one. | ||
|
||
new_board = { optional=true, path="new_board" } | ||
- ensure that the architecture [is supported in `riot-rs-embassy`](#adding-an-embassy-architecture) | ||
- in `laze-project.yml`: | ||
- add `context` for the MCU (if it doesn't exist, yet) | ||
- parent: the closest Embassy arch | ||
- selects: a [rustc-target](#adding-a-rustc-target-module) module | ||
- if the architecture does not have a dedicated SWI, choose one now | ||
and set `CONFIG_SWI` | ||
- ensure there's a way to flash the board: | ||
- if the MCU is supported by probe-rs, add `PROBE_RS_CHIP` | ||
and `PROBE_RS_PROTOCOL` | ||
- if the board is based on esp, it should inherit the espflash support | ||
- else, ask. :) | ||
|
||
1. add an entry in src/riot-rs-boards/src/lib.rs. replace underlines in the | ||
`pub use` but not in the feature name, e.g., if the board and feature | ||
`nrf52840-mdk` -> `pub use nrf52840_mdk as board;`. | ||
- add `builder` for the actual board that uses the context from above as `parent` | ||
|
||
1. in laze-project.yml, copy the base board builder entry (and fix the name) | ||
Whether to add an intermediate context or just a builder depends on whether the | ||
MCU-specific code can be re-used. | ||
|
||
1. try it: `laze -Cexamples/bottles build -b <new-board>` | ||
Example for the `st-nucleo-f401re`: | ||
|
||
Assuming the board can be flashed with openocd/jlink, the flash task should work | ||
as is. Otherwise, the flashing method needs to be added/fixed. | ||
```yaml | ||
contexts: | ||
# ... | ||
- name: stm32f401retx | ||
parent: stm32 | ||
selects: | ||
- thumbv7em-none-eabi # actually eabihf, but riot-rs doesn't support hard float yet | ||
env: | ||
PROBE_RS_CHIP: STM32F401RETx | ||
PROBE_RS_PROTOCOL: swd | ||
RUSTFLAGS: | ||
- --cfg context=\"stm32f401retx\" | ||
CARGO_ENV: | ||
- CONFIG_SWI=USART2 | ||
|
||
builders: | ||
# ... | ||
- name: st-nucleo-f401re | ||
parent: stm32f401retx | ||
|
||
``` | ||
|
||
- `src/riot-rs-boards/$BOARD`: add crate that matches board name | ||
- this crate should inject the board-specific dependencies to the arch crates. | ||
- `src/riot-rs-boards`: | ||
- `Cargo.toml`: add feature that matches board name | ||
- `src/lib.rs`: add board to dispatch | ||
|
||
## Adding a rustc target module | ||
|
||
Each actual rustc target needs its own module in laze-project.yml. | ||
If the device that's being added isn't listed yet, you'll need to take care | ||
of that. | ||
|
||
Example: | ||
|
||
```yaml | ||
modules: | ||
# ... | ||
- name: thumbv6m-none-eabi | ||
depends: | ||
- cortex-m | ||
env: | ||
global: | ||
RUSTC_TARGET: thumbv6m-none-eabi | ||
CARGO_TARGET_PREFIX: CARGO_TARGET_THUMBV6M_NONE_EABI | ||
RUSTFLAGS: | ||
- --cfg armv6m | ||
``` | ||
The variables `RUSTC_TARGET` and `CARGO_TARGET_PREFIX` need to be adjusted. | ||
Add `--cfg $arch` as needed. | ||
|
||
Chances are that if you need to add this, you'll also have to add support for the architecture to `riot-rs-threads`. | ||
|
||
## Adding an Embassy architecture | ||
|
||
As of this writing, RIOT-rs supports most architectures that Embassy supports, | ||
including `nrf`, `stm32`, `rp` and `esp-rs`, but excluding `std` and `wasm`. | ||
|
||
The steps to add support for another Embassy supported architecture are: | ||
|
||
- `src/riot-rs-embassy`: | ||
- `Cargo.toml`: add Embassy arch dependency | ||
- `src/lib.rs`: add arch dispatch | ||
- `src/arch/$ARCH.rs`: | ||
1. select the appropriate SWI interrupt (if not done through CONFIG_SWI) | ||
2. implement the `usb` module |