From ad1f7a6a3cd262cc084673ec5cf0c561328ec7c7 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Mon, 21 Sep 2026 11:09:36 -0400 Subject: Make repo fully path-portable and add reproducible installer - install.sh: one-command fresh-Ubuntu reproduction (deps, NVIDIA clone + patch, GSP firmware fetch from linux-firmware.git with objcopy .fwimage extraction + MD5 verify, ordered build, host config, load, mdev creation). Wrapper-neutral: works with libvirt/raw QEMU. - patches/nvidia: regenerated path-independent patch (KBUILD_EXTRA_SYMBOLS resolved via $(src)/$(CURDIR) relative to the NVIDIA tree). - scripts/stack_manager.sh and helper scripts auto-detect repo root (OPEN_IOV_ROOT override); no hardcoded developer paths anywhere. - firmware analysis scripts use script-relative paths (also fixes stale firmware/570-GSP references); docs/wiki updated to $OPEN_IOV_ROOT. - .github/workflows/ci.yml updated for standalone repo layout; firmware fetched from linux-firmware in CI. - Untrack remaining kbuild artifacts (Module.symvers, modules.order, *.o.d); gitignore them. - STATE.md: live project state, limitations, fixed/open bugs. - README.md: rewritten for clone-and-run reproducibility. --- docs/DEVELOPMENT_WORKFLOW.md | 94 ++++++++++++++++++++++---------------------- 1 file changed, 47 insertions(+), 47 deletions(-) (limited to 'docs') diff --git a/docs/DEVELOPMENT_WORKFLOW.md b/docs/DEVELOPMENT_WORKFLOW.md index 97aa267..2263af6 100644 --- a/docs/DEVELOPMENT_WORKFLOW.md +++ b/docs/DEVELOPMENT_WORKFLOW.md @@ -10,7 +10,7 @@ This document describes the complete development workflow, tooling, and shell in ### Primary Workspace ```bash -~/Git/open-iov/ # Main monorepo (git + LFS) +$OPEN_IOV_ROOT/ # Main monorepo (git + LFS) ``` ### Key Directories @@ -36,47 +36,47 @@ Add to `~/.zshrc` and run `source ~/.zshrc`: ```bash # Project navigation -alias oiv="cd ~/Git/open-iov" -alias oivk="cd ~/Git/open-iov/kernel" -alias oivu="cd ~/Git/open-iov/userspace" -alias oivf="cd ~/Git/open-iov/firmware/57X-GSP/570.144" -alias oivd="cd ~/Git/open-iov/docs" -alias oivs="cd ~/Git/open-iov/scripts" -alias oivt="cd ~/Git/open-iov/tools" +alias oiv="cd $OPEN_IOV_ROOT" +alias oivk="cd $OPEN_IOV_ROOT/kernel" +alias oivu="cd $OPEN_IOV_ROOT/userspace" +alias oivf="cd $OPEN_IOV_ROOT/firmware/57X-GSP/570.144" +alias oivd="cd $OPEN_IOV_ROOT/docs" +alias oivs="cd $OPEN_IOV_ROOT/scripts" +alias oivt="cd $OPEN_IOV_ROOT/tools" # Build commands -alias oiv-build="cd ~/Git/open-iov && make -j$(nproc)" -alias oiv-build-kernel="cd ~/Git/open-iov && make kernel" -alias oiv-build-userspace="cd ~/Git/open-iov && make userspace" -alias oiv-clean="cd ~/Git/open-iov && make clean" +alias oiv-build="cd $OPEN_IOV_ROOT && make -j$(nproc)" +alias oiv-build-kernel="cd $OPEN_IOV_ROOT && make kernel" +alias oiv-build-userspace="cd $OPEN_IOV_ROOT && make userspace" +alias oiv-clean="cd $OPEN_IOV_ROOT && make clean" # Module loading (requires reboot first!) -alias oiv-load="~/Git/open-iov/scripts/load_vgpu_stack.sh" -alias oiv-unload="~/Git/open-iov/scripts/unload_vgpu_stack.sh" -alias oiv-test="~/Git/open-iov/scripts/test_vgpu_stack.sh" -alias oiv-test-gsp="~/Git/open-iov/scripts/test_gsp_emu.sh" -alias oiv-test-guest="~/Git/open-iov/scripts/test_guest_driver.sh" -alias oiv-test-cuda="~/Git/open-iov/scripts/test_cuda_workloads.sh" -alias oiv-test-graphics="~/Git/open-iov/scripts/test_graphics_workloads.sh" -alias oiv-test-windows="~/Git/open-iov/scripts/test_windows_guest.sh" +alias oiv-load="$OPEN_IOV_ROOT/scripts/load_vgpu_stack.sh" +alias oiv-unload="$OPEN_IOV_ROOT/scripts/unload_vgpu_stack.sh" +alias oiv-test="$OPEN_IOV_ROOT/scripts/test_vgpu_stack.sh" +alias oiv-test-gsp="$OPEN_IOV_ROOT/scripts/test_gsp_emu.sh" +alias oiv-test-guest="$OPEN_IOV_ROOT/scripts/test_guest_driver.sh" +alias oiv-test-cuda="$OPEN_IOV_ROOT/scripts/test_cuda_workloads.sh" +alias oiv-test-graphics="$OPEN_IOV_ROOT/scripts/test_graphics_workloads.sh" +alias oiv-test-windows="$OPEN_IOV_ROOT/scripts/test_windows_guest.sh" # mdev management -alias oiv-mdev-create="~/Git/open-iov/scripts/create_mdev.sh" +alias oiv-mdev-create="$OPEN_IOV_ROOT/scripts/create_mdev.sh" alias oiv-mdev-list="ls -la /sys/bus/mdev/devices/ 2>/dev/null || echo 'No mdev devices'" # QEMU -alias oiv-qemu="~/Git/open-iov/scripts/launch_qemu_vgpu.sh" -alias oiv-qemu-debug="~/Git/open-iov/scripts/debug_guest_init.sh" +alias oiv-qemu="$OPEN_IOV_ROOT/scripts/launch_qemu_vgpu.sh" +alias oiv-qemu-debug="$OPEN_IOV_ROOT/scripts/debug_guest_init.sh" # Firmware analysis -alias oiv-ghidra="cd ~/Git/open-iov/tools/ghidra && ./ghidraRun" -alias oiv-fw-analyze="cd ~/Git/open-iov && python3 tools/firmware_analyzer.py" +alias oiv-ghidra="cd $OPEN_IOV_ROOT/tools/ghidra && ./ghidraRun" +alias oiv-fw-analyze="cd $OPEN_IOV_ROOT && python3 tools/firmware_analyzer.py" # Debugging tools (NEW) -alias oiv-guest-monitor="python3 ~/Git/open-iov/tools/guest_init_monitor.py" -alias oiv-failure-analyzer="python3 ~/Git/open-iov/tools/failure_analyzer.py" -alias oiv-benchmark="~/Git/open-iov/tools/benchmark_infrastructure.sh" -alias oiv-windows-test="~/Git/open-iov/scripts/windows_guest_automation.sh" +alias oiv-guest-monitor="python3 $OPEN_IOV_ROOT/tools/guest_init_monitor.py" +alias oiv-failure-analyzer="python3 $OPEN_IOV_ROOT/tools/failure_analyzer.py" +alias oiv-benchmark="$OPEN_IOV_ROOT/tools/benchmark_infrastructure.sh" +alias oiv-windows-test="$OPEN_IOV_ROOT/scripts/windows_guest_automation.sh" # Kernel debugging alias oiv-dmesg="dmesg -T | grep -i -e nvidia -e gsp -e vgpu -e open-iov -e mdev" @@ -85,12 +85,12 @@ alias oiv-dmesg-errors="dmesg -T | grep -i -e nvidia -e gsp -e vgpu -e open-iov alias oiv-trace="sudo cat /sys/kernel/debug/tracing/trace_pipe | grep gsp_emu" # Git -alias oiv-git="cd ~/Git/open-iov && git status" -alias oiv-git-log="cd ~/Git/open-iov && git log --oneline -20" -alias oiv-git-diff="cd ~/Git/open-iov && git diff" +alias oiv-git="cd $OPEN_IOV_ROOT && git status" +alias oiv-git-log="cd $OPEN_IOV_ROOT && git log --oneline -20" +alias oiv-git-diff="cd $OPEN_IOV_ROOT && git diff" # Restore point -alias oiv-restore="cd ~/Git/open-iov && git checkout f9ed5d8 -- . && git clean -fd" +alias oiv-restore="cd $OPEN_IOV_ROOT && git checkout f9ed5d8 -- . && git clean -fd" # Help oiv-help() { @@ -178,7 +178,7 @@ oiv-dmesg-follow # Live kernel logs ### Full Build ```bash -cd ~/Git/open-iov +cd $OPEN_IOV_ROOT make # Builds kernel + userspace + examples # OR oiv-build @@ -229,13 +229,13 @@ oiv-clean ### Load Order (Critical) ```bash # 1. NVIDIA OpenRM host driver (exports vGPU VFIO symbols) -sudo insmod ~/Git/open-iov/nvidia-open-gpu-kernel-modules/kernel-open/nvidia.ko +sudo insmod $OPEN_IOV_ROOT/nvidia-open-gpu-kernel-modules/kernel-open/nvidia.ko # 2. Open-IOV VFIO mdev driver (depends on nvidia.ko symbols) -sudo insmod ~/Git/open-iov/kernel/open-iov-vfio.ko +sudo insmod $OPEN_IOV_ROOT/kernel/open-iov-vfio.ko # 3. Guest vGPU driver (standalone, works without above) -sudo insmod ~/Git/open-iov/driver/gsp-vgpu.ko firmware_name=gsp-570.144.fwimage.bin +sudo insmod $OPEN_IOV_ROOT/driver/gsp-vgpu.ko firmware_name=gsp-570.144.fwimage.bin ``` ### Using Helper Script @@ -338,7 +338,7 @@ vncviewer localhost:1 ### Inside Guest VM ```bash # Run setup script (installs NVIDIA driver, firmware, loads module) -sudo ~/Git/open-iov/scripts/setup_guest_driver.sh +sudo $OPEN_IOV_ROOT/scripts/setup_guest_driver.sh # Or manual: # 1. Install NVIDIA driver (OpenRM 570.144) @@ -408,18 +408,18 @@ ffmpeg -hwaccel cuda -i test.mp4 -f null - ```bash # 1. Download firmware from NVIDIA OpenRM release # 2. Place in firmware dir -cp new-gsp.bin ~/Git/open-iov/firmware/570-GSP/gsp-XXX.fwimage.bin +cp new-gsp.bin $OPEN_IOV_ROOT/firmware/570-GSP/gsp-XXX.fwimage.bin # 3. Run Ghidra headless analysis -cd ~/Git/open-iov/tools/ghidra +cd $OPEN_IOV_ROOT/tools/ghidra ./support/analyzeHeadless /tmp/ghidra_project "gsp_XXX" \ - -import ~/Git/open-iov/firmware/570-GSP/gsp-XXX.fwimage.bin \ + -import $OPEN_IOV_ROOT/firmware/570-GSP/gsp-XXX.fwimage.bin \ -processor "RISCV:RV64:default" \ -postScript DecompileFunctions.java \ -deleteProject # 4. Run firmware analyzer (auto-discovers addresses) -cd ~/Git/open-iov +cd $OPEN_IOV_ROOT python3 tools/firmware_analyzer.py firmware/570-GSP/gsp-XXX.fwimage.bin > analysis_XXX.json # 5. Compare with previous version @@ -565,7 +565,7 @@ oiv-restore # git checkout f9ed5d8 -- . && git clean -fd ### Branch for Refactor ```bash -cd ~/Git/open-iov +cd $OPEN_IOV_ROOT git checkout -b refactor/host-gsp-emulation # Implement changes per docs/refactored-implementation-to-do.md ``` @@ -606,11 +606,11 @@ When you create new scripts or workflows, add them to `~/.zshrc`: ```bash # Example: Add new test command -alias oiv-test-cuda="~/Git/open-iov/scripts/test_cuda_workloads.sh" -alias oiv-test-gfx="~/Git/open-iov/scripts/test_graphics_workloads.sh" +alias oiv-test-cuda="$OPEN_IOV_ROOT/scripts/test_cuda_workloads.sh" +alias oiv-test-gfx="$OPEN_IOV_ROOT/scripts/test_graphics_workloads.sh" # Example: Add firmware analysis shortcut -alias oiv-fw-new="cd ~/Git/open-iov && python3 tools/firmware_analyzer.py firmware/57X-GSP/570.144/gsp-XXX.fwimage.bin" +alias oiv-fw-new="cd $OPEN_IOV_ROOT && python3 tools/firmware_analyzer.py firmware/57X-GSP/570.144/gsp-XXX.fwimage.bin" # Reload source ~/.zshrc @@ -656,5 +656,5 @@ Update `oiv-help()` function in `~/.zshrc` to include new commands. --- *Development Workflow Guide Version: 1.0* -*Repository: ~/Git/open-iov* +*Repository: $OPEN_IOV_ROOT* *Last Updated: $(date)* \ No newline at end of file -- cgit v1.2.3