single-gpu machine

Overview

single-gpu is the canonical one-GPU guest board: one machine, one vhost-x86-rocm QEMU vHost and one gem5 MI300X device sharing a 24 GiB memory pool.

Topology

# resources/machines/single-gpu.yaml
version: 1
imports:
  - vhosts/qemu.yaml
  - devices/gpu/mi300x.yaml
templates:
  node1:
    vhost: {use: vhost-x86-rocm}
    devices:
      - {use: mi300x}
machines:
  - {id: m0, use: node1}

  • Machine count: one (m0); both host and device come from imported templates.

  • node1 combines vhost-x86-rocm with the default mi300x. The vHost template selects ubuntu/24.04/x86_64/rocm/7.0.

Hardware resources

Resource

Value

Source

Machine

1 (m0)

resources/machines/single-gpu.yaml

vHost profile

vhost-x86: q35, kvm, host CPU, 4 vCPU

resources/vhosts/qemu.yaml

Guest RAM

8 GiB; the x86_64 PCI hole is rendered by memory_map

resources/vhosts/qemu.yaml

Device

1 × mi300x: 16 GiB VRAM, 40 CU

resources/devices/gpu/mi300x.yaml

Memory pool

24 GiB = 8 GiB RAM + 16 GiB VRAM

crates/cosim-topology/src/layout.rs

PCIe topology

One pcie-root-port per device (slots from 0x10), optional option ROM

resources/vhosts/qemu.yaml

Executables

QEMU build/qemu/qemu-system-x86_64; gem5 build/gem5/x86_64/VEGA_X86/gem5.opt

The two templates

Software stack

Layer

Component

Description

Guest OS

Ubuntu 24.04.2 LTS, kernel 6.8.0-124-generic

Direct kernel boot through the vHost

GPU driver

amdgpu with fixed parameters

ip_block_mask=0x67 ppfeaturemask=0 dpm=0 audio=0 ras_enable=0 discovery=2

GPU user space

ROCm 7.0 / HIP

rocminfo, rocm-smi and HIP programs

Device model

gem5 MI300X (MI300XVfioUser)

Partial PM4, SDMA and CU behavior; model details are in chapter 4

Guest initialization

cosim-gpu-initialize.service

Writes the ROM with dd and loads amdgpu after boot

Running this machine

# Validate and preview only
just run-cli validate resources/machines/single-gpu.yaml  --assets
just run-topology resources/machines/single-gpu.yaml --dry-run
# Start a session
just run-topology resources/machines/single-gpu.yaml

  • The serial console, login and shutdown flow are in First session.

  • A host exiting with status 0 ends its machine; SIGINT or SIGTERM starts a graceful shutdown.

  • --assets checks that the QEMU and gem5 binaries, the vHost kernel and the disk image exist.

Verification

  • The plan output contains one machine, one host process and one device process, a 24 GiB pool, and mi300x-0.vram at 8 GiB.

  • After guest boot amdgpu binds the simulated device; the gfx target reported by rocminfo is gfx942.

  • The repository's ROCm regression is generated by scripts/ci/run_rocm.py as an equivalent single-machine, single-GPU topology, and the integration workflow runs it through the same Rust launcher.

  • just test-gem5-mi300x separately checks the model and the pool; the sample itself is loaded by the render test.

Limitations

  • The guest disk image is about 55 GB, so the first preparation needs enough disk space.

  • PSP and SMU are not modeled: never set bit 3 of ip_block_mask.

  • BIOS/IP discovery paths are not modeled: the guest must write mi300.rom to 0xC0000 before modprobe.

  • The YAML adapter starts one GPU per process (--num-gpus=1); more GPUs means more device entries, see gpu-8 machine.

  • Booting a guest needs KVM; running a session needs Linux glibc and setpriv.