Merge pull request #947 from robjwells/picotool

Remove elf2uf2-rs in favour of picotool

Author: thejpster

README.md

@@ -67,15 +67,20 @@ rustup update stable
 rustup target add thumbv6m-none-eabi
 ```
 
-You may also want to install these helpful tools:
+You may also want to install probe-rs, to flash your device over the SWD pins
+with a debug probe:
 
 ```sh
-# Useful to creating UF2 images for the RP2040 USB Bootloader
-cargo install elf2uf2-rs --locked
-# Useful for flashing over the SWD pins using a supported JTAG probe
 cargo install --locked probe-rs-tools
 ```
 
+And also [picotool], if you are not using a debug probe or wish to create UF2
+images for the USB bootloader. You can download a [pre-built picotool
+binary][picotool-releases] for your system.
+
+[picotool]: https://github.com/raspberrypi/picotool
+[picotool-releases]: https://github.com/raspberrypi/pico-sdk-tools/releases
+
 ## Packages
 
 There is a _Hardware Abstraction Layer_ (or HAL) crate for the RP2040 chip,
@@ -125,11 +130,8 @@ a [separate repository][BSPs].
 Rust generates standard Arm ELF files, which you can load onto your Raspberry Pi
 Silicon device with your favourite Arm flashing/debugging tool. In addition, the
 RP2040 contains a ROM bootloader which appears as a Mass Storage Device over USB
-that accepts UF2 format images. You can use the `elf2uf2-rs` package to convert
-the Arm ELF file to a UF2 format image.
-
-For boards with USB Device support like the Raspberry Pi Pico, we recommend you
-use the UF2 process.
+that accepts UF2 format images. You can use picotool to flash your device over
+USB, or convert the Arm ELF file to a UF2 format image.
 
 The RP2040 contains two Cortex-M0+ processors, which execute Thumb-2 encoded
 ARMv6-M instructions. There are no operating-specific features in the binaries
@@ -156,20 +158,16 @@ More detailed information on how the linker flags work can be found in
 In most cases, it should be sufficient to use the example files from the
 [Project Template].
 
-### Loading a UF2 over USB
-
-*Step 1* - Install [`elf2uf2-rs`](https://github.com/JoNil/elf2uf2-rs):
+### Loading over USB with picotool
 
-```console
-$ cargo install elf2uf2-rs --locked
-```
+*Step 1* - Install a [picotool binary][picotool-releases] for your system.
 
 *Step 2* - Make sure your .cargo/config contains the following (it should by
 default if you are working in this repository):
 
 ```toml
 [target.thumbv6m-none-eabi]
-runner = "elf2uf2-rs -d"
+runner = "picotool load --update --verify --execute -t elf"
 ```
 
 The `thumbv6m-none-eabi` target may be replaced by the all-Arm wildcard
@@ -180,8 +178,8 @@ 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 started the
-specified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2
-file and copy it to your RP2040.
+specified 'runner'. As the 'runner' is picotool, it will flash your compiled
+binary over USB.
 
 ```console
 $ cargo run --release --features "critical-section-impl,rt,defmt" --example pwm_blink
@@ -190,6 +188,22 @@ $ cargo run --release --features "critical-section-impl,rt,defmt" --example pwm_
 (The `pwm_blink` example doesn't need all these feature flags. They are listed here
 so you can use the same command for all examples.)
 
+If you want to create a UF2 file, which is loaded by copying it over to the
+RPI-RP2 mass storage device, use the `picotool uf2 convert` command on your
+compiled program with the `-t elf` argument.
+
+```console
+$ picotool uf2 convert -t elf target/thumbv6m-none-eabi/release/pwm_blink
+pwm_blink.uf2
+```
+
+Picotool can also read "Binary Info" from a device with `picotool info`. To
+enable this in your firmware, see the [rp-binary-info] crate and the
+corresponding [binary info example].
+
+[rp-binary-info]: https://github.com/rp-rs/rp-hal/tree/main/rp-binary-info
+[binary info example]: https://github.com/rp-rs/rp-hal/blob/main/rp2040-hal-examples/src/bin/binary_info_demo.rs
+
 ### Loading with probe-rs
 [probe-rs](https://github.com/probe-rs/probe-rs) is a library and a
 command-line tool which can flash a wide variety of microcontrollers
@@ -234,20 +248,6 @@ connected to the RP2040.
 $ cargo run --release --example pwm_blink
 ```
 
-### Loading with picotool
-
-As ELF files produced by compiling Rust code are completely compatible with ELF
-files produced by compiling C or C++ code, you can also use the Raspberry Pi
-tool [picotool](https://github.com/raspberrypi/picotool). The only thing to be
-aware of is that picotool expects your ELF files to have a `.elf` extension, and
-by default Rust does not give the ELF files any extension. You can fix this by
-simply renaming the file.
-
-Also of note is that the special
-[pico-sdk](https://github.com/raspberrypi/pico-sdk) macros which hide
-information in the ELF file in a way that `picotool info` can read it out, are
-not supported in Rust. An alternative is TBC.
-
 [Project Template]: https://github.com/rp-rs/rp2040-project-template
 
 <!-- ROADMAP -->

on-target-tests/.cargo/config.toml

@@ -18,7 +18,7 @@ target = "thumbv6m-none-eabi"
 # * linker argument -Tlink.x tells the linker to use link.x as the linker
 #   script. This is usually provided by the cortex-m-rt crate, and by default
 #   the version in that crate will include a file called `memory.x` which
-#   describes the particular memory layout for your specific chip. 
+#   describes the particular memory layout for your specific chip.
 # * no-vectorize-loops turns off the loop vectorizer (seeing as the M0+ doesn't
 #   have SIMD)
 rustflags = [
@@ -28,9 +28,8 @@ rustflags = [
     "-C", "no-vectorize-loops",
 ]
 
-# This runner will make a UF2 file and then copy it to a mounted RP2040 in USB
-# Bootloader mode:
-runner = "elf2uf2-rs -d"
+# This runner will flash a mounted RP2040 in USB Bootloader mode:
+runner = "picotool load --update --verify --execute -t elf"
 
 # This runner will find a supported SWD debug probe and flash your RP2040 over
 # SWD:

rp2040-hal-examples/.cargo/config.toml

@@ -18,7 +18,7 @@ target = "thumbv6m-none-eabi"
 # * linker argument -Tlink.x tells the linker to use link.x as the linker
 #   script. This is usually provided by the cortex-m-rt crate, and by default
 #   the version in that crate will include a file called `memory.x` which
-#   describes the particular memory layout for your specific chip. 
+#   describes the particular memory layout for your specific chip.
 # * no-vectorize-loops turns off the loop vectorizer (seeing as the M0+ doesn't
 #   have SIMD)
 rustflags = [
@@ -28,9 +28,8 @@ rustflags = [
     "-C", "no-vectorize-loops",
 ]
 
-# This runner will make a UF2 file and then copy it to a mounted RP2040 in USB
-# Bootloader mode:
-runner = "elf2uf2-rs -d"
+# This runner will flash a mounted RP2040 in USB Bootloader mode:
+runner = "picotool load --update --verify --execute -t elf"
 
 # This runner will find a supported SWD debug probe and flash your RP2040 over
 # SWD:

rp2040-hal-examples/README.md

@@ -78,28 +78,30 @@ $ cargo build
 $ cargo build --bin dormant_sleep
     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
 $ file ./target/thumbv6m-none-eabi/debug/dormant_sleep
-./target/thumbv6m-none-eabi/debug/dormant_sleep: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, with debug_info, not stripped
+./target/thumbv6m-none-eabi/debug/dormant_sleep: ELF 32-bit LSB executable, ARM, EABI5 version 1 (GNU/Linux), statically linked, with debug_info, not stripped
 ```
 
-You can also 'run' an example, which will invoke [`elf2uf2-rs`] to copy it to an
-RP2040's virtual USB Mass Storage Device (which it puts over the USB port when
-in its ROM bootloader). You should install that if you don't have it already:
+You can also 'run' an example, which will invoke [picotool] to flash the RP2040
+over USB. You should install that if you don't have it already; [pre-built
+binaries][picotool-releases] are available for Windows, Linux, and macOS.
 
 ```console
-$ cargo install elf2uf2-rs --locked
 $ cd rp2040-hal-examples
 $ cargo run --bin dormant_sleep
-   Compiling rp2040-hal v0.10.0 (/home/user/rp-hal/rp2040-hal)
+   Compiling rp2040-hal v0.11.0 (/home/user/rp-hal/rp2040-hal)
    Compiling rp2040-hal-examples v0.1.0 (/home/user/rp-hal/rp2040-hal-examples)
-    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.62s
-     Running `elf2uf2-rs -d target/thumbv6m-none-eabi/debug/dormant_sleep`
-Found pico uf2 disk /media/user/RP2040
-Transfering program to pico
-88.50 KB / 88.50 KB [=====================================] 100.00 % 430.77 KB/s
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.47s
+     Running `picotool load --update --verify --execute -t elf target/thumbv6m-none-eabi/debug/dormant_sleep`
+Loading into Flash:   [==============================]  100%
+Verifying Flash:      [==============================]  100%
+  OK
+
+The device was rebooted to start the application.
 $
 ```
 
-[`elf2uf2-rs`]: https://github.com/JoNil/elf2uf2-rs
+[picotool]: https://github.com/raspberrypi/picotool
+[picotool-releases]: https://github.com/raspberrypi/pico-sdk-tools/releases
 
 <!-- ROADMAP -->
 ## Roadmap