upload-bitstream
/upload-bitstream
Wgrywa bitstream FPGA na płytkę Tang Nano 9K, do pamięci SRAM na próbę albo do trwałej pamięci flash.
- Autor
- phoenix367 ↗
- Repozytorium
- tang_nano_9K_linux ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 12.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/timing_summary.py
Co robi i kiedy
Wgrywa bitstream FPGA na płytkę Tang Nano 9K, do pamięci SRAM na próbę albo do trwałej pamięci flash.
Wyzwalacze z opisu
Argumenty
/upload-bitstream [sram|flash] [file.fs]
Oryginalny opis (EN)
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.
Jak działa
- 1. Pick the bitstream
- 2. Preflight
- 3a. SRAM
- 3b. Internal flash
- Report
Podgląd SKILL.md
---
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.
Pliki w paczce (2)
- SKILL.md 6 KB
- scripts/timing_summary.py 6 KB
Wersje
W bazie nie ma innych skilli o nazwie upload-bitstream.
Migawka bazy z 13.11.2026 · wersja paczki 2c8b7f355044 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100bitstream-program
Generuje bitstream i programuje FPGA Xilinx przez JTAG albo buduje obraz MCS i wypala go w pamięci konfiguracyjnej SPI lub BPI do rozruchu po włączeniu zasilania. - 100upload-kernel
Umieszcza jądro Linuksa na płytce Tang Nano 9K, uruchamiając je z RAM przez UART albo zapisując do flash, z DTB i rootfs. - 100fpga-bringup
Ładuje bitstream na fizyczny układ FPGA i steruje nim lub obserwuje go przez JTAG albo GPIO, także z bit-bangowanego JTAG na Raspberry Pi, oraz diagnozuje ciche porażki konfiguracji. - 100full-flow-demo
Prowadzi projekt FPGA Xilinx przez cały przepływ od RTL przez symulację, syntezę i implementację do bitstreamu, z bramką weryfikacyjną po każdym etapie. - 90fpga_capture_bringup
Uruchamia nową płytkę FPGA z zewnętrznym przetwornikiem ADC: sprawdza zegar, reset, czas ADC i ILA, a potem wstrzymuje build do czasu zaliczenia timingu, DRC i hashu bitstreamu. - 100fpga-design-to-board
Projektuje i optymalizuje system RTL na FPGA AMD: decyzje architektoniczne, symulacja, implementacja w Vivado i walidacja na płytce.