Skip to content

qemu-quickstart.md

Latest commit

 

History

History
151 lines (96 loc) · 4.81 KB

qemu-quickstart.md

File metadata and controls

151 lines (96 loc) · 4.81 KB
Raw

QEMU Quickstart Guide

English | 中文

This guide covers how to set up the AxVisor development environment locally and run different guest operating systems on QEMU.

Prerequisites

  • OS: Linux (native or WSL2)
  • Architecture: x86_64 host

1. Install System Dependencies

sudo apt update && sudo apt install -y \
  build-essential gcc libssl-dev libudev-dev pkg-config \
  qemu-system-x86 qemu-system-arm qemu-system-misc \
  git curl wget

2. Install Rust Toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Once you enter the project directory, Rust will automatically install the required nightly toolchain, components, and cross-compilation targets based on rust-toolchain.toml — no manual configuration needed.

Install additional Cargo tools:

cargo install cargo-binutils
cargo +stable install ostool --version '^0.8'
  • cargo-binutils: provides rust-objcopy, rust-objdump, etc.
  • ostool: custom build runner for AxVisor

3. KVM Setup (NimbOS x86_64 Only)

NimbOS runs on x86_64 QEMU and requires KVM hardware acceleration. ArceOS and Linux use AArch64 QEMU (TCG mode) and do not need KVM — you can skip this section.

Verify the KVM device exists:

ls -la /dev/kvm

Add your user to the kvm group:

sudo usermod -aG kvm $USER

Apply the group change in the current terminal without re-logging:

newgrp kvm

Verify:

id  # output should include "kvm"

4. Running Guest OSes

This branch provides a one-click setup script scripts/setup_qemu.sh that automatically downloads guest images, patches configuration paths, and prepares the rootfs.

ArceOS (AArch64)

./scripts/setup_qemu.sh arceos

cargo xtask qemu \
  --build-config configs/board/qemu-aarch64.toml \
  --qemu-config .github/workflows/qemu-aarch64.toml \
  --vmconfigs tmp/vmconfigs/arceos-aarch64-qemu-smp1.generated.toml

Success indicator: Hello, world! appears in the output.

Linux (AArch64)

./scripts/setup_qemu.sh linux

cargo xtask qemu \
  --build-config configs/board/qemu-aarch64.toml \
  --qemu-config .github/workflows/qemu-aarch64.toml \
  --vmconfigs tmp/vmconfigs/linux-aarch64-qemu-smp1.generated.toml

Success indicator: test pass! appears in the output.

NimbOS (x86_64, requires KVM)

./scripts/setup_qemu.sh nimbos

cargo xtask qemu \
  --build-config configs/board/qemu-x86_64.toml \
  --qemu-config .github/workflows/qemu-x86_64-kvm.toml \
  --vmconfigs tmp/vmconfigs/nimbos-x86_64-qemu-smp1.generated.toml

After booting, you will enter the Rust user shell (>> prompt). Type usertests to run the test suite. All tests passing will print usertests passed!

Note: NimbOS requires VT-x/KVM. If /dev/kvm does not exist or has insufficient permissions, you will get a Permission denied error. WSL2 requires nested virtualization support in the kernel to use KVM.

5. What Does setup_qemu.sh Do?

The script automates three steps, eliminating manual work:

  1. Download images: calls cargo xtask image download to fetch guest images to /tmp/.axvisor-images/
  2. Generate temp configs: copies VM config templates to tmp/vmconfigs/*.generated.toml, then uses sed to update kernel_path (and bios_path for NimbOS) to actual image paths without modifying tracked files in configs/vms/*.toml
  3. Prepare rootfs: copies rootfs.img to the project's tmp/ directory for QEMU to use

You can also perform these steps manually if you prefer not to use the script.

Troubleshooting

Path tmp/Image not found

The kernel_path in the VM config points to a non-existent file. Run ./scripts/setup_qemu.sh <guest> to automatically fix the paths.

Could not access KVM kernel module: Permission denied

Your user is not in the kvm group. See the "KVM Setup" section above.

qemu-system-aarch64: command not found

QEMU is not installed. Run the apt install command from Step 1.

Auto syncing from registry ... timed out

This usually indicates unstable access to GitHub Raw endpoints. scripts/setup_qemu.sh includes one built-in recovery attempt: when the first image download fails, it bootstraps a local registry and retries once automatically. The script also has a default fallback registry (currently pointing to v0.0.22.toml).

If your network is unstable for specific registry URLs, you can override the fallback registry:

export AXVISOR_REGISTRY_FALLBACK_URL="https://raw.githubusercontent.com/arceos-hypervisor/axvisor-guest/refs/heads/main/registry/v0.0.22.toml"
./scripts/setup_qemu.sh arceos

First build is very slow

This is expected. AxVisor has many dependencies, and the first compilation needs to download and build all crates. Subsequent incremental builds will be much faster.