From 038286be40da4ef877c2f1152bc3374e0c548499 Mon Sep 17 00:00:00 2001
From: Kaspar Schleiser <kaspar@schleiser.de>
Date: Tue, 14 May 2024 15:33:35 +0200
Subject: [PATCH] doc: update add_board_support.md

---
 doc/add_board_support.md | 112 +++++++++++++++++++++++++++++++--------
 1 file changed, 91 insertions(+), 21 deletions(-)

diff --git a/doc/add_board_support.md b/doc/add_board_support.md
index a5604eadb..f34f6a9bb 100644
--- a/doc/add_board_support.md
+++ b/doc/add_board_support.md
@@ -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