IMAGE_DEF

The two ways to provide an IMAGE_DEF metadata block on RP2350, and the code base address each requires

Overview

Bootable RP2350 binaries must include an IMAGE_DEF metadata block. There are two ways to provide it, and the choice constrains the code base address in your Astrobe configuration:

IMAGE_DEF source	Code base	Load / debug tooling
Path A: prepended at load time (framework default)	`10000100H`	Run `make-uf2 rp2350` to produce a bootable UF2 file; run `make-elf --image-def` to produce a debug ELF file. The first 256 bytes of flash are reserved for the prepended block.
Path B: module `ImageDef` (embedded in binary)	`10000000H`	Astrobe-emitted `.uf2` boots as-is; for a debug ELF file run `make-elf` without `--image-def`.

Both paths are valid and tested. The framework's example and test programs use Path A – the principle being that deployment data should be kept out of the program binary, so the same program binary can serve different load-time configurations. The instructions in the following sections follow that convention. If you prefer Path B, the table above captures the only differences; the rest of the build flow is the same.

Note that either path is a valid and useful approach. There is no right or wrong here.

Path A — Prepended at Load Time (Framework Default)

Do not import ImageDef. Set the .ini Code Range lower bound to 10000100H. The 256-byte gap from 10000000H to 100000FFH will be filled by the IMAGE_DEF block that make-uf2 rp2350 (for UF2 loading) or make-elf --image-def (for a debug ELF file) prepends to the program binary.

Path B — Embedded via `ImageDef` Module

Import ImageDef in Main immediately after Startup; this ensures that the IMAGE_DEF block appears in the first 4 kB of the binary:

IMPORT
  Startup, ImageDef, MemMap, Memory, Clocks, Console,
  RuntimeErrors, RuntimeErrorsOut, FPU, LED;

Set the .ini Code Range lower bound to 10000000H. Refer to the Astrobe documentation for further detail on the ImageDef module.

Coexistence

Leaving ImageDef in your program while also using make-uf2 or make-elf --image-def is harmless: the RP2350 boot ROM scans the first 4 kB of flash, picks up the prepended IMAGE_DEF, and ignores the one embedded later via ImageDef. The only requirement is that the code base address matches the actual IMAGE_DEF position – ie., the address scheme matches one of the two paths above.

Address-mismatch

If the code base address does not match the IMAGE_DEF source, the chip does not boot the program – unfortunately, no diagnostic is produced: the uploaded UF2 file is formally valid, and the virtual volume RP2350 mounted using BOOTSEL gets unmounted after the file transfer.

Obviously, there could be many other causes for a non-functioning program, but a quick check for the correct setting could be a first step.

If in doubt, build and load one of the simple example programs. If you want to use the Astrobe UF2 file, add module ImageDef to Main, as outlined above.

Last updated: 12 May 2026