flash

name

flash

description

Flash an A2FPGA board's FPGA BITSTREAM (the .fs gateware) with openFPGALoader. Use when the user asks to flash, program, upload, load, or deploy a BITSTREAM/gateware to a board (a2mega, a2n20v2, a2n20v2-GS, a2n20v2-Enhanced, a2p25, a2n9, a2n20v1). NOT for the a2n20v2-Enhanced BL616 MCU/microcontroller FIRMWARE — for that use the `flash-mcu` skill (different tool, different chip; using this one would not touch the BL616).

Flash an A2FPGA board

Programs a board's bitstream with openFPGALoader, using the correct cable/board config per board. Wraps tools/flash.sh (humans run the same script directly).

Flashing is a real, outward action on hardware — confirm the board and that a device is connected before running, unless the user already said to go ahead.

Steps

1. Determine the board. If unspecified, ask. See docs/boards.md.

2. Confirm a bitstream exists. The script flashes boards/<board>/impl/pnr/<proj>.fs. If it's missing, build first with the build skill (tools/build.sh <board>).

3. Preview, then flash. To show the exact command without running it:

   DRY_RUN=1 tools/flash.sh <board>
   

   Then flash:

   tools/flash.sh <board>          # write to persistent SPI flash (default)
   tools/flash.sh <board> --sram   # load to volatile SRAM (lost on power-down; for quick test)
   

Per-board programming config (handled by the script)

Board(s)	openFPGALoader
a2n20v1, a2n20v2, a2n20v2-GS, a2n20v2-Enhanced (Tang Nano 20K)	-b tangnano20k
a2n9 (Tang Nano 9K)	-b tangnano9k
a2mega (Tang Mega 60K), a2p25 (Tang Primer 25K)	-c esp32s3 (on-board ESP32S3; flash adds --bulk-erase -f)

Notes

• a2mega (DDR3): power-cycle the board between flashes. Reprogramming without a power cycle can fail DDR3 init and produce a black screen that looks like a logic bug, not a programming failure. The script prints this reminder. See docs/gotchas.md.
• Loader install (macOS): brew install openfpgaloader.
• a2mega, indeterminate/corrupt flash state (a write errored or was interrupted; FPGA no longer configures at power-on; flash ops fail with "Read ID failed"): do NOT iterate on writes. Bulk-erase first at low speed — openFPGALoader -c esp32s3 --freq 500000 --bulk-erase — then replug and flash normally. The flash phase's default 10 MHz JTAG clock does not work on this board; 500 kHz does. Full recipe: docs/gotchas.md.