Logo
  • Getting Started
    • What this chapter covers
      • Requirements
        • Host environments
        • Tools and versions
        • Disk and memory
        • Checklist
        • Related pages
      • Install and build
        • Sources and submodules
        • Choose the build environment
        • Build everything
        • Build in steps
        • Guest assets
        • Verify the build
        • Related pages
      • Guest image
        • Image contents
        • Reuse a prebuilt image
        • Rebuild the image
        • Bundle contents
        • Verify and reuse
        • Related pages
      • First session
        • Prerequisites
        • Launch the session
        • What the session does
        • Connect to the guest console
        • Session artifacts
        • Shut down the session
        • Related pages
      • Verify the guest
        • Automatic setup
        • Check the GPU and ROCm
        • First HIP program
        • Manual driver recovery
        • Related pages
      • Linux host
        • When to use it
        • System dependencies
        • KVM and permissions
        • WSL2 and nested virtualization
        • Verify the environment
        • Related pages
      • Development container
        • When to use it
        • Build and select the environment
        • How dev.sh behaves
        • Working inside the container
        • Limitations
        • Related pages
      • Next steps
        • Understand how the system works
        • Use and extend the launcher
        • Go deeper into simulators and the driver
        • Write your own topology
        • Look up facts and troubleshoot
        • Related pages
    • Recommended path
    • Expectations
    • Related pages
  • Architecture overview
    • What this chapter covers
      • Components and responsibilities
        • Overview
        • Component responsibilities
        • QEMU: functional simulation
        • gem5: performance simulation
        • vfio-user: the bridge between them
        • Supporting infrastructure
        • Source entry points
        • Related pages
      • Execution flow
        • From topology to plan
        • Starting the session
        • Readiness probes and leases
        • Shutdown and session end
        • Artifacts and verdict
        • Related pages
      • Memory and shared memory model
        • Memory pools and regions
        • Guest physical addresses and file offsets
        • How QEMU and gem5 share it
        • Capacity reservation and session isolation
        • Data and consistency
        • Related pages
      • vfio-user interface
        • Roles
        • Connection and lifecycle
        • Protocol operations
        • From doorbell to interrupt
        • DMA mapping
        • Why vfio-user
        • Related pages
      • Design decisions
        • Functional and performance simulation
        • Why connect with vfio-user
        • Why a shared memory pool
        • Why a Rust launcher
        • Why the machine owns its vHost
        • Costs and limitations
        • Related pages
    • Design goals
    • Recommended path
    • Relation to the other chapters
    • Related pages
  • Cosim Launcher
    • What the Launcher Does
    • Chapter Contents
      • CLI
        • Global Options
        • Subcommands
        • Run Options
        • Typical Workflows
        • Events, Exit Codes and the Verdict
        • Sources
        • Related Pages
      • YAML pipeline
        • Pipeline Overview
        • Topology document
        • Imports and Template Expansion
        • Validation and Identifiers
        • Memory Layout
        • Producing the Plan
        • Sources
        • Related Pages
      • Session lifecycle
        • Startup Order
        • Run Directory and Resource Publication
        • Process Supervision and Readiness
        • Shutdown and Signals
        • Sessions in the Development Container
        • Disks, Overlays and Locks
        • Cleanup and Session Records
        • Sources
        • Related Pages
      • Rust workspace
        • Workspace Layout
        • Module Responsibilities
        • Public Interfaces
        • Extension Points: Adapters and Command Templates
        • Adding a Model
        • Dependencies and Safety Rules
        • Sources
        • Related Pages
      • Debugging sessions
        • Session Events and Logs
        • Reading the Verdict
        • Common Startup Failures
        • Cleanup and Leftover Resources
        • Sources
        • Related Pages
      • Legacy shell launcher
        • Position
        • Differences from the Rust Launcher
        • Run Flow
        • Common Commands
        • Maintenance Boundaries
        • Sources
        • Related Pages
    • Recommended Reading Path
    • Related Chapters
  • QEMU and gem5
    • Functional and Performance Simulation
    • Choosing a Device Implementation
    • Chapter Contents
      • QEMU roles
        • Role One: vhost
        • Role Two: device model
        • Chapter Contents
        • Recommended Reading Path
      • gem5 performance simulation
        • Run Shape
        • Chapter Contents
        • Recommended Reading Path
      • Guest driver requirements
        • Image and Driver Prerequisites
        • Kernel Command Line
        • Driver Parameters
        • ROM Write Order
        • Automatic Loading and Manual Recovery
        • Verification
        • Common Failures
        • Sources
        • Related Pages
      • Model debugging
        • Enabling gem5 Debug Output
        • Log Locations
        • Common Model Problems
        • Debugging Workflow
        • Common Commands
        • Sources
        • Related Pages
    • Recommended Reading Path
  • Topology and hardware support
    • Three layers
    • In this chapter
      • Single-machine topologies
        • Composition of a machine
        • Process fan-out
        • Pool arithmetic
        • Run directory and resources
        • A minimal single-machine example
        • Sources and evidence
        • Related pages
      • Multi-machine topologies
        • Multi-machine semantics
        • count expansion
        • Cluster samples
        • Per-machine resource routing
        • Running multiple machines
        • Limitations
        • Related pages
      • Writing topologies
        • Document skeleton
        • Imports and templates
        • Machines, devices and count
        • vHost and device fields
        • vHost images and disks
        • Validating, previewing and running
        • Sources and evidence
        • Related pages
      • Machine catalog
        • Catalog table
        • Machine pages
        • How to read a row
        • Recommended reading path
        • Sources and evidence
        • Related pages
      • vHost profiles
        • Role in a topology
        • vHost fields
        • Shipped profiles
        • QEMU command contract
        • Memory map
        • Serial and readiness deadline
        • Related pages
      • Device catalog
        • Device kinds
        • Device fields
        • Launch and readiness contract
        • Devices and the memory pool
        • Choosing a device
        • Related pages
    • Recommended reading path
    • Related pages
  • Reference
    • Topology YAML schema
      • Core structure
      • Document fields
      • Machine fields
      • vHost fields
      • Disk fields
      • Device fields
      • Paths and limits
    • Device adapters
      • Adapter inventory
      • gem5-mi300x
      • qemu-device
      • Template devices and custom commands
      • vHost adapter contract
      • Readiness probes and timeouts
      • Sources and maintenance
      • Related pages
    • vHost image recipes
      • Recipe identity
      • Files in a recipe
      • recipe.toml fields
        • Base image: base
        • Build and installation: provision
        • Installation variables and files
        • Exported files: result
        • TOML structure example
      • provision.yml structure and fields
        • Play-level fields
        • Common task fields
        • Variables supplied by the project
        • File paths and transfer direction
      • Using an image
      • Commands
      • Related pages
    • Guest parameters
      • amdgpu modprobe parameters
      • VGA ROM write
      • Kernel command line
      • IP block mask
      • Initialization order
      • Verification and sources
      • Related pages
    • Version matrix
      • Component versions
      • Images and containers
      • Guest image recipe
      • Provenance and verification
      • Sources and maintenance
      • Related pages
    • Files and artifacts
      • Source directories
      • Build artifacts
      • Session directories and runtime artifacts
      • Guest image files
      • gem5 MI300X model sources
      • gem5 configuration, Python components and QEMU interface
      • Path-related environment variables
      • Sources and maintenance
      • Related pages
    • GART format
      • PTE format
      • Aperture registers
      • Typical values under co-simulation
      • GART table layout in VRAM
      • Co-simulation fallback lookup
      • Sources and maintenance
      • Related pages
    • Known issues
      • Quick triage
      • Issue catalog
        • 4.1 VGA ROM NULL dereference
        • 4.2 PSP / SMU firmware load failure
        • 4.3 GART table not populated under co-simulation
        • 4.4 Crash on unmapped GART pages
        • 4.5 SDMA ring test timeout
        • 4.6 VRAM address GART translation errors
        • 4.7 Shared memory file offset mismatch
        • 4.8 Timer overflow crash
        • 4.9 PM4ReleaseMem.dataSelect panic
        • 4.10 Unhandled PM4 opcodes
        • 4.11 PCI class code mismatch
        • 4.12 QEMU serial console conflict
        • 4.13 Out of memory while linking gem5
        • 4.14 DRM client error -13 (missing DKMS module)
        • 4.15 rmmod oops after a driver hw_init failure
      • Sources and maintenance
      • Related pages
    • Legacy launcher flags
      • Scope
      • Shell launcher options
      • Derived paths and names
      • gem5 config options
      • Differences from the YAML launcher
      • Sources and maintenance
      • Related pages
    • Recommended reading paths
    • Canonical ownership
    • Related chapters
  • Contributing
    • In this chapter
      • Workflow
        • Environment and prerequisites
        • Submodules and repository boundaries
        • Branches and commits
        • Checks before submitting
        • File ownership
        • Related pages
      • Add a vHost image recipe
        • 1. Choose the identifier
        • 2. Declare the build
        • 3. Install the image contents
        • 4. Connect a vHost sample
        • 5. Validate
        • Related pages
      • Patch check
        • Scope and requirements
        • Running the check locally
        • Differences from QEMU's checkpatch.pl
        • False positives
        • Related pages
      • Maintainers
        • Areas and file ownership
        • Looking up maintainers
        • Checks
        • Automatic assignment
        • Adding a maintainer
        • Related pages
      • CI
        • Workflow overview
        • Fast checks
        • Build caches and artifacts
        • ROCm regression
        • Reproducing locally
        • Related pages
      • Rust guidelines
        • Module boundaries
        • Types and configuration boundaries
        • External host parameters
        • Errors and resource ownership
        • Rust source conventions
        • Verification and documentation
        • Related pages
      • Documentation rules
        • Source format and toolchain
        • Chinese primary and English mirror
        • Chapter index template
        • Headings and page structure
        • RST conventions
        • Cross references and labels
        • Support status (deferred)
        • Build and checks
        • Related pages
    • Recommended path
    • Before you submit
    • Related pages
  • Glossary
    • Topology and runtime
    • Interfaces and hardware
    • Simulation and build
    • Related pages
  • SST experiments and remote placement
    • SST data models
    • Remote placement rules
    • Current state and limitations
    • Related pages
cosim-gpu
  • Search

© Copyright 2025-2026, cosim-gpu contributors. Last updated on 2026-10-25.