From b9927b7acf0c29e11e61eb22a953a4e608dc4f1e Mon Sep 17 00:00:00 2001 From: vasilito Date: Thu, 2 Jul 2026 01:14:52 +0300 Subject: [PATCH] docs: document build architecture in INTERFACES.sh Add a 'Build Architecture' section explaining the substrate approach (Ventoy modsrc as the GRUB binary), the runtime bridge via the hiperiso_boot GRUB script function, the two hardcoded layout constraints (FAT label 'VTOYEFI', /ventoy/ventoy.cpio at the ESP root), and the modsrc sed-patch strategy. Without this, a future contributor reading the build script will not understand why BOOTX64.EFI has ventoy_* symbols and the source tree has unused hiperiso_*.c files; they will likely try another incomplete rebrand. --- INTERFACES.sh | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/INTERFACES.sh b/INTERFACES.sh index a828604..e36074d 100644 --- a/INTERFACES.sh +++ b/INTERFACES.sh @@ -167,3 +167,34 @@ HIPERISO_JSON="${DATA_MOUNT}/hiperiso/hiperiso.json" # Usage: hiperiso-log trace [--format json|csv|text] # Usage: hiperiso-log serial [--stages] # Output: writes report.json, report.txt, and analysis.meta into + +# ── Build Architecture ───────────────────────────────────────────────────── +# The GRUB binary shipped as $EFI_PAYLOAD_DIR/../BOOTX64.EFI is built from +# Ventoy 2.04 + vendor/grub2-modsrc.tar.xz (Ventoy's GRUB core patches). +# This is the "substrate" approach: rather than rename Ventoy symbols to +# hiperiso_*, we keep the Ventoy module intact and bridge to a hiperiso +# runtime via two channels: +# +# 1. Runtime cmdline: the GRUB script function `hiperiso_boot` in +# $GRUB_CFG constructs a `hiperiso_iso=...` cmdline and runs +# `linux` + `initrd` + `boot` against the host kernel + QEMU +# initramfs under $EFI_PAYLOAD_DIR/. +# +# 2. Layout: the FAT16 volume label MUST be "VTOYEFI" and the +# /ventoy/ventoy.cpio file MUST exist at the ESP root — both are +# hardcoded checks in the modsrc's ventoy_check_official_device(). +# The label and file are produced by scripts/package_release.sh. +# +# Modsrc patches: scripts/build_grub2_204.sh applies a single sed +# pass to the unpacked modsrc tree to (1) accept a 64MB ESP (modsrc +# hardcodes 32MB / 65536 sectors) and (2) tolerate the missing 0x22 +# GPT-MBR marker byte. (The 0x22 marker is written by the installer +# in HiperisoWorker.sh — not by the build.) Anything beyond these +# patches is upstream Ventoy territory; do not modify modsrc without +# bumping the version check in scripts/build_all.sh. +# +# The hiperiso-specific C sources in src/grub2/hiperiso_*.c are kept +# in-tree as historical reference but are not compiled or shipped. +# They document an earlier (incomplete) rebrand attempt; their +# unmodified use would break moddep.lst generation. +