Update the rest of the QEMU chapter for app-template - #420
Open
webbgamers wants to merge 1 commit into
Open
Conversation
The `cargo-generate` command in this chapter switched to knurling's `app-template` (and rust-embedded#418 updates the surrounding project-creation prose to match), but everything downstream of project creation still describes `cortex-m-quickstart` and the pre-`defmt` `hprintln!` workflow. Following the chapter as written does not currently produce a running program. Program Overview: show `src/bin/hello.rs` rather than a `src/main.rs` that the template does not have, and explain `use app as _;` instead of `panic_halt`. Cross compiling: the template defaults to `thumbv6m-none-eabi`, so add the missing step of switching TODO(3) to `thumbv7m-none-eabi`. The listing shown before was quickstart's, which had the Cortex-M3 target already selected. Inspecting: the template builds no binary named after the project, so `cargo readobj --bin app` fails; use `--bin hello`. Refresh the captured output and describe every section the output lists -- the refresher previously covered five of them and lumped the rest together as "metadata" -- along with flip-link's inverted RAM layout, which is what readers will actually see. The disassembly excerpt was a truncated dump of `__stext` alone. Show `__stext` and `main` together via `--disassemble-symbols`, which needs no truncation and covers the whole boot path: pre-init hook, zeroing `.bss`, copying `.data`, then the call into the entry point. `-C` demangles the call targets. The body of the entry function itself is a local symbol carrying a crate hash, so it cannot be named on the command line; the text says so rather than offering a command that only works for one build. Running: plain `qemu-system-arm` cannot decode `defmt`, as the chapter itself says two paragraphs earlier, so it can't be the runner and doesn't print "Hello, world!" -- it prints four bytes of binary frame. Set `qemu-run` as the runner instead, under the cfg() table the template actually uses. Install `qemu-run` from crates.io rather than cloning the `defmt` repo; the clone snippet also used an SSH URL and a `../qemu-rs/` path that does not exist. Fix `--example hello` to `--bin hello`. Debugging: pass the GDB flags through `qemu-run` so the log output is still decoded, correct the `examples/hello` paths, and replace the `hprintln!` / `debug::exit` listing with the program the template ships. `cortex-m-rt` writes Reset in assembly now, so GDB stops at a bare address with a misattributed symbol rather than at `cortex-m-rt-0.6.1/src/lib.rs:473`. install/tooling: add `flip-link`, which the template sets as its linker and without which the build fails, and `qemu-run`. Neither was mentioned anywhere. All commands and output were re-run against a fresh `app-template` project. Semihosting, Panicking and Exceptions still print with `hprintln!`, and `qemu-run` swallows that plain text silently rather than erroring, so the chapter now tells readers to switch the runner back to plain `qemu-system-arm` before those chapters. Migrating them to `defmt` would remove the caveat and is probably worth doing, but is left out of this change. The `entry` link also now points at `cortex-m-rt`'s re-export rather than the `cortex-m-rt-macros` page, which carries no documentation of its own.
webbgamers
marked this pull request as ready for review
September 5, 2026 20:20
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
cargo-generatecommand in this chapter switched to knurling'sapp-template(and #418 updates the surrounding project-creation prose to match), but everything downstream of project creation still describescortex-m-quickstartand the pre-defmthprintln!workflow. Following the chapter as written does not currently produce a running program.Program Overview: show
src/bin/hello.rsrather than asrc/main.rsthat the template does not have, and explainuse app as _;instead ofpanic_halt.Cross compiling: the template defaults to
thumbv6m-none-eabi, so add the missing step of switching TODO(3) tothumbv7m-none-eabi. The listing shown before was quickstart's, which had the Cortex-M3 target already selected.Inspecting: the template builds no binary named after the project, so
cargo readobj --bin appfails; use--bin hello. Refresh the captured output and describe every section the output lists -- the refresher previously covered five of them and lumped the rest together as "metadata" -- along with flip-link's inverted RAM layout, which is what readers will actually see.The disassembly excerpt was a truncated dump of
__stextalone. Show__stextandmaintogether via--disassemble-symbols, which needs no truncation and covers the whole boot path: pre-init hook, zeroing.bss, copying.data, then the call into the entry point.-Cdemangles the call targets.Running: plain
qemu-system-armcannot decodedefmt, as the chapter itself says two paragraphs earlier, so it can't be the runner and doesn't print "Hello, world!" -- it prints four bytes of binary frame. Setqemu-runas the runner instead, under the cfg() table the template actually uses. Installqemu-runfrom crates.io rather than cloning thedefmtrepo; the clone snippet also used an SSH URL and a../qemu-rs/path that does not exist. Fix--example helloto--bin hello.Debugging: pass the GDB flags through
qemu-runso the log output is still decoded, correct theexamples/hellopaths, and replace thehprintln!/debug::exitlisting with the program the template ships.cortex-m-rtwrites Reset in assembly now, so GDB stops at a bare address with a misattributed symbol rather than atcortex-m-rt-0.6.1/src/lib.rs:473.install/tooling: add
flip-link, which the template sets as its linker and without which the build fails, andqemu-run. Neither was mentioned anywhere.All commands and output were re-run against a fresh
app-templateproject.Semihosting, Panicking and Exceptions still print with
hprintln!, andqemu-runswallows that plain text silently rather than erroring, so the chapter now tells readers to switch the runner back to plainqemu-system-armbefore those chapters. Migrating them todefmtwould remove the caveat and is probably worth doing.The
entrylink also now points atcortex-m-rt's re-export rather than thecortex-m-rt-macrospage, which carries no documentation of its own.