vasilito
b9927b7acf
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.
201 lines
12 KiB
Bash
201 lines
12 KiB
Bash
# hiperiso Interface Contracts
|
|
# =============================
|
|
# ALL components MUST conform to these definitions.
|
|
# This file is the single source of truth for inter-component interfaces.
|
|
|
|
# ── Kernel Command Line Parameters (GRUB2 → host kernel → initramfs) ──────────
|
|
# These are set by the GRUB2 hiperiso_boot command and parsed by initramfs/init.
|
|
HIPERISO_ISO_PATH="" # Path to ISO file on USB data partition (e.g. /ISOs/ubuntu.iso)
|
|
HIPERISO_LOG_DIR="" # Directory for boot logs (e.g. /hiperiso/logs/ubuntu/)
|
|
HIPERISO_TRACE_LEVEL="" # Trace tier: "standard" | "detailed" | "full" | "none"
|
|
HIPERISO_GUEST_RAM="" # Guest RAM in MB (default: 2048)
|
|
HIPERISO_GUEST_CPUS="" # Guest vCPUs (default: 2)
|
|
HIPERISO_DISPLAY="" # Display mode: "none" | "gtk" | "vnc" (default: none)
|
|
HIPERISO_VGA="" # VGA mode: "none" | "std" | "virtio" (default: std)
|
|
HIPERISO_FALLBACK="" # Force fallback mode: "1" skips KVM check
|
|
|
|
# ── Plugin Parameters ─────────────────────────────────────────────────────────
|
|
# These are resolved by the GRUB2 module from hiperiso.json plugins and passed
|
|
# via kernel cmdline to the initramfs, which translates them to QEMU args.
|
|
HIPERISO_AUTO_INSTALL="" # Path to auto-install script (kickstart/preseed)
|
|
HIPERISO_PERSISTENCE="" # Path to persistence .dat file
|
|
HIPERISO_DUD="" # Path to Driver Update Disk image
|
|
HIPERISO_INJECTION="" # Path to injection archive (tar.gz)
|
|
HIPERISO_CONF_REPLACE="" # Config replacement: "org=/path;new=/path"
|
|
HIPERISO_SECURE_BOOT="" # "1" = use Secure Boot OVMF firmware
|
|
HIPERISO_TPM="" # "1" = attach virtual TPM (swtpm)
|
|
HIPERISO_CPU_FEATURES="" # Comma-separated CPU features: "vmx,svm"
|
|
HIPERISO_BOOT_MODE="" # "normal" | "memdisk" | "grub2"
|
|
HIPERISO_NET_DUMP="" # "1" = add virtio-net + pcap capture to network.pcap
|
|
|
|
# ── USB Partition Layout ─────────────────────────────────────────────────────
|
|
DATA_PART="/dev/sdX1" # Partition 1: Data partition (exFAT/NTFS, rest of disk)
|
|
EFI_PART="/dev/sdX2" # Partition 2: EFI System Partition (FAT16, 64MB)
|
|
EFI_MOUNT="/mnt/efi" # Mount point for ESP during install
|
|
DATA_MOUNT="/mnt/usb" # Mount point for data partition at runtime
|
|
|
|
# ── File Paths (on EFI partition) ────────────────────────────────────────────
|
|
EFI_PAYLOAD_DIR="/EFI/hiperiso"
|
|
KERNEL_PATH="${EFI_PAYLOAD_DIR}/vmlinuz"
|
|
INITRAMFS_PATH="${EFI_PAYLOAD_DIR}/initramfs.cpio.gz"
|
|
OVMF_PATH="${EFI_PAYLOAD_DIR}/OVMF.fd"
|
|
TRACE_EVENTS_DIR="${EFI_PAYLOAD_DIR}/trace"
|
|
GRUB_CFG="/EFI/BOOT/grub.cfg"
|
|
HIPERISO_JSON="${DATA_MOUNT}/hiperiso/hiperiso.json"
|
|
|
|
# ── Log Directory Structure (per ISO boot session) ───────────────────────────
|
|
# Each boot creates a unique timestamped directory:
|
|
# /hiperiso/logs/<sanitized-iso-basename>_<UTC-timestamp>/
|
|
#
|
|
# Guaranteed artifacts (always written once the session dir exists, even when
|
|
# the boot fails before QEMU launches):
|
|
# session.json - Session manifest (structured metadata for agent intake)
|
|
# status.json - Live status, rewritten at every stage transition
|
|
# env.txt - Environment snapshot (host kernel, RAM, CPU, KVM, config)
|
|
#
|
|
# Conditional artifacts (present depending on how far the boot progressed):
|
|
# serial.log - Tier 1: Serial console output (written by QEMU)
|
|
# trace.bin - Tier 2+: QEMU simpletrace (only when trace_level != none)
|
|
# qemu.cmdline - Exact QEMU command line used (written before launch)
|
|
# monitor.sock - QEMU monitor socket (live introspection while guest runs)
|
|
# timing.dat - Raw boot phase timing (TSV: phase<TAB>uptime<TAB>iso8601)
|
|
# timing.json - Structured boot timing with per-phase deltas
|
|
# hw/ - Hardware inventory directory (host + QEMU guest data)
|
|
# network.pcap - Network packet capture (only when net_dump=1)
|
|
# report.json - Generated analysis report (auto-run after QEMU exits)
|
|
# report.txt - Human-readable report (auto-run after QEMU exits)
|
|
# report.log - Raw output from the hiperiso-log analyze invocation
|
|
# analysis.meta - Flat KEY=VALUE derived-analysis sidecar (written by
|
|
# hiperiso-log; consumed by init to fold boot_result /
|
|
# failure_domain / graphics hints into the final manifest)
|
|
# HEARTBEAT - Periodic liveness marker from the log_flush daemon
|
|
# SESSION_COMPLETE - Sentinel written when the session ended (success OR
|
|
# failure), by hiperiso_finalize_session
|
|
# FAILURE.txt - Human-readable failure summary (present only on failure)
|
|
#
|
|
# ── session.json (session manifest; written at start, REWRITTEN at end) ──────
|
|
# On start only the fields up to start_time_utc/kvm/trace_level/ram/cpus are
|
|
# present with status="started". At session end hiperiso_finalize_session()
|
|
# rewrites it as the canonical manifest with the full field set below.
|
|
# {
|
|
# "session_id": "<basename>_<UTC-timestamp>", # == dir basename
|
|
# "status": "complete" | "failed", # final lifecycle state
|
|
# "result": "success" | "failure" | "incomplete" | "no_serial",
|
|
# # derived boot result
|
|
# "iso_path": "/ISOs/<name>.iso",
|
|
# "iso_basename": "<name>.iso",
|
|
# "log_dir": "/hiperiso/logs/<dir>", # no trailing /
|
|
# "start_time_utc": "YYYY-MM-DDTHH:MM:SSZ", # captured at start
|
|
# "end_time_utc": "YYYY-MM-DDTHH:MM:SSZ", # captured at finalize
|
|
# "kvm": "available" | "unavailable" | "unknown",
|
|
# "trace_level": "standard" | "detailed" | "full" | "none",
|
|
# "guest_ram_mb": 2048, # number, MB
|
|
# "guest_cpus": 2, # number
|
|
# "qemu_exit_code": 0, # number or null
|
|
# "report_available": 1, # 1 if report.json exists
|
|
# "host": { # non-identifying host metadata
|
|
# "kernel_version": "Linux version 6.6.0...",
|
|
# "cpu_model": "Intel(R) Core(TM) i7-...",
|
|
# "cpu_logical_cores": 8,
|
|
# "total_ram_mb": 16384,
|
|
# "virt_supported": true
|
|
# },
|
|
# "analysis": { # derived by hiperiso-log
|
|
# "boot_result": "success" | "failure" | "incomplete" | "no_serial",
|
|
# "boot_stage_final": "login" | "userspace" | ... | "error" | "unknown",
|
|
# "failure_domain": "none" | "firmware" | "bootloader" | "kernel" |
|
|
# "hardware" | "userspace" | "unknown",
|
|
# "reached_login": 1,
|
|
# "kernel_panic_count": 0,
|
|
# "error_count": 0,
|
|
# "has_serial": 1,
|
|
# "has_trace": 1,
|
|
# "boot_duration_ms": 12345,
|
|
# "graphics_drivers": "i915,virtio_gpu", # comma-sep, may be ""
|
|
# "graphics_resolution": "1024x768" # may be ""
|
|
# },
|
|
# "hw_inventory": { # hardware data availability
|
|
# "available": true, # false if hw/ is empty
|
|
# "files": "host_cpuinfo.txt,qemu_qtree.txt,...",
|
|
# "has_timing": true # timing.json was generated
|
|
# "has_network_pcap":false # network.pcap exists
|
|
# }
|
|
# }
|
|
#
|
|
# ── /hiperiso/logs/index.jsonl (append-only global corpus index) ─────────────
|
|
# One compact JSON object per line; appended on BOTH success and failure by
|
|
# hiperiso_finalize_session(). Machine-readable for corpus ingestion:
|
|
# {"session_id":"...","status":"complete","result":"success",
|
|
# "iso_basename":"...","iso_path":"...","log_dir":"...",
|
|
# "start_time_utc":"...","end_time_utc":"...",
|
|
# "kvm":"available","trace_level":"standard",
|
|
# "qemu_exit_code":0,"report_available":1,
|
|
# "boot_result":"success","boot_stage_final":"login","failure_domain":"none",
|
|
# "graphics_drivers":"i915"}
|
|
#
|
|
# ── status.json (live status, rewritten at each stage transition) ────────────
|
|
# {
|
|
# "session_id": "<basename>_<UTC-timestamp>", # string
|
|
# "status": "started" | "running" | "complete" | "failed",
|
|
# "stage": "<current_stage>", # see stages below
|
|
# "qemu_exit_code": 0, # number, optional
|
|
# "timestamp_utc": "YYYY-MM-DDTHH:MM:SSZ"
|
|
# }
|
|
# Known stages: mounted | kvm_ok | tcg_emulation | launching_qemu |
|
|
# qemu_exited | session_complete | fallback_no_kvm |
|
|
# iso_not_found | fatal_error
|
|
|
|
# ── Trace Event Tiers ───────────────────────────────────────────────────────
|
|
# Tier 1 (standard): serial + basic disk I/O (always on)
|
|
# Tier 2 (detailed): + PCI config space + port I/O
|
|
# Tier 3 (full): + MMIO memory_region_ops (very slow, debug only)
|
|
|
|
# ── Config File Format (hiperiso.json) ──────────────────────────────────────
|
|
# JSON format:
|
|
# {
|
|
# "control": { ... },
|
|
# "theme": { ... },
|
|
# "menu_alias": [ ... ],
|
|
# "menu_tip": [ ... ],
|
|
# "iso_overrides": {
|
|
# "*./windows11*.iso": { "ram": 4096, "tpm": true, "cpu_features": ["vmx"] }
|
|
# }
|
|
# }
|
|
|
|
# ── hiperiso-log Tool Interface ─────────────────────────────────────────────
|
|
# Usage: hiperiso-log analyze <log_dir>
|
|
# Usage: hiperiso-log trace <trace.bin> [--format json|csv|text]
|
|
# Usage: hiperiso-log serial <serial.log> [--stages]
|
|
# Output: writes report.json, report.txt, and analysis.meta into <log_dir>
|
|
|
|
# ── 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.
|
|
|