Crate rp_binary_info

Expand description

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.

Modules§

consts: Constants for binary info

Macros§

env: Generate a static item containing the given environment variable, and return its EntryAddr.
int: Generate a static item containing the given string, and return its EntryAddr.
rp_cargo_bin_name: Generate a static item containing the CARGO_BIN_NAME as the program name, and return its EntryAddr.
rp_cargo_homepage_url: Generate a static item containing the CARGO_PKG_HOMEPAGE as the program URL, and return its EntryAddr.
rp_cargo_version: Generate a static item containing the CARGO_PKG_VERSION as the program version, and return its EntryAddr.
rp_pico_board: Generate a static item containing the specific board this program runs on, and return its EntryAddr.
rp_program_build_attribute: Generate a static item containing whether this is a debug or a release build, and return its EntryAddr.
rp_program_description: Generate a static item containing the program description, and return its EntryAddr.
rp_program_name: Generate a static item containing the program name, and return its EntryAddr.
rp_program_url: Generate a static item containing the program URL, and return its EntryAddr.
rp_program_version: Generate a static item containing the program version, and return its EntryAddr.
str: Generate a static item containing the given string, and return its EntryAddr.

Structs§

EntryAddr: This is a reference to an entry. It’s like a &dyn ref to some type T: Entry, except that the run-time type information is encoded into the Entry itself in very specific way.
Header: This is the ‘Binary Info’ header block that picotool looks for in your UF2 file/ELF file/Pico in Bootloader Mode to give you useful metadata about your program.
IntegerEntry: An entry which contains both an ID (e.g. ID_RP_BINARY_END) and an integer.
MappingTableEntry: Allows us to tell picotool where values are in the UF2 given their run-time address.
StringEntry: An entry which contains both an ID (e.g. ID_RP_PROGRAM_NAME) and a pointer to a null-terminated string.

Enums§

DataType: This is the set of data types that picotool supports.

Statics§

MAPPING_TABLE: This tells picotool how to convert RAM addresses back into Flash addresses

Functions§

make_tag: Create a tag from two ASCII letters.
rp_binary_end: Create a ‘Binary Info’ with the size of the binary
rp_boot2_name: Create a ‘Binary Info’ with which boot2 image this program uses
rp_pico_board: Create a ‘Binary Info’ with which board this program targets
rp_program_build_attribute: Create a ‘Binary Info’ with some whether this was a Debug or Release build
rp_program_build_date_string: Create a ‘Binary Info’ with the program build date
rp_program_description: Create a ‘Binary Info’ with a description of the program
rp_program_feature: Create a ‘Binary Info’ with some feature of the program
rp_program_name: Create a ‘Binary Info’ entry containing the program name
rp_program_url: Create a ‘Binary Info’ entry with a URL
rp_program_version: Create a ‘Binary Info’ entry containing the program version.
rp_sdk_version: Create a ‘Binary Info’ with the Pico SDK version used

Crate rp_binary_infoCopy item path