vasilito/hiperiso
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c6285a333d2365cb4e5cd67ff2f1cca41dcc172b
hiperiso/INTERFACES.sh
T
vasilito 18cf522c82 fix: build working hiperiso using Ventoy as GRUB substrate 
This commit consolidates the working state of hiperiso's build
pipeline. The previous rebranding attempt (trying to rename all
ventoy_* symbols in the modsrc to hiperiso_*) was incomplete and
the build was broken — 18 undefined symbols, mismatched field names
(hlnk vs vlnk), 2 missing functions.

Strategy: use Ventoy's stock modsrc as the GRUB substrate. The
rebranding is now limited to runtime artifacts:

- Kernel cmdline contract: `hiperiso_iso=...` etc. (hiperiso-spec)
- JSON config: `hiperiso.json` (hiperiso-spec)
- The `ventoy/ventoy.cpio` file from upstream Ventoy is vendored.
- ESP layout matches Ventoy's expectations (FAT label "VTOYEFI",
  64MB ESP, "ventoy/ventoy.cpio" at the partition root).

The modsrc is used as-is with two single-line sed patches to allow
hiperiso's 64MB ESP layout (Ventoy upstream hardcodes 32MB).

The QEMU hypervisor feature is preserved via a new GRUB script
function `hiperiso_boot` in grub.cfg that replaces the missing C-side
`hiperiso_cmd_boot` from the broken rebrand. The function reads
HISO_* env vars, builds the `hiperiso_iso=...` cmdline, and
executes `linux` + `initrd` + `boot` against the host kernel +
QEMU initramfs on the ESP.

Files changed:

  scripts/build_grub2_204.sh
    - Reverted the broken rebrand sed pipeline
    - Now: unpack modsrc, single sed pass to bump ESP size from
      32MB to 64MB (Ventoy upstream's modsrc hardcodes 32MB; this
      is the only Ventoy source-level change we make).
    - Drops support for the partial hiperiso C module.

  src/installer/tool/hiperiso_lib.sh
    - GPT part 2 type: 'esp on' → 'msftdata on' (matches Ventoy)
    - FAT16 volume label: 'HISOEFI' → 'VTOYEFI' (modsrc checks
      this string literally in ventoy_check_official_device)

  scripts/package_release.sh
    - FAT16 label: 'HISOEFI' → 'VTOYEFI'
    - Copy reference/Ventoy/INSTALL/ventoy/ventoy.cpio to the
      payload's ventoy/ directory at ESP-staging time (modsrc
      looks for it at the partition root).

  src/grub2/grub/grub.cfg
    - New `function hiperiso_boot` (~90 lines) that replaces the
      missing C-side `hiperiso_cmd_boot`. Reads HISO_* env vars,
      builds the `hiperiso_iso=...` kernel cmdline, and runs
      `linux` + `initrd` + `boot` against the host kernel +
      QEMU initramfs. The 9 call sites in grub.cfg that previously
      failed with "command not found" now work.

  grub2/bin/BOOTX64.EFI (binary)
    - Rebuilt by the new build_grub2_204.sh. The modsrc GRUB module
      is Ventoy's stock. 1.9MB, 4 sections, 257 ventoy_* symbols.

The 'src/grub2/hiperiso_*.c' files are kept in the source tree as
historical reference but are no longer compiled or shipped.

Verified by QEMU test:
  - Firmware boot manager recognizes USB as bootable device
  - modsrc's ventoy_check_official_device() passes (no "NOT a
    standard Ventoy device" error)
  - FAT label, ESP size, and CPIO presence all satisfy the
    hardcoded checks
  - Real hardware validation pending (requires physical USB)

To install:
  sudo bash build/payload/Hiperiso2Disk.sh -I -g /dev/sdX
2026-07-02 00:58:22 +03:00

170 lines
10 KiB
Bash
Raw Blame History

# 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>
Reference in New Issue View Git Blame Copy Permalink