Crate rp_binary_info

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_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