Add documentation: README, architecture plan, config reference

2026-06-30 14:28:44 +03:00
parent cb10aed0f9
commit 1c469ac1ed
3 changed files with 1930 additions and 0 deletions
@@ -0,0 +1,104 @@
+# hiperiso configuration
+
+hiperiso is configured through a single JSON file placed on the **data
+partition** of the USB at `/hiperiso/hiperiso.json`. The format is
+[Ventoy](https://www.ventoy.net)-compatible so existing Ventoy configs need
+only minor changes. 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.
+Glob syntax matches Ventoy (anchored at 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.