Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 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 |
Kevin O'Connor | 59fead6 | 2008-05-10 15:49:20 -0400 | [diff] [blame] | 5 | resulting file "out/bios.bin" contains the processed bios image. |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 6 | |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 7 | The build requires gcc v4.1 or later. Some buggy versions of gcc have |
| 8 | issues with the '-combine' compiler option - in particular, recent |
| 9 | versions of Ubuntu are affected. One can use "make AVOIDCOMBINE=1" to |
| 10 | get around this. |
| 11 | |
| 12 | |
| 13 | Testing of images: |
| 14 | |
| 15 | To test the bios under bochs, one will need to instruct bochs to use |
| 16 | the new bios image. Use the 'romimage' option - for example: |
| 17 | |
Kevin O'Connor | 59fead6 | 2008-05-10 15:49:20 -0400 | [diff] [blame] | 18 | bochs -q 'floppya: 1_44=myfdimage.img' 'romimage: file=out/bios.bin' |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 19 | |
| 20 | To test under qemu, one will need to create a directory with all the |
| 21 | bios images and then overwrite the main bios image. For example: |
| 22 | |
| 23 | cp /usr/share/qemu/*.bin mybiosdir/ |
Kevin O'Connor | 59fead6 | 2008-05-10 15:49:20 -0400 | [diff] [blame] | 24 | cp out/bios.bin mybiosdir/ |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 25 | |
| 26 | Once this is setup, one can instruct qemu to use the newly created |
| 27 | directory for rom images. For example: |
| 28 | |
| 29 | qemu -L mybiosdir/ -fda myfdimage.img |
| 30 | |
| 31 | |
| 32 | The following payloads have been tested: |
| 33 | |
| 34 | Freedos - see http://www.freedos.org/ . Useful tests include: booting |
| 35 | from installation cdrom, installing to hard drive and floppy, making |
| 36 | sure hard drive and floppy boots then work. It is also useful to take |
| 37 | the bootable floppy and hard-drive images, write them to an el-torito |
| 38 | bootable cdrom using the Linux mkisofs utility, and then boot those |
| 39 | cdrom images. |
| 40 | |
| 41 | Linux - useful hard drive image available from |
| 42 | http://fabrice.bellard.free.fr/qemu/linux-0.2.img.bz2 . It is also |
| 43 | useful to test standard distribution bootup and live cdroms. |
| 44 | |
| 45 | NetBSD - useful hard drive image available from |
| 46 | http://nopid.free.fr/small.ffs.bz2 . It is also useful to test |
| 47 | standard distribution installation cdroms. |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 48 | |
| 49 | |
| 50 | Overview of files: |
| 51 | |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 52 | The src/ directory contains the bios source code. Several of the |
| 53 | files are compiled twice - once for 16bit mode and once for 32bit |
Kevin O'Connor | 0bb2a44 | 2008-04-01 21:09:05 -0400 | [diff] [blame] | 54 | mode. (The gcc compile option '-fwhole-program' is used to remove |
| 55 | code that is not needed for a particular mode.) |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 56 | |
| 57 | The tools/ directory contains helper utilities for manipulating and |
| 58 | building the final rom. |
| 59 | |
| 60 | The out/ directory is created by the build process - it contains all |
| 61 | temporary and final files. |
| 62 | |
| 63 | |
| 64 | Build overview: |
| 65 | |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 66 | The 16bit code is compiled via gcc to assembler (file out/ccode.16.s). |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 67 | The gcc "-fwhole-program" option is used to optimize the process so |
Kevin O'Connor | 0bb2a44 | 2008-04-01 21:09:05 -0400 | [diff] [blame] | 68 | that gcc can efficiently compile and discard unneeded code. (In the |
| 69 | code, one can use the macros 'VISIBLE16' and 'VISIBLE32' to instruct a |
| 70 | symbol to be outputted in 16bit and 32bit mode respectively.) |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 71 | |
| 72 | This resulting assembler code is pulled into romlayout.S. The gas |
| 73 | option ".code16gcc" is used prior to including the gcc generated |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 74 | assembler - this option enables gcc to generate valid 16 bit code. |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 75 | |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 76 | The post code (post.c) is entered, via the function _start(), in 32bit |
| 77 | mode. The 16bit post vector (in romlayout.S) transitions the cpu into |
| 78 | 32 bit mode before calling the post.c code. |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 79 | |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 80 | In the last step of compilation, the 32 bit code is merged into the 16 |
| 81 | bit code so that one binary file contains both. Currently, both 16bit |
| 82 | and 32bit code will be located in the 64K block at segment 0xf000. |
Kevin O'Connor | f076a3e | 2008-02-25 22:25:15 -0500 | [diff] [blame] | 83 | |
| 84 | |
| 85 | GCC 16 bit limitations: |
| 86 | |
| 87 | Although the 16bit code is compiled with gcc, developers need to be |
| 88 | aware of the environment. In particular, global variables _must_ be |
| 89 | treated specially. |
| 90 | |
| 91 | The code has full access to stack variables and general purpose |
| 92 | registers. The entry code in romlayout.S will push the original |
| 93 | registers on the stack before calling the C code and then pop them off |
| 94 | (including any required changes) before returning from the interrupt. |
| 95 | Changes to CS, DS, and ES segment registers in C code is also safe. |
| 96 | Changes to other segment registers (SS, FS, GS) need to be restored |
| 97 | manually. |
| 98 | |
| 99 | Stack variables (and pointers to stack variables) work as they |
| 100 | normally do in standard C code. |
| 101 | |
| 102 | However, variables stored outside the stack need to be accessed via |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 103 | the GET_VAR and SET_VAR macros (or one of the helper macros described |
| 104 | below). This is due to the 16bit segment nature of the X86 cpu when |
| 105 | it is in "real mode". The C entry code will set DS and SS to point to |
| 106 | the stack segment. Variables not on the stack need to be accessed via |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 107 | an explicit segment register. Any other access requires altering one |
| 108 | of the other segment registers (usually ES) and then accessing the |
| 109 | variable via that segment register. |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 110 | |
| 111 | There are three low-level ways to access a remote variable: |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 112 | GET/SET_VAR, GET/SET_FARVAR, and GET/SET_FLATPTR. The first set takes |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 113 | an explicit segment descriptor (eg, "CS") and offset. The second set |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 114 | will take a segment id and offset, set ES to the segment id, and then |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 115 | make the access via the ES segment. The last method is similar to the |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 116 | second, except it takes a pointer that would be valid in 32-bit flat |
| 117 | mode instead of a segment/offset pair. |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 118 | |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 119 | Most BIOS variables are stored in global variables, the "BDA", or |
| 120 | "EBDA" memory areas. Because this is common, three sets of helper |
| 121 | macros (GET/SET_GLOBAL, GET/SET_BDA, and GET/SET_EBDA) are available |
| 122 | to simplify these accesses. |
| 123 | |
| 124 | Global variables defined in the C code can be read in 16bit mode if |
| 125 | the variable declaration is marked with VAR16 or VAR16_32. The |
| 126 | GET_GLOBAL macro will then allow read access to the variable. Global |
| 127 | variables are stored in the 0xf000 segment, and their values are |
| 128 | persistent across soft resets. Because the f-segment is marked |
| 129 | read-only during run-time, the 16bit code is not permitted to change |
| 130 | the value of 16bit variables (use of the SET_GLOBAL macro from 16bit |
| 131 | mode will cause a link error). Code running in 32bit mode can not |
| 132 | access variables with VAR16, but can access variables marked with |
| 133 | VAR16_32 or with no marking at all. The 32bit code can use the |
| 134 | GET/SET_GLOBAL macros, but they are not required. |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 135 | |
| 136 | |
| 137 | GCC 16 bit stack limitations: |
| 138 | |
| 139 | Another limitation of gcc is its use of 32-bit temporaries. Gcc will |
| 140 | allocate 32-bits of space for every variable - even if that variable |
| 141 | is only defined as a 'u8' or 'u16'. If one is not careful, using too |
| 142 | much stack space can break old DOS applications. |
| 143 | |
| 144 | There does not appear to be explicit documentation on the minimum |
| 145 | stack space available for bios calls. However, Freedos has been |
Kevin O'Connor | 0bb2a44 | 2008-04-01 21:09:05 -0400 | [diff] [blame] | 146 | observed to call into the bios with less than 150 bytes available. |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 147 | |
| 148 | Note that the post code and boot code (irq 18/19) do not have a stack |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 149 | limitation because the entry points for these functions transition the |
| 150 | cpu to 32bit mode and reset the stack to a known state. Only the |
| 151 | general purpose 16-bit service entry points are affected. |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 152 | |
| 153 | There are some ways to reduce stack usage: making sure functions are |
| 154 | tail-recursive often helps, reducing the number of parameters passed |
| 155 | to functions often helps, sometimes reordering variable declarations |
| 156 | helps, inlining of functions can sometimes help, and passing of packed |
Kevin O'Connor | 0afee52 | 2009-02-05 20:32:41 -0500 | [diff] [blame] | 157 | structures can also help. It is also possible to transition to/from |
| 158 | an extra stack stored in the EBDA using the stack_hop helper function. |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 159 | |
Kevin O'Connor | 0bb2a44 | 2008-04-01 21:09:05 -0400 | [diff] [blame] | 160 | Some useful stats: the overhead for the entry to a bios handler that |
| 161 | takes a 'struct bregs' is 38 bytes of stack space (6 bytes from |
| 162 | interrupt insn, 28 bytes to store registers, and 4 bytes for call |
| 163 | insn). An entry to an ISR handler without args takes 30 bytes (6 + 20 |
| 164 | + 4). |
| 165 | |
Kevin O'Connor | 838f08f | 2008-03-30 11:07:42 -0400 | [diff] [blame] | 166 | |
| 167 | Debugging the bios: |
| 168 | |
| 169 | The bios will output information messages to a special debug port. |
| 170 | Under qemu, one can view these messages by enabling the '#define |
| 171 | DEBUG_BIOS' definition in 'qemu/hw/pc.c'. Once this is done (and qemu |
| 172 | is recompiled), one should see status messages on the console. |
| 173 | |
| 174 | The gdb-server mechanism of qemu is also useful. One can use gdb with |
| 175 | qemu to debug system images. To use this, add '-s -S' to the qemu |
| 176 | command line. For example: |
| 177 | |
| 178 | qemu -L mybiosdir/ -fda myfdimage.img -s -S |
| 179 | |
| 180 | Then, in another session, run gdb with either out/rom16.o (to debug |
| 181 | bios 16bit code) or out/rom32.o (to debug bios 32bit code). For |
| 182 | example: |
| 183 | |
| 184 | gdb out/rom16.o |
| 185 | |
| 186 | Once in gdb, use the command "target remote localhost:1234" to have |
| 187 | gdb connect to qemu. See the qemu documentation for more information |
| 188 | on using gdb and qemu in this mode. Note that gdb seems to get |
| 189 | breakpoints confused when the cpu is in 16-bit real mode. This makes |
| 190 | stepping through the program difficult (though 'step instruction' |
| 191 | still works). Also, one may need to set 16bit break points at both |
| 192 | the cpu address and memory address (eg, break *0x1234 ; break |
| 193 | *0xf1234). |