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.