Skip to content
Skills Library
Programming · Automation

upload-bitstream

/upload-bitstream

Load an FPGA bitstream (.fs) onto the Tang Nano 9K, either into SRAM for a test run (gone at power-off) or into the GW1NR-9's internal flash so it loads at every power-up. Use this whenever the user wants to load, program, flash, upload, install or try a bitstream, FPGA design or SoC build on the board, or wants a fresh `fpga/build.sh` result running on the hardware, even if they don't say "bitstream". Also covers which bitstream the board holds and checking a build's timing before trusting it.

Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/timing_summary.py

What it does and when to use it

Load an FPGA bitstream (.fs) onto the Tang Nano 9K, either into SRAM for a test run (gone at power-off) or into the GW1NR-9's internal flash so it loads at every power-up. Use this whenever the user wants to load, program, flash, upload, install or try a bitstream, FPGA design or SoC build on the board, or wants a fresh `fpga/build.sh` result running on the hardware, even if they don't say "bitstream". Also covers which bitstream the board holds and checking a build's timing before trusting it.

Triggers from the description

t say

Arguments

/upload-bitstream [sram|flash] [file.fs]
Original author description

Load an FPGA bitstream (.fs) onto the Tang Nano 9K, either into SRAM for a test run (gone at power-off) or into the GW1NR-9's internal flash so it loads at every power-up. Use this whenever the user wants to load, program, flash, upload, install or try a bitstream, FPGA design or SoC build on the board, or wants a fresh `fpga/build.sh` result running on the hardware, even if they don't say "bitstream". Also covers which bitstream the board holds and checking a build's timing before trusting it.

How it works

  1. 1. Pick the bitstream
  2. 2. Preflight
  3. 3a. SRAM
  4. 3b. Internal flash
  5. Report
Original SKILL.md headings · 109 lines, 915 words
SKILL.md preview
---
name: upload-bitstream
description: Load an FPGA bitstream (.fs) onto the Tang Nano 9K, either into SRAM for a test run (gone at power-off) or into the GW1NR-9's internal flash so it loads at every power-up. Use this whenever the user wants to load, program, flash, upload, install or try a bitstream, FPGA design or SoC build on the board, or wants a fresh `fpga/build.sh` result running on the hardware, even if they don't say "bitstream". Also covers which bitstream the board holds and checking a build's timing before trusting it.
argument-hint: "[sram|flash] [file.fs]"
---

# Upload a bitstream to the Tang Nano 9K

| | SRAM (default) | Internal flash |
| --- | --- | --- |
| Lasts | until power-off or a reconfigure | loads at every power-up |
| Command | `openFPGALoader -b tangnano9k <fs>` | `openFPGALoader -b tangnano9k -f <fs>` (~12 s) |

Load into SRAM unless the user asks for the design to stay (flash it, make it permanent,
boot it at power-up). The internal flash is what the board runs when someone just plugs it
in, and the write erases it first: an interrupted write leaves the board with no design at
power-up. So write it only on an explicit request. "Flash both" means this skill plus
`upload-kernel` (SPI flash).

## 1. Pick the bitstream

- A fresh build is `fpga/impl/pnr/tang9k_soc.fs`. The current system is built with
  `SMODE=1 VIDEO=1 fpga/build.sh` (~2 min). `SMODE=0` is the stage-1 no-MMU CPU, which can't
  run the MMU kernel. Without `VIDEO=1` there is no HDMI, text console or splash, and the MMU
  kernel's DT names those devices.
- Check the build's timing before it goes on the board:
  ```
  python3 .claude/skills/upload-bitstream/scripts/timing_summary.py
  ```
  It prints the bitstream's md5 and date, Fmax against each clock's target, TNS, the
  worst paths and the logic use. It exits 1 if a clock misses. `cpu_clk` must reach 42 MHz
  with no negative slack at 42 MHz. A design that misses can still pass a quick test and
  then corrupt data at random, so don't load one that misses unless the user knowingly
  wants to try it.
  - The SDC keeps a 1.5 ns setup guard band on `cpu_clk` (`set_clock_uncertainty`), and
    Gowin's slack and Fmax include it. A good build shows TNS 0 with the band. One that
    eats into the band but still meets 42 MHz passes, with a note on the clock line: the
    script adds each path's uncertainty back. Prefer a rebuild with another `SDC_UNCERT`
    for something that goes into flash.
  - Hold violations inside the Gowin PSRAM IP's `u_psram_init` were a known, harmless
    exception while the SoC used the IP (until 2026-11-11). The SoC's own controller has
    none, so any hold violation now is real.
- Copy the build to a named file and load the copy:
  ```
  cp fpga/impl/pnr/tang9k_soc.fs /mnt/data/build/tang9k_linux/tang9k_soc_<tag>.fs
  ```
  The next build overwrites `fpga/impl/`. The named copies are how CLAUDE.md records what
  the board holds (`ls -lt /mnt/data/build/tang9k_linux/*.fs` lists the earlier ones). Pick
  a short tag for the change (`cbo`, `irq`, `text`).
- **The kernel has to match.** The kernel's device tree describes the hardware of the
  bitstream it was built with. On a bitstream without the text buffer, I2C or SPI blocks,
  that kernel's drivers talk to hardware that isn't there, and an older kernel can't use
  newer hardware. Pair a new
  bitstream with the kernel from the same point in time. When persisting, flash both.

## 2. Preflight

Put logs (`<log>` below) in the session's scratchpad directory.

```
pgrep -a 'programmer_cli|openFPGALoader'; lsusb | grep 0403:6010
```

- Only one program can hold the JTAG cable. If one of them is left over from an earlier run
  in this session, `kill -9` it (`programmer_cli` ignores SIGTERM). Otherwise openFPGALoader
  fails with "unable to claim usb device". Don't kill one you didn't start; ask instead,
  because it may be the user's Gowin programmer mid-write.
- If the board isn't in lsusb, ask the user to plug it in.
- Loading any bitstream resets the SoC and loses PSRAM, so a running Linux session is gone.
  Mention it if the user was using the board.

## 3a. SRAM

- To run something on it right away, let `sw/tools/qerv_boot.py` do the load. Its
  `--bitstream` option loads the SRAM first, then talks to the boot ROM:
  - `--bitstream <fs> --linux --mmu --timeout 120 --log <log> --input 'uname -a\n'` boots
    the kernel images over the UART (see `upload-kernel`).
  - `--bitstream <fs> --autoboot --timeout 120 --log <log>` sends nothing, so the ROM
    autoboots the SPI flash's kernel as at power-up.
  - `--bitstream <fs> --load prog.bin@0x80000000 --boot --timeout 5` runs a bare-metal test
    (`sw/tests/`).
- To load only: `openFPGALoader -b tangnano9k <fs>`. The boot ROM then prints `QERV boot ROM`
  on the UART (`/dev/ttyUSB1`, 1 Mbaud) and autoboots the flash's kernel after 2 s.
- `qerv_boot.py --reconfig ...` goes back to the internal flash's design without a power
  cycle.

## 3b. Internal flash

```
openFPGALoader -b tangnano9k -f /mnt/data/build/tang9k_linux/tang9k_soc_<tag>.fs 2>&1 \
  | tr '\r' '\n' | grep -aE 'CRC|rror'
```

- Success is `CRC check: Success`. On anything else, write again before the board is
  power-cycled.
- When writing both flashes, write the SPI flash first (`upload-kernel`, `flash_linux.sh`).
  Its tool erases the FPGA's SRAM and leaves Gowin's bridge there. Then write this one, then
  verify.
- Verify the power-up path:
  ```
  sw/tools/qerv_boot.py --reconfig --autoboot --timeout 120 --log <log> --input 'uname -a\n'
  ```
  This reloads the design from internal flash, as at power-up. Look for the ROM banner in
  the log and `[shell prompt after N s]` from the tool. With the current system that's about
  25 s. If the SPI flash holds no kernel, the banner alone confirms the design.
- Then update "What the board holds now" in CLAUDE.md: the named `.fs`, the date, and which
  kernel image it pairs with.

## Report

Say which file went where (path, md5 or tag), its Fmax and TNS, and the verification result
(ROM banner, shell prompt time). For a flash write, also say what it replaced: that comes
from CLAUDE.md's record before the update.
Files in this package (2)
  • SKILL.md 6 KB
  • scripts/timing_summary.py 6 KB

Versions

The database has no other skills named upload-bitstream.

Database snapshot: 13.11.2026 · package version 2c8b7f355044 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bitstream-program
    Generate a bitstream and program a Xilinx FPGA over JTAG, or build an MCS image and burn it into SPI/BPI configuration flash for power-on boot. Invoke when the user says "program the board", "generate bitstream", "flash the device", "download to FPGA", "burn the flash", "load my…
  • 100upload-kernel
    Put a Linux kernel on the Tang Nano 9K, either booted from RAM over the UART (temporary, the default) or written to the SPI flash so the board autoboots it at power-up. Use this whenever the user wants to run, boot, try, load, upload, flash or install a kernel, Image, DTB,…
  • 100fpga-bringup
    Use when loading a bitstream onto a physical FPGA and driving or observing it over JTAG or GPIO, especially bit-banged JTAG from a host like a Raspberry Pi, or when configuration silently fails
  • 100full-flow-demo
    Drive a Xilinx FPGA design end-to-end through the complete build flow: RTL -> simulation -> synthesis -> implementation -> bitstream, with a verification gate after every stage so a downstream stage never runs on an upstream stage that silently regressed. Invoke this skill when…
  • 90fpga_capture_bringup
    Use when bringing up a new FPGA board with an external ADC or high-speed capture, and when the build itself must be auditable: prove clock/reset, ADC timing, frame state machine, ILA alignment, then gate the build on timing, DRC, pin diff and bitstream hash. Covers the traps:…
  • 100fpga-design-to-board
    Develop and optimize an AMD FPGA RTL system through architecture decisions, source-bound simulation, Vivado implementation, and measured board validation. Use for FPGA design changes, resource or routing diagnosis, and reproducible delivery. Includes AXKU5P Qwen3 bit274 cases…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.