Difference between revisions of "QEMU Build Tutorial"

From coreboot
Jump to: navigation, search
(Building FILO)
(Starting coreboot in QEMU: change boot prompt command for FILO)
 
(33 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 
=== Introduction ===
 
=== Introduction ===
  
If you don't have a mainboard supported by LinuxBIOS don't worry: Qemu can help you to emulate one.
+
If you don't have a mainboard supported by coreboot don't worry: [http://qemu.org/ 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 <acassis@gmail.com>, with additions by Ed Swierk <eswierk@arastra.com>.
+
This nice tutorial was written by [mailto:acassis@gmail.com Alan Carvalho de Assis], with additions by [mailto:eswierk@arastra.com Ed Swierk] (but please use the [[Mailinglist|coreboot mailing list]] rather than emailing the authors directly).
  
While there are many ways to use LinuxBIOS to load and run a Linux kernel, this tutorial covers two of the most common:
+
While there are many ways to use coreboot to load and run a Linux kernel, this tutorial covers two of the most common:
  
* LinuxBIOS with FILO as payload, using FILO to load a Linux kernel and initramfs from a hard disk image.
+
* 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.
* LinuxBIOS with a Linux kernel and initramfs as payload.
+
* 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 ===   
 
=== Requirements ===   
Line 14: Line 14:
 
You need the following software packages:
 
You need the following software packages:
  
* [http://linuxbios.org/index.php/Download_LinuxBIOS LinuxBIOSv2] r2405 or greater
+
* [[Download_coreboot|coreboot v4]]
* [http://qemu.org/download.html Qemu] 0.8.2 or greater
+
* [http://qemu.org/ Qemu]
* [http://linuxbios.org/index.php/FILO FILO] 0.4.2 or greater (if using FILO)
+
* [[FILO]] 0.6 or greater (if using FILO)
 
* [ftp://ftp.lnxi.com/pub/mkelfImage mkelfImage] 2.7 or greater (if not using FILO)
 
* [ftp://ftp.lnxi.com/pub/mkelfImage 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.
+
plus a Linux kernel and root filesystem and a working development environment (make, gcc, etc.).
  
=== Building FILO ===
+
=== Building or finding a Linux kernel ===
  
If you plan to build your Linux kernel and root filesystem directly into LinuxBIOS, you can skip this section.
+
If you are using FILO, you can simply grab a Linux kernel and initramfs from your favorite distribution.
  
Download FILO (I used filo-0.4.2.tar.bz2), decompress it, enter inside the created directory.
+
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.
 
+
First invocation of make creates the default Config file.
+
$ make
+
  
Edit this file as you like. The default configuration worked for me.  
+
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:
  $ vi Config 
+
* [http://kboot.sourceforge.net/ kboot]
 +
* [http://wiki.laptop.org/go/Building_LinuxBIOS 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]], and cd to the filo directory
 +
 
 +
First invocation of make creates the config file.
 +
  $ make menuconfig
  
Run make again to create filo.elf, the ELF FILO image.   
+
Run make again to create build/filo.elf, the ELF FILO image.   
 
  $ make   
 
  $ make   
  
You will use this file (filo.elf) as the LinuxBIOS payload later on.
+
You will use this file (filo.elf) as the coreboot payload later on.
  
=== Creating LinuxBIOS ===
+
=== Building a Linux kernel payload ===
  
Download LinuxBIOS source code (I used LinuxBIOSv2-2394).
+
If you are using FILO, skip this section.
Decompress it. 
+
 
+
Change to directory targets/emulation/qemu-i386 and modify Config.lb to point to your filo.elf. 
+
 
+
Return to targets directory and execute: 
+
  
$ ./buildtarget emulation/qemu-i386 
+
Download mkelfImage (I used mkelfImage-2.7.tar.gz), decompress it, and cd to the created directory.
  
Go to targets/emulation/qemu-i386/qemu-i386 and execute:  
+
Configure and build the mkelfImage binary.
 +
  $ ./configure && make
  
  $ 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
  
It will create the file "qemu-bios.rom" 
+
Note: disable CONFIG_WRITE_HIGH_TABLES. Building coreboot with this option enabled crashes during elf image execution.
 
+
Rename this file to "bios.bin" and copy to your HOME directory. 
+
 
+
  
=== Creating your disk image ===
+
=== Building coreboot ===
+
Create a empty file (~ 200MB):
+
  
# dd if=/dev/zero of=disk.img bs=1M count=200
+
See the [[Build HOWTO]] for information on how to build coreboot for this board.
  
Format it as ext2:
+
This creates the coreboot image (build/coreboot.rom).
  
# mkfs.ext2 -F disk.img
+
=== Building Qemu ===
 +
Qemu used to require patches to work with coreboot, but any current standard build (as packaged by distributions) should be good enough.
  
Mount it on somewhere:  
+
<!--
 +
==== Building Qemu on FreeBSD ====
 +
Qemu can easily be installed using FreeBSD's Ports tree. The Qemu port lives in emulators/qemu. However, as of version 0.9.1 the FreeBSD port can unfortunately no longer be used with coreboot. The latest working version is 0.9.0 which can be retrieved from the FreeBSD CVS repository. For your convenience, an archive of the last working port version has been uploaded to this wiki. You can download the archive from [http://www.coreboot.org/Image:FreeBSD-Qemu-0.9.0.tgz here]. For some reason, the downloaded archive cannot be extracted with tar only, so use these steps to extract the archive:
  
  # mount disk.img /mnt/rootfs -t ext2 -o loop
+
  $ gunzip FreeBSD-Qemu-0.9.0.tgz
 +
$ tar -xvf FreeBSD-Qemu.0.9.0.tar
  
Now you need copy a root filesystem to it.
+
To build and install the port, do this:
  
I create a directory /debian and used debootstrap command to create a basic root filesystem, but you can use any root filesystem from your distro (i.e. copy one from diskboot.img):
+
$ cd qemu
 +
$ make clean install
  
# cp -R /debian/* /mnt/rootfs
+
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 <tt>/boot/loader.conf</tt>:
  
Open the file /mnt/rootfs/etc/inittab and change runlevel to level 1:
+
<pre>
 +
aio_load="YES"
 +
kqemu_load="YES"
 +
</pre>
  
id:1:initdefault:
+
You can now use the Qemu binary located in <tt>/usr/local/bin</tt>.
 +
-->
 +
=== Creating a hard disk image ===
  
Change to /mnt/rootfs/boot and copy your default vmlinuz and initrd:
+
If you are using FILO, you must create a hard disk image containing the Linux kernel and optional initramfs that FILO loads.
  
# cp /boot/vmlinuz-2.6.16-2-686 vmlinuz
+
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.
# cp /boot/initrd.img-2.6.16-2-686 initrd
+
  
Change to /root and umount /mnt/rootfs:
+
Create an empty disk image:
 +
$ qemu-img create -f raw disk.img 200M
  
  # umount /mnt/rootfs
+
Format it:
 +
  $ mkfs.ext2 -F disk.img
  
Exit of root account:
+
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
 
  # exit
  
 +
=== Starting coreboot in QEMU ===
 +
 +
Execute QEMU using the following parameters:
 +
$ qemu -bios path/to/coreboot.rom -hda disk.img -nographic
 +
 +
The -bios option tells QEMU to use path/to/coreboot.rom as its BIOS.  The -nographic option suppresses the graphical VGA display and connects the virtual machine's serial port to your console. If you want to keep VGA display, you can use "-serial stdio" instead, which only redirects serial to the console.
  
=== Starting LinuxBIOS in Qemu ===
+
You should now see all sorts of interesting coreboot messages, followed by Linux kernel boot messages or a FILO prompt.
  
Execute Qemu using the followings parameters:
+
If you are using FILO, enter at the boot: prompt:
  
  $ qemu -L ~ -hda disk.img -nographic -no-kqemu -d in_asm,exec
+
  kernel hda:/boot/vmlinuz root=/dev/hda
 +
initrd hda:/boot/initrd
 +
boot console=ttyS0
  
When appear "boot:" text enter it:
+
Example:
  
boot: hda:/boot/vmlinuz root=/dev/hda initrd=/boot/initrd console=tty0 console=ttyS0,115200
+
[[Image:Screenshot linuxbios boots qemu.png]]

Latest revision as of 14:22, 9 July 2013

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:

plus a Linux kernel and root filesystem and a working development environment (make, gcc, etc.).

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:

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, and cd to the filo directory

First invocation of make creates the config file.

$ make menuconfig

Run make again to create build/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

Note: disable CONFIG_WRITE_HIGH_TABLES. Building coreboot with this option enabled crashes during elf image execution.

Building coreboot

See the Build HOWTO for information on how to build coreboot for this board.

This creates the coreboot image (build/coreboot.rom).

Building Qemu

Qemu used to require patches to work with coreboot, but any current standard build (as packaged by distributions) should be good enough.

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 -bios path/to/coreboot.rom -hda disk.img -nographic

The -bios option tells QEMU to use path/to/coreboot.rom as its BIOS. The -nographic option suppresses the graphical VGA display and connects the virtual machine's serial port to your console. If you want to keep VGA display, you can use "-serial stdio" instead, which only redirects serial to the 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:

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

Example:

Screenshot linuxbios boots qemu.png