document probe-rs

Reviewed-on: #51

.cargo/def-config.toml

@@ -4,10 +4,9 @@
 # runner = "arm-none-eabi-gdb -q -x openocd.gdb"
 # runner = "gdb-multiarch -q -x openocd.gdb"
 # runner = "gdb -q -x openocd.gdb"
-runner = "gdb-multiarch -q -x jlink.gdb"
+# runner = "gdb-multiarch -q -x jlink.gdb"
 
-# Probe-rs is currently problematic: https://github.com/probe-rs/probe-rs/issues/2567
+runner = "probe-rs run --chip VA108xx_RAM --protocol jtag"
-# runner = "probe-rs run --chip VA108xx --chip-description-path ./scripts/VA108xx_Series.yaml"
 # runner = ["probe-rs", "run", "--chip", "$CHIP", "--log-format", "{L} {s}"]
 
 rustflags = [

README.md

@@ -14,6 +14,8 @@ This workspace contains the following released crates:
   crate containing basic low-level register definition.
 - The [`va108xx-hal`](https://egit.irs.uni-stuttgart.de/rust/va108xx-rs/src/branch/main/va108xx-hal)
   HAL crate containing higher-level abstractions on top of the PAC register crate.
+- The [`va108xx-embassy`](https://egit.irs.uni-stuttgart.de/rust/va108xx-rs/src/branch/main/va108xx-embassy)
+  crate containing support for running the embassy-rs RTOS.
 - The [`vorago-reb1`](https://egit.irs.uni-stuttgart.de/rust/va108xx-rs/src/branch/main/vorago-reb1)
   BSP crate containing support for the REB1 development board.
 
@@ -58,14 +60,56 @@ You can then adapt the files in `.vscode` to your needs.
 You can use CLI or VS Code for flashing, running and debugging. In any case, take
 care of installing the pre-requisites first.
 
-### Pre-Requisites
+### Using CLI with probe-rs
+
+Install [probe-rs](https://github.com/probe-rs/probe-rs) first.
+
+You can use `probe-rs` to run the software and display RTT log output. However, debugging does not
+work yet.
+
+After installation, you can run the following command
+
+```sh
+probe-rs run --chip VA108xx_RAM --protocol jtag --example blinky
+```
+
+to flash and run the blinky program on the RAM. There is also a `VA108xx` chip target
+available for persistent flashing.
+
+Runner configuration avilable in the `.cargo/def-config.toml` file to use `probe-rs` for
+convenience.
+
+### Using VS Code
+
+Assuming a working debug connection to your VA108xx board, you can debug using VS Code with
+the [`Cortex-Debug` plugin](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug).
+Please make sure that [`objdump-multiarch` and `nm-multiarch`](https://forums.raspberrypi.com/viewtopic.php?t=333146)
+are installed as well.
+
+Some sample configuration files for VS code were provided and can be used by running
+`cp -rT vscode .vscode` like specified above. After that, you can use `Run and Debug`
+to automatically rebuild and flash your application.
+
+If you would like to use a custom GDB application, you can specify the gdb binary in the following
+configuration variables in your `settings.json`:
+
+- `"cortex-debug.gdbPath"`
+- `"cortex-debug.gdbPath.linux"`
+- `"cortex-debug.gdbPath.windows"`
+- `"cortex-debug.gdbPath.osx"`
+
+The provided VS Code configurations also provide an integrated RTT logger, which you can access
+via the terminal at `RTT Ch:0 console`. In order for the RTT block address detection to
+work properly, `objdump-multiarch` and `nm-multiarch` need to be installed.
+
+### Using CLI with GDB and Segger J-Link Tools
+
+Install the following two tools first:
 
 1. [SEGGER J-Link tools](https://www.segger.com/downloads/jlink/) installed
 2. [gdb-multiarch](https://packages.debian.org/sid/gdb-multiarch) or similar
    cross-architecture debugger installed. All commands here assume `gdb-multiarch`.
 
-### Using CLI
-
 You can build the blinky example application with the following command
 
 ```sh
@@ -99,25 +143,8 @@ runner = "gdb-multiarch -q -x jlink/jlink.gdb"
 After that, you can simply use `cargo run --example blinky` to flash the blinky
 example.
 
-### Using VS Code
+### Using the RTT Viewer
 
-Assuming a working debug connection to your VA108xx board, you can debug using VS Code with
+The Segger RTT viewer can be used to display log messages received from the target. The base
-the [`Cortex-Debug` plugin](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug).
+address for the RTT block placement is 0x10000000. It is recommended to use a search range of
-Please make sure that [`objdump-multiarch` and `nm-multiarch`](https://forums.raspberrypi.com/viewtopic.php?t=333146)
+0x1000 around that base address when using the RTT viewer.
-are installed as well.
-
-Some sample configuration files for VS code were provided and can be used by running
-`cp -rT vscode .vscode` like specified above. After that, you can use `Run and Debug`
-to automatically rebuild and flash your application.
-
-If you would like to use a custom GDB application, you can specify the gdb binary in the following
-configuration variables in your `settings.json`:
-
-- `"cortex-debug.gdbPath"`
-- `"cortex-debug.gdbPath.linux"`
-- `"cortex-debug.gdbPath.windows"`
-- `"cortex-debug.gdbPath.osx"`
-
-The provided VS Code configurations also provide an integrated RTT logger, which you can access
-via the terminal at `RTT Ch:0 console`. In order for the RTT block address detection to
-work properly, `objdump-multiarch` and `nm-multiarch` need to be installed.

bootloader/Cargo.toml

@@ -15,10 +15,12 @@ num_enum = { version = "0.7", default-features = false }
 static_assertions = "1"
 
 [dependencies.va108xx-hal]
-path = "../va108xx-hal"
+version = "0.9"
+# path = "../va108xx-hal"
 
 [dependencies.vorago-reb1]
-path = "../vorago-reb1"
+version = "0.7"
+# path = "../vorago-reb1"
 
 [features]
 default = []

examples/embassy/Cargo.toml

@@ -28,7 +28,7 @@ embassy-executor = { version = "0.7", features = [
 ]}
 
 va108xx-hal = "0.9"
-va108xx-embassy = { path = "../../va108xx-embassy", default-features = false }
+va108xx-embassy = "0.1"
 
 [features]
 default = ["ticks-hz-1_000", "va108xx-embassy/irq-oc30-oc31"]

examples/rtic/Cargo.toml

@@ -23,4 +23,4 @@ once_cell = {version = "1", default-features = false, features = ["critical-sect
 ringbuf = { version = "0.4.7", default-features = false, features = ["portable-atomic"] }
 
 va108xx-hal = "0.9"
-vorago-reb1 = { path = "../../vorago-reb1" }
+vorago-reb1 = "0.7"

examples/simple/Cargo.toml

@@ -20,4 +20,4 @@ version = "0.9"
 features = ["rt", "defmt"]
 
 [dependencies.vorago-reb1]
-path = "../../vorago-reb1"
+version = "0.7"

flashloader/Cargo.toml

@@ -29,7 +29,9 @@ rtic-monotonics = { version = "2", features = ["cortex-m-systick"] }
 rtic-sync = {version = "1", features = ["defmt-03"]}
 
 [dependencies.va108xx-hal]
-path = "../va108xx-hal"
+version = "0.9"
+# path = "../va108xx-hal"
 
 [dependencies.vorago-reb1]
-path = "../vorago-reb1"
+version = "0.7"
+# path = "../vorago-reb1"

va108xx-embassy/CHANGELOG.md

@@ -0,0 +1,17 @@
+Change Log
+=======
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [unreleased]
+
+## [v0.1.2] and [v0.1.1] 2025-02-13
+
+Docs patch
+
+## [v0.1.0] 2025-02-13
+
+Initial release

va108xx-embassy/Cargo.toml

@@ -1,11 +1,17 @@
 [package]
 name = "va108xx-embassy"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
+authors = ["Robin Mueller <muellerr@irs.uni-stuttgart.de>"]
+description = "Embassy-rs support for the Vorago VA108xx family of microcontrollers"
+homepage = "https://egit.irs.uni-stuttgart.de/rust/va108xx-rs"
+repository = "https://egit.irs.uni-stuttgart.de/rust/va108xx-rs"
+license = "Apache-2.0"
+keywords = ["no-std", "hal", "cortex-m", "vorago", "va108xx"]
+categories = ["aerospace", "embedded", "no-std", "hardware-support"]
 
 [dependencies]
 critical-section = "1"
-portable-atomic = { version = "1", features = ["unsafe-assume-single-core"]}
 
 embassy-sync = "0.6"
 embassy-executor = "0.7"
@@ -14,8 +20,12 @@ embassy-time-queue-utils = "0.1"
 
 once_cell = { version = "1", default-features = false, features = ["critical-section"] }
 
-[dependencies.va108xx-hal]
+va108xx-hal = "0.9"
-path = "../va108xx-hal"
+
+[target.'cfg(all(target_arch = "arm", target_os = "none"))'.dependencies]
+portable-atomic = { version = "1", features = ["unsafe-assume-single-core"] }
+[target.'cfg(not(all(target_arch = "arm", target_os = "none")))'.dependencies]
+portable-atomic = "1"
 
 [features]
 default = ["irq-oc30-oc31"]
@@ -25,3 +35,6 @@ irqs-in-lib = []
 irq-oc28-oc29 = ["irqs-in-lib"]
 irq-oc29-oc30 = ["irqs-in-lib"]
 irq-oc30-oc31 = ["irqs-in-lib"]
+
+[package.metadata.docs.rs]
+rustdoc-args = ["--generate-link-to-definition"]

va108xx-embassy/docs.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+export RUSTDOCFLAGS="--cfg docsrs --generate-link-to-definition -Z unstable-options"
+cargo +nightly doc --open

va108xx-embassy/src/lib.rs

@@ -23,17 +23,17 @@
 //!
 //! You can disable the default features and then specify one of the features above to use the
 //! documented combination of IRQs. It is also possible to specify custom IRQs by importing and
-//! using the [embassy::embassy_time_driver_irqs] macro to declare the IRQ handlers in the
+//! using the [embassy_time_driver_irqs] macro to declare the IRQ handlers in the
 //! application code. If this is done, [embassy::init_with_custom_irqs] must be used
 //! method to pass the IRQ numbers to the library.
 //!
 //! ## Examples
 //!
-//! [embassy example project](https://egit.irs.uni-stuttgart.de/rust/va108xx-rs/src/branch/main/examples/embassy)
+//! [embassy example projects](https://egit.irs.uni-stuttgart.de/rust/va108xx-rs/src/branch/main/examples/embassy)
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 use core::cell::{Cell, RefCell};
-use critical_section::CriticalSection;
+use critical_section::{CriticalSection, Mutex};
-use embassy_sync::blocking_mutex::CriticalSectionMutex as Mutex;
 use portable_atomic::{AtomicU32, Ordering};
 
 use embassy_time_driver::{time_driver_impl, Driver, TICK_HZ};
@@ -45,7 +45,7 @@ use va108xx_hal::{
     clock::enable_peripheral_clock,
     enable_nvic_interrupt, pac,
     prelude::*,
-    timer::{enable_tim_clk, get_tim_raw, TimRegInterface},
+    timer::{enable_tim_clk, get_tim_raw, TimRegInterface, ValidTim},
     PeripheralSelect,
 };
 
@@ -62,7 +62,7 @@ time_driver_impl!(
 /// the feature flags specified. However, the macro is exported to allow users to specify the
 /// interrupt handlers themselves.
 ///
-/// Please note that you have to explicitely import the [va108xx_hal::pac::interrupt]
+/// Please note that you have to explicitely import the [macro@va108xx_hal::pac::interrupt]
 /// macro in the application code in case this macro is used there.
 #[macro_export]
 macro_rules! embassy_time_driver_irqs {
@@ -115,12 +115,15 @@ pub mod embassy {
     /// This has to be called once at initialization time to initiate the time driver for
     /// embassy.
     #[cfg(feature = "irqs-in-lib")]
-    pub unsafe fn init(
+    pub unsafe fn init<
+        TimekeeperTim: TimRegInterface + ValidTim,
+        AlarmTim: TimRegInterface + ValidTim,
+    >(
         syscfg: &mut pac::Sysconfig,
         irqsel: &pac::Irqsel,
         sysclk: impl Into<Hertz>,
-        timekeeper_tim: impl TimRegInterface,
+        timekeeper_tim: TimekeeperTim,
-        alarm_tim: impl TimRegInterface,
+        alarm_tim: AlarmTim,
     ) {
         TIME_DRIVER.init(
             syscfg,
@@ -139,12 +142,15 @@ pub mod embassy {
     ///
     /// This has to be called once at initialization time to initiate the time driver for
     /// embassy.
-    pub unsafe fn init_with_custom_irqs(
+    pub unsafe fn init_with_custom_irqs<
+        TimekeeperTim: TimRegInterface + ValidTim,
+        AlarmTim: TimRegInterface + ValidTim,
+    >(
         syscfg: &mut pac::Sysconfig,
         irqsel: &pac::Irqsel,
         sysclk: impl Into<Hertz>,
-        timekeeper_tim: impl TimRegInterface,
+        timekeeper_tim: TimekeeperTim,
-        alarm_tim: impl TimRegInterface,
+        alarm_tim: AlarmTim,
         timekeeper_irq: pac::Interrupt,
         alarm_irq: pac::Interrupt,
     ) {
@@ -187,21 +193,21 @@ pub struct TimerDriver {
 
 impl TimerDriver {
     #[allow(clippy::too_many_arguments)]
-    fn init(
+    fn init<TimekeeperTim: TimRegInterface + ValidTim, AlarmTim: TimRegInterface + ValidTim>(
         &self,
         syscfg: &mut pac::Sysconfig,
         irqsel: &pac::Irqsel,
         sysclk: impl Into<Hertz>,
-        timekeeper_tim: impl TimRegInterface,
+        timekeeper_tim: TimekeeperTim,
-        alarm_tim: impl TimRegInterface,
+        alarm_tim: AlarmTim,
         timekeeper_irq: pac::Interrupt,
         alarm_irq: pac::Interrupt,
     ) {
-        if ALARM_TIM.get().is_some() {
+        if ALARM_TIM.get().is_some() || TIMEKEEPER_TIM.get().is_some() {
             return;
         }
-        ALARM_TIM.set(alarm_tim.tim_id()).ok();
+        ALARM_TIM.set(AlarmTim::TIM_ID).ok();
-        TIMEKEEPER_TIM.set(timekeeper_tim.tim_id()).ok();
+        TIMEKEEPER_TIM.set(TimekeeperTim::TIM_ID).ok();
         enable_peripheral_clock(syscfg, PeripheralSelect::Irqsel);
         enable_tim_clk(syscfg, timekeeper_tim.tim_id());
         let timekeeper_reg_block = timekeeper_tim.reg_block();