Skip to content

fpga_diff: organize UVHS flow and debug tools #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
xiaokamikami wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fpga_diff: organize UVHS flow and debug tools #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c4073c
fpga_diff: add Hejian UVHS flow and XiangShan support
xiaokamikami Jul 23, 2026
0b1f9b4
fpga_diff: add validated UVHS UHD capture flow
xiaokamikami Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions fpga_diff/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,27 @@
!*.vh
!*.xdc
!*.tcl
.tmp_*.tcl
tools/write_debug_probes.tcl
uvhs/assign_pin_native_nutshell_f2.tcl
uvhs/probe.tcl
uvhs/setenv.local.sh

fpga_*/
logs/
src/tcl/cpu_files.tcl
src/tcl/chi_files.tcl

# UVHS generated working trees and local configuration
uvhs_*/
runtime_uvhs_*/
uvhs/*.local.sh

# FPGA build outputs
*.bit
*.ltx
*.dcp
*.rtdb
*.rpt
*.rpx
hw.dat/
51 changes: 49 additions & 2 deletions fpga_diff/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,45 @@ RTL_INCLUDE ?=
FPGA_BIT_HOME ?=
WORKLOAD ?=
AXI_WIDTH ?= 64
PLATFORM ?= U2.2
# Host-trigger ILA capture is opt-in. Keep the trigger mark_debug net in RTL,
# but avoid instantiating the ILA core by default to reduce routing pressure.
ENABLE_ILA ?= 0
ILA_DEPTH ?= 16384
XDMA_LINK_WIDTH ?= X4
XDMA_ENABLE_PF0_BAR1 ?= 1
# Expected values for the checked Hejian XDMA EP x4 DCP used by the UVHS flow:
# BAR0 512 KiB, BAR1 64 KiB, endpoint 10ee:9048. They are carried into the
# Hejian scripts and host probes; do not treat them as a request to patch the
# Vivado xdma_ep Tcl source.
XDMA_AXILITE_MASTER_SCALE ?= Kilobytes
XDMA_AXILITE_MASTER_SIZE ?= 512
XDMA_EXPECTED_VENDOR ?= 0x10ee
XDMA_EXPECTED_DEVICE ?= 0x9048
XDMA_EXPECTED_BAR0_SIZE ?= 0x80000
XDMA_EXPECTED_BAR1_SIZE ?= 0x10000
UVHS_BASE_ASSEMBLE_FILE ?=
UVHS_BASE_ASSEMBLE_SHA256 ?= 0e44f3ced8e5628a6f9b60a36d15194f03f6eddefcf29d0221a8abf140ecb18b
UVHS_XDMA_EP_DCP ?=
UVHS_XDMA_EP_DCP_SHA256 ?= e40002b4ccab73d4d7a1398630f59428add0a64b9f33d284d3789595bb791b32
UVHS_XDMA_EP_EXPECTED_VIVADO ?= 2024.2
UVHS_ALLOW_DCP_VIVADO_MISMATCH ?= 0
UVHS_DESIGN_NAME ?= VU19P_X4
UVHS_TARGET_BOARD ?= B0
UVHS_TARGET_PACK ?= $(UVHS_TARGET_BOARD)
UVHS_TARGET_FPGA ?= F2
UVHS_TARGET_FPGA_LOWER ?= $(shell printf '%s.%s' '$(UVHS_TARGET_PACK)' '$(UVHS_TARGET_FPGA)' | tr '[:upper:]' '[:lower:]')
UVHS_FPGA_COUNT ?= 1
UVHS_CPU_CLK_PERIOD_NS ?= 40
UVHS_CPU_DEBUG_CLK ?= 1
UVHS_PNR_STRATEGY ?= Strategy_uv_high_fanout_explore
UVHS_COMPILE_STRATEGY_NUM ?= 1
UVHS_COMPILE_STRATEGY0 ?= uv_high_fanout_explore
UVHS_COMPILE_STRATEGY1 ?=
UVHS_COMPILE_STRATEGY2 ?=
VIVADO_JOBS ?=
DDR_RANK_WIDTH ?= 2
export ENABLE_ILA ILA_DEPTH XDMA_LINK_WIDTH VIVADO_JOBS DDR_RANK_WIDTH
export PLATFORM ENABLE_ILA ILA_DEPTH XDMA_LINK_WIDTH XDMA_ENABLE_PF0_BAR1 XDMA_AXILITE_MASTER_SCALE XDMA_AXILITE_MASTER_SIZE XDMA_EXPECTED_VENDOR XDMA_EXPECTED_DEVICE XDMA_EXPECTED_BAR0_SIZE XDMA_EXPECTED_BAR1_SIZE UVHS_BASE_ASSEMBLE_FILE UVHS_BASE_ASSEMBLE_SHA256 UVHS_XDMA_EP_DCP UVHS_XDMA_EP_DCP_SHA256 UVHS_XDMA_EP_EXPECTED_VIVADO UVHS_ALLOW_DCP_VIVADO_MISMATCH UVHS_DESIGN_NAME UVHS_TARGET_BOARD UVHS_TARGET_PACK UVHS_TARGET_FPGA UVHS_TARGET_FPGA_LOWER UVHS_FPGA_COUNT UVHS_CPU_CLK_PERIOD_NS UVHS_CPU_DEBUG_CLK UVHS_PNR_STRATEGY UVHS_COMPILE_STRATEGY_NUM UVHS_COMPILE_STRATEGY0 UVHS_COMPILE_STRATEGY1 UVHS_COMPILE_STRATEGY2 VIVADO_JOBS DDR_RANK_WIDTH
# Supported CPU parameters:
# kmh
# nutshell
Expand All @@ -23,7 +54,20 @@ PRJ_NAME = fpga_$(CPU)$(if $(strip $(SUFFIX)),-$(strip $(SUFFIX)),)
PRJ_DIR ?= $(ENV_SCRIPTS_HOME)/$(PRJ_NAME)
PRJ ?= $(PRJ_DIR)/$(PRJ_NAME).xpr

.PHONY: bitstream vivado dump_ila write_jtag_flash update_core_flist
UVHS_SUBMAKE = $(MAKE) -f $(CURDIR)/uvhs/Makefile ROOT_DIR="$(CURDIR)"

UVHS_FORWARD_TARGETS := \
uvhs_prepare uvhs_export_vivado_ip \
uvhs_show_uvw_axi4_to_ddr4 uvhs_filelist uvhs_check_modules \
uvhs_tools_check uvhs_frontend uvhs_backend uvhs_all \
uvhs_clean uvhs_env uvhs_preflight uvhs_hejian_pcie_x4_env \
uvhs_hejian_pcie_x4_preflight uvhs_hejian_pcie_x4_nutshell_all \
uvhs_hejian_pcie_x4_nutshell_probe_all \
uvhs_hejian_pcie_x4_xiangshan_all \
uvhs_status uvhs_check_timing_clean uvhs_export_ltx \
uvhs_package_bitstream

.PHONY: bitstream vivado dump_ila write_jtag_flash update_core_flist $(UVHS_FORWARD_TARGETS)

# Get Vivado version
VIVADO_VERSION := $(shell vivado -version 2>/dev/null | head -1 | grep -o '[0-9]\{4\}\.[0-9]' || echo "unknown")
Expand All @@ -43,6 +87,9 @@ bitstream:
update_core_flist:
@./tools/update_core_flist.sh "$(CORE_DIR)" -- $(RTL_INCLUDE)

$(UVHS_FORWARD_TARGETS):
$(UVHS_SUBMAKE) $@

# Launch Vivado with FPGA project configuration
vivado: check_vivado_version
vivado -mode batch -source src/tcl/common/xs_uart.tcl -tclargs --cpu $(CPU) --project_name $(PRJ_NAME) --vivado_version $(VIVADO_VERSION)
Expand Down
24 changes: 24 additions & 0 deletions fpga_diff/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,4 +48,28 @@ FPGA_DDR_LOAD_CMD="bash -lc ' \
./fpga-host --diff <nemu> -i <workload>.bin
```

HJ/UVHS FPGA Flow
=================

The Hejian NutShell source-flow index is [uvhs/README.md](uvhs/README.md);
the canonical build, signoff, runtime, FPGA-host, and cleanup runbook is
[uvhs/flow.md](uvhs/flow.md).

A typical build starts with:

```shell
make uvhs_tools_check
make uvhs_hejian_pcie_x4_preflight CORE_DIR=/path/to/NutShell
make uvhs_hejian_pcie_x4_nutshell_all \
CORE_DIR=/path/to/NutShell SUFFIX=<unique-tag>
make uvhs_package_bitstream CPU=nutshell \
UVHS_WORK_DIR=/path/to/fpga_diff_uvhs_nutshell-<unique-tag>
```

Copy `uvhs/setenv.local.example.sh` to the ignored `setenv.local.sh` for
machine-specific tools and licenses. The caller supplies `CORE_DIR`, verified
UVHS DDR/XDMA IP assets, and a unique build suffix. Program the resulting
`hw.dat` through the vendor runtime using `user_script/hw_run_download.tcl`.
The normal `fpga-host` path loads workloads through H2C. Use
`uvhs_tagged_runtime.sh` so runtime sessions and cleanup remain exact-tag
scoped; keep board-specific debug helpers local.
Loading