Merge pull request #49 from probe-rs/defmt

General overhaul and defmt support

Author: bugadani

Cargo.toml

@@ -1,5 +1,6 @@
 [workspace]
 members = ["examples-cortex-m", "rtt-target", "panic-rtt-target", "panic-test"]
+resolver = "2"
 
 [patch.crates-io]
 rtt-target = { path = "./rtt-target" }

README.md

@@ -27,6 +27,13 @@ fn main() {
 }
 ```
 
+`rtt-target` also supports initializing multiple RTT channels, and even has a logger implementation
+for [`defmt`](https://defmt.ferrous-systems.com/) that can be used in conjunction with arbitrary
+channel setups. The `defmt` integration requires setting `features = ["defmt"]`, and the used
+channel needs to be manually configured with `set_defmt_channel`.
+
+For more information, please check out the [documentation](https://docs.rs/rtt-target).
+
 ## Development
 
 The examples-cortex-m and panic-test crates come with build files for the venerable STM32F103C8xx by default, but can be easily adapted for any chip as they contain only minimal platform-specific runtime code to get `fn main` to run.

examples-cortex-m/.cargo/config.toml

@@ -0,0 +1,5 @@
+[build]
+target = "thumbv7m-none-eabi"
+
+[unstable]
+build-std = ["core"]

examples-cortex-m/Cargo.toml

@@ -4,12 +4,16 @@ version = "0.1.0"
 authors = ["Matti Virkkunen <[email protected]>"]
 edition = "2018"
 
+[features]
+defmt = ["dep:defmt", "rtt-target/defmt"]
+
 [dependencies]
 cortex-m = { version = "0.7.6", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
 panic-halt = "0.2.0"
 rtt-target = { path = "../rtt-target" }
 ufmt = "0.2.0"
+defmt = { version = "0.3.0", optional = true }
 
 [[bin]]
 name = "custom"
@@ -19,3 +23,7 @@ name = "print"
 
 [[bin]]
 name = "ufmt"
+
+[[bin]]
+name = "defmt"
+required-features = ["defmt"]

examples-cortex-m/src/bin/defmt.rs

@@ -0,0 +1,27 @@
+#![no_std]
+#![no_main]
+
+use cortex_m_rt::entry;
+use panic_halt as _;
+use rtt_target::rtt_init;
+
+#[entry]
+fn main() -> ! {
+    let channels = rtt_init! {
+        up: {
+            0: {
+                size: 1024,
+                name: "defmt"
+            }
+        }
+    };
+
+    rtt_target::set_defmt_channel(channels.up.0);
+
+    let mut i = 0;
+    loop {
+        defmt::println!("Loop {}...", i);
+
+        i += 1;
+    }
+}

panic-rtt-target/Cargo.toml

@@ -1,18 +1,18 @@
 [package]
 name = "panic-rtt-target"
 description = "Logs panic messages over RTT using rtt-target"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 readme = "README.md"
 keywords = ["no-std", "embedded", "debugging", "rtt"]
 license = "MIT"
-license-file = "../LICENSE"
 authors = [
     "Matti Virkkunen <[email protected]>",
     "Per Lindgren <[email protected]>",
 ]
 repository = "https://github.com/probe-rs/rtt-target"
 
 [dependencies]
-rtt-target = "0.5.0"
+rtt-target = {version = "0.6.0", path = "../rtt-target" }
 critical-section = "1.1.1"
+portable-atomic = { version = "1.6.0", default-features = false }

panic-rtt-target/README.md

@@ -8,18 +8,18 @@ Logs panic messages over RTT. A companion crate for rtt-target.
 
 RTT must have been initialized by using one of the `rtt_init` macros. Otherwise you will get a linker error at compile time.
 
-Panics are always logged on channel 0. Upon panicking the channel mode is also automatically set to `BlockIfFull`, so that the full message will always be logged. If the code somehow manages to panic at runtime before RTT is initialized (quite unlikely), or if channel 0 doesn't exist, nothing is logged. 
+Panics are always logged to the print channel. Upon panicking the channel mode is also automatically set to `BlockIfFull`, so that the full message will always be logged. If the code somehow manages to panic at runtime before RTT is initialized (quite unlikely), or if the print channel doesn't exist, nothing is logged.
 
-The panic handler runs in a non-returning [critical_section](https://docs.rs/critical-section) which implementation should be provided by the user. 
+The panic handler runs in a non-returning [critical_section](https://docs.rs/critical-section) which implementation should be provided by the user.
 
 # Usage
 
 Cargo.toml:
 
 ```toml
 [dependencies]
-cortex-m = { version = "0.7.6", features = ["critical-section-single-core"]}
-panic-rtt-target = { version = "x.y.z" }
+rtt-target = "x.y.z"
+panic-rtt-target = "x.y.z"
 ```
 
 main.rs:
@@ -31,34 +31,9 @@ use panic_rtt_target as _;
 use rtt_target::rtt_init_default;
 
 fn main() -> ! {
-    // you can use any init macro as long as it creates channel 0
+    // you can use `rtt_init_print` or you can call `set_print_channel` after initialization.
     rtt_init_default!();
 
     panic!("Something has gone terribly wrong");
 }
 ```
-
-## Implementation details
-
-The provided interrupt handler checks if RTT channel 0 is configured, writes the `info` and enters an infinite loop. If RTT channel 0 is not configured, the panic handler enters the *failed to get channel* infinite loop. The final state can be observed by breaking/halting the target. 
-```rust
-fn panic(info: &PanicInfo) -> ! {
-    critical_section::with(|_| {
-        if let Some(mut channel) = unsafe { UpChannel::conjure(0) } {
-            channel.set_mode(ChannelMode::BlockIfFull);
-
-            writeln!(channel, "{}", info).ok();
-        } else {
-            // failed to get channel, but not much else we can do but spin
-            loop {
-                compiler_fence(SeqCst);
-            }
-        }
-
-        // we should never leave critical section
-        loop {
-            compiler_fence(SeqCst);
-        }
-    })
-}
-```

panic-rtt-target/src/lib.rs

@@ -3,20 +3,22 @@
 //! RTT must have been initialized by using one of the `rtt_init` macros. Otherwise you will get a
 //! linker error at compile time.
 //!
-//! Panics are always logged on channel 0. Upon panicking the channel mode is also automatically set
-//! to `BlockIfFull`, so that the full message will always be logged. If the code somehow manages to
-//! panic at runtime before RTT is initialized (quite unlikely), or if channel 0 doesn't exist,
-//! nothing is logged.
+//! Panics are always logged to the print channel. Upon panicking the channel mode is also
+//! automatically set to `BlockIfFull`, so that the full message will always be logged.
+//! If the code somehow manages to panic at runtime before RTT is initialized (quite unlikely),
+//! or if the print channel doesn't exist, nothing is logged.
 //!
-//! A platform feature such as `cortex-m` is required to use this crate.
+//! The panic handler runs in a non-returning [critical_section](https://docs.rs/critical-section)
+//! which implementation should be provided by the user.
 //!
 //! # Usage
 //!
 //! Cargo.toml:
 //!
 //! ```toml
 //! [dependencies]
-//! panic-rtt-target = { version = "x.y.z", features = ["cortex-m"] }
+//! rtt-target = "x.y.z"
+//! panic-rtt-target = "x.y.z"
 //! ```
 //!
 //! main.rs:
@@ -28,7 +30,7 @@
 //! use rtt_target::rtt_init_default;
 //!
 //! fn main() -> ! {
-//!     // you can use any init macro as long as it creates channel 0
+//!     // you can use `rtt_init_print` or you can call `set_print_channel` after initialization.
 //!     rtt_init_default!();
 //!
 //!     panic!("Something has gone terribly wrong");
@@ -37,37 +39,25 @@
 
 #![no_std]
 
-// allow(unused) is used so that warnings when no platform feature is defined don't drown out the
-// compile_error
+use core::{fmt::Write, panic::PanicInfo};
+use portable_atomic::{compiler_fence, Ordering};
 
-#[allow(unused)]
-use core::{
-    fmt::Write,
-    panic::PanicInfo,
-    sync::atomic::{compiler_fence, Ordering::SeqCst},
-};
-
-#[allow(unused)]
-use rtt_target::{ChannelMode, UpChannel};
+use rtt_target::{with_terminal_channel, ChannelMode};
 
 #[inline(never)]
 #[panic_handler]
 fn panic(info: &PanicInfo) -> ! {
     critical_section::with(|_| {
-        if let Some(mut channel) = unsafe { UpChannel::conjure(0) } {
-            channel.set_mode(ChannelMode::BlockIfFull);
+        with_terminal_channel(|term| {
+            term.set_mode(ChannelMode::BlockIfFull);
+            let mut channel = term.write(0);
 
             writeln!(channel, "{}", info).ok();
-        } else {
-            // failed to get channel, but not much else we can do but spin
-            loop {
-                compiler_fence(SeqCst);
-            }
-        }
+        });
 
         // we should never leave critical section
         loop {
-            compiler_fence(SeqCst);
+            compiler_fence(Ordering::SeqCst);
         }
     })
 }

panic-test/.cargo/config.toml

@@ -0,0 +1,5 @@
+[build]
+target = "thumbv7m-none-eabi"
+
+[unstable]
+build-std = ["core"]

rtt-target/Cargo.toml

@@ -1,15 +1,20 @@
 [package]
 name = "rtt-target"
 description = "Target side implementation of the RTT (Real-Time Transfer) I/O protocol"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2018"
 readme = "../README.md"
 keywords = ["no-std", "embedded", "debugging", "rtt"]
 license = "MIT"
-license-file = "../LICENSE"
 authors = ["Matti Virkkunen <[email protected]>"]
 repository = "https://github.com/probe-rs/rtt-target"
 
+[features]
+default = []
+
 [dependencies]
 ufmt-write = "0.1.0"
 critical-section = "1.0.0"
+portable-atomic = { version = "1.6.0", default-features = false }
+
+defmt = { version = "0.3.0", optional = true }