[SeaBIOS] [PATCH] Add wiki documentation to repository
Kevin O'Connor
kevin at koconnor.net
Thu Dec 18 06:04:51 CET 2014
Add a docs/ directory that contains the contents of the SeaBIOS wiki
in markdown format.
Signed-off-by: Kevin O'Connor <kevin at koconnor.net>
---
docs/Build_overview.md | 80 +++++++++++
docs/Debugging.md | 69 +++++++++
docs/Developer_Documentation.md | 24 ++++
docs/Developer_links.md | 86 +++++++++++
docs/Download.md | 25 ++++
docs/Execution_and_code_flow.md | 178 +++++++++++++++++++++++
docs/Mailinglist.md | 8 ++
docs/Memory_Model.md | 244 ++++++++++++++++++++++++++++++++
docs/README | 5 +
docs/Releases.md | 305 ++++++++++++++++++++++++++++++++++++++++
docs/SeaBIOS.md | 15 ++
11 files changed, 1039 insertions(+)
create mode 100644 docs/Build_overview.md
create mode 100644 docs/Debugging.md
create mode 100644 docs/Developer_Documentation.md
create mode 100644 docs/Developer_links.md
create mode 100644 docs/Download.md
create mode 100644 docs/Execution_and_code_flow.md
create mode 100644 docs/Mailinglist.md
create mode 100644 docs/Memory_Model.md
create mode 100644 docs/README
create mode 100644 docs/Releases.md
create mode 100644 docs/SeaBIOS.md
diff --git a/docs/Build_overview.md b/docs/Build_overview.md
new file mode 100644
index 0000000..26db226
--- /dev/null
+++ b/docs/Build_overview.md
@@ -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).
diff --git a/docs/Debugging.md b/docs/Debugging.md
new file mode 100644
index 0000000..d42110b
--- /dev/null
+++ b/docs/Debugging.md
@@ -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.
diff --git a/docs/Developer_Documentation.md b/docs/Developer_Documentation.md
new file mode 100644
index 0000000..ed2e9a4
--- /dev/null
+++ b/docs/Developer_Documentation.md
@@ -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).
diff --git a/docs/Developer_links.md b/docs/Developer_links.md
new file mode 100644
index 0000000..67a047e
--- /dev/null
+++ b/docs/Developer_links.md
@@ -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>
diff --git a/docs/Download.md b/docs/Download.md
new file mode 100644
index 0000000..1cfac9b
--- /dev/null
+++ b/docs/Download.md
@@ -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.
diff --git a/docs/Execution_and_code_flow.md b/docs/Execution_and_code_flow.md
new file mode 100644
index 0000000..9396eca
--- /dev/null
+++ b/docs/Execution_and_code_flow.md
@@ -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.
diff --git a/docs/Mailinglist.md b/docs/Mailinglist.md
new file mode 100644
index 0000000..21e74a4
--- /dev/null
+++ b/docs/Mailinglist.md
@@ -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/>
diff --git a/docs/Memory_Model.md b/docs/Memory_Model.md
new file mode 100644
index 0000000..c77fc22
--- /dev/null
+++ b/docs/Memory_Model.md
@@ -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.
diff --git a/docs/README b/docs/README
new file mode 100644
index 0000000..430e0fe
--- /dev/null
+++ b/docs/README
@@ -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.
diff --git a/docs/Releases.md b/docs/Releases.md
new file mode 100644
index 0000000..2a02b02
--- /dev/null
+++ b/docs/Releases.md
@@ -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.
diff --git a/docs/SeaBIOS.md b/docs/SeaBIOS.md
new file mode 100644
index 0000000..831bfce
--- /dev/null
+++ b/docs/SeaBIOS.md
@@ -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.
--
1.9.3
More information about the SeaBIOS
mailing list