coreboot-mirror
/
seabios
mirror of https://review.coreboot.org/seabios.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Add wiki documentation to repository 

Add a docs/ directory that contains the contents of the SeaBIOS wiki
in markdown format.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
This commit is contained in:
Kevin O'Connor 2014-12-16 08:53:24 -05:00
parent 72691a5299
commit 14d3d26792
11 changed files with 1039 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
docs/Build_overview.md Normal file
View File

@ -0,0 +1,80 @@
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](Download). 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.
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 VGA BIOS implementations.
This code is separate from the main BIOS code in the src/ directory.
When the build is configured to produce a VGA BIOS the resulting
binary is found in out/vgabios.bin. The VGA BIOS code is always
compiled in 16bit mode.
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](Memory
Model) for more details. For information on the major C code functions
and where code execution starts see [Execution and code
flow](Execution and code flow).

69
docs/Debugging.md Normal file
View File

@ -0,0 +1,69 @@
This page describes the process of obtaining diagnostic information
from SeaBIOS and for reporting problems.
Diagnostic information
======================
SeaBIOS has the ability to output diagnostic messages. This is
implemented in the code via calls to the "dprintf()" C function.
On QEMU these messages are written to a special debug port. One can
view these messages by adding '-chardev stdio,id=seabios -device
isa-debugcon,iobase=0x402,chardev=seabios' to the QEMU command line.
Once this is done, one should see status messages on the console.
On coreboot these messages are generally written to the "cbmem"
console (CONFIG_DEBUG_COREBOOT). If SeaBIOS launches a Linux operating
system, one can obtain the cbmem tool from the coreboot repository and
run "cbmem -c" to view the SeaBIOS diagnostic messages.
Additionally, if a serial port is available, one may compile SeaBIOS
to send the diagnostic messages to the serial port. See the SeaBIOS
CONFIG_DEBUG_SERIAL option.
Trouble reporting
=================
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 SeaBIOS [mailing list](Mailinglist).
Debugging with gdb on QEMU
==========================
One can use gdb with QEMU to debug system images. To do this, add '-s
-S' to the qemu command line. For example:
`qemu -bios out/bios.bin -fda myfdimage.img -s -S`
Then, in another session, run gdb with either out/rom16.o (to debug
bios 16bit code) or out/rom.o (to debug bios 32bit code). For example:
`gdb out/rom16.o`
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.
When debugging 16bit code, also run the following commands in gdb:
`set architecture i8086`\
`add-symbol-file out/rom16.o 0xf0000`
The second command loads the 16bit symbols a second time at an offset
of 0xf0000, which helps gdb set and catch breakpoints correctly.
To debug a VGA BIOS image, run "gdb out/vgarom.o" add use the gdb
command "add-symbol-file out/vgarom.o 0xc0000" to load the 16bit VGA
BIOS symbols twice.
If debugging the 32bit SeaBIOS initialization code with gdb, note that
SeaBIOS does self relocation by default. This relocation will alter
the location of initialization code symbols. Disable
CONFIG_RELOCATE_INIT to prevent SeaBIOS from doing this.

24
docs/Developer_Documentation.md Normal file
View File

@ -0,0 +1,24 @@
This page is intended for developers interested in understanding and
enhancing SeaBIOS. Please also consider joining the [mailing
list](Mailinglist).
The SeaBIOS code can be obtained via the [download](Download)
page. Please see the **README** file in the source code repository for
information on building SeaBIOS. For specific information on building
SeaBIOS for coreboot, please see the [coreboot
SeaBIOS](http://www.coreboot.org/SeaBIOS) page. For information on
building SeaBIOS for use as a Compatibility Support Module with UEFI,
please see the **README.CSM** file in the source code repository.
See details on [building SeaBIOS](Build overview).
There is also information on the SeaBIOS [Memory Model](Memory Model).
Along with information on SeaBIOS [Execution and code flow](Execution
and code flow).
To debug SeaBIOS and report problems see SeaBIOS
[debugging](Debugging).
Useful links to specifications is available at [Developer
links](Developer links).

86
docs/Developer_links.md Normal file
View File

@ -0,0 +1,86 @@
Links to pages with more information.
BIOS interfaces
===============
Ralf Brown's interrupt list
* <http://www.cs.cmu.edu/~ralf/files.html>
Memory layout info
* <http://stanislavs.org/helppc/bios_data_area.html>
Old PNP BIOS spec
* <ftp://download.intel.com/support/motherboards/desktop/sb/pnpbiosspecificationv10a.pdf>
T13 BIOS Enhanced Disk Drive (drafts):
* <http://www.t10.org/t13/#Project_drafts>
Exported BIOS tables
====================
ACPI spec
* <http://www.acpi.info/>
PCI IRQ Routing Table Specification
* <http://www.microsoft.com/whdc/archive/pciirq.mspx>
MP configuration table
* <http://www.intel.com/design/pentium/datashts/242016.htm>
SM BIOS (aka DMI):
* <http://www.dmtf.org/standards/smbios/>
Hardware information
====================
info on PIC
* <http://www.beyondlogic.org/interrupts/interupt.htm>
info on kbd
* <http://www.computer-engineering.org/ps2protocol/>
info on vga
* <http://www.osdever.net/FreeVGA/home.htm>
info on lpt
* <http://www.beyondlogic.org/spp/parallel.htm>
info on floppy
* <http://www.isdaman.com/alsos/hardware/fdc/floppy.htm>
info on ata
* <http://ata.wiki.kernel.org/index.php/Developer_Resources>
* <http://www.t10.org/t13/#Project_drafts>
info on serial
* <http://www.national.com/ds/PC/PC16550D.pdf>
General information
===================
Bochs tech document list
* <http://bochs.sourceforge.net/techdata.html>
Phoenix documents
* <http://www.phoenix.com/en/Customer+Services/White+Papers-Specs/PC+Industry+Specifications.htm>
Dosemu information
* <http://www.dosemu.org/docs/README-tech>

25
docs/Download.md Normal file
View File

@ -0,0 +1,25 @@
SeaBIOS may be distributed under the terms of the [GNU
LGPLv3](http://www.gnu.org/licenses/lgpl-3.0-standalone.html) license.
Both source code and binaries are available.
Latest source code
==================
The SeaBIOS project uses the [git](http://git-scm.com/) revision
control system. To download the latest source from revision control,
run:
`$ git clone git://git.seabios.org/seabios.git seabios`\
`$ cd seabios`
There's also a [website](http://git.seabios.org/) to browse the latest
source code online.
Released versions
=================
Released versions of the source code are available at:
<http://code.coreboot.org/p/seabios/downloads/>
Please see [releases](Releases) for information on each release.

178
docs/Execution_and_code_flow.md Normal file
View File

@ -0,0 +1,178 @@
This page provides a high-level description of some of the major code
phases that SeaBIOS transitions through and general information on
overall code flow.
SeaBIOS code phases
===================
The SeaBIOS code goes through a few distinct code phases during its
execution lifecycle. Understanding these code phases can help when
reading and enhancing the code.
POST phase
----------
The Power On Self Test (POST) phase is the initialization phase of the
BIOS. This phase is entered when SeaBIOS first starts execution. The
goal of the phase is to initialize internal state, initialize external
interfaces, detect and setup hardware, and to then start the boot
phase.
On emulators, this phase starts when the CPU starts execution in 16bit
mode at 0xFFFF0000:FFF0. The emulators map the SeaBIOS binary to this
address, and SeaBIOS arranges for romlayout.S:reset_vector() to be
present there. This code calls romlayout.S:entry_post() which then
calls post.c:handle_post() in 32bit mode.
On coreboot, the build arranges for romlayout.S:entry_elf() to be
called in 32bit mode. This then calls post.c:handle_post().
On CSM, the build arranges for romlayout.S:entry_csm() to be called
(in 16bit mode). This then calls csm.c:handle_csm() in 32bit mode.
Unlike on the emulators and coreboot, the SeaBIOS CSM POST phase is
orchastrated with UEFI and there are several calls back and forth
between SeaBIOS and UEFI via handle_csm() throughout the POST
process.
The POST phase itself has several sub-phases.
* The "preinit" sub-phase: code run prior to code relocation.
* The "init" sub-phase: code to initialize internal variables and
interfaces.
* The "setup" sub-phase: code to setup hardware and drivers.
* The "prepboot" sub-phase: code to finalize interfaces and prepare
for the boot phase.
At completion of the POST phase, SeaBIOS invokes an "int 0x19"
software interrupt in 16bit mode which begins the boot phase.
Boot phase
----------
The goal of the boot phase is to load the first portion of the
operating system's boot loader into memory and start execution of that
boot loader. This phase starts when a software interrupt ("int 0x19"
or "int 0x18") is invoked. The code flow starts in 16bit mode in
romlayout.S:entry_19() or romlayout.S:entry_18() which then
transition to 32bit mode and call boot.c:handle_19() or
boot.c:handle_18().
The boot phase is technically also part of the "runtime" phase of
SeaBIOS. It is typically invoked immiediately after the POST phase,
but it can also be invoked by an operating system or be invoked
multiple times in an attempt to find a valid boot media. Although the
boot phase C code runs in 32bit mode it does not have write access to
the 0x0f0000-0x100000 memory region and can not call the various
malloc_X() calls. See [Memory Model](Memory Model) for
more information.
Main runtime phase
------------------
The main runtime phase occurs after the boot phase starts the
operating system. Once in this phase, the SeaBIOS code may be invoked
by the operating system using various 16bit and 32bit calls. The goal
of this phase is to support these legacy calling interfaces and to
provide compatibility with BIOS standards. There are multiple entry
points for the BIOS - see the entry_XXX() assembler functions in
romlayout.S.
Callers use most of these legacy entry points by setting up a
particular CPU register state, invoking the BIOS, and then inspecting
the returned CPU register state. To handle this, SeaBIOS will backup
the current register state into a "struct bregs" (see romlayout.S,
entryfuncs.S, and bregs.h) on call entry and then pass this struct to
the C code. The C code can then inspect the register state and modify
it. The assembler entry functions will then restore the (possibly
modified) register state from the "struct bregs" on return to the
caller.
Resume and reboot
-----------------
As noted above, on emulators SeaBIOS handles the 0xFFFF0000:FFF0
machine startup execution vector. This vector is also called on
machine faults and on some machine "resume" events. It can also be
called (as 0xF0000:FFF0) by software as a request to reboot the
machine (on emulators, coreboot, and CSM).
The SeaBIOS "resume and reboot" code handles these calls and attempts
to determine the desired action of the caller. Code flow starts in
16bit mode in romlayout.S:reset_vector() which calls
romlayout.S:entry_post() which calls romlayout.S:entry_resume() which
calls resume.c:handle_resume(). Depending on the request the
handle_resume() code may transition to 32bit mode.
Technically this code is part of the "runtime" phase, so even though
parts of it run in 32bit mode it still has the same limitations of the
runtime phase.
Threads
=======
Internally SeaBIOS implements a simple cooperative multi-tasking
system. The system works by giving each "thread" its own stack, and
the system round-robins between these stacks whenever a thread issues
a yield() call. This "threading" system may be more appropriately
described as [coroutines](http://en.wikipedia.org/wiki/Coroutine).
These "threads" do not run on multiple CPUs and are not preempted, so
atomic memory accesses and complex locking is not required.
The goal of these threads is to reduce overall boot time by
parallelizing hardware delays. (For example, by allowing the wait for
an ATA harddrive to spinup and respond to commands to occur in
parallel with the wait for a PS/2 keyboard to respond to a setup
command.) These hardware setup threads are only available during the
"setup" sub-phase of the [POST phase](#POST_phase).
The code that implements threads is in stacks.c.
Hardware interrupts
===================
The SeaBIOS C code always runs with hardware interrupts disabled. All
of the C code entry points (see romlayout.S) are careful to explicitly
disable hardware interrupts (via "cli"). Because running with
interrupts disabled increases interrupt latency, any C code that could
loop for a significant amount of time (more than about 1 ms) should
periodically call yield(). The yield() call will briefly enable
hardware interrupts to occur, then disable interrupts, and then resume
execution of the C code.
There are two main reasons why SeaBIOS always runs C code with
interrupts disabled. The first reason is that external software may
override the default SeaBIOS handlers that are called on a hardware
interrupt event. Indeed, it is common for DOS based applications to do
this. These legacy third party interrupt handlers may have
undocumented expections (such as stack location and stack size) and
may attempt to call back into the various SeaBIOS software services.
Greater compatibility and more reproducible results can be achieved by
only permitting hardware interrupts at specific points (via yield()
calls). The second reason is that much of SeaBIOS runs in 32bit mode.
Attempting to handle interrupts in both 16bit mode and 32bit mode and
switching between modes to delegate those interrupts is an unneeded
complexity. Although disabling interrupts can increase interrupt
latency, this only impacts legacy systems where the small increase in
interrupt latency is unlikely to be noticeable.
Extra 16bit stack
=================
SeaBIOS implements 16bit real mode handlers for both hardware
interrupts and software request "interrupts". In a traditional BIOS,
these requests would use the caller's stack space. However, the
minimum amount of space the caller must provide has not been
standardized and very old DOS programs have been observed to allocate
very small amounts of stack space (100 bytes or less).
By default, SeaBIOS now switches to its own stack on most 16bit real
mode entry points. This extra stack space is allocated in ["low
memory"](Memory Model). It ensures SeaBIOS uses a minimal amount of a
callers stack (typically no more than 16 bytes) for these legacy
calls. (More recently defined BIOS interfaces such as those that
support 16bit protected and 32bit protected mode calls standardize a
minimum stack size with adequete space, and SeaBIOS generally will not
use its extra stack in these cases.)
The code to implement this stack "hopping" is in romlayout.S and in
stacks.c.

8
docs/Mailinglist.md Normal file
View File

@ -0,0 +1,8 @@
For questions and general information about SeaBIOS, please subscribe
to the [SeaBIOS mailing
list](http://www.seabios.org/mailman/listinfo/seabios). If you're not
subscribed, your post will be held temporarily for moderator approval
(to combat spam).
A mailing list archive is available at
<http://www.seabios.org/pipermail/seabios/>

244
docs/Memory_Model.md Normal file
View File

@ -0,0 +1,244 @@
The SeaBIOS code is required to support multiple x86 CPU memory
models. This requirement impacts the code layout and internal storage
of SeaBIOS.
x86 Memory Models
=================
The x86 line of CPUs has evolved over many years. The original 8086
chip used 16bit pointers and could only address 1 megabyte of memory.
The 80286 CPU still used 16bit pointers, but could address up to 16
megabytes of memory. The 80386 chips could process 32bit instructions
and could access up to 4 gigabyte of memory. The most recent x86 chips
can process 64bit instructions and access 16 exabytes of ram.
During the evolution of the x86 CPUs from the 8086 to the 80386 the
BIOS was extended to handle calls in the various modes that the CPU
implemented.
This section outlines the five different x86 CPU execution and memory
access models that SeaBIOS supports.
16bit real mode
---------------
This mode is a
[segmented](http://en.wikipedia.org/wiki/Memory_segmentation) memory
mode invoked by callers. The CPU defaults to executing 16bit
instructions. Callers typically invoke the BIOS by issuing an "int x"
instruction which causes a software
[interrupt](http://en.wikipedia.org/wiki/Interrupt) that is handled by
the BIOS. The SeaBIOS code also handles hardware interrupts in this
mode. SeaBIOS can only access the first 1 megabyte of memory in this
mode, but it can access any part of that first megabyte.
16bit bigreal mode
------------------
This mode is a segmented memory mode that is used for [option
roms](http://en.wikipedia.org/wiki/Option_ROM). The CPU defaults to
executing 16bit instructions and segmented memory accesses are still
used. However, the segment limits are increased so that the entire
first 4 gigabytes of memory is fully accessible. Callers can invoke
all the [16bit real mode](#16bit_real_mode) functions while in this
mode and can also invoke the Post Memory Manager (PMM) functions that
are available during option rom execution.
16bit protected mode
--------------------
CPU execution in this mode is similar to [16bit real
mode](#16bit_real_mode). The CPU defaults to executing 16bit
instructions. However, each segment register indexes a "descriptor
table", and it is difficult or impossible to know what the physical
address of each segment is. Generally speaking, the BIOS can only
access code and data in the f-segment. The PCIBIOS, APM BIOS, and PNP
BIOS all have documented 16bit protected mode entry points.
Some old code may attempt to invoke the standard [16bit real
mode](#16bit_real_mode) entry points while in 16bit protected
mode. The PCI BIOS specification explicitly requires that the legacy
"int 1a" real mode entry point support 16bit protected mode calls if
they are for the PCI BIOS. Callers of other legacy entry points in
protected mode have not been observed and SeaBIOS does not support
them.
32bit segmented mode
--------------------
In this mode the processor runs in 32bit mode, but the segment
registers may have a limit and may have a non-zero offset. In effect,
this mode has all of the limitations of [16bit protected
mode](#16bit_protected_mode) - the main difference between the modes
is that the processor defaults to executing 32bit instructions. In
addition to these limitations, callers may also run the SeaBIOS code
at varying virtual addresses and so the code must support code
relocation. The PCI BIOS specification and APM BIOS specification
define 32bit segmented mode interfaces.
32bit flat mode
---------------
In this mode the processor defaults to executing 32bit instructions,
and all segment registers have an offset of zero and allow access to
the entire first 4 gigabytes of memory. This is the only "sane" mode
for 32bit code - modern compilers and modern operating systems will
generally only support this mode (when running 32bit code).
Ironically, it's the only mode that is not strictly required for a
BIOS to support. SeaBIOS uses this mode internally to support the POST
and BOOT [phases of execution](Execution and code flow).
code16gcc
=========
In order to produce code that can run when the processor is in a 16bit
mode, SeaBIOS uses the
[binutils](http://en.wikipedia.org/wiki/GNU_Binutils) ".code16gcc"
assembler flag. This instructs the assembler to emit extra prefix
opcodes so that the 32bit code produced by
[gcc](http://en.wikipedia.org/wiki/GNU_Compiler_Collection) will run
even when the processor is in 16bit mode. Note that gcc always
produces 32bit code - it does not know about the ".code16gcc" flag and
does not know that the code will run in a 16bit mode.
SeaBIOS uses the same code for all of the 16bit modes ([16bit real
mode](#16bit_real_mode), [16bit bigreal mode](#16bit_bigreal_mode),
and [16bit protected mode](#16bit_protected_mode)) and that code is
assembled using ".code16gcc". SeaBIOS is careful to use segment
registers properly so that the same code can run in the different
16bit modes that it needs to support.
Common memory used at run-time
==============================
There are several memory areas that the SeaBIOS "runtime"
[phase](Execution and code flow) makes use of:
* 0x000000-0x000400: Interrupt descriptor table (IDT). This area
defines 256 interrupt vectors as defined by the Intel CPU
specification for 16bit irq handlers. This area is read/writable at
runtime and can be accessed from 16bit real mode and 16bit bigreal
mode calls. SeaBIOS only uses this area to maintain compatibility
with legacy systems.
* 0x000400-0x000500: BIOS Data Area (BDA). This area contains various
legacy flags and attributes. The area is read/writable at runtime
and can be accessed from 16bit real mode and 16bit bigreal mode
calls. SeaBIOS only uses this area to maintain compatibility with
legacy systems.
* 0x09FC00-0x0A0000 (typical): Extended BIOS Data Area (EBDA). This
area contains a few legacy flags and attributes. The area is
typically located at 0x9FC00, but it can be moved by option roms, by
legacy operating systems, and by SeaBIOS if
CONFIG_MALLOC_UPPERMEMORY is not set. Its actual location is
determined by a pointer in the BDA. The area is read/writable at
runtime and can be accessed from 16bit real mode and 16bit bigreal
mode calls. SeaBIOS only uses this area to maintain compatibility
with legacy systems.
* 0x0E0000-0x0F0000 (typical): "low" memory. This area is used for
custom read/writable storage internal to SeaBIOS. The area is
read/writable at runtime and can be accessed from 16bit real mode
and 16bit bigreal mode calls. The area is typically located at the
end of the e-segment, but the build may position it anywhere in the
0x0C0000-0x0F0000 region. However, if CONFIG_MALLOC_UPPERMEMORY is
not set, then this region is between 0x090000-0x0A0000. Space is
allocated in this region by either marking a global variable with
the "VARLOW" flag or by calling malloc_low() during
initialization. The area can be grown dynamically (via malloc_low),
but it will never exceed 64K.
* 0x0F0000-0x100000: The BIOS segment. This area is used for both
runtime code and static variables. Space is allocated in this region
by either marking a global variable with VARFSEG, one of the VAR16
flags, or by calling malloc_fseg() during initialization. The area
is read-only at runtime and can be accessed from 16bit real mode,
16bit bigreal mode, 16bit protected mode, and 32bit segmented mode
calls.
All of the above areas are also read/writable during the SeaBIOS
initialization phase and are accessible when in 32bit flat mode.
Segmented mode memory access
============================
The assembler entry functions for segmented mode calls (all modes
except [32bit flat mode](#32bit_flat_mode)) will arrange
to set the data segment (%ds) to be the same as the stack segment
(%ss) before calling any C code. This permits all C variables located
on the stack and C pointers to data located on the stack to work as
normal.
However, all code running in segmented mode must wrap non-stack memory
accesses in special macros. These macros ensure the correct segment
register is used. Failure to use the correct macro will result in an
incorrect memory access that will likely cause hard to find errors.
There are three low-level memory access macros:
* GET_VAR / SET_VAR : Accesses a variable using the specified segment
register. This isn't typically used directly by C code.
* GET_FARVAR / SET_FARVAR : Assigns the extra segment (%es) to the
given segment id and then performs the given memory access via %es.
* GET_FLATVAR / SET_FLATVAR : These macros take a 32bit pointer,
construct a segment/offset pair valid in real mode, and then perform
the given access. These macros must not be used in 16bit protected
mode or 32bit segmented mode.
Since most memory accesses are to [common memory used at
run-time](#Common_memory_used_at_run-time), several helper
macros are also available.
* GET_IDT / SET_IDT : Access the interrupt descriptor table (IDT).
* GET_BDA / SET_BDA : Access the BIOS Data Area (BDA).
* GET_EBDA / SET_EBDA : Access the Extended BIOS Data Area (EBDA).
* GET_LOW / SET_LOW : Access internal variables marked with
VARLOW. (There are also related macros GET_LOWFLAT / SET_LOWFLAT for
accessing storage allocated with malloc_low).
* GET_GLOBAL : Access internal variables marked with the VAR16 or
VARFSEG flags. (There is also the related macro GET_GLOBALFLAT for
accessing storage allocated with malloc_fseg).
Memory available during initialization
======================================
During the POST [phase](Execution and code flow) the code
can fully access the first 4 gigabytes of memory. However, memory
accesses are generally limited to the [common memory used at
run-time](#Common_memory_used_at_run-time) and areas
allocated at runtime via one of the malloc calls:
* malloc_high : Permanent high-memory zone. This area is used for
custom read/writable storage internal to SeaBIOS. The area is
located at the top of the first 4 gigabytes of ram. It is commonly
used for storing standard tables accessed by the operating system at
runtime (ACPI, SMBIOS, and MPTable) and for DMA buffers used by
hardware drivers. The area is read/writable at runtime and an entry
in the e820 memory map is used to reserve it. When running on an
emulator that has only 1 megabyte of ram this zone will be empty.
* malloc_tmphigh : Temporary high-memory zone. This area is used for
custom read/writable storage during the SeaBIOS initialization
phase. The area generally starts after the first 1 megabyte of ram
(0x100000) and ends prior to the Permanent high-memory zone. When
running on an emulator that has only 1 megabyte of ram this zone
will be empty. The area is not reserved from the operating system,
so it must not be accessed after the SeaBIOS initialization phase.
* malloc_tmplow : Temporary low-memory zone. This area is used for
custom read/writable storage during the SeaBIOS initialization
phase. The area resides between 0x07000-0x90000. The area is not
reserved from the operating system and by specification it is
required to be zero'd at the end of the initialization phase.
The "tmplow" and "tmphigh" regions are only available during the
initialization phase. Any access (either read or write) after
completion of the initialization phase can result in difficult to find
errors.

5
docs/README Normal file
View File

@ -0,0 +1,5 @@
This directory contains SeaBIOS documentation as found on the SeaBIOS
wiki. All the files in this directory (with the exclusion of this
README file) correspond to a page on the wiki.
The documentation files use markdown syntax.

305
docs/Releases.md Normal file
View File

@ -0,0 +1,305 @@
History of SeaBIOS releases. Please see [download](Download) for
information on obtaining these releases.
SeaBIOS 1.7.5
=============
Available on 20140528. Major changes in this release:
* Support for obtaining SMBIOS tables directly from QEMU.
* XHCI USB controller fixes for real hardware (now tested on several
boards)
* SeaVGABIOS improvements
* New driver for "coreboot native vga" support
* Improved detection of older x86emu versions with incorrect
emulation.
* Several bug fixes and code cleanups
SeaBIOS 1.7.4
=============
Available on 20131223. Major changes in this release:
* Support for obtaining ACPI tables directly from QEMU.
* Initial support for XHCI USB controllers (initially for QEMU only).
* Support for booting from "pvscsi" devices on QEMU.
* Enhanced floppy driver - improved support for real hardware.
* coreboot cbmem console support.
* Optional support for using the 9-segment instead of the e-segment
for local variables.
* Improved internal timer code and accuracy.
* SeaVGABIOS improvements
* Better support for legacy X.org releases with incomplete x86emu
emulation.
* Support for using an internal stack to reduce caller's stack
usage.
* Back port of new "bochs dispi" interface video modes.
* Several bug fixes and code cleanups
* Source code separated out into additional hardware and firmware
directories.
* Update to latest version of Kconfig
SeaBIOS 1.7.3
=============
Available on 20130707. Major changes in this release:
* Initial support for using SeaBIOS as a UEFI Compatibility Support
Module (CSM)
* Support for detecting and using ACPI reboot ports.
* By default, all 16bit entry points now use an internal stack to
reduce stack footprint.
* Floppy controller code has been rewritten to improve
compatibility. Non-standard floppy sizes now work again with recent
QEMU versions.
* Several bug fixes and code cleanups
SeaBIOS 1.7.2
=============
Available on 20130118. Major changes in this release:
* Support for ICH9 host chipset ("q35") on emulators
* Support for booting from LSI MegaRAID SAS controllers
* Support for using the ACPI PM timer on emulators
* Improved Geode VGA BIOS support.
* Several bug fixes
SeaBIOS 1.7.1
=============
Available on 20120831. Major changes in this release:
* Initial support for booting from USB attached scsi (USB UAS) drives
* USB EHCI 64bit controller support
* USB MSC multi-LUN device support
* Support for booting from LSI SCSI controllers on emulators
* Support for booting from AMD PCscsi controllers on emulators
* New PCI allocation code on emulators. Support 64bit PCI bars and
mapping them above 4G.
* Support for non-linear APIC ids on emulators.
* Stack switching for 16bit real mode irq handlers to reduce stack
footprint.
* Support for custom storage in the memory at 0xc0000-0xf0000. No
longer reserve memory for custom storage in first 640k.
* Improved code generation for 16bit segment register loads
* Boot code will now (by default) reboot after 60 seconds if no boot
device found
* CBFS and FWCFG "files" are now only scanned one time
* Several bug fixes
SeaBIOS 1.7.0
=============
Available on 20120414. Major changes in this release:
* Many enhancements to VGA BIOS code - it should now be feature
complete with LGPL vgabios.
* Support for virtio-scsi.
* Improved USB drive (usb-msc) support.
* Several USB controller bug fixes and improvements.
* Runtime ACPI AML PCI hotplug construction.
* Support for running on i386 and i486 CPUs.
* Enhancements to PCI init when running on emulators.
* Several bug fixes
SeaBIOS 1.6.3
=============
Available on 20111004. Major changes in this release:
* Initial support for Xen
* PCI init (on emulators) uses a two-phase initialization
* Fixes for AHCI so it can work on real hardware. AHCI is now enabled
by default.
* Bootsplash support for BMP files
* Several configuration options can now be configured at runtime via
CBFS files (eg, "etc/boot-menu-wait")
* PCI device scan is cached during POST phase
* Several bug fixes
SeaBIOS 0.6.2
=============
Available on 20110228. Major changes in this release:
* Setup code can relocate to high-memory to save space in c-f segments
* Build now configured via Kconfig
* Experimental support for AHCI controllers
* Support for run-time configuration of the boot order (via
CBFS/fw_cfg "bootorder" file)
* Support T13 EDD3.0 spec
* Improved bounds checking on PCI memory allocation
* Several bug fixes
SeaBIOS 0.6.1
=============
Available on 20100913. Major changes in this release:
* Support for virtio drives
* Add ACPI definitions for cpu hotplug support
* Support for a graphical bootsplash screen
* USB mouse support
* The PCI support for emulators is less dependent on i440 chipset
* New malloc implementation which improves memalign and free
* The build system no longer double links objects
* Several bug fixes
SeaBIOS 0.6.0
=============
Available on 20100326. Major changes in this release:
* USB hub support
* USB drive booting support
* USB keyboard auto-repeat support
* USB EHCI controller support
* Several improvements to compatibility of PS2 port handlers for old
code
* Support for qemu e820 interface
* Several bug fixes and code cleanups
SeaBIOS 0.5.1
=============
Available on 20100108. Major changes in this release:
* Support for 32bit PCI BIOS calls
* Support for int1589 calls
* MPTable fixes for OpenBSD
* ATA DMA and bus-mastering support
* Several bug fixes and code cleanups
SeaBIOS 0.5.0
=============
Available on 20091218. Major changes in this release:
* Several enhancements ported from the Bochs BIOS derived code in qemu
and kvm
* Support for parallel hardware initialization to reduce bootup times
* Enable PCI option rom support by default (Bochs users must now
enable CONFIG_OPTIONROMS_DEPLOYED in src/config.h). Support added
for extracting option roms from qemu "fw_cfg".
* Support USB UHCI and OHCI controllers
* Initial support for USB keyboards
* SeaBIOS can now be greater than 64K
* Support for permanent low memory allocations
* APIC "local interrupts" now enabled in SeaBIOS (on emulators)
* Several bug fixes and code cleanups
SeaBIOS 0.4.2
=============
Available on 20090909. Major changes in this release:
* Implement Post Memory Manager (PMM) support. Use equivalent "malloc"
functions for internal allocations as well.
* Refactor disk "block" interface for greater expandability
* Support CBFS based floppy images
* Allow boot menu to select either floppy to boot from
* Increase ebda size to store a CDROM harddrive/floppy emulation
buffer
* Support systems with multiple vga cards (only the card with the
legacy IO ranges mapped will have its option rom executed)
* Make option rom memory be writable during option rom execution (on
emulators)
* Compile version number into code and report on each boot
* Several bug fixes and code cleanups
SeaBIOS 0.4.1
=============
Available on 20090714. Major changes in this release:
* Support older versions of gcc that predate "-fwhole-program" (eg,
v3.x)
* Add initial port of "LGPL vga bios" code into tree in "vgasrc/"
directory
* Handle ATA drives still "spinning up" during SeaBIOS drive detect
* Add support for option rom Boot Connection Vectors (BCV)
* Enhance boot menu to support booting from any drive or any cdrom
* Support flash based Coreboot File System (CBFS)
* Support booting from a CBFS "payload"
* Support coreboot table forwarder
* Support compile time definitions for multiple root PCI buses
* New tools/readserial.py tool
* Several bug fixes and code cleanups
SeaBIOS 0.4.0
=============
Available on 20090206. Major changes in this release:
* Add Bios Boot Specification (BBS) calls; add PnP call stubs
* Support option roms stored in PCI rom BAR
* Support rebooting on ctrl+alt+delete key press
* Scan PCI devices for ATA adapters (don't assume legacy ISA ATA ports
are valid)
* Attempt to automatically determine gcc capabilities/bugs during
build
* Add script to layout 16bit sections at fixed offsets and in
compacted space
* Introduce timestamp counter based delays
* Support POST calls that are really a resume
* Use new stack in EBDA for int13 disk calls to reduce stack usage
* Support the EBDA being relocated by option roms
* Move many variables from EBDA to global variables (stored in
f-segment)
* Support for PCI bridges when iterating through PCI device list
* Initial port of several KVM specific features from their Bochs BIOS
derived code
* Access BDA using segment 0x40 and IVT using segment 0x00 (which
could be important for 16bit protected mode callers)
* Several bug fixes and code cleanups
SeaBIOS 0.3.0
=============
Available on 20080817. Major changes in this release:
* Run boot code (int18/19) in 32bit mode
* Rewrite of PS2 port handling - new code is more compatible with real
hardware
* Initial support for int155f VGA option rom calls
* Several bug fixes and code cleanups
SeaBIOS 0.2.3
=============
Available on 20080702. Major changes in this release:
* Initial support for running on real hardware with coreboot
* Support parsing coreboot tables
* Support relocating bios tables from high memory when running under
coreboot
* Dynamic e820 map generation
* Serial debug support
* New tools/checkstack.py tool
* Several bug fixes and code cleanups
SeaBIOS 0.2.2
=============
Formerly known as "legacybios". Available on 20080501. Major changes
in this release:
* Several bug fixes and code cleanups
SeaBIOS 0.2.1
=============
Formerly known as "legacybios". Available on 20080406. Major changes
in this release:
* Port of boot menu code from Bochs BIOS
* Several bug fixes and code cleanups
SeaBIOS 0.2.0
=============
Formerly known as "legacybios". Available on 20080330. Major changes
in this release:
* Completion of initial port of Bochs BIOS code to gcc.

15
docs/SeaBIOS.md Normal file
View File

@ -0,0 +1,15 @@
SeaBIOS is an open source implementation of a 16bit X86 BIOS. SeaBIOS
can run in an emulator or it can run natively on X86 hardware with the
use of [coreboot](http://www.coreboot.org/).
SeaBIOS is the default BIOS for [qemu](http://www.qemu.org/) and
[kvm](http://www.linux-kvm.org/).
The [coreboot SeaBIOS](http://www.coreboot.org/SeaBIOS) page has
information on using SeaBIOS in coreboot. Please see the
[releases](Releases) page for information on recent releases. See the
[download](Download) page to obtain SeaBIOS.
Please join the [mailing list](Mailinglist) to contribute to
SeaBIOS. Information on the internals of SeaBIOS is available on the
[Developer Documentation](Developer Documentation) page.