Chapter 2: Setting up your Rust tool-chain
This chapter introduction previews the tools and workflows for setting up an embedded Rust development environment.
After this chapter you will be able to
- Embedded Rust resource constraints. Explain why embedded Rust commonly uses no_std and what that means for allocation compared with desktop Rust.
- Rustup tool-chain management. Explain what rustup manages and why it is useful for embedded Rust development.
- Target selection and output. Explain what a Rust target specifies and why selecting one matters when compiling for embedded hardware.
- Embedded target triple meaning. Explain what a Rust target triple describes and interpret the embedded examples at the level shown here: their architecture or device family, bare-metal system designation, and, for the ARM example, hardware floating-point support.
- Floating-point ABI selection. Explain how to choose between eabihf and eabi when selecting an Arm target triple.
- Arm architecture identification. Describe why the Cortex-M family name alone is not enough to choose a target, and how to confirm the device’s architecture and features.
- rustc in embedded development. Explain that rustc serves a role comparable to GCC or Clang for C and C++, providing optimization, cross-compilation, and support for embedded architectures.
- Commercial tool-chain trade-off. Distinguish the usual sufficiency of open-source rustc for general embedded projects from the potential value of commercial tool-chains for certified or safety-critical applications.
- VSCode extension roles. Describe how the suggested VSCode extensions support embedded Rust work, including Rust code intelligence, device debugging, assembly highlighting, and serial communication.
- Embedded binary artifact needs. Explain why an embedded Rust workflow needs more than familiar desktop Cargo commands, naming the output formats the section identifies and what the artifacts are used for.
- Cross-compiling with Cargo. Explain that Cargo’s --target flag specifies the embedded target architecture, causing Cargo to invoke rustc to cross-compile a no_std bare-metal executable for that target.
- ELF artifact contents and uses. Describe the generated ELF file as containing machine code, symbols, and debug metadata, and explain its use both as a debugging target and as an intermediate file for conversion to a flashable image.
- Embedded binary inspection tools. Distinguish what cargo nm, cargo size, cargo objdump, and cargo readobj reveal about a compiled embedded binary.
- ELF conversion for flashing. Explain why cargo objcopy converts an ELF file to a raw binary or Intel HEX file for flashing, and what the `--` separator means when passing objcopy arguments.
- GNU binutils in embedded work. Explain what GNU binutils are used for in embedded Rust and why they remain useful alongside newer Rust tools.
- Binary identity and contents. Describe how file identifies a binary’s format and architecture, while hexdump or xxd reveals raw bytes and strings finds printable text in a firmware image.
- Symbols and ELF structure. Distinguish using nm to locate symbols from using readelf to inspect ELF headers, sections, and symbol tables when checking a binary’s layout.
- Firmware section size estimates. Explain how size reports section sizes and how its .text, .data, and .bss overview helps estimate FLASH and RAM usage.
- Flash image format conversion. Explain why objcopy is used to produce .bin or .hex images from an ELF executable for flashing.
- Template-based project setup. Explain why starting an embedded Rust project by hand is burdensome and how templates used with cargo generate offer a faster starting point.
- Cargo generate setup and purpose. Explain that cargo-generate is installed using Cargo before it can be used, and that the cargo generate sub-command creates a new Cargo project from a template in a remote Git repository.
- Template generation and setup choices. Describe how cargo-generate starts a project from stm32-template and what the example setup wizard asks the reader to choose.
- Generated embedded project components. Explain what the template produces and how those generated pieces reduce initial setup work.
- Project target configuration. Explain where a generated project specifies its target triple and when that setting needs to change.
- Device memory layout settings. Explain what memory.x must match, why its accuracy matters, and where to find the device’s memory map.
- Firmware deployment with OpenOCD. Explain that a built firmware binary may need transformation before it is given to OpenOCD, and that OpenOCD can flash a microcontroller as well as bridge GDB to a debug probe.
- SWD and JTAG trade-offs. Explain why SWD is usually preferred for Cortex-M projects while JTAG remains useful for advanced debugging.
- Adapter and target configuration. Describe why OpenOCD needs a configuration file for both the debug adapter and target microcontroller, and where to find available interface and target configurations.
- Firmware flashing outcome. Describe what the section says OpenOCD does when used to flash a built firmware binary to the device.
- Flashing tool trade-offs. Explain why a vendor-specific utility may be convenient for simple flashing, while OpenOCD remains useful across hardware platforms for debugging, scripting, and automation.
- Board firmware workflow. Describe the example workflow: start from the stm32-template project, add semihosting dependencies and an entry point, ensure the ARM Cortex-M3 target is available, build the firmware, then program a connected board with semihosting enabled. State where the resulting message appears.
- Hardware-free testing benefits. Explain why emulation and simulation are useful early in development or when hardware is unavailable, while recognizing that running code on real hardware remains the ultimate test.
- Knurling workflow trade-off. Explain that Knurling offers an optional, more integrated bare-metal Rust workflow that can ease setup and day-to-day development without replacing established OpenOCD/GDB workflows.
- Probe communication and Cargo runner. Explain that probe-rs supplies probe communication and target control for higher-level tools, and that configuring it as a Cargo runner lets cargo run flash and start firmware on the target.
- Flashing and debugging tool choices. Distinguish cargo-flash from cargo-embed by what each offers and when the simpler flashing workflow is sufficient.
- Knurling setup and template limits. Describe the setup sequence: have cargo-binstall available, follow the probe.rs installation instructions, install flip-link, and create a Knurling-based project. Explain what the generated project configures and what must still be done manually.
- Traditional and Knurling workflows. Contrast the manual build, flash, and semihosting setup of the traditional workflow with Knurling’s project generation and single-command compile, flash, and run workflow.
- Efficient defmt logging. Explain why the section presents defmt over RTT as better suited to frequent logging than semihosting.
- Blue Pill target configuration. Explain how .cargo/config.toml selects the Blue Pill chip for probe-rs and the appropriate compiler target for its Cortex-M3 core.
- Hardware run and output. Trace what happens when the configured project is run with a compatible debug adapter, and describe what the visible output demonstrates.
- Knurling and traditional workflow tradeoffs. Explain why a developer might favor Knurling for everyday development while still using traditional tools for detailed debugging, and why the book primarily uses GDB and OpenOCD.
- Benefits of firmware emulation. Explain why an embedded Rust developer might run firmware in an emulator instead of on a physical board.
- Software-Based Development Benefits. Explain how running firmware in an emulator can ease early development compared with repeatedly flashing a physical board.
- Emulation Fidelity Limits. Distinguish what emulator tests can check from what may still need testing on a physical device.
- QEMU capabilities and limits. Explain what QEMU system mode emulates, what kinds of firmware work it can help test, and why emulation does not replace a physical board for long-term development.
- Emulated board project adaptation. Describe how the example project is retargeted from the Blue Pill to a supported QEMU board before its firmware is run.
- Semihosting and runner configuration. Describe how the example displays output in QEMU and how its runner differs from one targeting a physical board.
- Renode capabilities and use cases. Explain what kinds of systems Renode can model and why it may be preferable to QEMU for some tests.
- PICSimLab’s visual simulation role. Explain that PICSimLab lets users visualize and interact with simulated microcontroller circuits and common peripherals, making it useful for education, rapid prototyping, and work that benefits from visual feedback.
- Wokwi simulation and Rust use. Describe Wokwi’s interactive, web-based simulation and explain that embedded Rust development uses Wokwi as a VSCode extension.
What it builds on
- What no_std excludes and what core provides (chapter 1) · The distinction between no_std and standard-library support.
- What minimal runtime crates initialize (chapter 1) · The role of minimal runtime crates in embedded Rust.
Section by section
Introduction
This chapter introduction previews the tools and workflows for setting up an embedded Rust development environment.
2.1 Setting up your embedded Rust environment
This section introduces the upcoming setup of an embedded Rust toolchain and editor and states the assumed background.
2.1.1 A brief word about embedded Rust vs. desktop Rust
Contrasts the support available to desktop Rust programs with the minimal environment and runtime support typical of embedded Rust.
- Embedded Rust resource constraints: Explain why embedded Rust commonly uses no_std and what that means for allocation compared with desktop Rust.
Why it matters: This explains why an embedded Rust project cannot simply assume desktop libraries and allocation are available. - Specialized bare-metal runtime crates: Describe what specialized runtime crates provide for bare-metal embedded Rust and identify the architecture examples given.
Why it matters: These crates provide basic program support that a bare-metal system does not supply as a desktop runtime would.
Key terms: no_std, standard library, heap allocation, static allocation, custom allocators, cortex-m-rt, riscv-rt, startup code, exception handling, bare-metal
2.1.2 Installing and using rustup
This subsection introduces rustup as Rust’s tool-chain manager and outlines how to install it, keep the tool-chain updated, and inspect installed components.
- Rustup tool-chain management: Explain what rustup manages and why it is useful for embedded Rust development.
Why it matters: Rustup provides the tool-chain management needed when developing for different embedded targets. - Tool-chain setup checks: Describe the setup actions the subsection recommends after introducing rustup.
Why it matters: Updating and inspecting the installation helps establish what Rust tooling is available.
Key terms: rustup, tool-chain, cross-compile, targets, core Rust tool-chain, tool-chains, components
2.1.3 Managing embedded targets
This section explains how Rust targets select a compilation environment, how target support is managed, and what Rust’s support tiers indicate.
- Target selection and output: Explain what a Rust target specifies and why selecting one matters when compiling for embedded hardware.
Why it matters: Choosing the intended target keeps an embedded build from silently targeting the development computer. - Installed target management: Describe the target-management actions mentioned for checking installed targets, adding support for new hardware, and removing a previously installed target.
Why it matters: Installed target support determines which hardware environments the toolchain is prepared to compile for. - Platform support tiers: Distinguish Rust’s three platform-support tiers by the maturity and maintenance they indicate.
Why it matters: A platform’s tier signals how complete and dependable its Rust toolchain support is likely to be.
Key terms: target, rustc, architecture, Application Binary Interface, installed targets, rustup target remove, Tier 1, Tier 2, Tier 3, platform support
2.1.4 Targets and target triples explained
This section explains how Rust target triples identify an embedded program’s intended hardware and bare-metal environment.
- Embedded target triple meaning: Explain what a Rust target triple describes and interpret the embedded examples at the level shown here: their architecture or device family, bare-metal system designation, and, for the ARM example, hardware floating-point support.
Why it matters: Reading a target triple helps you recognize which embedded device and environment a Rust target describes.
Key terms: target triple, architecture, vendor, system, ABI, bare-metal
2.1.5 Common pitfalls in target setup
This section explains two common target-selection pitfalls: choosing the right floating-point ABI and identifying the device’s Arm architecture and features.
- Floating-point ABI selection: Explain how to choose between eabihf and eabi when selecting an Arm target triple.
Why it matters: Matching the ABI to the hardware avoids a common target-setup mistake. - Arm architecture identification: Describe why the Cortex-M family name alone is not enough to choose a target, and how to confirm the device’s architecture and features.
Why it matters: Checking the specific core and device documentation helps prevent selecting a target for the wrong Arm variant.
Key terms: ABI, target triple, eabihf, eabi, hardware floating-point, Arm sub-families, Cortex-M0+, Cortex-M3, Arm v6-M, Arm v7-M
2.1.6 Understanding rustc and compiler alternatives
This section positions rustc as the usual embedded Rust compiler and explains when a commercial tool-chain may be worth considering.
- rustc in embedded development: Explain that rustc serves a role comparable to GCC or Clang for C and C++, providing optimization, cross-compilation, and support for embedded architectures.
Why it matters: You can use rustc for ordinary embedded projects without assuming that embedded Rust requires a separate compiler. - Commercial tool-chain trade-off: Distinguish the usual sufficiency of open-source rustc for general embedded projects from the potential value of commercial tool-chains for certified or safety-critical applications.
Why it matters: The choice of compiler tool-chain can depend on certification needs rather than basic embedded capability.
Key terms: rustc, optimization, cross-compilation, embedded architectures, commercial compilers, safety-critical, certified applications, validation
2.1.7 IDE and editor setup: VSCode
Recommends VSCode for most embedded Rust developers, identifies useful extensions, and notes alternatives for readers who prefer modal editors.
- VSCode extension roles: Describe how the suggested VSCode extensions support embedded Rust work, including Rust code intelligence, device debugging, assembly highlighting, and serial communication.
Why it matters: The extensions give VSCode practical support for several common embedded Rust tasks. - Editor choice and alternatives: Explain why the author recommends VSCode to most readers while acknowledging other editor choices for Rust development.
Why it matters: You can choose an editor that suits you rather than treating VSCode as mandatory.
Key terms: VSCode, Rust Analyzer, Cortex-Debug, Debugger for probe-rs, Arm Assembly, Serial Monitor, vim, Helix, Zed, modal editor
2.2 Expanding cargo: Building, generating, and inspecting binaries
This section introduces why embedded Rust workflows must generate and inspect target-specific binaries, not just compile and link code.
- Embedded binary artifact needs: Explain why an embedded Rust workflow needs more than familiar desktop Cargo commands, naming the output formats the section identifies and what the artifacts are used for.
Why it matters: The format and contents of a build artifact matter when you need to put firmware on a device or check what was built.
Key terms: target-specific artifacts, ELF, raw binary (.bin), Intel HEX (.hex)
2.2.1 Building embedded binaries with cargo
This section explains how Cargo builds bare-metal Rust programs for an embedded target, where it puts debug and release artifacts, and what the resulting ELF files contain.
- Cross-compiling with Cargo: Explain that Cargo’s --target flag specifies the embedded target architecture, causing Cargo to invoke rustc to cross-compile a no_std bare-metal executable for that target.
Why it matters: Selecting the target is the first step in producing an executable for the intended device. - Build profiles and artifact paths: Distinguish debug and release builds, noting that release enables optimizations for code size and performance, and describe how the target architecture and profile determine the artifact’s path under target/.
Why it matters: The target and profile directories tell you where to find the build you intend to use. - ELF artifact contents and uses: Describe the generated ELF file as containing machine code, symbols, and debug metadata, and explain its use both as a debugging target and as an intermediate file for conversion to a flashable image.
Why it matters: Knowing what the ELF file is helps you recognize its place in debugging and preparing firmware for flashing.
Key terms: Cargo, --target, cross-compile, rustc, no_std, debug build, release build, target/, build profile, ELF
2.2.2 Installing and using cargo-binutils
This section shows how to add cargo-binutils to the Rust toolchain and use its subcommands to inspect embedded binaries or convert them for flashing.
- Cargo binutils toolchain setup: Describe the two prerequisites for using cargo-binutils: installing the crate and adding the LLVM tools component to the Rust toolchain.
Why it matters: Both additions are needed before the inspection and conversion subcommands are available. - Embedded binary inspection tools: Distinguish what cargo nm, cargo size, cargo objdump, and cargo readobj reveal about a compiled embedded binary.
Why it matters: Choosing the right inspection tool helps you check placement, memory use, generated code, or ELF metadata. - ELF conversion for flashing: Explain why cargo objcopy converts an ELF file to a raw binary or Intel HEX file for flashing, and what the `--` separator means when passing objcopy arguments.
Why it matters: Conversion produces the file format a microcontroller flasher typically expects.
Key terms: cargo-binutils, LLVM tools component, rustup components, cargo nm, cargo size, cargo objdump, cargo readobj, ELF, cargo objcopy, raw binary
2.3 Oldies but goodies: The GNU binary utilities
This section explains why GNU binutils remain useful alongside Rust tooling for embedded firmware work and notes how developers can access them.
- GNU binutils in embedded work: Explain what GNU binutils are used for in embedded Rust and why they remain useful alongside newer Rust tools.
Why it matters: Binutils can help you work with firmware even when you primarily use Rust tooling. - Access to GNU binutils: State how developers can typically obtain GNU binutils on Linux, macOS, and Windows.
Why it matters: Knowing where to get the tools helps you follow the later examples on your platform.
Key terms: GNU binary utilities, binutils, embedded firmware, apt, brew, Windows Subsystem for Linux (WSL)
2.3.1 Overview of key tools
This section shows how GNU binary utilities help inspect, verify, convert, and prepare embedded firmware binaries.
- Binary identity and contents: Describe how file identifies a binary’s format and architecture, while hexdump or xxd reveals raw bytes and strings finds printable text in a firmware image.
Why it matters: These checks help you recognize an image and spot expected data before flashing it. - Symbols and ELF structure: Distinguish using nm to locate symbols from using readelf to inspect ELF headers, sections, and symbol tables when checking a binary’s layout.
Why it matters: Symbol and ELF inspection lets you check what the linker actually put into the firmware. - Firmware section size estimates: Explain how size reports section sizes and how its .text, .data, and .bss overview helps estimate FLASH and RAM usage.
Why it matters: A quick size check helps you manage limited device memory. - Flash image format conversion: Explain why objcopy is used to produce .bin or .hex images from an ELF executable for flashing.
Why it matters: Building an ELF does not necessarily give a flashing tool the image format it expects. - Generated instruction inspection: Describe how objdump disassembles a binary so you can review compiler-generated machine instructions for verification or troubleshooting.
Why it matters: Looking at generated instructions can reveal low-level problems that source code alone does not show. - Release binary stripping tradeoff: Explain how strip reduces binary size by removing debug information and symbol tables, and why that makes debugging harder.
Why it matters: The smallest deployable image may be less useful when diagnosing a problem.
Key terms: file, hexdump, xxd, strings, nm, readelf, symbols, ELF, size, .text
2.4 Streamlining bare-metal Rust development
This section explains why project templates and cargo generate can make starting a bare-metal Rust project less laborious and error-prone.
- Template-based project setup: Explain why starting an embedded Rust project by hand is burdensome and how templates used with cargo generate offer a faster starting point.
Why it matters: A template lets you spend less time on initial configuration and get to hardware logic sooner.
Key terms: project templates, cargo generate, compatible repository, boilerplate setup
2.4.1 Installing the cargo-generate sub-command
This section explains that cargo-generate must be installed with Cargo before it can create projects from remote Git templates.
- Cargo generate setup and purpose: Explain that cargo-generate is installed using Cargo before it can be used, and that the cargo generate sub-command creates a new Cargo project from a template in a remote Git repository.
Why it matters: This establishes what to install before using a project template and what the utility produces.
Key terms: cargo-generate, cargo generate sub-command, remote Git repository, template
2.4.2 Using a project template with cargo-generate
The section shows how cargo-generate uses stm32-template to create a configured embedded Rust project for an STM32 microcontroller.
- Template generation and setup choices: Describe how cargo-generate starts a project from stm32-template and what the example setup wizard asks the reader to choose.
Why it matters: These choices tailor the generated project to the example board and application. - Generated embedded project components: Explain what the template produces and how those generated pieces reduce initial setup work.
Why it matters: With the basic project structure and configuration in place, the reader can move sooner to hardware-specific code.
Key terms: cargo-generate, stm32-template, STM32F103C8T6, last-release, Cargo project layout, .cargo/config.toml, target triple, memory.x, cortex-m-rt
2.4.3 Making sense of project’s settings
This section identifies the target and memory settings to check when adapting a generated project to a particular microcontroller.
- Project target configuration: Explain where a generated project specifies its target triple and when that setting needs to change.
Why it matters: Checking the target setting helps ensure the generated project matches the device you intend to use. - Device memory layout settings: Explain what memory.x must match, why its accuracy matters, and where to find the device’s memory map.
Why it matters: A template’s memory settings are useful only if they match the actual device.
Key terms: [build], .cargo/config.toml, target triple, memory.x, FLASH, RAM, linker, runtime, technical reference manual
2.5 Getting your firmware onto the device and execution/testing options
Introduces the step from building embedded Rust firmware to deploying it on hardware, including OpenOCD’s flashing role.
- Firmware deployment with OpenOCD: Explain that a built firmware binary may need transformation before it is given to OpenOCD, and that OpenOCD can flash a microcontroller as well as bridge GDB to a debug probe.
Why it matters: It connects the build output to the next practical step of getting firmware onto a device.
Key terms: linked binaries, OpenOCD, GDB, debug probe, flashing
2.5.1 Common debug interfaces
Compares SWD, JTAG, and UART bootloaders for programming and debugging microcontrollers, explaining why SWD is usually preferred for Cortex-M projects.
- SWD and JTAG trade-offs: Explain why SWD is usually preferred for Cortex-M projects while JTAG remains useful for advanced debugging.
Why it matters: These trade-offs help you choose an interface for a Cortex-M project. - UART bootloader use cases: Distinguish firmware loading through a UART bootloader from the advanced debugging offered by hardware debug interfaces.
Why it matters: A convenient way to flash firmware may not provide the debugging needed during development.
Key terms: Serial Wire Debug (SWD), Joint Test Action Group (JTAG), Cortex-M, boundary scan, trace, UART bootloaders, firmware, initial flashing, field updates
2.5.2 Installing and using OpenOCD
Introduces OpenOCD, how to install and configure it for a debugger and target, and what happens when it flashes firmware.
- OpenOCD purpose and installation: Explain that OpenOCD connects hardware debuggers and microcontrollers over SWD or JTAG, and describe the installation options given for Linux, macOS, and Windows.
Why it matters: It identifies the tool that will connect your development machine to the board through a debugger. - Adapter and target configuration: Describe why OpenOCD needs a configuration file for both the debug adapter and target microcontroller, and where to find available interface and target configurations.
Why it matters: Selecting configurations for both pieces of hardware lets OpenOCD communicate with the intended board. - Firmware flashing outcome: Describe what the section says OpenOCD does when used to flash a built firmware binary to the device.
Why it matters: Flashing is the step that puts the built firmware onto the device and starts the new code.
Key terms: OpenOCD, SWD, JTAG, openocd.cfg, scripts directory, interface/, target/, flashing, firmware, verifies
2.5.3 Vendor-specific CLI alternatives
This subsection compares vendor-specific firmware flashing utilities with OpenOCD and gives STM32 and ESP32 examples.
- Flashing tool trade-offs: Explain why a vendor-specific utility may be convenient for simple flashing, while OpenOCD remains useful across hardware platforms for debugging, scripting, and automation.
Why it matters: The task determines whether a focused flashing utility or a more flexible tool is the better fit. - STM32 and ESP32 flashing paths: Describe the two example utilities and how each uploads firmware: st-flash over an ST-Link adapter for STM32, and esptool.py over UART for ESP32.
Why it matters: These examples show that the flashing utility and connection depend on the device.
Key terms: vendor-specific tools, OpenOCD, flashing, STM32, st-flash, stlink, ST-Link, ESP32, esptool.py
2.5.4 Example: Running the firmware on the board
Walks through building and running a minimal semihosting “Hello World” firmware on a connected STM32 board.
- Board firmware workflow: Describe the example workflow: start from the stm32-template project, add semihosting dependencies and an entry point, ensure the ARM Cortex-M3 target is available, build the firmware, then program a connected board with semihosting enabled. State where the resulting message appears.
Why it matters: It connects the build and programming steps to an observable result on the board.
Key terms: stm32-template, semihosting, ARM Cortex-M3 target, OpenOCD console
2.5.5 Testing and execution without hardware
This section explains when emulation and simulation help test embedded software without hardware and identifies several available platforms.
- Hardware-free testing benefits: Explain why emulation and simulation are useful early in development or when hardware is unavailable, while recognizing that running code on real hardware remains the ultimate test.
Why it matters: You can keep testing and making progress before you have a board, without mistaking simulation for final hardware validation. - Hardware-free platform options: Describe the kinds of hardware-free testing environments named here, using examples and their stated distinguishing features.
Why it matters: The named options show that testing without hardware can take different forms depending on the project.
Key terms: emulation, simulation, continuous integration, automated testing, QEMU, Renode, PICSimLab, Wokwi
2.6 A Pragmatic Bare-Metal Development Environment with the Knurling Tools
Introduces Knurling as an optional, productivity-focused alternative for bare-metal Rust development.
- Knurling workflow trade-off: Explain that Knurling offers an optional, more integrated bare-metal Rust workflow that can ease setup and day-to-day development without replacing established OpenOCD/GDB workflows.
Why it matters: This helps you decide whether a more integrated workflow is useful without assuming it is required.
Key terms: Knurling suite, bare-metal Rust, edit–build–flash cycle, OpenOCD/GDB-based workflows
2.6.1 Key Tools in the Knurling Ecosystem
This section identifies the complementary Knurling tools and explains what each contributes to building, deploying, observing, and starting an embedded Rust project.
- Probe communication and Cargo runner: Explain that probe-rs supplies probe communication and target control for higher-level tools, and that configuring it as a Cargo runner lets cargo run flash and start firmware on the target.
Why it matters: It explains how an ordinary Cargo command can deploy firmware to a board. - Flashing and debugging tool choices: Distinguish cargo-flash from cargo-embed by what each offers and when the simpler flashing workflow is sufficient.
Why it matters: The distinction helps you choose a deployment command based on whether you need live feedback or debugging. - Compact RTT logging with defmt: Describe what defmt provides over RTT and why this logging approach can suit performance-sensitive code.
Why it matters: It identifies the logging option in the toolset and the performance reason for using it. - Robust layout and project scaffold: Describe the distinct supporting roles of flip-link and the Knurling app-template.
Why it matters: These tools address project setup and firmware robustness rather than flashing or logging.
Key terms: probe-rs, Cargo runner, .cargo/config.toml, cargo-flash, cargo-embed, RTT terminal, GDB server, Embed.toml, defmt, defmt-rtt
2.6.2 Installing and setting up Knurling tools
This subsection outlines how to set up Knurling tools and create a project, while noting that the generated template still needs microcontroller-specific configuration.
- Knurling setup and template limits: Describe the setup sequence: have cargo-binstall available, follow the probe.rs installation instructions, install flip-link, and create a Knurling-based project. Explain what the generated project configures and what must still be done manually.
Why it matters: The template gives you a configured starting point, but you must adapt it to your particular microcontroller.
Key terms: cargo binstall, flip-link, Knurling-based project, Cortex-M
2.6.3 Contrasting Knurling and traditional embedded Rust workflows
This section contrasts the manual steps of a traditional embedded Rust workflow with Knurling’s faster build-and-run workflow and more efficient logging.
- Traditional and Knurling workflows: Contrast the manual build, flash, and semihosting setup of the traditional workflow with Knurling’s project generation and single-command compile, flash, and run workflow.
Why it matters: The comparison explains why Knurling can make repeated firmware tests quicker. - Efficient defmt logging: Explain why the section presents defmt over RTT as better suited to frequent logging than semihosting.
Why it matters: Logging overhead matters when observing firmware that must meet timing requirements.
Key terms: stm32-template, cargo generate, probe-rs, OpenOCD, RTT, defmt, semihosting, real-time requirements, binary-encoded
2.6.4 Practical Example: "Hello World" with Knurling on the Blue Pill board
Walks through adapting a Knurling app template for the Blue Pill, then running it on hardware and observing RTT output.
- Blue Pill project prerequisites: Describe the project files and prerequisites named in the walkthrough: scaffold a Knurling app, include the STM32F1xx dependencies, create src/bin/phoenix.rs, and provide a root-level memory.x file.
Why it matters: These are the project pieces the example calls for before running the firmware. - Blue Pill target configuration: Explain how .cargo/config.toml selects the Blue Pill chip for probe-rs and the appropriate compiler target for its Cortex-M3 core.
Why it matters: The chip selection and compiler target configure different parts of the build-and-run workflow. - Hardware run and output: Trace what happens when the configured project is run with a compatible debug adapter, and describe what the visible output demonstrates.
Why it matters: The output confirms that the example reached the board and that its logging path works.
Key terms: Knurling app template, Cargo.toml, src/bin, phoenix.rs, memory.x, .cargo/config.toml, runner, probe-rs, STM32F103C8, Cortex-M3
2.6.5 Traditional vs Knurling workflows
This section contrasts Knurling’s productivity benefits with traditional tools’ value for low-level debugging and explains why the book continues with GDB and OpenOCD.
- Knurling and traditional workflow tradeoffs: Explain why a developer might favor Knurling for everyday development while still using traditional tools for detailed debugging, and why the book primarily uses GDB and OpenOCD.
Why it matters: The tools serve different needs, so a faster development loop does not make low-level debugging tools obsolete.
Key terms: Knurling ecosystem, OpenOCD, semihosting (hprintln!()), GDB, flash-and-run development loop
2.7 Running embedded Rust code in an emulator
This section introduces emulation as a way to test embedded Rust firmware without relying on a physical development board.
- Benefits of firmware emulation: Explain why an embedded Rust developer might run firmware in an emulator instead of on a physical board.
Why it matters: Emulation gives you a way to keep testing firmware even when a board is hard to obtain or use.
Key terms: emulator, firmware testing and validation, development boards
2.7.1 The value and trade-offs of emulation
This section explains why emulation helps embedded development and which tests still require physical hardware.
- Software-Based Development Benefits: Explain how running firmware in an emulator can ease early development compared with repeatedly flashing a physical board.
Why it matters: Emulation can make early iterations and team testing less dependent on access to a board. - Emulation Fidelity Limits: Distinguish what emulator tests can check from what may still need testing on a physical device.
Why it matters: A passing emulator test cannot establish that timing-sensitive or board-specific behavior will work on the device.
Key terms: emulators, continuous integration (CI), regression testing, functional correctness, cycle-accurate timing, peripherals, board-specific quirks
2.7.2 QEMU: The workhorse emulator for embedded Rust
This section explains when QEMU is useful for embedded Rust and how to adapt and run a bare-metal project on an emulated board.
- QEMU capabilities and limits: Explain what QEMU system mode emulates, what kinds of firmware work it can help test, and why emulation does not replace a physical board for long-term development.
Why it matters: It helps you decide what to test in QEMU and when to move to real hardware. - Emulated board project adaptation: Describe how the example project is retargeted from the Blue Pill to a supported QEMU board before its firmware is run.
Why it matters: An emulated board needs firmware configured for the device QEMU actually models. - Semihosting and runner configuration: Describe how the example displays output in QEMU and how its runner differs from one targeting a physical board.
Why it matters: This distinguishes how the same kind of firmware project is launched and observed on virtual versus physical targets.
Key terms: QEMU, system mode, peripheral emulation, physical board, Blue Pill, STM32VLDISCOVERY, HAL feature, Cargo.toml, memory.x, RTT
2.7.3 The Renode emulation solution
This section explains when Renode is a useful alternative to QEMU for embedded-system emulation.
- Renode capabilities and use cases: Explain what kinds of systems Renode can model and why it may be preferable to QEMU for some tests.
Why it matters: These distinctions help you choose an emulator that fits the system you need to test.
Key terms: Renode, QEMU, heterogeneous, multi-core, functional accuracy
2.7.4 The PICSimLab graphical emulation environment
This section introduces PICSimLab as a graphical emulator for interacting with simulated microcontroller circuits and peripherals.
- PICSimLab’s visual simulation role: Explain that PICSimLab lets users visualize and interact with simulated microcontroller circuits and common peripherals, making it useful for education, rapid prototyping, and work that benefits from visual feedback.
Why it matters: It helps you recognize when a visual, interactive emulator is a useful choice.
Key terms: PICSimLab, graphical simulation environment, microcontroller circuits, common peripherals, visual feedback
2.7.5 The Wokwi graphical emulator
This subsection introduces Wokwi’s simulation strengths and how it is used for embedded Rust development.
- Wokwi simulation and Rust use: Describe Wokwi’s interactive, web-based simulation and explain that embedded Rust development uses Wokwi as a VSCode extension.
Why it matters: This distinguishes Wokwi’s browser-based capabilities from the way the section presents its use with embedded Rust.
Key terms: Wokwi, VSCode extension, real-time peripheral simulation, ESP32, ESP8266
2.8 Summary
Where this is used later
- What does no_std mean in embedded Rust? (chapter 3) · Explaining what no_std means in an embedded project.
- Why heap allocation is an explicit choice in no_std (chapter 7) · Explaining why heap allocation is an explicit choice.
- Core architecture crates (chapter 3) · Introducing core architecture crates used by embedded projects.
- Initializing Rust’s runtime in a bare-metal environment (chapter 4) · Discussing runtime initialization in a bare-metal environment.
- The role of .cargo/config.toml in embedded Rust (chapter 3) · Introduces target triples.
- Target-specific dependencies (chapter 3) · Builds can specify different targets.
- Platform-specific aspects: Cortex-M vs. RISC-V (chapter 3) · Platform-specific project setup depends on identifying the correct architecture.
- Inspecting the memory layout (chapter 4) · Inspecting the memory layout of a linked program.
Concepts explained in this chapter
- semihostingSemihosting is a development technique in which code on a target device requests services such as text output from a host debugger through a debug connection.
- probe-rsThe probe-rs crate is a Rust library for communicating with debug probes, flashing embedded targets, and capturing RTT data.
- QEMUQEMU is an open-source machine emulator and virtualizer capable of emulating processors and complete computer systems.
- emulationEmulation is the reproduction of a target system's behavior so software can run or be tested without the original hardware.
- binutilsGNU Binutils is a collection of command-line utilities for inspecting, manipulating, assembling, and linking binary program files.
- memory.xmemory.x is a conventional linker-script fragment that declares embedded memory regions for a Rust firmware build.
- Knurling workflowKnurling is an ecosystem of tools and libraries for embedded Rust development, including flashing, logging, testing, and debugging workflows.
- cargo-generatecargo-generate is a Cargo subcommand that creates projects from templates.
- RTT loggingReal-Time Transfer is a low-intrusion mechanism for exchanging data between a running embedded target and a host through target-memory buffers.
- target tripleA target triple is a standardized identifier describing the processor architecture, vendor, operating system, and binary environment for which software is built.
- OpenOCDOpen On-Chip Debugger is open-source software that provides debugging, in-system programming, and boundary-scan access through hardware probes.
- embedded RustEmbedded Rust is the practice of developing firmware for embedded or bare-metal targets using Rust.
- defmtdefmt is a binary logging framework for no_std firmware that stores format strings in the binary and defers message reconstruction to a host decoder.
- flip-linkflip-link is a linker wrapper that rearranges embedded memory layouts to place the main stack below other RAM sections and detect downward stack overflow.
- cargo-embedcargo-embed is a Cargo subcommand for flashing and debugging embedded targets with project-file-based configuration and RTT output streaming.
- cortex-m-rtcortex-m-rt is a Rust runtime crate that provides startup and exception-handling support for Cortex-M microcontrollers.
- no_std programno_std is a Rust crate configuration that excludes the standard library.
- runtime crateA runtime crate supplies target-specific startup and exception-handling support for an embedded application.
- .cargo/config.toml.cargo/config.toml is Cargo's project configuration file for specifying build targets, linker arguments, and runner commands.
- memory layoutA memory layout specifies the placement of a program's code, data, stack, and other regions in memory.
- CargoCargo is Rust's package manager and build system, providing dependency management, compilation, testing, and related project workflows.
- cargo.tomlCargo.toml is the TOML-formatted manifest file that declares a Rust package's metadata, dependencies, and build configuration.
- bare-metal targetA bare-metal target is an execution platform on which software runs directly on hardware without an operating system.
- application binary interfaceAn application binary interface specifies binary-level conventions for calling functions, representing data, and interoperating between compiled software components.
- execution environmentA runtime environment is the collection of execution support, hardware state, and software facilities available to a running program.
- GDBGDB is the GNU source-level debugger for controlling and inspecting program execution.
- runner configurationA Cargo runner is a target-specific setting that specifies the command used to launch or flash a built program.
- Embed.tomlEmbed.toml is a project configuration file used by cargo-embed to specify embedded-target settings such as the chip, probe protocol, and enabled features.
- cycle-accurate timingCycle-accurate timing is timing behavior that matches the precise processor-cycle execution of the real hardware.
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.
