Skip to content

feat(dts): generate device trees at build time with nemu_board #71

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

Merged
rezado merged 14 commits into from
Sep 15, 2026
Merged

feat(dts): generate device trees at build time with nemu_board #71

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
90de069
feat(dts): generate firmware device trees from nemu_board profiles
rezado Sep 10, 2026
f0b4ca4
fix(linux): place single-hart DTB at 2 MiB and kernel at 4 MiB
rezado Sep 10, 2026
f34745b
feat(dts): select Kunminghu V2 with DTS_ISA_CONFIG
rezado Sep 10, 2026
3f9a8f0
chore(nemu_board): bump for the annotated rng-seed
rezado Sep 10, 2026
c3ebea9
fix(dts): preserve template semantics and validate generated profiles
rezado Sep 10, 2026
1d33467
chore: vendor nemu_board as regular directory
rezado Sep 11, 2026
7057044
refactor(dts): consolidate generator sources
rezado Sep 11, 2026
c29063b
fix(dts): restore custom template compatibility
rezado Sep 12, 2026
dccae23
fix(dts): remove source in json file
rezado Sep 14, 2026
24a1458
feat(dts): support Kunminghu V2 for qemu-nemu
rezado Sep 14, 2026
5495e8f
Merge branch 'main' into feat-dts-gen
rezado Sep 14, 2026
f8e6d25
Add debug controller condition for multiple harts
rezado Sep 15, 2026
95baca0
Update build dependencies for fw_payload.bin
rezado Sep 15, 2026
96e8fc6
Simplify profile data explanation in README
rezado Sep 15, 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
24 changes: 16 additions & 8 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,16 @@ MULTIHART ?= 0
PLATFORM ?= $(if $(filter 1,$(MULTIHART)),qemu,nemu)
HARTS ?= 2
QEMU_DEFAULT_DTB ?= xiangshan-qemu-nemu-mem2g
DTS_ISA_CONFIG ?= kunminghu-v3
DTS_DIR := build/generated-dts
export DTS_ISA_CONFIG

ifeq ($(filter $(PLATFORM),nemu qemu),)
$(error PLATFORM must be either nemu or qemu)
endif
ifeq ($(filter $(DTS_ISA_CONFIG),kunminghu-v2 kunminghu-v3),)
$(error DTS_ISA_CONFIG must be either kunminghu-v2 or kunminghu-v3)
endif
ifeq ($(filter 1,$(MULTIHART)),1)
ifneq ($(PLATFORM),qemu)
$(error MULTIHART=1 requires PLATFORM=qemu)
Expand All @@ -22,7 +28,8 @@ LINUX_ROOTFS_BUILD_VARS_HASH := $(shell printf '%s\n' \
LINUX_FIRMWARE_BUILD_VARS_HASH := $(shell printf '%s\n' \
'multihart=$(if $(filter 1,$(MULTIHART)),1,0)' \
'harts=$(if $(filter 1,$(MULTIHART)),$(HARTS),1)' \
'default_dtb=$(if $(LINUX_DEFAULT_DTB),$(LINUX_DEFAULT_DTB),xiangshan)' | sha256sum | cut -d ' ' -f 1)
'default_dtb=$(if $(LINUX_DEFAULT_DTB),$(LINUX_DEFAULT_DTB),xiangshan)' \
'dts_isa_config=$(DTS_ISA_CONFIG)' | sha256sum | cut -d ' ' -f 1)

MULTIHART_SUPPORTED_HARTS = $(shell seq 2 128)
ifeq ($(filter 1,$(MULTIHART)),1)
Expand Down Expand Up @@ -72,13 +79,14 @@ GCPT_SOURCE_DIR := $(if $(filter 1,$(MULTIHART)),bootloader/LibCheckpoint,bootlo
GCPT_BUILD_DIR := $(if $(filter 1,$(MULTIHART)),build/LibCheckpoint,build/LibCheckpointAlpha)
GCPT_BIN := $(GCPT_BUILD_DIR)/build/gcpt.bin
GCPT_DEFAULT_DTB ?= $(if $(DEFAULT_DTB),$(DEFAULT_DTB),$(if $(filter qemu,$(PLATFORM)),$(QEMU_DEFAULT_DTB),xiangshan))
GCPT_DEFAULT_DTS := dts/$(GCPT_DEFAULT_DTB).dts.in
GCPT_CONFIGURE_MODE := $(if $(filter 1,$(MULTIHART)),dual_core,normal)
GCPT_SERIAL_PORT ?= $(if $(filter 1,$(MULTIHART)),0x310b0000,)
GCPT_DTB_CONFIG_HASH := $(shell printf '%s\n' "$(GCPT_DEFAULT_DTB)" | sha256sum | cut -d ' ' -f 1)
GCPT_CONFIG_STAMP := $(if $(filter 1,$(MULTIHART)),build/LibCheckpoint-config/mode.$(GCPT_CONFIGURE_MODE).serial-port.$(GCPT_SERIAL_PORT),build/LibCheckpointAlpha-config/dtb.$(GCPT_DTB_CONFIG_HASH))
GCPT_SOURCES := $(if $(filter 1,$(MULTIHART)),$(shell find $(GCPT_SOURCE_DIR) -path '*/.git' -prune -o -path '*/tests' -prune -o -type f -print 2>/dev/null),$(shell find $(GCPT_SOURCE_DIR) -path '*/.git' -prune -o -type f -print 2>/dev/null))
GCPT_DTS_SOURCES := $(if $(filter 1,$(MULTIHART)),,$(GCPT_DEFAULT_DTS))
GCPT_DTS_SOURCES := dts/generate-nemu-board-dts.py dts/generate-workload-builder-dts.py \
dts/DTSGen.py dts/workload-builder-profiles.json \
$(wildcard dts/$(GCPT_DEFAULT_DTB).dts.in)
$(GCPT_CONFIG_STAMP):
mkdir -p "$(@D)"
rm -f $(if $(filter 1,$(MULTIHART)),build/LibCheckpoint-config/mode.*,build/LibCheckpointAlpha-config/dtb.*)
Expand All @@ -90,7 +98,7 @@ $(GCPT_BIN): scripts/build-gcpt.sh scripts/dts-config.sh $(TOOLCHAIN_WRAPPER) $(
GCPT_PAYLOAD_PATH="$(if $(filter 1,$(MULTIHART)),$(abspath $(SBI_BIN)),)" \
GCPT_SERIAL_PORT="$(GCPT_SERIAL_PORT)" \
DEFAULT_DTB="$(GCPT_DEFAULT_DTB)" \
DTS_TEMPLATE_DIR="$(abspath dts)" \
DTS_TEMPLATE_DIR="$(abspath $(DTS_DIR))" \
bash scripts/build-gcpt.sh $(GCPT_SOURCE_DIR) $(GCPT_BUILD_DIR)

# Build OpenSBI
Expand All @@ -99,11 +107,11 @@ $(SBI_CONFIG_STAMP):
mkdir -p "$(@D)"
rm -f "$(@D)"/dtb.* "$(@D)"/multihart-fixed
touch "$@"
$(SBI_BIN): scripts/build-sbi.sh scripts/dts-config.sh bootloader/opensbi.config $(TOOLCHAIN_WRAPPER) $(if $(filter 1,$(MULTIHART)),,$(GCPT_DEFAULT_DTS)) $(SBI_CONFIG_STAMP)
$(SBI_BIN): scripts/build-sbi.sh scripts/dts-config.sh $(GCPT_DTS_SOURCES) bootloader/opensbi.config $(TOOLCHAIN_WRAPPER) $(SBI_CONFIG_STAMP)
CROSS_COMPILE="$(abspath $(BUILDROOT_DIR)/output/host/bin)/riscv64-linux-" \
MULTIHART="$(MULTIHART)" \
DEFAULT_DTB="$(GCPT_DEFAULT_DTB)" \
DTS_TEMPLATE_DIR="$(abspath dts)" \
DTS_TEMPLATE_DIR="$(abspath $(DTS_DIR))" \
bash scripts/build-sbi.sh bootloader/opensbi $(SBI_BUILD_DIR)

define add_workload_linux
Expand Down Expand Up @@ -132,14 +140,14 @@ build/linux-workloads/$(1)/firmware-vars.$(LINUX_FIRMWARE_BUILD_VARS_HASH).stamp
rm -f "$$(@D)"/firmware-vars.*.stamp
touch "$$@"

build/linux-workloads/$(1)/$(LINUX_FIRMWARE_FILENAME): $$(shell find $$(abspath dts)) $(GCPT_BIN) $(GCPT_DEFAULT_DTS) scripts/build-sbi.sh scripts/dts-config.sh scripts/build-firmware-linux.sh build/linux-workloads/$(1)/rootfs.cpio $(LINUX_IMAGE) $(SBI_BIN) build/linux-workloads/$(1)/firmware-vars.$(LINUX_FIRMWARE_BUILD_VARS_HASH).stamp
build/linux-workloads/$(1)/$(LINUX_FIRMWARE_FILENAME): $(GCPT_DTS_SOURCES) $(GCPT_BIN) scripts/build-sbi.sh scripts/dts-config.sh scripts/build-firmware-linux.sh build/linux-workloads/$(1)/rootfs.cpio $(LINUX_IMAGE) $(SBI_BIN) build/linux-workloads/$(1)/firmware-vars.$(LINUX_FIRMWARE_BUILD_VARS_HASH).stamp
CROSS_COMPILE="$$(abspath $(BUILDROOT_DIR)/output/host/bin)/riscv64-linux-" \
DTC="$$(abspath $(BUILDROOT_DIR)/output/host/bin)/dtc" \
DEFAULT_DTB="$(LINUX_DEFAULT_DTB)" \
FIRMWARE_OUTPUT="$$(abspath $$@)" \
MULTIHART="$$(MULTIHART)" \
HARTS="$$(HARTS)" \
bash scripts/build-firmware-linux.sh $(GCPT_BIN) $(SBI_BUILD_DIR) dts $(LINUX_IMAGE) build/linux-workloads/$(1)
bash scripts/build-firmware-linux.sh $(GCPT_BIN) $(SBI_BUILD_DIR) $(DTS_DIR) $(LINUX_IMAGE) build/linux-workloads/$(1)

linux/$(1): build/linux-workloads/$(1)/$(LINUX_FIRMWARE_FILENAME)

Expand Down
26 changes: 19 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,9 @@ make linux/spec2006 BENCH=astar INPUT=biglakes \
with `PLATFORM=nemu` is rejected. It creates per-hart workload directories,
uses `/bin/nemu-trap` to send codes 256 and 257 before each benchmark copy and
code 258 after it returns, and requires `DEFAULT_DTB` to be set to the complete
DTS basename. Its matching template must exist in `dts/`; the build fails
rather than guessing a memory profile or generating a missing multi-hart DTS.
DTS basename. Recognized basenames are generated into `build/generated-dts`;
an unsupported basename can be supplied explicitly as `dts/<name>.dts.in`.
The build still fails rather than guessing an omitted hart or memory profile.
Other Linux workload targets remain NEMU-only.

SPECjbb2015 can be built from locally supplied licensed media and an RV64 JDK:
Expand Down Expand Up @@ -165,10 +166,11 @@ A multi-hart image uses the fixed QEMU checkpoint layout:
For OpenSBI, the multi-hart image uses `FW_TEXT_START=0x80100000`,
`FW_JUMP_ADDR=0x88600000`, and `FW_JUMP_FDT_ADDR=0x80200000`.

The canonical single-core and multi-hart DTS memory maps, including DRAM
profiles and DTS selection examples, are in [dts/README.md](dts/README.md#single-core-physical-memory-map).
The canonical DTS generator usage, DRAM profiles, and DTS selection examples
are in [dts/README.md](dts/README.md).

For single-core images, the selected DTS is the source of truth for the DRAM
For single-core images, the selected DTS is generated by the bundled generator at build
time and is the source of truth for the DRAM
base used by GCPT, OpenSBI, the firmware packer, and the exported manifest, as
well as the CLINT address used by GCPT. Its generated DTS and DTB are placed in
the workload's `dt` directory and the DTB is embedded in the firmware image.
Expand Down Expand Up @@ -284,8 +286,18 @@ Then run `make` to build your new workload.

## Adding a Device Tree

To add a device tree, create a template file `device_name.dts.in` in the `dts`
directory and select it with `DEFAULT_DTB=device_name`.
Device trees are generated from the sources in [dts/README.md](dts/README.md).
Use `DEFAULT_DTB=device_name` to select a built-in generator profile; Make
writes the resulting template to `build/generated-dts` before compiling it.
To add a custom device tree, place `dts/device_name.dts.in` in the repository
and select it with the same `DEFAULT_DTB=device_name` interface.

For generated `xiangshan-fpga-noAIA*` and `xiangshan-qemu-nemu*` templates, the
default ISA declaration is Kunminghu V3. Select V2 with
`DTS_ISA_CONFIG=kunminghu-v2`; for QEMU `nemu`, this uses the intersection of
the QEMU and Kunminghu V2 ISA declarations. The DTB basename continues to
select hart count, memory size, and vector mode. See the DTS README for
generator options, validation, provenance, and contributors.

Currently, the memory location of the initramfs containing the workload is passed to the kernel by device tree. So for each workload, device tree files are generated from the template on the fly, because the size of the initramfs cannot be known in advance. You should use the parameters `INITRAMFS_BEGIN` and `INITRAMFS_END` in the device tree template.

Expand Down
Loading
Loading