blob: a87a0ad58c65ac7b07a36c8a75aae7dfcc9d52b9 [file] [log] [blame]
Kevin O'Connorf076a3e2008-02-25 22:25:15 -05001This code implements an X86 legacy bios. It is intended to be
2compiled using standard gnu tools (eg, gas and gcc).
4To build, one should be able to run "make" in the main directory. The
Kevin O'Connor59fead62008-05-10 15:49:20 -04005resulting file "out/bios.bin" contains the processed bios image.
Kevin O'Connorf076a3e2008-02-25 22:25:15 -05006
Kevin O'Connor838f08f2008-03-30 11:07:42 -04007
8Testing of images:
10To test the bios under bochs, one will need to instruct bochs to use
11the new bios image. Use the 'romimage' option - for example:
Kevin O'Connor59fead62008-05-10 15:49:20 -040013bochs -q 'floppya: 1_44=myfdimage.img' 'romimage: file=out/bios.bin'
Kevin O'Connor838f08f2008-03-30 11:07:42 -040014
15To test under qemu, one will need to create a directory with all the
16bios images and then overwrite the main bios image. For example:
18cp /usr/share/qemu/*.bin mybiosdir/
Kevin O'Connor59fead62008-05-10 15:49:20 -040019cp out/bios.bin mybiosdir/
Kevin O'Connorac467be2013-03-17 10:29:06 -040020cp out/*.aml mybiosdir/
Kevin O'Connor838f08f2008-03-30 11:07:42 -040021
22Once this is setup, one can instruct qemu to use the newly created
23directory for rom images. For example:
25qemu -L mybiosdir/ -fda myfdimage.img
Kevin O'Connorf076a3e2008-02-25 22:25:15 -050028Overview of files:
Kevin O'Connor838f08f2008-03-30 11:07:42 -040030The src/ directory contains the bios source code. Several of the
31files are compiled twice - once for 16bit mode and once for 32bit
Kevin O'Connor0942e7f2009-06-15 22:27:01 -040032mode. (The build system will remove code that is not needed for a
33particular mode.)
Kevin O'Connorf076a3e2008-02-25 22:25:15 -050034
35The tools/ directory contains helper utilities for manipulating and
36building the final rom.
38The out/ directory is created by the build process - it contains all
39temporary and final files.
42Build overview:
Kevin O'Connor0afee522009-02-05 20:32:41 -050044The 16bit code is compiled via gcc to assembler (file out/ccode.16.s).
Kevin O'Connor0942e7f2009-06-15 22:27:01 -040045The gcc "-fwhole-program" and "-ffunction-sections -fdata-sections"
46options are used to optimize the process so that gcc can efficiently
47compile and discard unneeded code. (In the code, one can use the
Kevin O'Connor0fdf1932011-10-04 21:12:28 -040048macros 'VISIBLE16' and 'VISIBLE32FLAT' to instruct a symbol to be
Kevin O'Connor0942e7f2009-06-15 22:27:01 -040049outputted in 16bit and 32bit mode respectively.)
Kevin O'Connorf076a3e2008-02-25 22:25:15 -050050
51This resulting assembler code is pulled into romlayout.S. The gas
52option ".code16gcc" is used prior to including the gcc generated
Kevin O'Connor838f08f2008-03-30 11:07:42 -040053assembler - this option enables gcc to generate valid 16 bit code.
Kevin O'Connorf076a3e2008-02-25 22:25:15 -050054
Kevin O'Connor0fdf1932011-10-04 21:12:28 -040055The post code (post.c) is entered, via the function handle_post(), in
5632bit mode. The 16bit post vector (in romlayout.S) transitions the
57cpu into 32 bit mode before calling the post.c code.
Kevin O'Connorf076a3e2008-02-25 22:25:15 -050058
Kevin O'Connor838f08f2008-03-30 11:07:42 -040059In the last step of compilation, the 32 bit code is merged into the 16
60bit code so that one binary file contains both. Currently, both 16bit
Kevin O'Connor0fdf1932011-10-04 21:12:28 -040061and 32bit code will be located in the memory at 0xe0000-0xfffff.
Kevin O'Connorf076a3e2008-02-25 22:25:15 -050062
64GCC 16 bit limitations:
66Although the 16bit code is compiled with gcc, developers need to be
67aware of the environment. In particular, global variables _must_ be
68treated specially.
70The code has full access to stack variables and general purpose
71registers. The entry code in romlayout.S will push the original
72registers on the stack before calling the C code and then pop them off
73(including any required changes) before returning from the interrupt.
74Changes to CS, DS, and ES segment registers in C code is also safe.
75Changes to other segment registers (SS, FS, GS) need to be restored
78Stack variables (and pointers to stack variables) work as they
79normally do in standard C code.
81However, variables stored outside the stack need to be accessed via
Kevin O'Connor838f08f2008-03-30 11:07:42 -040082the GET_VAR and SET_VAR macros (or one of the helper macros described
83below). This is due to the 16bit segment nature of the X86 cpu when
84it is in "real mode". The C entry code will set DS and SS to point to
85the stack segment. Variables not on the stack need to be accessed via
Kevin O'Connor0afee522009-02-05 20:32:41 -050086an explicit segment register. Any other access requires altering one
87of the other segment registers (usually ES) and then accessing the
88variable via that segment register.
Kevin O'Connor838f08f2008-03-30 11:07:42 -040089
90There are three low-level ways to access a remote variable:
Kevin O'Connor0afee522009-02-05 20:32:41 -050091GET/SET_VAR, GET/SET_FARVAR, and GET/SET_FLATPTR. The first set takes
Kevin O'Connor838f08f2008-03-30 11:07:42 -040092an explicit segment descriptor (eg, "CS") and offset. The second set
Kevin O'Connor0afee522009-02-05 20:32:41 -050093will take a segment id and offset, set ES to the segment id, and then
Kevin O'Connor838f08f2008-03-30 11:07:42 -040094make the access via the ES segment. The last method is similar to the
Kevin O'Connor0afee522009-02-05 20:32:41 -050095second, except it takes a pointer that would be valid in 32-bit flat
96mode instead of a segment/offset pair.
Kevin O'Connor838f08f2008-03-30 11:07:42 -040097
Kevin O'Connor0afee522009-02-05 20:32:41 -050098Most BIOS variables are stored in global variables, the "BDA", or
99"EBDA" memory areas. Because this is common, three sets of helper
100macros (GET/SET_GLOBAL, GET/SET_BDA, and GET/SET_EBDA) are available
101to simplify these accesses.
103Global variables defined in the C code can be read in 16bit mode if
Kevin O'Connor372e0712009-09-09 09:51:31 -0400104the variable declaration is marked with VAR16, VAR16VISIBLE,
105VAR16EXPORT, or VAR16FIXED. The GET_GLOBAL macro will then allow read
106access to the variable. Global variables are stored in the 0xf000
Kevin O'Connor88ab34e2013-01-20 10:46:51 -0500107segment. Because the f-segment is marked read-only during run-time,
108the 16bit code is not permitted to change the value of 16bit variables
109(use of the SET_GLOBAL macro from 16bit mode will cause a link error).
110Code running in 32bit mode can not access variables with VAR16, but
111can access variables marked with VAR16VISIBLE, VAR16EXPORT,
112VAR16FIXED, or with no marking at all. The 32bit code can use the
113GET/SET_GLOBAL macros, but they are not required.
Kevin O'Connor838f08f2008-03-30 11:07:42 -0400114
116GCC 16 bit stack limitations:
118Another limitation of gcc is its use of 32-bit temporaries. Gcc will
119allocate 32-bits of space for every variable - even if that variable
120is only defined as a 'u8' or 'u16'. If one is not careful, using too
121much stack space can break old DOS applications.
123There does not appear to be explicit documentation on the minimum
124stack space available for bios calls. However, Freedos has been
Kevin O'Connor0bb2a442008-04-01 21:09:05 -0400125observed to call into the bios with less than 150 bytes available.
Kevin O'Connor838f08f2008-03-30 11:07:42 -0400126
127Note that the post code and boot code (irq 18/19) do not have a stack
Kevin O'Connor0afee522009-02-05 20:32:41 -0500128limitation because the entry points for these functions transition the
129cpu to 32bit mode and reset the stack to a known state. Only the
130general purpose 16-bit service entry points are affected.
Kevin O'Connor838f08f2008-03-30 11:07:42 -0400131
132There are some ways to reduce stack usage: making sure functions are
133tail-recursive often helps, reducing the number of parameters passed
134to functions often helps, sometimes reordering variable declarations
135helps, inlining of functions can sometimes help, and passing of packed
Kevin O'Connor0afee522009-02-05 20:32:41 -0500136structures can also help. It is also possible to transition to/from
137an extra stack stored in the EBDA using the stack_hop helper function.
Kevin O'Connor838f08f2008-03-30 11:07:42 -0400138
Kevin O'Connor0bb2a442008-04-01 21:09:05 -0400139Some useful stats: the overhead for the entry to a bios handler that
Kevin O'Connor0942e7f2009-06-15 22:27:01 -0400140takes a 'struct bregs' is 42 bytes of stack space (6 bytes from
141interrupt insn, 32 bytes to store registers, and 4 bytes for call
Kevin O'Connor0bb2a442008-04-01 21:09:05 -0400142insn). An entry to an ISR handler without args takes 30 bytes (6 + 20
143+ 4).
Kevin O'Connor838f08f2008-03-30 11:07:42 -0400145
146Debugging the bios:
148The bios will output information messages to a special debug port.
Kevin O'Connor0fdf1932011-10-04 21:12:28 -0400149Under qemu, one can view these messages by adding '-chardev
150stdio,id=seabios -device isa-debugcon,iobase=0x402,chardev=seabios' to
151the qemu command line. Once this is done, one should see status
152messages on the console.
Kevin O'Connor838f08f2008-03-30 11:07:42 -0400153
154The gdb-server mechanism of qemu is also useful. One can use gdb with
155qemu to debug system images. To use this, add '-s -S' to the qemu
156command line. For example:
158qemu -L mybiosdir/ -fda myfdimage.img -s -S
160Then, in another session, run gdb with either out/rom16.o (to debug
161bios 16bit code) or out/rom32.o (to debug bios 32bit code). For
164gdb out/rom16.o
166Once in gdb, use the command "target remote localhost:1234" to have
167gdb connect to qemu. See the qemu documentation for more information
168on using gdb and qemu in this mode. Note that gdb seems to get
169breakpoints confused when the cpu is in 16-bit real mode. This makes
170stepping through the program difficult (though 'step instruction'
171still works). Also, one may need to set 16bit break points at both
172the cpu address and memory address (eg, break *0x1234 ; break