Simplify README files - point to online documentation instead

The README file and README.CSM file have gotten a bit out of date.
Instead of maintaining technical information in the README file, point
new users to the SeaBIOS wiki.

Signed-off-by: Kevin O'Connor <>
diff --git a/README b/README
index 1e61e2f..e18be16 100644
--- a/README
+++ b/README
@@ -1,182 +1,17 @@
-This code implements an X86 legacy bios.  It is intended to be
-compiled using standard gnu tools (eg, gas and gcc).
+Welcome to the SeaBIOS project!  This project implements an X86 legacy
+bios that is built with standard GNU tools.
-To build for QEMU, one should be able to run "make" in the main
-directory.  The resulting file "out/bios.bin" contains the processed
-bios image.  To build for coreboot, please see the coreboot wiki.  To
-build for CSM, please see README.CSM.
+Please see build and developer information at:
-Testing of images:
+For the impatient, SeaBIOS is built for QEMU and tested on QEMU with:
-To test the bios under bochs, one will need to instruct bochs to use
-the new bios image.  Use the 'romimage' option - for example:
+  make
+  qemu -bios out/bios.bin
-bochs -q 'floppya: 1_44=myfdimage.img' 'romimage: file=out/bios.bin'
+SeaBIOS can be configured with kconfig.  To change the default
+configuration one can run "make menuconfig" prior to running "make".
-To test under qemu, one will need to create a directory with all the
-bios images and then overwrite the main bios image.  For example:
-cp /usr/share/qemu/*.bin mybiosdir/
-cp out/bios.bin mybiosdir/
-cp out/*.aml mybiosdir/
-Once this is setup, one can instruct qemu to use the newly created
-directory for rom images.  For example:
-qemu -L mybiosdir/ -fda myfdimage.img
-Overview of files:
-The src/ directory contains the bios source code.  Several of the
-files are compiled twice - once for 16bit mode and once for 32bit
-mode.  (The build system will remove code that is not needed for a
-particular mode.)
-The vgasrc/ directory contains code for VGA BIOS implementations.
-This code is separate from the main BIOS code in the src/ directory.
-It produces a VGA BIOS rom 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 rom.
-The out/ directory is created by the build process - it contains all
-temporary and final files.
-Build overview:
-The 16bit code is compiled via gcc to assembler (file out/ccode.16.s).
-The gcc "-fwhole-program" and "-ffunction-sections -fdata-sections"
-options are used to optimize the process so that gcc can efficiently
-compile and discard unneeded code.  (In the code, one can use the
-macros 'VISIBLE16' and 'VISIBLE32FLAT' to instruct a symbol to be
-outputted in 16bit and 32bit mode respectively.)
-This resulting assembler code is pulled into romlayout.S.  The gas
-option ".code16gcc" is used prior to including the gcc generated
-assembler - this option enables gcc to generate valid 16 bit code.
-The post code (post.c) is entered, via the function handle_post(), in
-32bit mode.  The 16bit post vector (in romlayout.S) transitions the
-cpu into 32 bit mode before calling the post.c code.
-In the last step of compilation, the 32 bit code is merged into the 16
-bit code so that one binary file contains both.  Currently, both 16bit
-and 32bit code will be located in the memory at 0xe0000-0xfffff.
-GCC 16 bit limitations:
-Although the 16bit code is compiled with gcc, developers need to be
-aware of the environment.  In particular, global variables _must_ be
-treated specially.
-The code has full access to stack variables and general purpose
-registers.  The entry code in romlayout.S will push the original
-registers on the stack before calling the C code and then pop them off
-(including any required changes) before returning from the interrupt.
-Changes to CS, DS, and ES segment registers in C code is also safe.
-Changes to other segment registers (SS, FS, GS) need to be restored
-Stack variables (and pointers to stack variables) work as they
-normally do in standard C code.
-However, variables stored outside the stack need to be accessed via
-the GET_VAR and SET_VAR macros (or one of the helper macros described
-below).  This is due to the 16bit segment nature of the X86 cpu when
-it is in "real mode".  The C entry code will set DS and SS to point to
-the stack segment.  Variables not on the stack need to be accessed via
-an explicit segment register.  Any other access requires altering one
-of the other segment registers (usually ES) and then accessing the
-variable via that segment register.
-There are three low-level ways to access a remote variable:
-GET/SET_VAR, GET/SET_FARVAR, and GET/SET_FLATPTR.  The first set takes
-an explicit segment descriptor (eg, "CS") and offset.  The second set
-will take a segment id and offset, set ES to the segment id, and then
-make the access via the ES segment.  The last method is similar to the
-second, except it takes a pointer that would be valid in 32-bit flat
-mode instead of a segment/offset pair.
-Most BIOS variables are stored in global variables, the "BDA", or
-"EBDA" memory areas.  Because this is common, three sets of helper
-macros (GET_GLOBAL, GET/SET_BDA, and GET/SET_EBDA) are available to
-simplify these accesses.  Also, an area in the 0xc0000-0xf0000 memory
-range is made available for internal BIOS run-time variables that are
-marked with the VARLOW attribute.  These variables can then be
-accessed with the GET/SET_LOW macros.
-Global variables defined in the C code can be read in 16bit mode if
-the variable declaration is marked with VAR16, VARFSEG, or VAR16FIXED.
-The GET_GLOBAL macro will then allow read access to the variable.
-Global variables are stored in the 0xf000 segment.  Because the
-f-segment is marked read-only during run-time, the 16bit code is not
-permitted to change the value of 16bit variables.  Code running in
-32bit mode can not access variables with VAR16, but can access
-variables marked with VARFSEG, VARLOW, VAR16FIXED, or with no marking
-at all.  The 32bit code can use the GET_GLOBAL macros, but they are
-not required.
-GCC 16 bit stack limitations:
-Another limitation of gcc is its use of 32-bit temporaries.  Gcc will
-allocate 32-bits of space for every variable - even if that variable
-is only defined as a 'u8' or 'u16'.  If one is not careful, using too
-much stack space can break old DOS applications.
-There does not appear to be explicit documentation on the minimum
-stack space available for bios calls.  However, Freedos has been
-observed to call into the bios with less than 150 bytes available.
-Note that the post code and boot code (irq 18/19) do not have a stack
-limitation because the entry points for these functions transition the
-cpu to 32bit mode and reset the stack to a known state.  Only the
-general purpose 16-bit service entry points are affected.
-There are some ways to reduce stack usage: making sure functions are
-tail-recursive often helps, reducing the number of parameters passed
-to functions often helps, sometimes reordering variable declarations
-helps, inlining of functions can sometimes help, and passing of packed
-structures can also help.  It is also possible to transition to/from
-an extra stack stored in the EBDA using the stack_hop helper function.
-Some useful stats: the overhead for the entry to a bios handler that
-takes a 'struct bregs' is 42 bytes of stack space (6 bytes from
-interrupt insn, 32 bytes to store registers, and 4 bytes for call
-insn).  An entry to an ISR handler without args takes 30 bytes (6 + 20
-+ 4).
-Debugging the bios:
-The bios will output information messages to a special debug port.
-Under qemu, 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.
-The gdb-server mechanism of qemu is also useful.  One can use gdb with
-qemu to debug system images.  To use this, add '-s -S' to the qemu
-command line.  For example:
-qemu -L mybiosdir/ -fda myfdimage.img -s -S
-Then, in another session, run gdb with either out/rom16.o (to debug
-bios 16bit code) or out/rom32.o (to debug bios 32bit code).  For
-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.  Note that gdb seems to get
-breakpoints confused when the cpu is in 16-bit real mode.  This makes
-stepping through the program difficult (though 'step instruction'
-still works).  Also, one may need to set 16bit break points at both
-the cpu address and memory address (eg, break *0x1234 ; break
+For other types of builds, and for more detailed developer
+documentation, please see the online documentation listed above.