Add INTERFACES.sh: single source of truth for all interface contracts
This commit is contained in:
+169
@@ -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/<sanitized-iso-basename>_<UTC-timestamp>/
|
||||
#
|
||||
# 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: phase<TAB>uptime<TAB>iso8601)
|
||||
# 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": "<basename>_<UTC-timestamp>", # == dir basename
|
||||
# "status": "complete" | "failed", # final lifecycle state
|
||||
# "result": "success" | "failure" | "incomplete" | "no_serial",
|
||||
# # derived boot result
|
||||
# "iso_path": "/ISOs/<name>.iso",
|
||||
# "iso_basename": "<name>.iso",
|
||||
# "log_dir": "/hiperiso/logs/<dir>", # 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": "<basename>_<UTC-timestamp>", # string
|
||||
# "status": "started" | "running" | "complete" | "failed",
|
||||
# "stage": "<current_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 <log_dir>
|
||||
# Usage: hiperiso-log trace <trace.bin> [--format json|csv|text]
|
||||
# Usage: hiperiso-log serial <serial.log> [--stages]
|
||||
# Output: writes report.json, report.txt, and analysis.meta into <log_dir>
|
||||
Reference in New Issue
Block a user