Skip to content

Update the rest of the QEMU chapter for app-template - #420

Open
webbgamers wants to merge 1 commit into
rust-embedded:masterfrom
webbgamers:fix/qemu-chapter-post-app-template
Open

Update the rest of the QEMU chapter for app-template#420
webbgamers wants to merge 1 commit into
rust-embedded:masterfrom
webbgamers:fix/qemu-chapter-post-app-template

Conversation

@webbgamers

Copy link
Copy Markdown

The cargo-generate command in this chapter switched to knurling's app-template (and #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.

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.

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.

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
webbgamers marked this pull request as ready for review September 5, 2026 20:20
@webbgamers
webbgamers requested a review from a team as a code owner September 5, 2026 20:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant