QEMU Build Tutorial

Introduction

If you don't have a mainboard supported by coreboot don't worry: QEMU can help you to emulate one. Using coreboot with QEMU may serve the purpose to familiarize you as a developer with coreboot and may be a reference system during development.

This nice tutorial was written by Alan Carvalho de Assis, with additions by Ed Swierk (but please use the coreboot mailing list rather than emailing the authors directly).

While there are many ways to use coreboot to load and run a Linux kernel, this tutorial covers two of the most common:

• coreboot with FILO as payload, using FILO to load a Linux kernel (and optional initramfs) from a hard disk image. This approach involves a bit more mechanism (it relies on FILO's built-in disk and filesystem drivers) but it produces a tiny coreboot image.
• coreboot with a Linux kernel (and optional initramfs) as payload. This cuts FILO out of the picture, but the main challenge with this approach is squeezing the resulting coreboot image into QEMU's BIOS ROM area (currently 2 MB, but easy to extend by patching QEMU).

Requirements

You need the following software packages:

• coreboot v2 r2405 or greater
• Qemu 0.9.0 or greater
• FILO 0.4.2 or greater (if using FILO)
• mkelfImage 2.7 or greater (if not using FILO)

plus a Linux kernel and root filesystem and a working development environment (make, gcc, etc.). gcc 4.0.x and 4.1.x are known to work for all packages except QEMU, which requires gcc 3.x.

Building or finding a Linux kernel

If you are using FILO, you can simply grab a Linux kernel and initramfs from your favorite distribution.

Otherwise, you will probably need to build a kernel and initramfs from scratch, ensuring that the final coreboot image does not exceed QEMU's BIOS size limit (2MB if qemu-bios-size patch applied, 256KB otherwise). Building the kernel and initramfs is beyond the scope of this tutorial; how you configure them depends on your application.

If you plan to use kexec to chain-boot another Linux kernel, tools from these projects can help automate the process of generating a kernel and initramfs:

• kboot
• OLPC buildrom

Building a FILO payload

If you plan to build your Linux kernel and root filesystem directly into coreboot, you can skip this section.

Download FILO (I used filo-0.4.2.tar.bz2), decompress it, and cd to the created directory.

First invocation of make creates the default Config file.

$ make

Edit this file as you like. The default configuration worked for me.

$ vi Config   

Run make again to create filo.elf, the ELF FILO image.

$ make   

You will use this file (filo.elf) as the coreboot payload later on.

Building a Linux kernel payload

If you are using FILO, skip this section.

Download mkelfImage (I used mkelfImage-2.7.tar.gz), decompress it, and cd to the created directory.

Configure and build the mkelfImage binary.

$ ./configure && make

Now use mkelfImage to convert your Linux kernel image (vmlinuz) and initramfs (initrd) into a usable coreboot payload (linux.elf):

$ mkelfImage --append="console=ttyS0" --initrd=initrd vmlinuz linux.elf

Building coreboot

Download the coreboot source code (I used coreboot-v2 r2405) and extract it.

Change to directory targets/emulation/qemu-i386 and modify Config.lb:

• change payload to point to your payload (filo.elf or linux.elf)
• if you are using a Linux payload, increase the value of option ROM_SIZE to 2048*1024 (2 MB)

Return to targets directory and execute:

$ ./buildtarget emulation/qemu-i386  

Go to targets/emulation/qemu-i386/qemu-i386 and execute:

$ make  

This creates the coreboot image (qemu-bios.rom). Copy and rename this file to bios.bin in your home directory.

Building Qemu

If you plan to run Qemu version 0.9.0, you will have to build QEMU from source after applying a couple of patches. (Later versions of QEMU might incorporate these patches, allowing you to run them unmodified; hopefully someone will be kind enough to update this tutorial if this happens.)

Download the QEMU source code (I used qemu-0.9.0.tar.gz) and extract it.

Download these three patches and save them to the QEMU source directory:

• qemu-isa-bios-ram.patch
• qemu-piix-ram-size.patch
• qemu-bios-size.patch

Enter the QEMU source directory and apply the patches:

$ patch -p1 < qemu-isa-bios-ram.patch
$ patch -p1 < qemu-piix-ram-size.patch
$ patch -p1 < qemu-bios-size.patch

Configure and make QEMU (use the --cc option if your default gcc is newer than version 3.4):

$ ./configure --cc=gcc-3.4 --target-list=i386-softmmu && make

The QEMU binary is stored in the i386-softmmu directory.

Building Qemu on FreeBSD

Qemu can easily be installed using FreeBSD's Ports tree. The port system can also automatically apply patches as part of the port build process. Files in the port's files/ subdirectory whose name start with patch- will automatically be applied as patches when building the port.

The Qemu port lives in emulators/qemu. In order to apply the patches mentioned above, copy the patch files to the files/ subdirectory of the Qemu port (e.g. /usr/ports/emulators/qemu/files). Then rename them so that they carry the patch- prefix as part of their name. For instance, to have the port system automatically apply the Patch qemu-isa-bios-ram.patch mentioned above, rename the file to patch-isa-bios-ram.patch.

Please note that you cannot use a prebuilt package but must build the port from sources. To do that, run (as root):

$ cd /usr/ports/emulators/qemu
$ make clean install

Make sure you load the aio(4) kernel module before starting QEMU. Also, QEMU can be build with the kqemu kernel module that enhances QEMU's performance. To load both kernel modules at boot time, add the following lines to /boot/loader.conf:

aio_load="YES"
kqemu_load="YES"

You can now use the Qemu binary located in /usr/local/bin.

Creating a hard disk image

If you are using FILO, you must create a hard disk image containing the Linux kernel and optional initramfs that FILO loads.

Whether or not you use FILO, you may also wish to populate the disk image with the root filesystem of whatever Linux distribution you want to run.

Create an empty disk image:

$ qemu-img create -f raw disk.img 200M

Format it:

$ mkfs.ext2 -F disk.img 

The remaining steps must be performed as root. Create a temporary mountpoint and mount the image:

# mkdir /mnt/rootfs
# mount -o loop disk.img /mnt/rootfs

Create a boot directory and copy your Linux kernel (vmlinuz) and initramfs (initrd) to it:

# mkdir /mnt/rootfs/boot
# cp vmlinuz /mnt/rootfs/boot/vmlinuz
# cp initrd /mnt/rootfs/boot/initrd

At this point, you can also copy a complete root filesystem to the disk image.

# cp -R /* /mnt/rootfs 

Alternatively, with Debian you can use the debootstrap command to create a basic root filesystem:

# debootstrap --arch i386 sarge /mnt/rootfs http://ftp.debian.org/debian/ 

If you are using a debootstrap filesystem, open the file /mnt/rootfs/etc/inittab and change runlevel to level 1:

id:1:initdefault: 

cd out of /mnt/rootfs and umount it:

# umount /mnt/rootfs

Exit from the root account:

# exit

Starting coreboot in QEMU

Execute QEMU using the following parameters:

$ qemu -L ~ -hda disk.img -nographic

The -L option tells QEMU to look for bios.bin in your $HOME directory. The -nographic option suppresses the graphical VGA display and connects the virtual machine's serial port to your console.

You should now see all sorts of interesting coreboot messages, followed by Linux kernel boot messages or a FILO prompt.

If you are using FILO, enter at the boot: prompt:

boot: hda:/boot/vmlinuz root=/dev/hda initrd=/boot/initrd console=ttyS0

Example: