DE25-Standard · THDB-ADA project · bench notes

DE25 Bench Scripts

Two helper scripts in scripts/ take the Agilex 5 THDB-ADA project from a blank Quartus VM to a running board. Section 1 brings the remote JTAG cable across the LAN; section 2 loads the design into the FPGA's SRAM for a quick test or into the QSPI flash so it survives a power cycle.

scripts usbip_attach_all.sh · program_fpga.sh device 09fb:6022 Altera USB-Blaster II host 192.168.1.59 Quartus 26.1 Pro flash MT25QU128 ASx4

1Attaching the DE25 USB-Blaster over usbip

The Quartus VM has no USB port of its own. The board's JTAG cable lives on another machine, and scripts/usbip_attach_all.sh HOST pulls it across the LAN so jtagconfig and quartus_pgm can use it as if it were local.

1.1How the pieces connect

The DE25-Standard is plugged into a Windows PC at 192.168.1.59 that runs a usbipd server and shares the Blaster. On the Quartus VM, the vhci_hcd kernel module presents a virtual USB host controller; usbip attach imports the remote device onto it. From that point the Altera jtagd daemon and every Quartus tool see an ordinary local cable.

DE25-Standard Agilex 5 + ADA USB Windows PC 192.168.1.59 usbipd · port 3240 shares busid 8-1 LAN / TCP Quartus VM (this machine) usbip attach → vhci_hcd lsusb: Bus 002 · 09fb:6022 jtagd (root) → jtagconfig quartus_pgm → output_files/ada.sof
Once attached, the cable appears on USB bus 2 of the VM and the Quartus toolchain treats it as local.

1.2Before you run it

  • Board powered and shared. The DE25 must be on, and its Blaster must be bound and shared in usbipd on 192.168.1.59. Check with the list option in 1.4 if unsure.
  • usbip client present. Ubuntu ships it in linux-tools-generic. The vhci-hcd module is loaded by the script if it is missing.
  • sudo. Importing a USB device is a root operation. Run the script as yourself; it re-executes itself under sudo and prompts once.
  • Quartus path. The script verifies with ~/altera_pro/26.1/quartus/bin/jtagconfig. Set QUARTUS_BIN if your install differs.

1.3Quick start

From the project root, three commands take you from a blank VM to a programmed board.

# 1. bring the cable across and confirm the board is visible
./scripts/usbip_attach_all.sh workpc.akiragather.com.tw

# 2. build (skip if output_files/ada.sof is already current)
~/altera_pro/26.1/quartus/bin/quartus_sh --flow compile ada

# 3. program the Agilex 5, device index 1 in the chain
~/altera_pro/26.1/quartus/bin/quartus_pgm -c 1 -m jtag -o "p;output_files/ada.sof@1"

The script is idempotent. Running it when the cable is already imported just reports the port and re-runs jtagconfig.

1.4Options and overrides

(no flags)
Attach the Blaster from the default host, wait three seconds for enumeration, then run lsusb and jtagconfig.
-r HOST
Attach from a different usbipd host. Useful when the board moves to another bench PC.
-d
Detach the imported Blaster and hand it back to the remote PC. Finds the right vhci port by device ID, so no port number is needed.
-l
List every device the remote host exports and exit without attaching.
-h
Print the usage header.
Environment variableDefaultPurpose
USBIP_HOST192.168.1.59usbipd server holding the board. Same as -r.
USBIP_VIDPID09fb:6022USB vendor:product to look for. The script matches on this rather than a bus ID, so the remote bus number may change freely.
QUARTUS_BIN~/altera_pro/26.1/quartus/binWhere to find jtagconfig for the verification step.

1.5What success looks like

Output from a fresh attach on 2026-09-03. The device ID 4364C0DD is the Agilex 5 on the DE25; seeing it means the whole path from PC to FPGA is working.

./scripts/usbip_attach_all.sh workpc.akiragather.com.tw
Querying 192.168.1.59 for exportable devices...
Attaching bus 8-1 (09fb:6022) from 192.168.1.59...
Bus 002 Device 013: ID 09fb:6022 Altera DE25-Standard
--- jtagconfig:
1) DE25-Standard [2-1-iface0]
  4364C0DD   A5EC013(AB32A|BB32A)/..

Programming afterwards takes about eleven seconds and ends with Configuration succeeded at device index 1.

Tip Leave the cable attached for the whole bench session. Compile, program, and JTAG-UART capture all reuse it. Detach with -d only when the Windows PC needs the device back.

1.6When it does not work

SymptomLikely causeFix
Device 09fb:6022 is not exported by 192.168.1.59 The Blaster is not bound in usbipd, the board is off, or its USB cable is unplugged. On the Windows PC run usbipd list, then usbipd bind --busid 8-1. Re-run the script.
Script hangs or reports a connection error Host unreachable or usbipd service stopped. Port 3240 must be open. Ping the host, check the usbipd service, and confirm no firewall rule blocks 3240.
lsusb shows the device but jtagconfig says No JTAG hardware available Enumeration not finished, or jtagd started before the device existed. Wait a few seconds and run jtagconfig again. If it persists, sudo killall jtagd and retry; Quartus restarts it.
usbip attach fails with vhci_hcd errors Kernel module not loaded, or the running kernel has no matching linux-tools package. sudo modprobe vhci-hcd. Install linux-tools-$(uname -r) if usbip is missing for this kernel.
Device vanished mid-session Network drop or the remote PC rebooted. vhci does not reconnect on its own. Run ./scripts/usbip_attach_all.sh -d workpc.akiragather.com.tw to clear the stale port, then attach again.
Note The same host also exports two USB mass-storage devices. The script deliberately ignores them; attaching storage would pull those drives away from the Windows PC and auto-mount them here.

2Programming SRAM or flash with program_fpga.sh

scripts/program_fpga.sh wraps quartus_pgm and quartus_pfg. It checks the cable, warns when the bitstream is older than the sources, and then either loads the .sof straight into the FPGA or builds a .jic and writes it to the board's QSPI flash. It calls the section 1 script on its own if no JTAG hardware is visible.

2.1Two ways to load a design

default · SRAM Volatile, about 11 seconds

Configures the Agilex 5 directly from output_files/ada.sof over JTAG. The design runs until the board loses power or is reconfigured. Use this while iterating.

-f · QSPI flash Persistent, about 1.5 minutes

Generates output_files/ada.jic for the 128 Mbit MT25QU128 in Active Serial x4 mode, then erases, programs, and verifies the flash. The design loads itself on every power-up.

2.2Quick start

# load the current bitstream into SRAM for a bench test
./scripts/program_fpga.sh

# write it to flash so the board boots the design by itself
./scripts/program_fpga.sh -f

# edit sources, then compile and flash in one go
./scripts/program_fpga.sh -b -f

After a flash write the FPGA is still running the JIC helper image. Power-cycle the board once to see it boot from flash.

2.3Options and overrides

-s
SRAM mode. This is the default when no mode flag is given.
-f
Flash mode. Rebuilds the .jic only when it is missing or older than the .sof.
-b
Run the full Quartus compile (quartus_sh --flow compile ada) before programming. Several minutes on the Agilex 5.
-i FILE.sof
Program a different bitstream. The matching .jic is written next to it.
-c INDEX
Programming cable index for quartus_pgm. Default 1, which is the only cable when the Blaster is the sole imported device.
-d DEVICE
Flash part name for the JIC. Default MT25QU128, the part on the DE25-Standard.
-l
Print the JTAG chain and exit. Handy to confirm the cable before a long compile.
Environment variableDefaultPurpose
QUARTUS_BIN~/altera_pro/26.1/quartus/binLocation of quartus_pgm, quartus_pfg, quartus_sh, and jtagconfig.
PROJECTadaQuartus revision name. Sets the default .sof path and the compile target.
FLASH_LOADERA5ED013BB32AE4SCSThe FPGA part used as the serial flash loader inside the JIC. Matches the DE25-Standard's Agilex 5.

2.4What success looks like

SRAM run from 2026-09-03. The chain listing comes first, then the programmer's own progress lines.

./scripts/program_fpga.sh
--- JTAG chain:
1) DE25-Standard [2-1-iface0]
  4364C0DD   A5EC013(AB32A|BB32A)/..
--- Programming SRAM (volatile) with output_files/ada.sof
Info (213045): Using programming cable "DE25-Standard [2-1-iface0]"
Info (213011): Using programming file output_files/ada.sof with checksum 0x0610DFDA for device A5ED013BB32ACS@1
Info (18942): Configuring device index 1
Info (18943): Configuration succeeded at device index 1
Info: Quartus Prime Programmer was successful. 0 errors, 0 warnings
    Info: Elapsed time: 00:00:11

A flash run adds three more stages between configuration and the summary line.

Info (19094): Erasing flash chip select 0 at device index 1
Info (19096): Programming flash chip select 0 at device index 1
Info (19097): Verifying flash chip select 0 at device index 1
Info: Quartus Prime Programmer was successful. 0 errors, 0 warnings
    Info: Elapsed time: 00:01:37
Caution Flash mode overwrites whatever was in the QSPI, including Terasic's factory demo. The board's MSEL switches must stay in the Active Serial x4 position, the DE25-Standard default, or the flash image will not boot.

2.5When it does not work

SymptomLikely causeFix
WARNING: output_files/ada.sof is older than: ada.qsf ... Sources changed since the last compile. The board would get an outdated design. Re-run with -b, or compile in the Quartus GUI first.
Still no JTAG hardware The automatic attach in section 1 failed: board off, Blaster not shared, or host unreachable. Work through section 1.6, then retry.
Error (209012): Operation failed during configuration Cable dropped mid-transfer, or the .sof was built for a different device. Check -l shows device 4364C0DD, confirm the project device is A5ED013BB32AE4SCS, and program again.
Flash programs but the board boots the old design Board not power-cycled, or MSEL not set to ASx4. Power-cycle the board. If it still boots the old image, check the MSEL switch setting in the DE25-Standard manual.
quartus_pfg fails on the flash device name Typo in -d, or a board with a different QSPI part. Use MT25QU128 for the DE25-Standard. For other boards pick the part listed in the Programming File Generator GUI.