SeaBIOS: Difference between revisions

From coreboot
Jump to navigation Jump to search
 
(93 intermediate revisions by 11 users not shown)
Line 1: Line 1:
'''SeaBIOS''' (previously known as '''LegacyBIOS''') is an open-source legacy BIOS implementation, which can also be used as coreboot [[Payloads|payload]].
[http://seabios.org '''SeaBIOS'''] is an open-source legacy BIOS implementation which can be used as a coreboot [[Payloads|payload]]. It implements the standard [https://secure.wikimedia.org/wikipedia/en/wiki/BIOS BIOS] calling interfaces that a typical x86 proprietary BIOS implements.
 
This page describes using SeaBIOS with coreboot. SeaBIOS can also run natively in [[QEMU]] and [http://bochs.sourceforge.net/ bochs] — see the [http://seabios.org SeaBIOS website] for information on non-coreboot uses.


= Use cases =
= Use cases =


Any software requiring 16-bit BIOS services benefits from SeaBIOS.
Any software requiring 16-bit BIOS services benefits from SeaBIOS (eg, Windows and DOS). SeaBIOS also enables booting Linux out of the box (using standard boot-loaders like GRUB and Syslinux).


== Windows XP ==
SeaBIOS supports booting from ATA hard drives, ATAPI CDROMs, USB hard drives, USB CDROMs, payloads in flash, and from [http://en.wikipedia.org/wiki/Option_ROM Option ROMs] (eg, SCSI or network cards). SeaBIOS can initialize and use a PS/2 keyboard or USB keyboard.


Windows XP has been booted on real hardware with coreboot and SeaBIOS. Some patches are required.
== Windows ==


== Windows Vista ==
SeaBIOS has been tested with Windows XP, Windows 2008, Windows Vista (64/32 bit), Windows 7 (32 bit and 64 bit).


Windows Vista (64/32 bit) has been booted on real hardware with coreboot and SeaBIOS. Some patches are required.
However, Windows has a very strict ACPI interpreter, and some coreboot boards do not have a complete [[ACPI|ACPI definition]]. As a result, some coreboot boards may fail during Windows boot (eg, it may fail with a '''STOP 0xA5''' code).


== Windows 7 Beta ==
Many boards do have working ACPI and are able to boot XP/Vista/Windows 7. Please check the board documentation or ask on the [[Mailinglist|mailing list]] if unsure of the status.


Windows 7 Beta (64 bit) has been booted on real hardware with coreboot and SeaBIOS. Some patches required.
== Linux ==


== GRUB ==
SeaBIOS has been tested with GRUB, LILO, and Syslinux. Linux booting works well.


GRUB works with coreboot and SeaBIOS on real hardware and boots Linux just fine.
== Other ==
 
SeaBIOS has also been tested with FreeDOS, NetBSD, and OpenBSD.
 
Because SeaBIOS implements the standard x86 BIOS interfaces, it is expected many other operating systems and boot-loaders will work.


= Building =
= Building =


== SeaBIOS ==
== Building via coreboot's menuconfig ==
 
Probably the easiest way to use SeaBIOS as coreboot payload is to simply use the coreboot build process, which downloads and builds SeaBIOS as payload by default nowadays. You just have to run the following in your coreboot checkout:
 
<source lang="bash">
$ make menuconfig
$ make
</source>
 
Both SeaBIOS and coreboot will be built, and SeaBIOS will be added as payload to the '''coreboot.rom''' image that is being built.
 
== Manual build ==


You can download the latest version of SeaBIOS through a git repository:
One can download the latest version of SeaBIOS through a git repository:


<source lang="bash">
<source lang="bash">
$ git clone git://git.linuxtogo.org/home/kevin/seabios.git seabios
$ git clone git://git.seabios.org/seabios.git seabios
$ cd seabios
$ cd seabios
</source>
</source>


Alternatively, the released versions of SeaBIOS can be found at http://linuxtogo.org/~kevin/SeaBIOS/. There's also a [http://git.linuxtogo.org/?p=kevin/seabios.git;a=summary gitweb] facility to browse the latest source code online.
There's also a [https://review.coreboot.org/gitweb/cgit/seabios.git/ cgit] facility to browse the latest source code online.


Edit '''src/config.h''' and set the following values:
Run '''make menuconfig''' and set the following variables:


<source lang="C">
* CONFIG_COREBOOT 1
#define CONFIG_COREBOOT 1
* CONFIG_DEBUG_SERIAL 1
#define CONFIG_DEBUG_SERIAL 1
#define CONFIG_OPTIONROMS_DEPLOYED 0
#define CONFIG_COREBOOT_FLASH 1
#define CONFIG_VGAHOOKS 1
</source>


Then:
Then:
Line 50: Line 62:
</source>
</source>


The final SeaBIOS payload file is '''out/bios.bin.elf''', which can be used with coreboot v2 or v3.
The final SeaBIOS payload file is '''out/bios.bin.elf'''.


== coreboot ==
== coreboot ==


For best results, use coreboot-v2 and edit the target Config.lb with the following:
Configure coreboot with the following all disabled: '''CONFIG_VGA_ROM_RUN''', '''CONFIG_PCI_ROM_RUN''', '''CONFIG_ON_DEVICE_ROM_RUN'''


option CONFIG_CBFS=1
Then configure the SeaBIOS '''out/bios.bin.elf''' file as the coreboot payload and build coreboot. The resulting '''coreboot.rom''' file will contain both SeaBIOS and coreboot, and it can be flashed to a ROM chip.
option HAVE_HIGH_TABLES=1
...
romimage "fallback"
...
payload /path/to/seabios/out/bios.bin.elf
end


Unfortunately, many boards don't have HAVE_HIGH_TABLES support yet.  If the build fails complaining about this option, one can edit the src/mainboard/<vendor>/<board>/Options.lb file and add a "uses HAVE_HIGH_TABLES" line.  Then one can edit src/arch/i386/boot/tables.c and change the lines:
= SeaBIOS and CBFS =


<source lang="C">
SeaBIOS can read the coreboot flash filesystem and extract files. Details on the CBFS files that SeaBIOS supports are on the [http://seabios.org/Runtime_config SeaBIOS wiki].
uint64_t high_tables_base = 0;
 
uint64_t high_tables_size;
The following examples show some commonly used features.
 
== Adding a VGA option ROM ==
 
It is frequently necessary to add a VGA option ROM to CBFS in order to use a VGA adapter that is built-in to a motherboard. Note, VGA adapters on external cards (PCI, AGP, PCIe) do not require this step as SeaBIOS will automatically extract the VGA BIOS directly from the card. For machines without a VGA adapter, please follow the [[#Adding sgabios support|sgabios instructions]] below.
 
=== Using your BIOS's VGA option rom ===
The first step is to find the vendor and device ID of the built-in VGA adapter. This information can be found from '''lspci''':
 
<source lang="bash">
$ lspci -vnn
...
01:00.0 VGA compatible controller [0300]: VIA Technologies, Inc. UniChrome Pro IGP ['''1106:3344'''] (rev 01) (prog-if 00 [VGA controller])
</source>
</source>


to:
In the above example, the VGA vendor/device ID is '''1106:3344'''. [[VGA support#How_to_retrieve_a_good_video_bios|Obtain the VGA ROM]] (eg, '''vgabios.bin''') and add it to the ROM with:


<source lang="C">
<source lang="bash">
uint64_t high_tables_base = ( <memorysize> )*1024*1024 - (64*1024);
$ ./build/cbfstool build/coreboot.rom add -f /path/to/vgabios.bin -n pci1106,3344.rom -t optionrom
uint64_t high_tables_size = 64*1024;
$ ./build/cbfstool build/coreboot.rom print
</source>
</source>


where <memorysize> is the amount of memory (in MiB) available on the target machine, but not more than 3072. So, if you have more than 3GiB of ram installed, put 3072. Otherwise, put the number of MiB of ram installed in your machine.
Alternatively, SeaBIOS supports LZMA compressed option ROMs. Use the following to add a compressed option ROM instead:


Alternatively, one can add proper support for HAVE_HIGH_TABLES.
<source lang="bash">
$ ./build/cbfstool build/coreboot.rom add -f /path/to/vgabios.bin -c lzma -n pci1106,3344.rom.lzma -t optionrom
$ ./build/cbfstool build/coreboot.rom print
</source>


Once the above is done, the final image will be in '''coreboot.rom'''.
After the above is done, one can write the '''coreboot.rom''' file to flash. SeaBIOS will extract the VGA ROM and run it during boot.


= SeaBIOS and CBFS =
=== Adding sgabios support ===
 
An [http://code.google.com/p/sgabios/ sgabios] option ROM can forward many VGA BIOS requests and keyboard events over a serial port. One can deploy it in addition to the primary VGA BIOS or by itself.


SeaBIOS can read the coreboot flash filesystem and extract option roms and payloads.
If the target machine does not have a VGA adapter, then one should install sgabios. Most bootloaders (eg, GRUB) require a VGA BIOS in order to function properly &mdash; the sgabios ROM can fill this requirement.


When SeaBIOS scans the target machine's PCI devices, it will recognize option roms in CBFS that have the form "pciVVVV,DDDD.rom".  It will also run any file in the directory "genroms/" as an option rom not specific to a device.  In the above cases, SeaBIOS will recognize files with a ".lzma" suffix, and automatically decompress them (eg, "pci1106,3344.rom.lzma" and "genroms/sgabios.bin.lzma").
Place the sgabios ROM file in the '''vgaroms/''' directory of CBFS. For example:


SeaBIOS will also load payloads found in the CBFS directory "img/".
<source lang="bash">
$ ./build/cbfstool build/coreboot.rom add -f /path/to/sgabios.bin -n vgaroms/sgabios.bin -t raw
$ ./build/cbfstool build/coreboot.rom print
</source>


The examples below show some common uses of this feature.
When using sgabios, all the characters that SeaBIOS writes to the screen will be seen twice &mdash; once from SeaBIOS sending the character to the serial port and once from sgabios forwarding the character. To prevent the duplicates set the [[#Other Configuration items|config file]] '''etc/screen-and-debug''' to zero. This could be done like that:
<source lang="bash">
$ ./build/cbfstool build/coreboot.rom add-int -i 0 -n etc/screen-and-debug
</source>


== Adding a VGA option rom ==
=== Using coreboot VGA support ===
Coreboot can initialize the GPU of some mainboards. After initializing the GPU, the information about it is passed to the payload.


It is frequently necessary to add a vga option rom for built-in VGA adapters so that they are properly initialized.
SeaBIOS can provide an option rom that implements legacy VGA BIOS compatibility for coreboot initialized GPUs.  To use this feature select '''CONFIG_VGA_COREBOOT''' (in "make menuconfig" under "VGA ROM  ---> VGA Hardware Type" select "coreboot linear framebuffer").


The first step is to find the vendor and device id of the VGA adapter.  This information can be found from '''lspci''':
The resulting option rom '''out/vgabios.rom''' should be added to the '''vgaroms/''' directory of CBFS. For example:


<source lang="bash">
<source lang="bash">
$ lspci -vnn
$ ./build/cbfstool build/coreboot.rom add -f /path/to/seabios/out/vgabios.bin -n vgaroms/seavgabios.bin -t raw
...
$ ./build/cbfstool build/coreboot.rom print
01:00.0 VGA compatible controller [0300]: VIA Technologies, Inc. UniChrome Pro IGP [1106:3344] (rev 01) (prog-if 00 [VGA controller])
</source>
</source>


In the above example, the VGA vendor/deviceid is "1106:3344". [[VGA_support#How_to_retrieve_a_good_video_bios|Obtain the vga rom]] (eg, vgabios.bin) and add it to the rom with:
One should note that many bootloaders expect some vbios functionality which this vgabios does not provide.
To overcome this issue one can use a bootloader not requiring this functionality. For instance grub works fine if configured in textmode. To achieve this comment out or add to /etc/default/grub:
 
  GRUB_TERMINAL_OUTPUT=console
 
and regenerate the grub configuration:


<source lang="bash">
<source lang="bash">
$ ./cbfstool coreboot.rom add /path/to/vgabios.bin pci1106,3344.rom 0
grub-mkconfig -o /boot/grub/grub.cfg
$ ./cbfstool coreboot.rom print
</source>
</source>


Alternatively, SeaBIOS supports lzma compressed option roms. Use the following to add a compressed option rom instead:
=== Geode option roms ===
There are two VGA option roms for geode in SeaBIOS, they can be found in "VGA ROM  --->" in "make menuconfig":
 
* The first one is for the Geode LX, its named "GeodeLX" in "make menuconfig"
* The second one if for the Geode GX2, its named "Geode GX2" in "make menuconfig"
 
== Adding a graphical "bootsplash" image ==
 
SeaBIOS can show a custom [http://en.wikipedia.org/wiki/JPEG JPEG] image or [http://en.wikipedia.org/wiki/BMP_file_format BMP] image during bootup. To enable this, add the JPEG file to flash with the name '''bootsplash.jpg''' or BMP file as '''bootsplash.bmp'''. For example:


<source lang="bash">
<source lang="bash">
$ lzma -zc /path/to/vgabios.bin > vgabios.bin.lzma
$ ./build/cbfstool build/coreboot.rom add -f /path/to/image.jpg -n bootsplash.jpg -t raw
$ ./cbfstool coreboot.rom add vgabios.bin.lzma pci1106,3344.rom.lzma 0
$ ./build/cbfstool build/coreboot.rom print
$ ./cbfstool coreboot.rom print
</source>
</source>


After the above is done, one can write the coreboot.rom file to flash. SeaBIOS will extract the vga rom and run it during boot.
The size of the image determines the video mode to use for showing the image. Make sure the dimensions of the image exactly correspond to an available video mode (eg, 640x480, or 1024x768), otherwise it will not be displayed.
 
SeaBIOS will show the image during the wait for the boot menu (if the boot menu has been disabled, users will not see the image). The image should probably have "Press F12 for boot menu" embedded in it so users know they can enter the normal SeaBIOS boot menu. By default, the boot menu prompt (and thus graphical image) is shown for 2.5 seconds. This can be customized via a [[#Other Configuration items|configuration parameter]].
 
The JPEG viewer in SeaBIOS uses a simplified decoding algorithm. It supports most common JPEGs, but does not support all possible formats. Please see the [[#Trouble reporting|Trouble reporting]] section if a valid image isn't displayed properly.


== Adding gpxe support ==
== Adding gpxe support ==


A [[http://www.etherboot.org/ gpxe]] option rom can nicely complement SeaBIOS and coreboot by adding network boot support. Adding gpxe is similar to [[#Adding a VGA option rom]]. The first step is to find the ethernet vendor/device id. For example:
A [[GPXE|gpxe]] option ROM can nicely complement SeaBIOS and coreboot by adding network boot support. Adding gpxe is similar to [[#Adding a VGA option ROM]]. The first step is to find the Ethernet vendor/device ID. For example:


<source lang="bash">
<source lang="bash">
$ lspci -vnn
$ lspci -vnn
...
...
00:09.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL-8110SC/8169SC Gigabit Ethernet [10ec:8167] (rev 10)
00:09.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL-8110SC/8169SC Gigabit Ethernet ['''10ec:8167'''] (rev 10)
</source>
</source>


Then one can build a gpxe option rom. For example:
Then one can build a gpxe option ROM. For example:


<source lang="bash">
<source lang="bash">
Line 140: Line 184:
</source>
</source>


And add it to the coreboot image. For example:
And add it to the coreboot image. For example:
 
<source lang="bash">
$ ./build/cbfstool build/coreboot.rom add -f /path/to/gpxe/src/bin/10ec8167.rom -n pci10ec,8167.rom -t optionrom
$ ./build/cbfstool build/coreboot.rom print
</source>
 
As with VGA option ROMs, the gpxe option ROM may be compressed with LZMA. However, compression won't significantly reduce gpxe's size as it implements its own compression.
 
In addition to gpxe, other option ROMs can be added in the same manner.
 
== Adding payloads ==
 
Most [[Payloads|payloads]] can also be launched from SeaBIOS. To add a payload, build the corresponding .elf file and then add it to the '''coreboot.rom''' file in the '''img/''' directory. For example:


<source lang="bash">
<source lang="bash">
$ ./cbfstool coreboot.rom add /path/to/gpxe/src/bin/10ec8167.rom pci10ec,8167.rom 0
$ ./build/cbfstool build/coreboot.rom add-payload -f /path/to/payload.elf -n img/MyPayload
$ ./cbfstool coreboot.rom print
$ ./build/cbfstool build/coreboot.rom print
</source>
</source>


As with VGA option roms, the gpxe option rom may be compressed with lzma. However, compression wont significantly reduce gpxe's size as it implements its own compression.
During boot, one can press the '''ESC''' key to get a boot menu. SeaBIOS will show all files in the '''img/''' directory, and one can instruct SeaBIOS to run them.


In addition to gpxe, other option roms can be added in the same manor.
SeaBIOS supports both uncompressed and LZMA compressed payloads.


== Adding sgabios support ==
== Adding a floppy image ==


An [[http://code.google.com/p/sgabios/ sgabios]] option rom can forward some vga bios requests over a serial port. To use sgabios, place its rom file in the "genroms/" directory of CBFS. For example:
It is possible to embed an image of a floppy in flash. SeaBIOS can then boot from and redirect floppy BIOS calls to the flash image. This is mainly useful for legacy software (such as DOS utilities). To use this feature, place a floppy image into the CBFS directory '''floppyimg/'''. For example:


<source lang="bash">
<source lang="bash">
$ ./cbfstool coreboot.rom add /path/to/sgabios.bin genroms/sgabios.bin 0
$ ./build/cbfstool build/coreboot.rom add -f /path/to/myfloppy.img -c lzma -n floppyimg/MyFloppy.lzma -t raw
$ ./cbfstool coreboot.rom print
$ ./build/cbfstool build/coreboot.rom print
</source>
</source>


== Adding payloads ==
Both uncompressed and LZMA compressed images are supported. Several floppy formats are available: 360K, 1.2MB, 720K, 1.44MB, 2.88MB, 160K, 180K, 320K. SeaBIOS expects the uncompressed images size to be equal to the ones just mentioned. Else, given enough debug, it will complain with: "No floppy type found for ramdisk size".
 
The floppy image will appear as writable to the system, however all writes are discarded on reboot.
 
When using this system, SeaBIOS reserves high-memory to store the floppy. The reserved memory is then no longer available for OS use, so this feature should only be used when needed.
 
== Configuring boot order ==
 
Place a file in CBFS with the name '''bootorder''' to configure the boot up order. The file should be ASCII text and contain one line per boot method. The description of each boot method follows an [https://secure.wikimedia.org/wikipedia/en/wiki/Open_firmware Open Firmware] device path format. SeaBIOS will attempt to boot from each item in the file &mdash; first line of the file first.
 
The easiest way to find the available boot methods is to look for "Searching bootorder for" in the SeaBIOS serial output. For example, one may see lines similar to:
 
Searching bootorder for: /pci@i0cf8/*@f/drive@1/disk@0
Searching bootorder for: /pci@i0cf8/*@f,1/drive@2/disk@1
Searching bootorder for: /pci@i0cf8/usb@10,4/*@2
 
The above represents the patterns SeaBIOS will search for in the bootorder file. However, it's safe to just copy and paste the pattern into bootorder. For example, the file:
 
/pci@i0cf8/usb@10,4/*@2
/pci@i0cf8/*@f/drive@1/disk@0
 
will instruct SeaBIOS to attempt to boot from the given USB drive first and then attempt the given ATA harddrive second.
 
Once a file has been created, add it to CBFS with the name '''bootorder'''. For example:
 
<source lang="bash">
$ ./build/cbfstool build/coreboot.rom add -f mybootlist.txt -n bootorder -t raw
$ ./build/cbfstool build/coreboot.rom print
</source>
 
== Other Configuration items ==
 
Additional configuration options are available in the CBFS '''etc/''' directory.  For example, to set the duration of the boot menu to five and a half seconds, one would do the following:
 
<source lang="bash">
$ ./build/cbfstool build/coreboot.rom add-int -i 5500 -n etc/boot-menu-wait
$ ./build/cbfstool build/coreboot.rom print
</source>
 
The cbfstool "add-int" command will create a litte-endian encoded binary integer and place it into the specified CBFS file.
 
See the [http://seabios.org/Runtime_config SeaBIOS wiki] for details on available options.
 
== File aliases ==
 
It is possible to create the equivalent of "symbolic links" in CBFS so that one file's content appears under another name.  To do this, create a links file with one line per link and each line having the format of "linkname" and "destname" separated by a space character.  For example, the "links" file may look like:
 
pci1234,1000.rom somerom.rom
pci1234,1001.rom somerom.rom
pci1234,1002.rom somerom.rom


Most [[Payloads|payloads]] can also be launched from SeaBIOS.  To add a payload, build the corresponding .elf file and then add it to the '''coreboot.rom''' file in the "img/" directory.  For example:
Then add the "links" file to CBFS:


<source lang="bash">
<source lang="bash">
$ ./cbfstool coreboot.rom add-payload /path/to/payload.elf img/MyPayload l
$ ./build/cbfstool build/coreboot.rom add -f links -n links -t raw
$ ./cbfstool coreboot.rom print
$ ./build/cbfstool build/coreboot.rom print
</source>
</source>


During boot, one can press the F12 key to get a boot menu. SeaBIOS will show all files in the "img/" directory, and one can instruct SeaBIOS to run them.
The above example would cause SeaBIOS to treat "pci1234,1000.rom" or "pci1234,1001.rom" as files with the same content as the file "somerom.rom".
 
= Trouble reporting =


Note, SeaBIOS currently supports uncompressed and lzma compressed payloads.  The nrv2b compression algorithm is not supported.
If you are experiencing problems with SeaBIOS, please follow the directions on the [http://seabios.org/Debugging SeaBIOS wiki] to report the issue.

Latest revision as of 12:50, 10 May 2018

SeaBIOS is an open-source legacy BIOS implementation which can be used as a coreboot payload. It implements the standard BIOS calling interfaces that a typical x86 proprietary BIOS implements.

This page describes using SeaBIOS with coreboot. SeaBIOS can also run natively in QEMU and bochs — see the SeaBIOS website for information on non-coreboot uses.

Use cases

Any software requiring 16-bit BIOS services benefits from SeaBIOS (eg, Windows and DOS). SeaBIOS also enables booting Linux out of the box (using standard boot-loaders like GRUB and Syslinux).

SeaBIOS supports booting from ATA hard drives, ATAPI CDROMs, USB hard drives, USB CDROMs, payloads in flash, and from Option ROMs (eg, SCSI or network cards). SeaBIOS can initialize and use a PS/2 keyboard or USB keyboard.

Windows

SeaBIOS has been tested with Windows XP, Windows 2008, Windows Vista (64/32 bit), Windows 7 (32 bit and 64 bit).

However, Windows has a very strict ACPI interpreter, and some coreboot boards do not have a complete ACPI definition. As a result, some coreboot boards may fail during Windows boot (eg, it may fail with a STOP 0xA5 code).

Many boards do have working ACPI and are able to boot XP/Vista/Windows 7. Please check the board documentation or ask on the mailing list if unsure of the status.

Linux

SeaBIOS has been tested with GRUB, LILO, and Syslinux. Linux booting works well.

Other

SeaBIOS has also been tested with FreeDOS, NetBSD, and OpenBSD.

Because SeaBIOS implements the standard x86 BIOS interfaces, it is expected many other operating systems and boot-loaders will work.

Building

Building via coreboot's menuconfig

Probably the easiest way to use SeaBIOS as coreboot payload is to simply use the coreboot build process, which downloads and builds SeaBIOS as payload by default nowadays. You just have to run the following in your coreboot checkout:

<source lang="bash"> $ make menuconfig $ make </source>

Both SeaBIOS and coreboot will be built, and SeaBIOS will be added as payload to the coreboot.rom image that is being built.

Manual build

One can download the latest version of SeaBIOS through a git repository:

<source lang="bash"> $ git clone git://git.seabios.org/seabios.git seabios $ cd seabios </source>

There's also a cgit facility to browse the latest source code online.

Run make menuconfig and set the following variables:

  • CONFIG_COREBOOT 1
  • CONFIG_DEBUG_SERIAL 1

Then:

<source lang="bash"> $ make </source>

The final SeaBIOS payload file is out/bios.bin.elf.

coreboot

Configure coreboot with the following all disabled: CONFIG_VGA_ROM_RUN, CONFIG_PCI_ROM_RUN, CONFIG_ON_DEVICE_ROM_RUN

Then configure the SeaBIOS out/bios.bin.elf file as the coreboot payload and build coreboot. The resulting coreboot.rom file will contain both SeaBIOS and coreboot, and it can be flashed to a ROM chip.

SeaBIOS and CBFS

SeaBIOS can read the coreboot flash filesystem and extract files. Details on the CBFS files that SeaBIOS supports are on the SeaBIOS wiki.

The following examples show some commonly used features.

Adding a VGA option ROM

It is frequently necessary to add a VGA option ROM to CBFS in order to use a VGA adapter that is built-in to a motherboard. Note, VGA adapters on external cards (PCI, AGP, PCIe) do not require this step as SeaBIOS will automatically extract the VGA BIOS directly from the card. For machines without a VGA adapter, please follow the sgabios instructions below.

Using your BIOS's VGA option rom

The first step is to find the vendor and device ID of the built-in VGA adapter. This information can be found from lspci:

<source lang="bash"> $ lspci -vnn ... 01:00.0 VGA compatible controller [0300]: VIA Technologies, Inc. UniChrome Pro IGP [1106:3344] (rev 01) (prog-if 00 [VGA controller]) </source>

In the above example, the VGA vendor/device ID is 1106:3344. Obtain the VGA ROM (eg, vgabios.bin) and add it to the ROM with:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/vgabios.bin -n pci1106,3344.rom -t optionrom $ ./build/cbfstool build/coreboot.rom print </source>

Alternatively, SeaBIOS supports LZMA compressed option ROMs. Use the following to add a compressed option ROM instead:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/vgabios.bin -c lzma -n pci1106,3344.rom.lzma -t optionrom $ ./build/cbfstool build/coreboot.rom print </source>

After the above is done, one can write the coreboot.rom file to flash. SeaBIOS will extract the VGA ROM and run it during boot.

Adding sgabios support

An sgabios option ROM can forward many VGA BIOS requests and keyboard events over a serial port. One can deploy it in addition to the primary VGA BIOS or by itself.

If the target machine does not have a VGA adapter, then one should install sgabios. Most bootloaders (eg, GRUB) require a VGA BIOS in order to function properly — the sgabios ROM can fill this requirement.

Place the sgabios ROM file in the vgaroms/ directory of CBFS. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/sgabios.bin -n vgaroms/sgabios.bin -t raw $ ./build/cbfstool build/coreboot.rom print </source>

When using sgabios, all the characters that SeaBIOS writes to the screen will be seen twice — once from SeaBIOS sending the character to the serial port and once from sgabios forwarding the character. To prevent the duplicates set the config file etc/screen-and-debug to zero. This could be done like that: <source lang="bash"> $ ./build/cbfstool build/coreboot.rom add-int -i 0 -n etc/screen-and-debug </source>

Using coreboot VGA support

Coreboot can initialize the GPU of some mainboards. After initializing the GPU, the information about it is passed to the payload.

SeaBIOS can provide an option rom that implements legacy VGA BIOS compatibility for coreboot initialized GPUs. To use this feature select CONFIG_VGA_COREBOOT (in "make menuconfig" under "VGA ROM ---> VGA Hardware Type" select "coreboot linear framebuffer").

The resulting option rom out/vgabios.rom should be added to the vgaroms/ directory of CBFS. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/seabios/out/vgabios.bin -n vgaroms/seavgabios.bin -t raw $ ./build/cbfstool build/coreboot.rom print </source>

One should note that many bootloaders expect some vbios functionality which this vgabios does not provide. To overcome this issue one can use a bootloader not requiring this functionality. For instance grub works fine if configured in textmode. To achieve this comment out or add to /etc/default/grub: 

GRUB_TERMINAL_OUTPUT=console

and regenerate the grub configuration:

<source lang="bash"> grub-mkconfig -o /boot/grub/grub.cfg </source>

Geode option roms

There are two VGA option roms for geode in SeaBIOS, they can be found in "VGA ROM --->" in "make menuconfig":

  • The first one is for the Geode LX, its named "GeodeLX" in "make menuconfig"
  • The second one if for the Geode GX2, its named "Geode GX2" in "make menuconfig"

Adding a graphical "bootsplash" image

SeaBIOS can show a custom JPEG image or BMP image during bootup. To enable this, add the JPEG file to flash with the name bootsplash.jpg or BMP file as bootsplash.bmp. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/image.jpg -n bootsplash.jpg -t raw $ ./build/cbfstool build/coreboot.rom print </source>

The size of the image determines the video mode to use for showing the image. Make sure the dimensions of the image exactly correspond to an available video mode (eg, 640x480, or 1024x768), otherwise it will not be displayed.

SeaBIOS will show the image during the wait for the boot menu (if the boot menu has been disabled, users will not see the image). The image should probably have "Press F12 for boot menu" embedded in it so users know they can enter the normal SeaBIOS boot menu. By default, the boot menu prompt (and thus graphical image) is shown for 2.5 seconds. This can be customized via a configuration parameter.

The JPEG viewer in SeaBIOS uses a simplified decoding algorithm. It supports most common JPEGs, but does not support all possible formats. Please see the Trouble reporting section if a valid image isn't displayed properly.

Adding gpxe support

A gpxe option ROM can nicely complement SeaBIOS and coreboot by adding network boot support. Adding gpxe is similar to #Adding a VGA option ROM. The first step is to find the Ethernet vendor/device ID. For example:

<source lang="bash"> $ lspci -vnn ... 00:09.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL-8110SC/8169SC Gigabit Ethernet [10ec:8167] (rev 10) </source>

Then one can build a gpxe option ROM. For example:

<source lang="bash"> $ cd /path/to/gpxe/src/ $ make bin/10ec8167.rom </source>

And add it to the coreboot image. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/gpxe/src/bin/10ec8167.rom -n pci10ec,8167.rom -t optionrom $ ./build/cbfstool build/coreboot.rom print </source>

As with VGA option ROMs, the gpxe option ROM may be compressed with LZMA. However, compression won't significantly reduce gpxe's size as it implements its own compression.

In addition to gpxe, other option ROMs can be added in the same manner.

Adding payloads

Most payloads can also be launched from SeaBIOS. To add a payload, build the corresponding .elf file and then add it to the coreboot.rom file in the img/ directory. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add-payload -f /path/to/payload.elf -n img/MyPayload $ ./build/cbfstool build/coreboot.rom print </source>

During boot, one can press the ESC key to get a boot menu. SeaBIOS will show all files in the img/ directory, and one can instruct SeaBIOS to run them.

SeaBIOS supports both uncompressed and LZMA compressed payloads.

Adding a floppy image

It is possible to embed an image of a floppy in flash. SeaBIOS can then boot from and redirect floppy BIOS calls to the flash image. This is mainly useful for legacy software (such as DOS utilities). To use this feature, place a floppy image into the CBFS directory floppyimg/. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f /path/to/myfloppy.img -c lzma -n floppyimg/MyFloppy.lzma -t raw $ ./build/cbfstool build/coreboot.rom print </source>

Both uncompressed and LZMA compressed images are supported. Several floppy formats are available: 360K, 1.2MB, 720K, 1.44MB, 2.88MB, 160K, 180K, 320K. SeaBIOS expects the uncompressed images size to be equal to the ones just mentioned. Else, given enough debug, it will complain with: "No floppy type found for ramdisk size".

The floppy image will appear as writable to the system, however all writes are discarded on reboot.

When using this system, SeaBIOS reserves high-memory to store the floppy. The reserved memory is then no longer available for OS use, so this feature should only be used when needed.

Configuring boot order

Place a file in CBFS with the name bootorder to configure the boot up order. The file should be ASCII text and contain one line per boot method. The description of each boot method follows an Open Firmware device path format. SeaBIOS will attempt to boot from each item in the file — first line of the file first.

The easiest way to find the available boot methods is to look for "Searching bootorder for" in the SeaBIOS serial output. For example, one may see lines similar to: 

Searching bootorder for: /pci@i0cf8/*@f/drive@1/disk@0
Searching bootorder for: /pci@i0cf8/*@f,1/drive@2/disk@1
Searching bootorder for: /pci@i0cf8/usb@10,4/*@2

The above represents the patterns SeaBIOS will search for in the bootorder file. However, it's safe to just copy and paste the pattern into bootorder. For example, the file: 

/pci@i0cf8/usb@10,4/*@2
/pci@i0cf8/*@f/drive@1/disk@0

will instruct SeaBIOS to attempt to boot from the given USB drive first and then attempt the given ATA harddrive second.

Once a file has been created, add it to CBFS with the name bootorder. For example:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f mybootlist.txt -n bootorder -t raw $ ./build/cbfstool build/coreboot.rom print </source>

Other Configuration items

Additional configuration options are available in the CBFS etc/ directory. For example, to set the duration of the boot menu to five and a half seconds, one would do the following:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add-int -i 5500 -n etc/boot-menu-wait $ ./build/cbfstool build/coreboot.rom print </source>

The cbfstool "add-int" command will create a litte-endian encoded binary integer and place it into the specified CBFS file.

See the SeaBIOS wiki for details on available options.

File aliases

It is possible to create the equivalent of "symbolic links" in CBFS so that one file's content appears under another name. To do this, create a links file with one line per link and each line having the format of "linkname" and "destname" separated by a space character. For example, the "links" file may look like: 

pci1234,1000.rom somerom.rom
pci1234,1001.rom somerom.rom
pci1234,1002.rom somerom.rom

Then add the "links" file to CBFS:

<source lang="bash"> $ ./build/cbfstool build/coreboot.rom add -f links -n links -t raw $ ./build/cbfstool build/coreboot.rom print </source>

The above example would cause SeaBIOS to treat "pci1234,1000.rom" or "pci1234,1001.rom" as files with the same content as the file "somerom.rom".

Trouble reporting

If you are experiencing problems with SeaBIOS, please follow the directions on the SeaBIOS wiki to report the issue.

Retrieved from "https://www.coreboot.org/index.php?title=SeaBIOS&oldid=34839"