I've been thinking of adding the SeaBIOS wiki documents into the SeaBIOS git repo. The following patch shows what that might look like. (It creates a new "docs/" directory with files for each page currently on the wiki.)
I'm not sure if doing this is a good idea. It would be nice to have the documents in version control, and it would be good to allow patches to simultaneously update the code and documentation. However, modifying wiki syntax from an editor isn't that easy.
Thoughts? -Kevin
Kevin O'Connor (1): Add wiki documentation to repository
docs/Build_overview | 41 +++++++++ docs/Debugging | 38 ++++++++ docs/Developer_Documentation | 13 +++ docs/Developer_links | 64 +++++++++++++ docs/Download | 18 ++++ docs/Execution_and_code_flow | 66 ++++++++++++++ docs/Mailinglist | 3 + docs/Memory_Model | 76 ++++++++++++++++ docs/README | 5 ++ docs/Releases | 208 +++++++++++++++++++++++++++++++++++++++++++ docs/SeaBIOS | 7 ++ 11 files changed, 539 insertions(+) create mode 100644 docs/Build_overview create mode 100644 docs/Debugging create mode 100644 docs/Developer_Documentation create mode 100644 docs/Developer_links create mode 100644 docs/Download create mode 100644 docs/Execution_and_code_flow create mode 100644 docs/Mailinglist create mode 100644 docs/Memory_Model create mode 100644 docs/README create mode 100644 docs/Releases create mode 100644 docs/SeaBIOS
Add a docs/ directory that contains the contents of the SeaBIOS wiki.
Signed-off-by: Kevin O'Connor kevin@koconnor.net --- docs/Build_overview | 41 +++++++++ docs/Debugging | 38 ++++++++ docs/Developer_Documentation | 13 +++ docs/Developer_links | 64 +++++++++++++ docs/Download | 18 ++++ docs/Execution_and_code_flow | 66 ++++++++++++++ docs/Mailinglist | 3 + docs/Memory_Model | 76 ++++++++++++++++ docs/README | 5 ++ docs/Releases | 208 +++++++++++++++++++++++++++++++++++++++++++ docs/SeaBIOS | 7 ++ 11 files changed, 539 insertions(+) create mode 100644 docs/Build_overview create mode 100644 docs/Debugging create mode 100644 docs/Developer_Documentation create mode 100644 docs/Developer_links create mode 100644 docs/Download create mode 100644 docs/Execution_and_code_flow create mode 100644 docs/Mailinglist create mode 100644 docs/Memory_Model create mode 100644 docs/README create mode 100644 docs/Releases create mode 100644 docs/SeaBIOS
diff --git a/docs/Build_overview b/docs/Build_overview new file mode 100644 index 0000000..07ddca1 --- /dev/null +++ b/docs/Build_overview @@ -0,0 +1,41 @@ +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, [[Download|obtain the code]]. SeaBIOS can be compiled for several different build targets. It is also possible to configure additional compile time options - run '''make menuconfig''' to do this. + +== 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]] for more details. For information on the major C code functions and where code execution starts see [[Execution and code flow]]. diff --git a/docs/Debugging b/docs/Debugging new file mode 100644 index 0000000..43674f8 --- /dev/null +++ b/docs/Debugging @@ -0,0 +1,38 @@ +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 [[Mailinglist|mailing list]]. + += 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 b/docs/Developer_Documentation new file mode 100644 index 0000000..d00b293 --- /dev/null +++ b/docs/Developer_Documentation @@ -0,0 +1,13 @@ +This page is intended for developers interested in understanding and enhancing SeaBIOS. Please also consider joining the [[Mailinglist|mailing list]]. + +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 [http://www.coreboot.org/SeaBIOS coreboot 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 [[Build overview|building SeaBIOS]]. + +There is also information on the SeaBIOS [[Memory Model]]. + +Along with information on SeaBIOS [[Execution and code flow]]. + +To debug SeaBIOS and report problems see SeaBIOS [[Debugging]]. + +Useful links to specifications is available at [[Developer links]]. diff --git a/docs/Developer_links b/docs/Developer_links new file mode 100644 index 0000000..e330c13 --- /dev/null +++ b/docs/Developer_links @@ -0,0 +1,64 @@ +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+S... + +Dosemu information +* http://www.dosemu.org/docs/README-tech diff --git a/docs/Download b/docs/Download new file mode 100644 index 0000000..99ac61a --- /dev/null +++ b/docs/Download @@ -0,0 +1,18 @@ +SeaBIOS may be distributed under the terms of the [http://www.gnu.org/licenses/lgpl-3.0-standalone.html GNU LGPLv3] license. Both source code and binaries are available. + += Latest source code = + +The SeaBIOS project uses the [http://git-scm.com/ git] 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 [http://git.seabios.org/ website] 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]] for information on each release. diff --git a/docs/Execution_and_code_flow b/docs/Execution_and_code_flow new file mode 100644 index 0000000..6474999 --- /dev/null +++ b/docs/Execution_and_code_flow @@ -0,0 +1,66 @@ +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]] 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 [http://en.wikipedia.org/wiki/Coroutine coroutines]. 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]]. + +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 [[Memory Model|"low memory"]]. 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 b/docs/Mailinglist new file mode 100644 index 0000000..c6cf10b --- /dev/null +++ b/docs/Mailinglist @@ -0,0 +1,3 @@ +For questions and general information about SeaBIOS, please subscribe to the [http://www.seabios.org/mailman/listinfo/seabios SeaBIOS mailing list]. 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 b/docs/Memory_Model new file mode 100644 index 0000000..c81d4df --- /dev/null +++ b/docs/Memory_Model @@ -0,0 +1,76 @@ +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 [http://en.wikipedia.org/wiki/Memory_segmentation segmented] 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 [http://en.wikipedia.org/wiki/Interrupt 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 [http://en.wikipedia.org/wiki/Option_ROM option roms]. 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]] 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]]. 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]] 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]] - 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 [[Execution and code flow|phases of execution]]. + +=code16gcc= + +In order to produce code that can run when the processor is in a 16bit mode, SeaBIOS uses the [http://en.wikipedia.org/wiki/GNU_Binutils binutils] ".code16gcc" assembler flag. This instructs the assembler to emit extra prefix opcodes so that the 32bit code produced by [http://en.wikipedia.org/wiki/GNU_Compiler_Collection gcc] 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 "bigreal" mode]], and [[#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" [[Execution and code flow|phase]] 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]]) 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]], 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 [[Execution and code flow|phase]] 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]] 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..1448fad --- /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 should be in MediaWiki syntax. diff --git a/docs/Releases b/docs/Releases new file mode 100644 index 0000000..d6f51d3 --- /dev/null +++ b/docs/Releases @@ -0,0 +1,208 @@ +History of SeaBIOS releases. Please see [[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 b/docs/SeaBIOS new file mode 100644 index 0000000..903e682 --- /dev/null +++ b/docs/SeaBIOS @@ -0,0 +1,7 @@ +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 [http://www.coreboot.org/ coreboot]. + +SeaBIOS is the default BIOS for [http://www.qemu.org/ qemu] and [http://www.linux-kvm.org/ kvm]. + +The [http://www.coreboot.org/SeaBIOS coreboot SeaBIOS] page has information on using SeaBIOS in coreboot. Please see the [[Releases]] page for information on recent releases. See the [[Download]] page to obtain SeaBIOS. + +Please join the [[Mailinglist|mailing list]] to contribute to SeaBIOS. Information on the internals of SeaBIOS is available on the [[Developer Documentation]] page.
Hi,
I'm not sure if doing this is a good idea. It would be nice to have the documents in version control, and it would be good to allow patches to simultaneously update the code and documentation. However, modifying wiki syntax from an editor isn't that easy.
I don't see editing wiki syntax in $editor as a problem.
But what is the plan for the wiki then? Discontinue? Switch to read-only and update from git? Two-way sync between wiki+git?
cheers, Gerd
On Wed, Dec 17, 2014 at 01:01:59PM +0100, Gerd Hoffmann wrote:
Hi,
I'm not sure if doing this is a good idea. It would be nice to have the documents in version control, and it would be good to allow patches to simultaneously update the code and documentation. However, modifying wiki syntax from an editor isn't that easy.
I don't see editing wiki syntax in $editor as a problem.
The really long lines are annoying to work with. git-send-email even complains about lines over 998 characters long.
But what is the plan for the wiki then? Discontinue? Switch to read-only and update from git? Two-way sync between wiki+git?
Update the wiki from git. Right now, only I have write access to the wiki anyway (as no one has requested a wiki account). A solution other than a wiki is also possible, but that wasn't something I was thinking of, at least in the short term.
-Kevin
"Kevin O'Connor" kevin@koconnor.net writes:
On Wed, Dec 17, 2014 at 01:01:59PM +0100, Gerd Hoffmann wrote:
Hi,
I'm not sure if doing this is a good idea. It would be nice to have the documents in version control, and it would be good to allow patches to simultaneously update the code and documentation. However, modifying wiki syntax from an editor isn't that easy.
I don't see editing wiki syntax in $editor as a problem.
The really long lines are annoying to work with. git-send-email even complains about lines over 998 characters long.
A sufficiently powerful editor (Emacs: visual-line-mode) should make it somewhat less annoying. Alternatively, edit *only* in an editor, and avoid long lines.
But what is the plan for the wiki then? Discontinue? Switch to read-only and update from git? Two-way sync between wiki+git?
Update the wiki from git. Right now, only I have write access to the wiki anyway (as no one has requested a wiki account). A solution other than a wiki is also possible, but that wasn't something I was thinking of, at least in the short term.
Should two-way become desirable, a Wiki backed by git and included as a submodule could be practical.
On Wed, Dec 17, 2014 at 03:13:32PM +0100, Markus Armbruster wrote:
"Kevin O'Connor" kevin@koconnor.net writes:
On Wed, Dec 17, 2014 at 01:01:59PM +0100, Gerd Hoffmann wrote:
I'm not sure if doing this is a good idea. It would be nice to have the documents in version control, and it would be good to allow patches to simultaneously update the code and documentation. However, modifying wiki syntax from an editor isn't that easy.
I don't see editing wiki syntax in $editor as a problem.
The really long lines are annoying to work with. git-send-email even complains about lines over 998 characters long.
A sufficiently powerful editor (Emacs: visual-line-mode) should make it somewhat less annoying. Alternatively, edit *only* in an editor, and avoid long lines.
It's the mediawiki syntax that drives the long lines - certain features, like lists, can't have newlines in them or they end the list. Normal paragraphs can actually have newlines in them, but if you put a newline in the middle of some syntax (like a link) then it wont interpet that syntax. This makes a normal editor's auto line wrap feature unusable.
Finally, there is the difficulty in "previewing" changes to see what it will ultimately look like.
It's all possible to handle, but annoying.
But what is the plan for the wiki then? Discontinue? Switch to read-only and update from git? Two-way sync between wiki+git?
Update the wiki from git. Right now, only I have write access to the wiki anyway (as no one has requested a wiki account). A solution other than a wiki is also possible, but that wasn't something I was thinking of, at least in the short term.
Should two-way become desirable, a Wiki backed by git and included as a submodule could be practical.
-Kevin
On Mi, 2014-12-17 at 08:24 -0500, Kevin O'Connor wrote:
On Wed, Dec 17, 2014 at 01:01:59PM +0100, Gerd Hoffmann wrote:
Hi,
I'm not sure if doing this is a good idea. It would be nice to have the documents in version control, and it would be good to allow patches to simultaneously update the code and documentation. However, modifying wiki syntax from an editor isn't that easy.
I don't see editing wiki syntax in $editor as a problem.
The really long lines are annoying to work with. git-send-email even complains about lines over 998 characters long.
Oh, didn't notice this detail. Just scanned the patch briefly and with the email client breaking lines it wasn't that obvious.
That is annoying indeed.
But what is the plan for the wiki then? Discontinue? Switch to read-only and update from git? Two-way sync between wiki+git?
Update the wiki from git. Right now, only I have write access to the wiki anyway (as no one has requested a wiki account). A solution other than a wiki is also possible, but that wasn't something I was thinking of, at least in the short term.
So wiki-style editing isn't a strong requirement.
Going with something else which is easier to work with while maintaining the ability to generate html pages from it looks like a good way forward to me. Also generating static pages would remove the need to maintain the wiki software.
I don't have good suggestions for a format / software though.
cheers, Gerd
On Wed, Dec 17, 2014 at 03:13:47PM +0100, Gerd Hoffmann wrote:
On Mi, 2014-12-17 at 08:24 -0500, Kevin O'Connor wrote:
But what is the plan for the wiki then? Discontinue? Switch to read-only and update from git? Two-way sync between wiki+git?
Update the wiki from git. Right now, only I have write access to the wiki anyway (as no one has requested a wiki account). A solution other than a wiki is also possible, but that wasn't something I was thinking of, at least in the short term.
So wiki-style editing isn't a strong requirement.
Right.
Going with something else which is easier to work with while maintaining the ability to generate html pages from it looks like a good way forward to me. Also generating static pages would remove the need to maintain the wiki software.
The coreboot admins are doing the maintenance right now though. :-)
I don't have good suggestions for a format / software though.
Markdown seems popular, and there are translators to other formats. I'm not that familiar with it though.
-Kevin
On Wed, 2014-12-17 at 09:30 -0500, Kevin O'Connor wrote:
I don't have good suggestions for a format / software though.
Markdown seems popular, and there are translators to other formats. I'm not that familiar with it though.
ikiwiki (https://ikiwiki.info/) is quite a nice git+markdown based static wiki compiler (and more, I use it for blogging for example).
Ian.
-
Gerd Hoffmann -
Ian Campbell -
Kevin O'Connor -
Markus Armbruster