Build overview: Difference between revisions

From SeaBIOS
Jump to navigation Jump to search
(Page with info on compiling and running SeaBIOS)
 
(Minor - replace seavgabios text in Build_overview.md with link)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
The SeaBIOS code can be built using standard GNU tools. A recent Linux distribution should be able to build SeaBIOS using the standard compiler tools.
The SeaBIOS code can be built using standard GNU tools. A recent Linux distribution should be able to build SeaBIOS using the standard compiler tools.


= Quick start =
= Building SeaBIOS =


For QEMU and KVM users, [[Download|obtain the code]] and run '''make'''.  The resulting binary image will be located in '''out/bios.bin'''.  For coreboot users, please see the [http://www.coreboot.org/SeaBIOS coreboot SeaBIOS page].
First, [[Download|obtain the code]]. SeaBIOS can be compiled for several different build targets. It is also possible to configure additional compile time options - run '''make menuconfig''' to do this.


It is possible to configure additional compile time options - run '''make menuconfig''' to do this.
== Build for QEMU (along with KVM, Xen, and Bochs) ==


= Testing images on QEMU =
To build for QEMU (and similar), one should be able to run "make" in the main directory. The resulting file "out/bios.bin" contains the processed bios image.


To test under QEMU, one will need to create a directory with all the bios images and then overwrite the main bios image. For example:
One can use the resulting binary with QEMU by using QEMU's "-bios" option. For example:


cp /usr/share/qemu/*.bin mybiosdir/
<code>qemu -bios out/bios.bin -fda myfdimage.img</code>
cp out/bios.bin mybiosdir/


Once this is setup, one can instruct QEMU to use the newly created directory for rom images. For example:
One can also use the resulting binary with Bochs. For example:


qemu -L mybiosdir/ -fda myfdimage.img
<code>bochs -q 'floppya: 1_44=myfdimage.img' 'romimage: file=out/bios.bin'</code>


For best results, please use QEMU version 0.12.0 or later.
== Build for coreboot ==


= Testing images on Bochs =
To build for coreboot please see the coreboot build instructions at: http://www.coreboot.org/SeaBIOS


To test the bios under bochs, some config option changs are needed. Run '''make menuconfig''', set '''CONFIG_OPTIONROMS_DEPLOYED''', and unset '''CONFIG_MTRR_INIT'''.  Then one can run Bochs with the resulting bios.bin file - for example:
== Build as a UEFI Compatibility Support Module (CSM) ==


bochs -q 'floppya: 1_44=myfdimage.img, status=inserted' 'romimage: file=out/bios.bin'
To build as a CSM, first run kconfig (make menuconfig) and enable CONFIG_CSM. Then build SeaBIOS (make) - the resulting binary will be in &quot;out/Csm16.bin&quot;.


For best results, please use Bochs version 2.4.5 or later.
This binary may be used with the OMVF/EDK-II UEFI firmware. It will provide &quot;legacy&quot; BIOS services for booting non-EFI operating systems and will also allow OVMF to display on otherwise unsupported video hardware by using the traditional VGA BIOS. (Windows 2008r2 is known to use INT 10h BIOS calls even when booted via EFI, and the presence of a CSM makes this work as expected too.)


= Debug information =
Having built SeaBIOS with CONFIG_CSM, one should be able to drop the result (out/Csm16.bin) into an OVMF build tree at OvmfPkg/Csm/Csm16/Csm16.bin and then build OVMF with 'build -D CSM_ENABLE'. The SeaBIOS binary will be included as a discrete file within the 'Flash Volume' which is created, and there are tools which will extract it and allow it to be replaced.


SeaBIOS writes informational messages to a special debug port.
= Distribution builds =
Under QEMU, one can view these messages using the ''isa-debugcon'' module.  For example:


qemu -fda myfdimage.img -chardev stdio,id=seabios -device isa-debugcon,iobase=0x402,chardev=seabios
If one is building a binary version of SeaBIOS as part of a package (such as an rpm) or for wide distribution, please provide the EXTRAVERSION field during the build. For example:


It's possible to increase the verbosity of the SeaBIOS debug information.  To do this, run '''make menuconfig''' and set '''CONFIG_DEBUG_LEVEL''' to a higher value.  When reporting issues, please set the debug level to 8 (levels above 8 will frequently cause too much data) and include the full log along with a description of the problem in the trouble report.
<code>make EXTRAVERSION=&quot;-${RPM_PACKAGE_RELEASE}&quot;</code>


== Debugging with QEMU and GDB ==
The EXTRAVERSION field should provide the package version (if applicable) and the name of the distribution (if that's not already obvious from the package version). This string will be appended to the main SeaBIOS version. The above information helps SeaBIOS developers correlate defect reports to the source code and build environment.


The gdb-server mechanism of QEMU is also useful.  One can use gdb with QEMU to debug system images. To use this, add '-s -S' to the QEMU command line. For example:
If one is building a binary in a build environment that does not have access to the git tool or does not have the full SeaBIOS git repo available, then please use an official SeaBIOS release tar file as source. If building from a snapshot (where there is no official SeaBIOS tar) then one should generate a snapshot tar file on a machine that does support git using the scripts/tarball.sh tool. For example:


qemu -L mybiosdir/ -fda myfdimage.img -s -S
<code>scripts/tarball.sh</code>


Then, in another session, run gdb with either out/rom16.o (to debug bios 16bit code) or out/rom32.o (to debug bios 32bit code). For example:
The tarball.sh script encodes version information in the resulting tar file which the build can extract and include in the final binary. The above EXTRAVERSION field should still be set when building from a tar.


gdb out/rom16.o
= Overview of files in the repository =


Once in gdb, use the command '''target remote localhost:1234''' to have gdb connect to qemu. See the QEMU documentation for more information on using gdb and qemu in this mode. Note that gdb seems to get breakpoints confused when the cpu is in 16-bit real mode. This makes stepping through the program difficult (though 'step instruction' still works). Also, one may need to set 16bit break points at both the cpu address and memory address (eg, break *0x1234 ; break *0xf1234).
The '''src/''' directory contains the main bios source code. The '''src/hw/''' directory contains source code specific to hardware drivers. The '''src/fw/''' directory contains source code for platform firmware initialization. The '''src/std/''' directory contains header files describing standard bios, firmware, and hardware interfaces.
 
The '''vgasrc/''' directory contains code for [[SeaVGABIOS|SeaVGABIOS]].
 
The '''scripts/''' directory contains helper utilities for manipulating and building the final roms.
 
The '''out/''' directory is created by the build process - it contains all intermediate and final files.
 
When reading the C code be aware that code that runs in 16bit mode can not arbitrarily access non-stack memory - see [[Memory%20Model|Memory Model]] for more details. For information on the major C code functions and where code execution starts see [[Execution%20and%20code%20flow|Execution and code flow]].

Latest revision as of 13:43, 26 October 2015

The SeaBIOS code can be built using standard GNU tools. A recent Linux distribution should be able to build SeaBIOS using the standard compiler tools.

Building SeaBIOS

First, obtain the code. SeaBIOS can be compiled for several different build targets. It is also possible to configure additional compile time options - run make menuconfig to do this.

Build for QEMU (along with KVM, Xen, and Bochs)

To build for QEMU (and similar), one should be able to run "make" in the main directory. The resulting file "out/bios.bin" contains the processed bios image.

One can use the resulting binary with QEMU by using QEMU's "-bios" option. For example:

qemu -bios out/bios.bin -fda myfdimage.img

One can also use the resulting binary with Bochs. For example:

bochs -q 'floppya: 1_44=myfdimage.img' 'romimage: file=out/bios.bin'

Build for coreboot

To build for coreboot please see the coreboot build instructions at: http://www.coreboot.org/SeaBIOS

Build as a UEFI Compatibility Support Module (CSM)

To build as a CSM, first run kconfig (make menuconfig) and enable CONFIG_CSM. Then build SeaBIOS (make) - the resulting binary will be in "out/Csm16.bin".

This binary may be used with the OMVF/EDK-II UEFI firmware. It will provide "legacy" BIOS services for booting non-EFI operating systems and will also allow OVMF to display on otherwise unsupported video hardware by using the traditional VGA BIOS. (Windows 2008r2 is known to use INT 10h BIOS calls even when booted via EFI, and the presence of a CSM makes this work as expected too.)

Having built SeaBIOS with CONFIG_CSM, one should be able to drop the result (out/Csm16.bin) into an OVMF build tree at OvmfPkg/Csm/Csm16/Csm16.bin and then build OVMF with 'build -D CSM_ENABLE'. The SeaBIOS binary will be included as a discrete file within the 'Flash Volume' which is created, and there are tools which will extract it and allow it to be replaced.

Distribution builds

If one is building a binary version of SeaBIOS as part of a package (such as an rpm) or for wide distribution, please provide the EXTRAVERSION field during the build. For example:

make EXTRAVERSION="-${RPM_PACKAGE_RELEASE}"

The EXTRAVERSION field should provide the package version (if applicable) and the name of the distribution (if that's not already obvious from the package version). This string will be appended to the main SeaBIOS version. The above information helps SeaBIOS developers correlate defect reports to the source code and build environment.

If one is building a binary in a build environment that does not have access to the git tool or does not have the full SeaBIOS git repo available, then please use an official SeaBIOS release tar file as source. If building from a snapshot (where there is no official SeaBIOS tar) then one should generate a snapshot tar file on a machine that does support git using the scripts/tarball.sh tool. For example:

scripts/tarball.sh

The tarball.sh script encodes version information in the resulting tar file which the build can extract and include in the final binary. The above EXTRAVERSION field should still be set when building from a tar.

Overview of files in the repository

The src/ directory contains the main bios source code. The src/hw/ directory contains source code specific to hardware drivers. The src/fw/ directory contains source code for platform firmware initialization. The src/std/ directory contains header files describing standard bios, firmware, and hardware interfaces.

The vgasrc/ directory contains code for SeaVGABIOS.

The scripts/ directory contains helper utilities for manipulating and building the final roms.

The out/ directory is created by the build process - it contains all intermediate and final files.

When reading the C code be aware that code that runs in 16bit mode can not arbitrarily access non-stack memory - see Memory Model for more details. For information on the major C code functions and where code execution starts see Execution and code flow.

Retrieved from "https://www.seabios.org/index.php?title=Build_overview&oldid=88"