From 5f44ad81f06a6d9d4b3f0fb98ea7dfea20ea9b57 Mon Sep 17 00:00:00 2001 From: okuji Date: Sat, 5 Jun 1999 19:05:35 +0000 Subject: [PATCH] doc update --- docs/grub.texi | 515 +++++++++++++++++++++++++++++++++++++++++++- docs/multiboot.texi | 2 +- 2 files changed, 506 insertions(+), 11 deletions(-) diff --git a/docs/grub.texi b/docs/grub.texi index 6f347c0bd..0da4f5002 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -82,6 +82,7 @@ edition documents version @value{VERSION}. * Using:: Booting your operating systems. * Filesystems:: Filesystem syntax and semantics. * Troubleshooting:: Error messages produced by GRUB. +* Stage 2 Emulator:: The command @command{grub}. * Hacking:: Implementation details. * Index:: Index. @@ -98,7 +99,6 @@ How to install GRUB on your computer * Boot floppy:: Creating a GRUB boot floppy. * Automated install:: Installation via @code{install=}. -* Installation under Unix:: Installation by @file{/sbin/grub}. Booting your operating systems @@ -118,6 +118,12 @@ Error messages reported by GRUB * Stage1.5 errors:: Errors reported by the Stage 1.5. * Stage2 errors:: Errors reported by the Stage 2. +The command @command{grub} + +* Basic usage:: Introduction into the Stage 2 emulator. +* Command-line options:: The list of @command{grub} options. +* Installation under UNIX:: How to install GRUB by @command{grub}. + Implementation details * Memory map:: The memory map of the various @@ -345,7 +351,6 @@ command at the GRUB command line (@pxref{Using}). @menu * Boot floppy:: Creating a GRUB boot floppy. * Automated install:: Installation via @code{install=}. -* Installation under Unix:: Installation by @file{/sbin/grub}. @end menu @@ -478,12 +483,6 @@ kernel= /zImage root=/dev/hda2 the OS. -@node Installation under Unix -@section Installation by @file{/sbin/grub} - -FIXME - - @node Using @chapter Booting your operating system @@ -1075,6 +1074,34 @@ should be correct. @end table +@node Stage 2 Emulator +@chapter The command @command{grub} + +@menu +* Basic usage:: Introduction into the Stage 2 emulator. +* Command-line options:: The list of @command{grub} options. +* Installation under UNIX:: How to install GRUB by @command{grub}. +@end menu + + +@node Basic usage +@section Introduction into the Stage 2 emulator + +FIXME + + +@node Command-line options +@section The list of @command{grub} options + +FIXME + + +@node Installation under UNIX +@section How to install GRUB by @command{grub} + +FIXME + + @node Hacking @chapter Implementation details @@ -2190,13 +2217,481 @@ hard disk. @node Partition table @section The format of partition table -PC_partitioning.txt +@menu +* Partition basics:: Overview the partition table. +* Partition types:: The list of the @dfn{type} code. +* Partition entry format:: The format of the table entry. +* Partition table rules:: Some basic rules for Partition table. +@end menu + + +@node Partition basics +@subsection Overview the partition table + +FDISK creates all partition records (sectors). The primary purpose of a +partition record is to hold a partition table. The rules for how FDISK +works are unwritten but so far most FDISK programs seem to follow the +same basic idea. + +First, all partition table records (sectors) have the same format. This +includes the partition table record at cylinder 0, head 0, sector 1 -- +what is known as the Master Boot Record (MBR). The last 66 bytes of a +partition table record contain a partition table and a 2 byte +signature. The first 446 bytes of these sectors usually contain a +program but only the program in the MBR is ever executed (so extended +partition table records could contain something other than a program in +the first 466 bytes). For more information, see @ref{MBR}. + +Second, extended partitions are @emph{nested} inside one another and +extended partition table records form a @dfn{linked list}. I will +attempt to show this in a diagram at @ref{Partition entry format}. + +Each partition table entry is 16 bytes and contains things like the +start and end location of a partition in CHS, the start in LBA, the size +in sectors, the partition @dfn{type} and the @dfn{active} flag. Older +versions of FDISK may compute incorrect LBA or size values. And when +your computer boots itself, only the CHS fields of the partition table +entries are used (another reason LBA doesn't solve the >528MB +problem). The CHS fields in the partition tables are in L-CHS format, +see @ref{CHS Translation}. + + +@node Partition types +@subsection The list of the @dfn{type} code + +There is no central clearing house to assign the codes used in the one +byte @dfn{type} field. But codes are assigned (or used) to define most +every type of file system that anyone has ever implemented on the x86 +PC: 12-bit FAT, 16-bit FAT, HPFS, NTFS, etc. Plus, an extended partition +also has a unique type code. + +In the FDISK program @samp{sfdisk}, the following list is assumed: + +@table @asis +@item 00 +Empty + +@item 01 +DOS 12-bit FAT + +@item 02 +XENIX / + +@item 03 +XENIX /usr + +@item 04 +DOS 16-bit FAT <32M + +@item 05 +DOS Extended + +@item 06 +DOS 16-bit FAT >=32M + +@item 07 +HPFS / NTFS + +@item 08 +AIX boot or SplitDrive + +@item 09 +AIX data or Coherent + +@item 0A +OS/2 Boot Manager + +@item 0B +Windows95 FAT32 + +@item 0C +Windows95 FAT32 (LBA) + +@item 0E +Windows95 FAT16 (LBA) + +@item 0F +Windows95 Extended (LBA) + +@item 10 +OPUS + +@item 11 +Hidden DOS FAT12 + +@item 12 +Compaq diagnostics + +@item 14 +Hidden DOS FAT16 + +@item 16 +Hidden DOS FAT16 (big) + +@item 17 +Hidden HPFS/NTFS + +@item 18 +AST Windows swapfile + +@item 24 +NEC DOS + +@item 3C +PartitionMagic recovery + +@item 40 +Venix 80286 + +@item 41 +Linux/MINIX (sharing disk with DRDOS) + +@item 42 +SFS or Linux swap (sharing disk with DRDOS) + +@item 43 +Linux native (sharing disk with DRDOS) + +@item 50 +DM (disk manager) + +@item 51 +DM6 Aux1 (or Novell) + +@item 52 +CP/M or Microsoft SysV/AT + +@item 53 +DM6 Aux3 + +@item 54 +DM6 + +@item 55 +EZ-Drive (disk manager) + +@item 56 +Golden Bow (disk manager) + +@item 5C +Priam Edisk (disk manager) + +@item 61 +SpeedStor + +@item 63 +GNU Hurd or Mach or Sys V/386 (such as ISC UNIX)@footnote{But the reason +why they decided that 63 means GNU Hurd is not known. Do not use 63 for +GNU Hurd.} + +@item 64 +Novell Netware 286 + +@item 65 +Novell Netware 386 + +@item 70 +DiskSecure Multi-Boot + +@item 75 +PC/IX + +@item 77 +QNX4.x + +@item 78 +QNX4.x 2nd part + +@item 79 +QNX4.x 3rd part + +@item 80 +MINIX until 1.4a + +@item 81 +MINIX / old Linux + +@item 82 +Linux swap + +@item 83 +Linux native@footnote{This is not true. Use 83 for ext2fs even if the +owner OS is GNU/Hurd.} + +@item 84 +OS/2 hidden C: drive + +@item 85 +Linux extended + +@item 86 +NTFS volume set + +@item 87 +NTFS volume set + +@item 93 +Amoeba + +@item 94 +Amoeba BBT + +@item A0 +IBM Thinkpad hibernatoin + +@item A5 +BSD/386 + +@item A7 +NeXTSTEP 486 + +@item B7 +BSDI fs + +@item B8 +BSDI swap + +@item C1 +DRDOS/sec (FAT-12) + +@item C4 +DRDOS/sec (FAT-16, < 32M) + +@item C6 +DRDOS/sec (FAT-16, >= 32M) + +@item C7 +Syrinx + +@item DB +CP/M or Concurrent CP/M or Concurrent DOS or CTOS + +@item E1 +DOS access or SpeedStor 12-bit FAT extended partition + +@item E3 +DOS R/O or SpeedStor + +@item E4 +SpeedStor 16-bit FAT extended partition < 1024 cyl. + +@item F1 +SpeedStor + +@item F2 +DOS 3.3+ secondary + +@item F4 +SpeedStor large partition + +@item FE +SpeedStor >1024 cyl. or LANstep + +@item FF +Xenix Bad Block Table +@end table + +@node Partition entry format +@subsection The format of the table entry + +The 16 bytes of a partition table entry are used as follows: + +@example +@group + +--- Bit 7 is the active partition flag, bits 6-0 are zero. + | + | +--- Starting CHS in INT 13 call format. + | | + | | +--- Partition type byte. + | | | + | | | +--- Ending CHS in INT 13 call format. + | | | | + | | | | +-- Starting LBA. + | | | | | + | | | | | +-- Size in sectors. + | | | | | | + v <--+---> v <--+--> v v + + 0 1 2 3 4 5 6 7 8 9 A B C D E F + DH DL CH CL TB DL CH CL LBA..... SIZE.... + + 80 01 01 00 06 0e be 94 3e000000 0c610900 1st entry + + 00 00 81 95 05 0e fe 7d 4a610900 724e0300 2nd entry + + 00 00 00 00 00 00 00 00 00000000 00000000 3rd entry + + 00 00 00 00 00 00 00 00 00000000 00000000 4th entry +@end group +@end example + +Bytes 0-3 are used by the small program in the Master Boot Record to +read the first sector of an active partition into memory. The @dfn{DH}, +@dfn{DL}, @dfn{CH} and @dfn{CL} above show which x86 register is loaded +when the MBR program calls INT 13H AH=02h to read the active partition's +boot sector. For more information, see @ref{MBR}. + +These entries define the following partitions: + +@enumerate +@item +The first partition, a primary partition DOS FAT, starts at CHS 0H,1H,1H +(LBA 3EH) and ends at CHS 294H,EH,3EH with a size of 9610CH sectors. + +@item +The second partition, an extended partition, starts at CHS 295H,0H,1H +(LBA 9614AH) and ends at CHS 37DH,EH,3EH with a size of 34E72H sectors. + +@item +The third and fourth table entries are unused. +@end enumerate + + +@node Partition table rules +@subsection Some basic rules for Partition table. + +Keep in mind that there are @emph{no} written rules and @emph{no} +industry standards on how FDISK should work but here are some basic +rules that seem to be followed by most versions of FDISK: + +@enumerate +@item +In the MBR there can be 0-4 @dfn{primary} partitions, OR, 0-3 primary +partitions and 0-1 extended partition entry. + +@item +In an extended partition there can be 0-1 @dfn{secondary} partition +entries and 0-1 extended partition entries. + +@item +Only 1 primary partition in the MBR can be marked @dfn{active} at any +given time. + +@item +In most versions of FDISK, the first sector of a partition will be +aligned such that it is at head 0, sector 1 of a cylinder. This means +that there may be unused sectors on the track(s) prior to the first +sector of a partition and that there may be unused sectors following a +partition table sector. + +For example, most new versions of FDISK start the first partition +(primary or extended) at cylinder 0, head 1, sector 0. This leaves the +sectors at cylinder 0, head 0, sectors 2...n as unused sectors. This +same layout may be seen on the first track of an extended partition. +See example 2 below. + +Also note that software drivers like Ontrack's Disk Manager depend on +these unused sectors because these drivers will @dfn{hide} their code +there (in cylinder 0, head 0, sectors 2...n). This is also a good place +for boot sector virus programs to hang out. + +@item +The partition table entries (slots) can be used in any order. Some +versions of FDISK fill the table from the bottom up and some versions of +FDISK fill the table from the top down. Deleting a partition can leave +an unused entry (slot) in the middle of a table. + +@item +And then there is the @dfn{hack} that some newer OS's (OS/2 and Linux) +use in order to place a partition spanning or passed cylinder 1024 on a +system that does not have a CHS translating BIOS. These systems create a +partition table entry with the partition's starting and ending CHS +information set to all FFH. The starting and ending LBA information is +used to describe the location of the partition. The LBA can be converted +back to a CHS --- most likely a CHS with more than 1024 cylinders. Since +such a CHS can't be used by the system BIOS, these partitions can not be +booted or accessed until the OS's kernel and hard disk device drivers +are loaded. It is not known if the systems using this @dfn{hack} follow +the same rules for the creation of these type of partitions. +@end enumerate + +There are @emph{no} written rules as to how an OS scans the partition +table entries so each OS can have a different method. For DOS, this +means that different versions could assign different drive letters to +the same FAT file system partitions. @node Filesystem interface @section The generic interface for the fs code -filesystem.txt +For any particular partition, it is presumed that only one of the +@dfn{normal} filesystems such as FAT, FFS, or ext2fs can be used, so +there is a switch table managed by the functions in +@file{disk_io.c}. The notation is that you can only @dfn{mount} one at a +time. + +The blocklist filesystem has a special place in the system. In addition +to the @dfn{normal} filesystem (or even without one mounted), you can +access disk blocks directly (in the indicated partition) via the +blocklist notation. Using the blocklist filesystem doesn't effect any +other filesystem mounts. + +The variables which can be read by the filesystem backend are: + +@vtable @code +@item current_drive +Contain the current BIOS drive number (numbered from 0, if a floppy, +and numbered from 0x80, if a hard disk). + +@item current_slice +Contain the current partition length, in sectors. + +@item print_possibilities +True when the @code{dir} function should print the possible completions +of a file, and false when it should try to actually open a file of that +name. + +@item FSYS_BUF +Point to a filesystem buffer which is 32K in size, to use in any way +which the filesystem backend desires. +@end vtable + +The variables which need to be written by a filesystem backend are: + +@vtable @code +@item filepos +Should be the current position in the file. + +@strong{Caution:} the value of @var{filepos} can be changed out from +under the filesystem code in the current implementation. Don't depend on +it being the same for later calls into the back-end code! + +@item filemax +Should be the length of the file. + +@item debug_fs_func +Should be set to the value of @samp{debug_fs} @emph{only} during reading +of data for the file, not any other fs data, inodes, FAT tables, +whatever, then set to @code{NULL} at all other times (it will be +@code{NULL} by default). If this isn't done corrently, then the +@command{testload=} and @command{install=} commands won't work +correctly. +@end vtable + +The functions expected to be used by the filesystem backend are: + +@ftable @code +@item devread +Only read sectors from within a partition. Sector 0 is the first sector +in the partition. + +@item grub_read +If the backend uses the block-list code (like the FAT filesystem backend +does), then @code{grub_read} can be used, after setting @var{block_file} +to 1. +@end ftable + +The functions expected to be defined by the filesystem backend are +described at least moderately in the file @file{filesys.h}. Their usage +is fairly evident from their use in the functions in @file{disk_io.c}, +look for the use of the @var{fsys_table} array. + +@strong{Caution:} The semantics are such that then @samp{mount}ing the +filesystem, presume the filesystem buffer @var{FSYS_BUF} is corrupted, +and (re-)load all important contents. When opening and reading a file, +presume that the data from the @samp{mount} is available, and doesn't +get corrupted by the open/read (i.e. multiple opens and/or reads will be +done with only one mount if in the same filesystem). @node Index diff --git a/docs/multiboot.texi b/docs/multiboot.texi index 38ff869fb..0a01ad2bc 100644 --- a/docs/multiboot.texi +++ b/docs/multiboot.texi @@ -816,7 +816,7 @@ This distribution also contains code implementing a @dfn{Linux boot adaptor}, which collects a MultiBoot-compliant OS image and an optional set of boot modules, compresses them, and packages them into a single traditional Linux boot image that can be loaded from LILO or other Linux -boot loaders. There is also a corresponding "BSD boot adaptor" which +boot loaders. There is also a corresponding @dfn{BSD boot adaptor} which can be used to wrap a MultiBoot kernel and set of modules and produce an image that can be loaded from the FreeBSD and NetBSD boot loaders. All of this code can be used as-is or as a basis for other boot loaders.