rp-rs · thejpster · Aug 23, 2024 · Aug 18, 2024 · Aug 18, 2024 · Aug 18, 2024
diff --git a/.github/workflows/rp235x_hal_examples_riscv.yml b/.github/workflows/rp235x_hal_examples_riscv.yml
@@ -1,5 +1,5 @@
 on: [push, pull_request]
-name: Check rp235x-hal-examples on Arm
+name: Check rp235x-hal-examples on RISC-V
 env:
   PACKAGE: rp235x-hal-examples
   TARGET: riscv32imac-unknown-none-elf

diff --git a/rp-hal-common/src/lib.rs b/rp-hal-common/src/lib.rs
@@ -1,7 +1,7 @@
 //! Common HAL code
 //!
 //! This library contains types and functions which are shared between the
-//! RP2040 HAl and the RP235x HAL.
+//! RP2040 HAL and the RP235x HAL.
 //!
 //! You shouldn't include anything here which requires either the `cortex-m`
 //! crate, or a PAC.

diff --git a/rp2040-hal-examples/src/bin/alloc.rs b/rp2040-hal-examples/src/bin/alloc.rs
@@ -6,7 +6,7 @@
 //! the on-board LED. It may need to be adapted to your particular board layout
 //! and/or pin assignment.
 //!
-//! While blinkin the LED, it will continuously push to a `Vec`, which will
+//! While blinking the LED, it will continuously push to a `Vec`, which will
 //! eventually lead to a panic due to an out of memory condition.
 //!
 //! See the top-level `README.md` file for Copyright and licence details.
@@ -58,7 +58,7 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 /// as soon as all global variables are initialised.
 ///
 /// The function configures the RP2040 peripherals, then blinks the LED in an
-/// infinite loop.
+/// infinite loop where the duration indicates how many items were allocated.
 #[entry]
 fn main() -> ! {
     {

diff --git a/rp2040-hal-examples/src/bin/gpio_in_out.rs b/rp2040-hal-examples/src/bin/gpio_in_out.rs
@@ -1,6 +1,6 @@
-//! # GPIO 'Blinky' Example
+//! # GPIO In/Out Example
 //!
-//! This application demonstrates how to control a GPIO pin on the RP2040.
+//! This application demonstrates how to control GPIO pins on the RP2040.
 //!
 //! It may need to be adapted to your particular board layout and/or pin assignment.
 //!

diff --git a/rp2040-hal-examples/src/bin/watchdog.rs b/rp2040-hal-examples/src/bin/watchdog.rs
@@ -98,7 +98,7 @@ fn main() -> ! {
         watchdog.feed();
     }
 
-    // Blink 10 times per second, not feeding the watchdog.
+    // Blink 5 times per second, not feeding the watchdog.
     // The processor should reset in 1.05 seconds, or 5 blinks time
     loop {
         led_pin.set_low().unwrap();

diff --git a/rp235x-hal-examples/.cargo/config.toml b/rp235x-hal-examples/.cargo/config.toml
@@ -31,7 +31,8 @@ rustflags = [
     "-C", "target-cpu=cortex-m33",
 ]
 
-# Use picotool for loading, as probe-rs doesn't support RP2350 yet:
+# Use picotool for loading.
+#
 # Load an elf, skipping unchanged flash sectors, verify it, and execute it
 runner = "picotool load -u -v -x -t elf"
 
@@ -48,14 +49,10 @@ rustflags = [
     "-C", "link-arg=-Tdefmt.x",
 ]
 
-# This runner will make a UF2 file and then copy it to a mounted RP2040 in USB
-# Bootloader mode:
-runner = "elf2uf2-rs -d"
-
-# Alternatively, use picotool for loading.
+# Use picotool for loading.
 #
 # Load an elf, skipping unchanged flash sectors, verify it, and execute it
-# runner = "picotool load -u -v -x -t elf"
+runner = "picotool load -u -v -x -t elf"
 
 # This is the soft-float ABI for RISC-V mode.
 #
@@ -78,11 +75,7 @@ rustflags = [
     "-C", "link-arg=-Tdefmt.x",
 ]
 
-# This runner will make a UF2 file and then copy it to a mounted RP2040 in USB
-# Bootloader mode:
-runner = "elf2uf2-rs -d"
-
-# Alternatively, use picotool for loading.
+# Use picotool for loading.
 #
 # Load an elf, skipping unchanged flash sectors, verify it, and execute it
-# runner = "picotool load -u -v -x -t elf"
+runner = "picotool load -u -v -x -t elf"
diff --git a/rp235x-hal-examples/README.md b/rp235x-hal-examples/README.md
@@ -82,25 +82,24 @@ $ file ./target/thumbv8m.main-none-eabihf/debug/blinky
 ```
 
 You can also 'run' an example, which thanks to our supplied
-[`.cargo/config.toml`](./.cargo/config.toml) will invoke [`elf2uf2-rs`] to copy
-it to an RP235x in USB Bootloader mode. You should install that if
-you don't have it already.
-
-```console
-$ cargo install elf2uf2-rs --locked
-```
-
-[`elf2uf2-rs`]: https://github.com/JoNil/elf2uf2-rs
+[`.cargo/config.toml`](./.cargo/config.toml) will invoke Raspberry Pi's
+`picotool` to copy it to an RP235x in USB Bootloader mode. You should install
+that if you don't have it already, from
+<https://github.com/raspberrypi/pico-sdk-tools/releases>.
 
 ```console
 $ cargo run --bin blinky --target=thumbv8m.main-none-eabihf
    Compiling rp235x-hal v0.10.0 (/home/user/rp-hal/rp235x-hal)
    Compiling rp235x-hal-examples v0.1.0 (/home/user/rp-hal/rp235x-hal-examples)
     Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.62s
-     Running `elf2uf2-rs -d target/thumbv8m.main-none-eabihf/debug/blinky`
-Found pico uf2 disk /media/user/RP235x
-Transfering program to pico
-88.50 KB / 88.50 KB [=====================================] 100.00 % 430.77 KB/s
+     Running `picotool load -u -v -x -t elf target/thumbv8m.main-none-eabihf/debug/blinky`
+Family id 'rp2350-arm-s' can be downloaded in absolute space:
+  00000000->02000000
+Loading into Flash: [==============================]  100%
+Verifying Flash:    [==============================]  100%
+  OK
+
+The device was rebooted to start the application.
 ```
 
 It is currently possible to build *some* of the examples in RISC-V mode. See
@@ -113,15 +112,18 @@ $ cargo build --bin blinky --target=riscv32imac-unknown-none-elf
     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
 $ file ./target/riscv32imac-unknown-none-elf/debug/blinky
 ./target/riscv32imac-unknown-none-elf/debug/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, with debug_info, not stripped
+$ cargo run --bin blinky --target=riscv32imac-unknown-none-elf
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
+     Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/debug/blinky`
+Family id 'rp2350-riscv' can be downloaded in absolute space:
+  00000000->02000000
+Loading into Flash: [==============================]  100%
+Verifying Flash:    [==============================]  100%
+  OK
+
+The device was rebooted to start the application.
 ```
 
-You cannot use `cargo run` with a RISC-V example because [`elf2uf2-rs`] doesn't
-know about RISC-V binaries yet. If you look in
-[`.cargo/config.toml`](./.cargo/config.toml) you'll see some alternative runner
-definitions which are commented out. For RISC-V mode, try the `picotool` runner
-- but you'll have to install the official Raspberry Pi Pico SDK first in order
-to get a copy of `picotool`, which is why we don't recommend it by default.
-
 <!-- ROADMAP -->
 ## Roadmap
 

diff --git a/rp235x-hal-examples/src/bin/adc.rs b/rp235x-hal-examples/src/bin/adc.rs
@@ -33,8 +33,8 @@ use hal::uart::{DataBits, StopBits, UartConfig};
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/adc_fifo_dma.rs b/rp235x-hal-examples/src/bin/adc_fifo_dma.rs
@@ -34,8 +34,8 @@ use hal::uart::{DataBits, StopBits, UartConfig};
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/adc_fifo_irq.rs b/rp235x-hal-examples/src/bin/adc_fifo_irq.rs
@@ -31,8 +31,8 @@ mod app {
     use hal::Clock;
     use rp235x_hal as hal;
 
-    /// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-    /// if your board has a different frequency
+    /// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+    /// Adjust if your board has a different frequency
     const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
     // This example will capture 1000 samples to `shared.buf`.

diff --git a/rp235x-hal-examples/src/bin/adc_fifo_poll.rs b/rp235x-hal-examples/src/bin/adc_fifo_poll.rs
@@ -31,8 +31,8 @@ use hal::uart::{DataBits, StopBits, UartConfig};
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/alloc.rs b/rp235x-hal-examples/src/bin/alloc.rs
@@ -6,7 +6,7 @@
 //! the on-board LED. It may need to be adapted to your particular board layout
 //! and/or pin assignment.
 //!
-//! While blinkin the LED, it will continuously push to a `Vec`, which will
+//! While blinking the LED, it will continuously push to a `Vec`, which will
 //! eventually lead to a panic due to an out of memory condition.
 //!
 //! See the `Cargo.toml` file for Copyright and licence details.
@@ -38,17 +38,17 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.
 ///
 /// The `#[hal::entry]` macro ensures the Cortex-M start-up code calls this function
 /// as soon as all global variables are initialised.
 ///
-/// The function configures the RP2040 peripherals, then blinks the LED in an
-/// infinite loop.
+/// The function configures the RP2350 peripherals, then blinks the LED in an
+/// infinite loop where the duration indicates how many items were allocated.
 #[hal::entry]
 fn main() -> ! {
     {

diff --git a/rp235x-hal-examples/src/bin/arch_flip.rs b/rp235x-hal-examples/src/bin/arch_flip.rs
@@ -33,8 +33,8 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/binary_info_demo.rs b/rp235x-hal-examples/src/bin/binary_info_demo.rs
@@ -28,8 +28,8 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/blinky.rs b/rp235x-hal-examples/src/bin/blinky.rs
@@ -25,8 +25,8 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/block_loop.rs b/rp235x-hal-examples/src/bin/block_loop.rs
@@ -1,4 +1,14 @@
-//! # An example application with two Blocks
+//! # An example application with two Blocks.
+//!
+//! Our first block is an *Image Definition* Block and it points at our second
+//! Block which contains a placeholder item for the purposes of this example.
+//! The placeholder isn't useful per se, but it allows us to show how to
+//! construct two Blocks in a loop without having to use `picotool` to modify
+//! the application after compilation and linking.
+//!
+//! See [Section
+//! 5.1.5.2](https://rptl.io/rp2350-datasheet#bootrom-concept-block-loop) in the
+//! RP2350 datasheet for more information about Blocks and Block Loops.
 //!
 //! See the `Cargo.toml` file for Copyright and license details.
 
@@ -38,8 +48,8 @@ pub static END_IMAGE_DEF: hal::block::Block<1> =
     hal::block::Block::new([hal::block::item_ignored()])
             .with_offset(unsafe { core::ptr::addr_of!(end_to_start) });
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/dht11.rs b/rp235x-hal-examples/src/bin/dht11.rs
@@ -27,8 +27,8 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 use dht_sensor::{dht11, DhtReading};

diff --git a/rp235x-hal-examples/src/bin/float_test.rs b/rp235x-hal-examples/src/bin/float_test.rs
@@ -100,8 +100,8 @@ use hal::Clock;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 struct GlobalUart {

diff --git a/rp235x-hal-examples/src/bin/gpio_dyn_pin_array.rs b/rp235x-hal-examples/src/bin/gpio_dyn_pin_array.rs
@@ -33,8 +33,8 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/gpio_in_out.rs b/rp235x-hal-examples/src/bin/gpio_in_out.rs
@@ -1,6 +1,6 @@
-//! # GPIO 'Blinky' Example
+//! # GPIO In/Out Example
 //!
-//! This application demonstrates how to control a GPIO pin on the rp235x.
+//! This application demonstrates how to control GPIO pins on the RP2040.
 //!
 //! It may need to be adapted to your particular board layout and/or pin assignment.
 //!
@@ -25,8 +25,8 @@ use embedded_hal::digital::OutputPin;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/gpio_irq_example.rs b/rp235x-hal-examples/src/bin/gpio_irq_example.rs
@@ -48,8 +48,8 @@ use gpio::Interrupt::EdgeLow;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 // Pin types quickly become very long!

diff --git a/rp235x-hal-examples/src/bin/i2c.rs b/rp235x-hal-examples/src/bin/i2c.rs
@@ -26,8 +26,8 @@ use hal::gpio::{FunctionI2C, Pin};
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.

diff --git a/rp235x-hal-examples/src/bin/i2c_async.rs b/rp235x-hal-examples/src/bin/i2c_async.rs
@@ -35,8 +35,8 @@ use embedded_hal_async::i2c::I2c;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Bind the interrupt handler with the peripheral

diff --git a/rp235x-hal-examples/src/bin/i2c_async_cancelled.rs b/rp235x-hal-examples/src/bin/i2c_async_cancelled.rs
@@ -38,8 +38,8 @@ use defmt_rtt as _;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 #[interrupt]

diff --git a/rp235x-hal-examples/src/bin/lcd_display.rs b/rp235x-hal-examples/src/bin/lcd_display.rs
@@ -27,8 +27,8 @@ use hd44780_driver as hd44780;
 #[used]
 pub static IMAGE_DEF: hal::block::ImageDef = hal::block::ImageDef::secure_exe();
 
-/// External high-speed crystal on the Raspberry Pi Pico board is 12 MHz. Adjust
-/// if your board has a different frequency
+/// External high-speed crystal on the Raspberry Pi Pico 2 board is 12 MHz.
+/// Adjust if your board has a different frequency
 const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 
 /// Entry point to our bare-metal application.