pmem/run_qemu/run-qemu

run_qemu

Overview

run_qemu builds a Linux kernel from a source tree, creates a Fedora rootfs using mkosi, installs the kernel into it, and boots QEMU with a generated command line. It supports complex NUMA/CXL/NVDIMM topologies and provides SSH access to the guest.

Run from the root of a Linux kernel tree. The run_qemu.sh script should be in the user's PATH.

Prerequisites: mkosi, qemu-system-x86_64, rsync, dracut, KVM-enabled host, nopasswd sudo preferred.

MCP Tools (Primary Agent Interface)

When the run-qemu MCP server is available, use these tools for all VM operations. They provide structured, async-safe interaction with run_qemu.

Typical Agent Workflow

1. vm_start(linux_dir=".", rebuild="kmod", preset="small", cxl=true)
   → Returns immediately. VM is building in background.
 
2. vm_status(instance=0)
   → Poll every 30-60s until state is "ready".
   States: starting → ready (or exited on failure)
 
3. vm_run(instance=0, command="uname -r")
   → Execute commands inside the VM via SSH.
 
4. vm_dmesg(instance=0, grep="cxl")
   → Check kernel log for specific messages.
 
5. vm_log(instance=0, tail_lines=100)
   → Read console log for boot messages or errors.
 
6. vm_stop(instance=0)
   → Graceful shutdown when done.

Tool Reference

vm_start — Build kernel and launch VM

Builds the kernel, creates/updates the rootfs, and launches QEMU in the background. Returns immediately with instance info. Runs make olddefconfig by default to avoid interactive config prompts.

Typed parameters (common options):

`extra_args` (str): Any additional run_qemu.sh options not covered above, passed verbatim. Examples:

• "--cxl-debug" — enable CXL dyndbg
• "--hmat" — enable HMAT table
• "--kcmd-append myfile.txt" — append kernel command line from file
• "--no-kvm" — disable KVM (for environments without hardware virtualization)

vm_status — Check VM state

Returns the current state: starting, ready, exited, or unknown. When ready, the SSH connection string is included.

vm_run — Execute command in VM

Runs a shell command via SSH. Returns stdout, stderr, and exit code. The VM must be in ready state.

vm_dmesg — Read kernel log

Reads dmesg from the VM. Supports filtering by level (err, warn) and grep pattern.

vm_log — Read console log

Reads the QEMU console log file. Supports tail (last N lines) and grep filtering.

vm_stop — Stop VM

Gracefully shuts down the VM. Tries QMP quit → SSH poweroff → SIGTERM → SIGKILL.

vm_list — List running VMs

Shows all running run_qemu instances with their state and SSH ports.

Common MCP Workflows

CXL Topology Testing

vm_start(cxl=true, preset="small", extra_args="--cxl-debug")
# Poll vm_status until ready...
vm_run(command="lspci | grep '3[45]:00'")
vm_run(command="readlink -f /sys/bus/cxl/devices/mem0")
vm_dmesg(grep="cxl")

The default CXL topology creates:

• 1 CXL host bridge (bus #52, window at 0x4c00000000)
• 1 root port
• 1 Type 3 device (256M persistent)

CXL Unit Testing (cxl_test)

Uses the kernel's cxl_test module to mock a CXL hierarchy without real hardware:

vm_start(cxl_test=true, extra_args="--cxl-debug")
# cxl_test implies cxl, and includes extra CXL mock modules
vm_run(command="modprobe cxl_test")
vm_dmesg(grep="cxl_test")

NFIT Unit Testing (nfit_test)

Tests libnvdimm with mock NFIT/NVDIMM devices. Forces preset to med:

vm_start(nfit_test=true)
# Includes libnvdimm 'extra' modules and memmap reserved memory
vm_run(command="modprobe nfit_test")
vm_dmesg(grep="nfit")

Multiple VMs

vm_start(instance=0, preset="small")        # SSH port 10022
vm_start(instance=1, preset="med", cxl=true) # SSH port 10023
vm_run(instance=0, command="uname -r")
vm_run(instance=1, command="lspci | grep CXL")

Core Concepts

Build Directory

run_qemu creates a builddir (default: ../builddir-<branch>) containing:

• The rootfs image (root.img)
• mkosi cache (mkosi.cache/)
• Built kernel artifacts

Rebuild Modes

Topology Presets

Kernel .config Management

run_qemu does not manage .config — it's the user's responsibility. The MCP's vm_start runs make olddefconfig by default to avoid interactive prompts. Common patterns:

make defconfig
# Or merge CXL configs:
./scripts/kconfig/merge_config.sh .config ../run_qemu/.github/workflows/*.cfg

SSH Access

• SSH port = 10022 + instance number
• Root password: root (serial console auto-logs in)
• Recommended .ssh/config:

`` Host rq Hostname localhost User root Port 10022 StrictHostKeyChecking no UserKnownHostsFile /dev/null ``

• File sharing: dpipe /usr/lib/ssh/sftp-server = ssh rq sshfs :$HOME/CXL /root/CXL -o passive

Manual CLI Workflows (when MCP not available)

If the MCP tools are not available, drive run_qemu.sh directly from a bash shell.

Interactive Kernel Test

cd /path/to/linux
run_qemu.sh --defconfig --preset=small
# Drops you into a serial console. Ctrl-a x to exit.
# SSH in from another terminal: ssh -p 10022 root@localhost

CXL Topology Testing

run_qemu.sh --defconfig --cxl --cxl-debug --preset=small

CXL Unit Testing

run_qemu.sh --defconfig --cxl-test --cxl-debug

NFIT Unit Testing

run_qemu.sh --defconfig --nfit-test
# Note: --nfit-test forces preset=med

Automated Test Run

run_qemu.sh --defconfig --autorun=my_test.sh --timeout=10 --log=/tmp/rq_test.log
# Runs my_test.sh as a systemd service on boot
# Kills VM after 10 minutes
# Console output captured in /tmp/rq_test.log

Iterative Development Cycle

# First run (creates rootfs):
run_qemu.sh --defconfig --rebuild=img --cxl
 
# Subsequent runs (kernel-only rebuild, fast):
run_qemu.sh --defconfig --cxl
# (default --rebuild=kmod rebuilds the kernel and updates modules)

Option Reference

Build & Image

Topology

CXL

NFIT / NVDIMM

Runtime

Kernel Command Line

Display & Debug

Other

Troubleshooting

Build Failures

• Check that .config exists and has the needed options enabled
• Use --rebuild=wipe to start fresh if the rootfs is corrupted
• mkosi cache issues: remove builddir/mkosi.cache/ or use --rebuild=wipe

VM Won't Boot

• Check the log file (vm_log or --log) for kernel panics
• Try --no-kvm if hardware virtualization isn't available
• Verify QEMU is installed: qemu-system-x86_64 --version

SSH Not Connecting

• Verify the correct port: 10022 + instance number
• Check host firewall: port 10022 may be blocked
• Wait for boot to complete — the VM needs time to start sshd
• Check vm_log for boot progress

CXL Devices Not Visible

• Ensure .config has CXL options enabled (CONFIG_CXL_BUS=y, CONFIG_CXL_PCI=m, etc.)
• Use --cxl-debug for dyndbg output
• Check vm_dmesg(grep="cxl") for driver messages

nfit_test / cxl_test Issues

• These require --rebuild=img or higher when switching to/from test mode
• Check that the test modules are built: vm_run(command="modinfo cxl_test")