Merge pull request #824 from rp-rs/add-picotool-metadata-again

Adds binary info block support.

.github/workflows/build_and_test.yml

@@ -62,7 +62,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: 1.75
+          toolchain: 1.77
           target: thumbv6m-none-eabi
       - name: Install cargo-hack
         run: |

memory.x

@@ -28,9 +28,51 @@ MEMORY {
 EXTERN(BOOT2_FIRMWARE)
 
 SECTIONS {
-    /* ### Boot loader */
+    /* ### Boot loader
+     *
+     * An executable block of code which sets up the QSPI interface for
+     * 'Execute-In-Place' (or XIP) mode. Also sends chip-specific commands to
+     * the external flash chip.
+     *
+     * Must go at the start of external flash, where the Boot ROM expects it.
+     */
     .boot2 ORIGIN(BOOT2) :
     {
         KEEP(*(.boot2));
     } > BOOT2
 } INSERT BEFORE .text;
+
+SECTIONS {
+    /* ### Boot ROM info
+     *
+     * Goes after .vector_table, to keep it in the first 512 bytes of flash,
+     * where picotool can find it
+     */
+    .boot_info : ALIGN(4)
+    {
+        KEEP(*(.boot_info));
+    } > FLASH
+
+} INSERT AFTER .vector_table;
+
+/* move .text to start /after/ the boot info */
+_stext = ADDR(.boot_info) + SIZEOF(.boot_info);
+
+SECTIONS {
+    /* ### Picotool 'Binary Info' Entries
+     *
+     * Picotool looks through this block (as we have pointers to it in our
+     * header) to find interesting information.
+     */
+    .bi_entries : ALIGN(4)
+    {
+        /* We put this in the header */
+        __bi_entries_start = .;
+        /* Here are the entries */
+        KEEP(*(.bi_entries));
+        /* Keep this block a nice round size */
+        . = ALIGN(4);
+        /* We put this in the header */
+        __bi_entries_end = .;
+    } > FLASH
+} INSERT AFTER .text;

rp2040-hal/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### MSRV
+
+The Minimum-Supported Rust Version (MSRV) for the next release is 1.77
+
+### Added
+
+- Support for *binary info*, which is metadata that `picotool` can read from your binary.
+- Bump MSRV to 1.77, because *binary info* examples need C-Strings.
+
 ## [0.10.0] - 2024-03-10
 
 ### Added

rp2040-hal/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2021"
 homepage = "https://github.com/rp-rs/rp-hal"
 description = "A Rust Embedded-HAL impl for the rp2040 microcontroller"
 license = "MIT OR Apache-2.0"
-rust-version = "1.75"
+rust-version = "1.77"
 repository = "https://github.com/rp-rs/rp-hal"
 categories = ["embedded", "hardware-support", "no-std", "no-std::no-alloc"]
 keywords = ["embedded", "hal", "raspberry-pi", "rp2040", "embedded-hal"]
@@ -106,6 +106,16 @@ rtic-monotonic = ["dep:rtic-monotonic"]
 # Implement `i2c-write-iter` traits
 i2c-write-iter = ["dep:i2c-write-iter"]
 
+# Add a binary-info header block containing picotool-compatible metadata.
+#
+# Requires 'rt' so that the vector table is correctly sized and therefore the
+# header is within reach of picotool.
+binary-info = ["rt"]
+
+[[example]]
+name = "binary_info_demo"
+required-features = ["binary-info", "critical-section-impl"]
+
 [[example]]
 # irq example uses cortex-m-rt::interrupt, need rt feature for that
 name = "gpio_irq_example"

rp2040-hal/examples/binary_info_demo.rs

@@ -0,0 +1,109 @@
+//! # GPIO 'Blinky' Example, with Binary Info
+//!
+//! This application demonstrates how to control a GPIO pin on the RP2040, and
+//! includes some picotool-compatible metadata.
+//!
+//! It may need to be adapted to your particular board layout and/or pin assignment.
+//!
+//! See the `Cargo.toml` file for Copyright and license details.
+
+#![no_std]
+#![no_main]
+
+// Ensure we halt the program on panic (if we don't mention this crate it won't
+// be linked)
+use panic_halt as _;
+
+// Alias for our HAL crate
+use rp2040_hal as hal;
+
+// A shorter alias for the Peripheral Access Crate, which provides low-level
+// register access
+use hal::pac;
+
+use hal::binary_info;
+
+// Some traits we need
+use embedded_hal::delay::DelayNs;
+use embedded_hal::digital::OutputPin;
+
+/// The linker will place this boot block at the start of our program image. We
+/// need this to help the ROM bootloader get our code up and running.
+/// Note: This boot block is not necessary when using a rp-hal based BSP
+/// as the BSPs already perform this step.
+#[link_section = ".boot2"]
+#[used]
+pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_GENERIC_03H;
+
+/// External high-speed crystal on the Raspberry Pi Pico 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 `#[rp2040_hal::entry]` macro ensures the Cortex-M start-up code calls this function
+/// as soon as all global variables and the spinlock are initialised.
+///
+/// The function configures the RP2040 peripherals, then toggles a GPIO pin in
+/// an infinite loop. If there is an LED connected to that pin, it will blink.
+#[hal::entry]
+fn main() -> ! {
+    // Grab our singleton objects
+    let mut pac = pac::Peripherals::take().unwrap();
+
+    // Set up the watchdog driver - needed by the clock setup code
+    let mut watchdog = hal::Watchdog::new(pac.WATCHDOG);
+
+    // Configure the clocks
+    let clocks = hal::clocks::init_clocks_and_plls(
+        XTAL_FREQ_HZ,
+        pac.XOSC,
+        pac.CLOCKS,
+        pac.PLL_SYS,
+        pac.PLL_USB,
+        &mut pac.RESETS,
+        &mut watchdog,
+    )
+    .unwrap();
+
+    let mut timer = rp2040_hal::Timer::new(pac.TIMER, &mut pac.RESETS, &clocks);
+
+    // The single-cycle I/O block controls our GPIO pins
+    let sio = hal::Sio::new(pac.SIO);
+
+    // Set the pins to their default state
+    let pins = hal::gpio::Pins::new(
+        pac.IO_BANK0,
+        pac.PADS_BANK0,
+        sio.gpio_bank0,
+        &mut pac.RESETS,
+    );
+
+    // Configure GPIO25 as an output
+    let mut led_pin = pins.gpio25.into_push_pull_output();
+    loop {
+        led_pin.set_high().unwrap();
+        timer.delay_ms(500);
+        led_pin.set_low().unwrap();
+        timer.delay_ms(500);
+    }
+}
+
+/// This is a list of references to our table entries
+///
+/// They must be in the `.bi_entries` section as we tell picotool the start and
+/// end addresses of that section.
+#[link_section = ".bi_entries"]
+#[used]
+pub static PICOTOOL_ENTRIES: [binary_info::EntryAddr; 7] = [
+    hal::binary_info_rp_program_name!(c"rp2040-hal Binary Info Example"),
+    hal::binary_info_rp_cargo_version!(),
+    hal::binary_info_rp_program_description!(c"A GPIO blinky with extra metadata."),
+    hal::binary_info_rp_program_url!(c"https://github.com/rp-rs/rp-hal"),
+    hal::binary_info_rp_program_build_attribute!(),
+    hal::binary_info_rp_pico_board!(c"pico"),
+    // An example with a non-Raspberry-Pi tag
+    hal::binary_info_int!(binary_info::make_tag(b"JP"), 0x0000_0001, 0x12345678),
+];
+
+// End of file

rp2040-hal/src/binary_info/consts.rs

@@ -0,0 +1,31 @@
+//! Constants for binary info
+
+/// All Raspberry Pi specified IDs have this tag.
+///
+/// You can create your own for custom fields.
+pub const TAG_RASPBERRY_PI: u16 = super::make_tag(b"RP");
+
+/// Used to note the program name - use with StringEntry
+pub const ID_RP_PROGRAM_NAME: u32 = 0x02031c86;
+/// Used to note the program version - use with StringEntry
+pub const ID_RP_PROGRAM_VERSION_STRING: u32 = 0x11a9bc3a;
+/// Used to note the program build date - use with StringEntry
+pub const ID_RP_PROGRAM_BUILD_DATE_STRING: u32 = 0x9da22254;
+/// Used to note the size of the binary - use with IntegerEntry
+pub const ID_RP_BINARY_END: u32 = 0x68f465de;
+/// Used to note a URL for the program - use with StringEntry
+pub const ID_RP_PROGRAM_URL: u32 = 0x1856239a;
+/// Used to note a description of the program - use with StringEntry
+pub const ID_RP_PROGRAM_DESCRIPTION: u32 = 0xb6a07c19;
+/// Used to note some feature of the program - use with StringEntry
+pub const ID_RP_PROGRAM_FEATURE: u32 = 0xa1f4b453;
+/// Used to note some whether this was a Debug or Release build - use with StringEntry
+pub const ID_RP_PROGRAM_BUILD_ATTRIBUTE: u32 = 0x4275f0d3;
+/// Used to note the Pico SDK version used - use with StringEntry
+pub const ID_RP_SDK_VERSION: u32 = 0x5360b3ab;
+/// Used to note which board this program targets - use with StringEntry
+pub const ID_RP_PICO_BOARD: u32 = 0xb63cffbb;
+/// Used to note which `boot2` image this program uses - use with StringEntry
+pub const ID_RP_BOOT2_NAME: u32 = 0x7f8882e1;
+
+// End of file

rp2040-hal/src/binary_info/macros.rs

@@ -0,0 +1,145 @@
+//! Handy macros for making Binary Info entries
+
+/// Generate a static item containing the given environment variable,
+/// and return its [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_env {
+    ($tag:expr, $id:expr, $env_var_name:expr) => {
+        $crate::binary_info_str!($tag, $id, {
+            let value = concat!(env!($env_var_name), "\0");
+            // # Safety
+            //
+            // We used `concat!` to null-terminate on the line above.
+            let value_cstr =
+                unsafe { core::ffi::CStr::from_bytes_with_nul_unchecked(value.as_bytes()) };
+            value_cstr
+        })
+    };
+}
+
+/// Generate a static item containing the given string, and return its
+/// [`EntryAddr`](super::EntryAddr).
+///
+/// You must pass a numeric tag, a numeric ID, and `&CStr` (which is always
+/// null-terminated).
+#[macro_export]
+macro_rules! binary_info_str {
+    ($tag:expr, $id:expr, $str:expr) => {{
+        static ENTRY: $crate::binary_info::StringEntry =
+            $crate::binary_info::StringEntry::new($tag, $id, $str);
+        ENTRY.addr()
+    }};
+}
+
+/// Generate a static item containing the given string, and return its
+/// [`EntryAddr`](super::EntryAddr).
+///
+/// You must pass a numeric tag, a numeric ID, and `&CStr` (which is always
+/// null-terminated).
+#[macro_export]
+macro_rules! binary_info_int {
+    ($tag:expr, $id:expr, $int:expr) => {{
+        static ENTRY: $crate::binary_info::IntegerEntry =
+            $crate::binary_info::IntegerEntry::new($tag, $id, $int);
+        ENTRY.addr()
+    }};
+}
+
+/// Generate a static item containing the program name, and return its
+/// [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_program_name {
+    ($name:expr) => {
+        $crate::binary_info_str!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PROGRAM_NAME,
+            $name
+        )
+    };
+}
+
+/// Generate a static item containing the program version, and return its
+/// [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_program_version {
+    ($version:expr) => {{
+        $crate::binary_info_str!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PROGRAM_VERSION,
+            $version
+        )
+    }};
+}
+
+/// Generate a static item containing the `CARGO_PKG_VERSION` as the program
+/// version, and return its [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_cargo_version {
+    () => {
+        $crate::binary_info_env!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PROGRAM_VERSION_STRING,
+            "CARGO_PKG_VERSION"
+        )
+    };
+}
+
+/// Generate a static item containing the program url, and return its
+/// [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_program_url {
+    ($url:expr) => {
+        $crate::binary_info_str!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PROGRAM_URL,
+            $url
+        )
+    };
+}
+
+/// Generate a static item containing the program description, and return its
+/// [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_program_description {
+    ($description:expr) => {
+        $crate::binary_info_str!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PROGRAM_DESCRIPTION,
+            $description
+        )
+    };
+}
+
+/// Generate a static item containing whether this is a debug or a release
+/// build, and return its [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_program_build_attribute {
+    () => {
+        $crate::binary_info_str!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PROGRAM_BUILD_ATTRIBUTE,
+            {
+                if cfg!(debug_assertions) {
+                    c"debug"
+                } else {
+                    c"release"
+                }
+            }
+        )
+    };
+}
+
+/// Generate a static item containing the specific board this program runs on,
+/// and return its [`EntryAddr`](super::EntryAddr).
+#[macro_export]
+macro_rules! binary_info_rp_pico_board {
+    ($board:expr) => {
+        $crate::binary_info_str!(
+            $crate::binary_info::consts::TAG_RASPBERRY_PI,
+            $crate::binary_info::consts::ID_RP_PICO_BOARD,
+            $board
+        )
+    };
+}
+
+// End of file