Update qemu-run so we can publish it and use it in the training examples.

Author: jonathanpallant

firmware/qemu/.cargo/config.toml

@@ -5,7 +5,7 @@ rrb = "-q run --target thumbv7m-none-eabi --release --bin"
 
 [target.'cfg(all(target_arch = "arm", target_os = "none"))']
 # runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"
-runner = "cargo -q run --manifest-path ../../qemu-run/Cargo.toml"
+runner = "cargo -q run --manifest-path ../../qemu-run/Cargo.toml -- --machine lm3s6965evb --verbose"
 
 rustflags = [
   # LLD (shipped with the Rust toolchain) is used as the default linker

qemu-run/Cargo.toml

@@ -1,11 +1,16 @@
 [package]
 authors = ["The Knurling-rs developers"]
+categories = ["embedded"]
+description = "Runs qemu-system-arm but decodes defmt data sent to semihosting"
 edition = "2021"
+keywords = ["knurling", "logging", "formatting", "qemu"]
 license = "MIT OR Apache-2.0"
 name = "qemu-run"
-publish = false
-version = "0.0.0"
+readme = "README.md"
+repository = "https://github.com/knurling-rs/defmt"
+version = "0.1.0"
 
 [dependencies]
 anyhow = "1"
+clap = { version = "4.0", features = ["derive", "env"] }
 defmt-decoder = { version = "=1.0.0", path = "../decoder" }

qemu-run/README.md

@@ -0,0 +1,48 @@
+# `qemu-run`
+
+> Runs [`qemu-system-arm`] but decodes [`defmt`] data sent to semihosting
+
+[`qemu-system-arm`]: https://www.qemu.org/docs/master/system/target-arm.html
+[`defmt`]: https://crates.io/crates/defmt
+
+## Using
+
+Set as your cargo runner, e.g. in your `.cargo/config.toml` file:
+
+```toml
+[target.thumbv7em-none-eabihf]
+runner = "qemu-run -machine lm3s6965evb"
+```
+
+It will execute `qemu-system-arm`, pass the given `-machine` argument, pass
+additional arguments to configure semihosting, and pipe semihosting data into
+`defmt-decoder` to be decoded and printed to the console.
+
+## Support
+
+`defmt-print` is part of the [Knurling] project, [Ferrous Systems]' effort at
+improving tooling used to develop for embedded systems.
+
+If you think that our work is useful, consider sponsoring it via [GitHub
+Sponsors].
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+
+- MIT license ([LICENSE-MIT](../LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+licensed as above, without any additional terms or conditions.
+
+[Knurling]: https://knurling.ferrous-systems.com/
+[Ferrous Systems]: https://ferrous-systems.com/
+[GitHub Sponsors]: https://github.com/sponsors/knurling-rs

qemu-run/src/main.rs

@@ -1,7 +1,9 @@
+//! # qemu-run
+//!
 //! An alternative to the [`probe-run`](https://github.com/knurling-rs/probe-run) printer,
 //! used by [`defmt`](https://github.com/knurling-rs/defmt).
+//!
 //! Parses data sent by QEMU over semihosting (ARM Cortex-M only).
-//! *Printers* are *host* programs that receive log data, format it and display it.
 
 use std::{
     env, fs,
@@ -10,9 +12,35 @@ use std::{
 };
 
 use anyhow::{anyhow, bail};
+use clap::Parser;
 use defmt_decoder::{DecodeError, StreamDecoder, Table};
 use process::Child;
 
+/// Run qemu-system-arm, takes defmt logs from semihosting output and prints them to stdout
+#[derive(clap::Parser, Clone)]
+#[command(name = "qemu-run")]
+struct Opts {
+    /// The firmware running on the device being logged
+    #[arg(required = false, conflicts_with("version"))]
+    elf: Option<std::path::PathBuf>,
+
+    /// Specify the QEMU machine type
+    #[arg(long, required = false)]
+    machine: Option<String>,
+
+    /// Specify the QEMU CPU type
+    #[arg(long, required = false)]
+    cpu: Option<String>,
+
+    /// Print the version number, and quit
+    #[arg(short = 'V', long)]
+    version: bool,
+
+    /// Print the version number, and quit
+    #[arg(short = 'v', long)]
+    verbose: bool,
+}
+
 fn main() -> Result<(), anyhow::Error> {
     notmain().map(|opt_code| {
         if let Some(code) = opt_code {
@@ -22,38 +50,69 @@ fn main() -> Result<(), anyhow::Error> {
 }
 
 fn notmain() -> Result<Option<i32>, anyhow::Error> {
-    let args = env::args().skip(1 /* program name */).collect::<Vec<_>>();
+    let opts = Opts::parse();
+
+    if opts.version {
+        return print_version();
+    }
+
+    let Some(elf_path) = opts.elf else {
+        bail!("ELF filename is required. Syntax: `qemu-run -machine <machine> <path-to-elf>`.");
+    };
 
-    if args.len() != 1 {
-        bail!("expected exactly one argument. Syntax: `qemu-run <path-to-elf>`");
+    let Some(machine) = opts.machine else {
+        bail!("Machine type is required. Syntax: `qemu-run -machine <machine> <path-to-elf>`.");
+    };
+
+    if opts.verbose {
+        eprintln!("QEMU machine is {:?}", machine);
+        if let Some(cpu) = &opts.cpu {          
+            eprintln!("QEMU cpu is {:?}", cpu);
+        }
     }
 
-    let path = &args[0];
-    let bytes = fs::read(path)?;
+    let bytes = fs::read(&elf_path)?;
 
     let table = if env::var_os("QEMU_RUN_IGNORE_VERSION").is_some() {
         Table::parse_ignore_version(&bytes)
     } else {
         Table::parse(&bytes)
     };
-    let table = table?.ok_or_else(|| anyhow!("`.defmt` section not found"))?;
+    let table = match table {
+        Ok(Some(table)) => table,
+        Ok(None) => {
+            bail!("Loaded ELF but did not find a .defmt section");
+        }
+        Err(e) => {
+            bail!("Failed to load ELF: {:?}", e);
+        }
+    };
+
+    let mut command = Command::new("qemu-system-arm");
+    command.args([
+        "-machine",
+        &machine,
+        "-nographic",
+        "-monitor",
+        "none",
+        "-semihosting-config",
+        "enable=on,target=native",
+        "-kernel",
+    ]);
+    command.arg(elf_path);
+    command.stdout(Stdio::piped());
+
+    if let Some(cpu) = &opts.cpu {
+        command.arg("-cpu");
+        command.arg(cpu);
+    }
+
+    if opts.verbose {
+        eprintln!("Running: {:?}", command);
+    }
 
     let mut child = KillOnDrop(
-        Command::new("qemu-system-arm")
-            .args([
-                "-cpu",
-                "cortex-m3",
-                "-machine",
-                "lm3s6965evb",
-                "-nographic",
-                "-monitor",
-                "none",
-                "-semihosting-config",
-                "enable=on,target=native",
-                "-kernel",
-            ])
-            .arg(path)
-            .stdout(Stdio::piped())
+        command
             .spawn()
             .expect("Error running qemu-system-arm; perhaps you haven't installed it yet?"),
     );
@@ -71,24 +130,25 @@ fn notmain() -> Result<Option<i32>, anyhow::Error> {
     loop {
         let n = stdout.read(&mut readbuf)?;
         decoder.received(&readbuf[..n]);
-        decode(&mut *decoder)?;
+        decode_and_print(decoder.as_mut())?;
 
         if let Some(status) = child.0.try_wait()? {
+            // process finished - grab all remaining bytes and quit
             exit_code = status.code();
-
             let mut data = Vec::new();
             stdout.read_to_end(&mut data)?;
             decoder.received(&data);
-            decode(&mut *decoder)?;
-
+            decode_and_print(decoder.as_mut())?;
             break;
         }
     }
 
+    // pass back qemu exit code (if any)
     Ok(exit_code)
 }
 
-fn decode(decoder: &mut dyn StreamDecoder) -> Result<(), DecodeError> {
+/// Pump the decoder and print any new frames
+fn decode_and_print(decoder: &mut dyn StreamDecoder) -> Result<(), DecodeError> {
     loop {
         match decoder.decode() {
             Ok(frame) => {
@@ -110,3 +170,21 @@ impl Drop for KillOnDrop {
         self.0.kill().ok();
     }
 }
+
+/// Report version from Cargo.toml _(e.g. "0.1.4")_ and supported `defmt`-versions.
+///
+/// Used by `--version` flag.
+#[allow(clippy::unnecessary_wraps)]
+fn print_version() -> anyhow::Result<Option<i32>> {
+    println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+    let s = if defmt_decoder::DEFMT_VERSIONS.len() > 1 {
+        "s"
+    } else {
+        ""
+    };
+    println!(
+        "supported defmt version{s}: {}",
+        defmt_decoder::DEFMT_VERSIONS.join(", ")
+    );
+    Ok(Some(0))
+}