1 @node Internals 2 @appendix Hacking GRUB 3 4 This chapter documents the user-invisible aspect of GRUB. 5 6 As a general rule of software development, it is impossible to keep the 7 descriptions of the internals up-to-date, and it is quite hard to 8 document everything. So refer to the source code, whenever you are not 9 satisfied with this documentation. Please assume that this gives just 10 hints to you. 11 12 @menu 13 * Memory map:: The memory map of various components 14 * Embedded data:: Embedded variables in GRUB 15 * Filesystem interface:: The generic interface for filesystems 16 * Command interface:: The generic interface for built-ins 17 * Bootstrap tricks:: The bootstrap mechanism used in GRUB 18 * I/O ports detection:: How to probe I/O ports used by INT 13H 19 * Memory detection:: How to detect all installed RAM 20 * Low-level disk I/O:: INT 13H disk I/O interrupts 21 * MBR:: The structure of Master Boot Record 22 * Partition table:: The format of partition tables 23 * Submitting patches:: Where and how you should send patches 24 @end menu 25 26 27 @node Memory map 28 @section The memory map of various components 29 30 GRUB consists of two distinct components, called @dfn{stages}, which are 31 loaded at different times in the boot process. Because they run 32 mutual-exclusively, sometimes a memory area overlaps with another 33 memory area. And, even in one stage, a single memory area can be used 34 for various purposes, because their usages are mutually exclusive. 35 36 Here is the memory map of the various components: 37 38 @table @asis 39 @item 0 to 4K-1 40 BIOS and real mode interrupts 41 42 @item 0x07BE to 0x07FF 43 Partition table passed to another boot loader 44 45 @item down from 8K-1 46 Real mode stack 47 48 @item 0x2000 to ? 49 The optional Stage 1.5 is loaded here 50 51 @item 0x2000 to 0x7FFF 52 Command-line buffer for Multiboot kernels and modules 53 54 @item 0x7C00 to 0x7DFF 55 Stage 1 is loaded here by BIOS or another boot loader 56 57 @item 0x7F00 to 0x7F42 58 LBA drive parameters 59 60 @item 0x8000 to ? 61 Stage2 is loaded here 62 63 @item The end of Stage 2 to 416K-1 64 Heap, in particular used for the menu 65 66 @item down from 416K-1 67 Protected mode stack 68 69 @item 416K to 448K-1 70 Filesystem buffer 71 72 @item 448K to 479.5K-1 73 Raw device buffer 74 75 @item 479.5K to 480K-1 76 512-byte scratch area 77 78 @item 480K to 512K-1 79 Buffers for various functions, such as password, command-line, cut and 80 paste, and completion. 81 82 @item The last 1K of lower memory 83 Disk swapping code and data 84 @end table 85 86 See the file @file{stage2/shared.h}, for more information. 87 88 89 @node Embedded data 90 @section Embedded variables in GRUB 91 92 Stage 1 and Stage 2 have embedded variables whose locations are 93 well-defined, so that the installation can patch the binary file 94 directly without recompilation of the stages. 95 96 In Stage 1, these are defined: 97 98 @table @code 99 @item 0x3E 100 The version number (not GRUB's, but the installation mechanism's). 101 102 @item 0x40 103 The boot drive. If it is 0xFF, use a drive passed by BIOS. 104 105 @item 0x41 106 The flag for if forcing LBA. 107 108 @item 0x42 109 The starting address of Stage 2. 110 111 @item 0x44 112 The first sector of Stage 2. 113 114 @item 0x48 115 The starting segment of Stage 2. 116 117 @item 0x1FE 118 The signature (@code{0xAA55}). 119 @end table 120 121 See the file @file{stage1/stage1.S}, for more information. 122 123 In the first sector of Stage 1.5 and Stage 2, the block lists are 124 recorded between @code{firstlist} and @code{lastlist}. The address of 125 @code{lastlist} is determined when assembling the file 126 @file{stage2/start.S}. 127 128 The trick here is that it is actually read backward, and the first 129 8-byte block list is not read here, but after the pointer is decremented 130 8 bytes, then after reading it, it decrements again, reads, and so on, 131 until it is finished. The terminating condition is when the number of 132 sectors to be read in the next block list is zero. 133 134 The format of a block list can be seen from the example in the code just 135 before the @code{firstlist} label. Note that it is always from the 136 beginning of the disk, but @emph{not} relative to the partition 137 boundaries. 138 139 In the second sector of Stage 1.5 and Stage 2, these are defined: 140 141 @table @asis 142 @item @code{0x6} 143 The version number (likewise, the installation mechanism's). 144 145 @item @code{0x8} 146 The installed partition. 147 148 @item @code{0xC} 149 The saved entry number. 150 151 @item @code{0x10} 152 The identifier. 153 154 @item @code{0x11} 155 The flag for if forcing LBA. 156 157 @item @code{0x12} 158 The version string (GRUB's). 159 160 @item @code{0x12} + @dfn{the length of the version string} 161 The name of a configuration file. 162 @end table 163 164 See the file @file{stage2/asm.S}, for more information. 165 166 167 @node Filesystem interface 168 @section The generic interface for filesystems 169 170 For any particular partition, it is presumed that only one of the 171 @dfn{normal} filesystems such as FAT, FFS, or ext2fs can be used, so 172 there is a switch table managed by the functions in 173 @file{disk_io.c}. The notation is that you can only @dfn{mount} one at a 174 time. 175 176 The block list filesystem has a special place in the system. In addition 177 to the @dfn{normal} filesystem (or even without one mounted), you can 178 access disk blocks directly (in the indicated partition) via the block 179 list notation. Using the block list filesystem doesn't effect any other 180 filesystem mounts. 181 182 The variables which can be read by the filesystem backend are: 183 184 @vtable @code 185 @item current_drive 186 The current BIOS drive number (numbered from 0, if a floppy, and 187 numbered from 0x80, if a hard disk). 188 189 @item current_partition 190 The current partition number. 191 192 @item current_slice 193 The current partition type. 194 195 @item saved_drive 196 The @dfn{drive} part of the root device. 197 198 @item saved_partition 199 The @dfn{partition} part of the root device. 200 201 @item part_start 202 The current partition starting address, in sectors. 203 204 @item part_length 205 The current partition length, in sectors. 206 207 @item print_possibilities 208 True when the @code{dir} function should print the possible completions 209 of a file, and false when it should try to actually open a file of that 210 name. 211 212 @item FSYS_BUF 213 Filesystem buffer which is 32K in size, to use in any way which the 214 filesystem backend desires. 215 @end vtable 216 217 The variables which need to be written by a filesystem backend are: 218 219 @vtable @code 220 @item filepos 221 The current position in the file, in sectors. 222 223 @strong{Caution:} the value of @var{filepos} can be changed out from 224 under the filesystem code in the current implementation. Don't depend on 225 it being the same for later calls into the backend code! 226 227 @item filemax 228 The length of the file. 229 230 @item disk_read_func 231 The value of @var{disk_read_hook} @emph{only} during reading of data 232 for the file, not any other fs data, inodes, FAT tables, whatever, then 233 set to @code{NULL} at all other times (it will be @code{NULL} by 234 default). If this isn't done correctly, then the @command{testload} and 235 @command{install} commands won't work correctly. 236 @end vtable 237 238 The functions expected to be used by the filesystem backend are: 239 240 @ftable @code 241 @item devread 242 Only read sectors from within a partition. Sector 0 is the first sector 243 in the partition. 244 245 @item grub_read 246 If the backend uses the block list code, then @code{grub_read} can be 247 used, after setting @var{block_file} to 1. 248 249 @item print_a_completion 250 If @var{print_possibilities} is true, call @code{print_a_completion} for 251 each possible file name. Otherwise, the file name completion won't work. 252 @end ftable 253 254 The functions expected to be defined by the filesystem backend are 255 described at least moderately in the file @file{filesys.h}. Their usage 256 is fairly evident from their use in the functions in @file{disk_io.c}, 257 look for the use of the @var{fsys_table} array. 258 259 @strong{Caution:} The semantics are such that then @samp{mount}ing the 260 filesystem, presume the filesystem buffer @code{FSYS_BUF} is corrupted, 261 and (re-)load all important contents. When opening and reading a file, 262 presume that the data from the @samp{mount} is available, and doesn't 263 get corrupted by the open/read (i.e. multiple opens and/or reads will be 264 done with only one mount if in the same filesystem). 265 266 267 @node Command interface 268 @section The generic interface for built-ins 269 270 GRUB built-in commands are defined in a uniformal interface, whether 271 they are menu-specific or can be used anywhere. The definition of a 272 builtin command consists of two parts: the code itself and the table of 273 the information. 274 275 The code must be a function which takes two arguments, a command-line 276 string and flags, and returns an @samp{int} value. The @dfn{flags} 277 argument specifies how the function is called, using a bit mask. The 278 return value must be zero if successful, otherwise non-zero. So it is 279 normally enough to return @var{errnum}. 280 281 The table of the information is represented by the structure 282 @code{struct builtin}, which contains the name of the command, a pointer 283 to the function, flags, a short description of the command and a long 284 description of the command. Since the descriptions are used only for 285 help messages interactively, you don't have to define them, if the 286 command may not be called interactively (such as @command{title}). 287 288 The table is finally registered in the table @var{builtin_table}, so 289 that @code{run_script} and @code{enter_cmdline} can find the 290 command. See the files @file{cmdline.c} and @file{builtins.c}, for more 291 details. 292 293 294 @node Bootstrap tricks 295 @section The bootstrap mechanism used in GRUB 296 297 The disk space can be used in a boot loader is very restricted because 298 a MBR (@pxref{MBR}) is only 512 bytes but it also contains a partition 299 table (@pxref{Partition table}) and a BPB. So the question is how to 300 make a boot loader code enough small to be fit in a MBR. 301 302 However, GRUB is a very large program, so we break GRUB into 2 (or 3) 303 distinct components, @dfn{Stage 1} and @dfn{Stage 2} (and optionally 304 @dfn{Stage 1.5}). @xref{Memory map}, for more information. 305 306 We embed Stage 1 in a MBR or in the boot sector of a partition, and 307 place Stage 2 in a filesystem. The optional Stage 1.5 can be installed 308 in a filesystem, in the @dfn{boot loader} area in a FFS or a ReiserFS, 309 and in the sectors right after a MBR, because Stage 1.5 is enough small 310 and the sectors right after a MBR is normally an unused region. The size 311 of this region is the number of sectors per head minus 1. 312 313 Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if 314 Stage 1 needs not to support the user interface or the filesystem 315 interface, it is impossible to make Stage 1 less than 400 bytes, because 316 GRUB should support both the CHS mode and the LBA mode (@pxref{Low-level 317 disk I/O}). 318 319 The solution used by GRUB is that Stage 1 loads only the first sector of 320 Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The flow of 321 Stage 1 is: 322 323 @enumerate 324 @item 325 Initialize the system briefly. 326 327 @item 328 Detect the geometry and the accessing mode of the @dfn{loading drive}. 329 330 @item 331 Load the first sector of Stage 2. 332 333 @item 334 Jump to the starting address of the Stage 2. 335 @end enumerate 336 337 The flow of Stage 2 (and Stage 1.5) is: 338 339 @enumerate 340 @item 341 Load the rest of itself to the real starting address, that is, the 342 starting address plus 512 bytes. The block lists are stored in the last 343 part of the first sector. 344 345 @item 346 Long jump to the real starting address. 347 @end enumerate 348 349 Note that Stage 2 (or Stage 1.5) does not probe the geometry 350 or the accessing mode of the @dfn{loading drive}, since Stage 1 has 351 already probed them. 352 353 354 @node I/O ports detection 355 @section How to probe I/O ports used by INT 13H 356 357 FIXME: I will write this chapter after implementing the new technique. 358 359 360 361 @node Memory detection 362 @section How to detect all installed RAM 363 364 FIXME: I doubt if Erich didn't write this chapter only himself wholly, 365 so I will rewrite this chapter. 366 367 368 @node Low-level disk I/O 369 @section INT 13H disk I/O interrupts 370 371 FIXME: I'm not sure where some part of the original chapter is derived, 372 so I will rewrite this chapter. 373 374 375 @node MBR 376 @section The structure of Master Boot Record 377 378 FIXME: Likewise. 379 380 381 @node Partition table 382 @section The format of partition tables 383 384 FIXME: Probably the original chapter is derived from "How It Works", so 385 I will rewrite this chapter. 386 387 388 @node Submitting patches 389 @section Where and how you should send patches 390 391 When you write patches for GRUB, please send them to the mailing list 392 @email{bug-grub@@gnu.org}. Here is the list of items of which you 393 should take care: 394 395 @itemize @bullet 396 @item 397 Please make your patch as small as possible. Generally, it is not a good 398 thing to make one big patch which changes many things. Instead, 399 segregate features and produce many patches. 400 401 @item 402 Use as late code as possible, for the original code. The CVS repository 403 always has the current version (@pxref{Obtaining and Building GRUB}). 404 405 @item 406 Write ChangeLog entries. @xref{Change Logs, , Change Logs, standards, 407 GNU Coding Standards}, if you don't know how to write ChangeLog. 408 409 @item 410 Make patches in unified diff format. @samp{diff -urN} is appropriate in 411 most cases. 412 413 @item 414 Don't make patches reversely. Reverse patches are difficult to read and 415 use. 416 417 @item 418 Be careful enough of the license term and the copyright. Because GRUB 419 is under GNU General Public License, you may not steal code from 420 software whose license is incompatible against GPL. And, if you copy 421 code written by others, you must not ignore their copyrights. Feel free 422 to ask GRUB maintainers, whenever you are not sure what you should do. 423 424 @item 425 If your patch is too large to send in e-mail, put it at somewhere we can 426 see. Usually, you shouldn't send e-mail over 20K. 427 @end itemize 428
