[WIP] Document and tweaks vmrt (qemu) CLI args

The goal of this PR is to let qemu load root filsystem of the guest as
a virtiofs drive (and then successfully boot from it).

The provided initramfs file should be tweaked to achieve that!

Author: yvan-sraka

runtime/examples/direct.rs

@@ -97,6 +97,7 @@ fn spawn_vm<'a, P: AsRef<Path>>(temp_path: P, mount_args: &'a [(&'a str, impl To
     let project_dir = get_project_dir();
     let init_dir = project_dir.join("init-container");
 
+    // QUESTION: I guess this is an outdated example and should be renamed to `vmrt` right?
     let mut cmd = Command::new("qemu-system-x86_64");
     cmd.current_dir(&init_dir).args([
         "-m",

runtime/examples/network.rs

@@ -130,6 +130,7 @@ fn spawn_vm<P: AsRef<Path>>(temp_path: P) -> Child {
     let chardev =
         |name, path: &PathBuf| format!("socket,path={},server,nowait,id={}", path.display(), name);
 
+    // QUESTION: why not rather use `vmrt::start_vmrt` here?`
     let mut cmd = Command::new("vmrt");
     cmd.current_dir(runtime_dir).args([
         "-m",

runtime/poc/gvmkit.sh

@@ -98,6 +98,7 @@ do_run() {
 		append="$append apparg=\"$a\""
 	done
 	echo $@
+	# QUESTION: is the plan to rewrite this PoC in Rust?
 	./vmrt -m "$memory" -nographic -vga none -kernel vmlinuz-virt -initrd initramfs-virt -net none -accel kvm -cpu "host" -smp $(nproc) \
 		-device virtio-serial,id=ser0 -device virtserialport,chardev=foo,name=org.fedoraproject.port.0 -chardev socket,path=/tmp/foo,server,nowait,id=foo \
 		-append "console=ttyS0 panic=1 $append" \

runtime/src/vmrt.rs

@@ -54,6 +54,10 @@ impl RuntimeData {
     }
 }
 
+/// Starts the VM runtime (vmrt), which is a specialized build of QEMU.
+///
+/// It sets up communication with the VM through a guest agent and emits runtime events
+/// using the provided `EventEmitter`.
 pub async fn start_vmrt(
     work_dir: PathBuf,
     runtime_data: Arc<Mutex<RuntimeData>>,
@@ -81,28 +85,20 @@ pub async fn start_vmrt(
         "socket,path={},server=on,wait=off,id=manager_cdev",
         manager_sock.display()
     );
+    // TODO: I got that what I've to do is just tweak those args :)
     let mut args = vec![
-        "-nographic",
-        "-no-reboot",
-        "-m",
-        memory_size.as_str(),
-        "-kernel",
-        FILE_VMLINUZ,
-        "-initrd",
-        FILE_INITRAMFS,
-        "-enable-kvm",
-        "-cpu",
-        "host,-sgx",
-        "-smp",
-        cpu_cores.as_str(),
-        "-device",
-        "virtio-serial",
-        "-device",
-        "virtio-rng-pci",
-        "-chardev",
-        manager_sock_path.as_str(),
-        "-device",
-        "virtserialport,chardev=manager_cdev,name=manager_port",
+        "-nographic", // Disable graphical output; run in headless mode.
+        "-no-reboot", // Prevent the VM from rebooting automatically on failure.
+        "-m", memory_size.as_str(), // Set the memory size for the VM (e.g., "512M").
+        "-kernel", FILE_VMLINUZ, // Specify the kernel image to boot.
+        "-initrd", FILE_INITRAMFS, // Specify the initial RAM disk image.
+        "-enable-kvm", // Enable KVM (Kernel-based Virtual Machine) for hardware acceleration.
+        "-cpu", "host,-sgx", // Use the host CPU model but disable Intel SGX (Software Guard Extensions).
+        "-smp", cpu_cores.as_str(), // Set the number of CPU cores for the VM.
+        "-device", "virtio-serial", // Add a virtio-serial device for communication between host and guest.
+        "-device", "virtio-rng-pci", // Add a virtio RNG (random number generator) device for entropy.
+        "-chardev", manager_sock_path.as_str(), // Define a character device for communication via a Unix socket.
+        "-device", "virtserialport,chardev=manager_cdev,name=manager_port", // Attach a virtio-serial port to the character device.
     ];
 
     let rootfs_devices: Vec<(String, String)> = deployment
@@ -114,17 +110,15 @@ pub async fn start_vmrt(
                 "file={},cache=unsafe,readonly=on,format=raw,id=rootfs-{},if=none",
                 path.display(),
                 i
-            );
-            let device = format!("virtio-blk-pci,drive=rootfs-{},serial=rootfs-{}", i, i);
+            ); // Define a read-only raw disk image for the root filesystem.
+            let device = format!("virtio-blk-pci,drive=rootfs-{},serial=rootfs-{}", i, i); // Attach the disk image as a virtio block device.
             (drive, device)
         })
         .collect();
 
     for (drive, device) in rootfs_devices.iter() {
-        args.push("-drive");
-        args.push(drive);
-        args.push("-device");
-        args.push(device);
+        args.append(["-drive", drive]); // Add the disk image as a drive.
+        args.append(["-device", device]); // Attach the drive as a virtio block device.
     }
 
     cmd.args(args);
@@ -152,9 +146,9 @@ pub async fn start_vmrt(
                         "file={},format=qcow2,media=disk,id=vol-{vol_idx},if=none",
                         img_path.display()
                     )
-                    .as_str(),
+                    .as_str(), // Add a QCOW2 disk image for storage.
                     "-device",
-                    format!("virtio-blk-pci,drive=vol-{vol_idx},serial=vol-{vol_idx}").as_ref(),
+                    format!("virtio-blk-pci,drive=vol-{vol_idx},serial=vol-{vol_idx}").as_ref(), // Attach the storage as a virtio block device.
                 ]);
                 kernel_cmdline.push_str(&format!(" vol-{vol_idx}-path={guest_path}"));
                 kernel_cmdline.push_str(&format!(" vol-{vol_idx}-errors={errors}"));
@@ -169,12 +163,10 @@ pub async fn start_vmrt(
 
     if let Some(pci_device_id) = &data.pci_device_id {
         for device_id in pci_device_id.iter() {
-            cmd.arg("-device");
-            cmd.arg(format!("vfio-pci,host={}", device_id).as_str());
+            cmd.args(["-device", format!("vfio-pci,host={}", device_id).as_str()]); // Pass through a PCI device to the VM.
         }
     } else {
-        cmd.arg("-vga");
-        cmd.arg("none");
+        cmd.args(["-vga", "none"]); // Disable VGA output.
     }
 
     if runtime_dir.join(FILE_NVIDIA_FILES).exists() {
@@ -184,17 +176,17 @@ pub async fn start_vmrt(
                 "file={},cache=unsafe,readonly=on,format=raw,id=nvidia-files,if=none",
                 runtime_dir.join(FILE_NVIDIA_FILES).display()
             )
-            .as_str(),
+            .as_str(), // Add a read-only disk image for NVIDIA files.
             "-device",
             "virtio-blk-pci,drive=nvidia-files,serial=nvidia-files"
                 .to_string()
-                .as_ref(),
+                .as_ref(), // Attach the NVIDIA files as a virtio block device.
         ]);
     }
 
-    kernel_cmdline.push_str(&format!(" hostname={}", deployment.hostname));
+    kernel_cmdline.push_str(&format!(" hostname={}", deployment.hostname)); // Set the hostname for the VM.
 
-    cmd.args(["-append", &kernel_cmdline]);
+    cmd.args(["-append", &kernel_cmdline]); // Pass the kernel command-line arguments.
 
     if vpn_remote.is_some() || inet_remote.is_some() {
         let mut pair = SocketPairConf::default();
@@ -213,12 +205,11 @@ pub async fn start_vmrt(
     }
 
     for (idx, volume) in volumes.iter().enumerate() {
-        cmd.arg("-virtfs");
-        cmd.arg(format!(
+        cmd.args(["-virtfs", &format!(
             "local,id={tag},path={path},security_model=none,mount_tag={tag}",
             tag = format!("mnt{}", idx),
             path = work_dir.join(&volume.name).to_string_lossy(),
-        ));
+        )]); // Add a VirtFS (9p) shared folder for the volume.
     }
 
     log::info!("Executing command: {cmd:?}");