Introduction

This is a short but hopefully complete walk through, which should help you getting started with LinuxBIOS (LB) and the IWILL DK8-HTX mainboard. It was written by Philipp Degler <pdegler {at} rumms.uni-mannheim.de> with the help of Mondrian Nuessle <mondrian {at} uni-mannheim.de>.

At the end of this tutorial you should be able to install LinuxBIOS on an IWILL DK8-HTX mainboard. You should also understand how to use different payloads.

Requirements

You need the following software packages:

LinuxBIOSv2 r2481 (You may also use newer versions. Anyway, this one is tested and working)

Overview

OK, before we go into every detail you should get a rough overview of the "install" process. You don't need to go through the first 5 points if you have a working LinuxBIOS image. Unfortunately, the LinuxBIOS project is not distributing ready-made images. There have already been discussions on the mailing list about that topic.

So, what will be your next steps?

Get specific revision of LinuxBIOS

Choose and build the payload

Tweak LinuxBIOS config

Build LinuxBIOS

Check created ROM image

Flash new BIOS - now it's getting dirty :)

Verify your new BIOS

Turn off your machine and start again

After first boot, LinuxBIOS tables are in place and can be changed with the lxbios utility.

Getting LinuxBIOS source code

We recommend using LinuxBIOS SVN revision r2481. But a newer one should also be OK. Omitting "-r xxxx" will retrieve the newest revision.

Choosing a payload

LinuxBIOS alone is not able to boot your OS directly (bootstrap). Normally this is done by grub, lilo, ntloader or another bootloader. Unfortunately, LinuxBIOS is not providing a native 16 bit callback layer any more. As grub and others are depending on that layer you obviously can't use them together with LinuxBIOS. Therefore LinuxBIOS is offering an elf-loader that is able to load and start an elf executable. The elf image is put into the ROM together with the LinuxBIOS image. In context with LinuxBIOS this elf image is called payload. So finally the payload has the task to boot your OS. You can choose between a lot of different payloads. In this HOWTO we only mention FILO and Etherboot. These two will allow us to boot a Linux OS from local disk (IDE or SATA).

FILO (boot from IDE)

FILO sounds like lilo. In reality they have not so much in common. Both can boot an OS from IDE disk. As already mentioned earlier it is not possible to use lilo with LinuxBIOS directly. FILO is filling the gap. It is fully 32 bit and needs no BIOS callbacks like grub or lilo do. You should use FILO if you plan to boot from an IDE Disk or CDROM. Etherboot would also be able to boot from IDE but FILO standalone can read grub's menu.lst and generate a nice boot menu for you. Now please read the FILO article and build your elf image.
Maybe you will find our FILO config for DK8-HTX helpful.

Etherboot (boot from SATA)

Etherboot is an independent open source project. It allows one to boot an OS from various media:

floppy

CDROM

HDD

USB

most network interfaces (of course).

Etherboot also supports PXE (Preboot Execution Environment).
Why is etherboot interesting in this HOWTO? Well, etherboot also supports SATA. This is because an earlier modified FILO version was integrated into etherboot. More details on building an etherboot for LinuxBIOS are available.

Hints

How can I choose the driver for my network interface (if)?

If you want to add support for more than one if-driver use '--' to separate the options from each other. In the example underneath we are compiling etherboot with Intel® 82541PI and FILO support. "*.zelf" states that we want to build a compressed image which is normally a good idea.

$ make bin/e1000--filo.zelf

But how do I know the name of the driver for my network if?

In etherboot most drivers cover a whole family of cards. This means you have to find out which driver family is supporting your specific device. So here is what you do:

Change to the "src" directory of etherboot and run "make" without any arguments. This will generate a NIC file in the "bin" dir.

Change to the "bin" dir and open the NIC file with your favorite editor. You should find the matching family name to your device.

Configuring LinuxBIOS

Configuration Spaces

As you can see in the graphic the config space of LinuxBIOS can be divided in 3 sets. Each set comprises a number of configuration options.

Set of all Config options (1)

Typically a LinuxBIOS developer adds or changes config options during the process of development. The support of new chips and functions often leads to new config options.

Set of Mainboard options (2)

This is a subset of all existing Options. If one ports a mainboard for LB one has to decide which config options are needed in order to model the architecture of the mainboard. The maintainer sets default values that should ensure a working version for the respective mainboard.

Set of Image options (3)

Finally the image specific options are a subset of the mainboard specific options. They allow endusers to override default values. Although one can override any option the mainboard maintainer has defined it is not a good idea to do so. One should only override options that regard image settings. For example which payload to use.

In this HOWTO we want to concentrate on the image config. Normally you would only need one image to boot your PC, but changing configuration may lead to a broken BIOS. For this reason LinuxBIOS offers a fallback mechanism, that jumps into place if your normal LinuxBIOS image would not boot. We will see later how you can boot with a specific image (normal or fallback).

Specify Log-Level

Normally LB can boot really fast — a lot of log messages may really slow it down. You can choose between 9 different loglevels:

EMERG — system is unusable

ALERT — action must be taken immediately

CRIT — critical conditions

ERR — error conditions

WARNING — warning conditions

NOTICE — normal but significant condition

INFO — informational

DEBUG — debug-level messages

SPEW — way too many details

You may change the default loglevel (8) by adding the following two lines to your "targets/iwill/dk8_htx/Config.lb"

## Request this level of debugging output
default DEFAULT_CONSOLE_LOGLEVEL=5
## At a maximum only compile in this level of debugging
default MAXIMUM_CONSOLE_LOGLEVEL=5

VGA Support

Before one can access the VGA device it has to be initialized. In LB you can choose between two options:

Use the original proprietary ATI BIOS.

or use a LB open source driver if there is one. Otherwise you have to implement your own driver.

In this HOWTO we will concentrate on the first option, because this will add full support for the VGA onboard device.

Image Config (targets/iwill/dk8_htx/Config.lb)

The original ATI BIOS has to be prepended to the linuxbios.rom. Therefore you have to change the size of the linuxbios.rom. Add the following lines to your Config.lb:

reserve 36k for VGA extension ROM

option ROM_SIZE = (512*1024)-(36*1024)

As you can see we are reserving 36KB for the VGA BIOS.

Mainboard Config (src/mainboards/iwill/dk8_htx/Config.lb)

Normally you should not change the mainboard config because mainboards do not change that often. In case of VGA support we need to make some modifications so that LinuxBIOS will know where to load the VGA BIOS from. So please add the following node (the italic lines) to the "device tree" of the mainboard's Config.lb.

...

PCI bridge

device pci 0.0 on
device pci 0.0 on end
device pci 0.1 on end
device pci 0.2 off end
device pci 1.0 off end
chip drivers/pci/onboarddevice pci 6.0 on endregister "rom_address" = "0xfff80000"end
end
...

Building LinuxBIOS

You have compiled your payload and changed Config.lb of your target mainboard accordingly. So you are now ready to make the next step.

Start the build process

cd to "targets" dir

run "./buildtarget producer/mainboard_model"

The result should be a build directory. In this case a new dir called "dk8_htx".

$ ./buildtarget iwill/dk8_htx

cd to new dir "iwill/dk8_htx/dk8_htx"

run "make"

Depending on your image config (Config.lb) a normal-, a fallback- and maybe a failure-image will be compiled. Finally these separate images will be concatenated to a final "linuxbios.rom".

Append VGA BIOS

If you are not planing to use VGA you can leave out this part of the HOWTO.

Do you remember the configuration chapter where we reduced the size of the linuxbios.rom image about 36KB. Now we have to concatenate VGA BIOS image and LinuxBIOS image. We assume the name of your VGA BIOS image is "ati_bios.rom".

copy ati_bios.rom into the build directory

cd to build directory "targets/iwill/dk8_htx/dk8_htx"

use "cat" to concat the two images

$ cat ati_bios.rom linuxbios.rom > final.rom

Check the image file

Before burning the final image it is always a good idea to check the image size. DK8-HTX has a 512KB ROM. So the "linuxbios.rom" ("final.rom" respectively) should also have 512KB.

Hints

LinuxBIOS is not compiling?

Sometimes scripts use standard output of a command to decide for example if a library has the right version. Actually this is not good style and you should post such issues if you find some. But one could solve such problems by changing console language to English. This can be done for example in your local .bashrc:

Installing LinuxBIOS

Up till now we only looked at the software part of this HOWTO. The next steps may involve a little bit of hardware. We used a BIOS Savior in order to safely install and develop LinuxBIOS. Other options include FLASH/ROM emulators and external FLASH/EPROM programmers. If you simply want to use LinuxBIOS as "normal" BIOS replacement you could skip the next paragraph and continue with compiling the flashrom utility.

The BIOS Savior

RD1 BIOS Savior

We used a BIOS Savior for development purposes. Unfortunately it is hard to get the right model in Europe. So we got ourselves a similar model and modified it a "little". Actually this was quite a hack and should not be repeated. Try to get the right one for a PLCC32 socket. The ROM chip is produced by SST and its name is "49LF004B". The BIOS Savior is produced by IOSS they provide a list to find the right RD1 Savior. As you can see on the picture on the right hand side the RD1 is a sandwich consisting of two chips. One is your original chip and one is an internal chip that comes together with the savior. Once your System is up and running you can choose between one or the other by using a dip switch. Some people on the mailing list reported problems with the quality of the internal flash part. Therefore, one would copy the original BIOS image to the internal flash part and then always (re)flash the original mainboard ROM chip. Of course you should have tested both options with the original BIOS before you really start your development. Please also read the FAQ regarding this topic.

There are also a lot of other tools that could be helpful, especially if you plan to join LB development. See here for more info.

Compiling the flashrom utility

Make sure the packages pciutils and pciutils-devel are installed on your machine.

Flashing the new image

Before you start flashing, you should use flashrom to save the original BIOS image.

$ ./flashrom -r orig.rom

Now switch your BIOS Savior to "RD1". If you don't have a BIOS Savior you can also use another ROM chip and replace the original one while the system is up and running (hot-swapping). ATTENTION: Changing hardware while system power is on often bares the risk of damaging something. We warned you! It is your risk!

Modifying LB tables with lxbios

After the first boot with LinuxBIOS, LB is saving information and configuration data in form of tables into CMOS/NVRAM. This data can be viewed and tweaked with a utility called lxbios.
Show all available parameters/data:

$ lxbios -a

Set a parameter to specific value. In this example set default boot to "normal" image.