qemu_boot

Boot a QEMU VM headless and register it under name.

name identifies this VM in all later calls (qemu_screenshot, qemu_stop, etc.) - it must be non-empty and contain no "/" or "" (it also names a temp directory and is passed to QEMU's -name flag). Provide at least one of: iso (bootable CD image), kernel (multiboot/bzImage, optionally with append/initrd), or disk (raw or qcow2 disk image, auto-detected; qcow2 is required for qemu_snapshot_save/qemu_snapshot_load). append/initrd require kernel to also be given - QEMU itself rejects -append/-initrd without -kernel, so this is checked up front with a clear ValueError. Each of iso, kernel, initrd, and disk, if given, must already exist on disk - qemu_boot checks with a clear FileNotFoundError naming the param and path before any QEMU process starts, rather than letting a typo surface later as an opaque "QEMU exited immediately" failure; qemu_boot never creates a disk image for you, so disk must point at an existing image file. memory_mb must be positive. arch picks the qemu-system- binary (x86_64, i386, aarch64, riscv64...) and, like name, must contain no "/" or "" and not be "." or "..". machine is passed as QEMU's -M and is required on some archs - aarch64 and riscv64 have no default machine and need e.g. machine="virt". smp sets the number of virtual CPUs (QEMU -smp), for testing SMP-aware guest code; must be positive when given. smp_cores/smp_threads/smp_sockets/smp_maxcpus add QEMU's -smp CPU-topology qualifiers (cores=/threads=/sockets=/maxcpus=) onto the same -smp flag instead of a flat count - for guest code that cares about socket/core/thread shape (ACPI MADT entries, CPUID topology leaves, per-socket vs. per-core scheduling), not just a total vCPU number. Each must be positive when given; any of them (with or without smp itself) causes -smp to be emitted. accel is passed as QEMU's -accel (e.g. "kvm", "kvm:tcg" to fall back to software emulation if KVM isn't available, "hvf"/"hvf:tcg" on macOS, "whpx:tcg" on Windows) to opt into hardware acceleration; left unset, QEMU defaults to TCG (software emulation), which is correct but slow for anything beyond a trivial kernel. There's no host-capability probe for this - if the requested accelerator isn't available, QEMU itself fails immediately and that failure (including QEMU's own explanation) is surfaced the same way any other immediate boot failure is, in the raised error. cpu is passed as QEMU's -cpu (e.g. "qemu64,+avx", "max", "host" when accel="kvm"/"hvf") to select or customize the emulated CPU model - useful for testing guest code against a specific feature set (SSE4, AVX, a particular vendor's quirks) rather than whatever QEMU defaults to for the arch. extra_args is passed to QEMU verbatim, e.g. "-netdev user,id=n0 -device rtl8139,netdev=n0" (must be valid shell-style quoting, e.g. no unbalanced quotes). extra_args may not contain a flag qemu_boot already sets itself: -name, -m, -display, -qmp always; -M/-machine, -cdrom/-boot, -kernel, -append, -initrd, -smp, -accel, -cpu when the corresponding param above is also given (-smp collides when smp or any of the smp_* topology params is given). -drive is exempt from this check even when disk is given - QEMU allows repeated -drive flags, so extra_args can add further disks, e.g. extra_args="-drive file=data.img,format=raw" for a second drive alongside disk (pointing extra_args's -drive at the same file as disk will still fail, but as a QEMU image-locking error at boot, not a pre-flight one). -chardev/-serial are similarly exempt except for the exact chardev qemu_boot's own serial console uses (id=serial0 / chardev:serial0) - extra_args can add an unrelated -chardev or a second -serial (e.g. a COM2 backed by another chardev) freely, but reusing id=serial0 or pointing another -serial at chardev:serial0 is rejected, since that's the pair qemu_serial/qemu_serial_send depend on. hostfwd is a convenience for reaching a guest service (SSH, a web server under test) from the host, without needing QEMU-specific NIC/chipset knowledge: give it QEMU's hostfwd rule, e.g. hostfwd="tcp::2222-:22" to forward host port 2222 to guest port 22, and qemu_boot adds the "-netdev user,id=net0,hostfwd=..." / "-device e1000,netdev=net0" pair for you (the guest needs its own driver for an e1000 NIC - most general-purpose OSes, Linux included, have one built in). Must look like [tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport. -netdev/-device are similarly exempt from the extra_args conflict check except for the exact netdev hostfwd's own NIC uses (id=net0 / netdev=net0) - extra_args can add an unrelated NIC (e.g. for testing a guest driver) freely, but reusing id=net0 or pointing a -device at netdev=net0 is rejected. hostfwd's host port is probed pre-flight (a bind attempt on that exact port/address) so a collision - two VMs sharing a hostfwd port, or an unrelated process already bound to it - raises a clear ValueError naming the port instead of surfacing as QEMU's own confusing bind-failure output through the generic "QEMU exited immediately" path. qmp_connect_timeout_s bounds how long to retry connecting to QEMU's QMP socket after launch (raise it on a slow/loaded host where QEMU's first launch is slow, e.g. under AV scanning). qmp_read_timeout_s bounds how long any single QMP command (including ones issued by other qemu_* tools for this VM, like qemu_qmp or qemu_snapshot_save) waits for a response - raise it if you expect a command that can legitimately run long. Both timeouts must be positive. The VM keeps running until qemu_stop; serial output is captured continuously.