From 9aac84e6999321e243422f0bc3bbf63043a8178e Mon Sep 17 00:00:00 2001 From: vasilito Date: Tue, 30 Jun 2026 14:28:44 +0300 Subject: [PATCH] Add INTERFACES.sh: single source of truth for all interface contracts --- INTERFACES.sh | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 INTERFACES.sh diff --git a/INTERFACES.sh b/INTERFACES.sh new file mode 100644 index 0000000..2588860 --- /dev/null +++ b/INTERFACES.sh @@ -0,0 +1,169 @@ +# 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 (new for full Ventoy parity) ─────────────────────────── +# 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, 32MB) +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/_/ +# +# 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: phaseuptimeiso8601) +# 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": "_", # == dir basename +# "status": "complete" | "failed", # final lifecycle state +# "result": "success" | "failure" | "incomplete" | "no_serial", +# # derived boot result +# "iso_path": "/ISOs/.iso", +# "iso_basename": ".iso", +# "log_dir": "/hiperiso/logs/", # 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": "_", # string +# "status": "started" | "running" | "complete" | "failed", +# "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, compatible with Ventoy's ventoy.json structure: +# { +# "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 +# Usage: hiperiso-log trace [--format json|csv|text] +# Usage: hiperiso-log serial [--stages] +# Output: writes report.json, report.txt, and analysis.meta into