From a2d9df3ab6abedbbcd6bcdf93e1024e40bb98294 Mon Sep 17 00:00:00 2001 From: Gray Olson Date: Tue, 17 Oct 2023 14:51:57 -0700 Subject: [PATCH] Change default runner to `probe-rs` and deprecate `probe-run` (#67) `probe-run` was recently announced as deprecated in favor of `probe-rs`. This changes the default runner to `probe-rs run` and removes reference to the old `probe-run`. --- .cargo/config.toml | 8 +++---- README.md | 57 ++++++++++++++++------------------------------ 2 files changed, 22 insertions(+), 43 deletions(-) diff --git a/.cargo/config.toml b/.cargo/config.toml index b37934c..8cce891 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,11 +1,9 @@ [target.'cfg(all(target_arch = "arm", target_os = "none"))'] -# Choose a default "cargo run" tool: -# - probe-run provides flashing and defmt via a hardware debugger, and stack unwind on panic +# Choose a default "cargo run" tool (see README for more info) +# - `probe-rs` provides flashing and defmt via a hardware debugger, and stack unwind on panic # - elf2uf2-rs loads firmware over USB when the rp2040 is in boot mode -# - "probe-rs run" is similar to probe-run but it uses the latest probe-rs lib crate -runner = "probe-run --chip RP2040" +runner = "probe-rs run --chip RP2040 --protocol swd" # runner = "elf2uf2-rs -d" -# runner = "probe-rs run --chip RP2040 --protocol swd" rustflags = [ "-C", "linker=flip-link", diff --git a/README.md b/README.md index a154d27..d153637 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ This template is intended as a starting point for developing your own firmware b It includes all of the `knurling-rs` tooling as showcased in https://github.com/knurling-rs/app-template (`defmt`, `defmt-rtt`, `panic-probe`, `flip-link`) to make development as easy as possible. -`probe-run` is configured as the default runner, so you can start your program as easy as +`probe-rs` is configured as the default runner, so you can start your program as easy as ```sh cargo run --release ``` -If you aren't using a debugger (or want to use cargo-embed/probe-rs-debugger), check out [alternative runners](#alternative-runners) for other options +If you aren't using a debugger (or want to use other debugging configurations), check out [alternative runners](#alternative-runners) for other options
@@ -39,9 +39,9 @@ If you aren't using a debugger (or want to use cargo-embed/probe-rs-debugger), c - flip-link - this allows you to detect stack-overflows on the first core, which is the only supported target for now. -- probe-run. Upstream support for RP2040 was added with version 0.3.1. +- (by default) A [`probe-rs` installation](https://probe.rs/docs/getting-started/installation/) -- A CMSIS-DAP probe. (J-Link and other probes will not work with probe-run) +- A [`probe-rs` compatible](https://probe.rs/docs/getting-started/probe-setup/) probe You can use a second [Pico as a CMSIS-DAP debug probe](debug_probes.md#raspberry-pi-pico). Details @@ -57,12 +57,10 @@ If you aren't using a debugger (or want to use cargo-embed/probe-rs-debugger), c ```sh rustup target install thumbv6m-none-eabi cargo install flip-link -# This is our suggested default 'runner' -cargo install probe-run --locked -# If you want to use elf2uf2-rs instead of probe-run, instead do... -cargo install elf2uf2-rs --locked -# If you want to use any of the probe-rs tools (probe-rs run, cargo-embed, probe-rs-debugger) +# Installs the probe-rs tools, including probe-rs run, our recommended default runner cargo install probe-rs --features=cli --locked +# If you want to use elf2uf2-rs instead, do... +cargo install elf2uf2-rs --locked ``` If you get the error ``binary `cargo-embed` already exists`` during installation of probe-rs, run `cargo uninstall cargo-embed` to uninstall your older version of cargo-embed before trying again. @@ -131,8 +129,12 @@ If you don't have a debug probe or if you want to do interactive debugging you c Some of the options for your `runner` are listed below: -* **cargo embed** - *Step 1* - Install cargo-embed. This is part of the [`probe-rs`](https://crates.io/crates/probe-rs) crate: +* **`cargo embed`** + This is basically a more configurable version of `probe-rs run`, our default runner. + See [the `cargo-embed` tool docs page](https://probe.rs/docs/tools/cargo-embed/) for + more information. + + *Step 1* - Install `cargo-embed`. This is part of the [`probe-rs`](https://crates.io/crates/probe-rs) tools: ```console $ cargo install probe-rs --features=cli --locked @@ -163,28 +165,6 @@ Some of the options for your `runner` are listed below: *Step 5* - Launch a debug session by choosing `Run`>`Start Debugging` (or press F5) -* **probe-rs run** - *Step 1* - Install [`probe-rs`](https://crates.io/crates/probe-rs-cli): - - ```console - $ cargo install probe-rs --features=cli --locked - ``` - - *Step 2* - Make sure your .cargo/config contains the following - - ```toml - [target.thumbv6m-none-eabi] - runner = "probe-rs run --chip RP2040 --protocol swd" - ``` - - *Step 3* - Use `cargo run`, which will compile the code and start the - specified 'runner'. As the 'runner' is cargo embed, it will flash the device - and start running immediately - - ```console - $ cargo run --release - ``` - * **Loading a UF2 over USB** *Step 1* - Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs): @@ -192,22 +172,23 @@ Some of the options for your `runner` are listed below: $ cargo install elf2uf2-rs --locked ``` - *Step 2* - Make sure your .cargo/config contains the following + *Step 2* - Modify `.cargo/config` to change the default runner ```toml - [target.thumbv6m-none-eabi] + [target.`cfg(all(target-arch = "arm", target_os = "none"))`] runner = "elf2uf2-rs -d" ``` - The `thumbv6m-none-eabi` target may be replaced by the all-Arm wildcard - `'cfg(all(target_arch = "arm", target_os = "none"))'`. + The all-Arm wildcard `'cfg(all(target_arch = "arm", target_os = "none"))'` is used + by default in the template files, but may also be replaced by + `thumbv6m-none-eabi`. *Step 3* - Boot your RP2040 into "USB Bootloader mode", typically by rebooting whilst holding some kind of "Boot Select" button. On Linux, you will also need to 'mount' the device, like you would a USB Thumb Drive. *Step 4* - Use `cargo run`, which will compile the code and start the - specified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2 + specified 'runner'. As the 'runner' is the `elf2uf2-rs` tool, it will build a UF2 file and copy it to your RP2040. ```console