add defmt support (#255)

Cargo.toml

@@ -49,7 +49,7 @@ embassy-usb = { version = "0.1", default-features = false }
 esp-hal = { git = "https://github.com/kaspar030/esp-hal", branch = "for-riot-rs-2024-06-14", default-features = false }
 esp-hal-embassy = { git = "https://github.com/kaspar030/esp-hal", branch = "for-riot-rs-2024-06-14", default-features = false }
 esp-println = { version = "0.9.0" }
-esp-wifi = { git = "https://github.com/kaspar030/esp-hal", branch = "for-riot-rs-2024-06-14" }
+esp-wifi = { git = "https://github.com/kaspar030/esp-hal", branch = "for-riot-rs-2024-06-14", default-features = false }
 
 linkme = { version = "0.3.21", features = ["used_linker"] }
 
@@ -62,6 +62,7 @@ riot-rs-runqueue = { path = "src/riot-rs-runqueue" }
 riot-rs-utils = { path = "src/riot-rs-utils", default-features = false }
 
 const_panic = { version = "0.2.8", default-features = false }
+defmt = { version = "0.3.7" }
 document-features = "0.2.8"
 heapless = { version = "0.8.0", default-features = false }
 konst = { version = "0.3.8", default-features = false }

book/src/SUMMARY.md

@@ -7,6 +7,9 @@
 
 # User Guide
 
+- [Tooling](./tooling/index.md)
+  - [defmt](./tooling/defmt.md)
+
 # Developer Guide
 
 - [Appendices](./appendices.md)

book/src/tooling/defmt.md

@@ -0,0 +1,33 @@
+# defmt
+
+RIOT-rs supports [defmt] on all platforms.
+To enable it, enable the laze module `defmt`, either on the laze command line or
+in a laze file. Don't forget to set the `DEFMT_LOG` variable, it defaults to `error`.
+See the [defmt documentation] for general info on `defmt`.
+
+Example:
+
+```shell
+# DEFMT_LOG=info laze -C examples/hello-world-async --board nrf52840dk --select defmt run
+```
+
+Then within Rust code, import `riot_rs::debug::log` items, then use `defmt` log
+macros [as usual][defmt-macros]:
+
+```rust
+use riot_rs::debug::log::*;
+
+#[riot_rs::task(autostart)]
+async fn main() {
+    info!("Hello!");
+}
+```
+
+If the `defmt` laze module is not selected, all log statements become no-ops.
+
+Note: On Cortex-M devices, the order of `riot_rs::debug::println!()` output and
+      `defmt` log output is not deterministic.
+
+[defmt]: https://github.com/knurling-rs/defmt
+[defmt documentation]: https://defmt.ferrous-systems.com/
+[defmt-macros]: https://defmt.ferrous-systems.com/macros

book/src/tooling/index.md

@@ -0,0 +1,3 @@
+# Tooling
+
+This chapter contains documentation on tooling that RIOT-rs provides or integrates.

laze-project.yml

@@ -276,7 +276,7 @@ contexts:
         #- -C force-frame-pointers
       CARGO_ARGS:
         - -Zbuild-std=core
-      CARGO_RUNNER: '"espflash flash --monitor"'
+      CARGO_RUNNER: '"espflash flash --monitor ${ESPFLASH_LOG_FORMAT}"'
 
   - name: esp32c3
     parent: esp
@@ -374,6 +374,21 @@ modules:
         FEATURES:
           - riot-rs/debug-console
 
+  - name: defmt
+    help: Enable use of defmt
+    context: riot-rs
+    env:
+      global:
+        FEATURES:
+          - riot-rs/defmt
+        RUSTFLAGS:
+          - -Clink-arg=-Tdefmt.x
+        ESPFLASH_LOG_FORMAT: '--log-format defmt'
+        CARGO_ENV:
+          # For some reason, `sccache` makes the build not realize changes to
+          # `DEFMT_LOG`. Painful as it is, hard-disable `sccache` here.
+          - RUSTC_WRAPPER=""
+
   - name: silent-panic
     context: riot-rs
     env:

src/riot-rs-debug/Cargo.toml

@@ -11,11 +11,16 @@ repository.workspace = true
 workspace = true
 
 [dependencies]
+defmt = { workspace = true, optional = true }
+
+# listed here so they can enable its features conditionally
+esp-println = { workspace = true, optional = true }
 
 [target.'cfg(context = "cortex-m")'.dependencies]
 cortex-m = { workspace = true, features = ["critical-section-single-core"] }
 cortex-m-semihosting = { workspace = true, optional = true }
-rtt-target = { version = "0.4.0", optional = true }
+rtt-target = { version = "0.5.0", optional = true }
+defmt-rtt-target = { git = "https://github.com/kaspar030/defmt-rtt-target", rev = "5668c92ac5a0689b165a6a07bb14e173fc47cd34" }
 
 [target.'cfg(context = "esp")'.dependencies]
 esp-println = { workspace = true, features = ["log"] }
@@ -29,3 +34,4 @@ esp-println = { workspace = true, features = ["esp32c6"] }
 
 [features]
 debug-console = []
+defmt = ["dep:defmt", "esp-println?/defmt-espflash"]

src/riot-rs-debug/src/lib.rs

@@ -27,10 +27,40 @@ mod backend {
             unsafe { cortex_m::asm::semihosting_syscall(SYS_EXIT, semihosting_exit_code) };
         }
     }
-    pub use rtt_target::rprint as print;
-    pub use rtt_target::rprintln as println;
+
+    pub use rtt_target::{rprint as print, rprintln as println};
+
     pub fn init() {
-        rtt_target::rtt_init_print!(NoBlockTrim);
+        #[cfg(not(feature = "defmt"))]
+        {
+            use rtt_target::ChannelMode::NoBlockTrim;
+
+            rtt_target::rtt_init_print!(NoBlockTrim);
+        }
+
+        #[cfg(feature = "defmt")]
+        {
+            use rtt_target::ChannelMode::{NoBlockSkip, NoBlockTrim};
+            let channels = rtt_target::rtt_init! {
+                up: {
+                    0: {
+                        size: 1024,
+                        mode: NoBlockTrim,
+                        // probe-run autodetects whether defmt is in use based on this channel name
+                        name: "Terminal"
+                    }
+                    1: {
+                        size: 1024,
+                        mode: NoBlockSkip,
+                        // probe-run autodetects whether defmt is in use based on this channel name
+                        name: "defmt"
+                    }
+                }
+            };
+
+            rtt_target::set_print_channel(channels.up.0);
+            defmt_rtt_target::init(channels.up.1);
+        }
     }
 }
 
@@ -81,3 +111,70 @@ mod backend {
 }
 
 pub use backend::*;
+
+#[cfg(feature = "defmt")]
+pub mod log {
+    pub use defmt;
+
+    #[macro_export]
+    macro_rules! __trace {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::trace!($($arg)*);
+        }};
+    }
+
+    #[macro_export]
+    macro_rules! __debug {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::debug!($($arg)*);
+        }};
+    }
+
+    #[macro_export]
+    macro_rules! __info {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::info!($($arg)*);
+        }};
+    }
+
+    #[macro_export]
+    macro_rules! __warn {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::warn!($($arg)*);
+        }};
+    }
+
+    #[macro_export]
+    macro_rules! __error {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::error!($($arg)*);
+        }};
+    }
+
+    pub use __debug as debug;
+    pub use __error as error;
+    pub use __info as info;
+    pub use __trace as trace;
+    pub use __warn as warn;
+}
+
+#[cfg(not(feature = "defmt"))]
+pub mod log {
+    #[macro_export]
+    macro_rules! __stub {
+        ($($arg:tt)*) => {{
+            let _ = ($($arg)*); // Do nothing
+        }};
+    }
+
+    pub use __stub as debug;
+    pub use __stub as error;
+    pub use __stub as info;
+    pub use __stub as trace;
+    pub use __stub as warn;
+}

src/riot-rs-embassy/Cargo.toml

@@ -43,6 +43,7 @@ cyw43-pio = { version = "0.1.0", features = ["overclock"], optional = true }
 embassy-nrf = { workspace = true, default-features = false, optional = true }
 esp-hal = { workspace = true, default-features = false, optional = true }
 esp-hal-embassy = { workspace = true, default-features = false, optional = true }
+esp-wifi = { workspace = true, optional = true }
 
 [target.'cfg(context = "cortex-m")'.dependencies]
 embassy-executor = { workspace = true, default-features = false, features = [
@@ -79,7 +80,7 @@ esp-hal = { workspace = true, features = [] }
 esp-hal-embassy = { workspace = true, default-features = false, features = [
   "time-timg0",
 ] }
-esp-wifi = { workspace = true, features = [
+esp-wifi = { workspace = true, default-features = false, features = [
   "async",
   "embassy-net",
   "wifi",
@@ -90,14 +91,18 @@ esp-hal = { workspace = true, features = ["esp32c3"] }
 esp-hal-embassy = { workspace = true, default-features = false, features = [
   "esp32c3",
 ] }
-esp-wifi = { workspace = true, features = ["esp32c3"], optional = true }
+esp-wifi = { workspace = true, default-features = false, features = [
+  "esp32c3",
+], optional = true }
 
 [target.'cfg(context = "esp32c6")'.dependencies]
 esp-hal = { workspace = true, features = ["esp32c6"] }
 esp-hal-embassy = { workspace = true, default-features = false, features = [
   "esp32c6",
 ] }
-esp-wifi = { workspace = true, features = ["esp32c6"], optional = true }
+esp-wifi = { workspace = true, default-features = false, features = [
+  "esp32c6",
+], optional = true }
 
 [features]
 time = ["dep:embassy-time", "embassy-executor/integrated-timers"]
@@ -129,3 +134,11 @@ executor-single-thread = [
 executor-interrupt = ["embassy-executor/executor-interrupt"]
 executor-thread = ["threading"]
 executor-none = []
+
+defmt = [
+  "embassy-net?/defmt",
+  "embassy-nrf?/defmt",
+  "embassy-time?/defmt",
+  "embassy-usb?/defmt",
+  "esp-wifi?/defmt",
+]

src/riot-rs/Cargo.toml

@@ -71,6 +71,8 @@ wifi-esp = ["riot-rs-embassy/wifi-esp"]
 ## Enables the debug console, required to use
 ## [`println!`](riot_rs_debug::println).
 debug-console = ["riot-rs-rt/debug-console"]
+## Enables logging support through `defmt`.
+defmt = ["riot-rs-debug/defmt", "riot-rs-embassy/defmt"]
 ## Enables benchmarking facilities.
 bench = ["dep:riot-rs-bench"]
 ## Prints nothing in case of panics (may help reduce binary size).