Files

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

4.8 KiB

Raw Blame History

hiperiso configuration

hiperiso is configured through a single JSON file placed on the data partition of the USB at /hiperiso/hiperiso.json. Start from hiperiso.json.example.

JSON cannot contain comments, so every option is described here.

Location

<data partition>/
└── hiperiso/
    └── hiperiso.json      ← global config (copied from hiperiso.json.example)

Top-level sections

Section	Purpose
`control`	Default hypervisor/guest settings applied to every boot.
`theme`	GRUB2 menu theme.
`menu_alias`	Rename ISO entries in the menu.
`menu_tip`	Show a one-line tip under a menu entry.
`iso_overrides`	Per-ISO settings keyed by glob pattern.

`control`

Key	Type	Default	Meaning
`default_ram`	number	`2048`	Guest RAM in MB.
`default_cpus`	number	`2`	Guest vCPUs.
`default_trace_level`	string	`standard`	`none` \| `standard` \| `detailed` \| `full`.
`default_display`	string	`none`	QEMU display: `none` \| `gtk` \| `vnc`.
`default_vga`	string	`none`	QEMU VGA: `none` \| `std` \| `virtio`.
`fallback_no_kvm`	boolean	`true`	Fall back to direct boot if `/dev/kvm` is missing.
`net_dump`	boolean	`false`	Capture guest network traffic to `network.pcap`.
`timeout`	number	`10`	GRUB2 menu auto-boot timeout in seconds.

These map directly to the kernel command-line parameters defined in INTERFACES.sh (HIPERISO_GUEST_RAM, HIPERISO_GUEST_CPUS, HIPERISO_TRACE_LEVEL, HIPERISO_DISPLAY, HIPERISO_VGA, HIPERISO_FALLBACK).

`theme`

Key	Type	Meaning
`file`	string	Path to a GRUB2 `theme.txt`.
`gfxmode`	string	GRUB2 graphics resolution.
`gfxpayload`	string	`keep` to preserve resolution for guest.

`menu_alias` / `menu_tip`

Both are arrays of objects with an iso path (relative to the data partition) and a value:

[
  { "iso": "/ISOs/ubuntu-24.04.iso", "alias": "Ubuntu 24.04 LTS" }
]

`iso_overrides`

A map of glob pattern → override object. The first matching pattern wins. Patterns are matched against the filename.

Key	Type	Meaning
`ram`	number	Override guest RAM (MB).
`cpus`	number	Override guest vCPUs.
`tpm`	boolean	Attach a virtual TPM (`swtpm`) for Windows 11.
`secure_boot`	boolean	Use Secure-Boot-enabled OVMF vars.
`cpu_features`	string[]	Extra CPU flags, e.g. `["vmx"]` for nested virt.
`trace_level`	string	Override trace tier for this ISO.
`display`	string	Override display mode.
`net_dump`	boolean	Capture network traffic for this ISO.
`qemu_extra_args`	string[]	Raw extra arguments appended to the QEMU command line.

{
  "*./windows11*.iso": { "ram": 4096, "tpm": true, "cpu_features": ["vmx"] }
}

Standalone override files

config/iso_overrides/<name>.json holds a single override (see windows11.json). These are intended as reusable templates you can merge into iso_overrides or ship alongside a curated ISO set.

Trace tiers (recap)

Tier	Events	Overhead
`standard`	serial + basic disk/CD-ROM I/O	~0%
`detailed`	+ PCI config-space + port I/O	low
`full`	+ every MMIO access	10–100×
`none`	serial only (no trace)	0%

The corresponding event lists live in logging/trace-*.events and are copied to the ESP at /EFI/hiperiso/trace/ during install.

4.8 KiB Raw Blame History Unescape Escape