Column 4: Getting started under QEMU. (2011-07-20)

Everybody who runs Linux can have at least some hands-on experience with Coreboot. The PC emulator QEMU can use a Coreboot ROM image file instead of its normal BIOS ROM image. So there is absolutely no risk of frying your motherboard with that. On the downside: you can only test the "easy part" of Coreboot. The hard part (low-level chipset and RAM initialization) under QEMU will not be representative of real hardware (RAM just works from the start in QEMU).

Before you begin

In this document I will explain how to get started with Coreboot using Ubuntu Linux 11.04. It may (and probably will) work on different recent Linux distributions and possibly some non-Linux distributions as well. QEMU will run on Windows but its paths for ROM images are different from Linux. If you run Windows you have some viable options to run the development tools as well, such as Cygwin and running Ubuntu itself under QEMU. The following packages will be needed.

• Development tools. Even though we are going to build our own C compiler and related tools for Coreboot, we need working development tools to start with. Most is already installed by default under the latest version of Ubuntu, but "bison", "flex" and "ncurses-dev" (for the configure tool) are absent and have to be installed explicitly.
• QEMU. The 0.14.0 version supplied with Ubuntu 11.04 works well. If your distribution uses an older version of QEMU, it may be worth trying to compile a 0.14 version yourself.
• Git, the version control system used by Coreboot. We will not commit changes to the Coreboot repository (and we would need a developer account for that), but obtaining the latest sources with git is easy.

Under Ubuntu 11.04 you can get all required packages at once using the following command:

$ sudo apt-get install qemu git flex bison ncurses-dev

It is worth reading the Coreboot Build Howto and the the Coreboot SeaBIOS page at the main Coreboot site.

Getting yourself up to speed with QEMU

Before you start running Coreboot on QEMU, it is very well worth you time to get familiar with QEMU using its own BIOS (which is SeaBIOS by the way).

• Get yourself an ISO image or a CD-ROM for your favorite Linux distribution.
• Create a hard disk image. For instance to create a raw image of 10 Gigabyte, type:

  $ mkdir images
  $ dd if=/dev/zero of=images/debian_hd.img bs=1G count=10
  

• Start QEMU with a CD-ROM image and 512MB of RAM (image is stored in the images directory):

  $ qemu -hda images/debian_hd.img -cdrom images/debian-6.0.1a-i386-netinst.iso -boot d -m 512 &
  

  Alternatively you can use a real CD-ROM, like this:

  $ qemu -hda images/debian_hd.img -cdrom /dev/cdrom -boot d -m 512 &
  

  Run through the installation procedure of your distribution as usual.
• When rebooting QEMU, leave out the "-boot d" option and you can boot it from the hard disk image.

  $ qemu -hda images/debian_hd.img  -m 512 &
  

Obtaining the sources

The Coreboot project uses git as its version control system. Anonymous read-only access is available. Obtain the project with the following command.

git clone http://review.coreboot.org/p/coreboot

This command downloads the sources of Coreboot project only, but not the payloads. When building Coreboot with SeaBIOS (the default), the make procedure will automatically download the SeaBIOS sources.

Under the "coreboot" directory you can later type the "git pull" command to update the source tree to the latest available version.

$ cd coreboot
$ git pull

Building the cross compiler

Even though your PC will likely use the same CPU architecture as Coreboot (both x86), it is still strongly recommended to use a cross compiler. Especially where it comes to 16-bit code and properly linking the code into a single ROM image, it is very important to use the exact correct version of certain tools. If there are bugs in certain versions of GNU tools, at least you can be fairly sure that they are the same as those encountered by the main developers. This is true when you use the same version of GCC, bintils and all related tools as the developers are using.

Because the build procedure is fully scripted, building the cross toolchain is only hard for your computer, not for you (and hopefully it is a one-time job). Make sure the development tools including bison and flex are in place before you start.

Type the following commands and take a long break.

$ cd coreboot
$ make crossgcc

Stealing the VGA BIOS

Fortunately this is legal, at least for the open source VGA BIOS image included with QEMU. Neither Coreboot nor SeaBIOS includes a usable VGA BIOS, so it is necessary to reuse the VGA BIOS that came from QEMU. This will be included in the main ROM image, so it won't be a separate ROM image.

Make sure you are in the coreboot directory and copy the image from the directory where QEMU stores it.

$ cp /usr/share/qemu/vgabios-cirrus.bin .

Configuring and building the BIOS

Now it's time to configure Coreboot. The default "mainboard" is already set to "QEMU" and the default payload is already set to "SeaBIOS", but there are still a few things left to do. First run the following command:

$ make menuconfig

If you have ever configured a Linux kernel, this interface should be very familiar to you. Perform the following configuration steps.

• Select the Console submenu, under the submenu enable "Use onboard VGA as primary video device". Exit this submenu.
• Under the Chipset submenu, disable "Run VGA option ROMs". SeaBIOS will already run the VGA option ROM and there is no reason to run this twice. Exit this submenu.
• Select the VGA BIOS submenu. Change the file name to "vga-cirrus.bin" and the PCI device IDs to 1013,00b8. This is for the emulated Cirrus VGA chip included with QEMU 0.14, different versions of QEMU may require different ROM images and different PCI IDs.

Now you are ready to run make.

$ make

Testing the result

Now that the ROM image is made, the only thing left to do is to make it visible for QEMU. In this example we start QEMU from the "coreboot" directory. Next we can run QEMU.

$ ln -s build/coreboot.rom bios.bin
$ qemu -L . -hda ../images/debian_hd.img -cdrom ../images/debian-6.0.1a-i386-netinst.iso -m 512 -serial stdio

A few remarks:

• The "-L." option causes QEMU to read its ROM images from the current directory. Only "bios.bin" needs to be present.
• There is no network card ROM whatsoever. This is no problem for Linux (it can initialize the interface from scratch), but it is likely to be problematic for some other operating systems. The network interface ROM from QEMU can be added to the Coreboot ROM image.
• With "-serial stdio" the serial output (lots of diagnostics) will be displayed on standard output. You must not run the program in the background.
• Selecting the boot device is now performed by pressing the F12 key in the QEMU window just after startup. This will present a choice between boot devices (CD or hard disk). Other Coreboot payloads may be added to this boot menu as well.

Where to go from here?

Hopefully the first attempt to run Coreboot under QEMU was a success. Now you are ready to experiment. There are many things you can try:

• In "make menuconfig" (mainboard submenu) you can increase the ROM size for QEMU to 2048kB (default is 256kB), so you can add more and larger payloads.
• Try to add a boot splash screen by adding an appropriate JPEG file to the ROM image.
• Try to add a gPXE network ROM.
• Try to compile different Coreboot payloads (FILO, TINT) and add them as additional payloads (see Coreboot SeaBIOS page). These should now appear in the menu when you press F12.
• Create a small Linux kernel (with initramfs) and use that as a payload.
• Try to build Coreboot with a payload other than SeaBIOS and run this without SeaBIOS. Now you must enable "Run VGA option ROMs" in the chipset menu.