NAME

       rocm-qemu-run - rocm-qemu-run

DESCRIPTION

       Boot an amd64 QEMU VM to a console, passing through GPUs.

       By  default,  all GPUs assigned to vfio-pci are passed through. This can be overridden with -g, which can
       be specified multiple times. [NOTE: multi-GPU is untested, and therefore disabled for now.]

       The VM will boot an amd64 image in EFI mode. The EFIVARS file will be a clean copy  at  every  boot.  The
       image will be writeable, so use qemu-img(1) to create a snapshot first if you'd like to be able to revert
       your changes.

       All  [qemu options] are passed on to the QEMU command line, in case you want to add more configuration to
       the VM.

       This utility assumes that the invoking user has all  the  necessary  permissions  required  in  order  to
       effectively  and  efficiently  operate the VM, most notably that the user has access to /dev/kvm. When in
       doubt, try running the script as root.

   Synopsis:
              bin/rocm-qemu-run -h

              bin/rocm-qemu-run [-c CPUs] [-d DIR ] [-g GPU] [-m MEM] [-p SSHPORT] image [qemu options]

OPTIONS

       -h     Show this help

       -c CPUS
              Number of guest CPUs (default: 75% of CPU cores)

       -d DIR Mount host dir DIR as /shared in the guest

       -g GPU PCI slot ID of GPU to pass through (eg: 09:00.0)

       -m MEM Guest RAM (default: 75% of memory)

       -p SSHPORT Forward host port PORT to guest port 22

       -s     Boot the VM in snapshot mode (changes are discarded)

EXAMPLES

              # Configure the system for GPU pass-through

              $ rocm-qemu-setup -u <user>

              # Create an image

              $ sudo rocm-qemu-create unstable.img
              $ sudo chown $USER: unstable.img

              # Boot the image above to a console # This will pass through all GPUs assigned to vfio-pci

              $ bin/rocm-qemu-run unstable.img

              # Like above, but use 4 CPUs and 8GB of RAM

              $ bin/rocm-qemu-run -c 4 -m 8192 unstable.img

              # Like above, but only pass through GPU 09:00.0

              $ bin/rocm-qemu-run unstable.img -g 09:00.0

              # Forward host port 10022 to guest port 22. Connect with: # ssh  -p  10022  -o  CheckHostIP=no  -o
              StrictHostKeyChecking=no root@localhost

              $ bin/rocm-qemu-run -p 10022 -d /some/host/dir unstable-amd64.img

              # Snapshot mode (no changes to the image will be saved)

              $ bin/rocm-qemu-run -s unstable.img

              # Share host directory /tmp/foo # The directory will be mounted at /shared within the guest

              $ bin/rocm-qemu-run -d /tmp/foo unstable.img

debian                                             March 2025                                   ROCM-QEMU-RUN(1)