liveBook · Manning

Chapter 6: Debugging, observability, and profiling

What you will learn in chapter 6 of Embedded Software with Rust

The introduction explains why observing a bare-metal Rust program requires an explicit path for information to reach the developer.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The introduction explains why observing a bare-metal Rust program requires an explicit path for information to reach the developer.

Key terms: bare-metal Rust application, debug probe

6.1 Debugging fundamentals: methods, interfaces, and protocols

The section explains why embedded debugging differs from desktop debugging and how a host gains visibility into a constrained target.

Key terms: target, host, debug probe, microcontroller

6.1.1 Overview of debugging techniques

This subsection compares debugging approaches by their effect on timing and hardware requirements, and identifies the Arm targets and debug interfaces relevant to the chapter.

Key terms: synchronous logging, breakpoints, semihosting, ITM, RTT, DWT cycle counters, Armv6-M, Armv8-M baseline, Armv7-M, Armv7E-M

6.1.2 The debugging pipeline from host to target

This section maps the four layers of an embedded debugging connection and explains the debug probe’s roles in programming and live debugging.

Key terms: debug host, GDB server or runtime backend, hardware debug probe, target MCU, debug port, debug probe, firmware images, live debug traffic, memory reads, register access

6.1.3 Debug interfaces: JTAG vs. SWD

This section contrasts JTAG and SWD debug interfaces and explains which is commonly used on Cortex-M and RISC-V platforms.

Key terms: JTAG, SWD, Arm Cortex-M, RISC-V, Debug Module Interfaces

6.1.4 Debug probes: hardware interfaces

This section identifies the hardware that connects host debugging tools to an MCU and explains how probe choice and trace support affect a debugging workflow.

Key terms: debug probe, host toolchain, MCU’s debug port, ST-Link, MCU-Link, J-Link, CMSIS-DAP, SWO, ITM-based workflow, data trace

6.2 Printing debug messages in embedded Rust

This section explains why bare-metal Rust needs explicit ways to print debug information and what factors guide the choice.

Key terms: bare-metal, no_std, runtime observability, semihosting, UART, ITM

6.2.1 Semihosting with hprintln!()

This section explains how hprintln!() prints through semihosting, how to enable it in OpenOCD, and why it is unsuitable for some standalone or time-sensitive firmware.

Key terms: semihosting, hprintln!(), cortex-m-semihosting, BKPT 0xAB, debug probe, HardFault, DebugMonitor, no-semihosting, Cortex-M0/M0+, Cortex-M23

6.2.2 UART logging with writeln!()

This section presents UART as a production-capable logging output and notes how the chip-specific example’s output can be viewed on a host computer.

Key terms: UART, serial output, debugger, STM32F103, Blue Pill, stm32f1xx-hal, minicom, screen, PuTTY

6.2.3 ITM logging with iprintln!()

This section explains how ITM sends embedded debug messages over SWO and how to capture and view them on a host.

Key terms: ITM, CoreSight, SWO, ITM port, iprintln!(), <CPU_CLOCK_HZ>, itmdump, -s <port>, -F, OpenOCD

6.2.4 RTT logging with rtt-target

Explains how RTT carries debug output through target RAM, how host tools capture it, and when its probe-dependent logging is useful.

Key terms: Real-Time Transfer (RTT), ring buffer, SWD, JTAG, probe-rs run, cargo-embed, probe-rs crate, Embed.toml, OpenOCD, GDB

6.3 Structured logging with defmt

This section explains how defmt moves log-message formatting from no_std firmware to a host decoder, reducing firmware size and log-call cost.

Key terms: defmt, no_std, token, interned, ELF binary, host decoder

6.3.1 A minimal example

This section clarifies how panic messages reach a defmt transport and how release-build debug information enables source locations in logs.

Key terms: defmt, Format trait, panic-probe, print-defmt, print-rtt, RTT, DWARF, debug=2, probe-rs

6.3.2 Transport backends

This section separates defmt’s binary log generation from transport to the host and explains how to choose one transport backend.

Key terms: defmt, binary log frames, transport crate, logging API, defmt-rtt, RTT, defmt-itm, SWO, defmt-semihosting, QEMU

6.3.3 Linker setup

Explains how defmt’s linker metadata is provided without requiring a manual change to memory.x in normal use.

Key terms: defmt, dedicated linker section, interned format strings, log metadata, transport crates, build scripts

6.3.4 Host-side tooling

This section explains how host tools use ELF metadata to decode defmt logs and flash and monitor a target.

Key terms: defmt, ELF symbol table, metadata section, log frame, probe-rs run, cargo-embed

6.3.5 Configuring cargo-embed with Embed.toml

Explains how Embed.toml profiles configure cargo-embed and how target, probe, and reset settings affect a flashing session.

Key terms: Embed.toml, cargo embed, default profile, named profiles, chip, probe-rs target identifier, probe-rs chip list, [default.probe], SWD, JTAG

6.3.6 Comparative summary

Compares the availability of Cortex-M debugging and logging techniques on RISC-V targets.

Key terms: RISC-V, UART, semihosting, riscv-semihosting, ITM, RTT, JTAG, SWD, ARM CoreSight DAP, hybrid SoCs

6.4 Handling panics in embedded applications

Explains why bare-metal Rust needs an explicit panic handler and how panic messages use existing logging channels.

Key terms: no_std, core, #[panic_handler], panic = "abort", stack unwinding, panic-semihosting, panic-itm, panic-probe, defmt, RTT

6.4.1 When and why panics occur

This subsection identifies operations that can trigger a panic in embedded Rust.

Key terms: panic, runtime safety guarantees, Result::Err, Option::None, panic!(), debug_assert!()

6.4.2 Available panic handler crates

Compares ready-made panic behaviors for different deployment contexts and explains how importing a panic-handler crate selects its handler.

Key terms: panic-halt, panic-abort, HardFault handler, sys_reset(), panic-semihosting, panic-itm, panic-probe, ITM/SWO, print-defmt, use panic_xxx as _;

6.4.3 Minimal handler implementation

This section describes the minimal panic handler required without a pre-built crate and explains why it must never return.

Key terms: #[panic_handler], PanicInfo, panic-halt, ! return type

6.4.4 Logging-integrated panic handlers

This section explains how to select a logging-integrated panic handler and why UART is an exception.

Key terms: transport, panic crate, dependency entry, wildcard import, UART

6.4.5 Conditional panic behavior with Cargo features

Shows how a Cargo feature selects a diagnostic or silent panic handler from the same firmware source tree.

Key terms: debug-panic, Cargo feature flags, #[cfg(… )], panic handler, semihosting output

6.4.6 Fault handlers and exception frame recovery

This section shows how Cortex-M fault handlers can report saved execution context and fault-status information to help locate and classify failures.

Key terms: HardFault, ExceptionFrame, panic!(), panic output channel, pc, lr, arm-none-eabi-addr2line, ELF file, MemoryManagement, BusFault

6.5 Interactive debugging & on-chip debugging

The section explains why inspecting a variable on an embedded target requires a debug toolchain rather than the direct introspection available in desktop debugging.

Key terms: introspection, debug pins, GDB, OpenOCD, debug probe

6.5.1 Choosing a toolchain: GDB + OpenOCD vs. probe-rs

This section explains how GDB with OpenOCD and probe-rs differ, and how to choose between them for embedded Rust debugging.

Key terms: GNU GDB, OpenOCD, GDB remote serial protocol, debug probe, JTAG, SWD, probe-rs, GDB+OpenOCD, Cargo, RTT logging

6.5.2 GDB for embedded systems

This section explains GDB’s role in embedded debugging, why it needs a GDB server to reach the target, and how to choose a GDB build for the target architecture.

Key terms: GDB, GDB server, remote serial protocol, debug probe, JTAG, SWD, gdb-multiarch, arm-none-eabi-gdb, riscv32-unknown-elf-gdb, riscv64-unknown-elf-gdb

6.5.3 GDB interfaces: CLI, TUI, and GUIs

This section identifies terminal and graphical interfaces for interactive debugging and distinguishes VSCode’s GDB-based and direct probe-rs connections.

Key terms: gdb --tui, GDB-Dashboard, .gdbinit, GDBGUI, DDD, VSCode, Cortex-Debug, probe-rs, Debug Adapter Protocol

6.5.4 Common GDB command groups

This section groups GDB commands by their roles in a remote-debug session, from connecting and loading firmware to controlling execution and inspecting memory.

Key terms: GDB server, extended-remote, debug probe, load, monitor, reset halt, continue, run, breakpoints, x command

6.5.5 OpenOCD: GDB’s embedded debugging backend

This section explains OpenOCD’s role between GDB and an embedded target, and how to select its configuration files and start its GDB server.

Key terms: OpenOCD, GDB server, debug probe, GDB’s remote serial protocol, JTAG, SWD, interface/stlink.cfg, target/stm32f1x.cfg, openocd.cfg, port 3333

6.5.6 Launching a debugging session

This section describes how to start an OpenOCD–GDB session, load symbols, connect and flash the target, and enable semihosting.

Key terms: OpenOCD, GDB, port 3333, semihosting interception, hprintln!(), ELF, symbol table, breakpoint, Function not defined, extended-remote

6.5.7 Automating GDB with a configuration file

This section explains how to reuse GDB startup commands from a project configuration file, why to load it explicitly, and what its breakpoint and optional ITM settings require.

Key terms: .gdbinit, -x, auto-load safe-path, rust_begin_unwind, DefaultHandler, HardFault, #[panic_handler], ITM, SWO, TPIU

6.6 Profiling & Performance analysis in embedded Rust

This section explains why embedded profiling needs measured execution time and why the way measurements are reported must not distort them.

Key terms: deadline, cycle counts, clock speed, wall-clock time, semihosting, RTT, direct register access

6.6.1 The DWT cycle counter

Explains how the Cortex-M DWT cycle counter measures code execution in CPU cycles, where it is available, and the corresponding RISC-V counter.

Key terms: DWT, CYCCNT, CPU clock cycle, Cortex-M7, DWT::unlock(), mcycle, mcycleh, RV32, CSR

6.6.2 Setting up DWT in embedded Rust

This section explains how embedded Rust accesses the memory-mapped DWT safely through the cortex-m crate rather than raw pointers.

Key terms: Data Watchpoint and Trace unit, DWT, Debug Control Block, DCB, cortex-m crate, memory mapped

6.6.3 Example: Measuring function execution time

The section illustrates timing two tasks with a cycle counter and explains why wrapping subtraction gives the correct elapsed cycle count.

Key terms: CYCCNT, wrapping_sub, RTT

6.6.4 Example: SysTick-based timing for cores without DWT

This section explains how to use SysTick to estimate elapsed CPU cycles when DWT is unavailable, including wraparound limits and conflicts with other uses of the timer.

Key terms: SysTick, DWT, core clock, 24-bit down-counter, start.wrapping_sub(end), 24-bit mask, reload period, software wrap counter, RTOS, delay routine

6.6.5 Platform notes

This section describes a GPIO-based way to time code on cores without a DWT cycle counter.

Key terms: DWT, SysTick, GPIO pin, pulse width, logic analyzer, oscilloscope

6.7 Summary

Concepts explained in this chapter

← Chapter 5: Memory-Mapped I/O, Register Abstractions, and Low-Level Control on Cortex-M Chapter 7: Managing stack and heap in resource-constrained systems →

These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.