fpga_mgr

RP2040 (Raspberry Pi Pico) firmware that programs a Wildbits/Foenix FPGA from an SD card, with an optional fallback to preloaded LZ4 images stored in flash.

What it does

• Reads the 2-bit context DIP switch to select one of four FPGA contexts.
• Attempts to program the FPGA from the SD card first (LZ4 blocks, gzip, then raw .bin).
• Falls back to LZ4 images stored in fixed flash slots if the SD card is unavailable or if programming from images on the SD card is unsuccessful.
• Prints the chosen method and timing over USB stdio if enabled.

SD card layout

The context DIP switch determines which of the following directories is selected as a base path:

• CNTX1/
• CNTX2/
• CNTX3/
• CNTX4/

Within the base directory, the loader first looks for Wildbits*.{lz4,gz,bin} images (the file name lookup is case-insensitive). If multiple Wildbits* images share an extension, the loader selects the case-insensitive lexicographically greatest filename; for example, wildbits-2026-07-18.lz4 takes precedence over Wildbits-2026-05-29.lz4.

If no matching Wildbits* images are found, or if the loader cannot successfully program the FPGA using any of the found images, it falls back to the following per-context legacy base paths, which are probed in the same order (.bin.lz4 first, then .bin.gz, then .bin):

• CNTX1/CFP95600C.bin
• CNTX2/CFP95616E.bin
• CNTX3/f256k2t9.bin
• CNTX4/foenix138.bin

The .lz4 format is a simple block format generated by tools/mk_lz4_blocks.c (not the LZ4 frame format).

Flash slots

LZ4 blobs can be placed into flash at fixed addresses (2 MiB each):

• Slot 0: 0x10800000
• Slot 1: 0x10A00000
• Slot 2: 0x10C00000
• Slot 3: 0x10E00000

CMakeLists.txt reserves the top 8 MiB for these blobs.

Build

Prerequisites:

• Raspberry Pi Pico SDK
• CMake + a build tool (Ninja or Make)
• Python 3 (optional, used for UF2 concatenation)
• picotool (optional, for combined UF2 with FPGA blobs)

Example build:

mkdir -p build
cd build
cmake ..
cmake --build .

Artifacts (in build/):

• fpga_mgr.uf2 (main firmware)
• fpga_mgr.elf / fpga_mgr.bin
• fpga_mgr_with_fpga.uf2 (--target fpga_mgr_with_fpga_uf2, requires picotool + Python)

Combined UF2 with FPGA images

If picotool and Python 3 are available, CMake exposes a target that bundles the firmware UF2 with the LZ4 images from fpga/ into one UF2:

cmake --build . --target fpga_mgr_with_fpga_uf2

Tools

• tools/mk_lz4_blocks.c: converts a raw .bin to the block-based .lz4 format the loader expects.
• tools/concat_uf2.py: concatenates UF2 files to form a single image.