Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions src/intro/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,25 @@ cargo install cargo-generate

Note: on some Linux distros (e.g. Ubuntu) you may need to install the packages `libssl-dev` and `pkg-config` prior to installing cargo-generate.

### `flip-link`

The project template we'll use sets `flip-link` as its linker, so the build will
fail without it. It is a wrapper around the regular linker that rearranges the
memory layout so that a stack overflow triggers a hard fault instead of silently
corrupting your static variables.

``` console
cargo install flip-link
```

### `qemu-run`

We'll use this to run programs on QEMU and decode their `defmt` log output.

``` console
cargo install qemu-run
```

### OS-Specific Instructions

Now follow the instructions specific to the OS you are using:
Expand Down
18 changes: 18 additions & 0 deletions src/intro/tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ tested.
versions: 7.10, 7.11, 7.12 and 8.1
- [`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate) or `git`.
These tools are optional but will make it easier to follow along with the book.
- [`flip-link`](https://github.com/knurling-rs/flip-link). The project template
we use sets this as its linker, so it is required to build the examples.
- [`qemu-run`](https://crates.io/crates/qemu-run). Runs a program on QEMU and
decodes the `defmt` log output it sends over semihosting.

The text below explains why we are using these tools. Installation instructions
can be found on the next page.
Expand Down Expand Up @@ -53,6 +57,20 @@ QEMU is an emulator. In this case we use the variant that can fully emulate ARM
systems. We use QEMU to run embedded programs on the host. Thanks to this you
can follow some parts of this book even if you don't have any hardware with you!

## `flip-link`

`flip-link` is a wrapper around the regular linker. It inverts the memory layout
of the program so that the call stack grows away from your static variables
rather than into them, which turns a stack overflow into a hard fault instead of
silent memory corruption.

## `qemu-run`

The template we use logs with `defmt`, which sends compact binary frames rather
than plain text, so the output has to be decoded on the host to be readable.
`qemu-run` launches `qemu-system-arm` for you, reads the `defmt` data the program
sends over semihosting, and prints the decoded messages.

# Tooling for Embedded Rust Debugging

## Overview
Expand Down
Loading
Loading