Based on the previous feedback, I've converted the current wiki documents to markdown format (via the pandoc tool) and then touched up the translation. The attached patch shows what moving the wiki documents into the seabios repo might look like. (It creates a new "docs/" directory with files for each page currently on the wiki.)
The pandoc tool seams to be able to translate back to mediawiki format without much issue. So, a possible workflow would be to use the git patch submission process to update documentation, and then use pandoc to translate the pages and push them to the wiki. (Or, if at some future point the wiki is decommissioned, then use pandoc or a similar tool to create html directly.)
Thoughts? -Kevin
Kevin O'Connor (1): Add wiki documentation to repository
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
Add a docs/ directory that contains the contents of the SeaBIOS wiki in markdown format.
Signed-off-by: Kevin O'Connor kevin@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.
"Kevin O'Connor" kevin@koconnor.net writes:
Based on the previous feedback, I've converted the current wiki documents to markdown format (via the pandoc tool) and then touched up the translation. The attached patch shows what moving the wiki documents into the seabios repo might look like. (It creates a new "docs/" directory with files for each page currently on the wiki.)
The pandoc tool seams to be able to translate back to mediawiki format without much issue. So, a possible workflow would be to use the git patch submission process to update documentation, and then use pandoc to translate the pages and push them to the wiki. (Or, if at some future point the wiki is decommissioned, then use pandoc or a similar tool to create html directly.)
Thoughts?
If this workflow works for you, go right ahead! Patch looks fine on a glance.
On Thu, Dec 18, 2014 at 12:04:50AM -0500, Kevin O'Connor wrote:
Based on the previous feedback, I've converted the current wiki documents to markdown format (via the pandoc tool) and then touched up the translation. The attached patch shows what moving the wiki documents into the seabios repo might look like. (It creates a new "docs/" directory with files for each page currently on the wiki.)
The pandoc tool seams to be able to translate back to mediawiki format without much issue. So, a possible workflow would be to use the git patch submission process to update documentation, and then use pandoc to translate the pages and push them to the wiki. (Or, if at some future point the wiki is decommissioned, then use pandoc or a similar tool to create html directly.)
FYI, I went ahead and pushed this change into the main seabios repo. The markdown format is quite readable for those wishing to review the documentation in the docs/ directory, and converting it to wiki format via pandoc is also straight forward. So, I don't see any downside to having the documentation stored in git.
-Kevin
-
Kevin O'Connor -
Markus Armbruster