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
104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
[
|
||
{ "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.|
|
||
|
||
```json
|
||
{
|
||
"*./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.
|