# 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/_/ # # 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: phaseuptimeiso8601) # 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": "_", # == dir basename # "status": "complete" | "failed", # final lifecycle state # "result": "success" | "failure" | "incomplete" | "no_serial", # # derived boot result # "iso_path": "/ISOs/.iso", # "iso_basename": ".iso", # "log_dir": "/hiperiso/logs/", # 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": "_", # string # "status": "started" | "running" | "complete" | "failed", # "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 # 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.