v86 0.4.0 → 0.5.11

package/bios/seabios/docs/Debugging.md

@@ -1,111 +0,0 @@
-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).
-
-Timing debug messages
-=====================
-
-The SeaBIOS repository has a tool (**scripts/readserial.py**) that can
-timestamp each diagnostic message produced. The timestamps can provide
-some additional information on how long internal processes take. It
-also provides a simple profiling mechanism.
-
-The tool can be used on coreboot builds that have diagnostic messages
-sent to a serial port. Make sure SeaBIOS is configured with
-CONFIG_DEBUG_SERIAL and run the following on the host receiving serial
-output:
-
-`/path/to/seabios/scripts/readserial.py /dev/ttyS0 115200`
-
-Update the above command with the appropriate serial device and baud
-rate.
-
-The tool can also timestamp the messages from the QEMU debug port. To
-use with QEMU run the following:
-
-```
-mkfifo qemudebugpipe
-qemu -chardev pipe,path=qemudebugpipe,id=seabios -device isa-debugcon,iobase=0x402,chardev=seabios ...
-```
-
-And then in another session:
-
-`/path/to/seabios/scripts/readserial.py -nf qemudebugpipe`
-
-The mkfifo command only needs to be run once to create the pipe file.
-
-When readserial.py is running, it shows a timestamp with millisecond
-precision of the amount of time since the start of the log. If one
-presses the "enter" key in the readserial.py session it will add a
-blank line to the screen and also reset the time back to zero. The
-readserial.py program also keeps a log of all output in files that
-look like "seriallog-YYYYMMDD_HHMMSS.log".
-
-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 it is necessary to load the 16bit symbols
-twice in order for gdb to properly handle break points.  To do this,
-run the following command `objcopy --adjust-vma 0xf0000 out/rom16.o
-rom16offset.o` and then run the following in gdb:
-
-```
-set architecture i8086
-add-symbol-file rom16offset.o 0
-```
-
-To debug a VGA BIOS image, run `gdb out/vgarom.o`, create a
-vgaromoffset.o file with offset 0xc0000, add use the gdb
-command `add-symbol-file out/vgaromoffset.o 0` 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.

package/bios/seabios/docs/Developer_Documentation.md

@@ -1,25 +0,0 @@
-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. For specific information on building SeaBIOS for coreboot,
-please see the [coreboot SeaBIOS](http://www.coreboot.org/SeaBIOS)
-page.
-
-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). A description of the process of linking the final
-SeaBIOS binary is available at [Linking overview](Linking overview).
-
-The list of available runtime configuration items is at
-[runtime config](Runtime_config).
-
-To debug SeaBIOS and report problems see SeaBIOS
-[debugging](Debugging). To contribute changes to SeaBIOS see
-[contributing](Contributing).
-
-Useful links to specifications is available at [Developer
-links](Developer links).

package/bios/seabios/docs/Developer_links.md

@@ -1,86 +0,0 @@
-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>

package/bios/seabios/docs/Download.md

@@ -1,27 +0,0 @@
-SeaBIOS may be distributed under the terms of the [GNU
-LGPLv3](https://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](https://git-scm.com/) revision
-control system. To download the latest source from revision control,
-run:
-
-```
-$ git clone https://git.seabios.org/seabios.git
-$ 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:
-
-<https://www.seabios.org/downloads/>
-
-Please see [releases](Releases) for information on each release.

package/bios/seabios/docs/Execution_and_code_flow.md

@@ -1,178 +0,0 @@
-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
-orchestrated 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](Linking overview#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 immediately 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 hard drive to spin-up 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 expectations (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 adequate 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.

package/bios/seabios/docs/Linking_overview.md

@@ -1,160 +0,0 @@
-This page describes the process that the SeaBIOS build uses to link
-the compiled code into the final binary objects.
-
-Unfortunately, the SeaBIOS linking phase is complex. This complexity
-is due to several unusual requirements:
-
-* Some BIOS entry points must reside at specific hardcoded memory
-  locations. The build must support positioning code and variables at
-  specific locations.
-* In order to support multiple [memory models](Memory Model) the same
-  C code can be complied in three modes (16bit mode, 32bit segmented
-  mode, and 32bit "flat" mode). Binary code from these three modes
-  must be able to co-exist and on occasion reference each other.
-* There is a finite amount of memory available to the BIOS. The build
-  will attempt to weed out unused code and variables from the final
-  binary. It also supports self-relocation of one-time initialization
-  code.
-
-Code layout
-===========
-
-To support the unusual build requirements, several
-[gcc](http://en.wikipedia.org/wiki/GNU_Compiler_Collection) compiler
-options are used. The "-ffunction-sections" and "-fdata-sections"
-flags instruct the compiler to place each variable and function into
-its own
-[ELF](http://en.wikipedia.org/wiki/Executable_and_Linkable_Format)
-section.
-
-The C code is compiled three times into three separate objects for
-each of the major supported [memory models](Memory Model):
-**code16.o**, **code32seg.o**, and **code32flat.o**. Information on
-the sections and symbols of these three objects are extracted (using
-**objdump**) and passed in to the **scripts/layoutrom.py** python
-script. This script analyzes this information and produces gnu
-[ld](http://en.wikipedia.org/wiki/GNU_linker) "linker scripts" which
-provide precise location information to the linker. These linker
-scripts are then used during the link phase which produces a **rom.o**
-object containing all the code.
-
-Fixed location entry points
----------------------------
-
-The build supports placing code entry points and variables at fixed
-memory locations. This support is required in order to support the
-legacy BIOS standards. For example, a program might execute an "int
-0x15" to request system information from the BIOS, but another old
-program might use "ljmpw $0xf000, $0xf859" instead. Both must provide
-the same results and so the build must position the 0x15 interrupt
-entry point in physical memory at 0xff859.
-
-This support is accomplished by placing the given code/variables into
-ELF sections that have a name containing the substring
-".fixedaddr.0x1234" (where 0x1234 is the desired address). For
-variables in C code this is accomplished by marking the variables with
-the VARFSEGFIXED(0x1234) macro. For assembler entry points the ORG
-macro is used (see **romlayout.S**).
-
-During the build, the **layoutrom.py** script will detect sections
-that contain the ".fixedaddr." substring and will arrange for the
-final linker scripts to specify the desired address for the given
-section.
-
-Due to the sparse nature of these fixed address sections, the
-layoutrom.py script will also arrange to pack in other unrelated 16bit
-code into the free space between fixed address sections (see
-layoutrom.py:fitSections()). This maximizes the space available and
-reduces the overall size of the final binary.
-
-C code in three modes
----------------------
-
-SeaBIOS must support multiple [memory models](Memory Model). This is
-accomplished by compiling the C code three separate times into three
-separate objects.
-
-The C code within a mode must not accidentally call a C function in
-another mode, but multiple modes must all access the same single copy
-of global variables. Further, it is occasionally necessary for the C
-code in one mode to obtain the address of C code in another mode.
-
-In order to use the same global variables between all modes, the
-layoutrom.py script will detect references to global variables and
-emit specific symbol definitions for those global variables in the
-linker scripts so that all references use the same physical memory
-address (see layoutrom.py:outXRefs()).
-
-To ensure C code does not accidentally call C code compiled in a
-different mode, the build will ensure the symbols for C code in each
-mode are isolated from each other during the linking stage. To support
-those situations where an address of a C function in another mode is
-required the build supports symbols with a special "\_cfuncX_"
-prefix. The layoutrom.py script detects these references and will emit
-a corresponding symbol definitions in the linker script that points to
-the C code of the specified mode. The call32() and stack_hop_back()
-macros automatically add the required prefix for C code, but the
-prefixes need to be explicitly added in assembler code.
-
-Build garbage collection
-------------------------
-
-To reduce the overall size of the final SeaBIOS binary the build
-supports automatically weeding out of unused code and variables. This
-is done with two separate processes: when supported the gcc
-"-fwhole-program" compilation flag is used, and the layoutrom.py
-script checks for unreferenced ELF sections. The layoutrom.py script
-builds the final linker scripts with only referenced ELF sections, and
-thus unreferenced sections are weeded out from the final objects.
-
-When writing C code, it is necessary to mark C functions with the
-VISIBLE16, VISIBLE32SEG, or VISIBLE32FLAT macros if the functions are
-ever referenced from assembler code. These macros ensure the
-corresponding C function is emitted by the C compiler when compiling
-for the given memory mode. These macros, however, do not affect the
-layoutrom.py reference check, so even a function decorated with one of
-the above macros can be weeded out from the final object if it is
-never referenced.
-
-Code relocation
----------------
-
-To further reduce the runtime memory size of the BIOS, the build
-supports runtime self-relocation. Normally SeaBIOS is loaded into
-memory in the memory region at 0xC0000-0x100000. This is convenient
-for initial binary deployment, but the space competes with memory
-requirements for Option ROMs, BIOS tables, and runtime storage. By
-default, SeaBIOS will self-relocate its one-time initialization code
-to free up space in this region.
-
-To support this feature, the build attempts to automatically detect
-which C code is exclusively initialization phase code (see
-layoutrom.py:checkRuntime()). It does this by finding all functions
-decorated with the VISIBLE32INIT macro and all functions only
-reachable via functions with that macro. These "init only" functions
-are then grouped together and their location and size is stored in the
-binary for the runtime code to relocate (see post.c:reloc_preinit()).
-
-The build also locates all cross section code references along with
-all absolute memory addresses in the "init only" code. These addresses
-need to be modified with the new run-time address in order for the
-code to successfully run at a new address. The build finds the
-location of the addresses (see layoutrom.py:getRelocs()) and stores
-the information in the final binary.
-
-Final binary checks
-===================
-
-At the conclusion of the main linking stage, the code is contained in
-the file **rom.o**. This object file contains all of the assembler
-code, variables, and the C code from all three memory model modes.
-
-At this point the **scripts/checkrom.py** script is run to perform
-final checks on the code. The script performs some sanity checks, it
-may update some tables in the binary, and it reports some size
-information.
-
-After the checkrom.py script is run the final user visible binary is
-produced. The name of the final binary is either **bios.bin**,
-**Csm16.bin**, or **bios.bin.elf** depending on the SeaBIOS build
-requested.

package/bios/seabios/docs/Mailinglist.md

@@ -1,8 +0,0 @@
-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/>