Nanhu Linux DDR / E6 一页复现指南

这个仓库的目标很单一：生成南湖 FPGA 上板用的 Linux DDR 加载包，并把 E6 driver、workspace、smoke payload 和验证脚本串成一条可复现的链路。

如果你只想先跑通一次，直接看“快速开始”。如果你想知道每个目录负责什么，看“分层模块图”。如果你想确认结果是否可信，看“验证矩阵”。

0. 快速开始

cd /Users/akibadi111/project/nanhu-linux-ddr
make check-env
make workspace-final
make verify-workspace-final

构建完成后，主输出在：

output/workspace-final/

把它拷到 runtime 服务器后，在服务器上重新 load：

scp -r output/workspace-final \
  hjuser@172.38.9.112:/home/hjuser/Desktop/NH_260803/test/
cd /home/hjuser/Desktop/NH_260803
make uv_run0 layout=/home/hjuser/Desktop/NH_260803/test/workspace-final/ddr-load.plan

进入板上 Linux 后，最小验证命令是：

dmesg | grep -i e6
ls -lh /dev/e6npu0
/workspace/bin/e6-iface-test all

预期结果：

/dev/e6npu0 存在
PASS: e6-iface-test all

1. 分层模块图

1.1 Board / boot 层

路径	作用
`board/`	DTS、stage0 汇编和 linker script
`build-14m7456.sh`	14m7456 目标镜像构建脚本
`build-phase1.sh`	Phase1 基础构建脚本
`build-workspace-final.sh`	全量复现脚本：Linux + OpenSBI + stage0 + workspace

1.2 DDR layout 层

路径	作用
`layout/`	不同 bundle 的 DDR 布局 TOML
`scripts/generate_ddr_bundle.py`	根据 layout 生成 `module_table.bin`、`ddr-load.plan`、DTS 片段和 header

1.3 Rootfs / workspace 层

路径	作用
`rootfs-overlay/`	注入 initramfs 的启动脚本
`workspace-root/`	`/workspace` 的种子目录
`software-workspace-sdk/`	只重打包 `/workspace` 的 SDK

workspace-root/startup.sh 是故意不阻塞的；它只打印建议命令，不会拦住 Linux 进入 shell。

1.4 Experiments / validation 层

路径	作用
`experiments/e6-iface-test/`	Linux driver 接口测试
`experiments/e6-mmap-runner/`	E6 加载 / 执行调试 runner
`experiments/e6-firmware/`	RV32 smoke firmware
`experiments/e6-firmware-rv64/`	RV64 smoke firmware
`experiments/four-segment-smoke/`	four-segment smoke 输入样例

1.5 Automation / verification 层

路径	作用
`scripts/`	构建、打包、验证辅助脚本
`module-tools/`	读取和校验 module table 的小工具

1.6 Source / vendor 层

路径	作用
`src/linux-6.12/`	Linux 主源码树
`src/busybox-1.36.1/`	BusyBox 源码树
`src/opensbi-1.3-qemu/`	OpenSBI 源码树
`configs/`	Linux / BusyBox 基础配置
`third_party/`	第三方源码、patch 和 provenance
`userland/`	额外 userland 源码

2. 构建模式

2.1 全量复现：Linux + E6 driver + workspace

这是默认推荐路径。它会重新生成：

Linux kernel
OpenSBI
stage0
/workspace ext4 镜像
module_table.bin 和 ddr-load.plan
最终的 output/workspace-final/

命令：

make workspace-final
make verify-workspace-final

2.2 只重打包 `/workspace`

如果只改了 /workspace 里的软件、脚本、输入数据、模型或库，不需要重编 Linux / E6 driver：

make package-workspace DIR=/absolute/path/to/software-root
make verify-package-workspace

这里的 software-root 必须是板上 /workspace 的根目录。

2.3 Smoke bundles

两个独立的 smoke 路径：

make four-segment-smoke
make verify-four-segment-smoke

make high-address-smoke
make verify-high-address-smoke

2.4 SDK / bundle 复现

如果只想验证 workspace SDK 发布物：

make workspace-sdk
make verify-workspace-sdk

3. 可复现步骤

步骤 1：检查主机依赖

make check-env
make versions

需要的核心工具包括：make、dtc、python3、mkfs.ext4、e2fsck、debugfs 和 RISC-V 工具链。

步骤 2：生成完整 bundle

make workspace-final

主输出目录：

output/workspace-final/

关键文件：

linux_base.bin
module_table.bin
ddr-load.plan
SHA256SUMS
WORKSPACE_TREE.txt
workspace-root/
workspace-extents/

步骤 3：静态验证

make verify-workspace-final

这个目标是最终 bundle 的合同检查，覆盖 ext4 镜像、load plan、workspace tree、DTS、kernel config 和 sparse extents。

步骤 4：上传到 runtime 服务器

scp -r output/workspace-final \
  hjuser@172.38.9.112:/home/hjuser/Desktop/NH_260803/test/

注意：不要直接上传 build-workspace-final/software_workspace.ext4，它是内部构建产物。真正需要 load 的是 output/workspace-final/ddr-load.plan 和同目录下的 bundle 文件。

步骤 5：在 runtime 服务器上 load

cd /home/hjuser/Desktop/NH_260803
make uv_run0 layout=/home/hjuser/Desktop/NH_260803/test/workspace-final/ddr-load.plan

如果只 scp、不重新 load，板上的 /workspace 仍然可能是旧镜像。

步骤 6：在板上确认 E6 driver

dmesg | grep -i e6
ls -lh /dev/e6npu0
ls -lh /workspace/bin/e6-iface-test \
       /workspace/bin/e6-mmap-runner \
       /workspace/e6/e6-smoke.bin \
       /workspace/e6/e6-smoke-rv64.bin
/workspace/bin/e6-iface-test all

预期：

/dev/e6npu0 存在
PASS: e6-iface-test all

4. 验证矩阵

目标 / 脚本	验证内容
`make verify-workspace-final`	`scripts/verify_workspace_final.sh`；最终 bundle 的静态合同
`make verify-four-segment-smoke`	`scripts/verify_four_segment_smoke.sh`；four-segment smoke 输出
`make verify-high-address-smoke`	`scripts/verify_high_address_smoke.sh`；高地址 smoke 输出
`make verify-workspace-sdk`	`scripts/verify_workspace_sdk_release.sh`；SDK 发布物一致性
`make verify-package-workspace`	`software-workspace-sdk/verify-sdk.sh ./output/workspace-final`；软件-only bundle 一致性

4.1 workspace-final 的参考合同

scripts/verify_workspace_final.sh 会检查：

output/workspace-final/ 下的 checksum
WORKSPACE_TREE.txt
workspace-extents/
kernel config 中的关键选项
ddr-load.plan 和 module_table.bin
workspace 中是否真的包含：
- /workspace/bin/e6-iface-test
- /workspace/bin/e6-mmap-runner
- /workspace/e6/e6-smoke.bin
- /workspace/e6/e6-smoke-rv64.bin

5. 清理建议

5.1 可以删除的生成物

下面这些通常只是本地构建缓存或实验产物：

build-busybox-dynamic/
build-busybox-scalar/
build-e6-compile-test/
build-workspace-final/（删除后需重新 make workspace-final，再运行 make verify-workspace-final）
output/e6-transfer/
output/e6-transfer-scalar-baseline/
output/e6-transfer-scalar-host/
scripts/__pycache__/
src/build-e6-compile-test
src/linux-6.12/build-e6-compile-test
experiments/*/build/

5.2 先保留的内容

以下内容属于文档化流程或已验证的参考输入，默认不要删：

board/
configs/
layout/
rootfs-overlay/
scripts/
software-workspace-sdk/
module-tools/
workspace-root/
third_party/
userland/
src/
output/workspace-final/
output/four-segment-smoke/
output/high-address-smoke/
output/phase1/

历史诊断输入如果还要保留，只把它们当作 archive，不要把它们当成默认主流程的一部分：

build-14m7456-pathtrace.sh
board/opensbi-1.3-nanhu-pathtrace.patch
board/nanhu-fpga-singlecore.dts

5.3 清理原则

不要删除任何被 make verify-*、software-workspace-sdk/verify-sdk.sh 或 scripts/verify_workspace_final.sh 明确消费的文件，除非你同时更新了验证合同。

6. 常见问题

`/dev/e6npu0` 不存在

先检查：

是否用新的 linux_base.bin 启动
CONFIG_NANHU_E6=y 是否生效
DTS 中是否包含 E6 节点

`/workspace/bin/e6-iface-test` 不存在

通常是以下原因之一：

没有重新执行 make workspace-final
拷贝了文件，但没有用新的 ddr-load.plan 重新 load

`e6-mmap-runner` 全 0

这表示 E6 执行路径仍需继续排查。Linux driver 的基础接口先以 e6-iface-test all 为准。

7. 关键源码位置

src/linux-6.12/drivers/misc/e6_driver.c       E6 Linux driver
src/linux-6.12/include/uapi/linux/e6.h        E6 ioctl ABI
board/nanhu-fpga-singlecore-workspace-14m7456.dts
experiments/e6-iface-test/                    driver 接口测试
experiments/e6-mmap-runner/                   E6 执行调试 runner
experiments/e6-firmware/                      RV32 smoke firmware
experiments/e6-firmware-rv64/                 RV64 smoke firmware
build-workspace-final.sh                      全量构建脚本
software-workspace-sdk/pack-workspace.sh      软件-only 打包脚本