update examples

- Introduce `defmt` which is very commonly used on embedded systems. It
  is used to print the allocated structures.
- New QEMU runner to support defmt.
- Introduce new example which uses a global heap initialized on BSS
  memory.
- Switch to more commonly used thumbv7em-none-eabihf target for the QEMU
  runner.

Author: robamu

.cargo/config.toml

@@ -1,4 +1,16 @@
-[target.thumbv7m-none-eabi]
+[build]
+# Common embedded build targets
+# target = "thumbv7em-none-eabihf"
+# target = "thumbv6m-none-eabi"
+
+[target.thumbv7em-none-eabihf]
 # used to run the qemu_test.rs example with QEMU
-runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"
-rustflags = ["-C", "link-arg=-Tlink.x"]
+runner = "./qemu-runner.sh"
+
+rustflags = [
+  "-Clink-arg=-Tlink.x",
+  "-Clink-arg=-Tdefmt.x",
+]
+
+[env]
+DEFMT_LOG="info"

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         target:
           - thumbv6m-none-eabi
-          - thumbv7m-none-eabi
+          - thumbv7em-none-eabihf
         toolchain:
           - stable
           - nightly
@@ -49,7 +49,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@master
         with:
-          targets: thumbv7m-none-eabi
+          targets: thumbv7em-none-eabihf
           toolchain: nightly
       - name: Install QEMU
         run: |

Cargo.toml

@@ -41,8 +41,11 @@ const-default = { version = "1.0.0", default-features = false, optional = true }
 [dev-dependencies]
 cortex-m = { version = "0.7.6", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
-cortex-m-semihosting = "0.5"
-panic-semihosting = { version = "0.6", features = ["exit"] }
+# cortex-m-semihosting = "0.5"
+defmt = "1.0"
+defmt-semihosting = "0.3.0"
+semihosting = { version = "0.1.20", features = ["stdio"] }
+static_cell = "2"
 
 [[example]]
 name = "allocator_api"

examples/allocator_api.rs

@@ -1,13 +1,15 @@
+//! This examples requires nightly for the allocator API.
 #![feature(allocator_api)]
 #![no_std]
 #![no_main]
 
 extern crate alloc;
 
-use alloc::vec::Vec;
-use core::mem::MaybeUninit;
-use core::panic::PanicInfo;
+use core::{mem::MaybeUninit, panic::PanicInfo};
+use cortex_m as _;
 use cortex_m_rt::entry;
+use defmt::Debug2Format;
+use defmt_semihosting as _;
 use embedded_alloc::LlffHeap as Heap;
 
 // This is not used, but as of 2023-10-29 allocator_api cannot be used without
@@ -22,14 +24,16 @@ fn main() -> ! {
     let heap: Heap = Heap::empty();
     unsafe { heap.init(&raw mut HEAP_MEM as usize, HEAP_SIZE) }
 
-    let mut xs = Vec::new_in(heap);
-    xs.push(1);
+    let mut vec = alloc::vec::Vec::new_in(heap);
+    vec.push(1);
 
-    #[allow(clippy::empty_loop)]
-    loop { /* .. */ }
+    defmt::info!("Allocated vector: {:?}", Debug2Format(&vec));
+
+    semihosting::process::exit(0);
 }
 
 #[panic_handler]
-fn panic(_: &PanicInfo) -> ! {
-    loop {}
+fn panic(info: &PanicInfo) -> ! {
+    defmt::error!("{}", info);
+    semihosting::process::exit(0);
 }

examples/global_alloc.rs

@@ -3,9 +3,12 @@
 
 extern crate alloc;
 
-use alloc::vec::Vec;
-use core::panic::PanicInfo;
+use cortex_m as _;
 use cortex_m_rt::entry;
+use defmt::Debug2Format;
+use defmt_semihosting as _;
+
+use core::panic::PanicInfo;
 // Linked-List First Fit Heap allocator (feature = "llff")
 use embedded_alloc::LlffHeap as Heap;
 // Two-Level Segregated Fit Heap allocator (feature = "tlsf")
@@ -21,14 +24,19 @@ fn main() -> ! {
         embedded_alloc::init!(HEAP, 1024);
     }
 
-    let mut xs = Vec::new();
-    xs.push(1);
+    let vec = alloc::vec![1];
+
+    defmt::info!("Allocated vector: {:?}", Debug2Format(&vec));
+
+    let string = alloc::string::String::from("Hello, world!");
+
+    defmt::info!("Allocated string: {:?}", Debug2Format(&string));
 
-    #[allow(clippy::empty_loop)]
-    loop { /* .. */ }
+    semihosting::process::exit(0);
 }
 
 #[panic_handler]
-fn panic(_: &PanicInfo) -> ! {
-    loop {}
+fn panic(info: &PanicInfo) -> ! {
+    defmt::error!("{}", info);
+    semihosting::process::exit(0);
 }

examples/global_alloc_bss_heap.rs

@@ -0,0 +1,41 @@
+#![no_std]
+#![no_main]
+
+extern crate alloc;
+
+use cortex_m as _;
+use cortex_m_rt::entry;
+use defmt::Debug2Format;
+use defmt_semihosting as _;
+
+use core::panic::PanicInfo;
+use embedded_alloc::TlsfHeap as Heap;
+
+#[global_allocator]
+static HEAP: Heap = Heap::empty();
+
+#[entry]
+fn main() -> ! {
+    const HEAP_SIZE: usize = 16 * 1024;
+    static HEAP_MEM: static_cell::ConstStaticCell<[u8; HEAP_SIZE]> =
+        static_cell::ConstStaticCell::new([0; HEAP_SIZE]);
+    unsafe {
+        HEAP.init(HEAP_MEM.take().as_mut_ptr() as usize, HEAP_SIZE);
+    }
+
+    let vec = alloc::vec![1];
+
+    defmt::info!("Allocated vector: {:?}", Debug2Format(&vec));
+
+    let string = alloc::string::String::from("Hello, world!");
+
+    defmt::info!("Allocated string: {:?}", Debug2Format(&string));
+
+    semihosting::process::exit(0);
+}
+
+#[panic_handler]
+fn panic(info: &PanicInfo) -> ! {
+    defmt::error!("{}", info);
+    semihosting::process::exit(0);
+}

examples/llff_integration_test.rs

@@ -17,12 +17,12 @@
 #![no_std]
 
 extern crate alloc;
-extern crate panic_semihosting;
 
+use defmt_semihosting as _;
 use alloc::vec::Vec;
-use core::mem::{size_of, MaybeUninit};
+use core::{mem::{MaybeUninit, size_of}, panic::PanicInfo};
 use cortex_m_rt::entry;
-use cortex_m_semihosting::{debug, hprintln};
+use cortex_m as _;
 use embedded_alloc::LlffHeap as Heap;
 
 #[global_allocator]
@@ -67,20 +67,23 @@ fn main() -> ! {
         embedded_alloc::init!(HEAP, 1024);
     }
 
-    #[allow(clippy::type_complexity)]
     let tests: &[(fn() -> (), &'static str)] = &[
         (test_global_heap, "test_global_heap"),
         (test_allocator_api, "test_allocator_api"),
     ];
 
     for (test_fn, test_name) in tests {
-        hprintln!("{}: start", test_name);
+        defmt::info!("{}: start", test_name);
         test_fn();
-        hprintln!("{}: pass", test_name);
+        defmt::info!("{}: pass", test_name);
     }
 
     // exit QEMU with a success status
-    debug::exit(debug::EXIT_SUCCESS);
-    #[allow(clippy::empty_loop)]
-    loop {}
+    semihosting::process::exit(0);
+}
+
+#[panic_handler]
+fn panic(info: &PanicInfo) -> ! {
+    defmt::error!("{}", info);
+    semihosting::process::exit(-1);
 }

examples/tlsf_integration_test.rs

@@ -17,12 +17,12 @@
 #![no_std]
 
 extern crate alloc;
-extern crate panic_semihosting;
+use defmt_semihosting as _;
 
 use alloc::collections::LinkedList;
-use core::mem::MaybeUninit;
+use core::{mem::MaybeUninit, panic::PanicInfo};
 use cortex_m_rt::entry;
-use cortex_m_semihosting::{debug, hprintln};
+use cortex_m as _;
 use embedded_alloc::TlsfHeap as Heap;
 
 #[global_allocator]
@@ -92,13 +92,17 @@ fn main() -> ! {
     ];
 
     for (test_fn, test_name) in tests {
-        hprintln!("{}: start", test_name);
+        defmt::info!("{}: start", test_name);
         test_fn();
-        hprintln!("{}: pass", test_name);
+        defmt::info!("{}: pass", test_name);
     }
 
     // exit QEMU with a success status
-    debug::exit(debug::EXIT_SUCCESS);
-    #[allow(clippy::empty_loop)]
-    loop {}
+    semihosting::process::exit(0);
+}
+
+#[panic_handler]
+fn panic(info: &PanicInfo) -> ! {
+    defmt::error!("{}", info);
+    semihosting::process::exit(-1);
 }

qemu-runner.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# This requires you to previously run `cargo install defmt-print`
+
+# See https://ferroussystems.hackmd.io/@jonathanpallant/ryA1S6QDJx for a description of all the relevant QEMU machines
+ELF_BINARY="$1"
+
+# All suitable for thumbv7em-none-eabihf
+MACHINE="-cpu cortex-m4 -machine mps2-an386"
+# MACHINE="-cpu cortex-m7 -machine mps2-387"
+# MACHINE="-cpu cortex-m7 -machine mps2-500"
+LOG_FORMAT='{[{L}]%bold} {s} {({ff}:{l:1})%dimmed}'
+
+echo "Running on '$MACHINE'..."
+echo "------------------------------------------------------------------------"
+qemu-system-arm $MACHINE -semihosting-config enable=on,target=native -nographic -kernel $ELF_BINARY | defmt-print -e $ELF_BINARY --log-format="$LOG_FORMAT"
+echo "------------------------------------------------------------------------"