Menu
Use when you need to start the QEMU+gem5 cosim environment. Launches gem5 in Docker, QEMU with KVM on host, via vfio-user or legacy cosim socket.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use as the main entry for cosim debugging: gem5 crashes, assertions, hangs, timeouts, address translation faults, non-PASS test results, guest-side waits, and QEMU exits that may be secondary to gem5. Collect logs, preserve live state when needed, route to gem5 model references, and decide the first failing component.
Use when building gem5 or QEMU, checking build provenance, or preserving gem5 incremental builds across worktrees. Delegates to scripts/cosim_build.sh; never hand-roll Docker, scons, or QEMU make commands.
Use when delegating independent code review, design review, or focused bug investigation to an AI reviewer. Provides delegation templates and records reviewer evidence; higher-level review flow remains in cosim-gpu-review or cosim-gpu-rlcr-loop.
Use when the guest disk image needs modification without a full rebuild. Mount with guestmount, add files, systemd services, kernel module config.
Use as the first step for non-trivial cosim testing, debugging, review, or iterative implementation tasks. Do not use for ordinary repository maintenance such as commit splitting, submodule pointer updates, author config, or documentation-only cleanup.
Use when you need to send commands to a running cosim guest. Console pipe interaction, 9p share mount, GPU status check, manual driver load.
| name | cosim-gpu-launch |
| description | Use when you need to start the QEMU+gem5 cosim environment. Launches gem5 in Docker, QEMU with KVM on host, via vfio-user or legacy cosim socket. |
Launch the QEMU+gem5 co-simulation environment.
This is a direct launcher, not the test harness. Use it for manual boot,
interactive inspection, backend checks, and standalone QEMU+gem5 sessions. It
does not accept --output-dir, does not create test matrices, does not write
guest program logs, and does not run binary-provenance hooks. Use cosim-gpu-test
when a run must produce case-managed evidence.
bash scripts/cosim_cleanup.sh # always preflight first
./scripts/cosim_launch.sh # vfio-user (default)
./scripts/cosim_launch.sh --gem5-debug MI300XCosim # with debug trace
./scripts/cosim_launch.sh --cosim-backend legacy # legacy cosim socket
After guest boots, the driver loads automatically via cosim-gpu-setup.service.
If not, manually load with cosim-gpu-guest.
Run bash scripts/cosim_cleanup.sh before launch without asking the user. This
is the normal preflight for cosim and removes only known leftover cosim state.
Do not ask before the standard launcher either. Ask only before broad manual
cleanup outside repository scripts, deleting unrelated files, or a full/cold
rebuild.
| Backend | Protocol | Default? | Notes |
|---|---|---|---|
| vfio-user | libvfio-user over Unix socket | Yes | Standard, no custom QEMU code |
| legacy | Custom cosim socket protocol | No | QEMU mi300x-gem5 device |
QEMU (Q35+KVM, host) ←Unix socket→ gem5 (MI300X GPU, Docker)
Shared memory uses run-id names: /dev/shm/cosim-guest-ram-<run-id> for guest RAM and /dev/shm/mi300x-vram-<run-id> for VRAM.
BAR layout: 0+1=VRAM, 2+3=Doorbell, 4=MSI-X, 5=MMIO.
ip_block_mask=0x67 # enable common/GMC/IH/GFX/SDMA; disable PSP bit 3 and SMU bit 4
ppfeaturemask=0 # disable power play
dpm=0 # disable dynamic power management
audio=0 # no audio controller
ras_enable=0 # disable RAS
discovery=2 # firmware-based discovery
| Symptom | Route |
|---|---|
| gem5 container exited during launch | Use cosim-gpu-debug to inspect active gem5 container logs |
| Driver failed while parsing AtomBIOS | Use cosim-gpu-guest or launch setup workflow to inspect ROM visibility before amdgpu loads |
| KIQ disable timeout (-110) | Treat as expected cosim noise unless followed by a functional failure |
| DRM client -13 / EPERM | Use guest setup or disk-image workflow to inspect permissions and image state |
cosim-gpu-build directly when binaries are stale or missingbash scripts/cosim_cleanup.sh directly to clear leftover statecosim-gpu-guest to interact, cosim-gpu-debug to inspectcosim-gpu-test for automated execution (handles launch internally)