3.4. Building Disk Images

Full-system host simulators boot Linux from a disk image (see Disk Images and Data Flow for how disk images are referenced from virtual prototype scripts). Disk image building lives in its own small, simulator-independent repository: image-builder. It drives Packer and QEMU to turn a stock cloud image into the image plus boot artifacts SimBricks needs.

Note

You only need this if you execute simulations on your own machines with custom images. The SimBricks Cloud Runners and the simbricks/simbricks-executor Docker image already ship a pre-built base image with the common drivers and tools included.

3.4.1. What it produces

A build produces one directory that maps 1:1 onto the global input directory layout the orchestration framework expects:

output-base/
  base            # the disk image (qcow2)
  base.raw        # raw conversion (with CONVERT_RAW=true; required for gem5)
  boot/
    vmlinuz       # kernel (bzImage)  -> used by QEMU
    initrd        # initramfs         -> used by QEMU
    vmlinux       # kernel (ELF)      -> used by gem5

Copy (or symlink) this into your global input directory as images/<name>/ and reference it with system.DistroDiskImage(syst, "<name>").

3.4.2. Requirements and basic usage

You need Packer (with the QEMU plugin), qemu-system-x86_64/qemu-img (KVM strongly recommended), and libguestfs-tools. Alternatively, the repository ships a dev container with everything pre-installed. Then:

git clone https://github.com/simbricks/image-builder.git
cd image-builder
make image                       # builds the default Ubuntu-based 'base' image

The build boots the distro cloud image under QEMU, runs a configurable list of provisioning scripts inside the guest (installing the generic kernel, base benchmarking tools, serial-console boot configuration, and the SimBricks guest-init hook), and finally extracts the boot artifacts from the finished image. Variables like SOURCE_IMAGE/SOURCE_CHECKSUM (base cloud image), NAME, DISK_SIZE, ACCELERATOR (kvm/tcg) and CONVERT_RAW can be overridden on the make command line — see the repository README for the full list.

Important

gem5 only supports raw images, so build with CONVERT_RAW=true if you plan to use Gem5Sim.

3.4.3. Custom images

There are two ways to customize images, both driven by additional provisioning scripts that run inside the guest as root:

One-shot — append extra scripts to the base build:

make image EXTRA_SCRIPTS="path/to/your/install-script.sh"

Layered — build the base once, then derive specialized images from it (faster when you maintain several images):

make image                                     # 1. base image -> output-base/base
make image NAME=my-image \
    SOURCE_IMAGE=output-base/base SOURCE_CHECKSUM=none \
    BASE_SCRIPTS= EXTRA_SCRIPTS="path/to/your/install-script.sh"

Component repositories that need guest-side software ship such install scripts — e.g. the Corundum mqnic driver (examples/corundum/install-mqnic.sh, which builds the driver against the image’s kernel) and gem5’s m5 guest tool (examples/gem5/install-m5.sh). See Packaging a Simulator as a Component Repository for how this fits into a simulator integration.

3.4.4. Custom kernels (gem5)

By default images use the distribution’s own kernel. For gem5, the repository can additionally build a custom kernel that boots without an initrd and includes timer patches for gem5:

make kernel                          # -> output/kernel/{vmlinux, linux-*.deb}
make image NAME=gem5 INPUT=output/kernel \
  BASE_SCRIPTS="kernel/install-kernel.sh scripts/install-base.sh scripts/configure-boot.sh scripts/install-guestinit.sh" \
  EXTRA_SCRIPTS="examples/gem5/install-m5.sh" \
  CONVERT_RAW=true

This is also exactly how the base image shipped in the executor Docker image is built.

3.4.5. In-script image builds

Instead of building images ahead of time, virtual prototype scripts can also reference a Packer configuration directly through system.PackerDiskImage(syst, <path-to-config>) — the image is then built as part of preparing the simulation.