The wiki is being retired!
Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
- 1 Use cases
- 2 Building
- 3 SeaBIOS and CBFS
- 3.1 Adding a VGA option ROM
- 3.2 Adding sgabios support
- 3.3 Adding a graphical "bootsplash" image
- 3.4 Adding gpxe support
- 3.5 Adding payloads
- 3.6 Adding a floppy image
- 3.7 Configuring boot order
- 3.8 Other Configuration items
- 3.9 File aliases
- 4 Trouble reporting
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.
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.
SeaBIOS has been tested with GRUB, LILO, and Syslinux. Linux booting works well.
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.
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:
$ make menuconfig $ make
Both SeaBIOS and coreboot will be built, and SeaBIOS will be added as payload to the coreboot.rom image that is being built.
One can download the latest version of SeaBIOS through a git repository:
$ git clone git://git.seabios.org/seabios.git seabios $ cd seabios
There's also a gitweb facility to browse the latest source code online.
Run make menuconfig and set the following variables:
- CONFIG_COREBOOT 1
- CONFIG_DEBUG_SERIAL 1
The final SeaBIOS payload file is out/bios.bin.elf.
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.
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 vgaroms/ as a VGA option ROM not specific to a device and files in genroms/ as a generic 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 vgaroms/sgabios.bin.lzma).
SeaBIOS can also load a graphical bootsplash image from bootsplash.jpg or bootsplash.bmp, payloads found in the CBFS directory img/, and floppy images found in the floppyimg/ directory.
Further, SeaBIOS can obtain configuration information from CBFS. A file bootorder determines the order of devices and methods to attempt to boot the system from. Additional configuration items may be found in the CBFS etc/ directory. It's also possible to create CBFS file aliases with the links file.
The examples below show some common uses of these 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:
$ lspci -vnn ... 01:00.0 VGA compatible controller : VIA Technologies, Inc. UniChrome Pro IGP ['''1106:3344'''] (rev 01) (prog-if 00 [VGA controller])
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:
$ ./build/cbfstool build/coreboot.rom add -f /path/to/vgabios.bin -n pci1106,3344.rom -t raw $ ./build/cbfstool build/coreboot.rom print
Alternatively, SeaBIOS supports LZMA compressed option ROMs. Use the following to add a compressed option ROM instead:
$ lzma -zc /path/to/vgabios.bin > vgabios.bin.lzma $ ./build/cbfstool build/coreboot.rom add -f vgabios.bin.lzma -n pci1106,3344.rom.lzma -t raw $ ./build/cbfstool build/coreboot.rom print
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.
Using coreboot VGA support
Coreboot can now initialize the GPU of some mainboards. After initializing the GPU, the information about it is passed to the payload.
SeaBIOS then provides a compatibility option rom that implements VGA compatibility. In "make menuconfig", it can be found under:
VGA ROM --->
Then in "VGA Hardware Type", select the following:
(X) coreboot linear framebuffer
Then making SeaBIOS use it is done in the same way than for sgabios
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 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:
$ ./build/cbfstool build/coreboot.rom add -f /path/to/sgabios.bin -n vgaroms/sgabios.bin -t raw $ ./build/cbfstool build/coreboot.rom print
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.
Adding a graphical "bootsplash" image
$ ./build/cbfstool build/coreboot.rom add -f /path/to/image.jpg -n bootsplash.jpg -t raw $ ./build/cbfstool build/coreboot.rom print
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:
$ lspci -vnn ... 00:09.0 Ethernet controller : Realtek Semiconductor Co., Ltd. RTL-8110SC/8169SC Gigabit Ethernet ['''10ec:8167'''] (rev 10)
Then one can build a gpxe option ROM. For example:
$ cd /path/to/gpxe/src/ $ make bin/10ec8167.rom
And add it to the coreboot image. For example:
$ ./build/cbfstool build/coreboot.rom add -f /path/to/gpxe/src/bin/10ec8167.rom -n pci10ec,8167.rom -t raw $ ./build/cbfstool build/coreboot.rom print
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.
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:
$ ./build/cbfstool build/coreboot.rom add-payload /path/to/payload.elf img/MyPayload l $ ./build/cbfstool build/coreboot.rom print
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.
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:
$ lzma -zc /path/to/myfloppy.img > myfloppy.img.lzma $ ./build/cbfstool build/coreboot.rom add -f myfloppy.img.lzma -n floppyimg/MyFloppy.lzma -t raw $ ./build/cbfstool build/coreboot.rom print
Both uncompressed and LZMA compressed images are supported. Several floppy formats are available: 360K, 1.2MB, 720K, 1.44MB, 2.88MB, 160K, 180K, 320K.
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:
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:
$ ./build/cbfstool build/coreboot.rom add -f mybootlist.txt -n bootorder -t raw $ ./build/cbfstool build/coreboot.rom print
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:
$ /path/to/seabios/scripts/encodeint.py boot-menu-wait 5500 $ ./build/cbfstool build/coreboot.rom add -f boot-menu-wait -n etc/boot-menu-wait -t raw $ ./build/cbfstool build/coreboot.rom print
The SeaBIOS tool scripts/encodeint.py will create a litte-endian encoded binary integer which can be placed into a CBFS file.
|show-boot-menu||Controls the display of the boot menu. Set to 0 to disable the boot menu.|
|boot-menu-message||Customize the text boot menu message. Normally, when in text mode SeaBIOS will report the string "\nPress F12 for boot menu.\n\n". This field allows the string to be changed. (This is a string field, not an integer field; don't use encodeint.py, just place the desired string into a file and add as above.)|
|boot-menu-key||Controls which key activates the boot menu. The value stored is the DOS scan code (eg, 0x86 for F12, 0x01 for Esc). If this field is set, be sure to also customize the boot-menu-message field above.|
|boot-menu-wait||Amount of time (in milliseconds) to wait at the boot menu prompt before selecting the default boot.|
|boot-fail-wait||If no boot devices are found SeaBIOS will reboot after 60 seconds. Set this to the amount of time (in milliseconds) to customize the reboot delay or set to -1 to disable rebooting when no boot devices are found|
|extra-pci-roots||If the target machine has multiple independent root buses set this to a positive value. The SeaBIOS PCI probe will then search for the given number of extra root buses.|
|ps2-keyboard-spinup||Some laptops that emulate PS2 keyboards don't respond to keyboard commands immediately after powering on. One may specify the amount of time (in milliseconds) here to allow as additional time for the keyboard to become responsive. When this field is set, SeaBIOS will repeatedly attempt to detect the keyboard until the keyboard is found or the specified timeout is reached.|
|optionroms-checksum||Option ROMs are required to have correct checksums. However, some option ROMs in the wild don't correctly follow the specifications and have bad checksums. Set this to a zero value to allow SeaBIOS to execute them anyways.|
|s3-resume-vga-init||Set this to a non-zero value to instruct SeaBIOS to run the vga rom on an S3 resume.|
|screen-and-debug||Set this to a zero value to instruct SeaBIOS to not write characters it sends to the screen to the debug ports. This can be useful when using sgabios.|
|advertise-serial-debug-port||If using a serial debug port, one can set this file to a zero value to prevent SeaBIOS from listing that serial port as available for operating system use. This can be useful when running old DOS programs that are known to reset the baud rate of all advertised serial ports.|
|floppy0||Set this to the type of the first floppy drive in the system (only type 4 for 3.5 inch drives is supported).|
|floppy1||The type of the second floppy drive in the system. See the description of floppy0 for more info.|
|threads||By default, SeaBIOS will parallelize hardware initialization during bootup to reduce boot time. Multiple hardware devices can be initialized in parallel between vga initialization and option rom initialization. One can set this file to a value of zero to force hardware initialization to run serially. Alternatively, one can set this file to 2 to enable early hardware initialization that runs in parallel with vga, option rom initialization, and the boot menu.|
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:
$ ./build/cbfstool build/coreboot.rom add -f links -n links -t raw $ ./build/cbfstool build/coreboot.rom print
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".
If you are experiencing problems with SeaBIOS, it's useful to increase the debugging level. This is done by running make menuconfig and setting CONFIG_DEBUG_LEVEL to a higher value. A debug level of 8 will show a lot of diagnostic information without flooding the serial port (levels above 8 will frequently cause too much data).
To report an issue, please collect the serial boot log with SeaBIOS set to a debug level of 8 and forward the full log along with a description of the problem to the coreboot mailing list.