Reduce stack usage in call16().
[people/mcb30/legacybios.git] / README
1 This code implements an X86 legacy bios.  It is intended to be
2 compiled using standard gnu tools (eg, gas and gcc).
3
4 To build, one should be able to run "make" in the main directory.  The
5 resulting file "out/rom.bin" contains the processed bios image.
6
7 The code has been successfully compiled with gcc 4.1.2 and gas
8 2.17.50.0.18.
9
10
11 Overview of files:
12
13 The src/ directory contains the bios source code.  The post.c code is
14 compiled in 32bit mode.  The output.c code is compiled twice - once in
15 16bit mode and once in 32bit mode.  The remaining c files are compiled
16 in 16bit mode.
17
18 The tools/ directory contains helper utilities for manipulating and
19 building the final rom.
20
21 The out/ directory is created by the build process - it contains all
22 temporary and final files.
23
24
25 Build overview:
26
27 The 16bit code is compiled via gcc to assembler (file out/blob.16.s).
28 The gcc "-fwhole-program" option is used to optimize the process so
29 that gcc can efficiently compile and discard unneeded code.
30
31 This resulting assembler code is pulled into romlayout.S.  The gas
32 option ".code16gcc" is used prior to including the gcc generated
33 assembler - this option enables gcc to be used to generate valid 16
34 bit code.  The romlayout.S also defines all the mandatory bios visible
35 memory locations.
36
37 The post code (post.c) is written in 32bits.  The 16bit post vector
38 (in romlayout.S) transitions the cpu into 32 bit mode before calling
39 the initialization code in post.c.
40
41 In the last step, the compiled 32 bit code is merged into the 16 bit
42 code so that one binary file contains both.  Currently, both 16bit and
43 32bit code will be located in the 64K block at segment 0xf000.
44
45
46 GCC 16 bit limitations:
47
48 Although the 16bit code is compiled with gcc, developers need to be
49 aware of the environment.  In particular, global variables _must_ be
50 treated specially.
51
52 The code has full access to stack variables and general purpose
53 registers.  The entry code in romlayout.S will push the original
54 registers on the stack before calling the C code and then pop them off
55 (including any required changes) before returning from the interrupt.
56 Changes to CS, DS, and ES segment registers in C code is also safe.
57 Changes to other segment registers (SS, FS, GS) need to be restored
58 manually.
59
60 Stack variables (and pointers to stack variables) work as they
61 normally do in standard C code.
62
63 However, variables stored outside the stack need to be accessed via
64 the GET_VAR and SET_VAR macros.  This is due to the 16bit segment
65 nature of the X86 cpu when it is in "real mode".  The C entry code
66 will set DS and SS to point to the stack segment.  Variables not on
67 the stack need to be accessed via an explicit segment register.
68 Global constant definitions (those in 0xf000) can be accessed via the
69 CS segment register.  Any other access requires altering one of the
70 other segment registers (usually ES) and then accessing the variable
71 via that segment register.