rp-binary-info

Code and types for creating Picotool compatible "Binary Info" metadata.

License

The contents of this repository are dual-licensed under the MIT OR Apache 2.0 License. That means you can choose either the MIT license or the Apache 2.0 license when you re-use this code. See LICENSE-MIT or LICENSE-APACHE for more information on each specific license. Our Apache 2.0 notices can be found in NOTICE.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclus`ion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

lib.rs:

Code and types for creating Picotool compatible "Binary Info" metadata

Example usage

Enable the Cargo feature binary-info.

Add this to your linker script (usually named memory.x):

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;

Then, add this to your Rust code:

#[link_section = ".bi_entries"]
#[used]
pub static PICOTOOL_ENTRIES: [rp_binary_info::EntryAddr; 3] = [
    rp_binary_info::rp_program_name!(c"Program Name Here"),
    rp_binary_info::rp_cargo_version!(),
    rp_binary_info::int!(
        rp_binary_info::make_tag(b"JP"),
        0x0000_0001,
        0x12345678
    ),
];

Cargo features

The binary-info Cargo feature enables emitting the main PICOTOOL_HEADER static, which is what Picotool looks for to discover the binary info.

It is optional to allow you to emit the static yourself differently, for e.g. compatibility with different linker scripts, while still allowing using the rest of the utilities in the crate to format the info.