tools_for_fpga

tools_for_fpga/ is the target-side runtime bundle for a minimal RISC-V Linux machine. The intended deployment path is:

/dev/nhws0/tools_for_fpga/

The target contract is:

• target CPU/ABI: riscv64, little endian, lp64d
• target kernel: Linux 6.12.0 or compatible
• target filesystem: ext4
• target may provide /bin/bash, /bin/sh, /usr/bin/env, and coreutils
• Python, PyTorch, Triton ELF runtime libraries, glibc loader, and all .so dependencies must come from this directory, not from target /lib or /usr/lib

Runtime entrypoints

Only use these entrypoints on the target:

/dev/nhws0/tools_for_fpga/bin/tfpgarun pytorch/examples/ml_package_smoke.py
/dev/nhws0/tools_for_fpga/bin/tfpgarun triton-kernel/elf/flaggems-div-dynamic.elf

If you prefer the lower-level wrappers, you can still call:

cd /dev/nhws0/tools_for_fpga
./bin/run-python ./pytorch/examples/<script>.py
./bin/run-elf ./triton-kernel/elf/<kernel>.elf

bin/run-python invokes:

runtime/loader/ld-linux-riscv64-lp64d.so.1 --library-path ... python/bin/python3

bin/run-elf invokes the same bundled loader and refuses to run if the loader is missing, so it cannot fall back to target /lib or /usr/lib.

Build/stage the package

The package script stages only explicit RISC-V inputs. It intentionally refuses to silently copy host Python/PyTorch.

Example:

cd /Users/akibadi111/project/work/tools_for_fpga
python3 scripts/package.py \
  --python-prefix /path/to/riscv64-python-prefix \
  --sysroot /path/to/riscv64/sysroot \
  --search-root /path/to/riscv64/torch/runtime \
  --triton-root ../triton-kernel

If the RISC-V Python/PyTorch/sysroot inputs are absent, the script still leaves a package skeleton and writes manifest.json, but exits nonzero with a precise missing_inputs list.

The checked-in staging can also be reproduced from signed Ubuntu ports packages:

APT_NO_PROXY=1 \
UBUNTU_PORTS_MIRROR=http://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports \
scripts/download_ubuntu_riscv64_debs.sh

python3 scripts/stage_debian_debs.py \
  --rootfs .pkg-rootfs-riscv64-stage \
  $(find .pkg-cache/riscv64-debs -maxdepth 1 -name '*.deb' -printf ' --deb %p')

python3 scripts/package.py \
  --triton-root ../triton-kernel \
  --sysroot /usr/riscv64-linux-gnu \
  --python-rootfs .pkg-rootfs-riscv64-stage \
  --search-root .pkg-rootfs-riscv64-stage/usr/lib/riscv64-linux-gnu \
  --search-root .pkg-rootfs-riscv64-stage/usr/lib

Dependency checks

After staging, check that every ELF/.so dependency is closed inside the bundle:

python3 scripts/collect_deps.py --root . --search-root /path/to/riscv64/sysroot
python3 scripts/stage_broad_runtime_libs.py \
  --root . \
  --source .pkg-rootfs-riscv64-stage/usr/lib/riscv64-linux-gnu \
  --source .pkg-rootfs-riscv64-stage/usr/lib \
  --source /usr/riscv64-linux-gnu/lib
python3 scripts/scan_package.py --root .
python3 scripts/scan_package.py --root . --report deps-resolved-report.json

The scanner uses readelf, not ldd, so it does not execute target binaries and does not resolve through the host dynamic linker. The resolved report records each ELF object’s NEEDED entries and the exact in-bundle file paths that satisfy them. It also fails on missing libraries or non-riscv64 ELF files.

Verified locally

The bundle has been checked with QEMU user-mode on the build host:

# Dynamic Triton ELF through bundled ld-linux + bundled runtime libs.
qemu-riscv64 runtime/loader/ld-linux-riscv64-lp64d.so.1 \
  --library-path runtime/glibc:runtime/cxx:runtime/common:runtime/triton \
  triton-kernel/elf/flaggems-div-dynamic.elf

# RISC-V Python + PyTorch smoke through bundled ld-linux + bundled runtime libs.
qemu-riscv64 runtime/loader/ld-linux-riscv64-lp64d.so.1 \
  --library-path python/lib/python3/dist-packages/torch/lib:runtime/torch:runtime/common:runtime/glibc:runtime/cxx:python/lib \
  python/bin/python3 pytorch/examples/smoke.py

Both commands print PASS. runtime/broad/ additionally stages a broad pool of riscv64 shared libraries from the signed Ubuntu ports rootfs and the local riscv64 sysroot, so future PyTorch imports and Triton ELF dependencies have a larger in-bundle library set available while remaining under the 10GB target limit. The final resolved dependency report currently covers 892 ELF objects with 0 problems.

The current riscv64 Python environment has been validated with the following imports under QEMU user-mode:

./bin/run-python ./pytorch/examples/ml_package_smoke.py

This smoke covers:

• torch
• torchvision
• torchaudio
• pandas
• scipy
• sklearn
• PIL
• sentencepiece
• safetensors

The transformers, tokenizers, and torchtext package names were not present as installable riscv64 Ubuntu packages in the current mirror, so they are still not part of this staged set and would need a separate PyPI wheel or source-build path if you want them in the bundle.

The Ubuntu riscv64 libtorch2.6 package references three older gloo rendezvous symbols not exported by the matching libgloo0 package, so runtime/torch/libgloo_store_shim.so provides those unused rendezvous symbols and bin/run-python preloads it automatically. Basic tensor execution is verified; distributed gloo rendezvous is not part of this bundle’s contract.

Space policy

Do not stage CUDA, compilers, LLVM build trees, pip/conda caches, PyTorch source trees, or debug-symbol-heavy build outputs unless they are required at runtime. The target volume is limited to 10GB.

The .apt-riscv64/, .pkg-cache/, and .pkg-rootfs-riscv64-stage/ directories are build caches for reproducibility, not runtime requirements. They may be omitted from the final target copy if space is tight.