vasilito
18cf522c82
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
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.