« back to all changes in this revision
Viewing changes to docs/grub.info-3
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Jason Thomas
- Date: 2002-02-04 15:35:01 UTC
- Revision ID: james.westby@ubuntu.com-20020204153501-neulkag77r3a2m0v
Tags: upstream-0.91
Import upstream version 0.91
- files added:
- docs
- grub
- lib
- netboot
- stage1
- stage2
- util
added
removed
docs/grub.info-3
1
This is grub.info, produced by makeinfo version 4.0 from grub.texi.
2
3
INFO-DIR-SECTION Kernel
4
START-INFO-DIR-ENTRY
5
* GRUB: (grub). The GRand Unified Bootloader
6
* grub-install: (grub)Invoking grub-install. Install GRUB on your drive
7
* grub-md5-crypt: (grub)Invoking grub-md5-crypt. Encrypt a password
8
in MD5 format
9
* mbchk: (grub)Invoking mbchk. Check for the format of a Multiboot kernel
10
END-INFO-DIR-ENTRY
11
12
Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
13
14
Permission is granted to make and distribute verbatim copies of this
15
manual provided the copyright notice and this permission notice are
16
preserved on all copies.
17
18
Permission is granted to copy and distribute modified versions of
19
this manual under the conditions for verbatim copying, provided also
20
that the entire resulting derived work is distributed under the terms
21
of a permission notice identical to this one.
22
23
Permission is granted to copy and distribute translations of this
24
manual into another language, under the above conditions for modified
25
versions.
26
27
28
File: grub.info, Node: Troubleshooting, Next: Invoking the grub shell, Prev: Commands, Up: Top
29
30
Error messages reported by GRUB
31
*******************************
32
33
This chapter describes error messages reported by GRUB when you
34
encounter trouble. *Note Invoking the grub shell::, if your problem is
35
specific to the grub shell.
36
37
* Menu:
38
39
* Stage1 errors:: Errors reported by the Stage 1
40
* Stage1.5 errors:: Errors reported by the Stage 1.5
41
* Stage2 errors:: Errors reported by the Stage 2
42
43
44
File: grub.info, Node: Stage1 errors, Next: Stage1.5 errors, Up: Troubleshooting
45
46
Errors reported by the Stage 1
47
==============================
48
49
The general way that the Stage 1 handles errors is to print an error
50
string and then halt. Pressing `<CTRL>-<ALT>-<DEL>' will reboot.
51
52
The following is a comprehensive list of error messages for the
53
Stage 1:
54
55
Hard Disk Error
56
The stage2 or stage1.5 is being read from a hard disk, and the
57
attempt to determine the size and geometry of the hard disk failed.
58
59
Floppy Error
60
The stage2 or stage1.5 is being read from a floppy disk, and the
61
attempt to determine the size and geometry of the floppy disk
62
failed. It's listed as a separate error since the probe sequence
63
is different than for hard disks.
64
65
Read Error
66
A disk read error happened while trying to read the stage2 or
67
stage1.5.
68
69
Geom Error
70
The location of the stage2 or stage1.5 is not in the portion of
71
the disk supported directly by the BIOS read calls. This could
72
occur because the BIOS translated geometry has been changed by the
73
user or the disk is moved to another machine or controller after
74
installation, or GRUB was not installed using itself (if it was,
75
the Stage 2 version of this error would have been seen during that
76
process and it would not have completed the install).
77
78
79
File: grub.info, Node: Stage1.5 errors, Next: Stage2 errors, Prev: Stage1 errors, Up: Troubleshooting
80
81
Errors reported by the Stage 1.5
82
================================
83
84
The general way that the Stage 1.5 handles errors is to print an
85
error number in the form `Error NUM' and then halt. Pressing
86
`<CTRL>-<ALT>-<DEL>' will reboot.
87
88
The error numbers correspond to the errors reported by Stage 2.
89
*Note Stage2 errors::.
90
91
92
File: grub.info, Node: Stage2 errors, Prev: Stage1.5 errors, Up: Troubleshooting
93
94
Errors reported by the Stage 2
95
==============================
96
97
The general way that the Stage 2 handles errors is to abort the
98
operation in question, print an error string, then (if possible) either
99
continue based on the fact that an error occurred or wait for the user
100
to deal with the error.
101
102
The following is a comprehensive list of error messages for the
103
Stage 2 (error numbers for the Stage 1.5 are listed before the colon in
104
each description):
105
106
1 : Filename must be either an absolute filename or blocklist
107
This error is returned if a file name is requested which doesn't
108
fit the syntax/rules listed in the *Note Filesystem::.
109
110
2 : Bad file or directory type
111
This error is returned if a file requested is not a regular file,
112
but something like a symbolic link, directory, or FIFO.
113
114
3 : Bad or corrupt data while decompressing file
115
This error is returned if the run-length decompression code gets an
116
internal error. This is usually from a corrupt file.
117
118
4 : Bad or incompatible header in compressed file
119
This error is returned if the file header for a supposedly
120
compressed file is bad.
121
122
5 : Partition table invalid or corrupt
123
This error is returned if the sanity checks on the integrity of the
124
partition table fail. This is a bad sign.
125
126
6 : Mismatched or corrupt version of stage1/stage2
127
This error is returned if the install command is pointed to
128
incompatible or corrupt versions of the stage1 or stage2. It can't
129
detect corruption in general, but this is a sanity check on the
130
version numbers, which should be correct.
131
132
7 : Loading below 1MB is not supported
133
This error is returned if the lowest address in a kernel is below
134
the 1MB boundary. The Linux zImage format is a special case and
135
can be handled since it has a fixed loading address and maximum
136
size.
137
138
8 : Kernel must be loaded before booting
139
This error is returned if GRUB is told to execute the boot sequence
140
without having a kernel to start.
141
142
9 : Unknown boot failure
143
This error is returned if the boot attempt did not succeed for
144
reasons which are unknown.
145
146
10 : Unsupported Multiboot features requested
147
This error is returned when the Multiboot features word in the
148
Multiboot header requires a feature that is not recognized. The
149
point of this is that the kernel requires special handling which
150
GRUB is likely unable to provide.
151
152
11 : Unrecognized device string
153
This error is returned if a device string was expected, and the
154
string encountered didn't fit the syntax/rules listed in the *Note
155
Filesystem::.
156
157
12 : Invalid device requested
158
This error is returned if a device string is recognizable but does
159
not fall under the other device errors.
160
161
13 : Invalid or unsupported executable format
162
This error is returned if the kernel image being loaded is not
163
recognized as Multiboot or one of the supported native formats
164
(Linux zImage or bzImage, FreeBSD, or NetBSD).
165
166
14 : Filesystem compatibility error, cannot read whole file
167
Some of the filesystem reading code in GRUB has limits on the
168
length of the files it can read. This error is returned when the
169
user runs into such a limit.
170
171
15 : File not found
172
This error is returned if the specified file name cannot be found,
173
but everything else (like the disk/partition info) is OK.
174
175
16 : Inconsistent filesystem structure
176
This error is returned by the filesystem code to denote an internal
177
error caused by the sanity checks of the filesystem structure on
178
disk not matching what it expects. This is usually caused by a
179
corrupt filesystem or bugs in the code handling it in GRUB.
180
181
17 : Cannot mount selected partition
182
This error is returned if the partition requested exists, but the
183
filesystem type cannot be recognized by GRUB.
184
185
18 : Selected cylinder exceeds maximum supported by BIOS
186
This error is returned when a read is attempted at a linear block
187
address beyond the end of the BIOS translated area. This generally
188
happens if your disk is larger than the BIOS can handle (512MB for
189
(E)IDE disks on older machines or larger than 8GB in general).
190
191
19 : Linux kernel must be loaded before initrd
192
This error is returned if the initrd command is used before
193
loading a Linux kernel. Similar to the above error, it only makes
194
sense in that case anyway.
195
196
20 : Multiboot kernel must be loaded before modules
197
This error is returned if the module load command is used before
198
loading a Multiboot kernel. It only makes sense in this case
199
anyway, as GRUB has no idea how to communicate the presence of
200
location of such modules to a non-Multiboot-aware kernel.
201
202
21 : Selected disk does not exist
203
This error is returned if the device part of a device- or full
204
file name refers to a disk or BIOS device that is not present or
205
not recognized by the BIOS in the system.
206
207
22 : No such partition
208
This error is returned if a partition is requested in the device
209
part of a device- or full file name which isn't on the selected
210
disk.
211
212
23 : Error while parsing number
213
This error is returned if GRUB was expecting to read a number and
214
encountered bad data.
215
216
24 : Attempt to access block outside partition
217
This error is returned if a linear block address is outside of the
218
disk partition. This generally happens because of a corrupt
219
filesystem on the disk or a bug in the code handling it in GRUB
220
(it's a great debugging tool).
221
222
25 : Disk read error
223
This error is returned if there is a disk read error when trying to
224
probe or read data from a particular disk.
225
226
26 : Too many symbolic links
227
This error is returned if the link count is beyond the maximum
228
(currently 5), possibly the symbolic links are looped.
229
230
27 : Unrecognized command
231
This error is returned if an unrecognized command is entered into
232
the command-line or in a boot sequence section of a configuration
233
file and that entry is selected.
234
235
28 : Selected item cannot fit into memory
236
This error is returned if a kernel, module, or raw file load
237
command is either trying to load its data such that it won't fit
238
into memory or it is simply too big.
239
240
29 : Disk write error
241
This error is returned if there is a disk write error when trying
242
to write to a particular disk. This would generally only occur
243
during an install of set active partition command.
244
245
30 : Invalid argument
246
This error is returned if an argument specified to a command is
247
invalid.
248
249
31 : File is not sector aligned
250
This error may occur only when you access a ReiserFS partition by
251
block-lists (e.g. the command `install'). In this case, you should
252
mount the partition with the `-o notail' option.
253
254
32 : Must be authenticated
255
This error is returned if you try to run a locked entry. You should
256
enter a correct password before running such an entry.
257
258
33 : Serial device not configured
259
This error is returned if you try to change your terminal to a
260
serial one before initializing any serial device.
261
262
34 : No spare sectors on the disk
263
This error is returned if a disk doesn't have enough spare space.
264
This happens when you try to embed Stage 1.5 into the unused
265
sectors after the MBR, but the first partition starts right after
266
the MBR or they are used by EZ-BIOS.
267
268
269
File: grub.info, Node: Invoking the grub shell, Next: Invoking grub-install, Prev: Troubleshooting, Up: Top
270
271
Invoking the grub shell
272
***********************
273
274
This chapter documents the grub shell `grub'. Note that the grub
275
shell is an emulator; it doesn't run under the native environment, so it
276
sometimes does something wrong. Therefore, you shouldn't trust it too
277
much. If there is anything wrong with it, don't hesitate to try the
278
native GRUB environment, especially when it guesses a wrong map between
279
BIOS drives and OS devices.
280
281
* Menu:
282
283
* Basic usage:: How to use the grub shell
284
* Installation under UNIX:: How to install GRUB via `grub'
285
* Device map:: The map between BIOS drives and OS devices
286
287
288
File: grub.info, Node: Basic usage, Next: Installation under UNIX, Up: Invoking the grub shell
289
290
Introduction into the grub shell
291
================================
292
293
You can use the command `grub' for installing GRUB under your
294
operating systems and for a testbed when you add a new feature into GRUB
295
or when fix a bug. `grub' is almost the same as the Stage 2, and, in
296
fact, it shares the source code with the Stage 2 and you can use the
297
same commands (*note Commands::) in `grub'. It is emulated by replacing
298
BIOS calls with UNIX system calls and libc functions.
299
300
The command `grub' accepts the following options:
301
302
`--help'
303
Print a summary of the command-line options and exit.
304
305
`--version'
306
Print the version number of GRUB and exit.
307
308
`--verbose'
309
Print some verbose messages for debugging purpose.
310
311
`--device-map=FILE'
312
Use the device map file FILE. The format is described in *Note
313
Device map::.
314
315
`--no-floppy'
316
Do not probe any floppy drive. This option has no effect if the
317
option `--device-map' is specified (*note Device map::).
318
319
`--probe-second-floppy'
320
Probe the second floppy drive. If this option is not specified,
321
the grub shell does not probe it, as that sometimes takes a long
322
time. If you specify the device map file (*note Device map::), the
323
grub shell just ignores this option.
324
325
`--config-file=FILE'
326
Read the configuration file FILE instead of `/boot/grub/menu.lst'.
327
The format is the same as the normal GRUB syntax. See *Note
328
Filesystem::, for more information.
329
330
`--boot-drive=DRIVE'
331
Set the stage2 BOOT_DRIVE to DRIVE. This argument should be an
332
integer (decimal, octal or hexadecimal).
333
334
`--install-partition=PAR'
335
Set the stage2 INSTALL_PARTITION to PAR. This argument should be
336
an integer (decimal, octal or hexadecimal).
337
338
`--no-config-file'
339
Do not use the configuration file even if it can be read.
340
341
`--no-curses'
342
Do not use the curses interface even if it is available.
343
344
`--batch'
345
This option has the same meaning as `--no-config-file --no-curses'.
346
347
`--read-only'
348
Disable writing to any disk.
349
350
`--hold'
351
Wait until a debugger will attach. This option is useful when you
352
want to debug the startup code.
353
354
355
File: grub.info, Node: Installation under UNIX, Next: Device map, Prev: Basic usage, Up: Invoking the grub shell
356
357
How to install GRUB via `grub'
358
==============================
359
360
The installation procedure is the same as under the "native" Stage
361
2. *Note Installation::, for more information. The command
362
`grub'-specific information is described here.
363
364
What you should be careful about is "buffer cache". `grub' makes use
365
of raw devices instead of filesystems that your operating systems
366
serve, so there exists a potential problem that some cache
367
inconsistency may corrupt your filesystems. What we recommend is:
368
369
* If you can unmount drives to which GRUB may write any amount of
370
data, unmount them before running `grub'.
371
372
* If a drive cannot be unmounted but can be mounted with the
373
read-only flag, mount it in read-only mode. That should be secure.
374
375
* If a drive must be mounted with the read-write flag, make sure
376
that any activity is not being done on it during running the
377
command `grub'.
378
379
* Reboot your operating system as soon as possible. Probably that is
380
not required if you follow these rules above, but reboot is the
381
most secure way.
382
383
In addition, enter the command `quit' when you finish the
384
installation. That is _very important_ because `quit' makes the buffer
385
cache consistent. Do not push <C-c>.
386
387
If you want to install GRUB non-interactively, specify `--batch'
388
option in the command-line. This is a simple example:
389
390
#!/bin/sh
391
392
# Use /usr/sbin/grub if you are on an older system.
393
/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
394
root (hd0,0)
395
setup (hd0)
396
quit
397
EOT
398
399
400
File: grub.info, Node: Device map, Prev: Installation under UNIX, Up: Invoking the grub shell
401
402
The map between BIOS drives and OS devices
403
==========================================
404
405
When you specify the option `--device-map' (*note Basic usage::),
406
the grub shell creates the "device map file" automatically unless it
407
already exists. The file name `/boot/grub/device.map' is preferred.
408
409
If the device map file exists, the grub shell reads it to map BIOS
410
drives to OS devices. This file consists of lines like this:
411
412
DEVICE FILE
413
414
DEVICE is a drive, which syntax is the same as the one in GRUB
415
(*note Device syntax::), and FILE is an OS's file, which is normally a
416
device file.
417
418
The reason why the grub shell gives you the device map file is that
419
it cannot guess the map between BIOS drives and OS devices correctly in
420
some environments. For example, if you exchange the boot sequence
421
between IDE and SCSI in your BIOS, it mistakes the order.
422
423
Thus, edit the file if the grub shell makes a mistake. You can put
424
any comments in the file if needed, as the grub shell assumes that a
425
line is just a comment if the first character is `#'.
426
427
428
File: grub.info, Node: Invoking grub-install, Next: Invoking grub-md5-crypt, Prev: Invoking the grub shell, Up: Top
429
430
Invoking grub-install
431
*********************
432
433
The program `grub-install' installs GRUB on your drive by the grub
434
shell (*note Invoking the grub shell::). You must specify the device
435
name on which you want to install GRUB, like this:
436
437
grub-install INSTALL_DEVICE
438
439
The device name INSTALL_DEVICE is an OS device name or a GRUB device
440
name.
441
442
`grub-install' accepts the following options:
443
444
`--help'
445
Print a summary of the command-line options and exit.
446
447
`--version'
448
Print the version number of GRUB and exit.
449
450
`--force-lba'
451
Force GRUB to use LBA mode even for a buggy BIOS. Use this option
452
only if your BIOS doesn't work in LBA mode even though it supports
453
LBA mode.
454
455
`--root-directory=DIR'
456
Install GRUB images under the directory DIR instead of the root
457
directory. This option is useful when you want to install GRUB
458
into a separate partition or a removable disk. Here is an example
459
when you have a separate "boot" partition which is mounted on
460
`/boot':
461
462
grub-install --root-directory=/boot '(hd0)'
463
464
`--grub-shell=FILE'
465
Use FILE as the grub shell. You can append arbitrary options to
466
FILE after the file name, like this:
467
468
grub-install --grub-shell="grub --read-only" /dev/fd0
469
470
`--recheck'
471
Recheck the device map, even if `/boot/grub/device.map' already
472
exists. You should use this option whenever you add/remove a disk
473
into/from your computer.
474
475
476
File: grub.info, Node: Invoking grub-md5-crypt, Next: Invoking mbchk, Prev: Invoking grub-install, Up: Top
477
478
Invoking grub-md5-crypt
479
***********************
480
481
The program `grub-md5-crypt' encrypts a password in MD5 format.
482
This is just a frontend of the grub shell (*note Invoking the grub
483
shell::). Passwords encrypted by this program can be used with the
484
command `password' (*note password::).
485
486
`grub-md5-crypt' accepts the following options:
487
488
`--help'
489
Print a summary of the command-line options and exit.
490
491
`--version'
492
Print the version information and exit.
493
494
`--grub-shell=FILE'
495
Use FILE as the grub shell.
496
497
498
File: grub.info, Node: Invoking mbchk, Next: FAQ, Prev: Invoking grub-md5-crypt, Up: Top
499
500
Invoking mbchk
501
**************
502
503
The program `mbchk' checks for the format of a Multiboot kernel. We
504
recommend using this program before booting your own kernel by GRUB.
505
506
`mbchk' accepts the following options:
507
508
`--help'
509
Print a summary of the command-line options and exit.
510
511
`--version'
512
Print the version number of GRUB and exit.
513
514
`--quiet'
515
Suppress all normal output.
516
517
518
File: grub.info, Node: FAQ, Next: Obtaining and Building GRUB, Prev: Invoking mbchk, Up: Top
519
520
Frequently asked questions
521
**************************
522
523
How does GNU GRUB differ from Erich's original GRUB?
524
GNU GRUB is the successor of Erich's great GRUB. He couldn't work
525
on GRUB because of some other tasks, so the current maintainers
526
OKUJI Yoshinori and Gordon Matzigkeit took over the
527
maintainership, and opened the development in order for everybody
528
to participate it.
529
530
Technically speaking, GNU GRUB has many features that are not seen
531
in the original GRUB. For example, GNU GRUB can be installed on
532
UNIX-like operating system (such as GNU/Hurd) via the grub shell
533
`/sbin/grub' (or `/usr/sbin/grub' on older systems), it supports
534
Logical Block Address (LBA) mode that solves the 1024 cylinders
535
problem, and `<TAB>' completes a file name when it's unique. Of
536
course, many bug fixes are done as well, so it is recommended to
537
use GNU GRUB.
538
539
Can GRUB boot my operating system from over 8GB hard disks?
540
That depends on your BIOS and your operating system. You must make
541
sure that your drive is accessible in LBA mode. Generally, that is
542
configurable in BIOS setting utility. Read the manual for your BIOS
543
for more information.
544
545
Furthermore, some operating systems (i.e. DOS) cannot access any
546
large disk, so the problem is not solved by any kind of boot
547
loader. GNU/Hurd and GNU/Linux can surely boot from such a large
548
disk.
549
550
Can I put Stage2 into a partition which is over 1024 cylinders?
551
Yes, if your BIOS supports the LBA mode.
552
553
How to create a GRUB boot floppy with the menu interface?
554
The easiest way is:
555
556
1. Create filesystem in your floppy disk. For example:
557
558
$ mke2fs /dev/fd0
559
560
2. Mount it on somewhere, say, `/mnt'.
561
562
3. Copy the GRUB images to `/mnt/boot/grub'. Only `stage1',
563
`stage2' and `menu.lst' are necessary. You may not copy
564
"stage1.5"s.
565
566
4. Run the following command (substitute `/usr/sbin/grub' for
567
`/sbin/grub' if you are using an older system):
568
569
$ /sbin/grub --batch <<EOT
570
root (fd0)
571
setup (fd0)
572
quit
573
EOT
574
575
How to specify a partition?
576
*Note Device syntax::.
577
578
GRUB does not recognize my GNU/Hurd partition.
579
I don't know why, but the authors of FDISK programs have assigned
580
the partition type `0x63' to GNU Hurd incorrectly. A partition type
581
should mean what format is used in the partition, such as
582
filesystem and BSD slices, and should not be used to represent
583
what operating system owns the partition. So use `0x83' if the
584
partition contains ext2fs filesystem, and use `0xA5' if the
585
partition contains ffs filesystem, whether the partition owner is
586
Hurd or not. We will use `0x63' for GNU Hurd filesystem that has
587
not been implemented yet.
588
589
I've installed a recent version of binutils, but GRUB still crashes.
590
Please check for the version of your binutils by this command:
591
592
ld -v
593
594
This will show two versions, but only the latter is important. If
595
the version is identical with what you have installed, the
596
installation was not bad.
597
598
Well, please try:
599
600
gcc -Wl,-v 2>&1 | grep "GNU ld"
601
602
If this is not identical with the result above, you should specify
603
the directory where you have installed binutils for the script
604
configure, like this:
605
606
./configure --with-binutils=/usr/local/bin
607
608
If you follow the instructions above but GRUB still crashes,
609
probably there is a serious bug in GRUB. *Note Reporting bugs::.
610
611
GRUB hangs up when accessing my SCSI disk.
612
Check if you have turned on the support for INT 13 extension
613
(LBA). If so, disable the support and see if GRUB can now access
614
your SCSI disk. This will make it clear that your SCSI BIOS sucks.
615
616
For now, we know the following doesn't provide working LBA mode:
617
618
619
Adaptec AIC-7880
620
621
In the case where you have such a SCSI controller unfortunately,
622
you cannot use the LBA mode, though GRUB still works fine in the
623
CHS mode (so the well-known 1024 cylinders problem comes again to
624
you).
625
626
*Caution:* Actually it has not been verified yet if this bug is
627
due to the SCSI BIOS or GRUB itself, frankly speaking. Because the
628
developers haven't seen it by their own eyes. This is why it is
629
desirable that you investigate the cause seriously if you have the
630
skill.
631
632
How can I specify an arbitrary memory size to Linux?
633
Pass a `mem=' option to your Linux kernel, like this:
634
635
grub> kernel /vmlinuz mem=128M
636
637
You may pass other options in the same way. See *Note GNU/Linux::,
638
for more details.
639
640
I have a separate boot partition and GRUB doesn't recognize it.
641
This is often reported as a "bug", but this is not a bug really.
642
This is a feature.
643
644
Because GRUB is a boot loader and it normally runs under no
645
operating system, it doesn't know where a partition is mounted
646
under your operating systems. So, if you have the partition
647
`/boot' and you install GRUB images into the directory
648
`/boot/grub', GRUB recognizes that the images lies under the
649
directory `/grub' but not `/boot/grub'. That's fine, since there
650
is no guarantee that all of your operating systems mount the same
651
partition as `/boot'.
652
653
There are several solutions for this situation.
654
655
1. Install GRUB into the directory `/boot/boot/grub' instead of
656
`/boot/grub'. This may sound ugly but should work fine.
657
658
2. Create a symbolic link before installing GRUB, like `cd /boot
659
&& ln -s . boot'. This works only if the filesystem of the
660
boot partition supports symbolic links and GRUB supports the
661
feature as well.
662
663
3. Install GRUB with the command `install', to specify the paths
664
of GRUB images explicitly. Here is an example:
665
666
grub> root (hd0,1)
667
grub> install /grub/stage1 d (hd0) /grub/stage2 p /grub/menu.lst
668
669
How to uninstall GRUB from my hard disk drive?
670
There is no concept "uninstall" in boot loaders, because if you
671
"uninstall" a boot loader, an unbootable machine would simply
672
remain. So all you need to do is overwrite another boot loader you
673
like to your disk, that is, install the boot loader without
674
uninstalling GRUB.
675
676
For example, if you want to install the boot loader for Windows,
677
just run `FDISK /MBR' on Windows. If you want to install LILO(1)
678
(*note FAQ-Footnote-1::), run `/sbin/lilo' on GNU/Linux.
679
680
GRUB hangs when accessing my large IDE disk.
681
If your disk is bigger than 32GB, probably updating your mainboard
682
BIOS will solve your problem. This bug is well-known and most
683
vendors should provide fixed versions. For example, if you have
684
ASUS-P3BF, upgrading the BIOS to V1007beta1 or later can fix it.
685
Please ask your vendor, for more information.
686
687
Why don't Linux, FreeBSD, NetBSD, etc. become Multiboot-compliant?
688
Please ask the relevant maintainers. If all free kernels were
689
Multiboot-compliant (*note Multiboot Specification:
690
(multiboot)Top.), the world would be an utopia...
691
692
693
File: grub.info, Node: FAQ-Footnotes, Up: FAQ
694
695
(1) I can't imagine why you want to do such a thing, though
696
697
698
File: grub.info, Node: Obtaining and Building GRUB, Next: Reporting bugs, Prev: FAQ, Up: Top
699
700
How to obtain and build GRUB
701
****************************
702
703
*Caution:* GRUB requires binutils-2.9.1.0.23 or later because the
704
GNU assembler has been changed so that it can produce real 16bits
705
machine code between 2.9.1 and 2.9.1.0.x. See
706
`http://sourceware.cygnus.com/binutils/', to obtain information on
707
how to get the latest version.
708
709
GRUB is available from the GNU alpha archive site
710
`ftp://alpha.gnu.org/gnu/grub' or any of its mirrors. The file will be
711
named grub-version.tar.gz. The current version is 0.91, so the file you
712
should grab is:
713
714
`ftp://alpha.gnu.org/gnu/grub/grub-0.91.tar.gz'
715
716
To unbundle GRUB use the instruction:
717
718
zcat grub-0.91.tar.gz | tar xvf -
719
720
which will create a directory called `grub-0.91' with all the
721
sources. You can look at the file `INSTALL' for detailed instructions
722
on how to build and install GRUB, but you should be able to just do:
723
724
cd grub-0.91
725
./configure
726
make install
727
728
This will install the grub shell `grub' (*note Invoking the grub
729
shell::), the Multiboot checker `mbchk' (*note Invoking mbchk::), and
730
the GRUB images. This will also install the GRUB manual.
731
732
Also, the latest version is available from the CVS. The repository
733
is:
734
735
`:pserver:anoncvs@subversions.gnu.org:/cvsroot/grub'
736
737
and the module is:
738
739
`grub'
740
741
The password for anoncvs is empty. So the instruction is:
742
743
cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/grub login
744
Password: <ENTER>
745
cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/grub co grub
746
747
748
File: grub.info, Node: Reporting bugs, Next: Future, Prev: Obtaining and Building GRUB, Up: Top
749
750
Reporting bugs
751
**************
752
753
This is the guideline of how to report bugs. Take a look at this list
754
below before you send e-mail to <bug-grub@gnu.org>:
755
756
1. Before unsettled, read this manual through and through, in
757
particular *Note FAQ::.
758
759
2. Always mention the information on your GRUB. The version number
760
and the configuration are quite important. If you build it
761
yourself, write the options specified to the configure script and
762
your operating system, including the versions of gcc and binutils.
763
764
3. If you get troubled with the installation, inform us of how you
765
installed GRUB. Don't omit error messages, if any. Just `GRUB hangs
766
up when it boots' is not enough.
767
768
The information on your hardware is also essential. These are
769
especially important: the geometries and the partition tables of
770
your hard disk drives and your BIOS.
771
772
4. If GRUB cannot boot your operating system, write down _all_ on the
773
screen. Don't paraphrase them, like `The foo OS crashes with GRUB,
774
even though it can boot with the bar boot loader fine'. Mention the
775
commands you executed, the messages printed by them, and
776
information on your operating system including the version number.
777
778
5. Explain what you wanted to do. It is very useful to know your
779
purpose and your wish, and how GRUB didn't satisfy you.
780
781
6. If you can investigate the problem yourself, please do. That will
782
give you and us much more information on the problem. Attaching a
783
patch is even better.
784
785
When you attach a patch, make the patch in unified diff format, and
786
write ChangeLog entries. But, even when you make a patch, don't
787
forget to explain the problem, so that we can understand what your
788
patch is for.
789
790
7. Write down anything that you think might be related. Please
791
understand that we often need to reproduce the same problem you
792
encounterred in our environment. So your information should be
793
sufficient for us to do the same thing--Don't forget that we
794
cannot see your computer directly. If you are not sure whether to
795
state a fact or leave it out, state it! Reporting too many things
796
is quite better than omitting an important thing.
797
798
If you realize the guideline above, send e-mail to
799
<bug-grub@gnu.org>, and we will try to fix the bugs.
800
801
802
File: grub.info, Node: Future, Next: Internals, Prev: Reporting bugs, Up: Top
803
804
Where GRUB will go
805
******************
806
807
Here are some ideas that might happen in the future:
808
809
* Support dynamic loading.
810
811
* Add real memory management.
812
813
* Add a real scripting language.
814
815
* Support internationalization.
816
817
* Support other architectures than i386-pc.
818
819
See the file `TODO' in the source distribution, for more information.
820
821
822
File: grub.info, Node: Internals, Next: Index, Prev: Future, Up: Top
823
824
Hacking GRUB
825
************
826
827
This chapter documents the user-invisible aspect of GRUB.
828
829
As a general rule of software development, it is impossible to keep
830
the descriptions of the internals up-to-date, and it is quite hard to
831
document everything. So refer to the source code, whenever you are not
832
satisfied with this documentation. Please assume that this gives just
833
hints to you.
834
835
* Menu:
836
837
* Memory map:: The memory map of various components
838
* Embedded data:: Embedded variables in GRUB
839
* Filesystem interface:: The generic interface for filesystems
840
* Command interface:: The generic interface for built-ins
841
* Bootstrap tricks:: The bootstrap mechanism used in GRUB
842
* I/O ports detection:: How to probe I/O ports used by INT 13H
843
* Memory detection:: How to detect all installed RAM
844
* Low-level disk I/O:: INT 13H disk I/O interrupts
845
* MBR:: The structure of Master Boot Record
846
* Partition table:: The format of partition tables
847
* Submitting patches:: Where and how you should send patches
848
849
850
File: grub.info, Node: Memory map, Next: Embedded data, Up: Internals
851
852
The memory map of various components
853
====================================
854
855
GRUB consists of two distinct components, called "stages", which are
856
loaded at different times in the boot process. Because they run
857
mutual-exclusively, sometimes a memory area overlaps with another
858
memory area. And, even in one stage, a single memory area can be used
859
for various purposes, because their usages are mutually exclusive.
860
861
Here is the memory map of the various components:
862
863
0 to 4K-1
864
BIOS and real mode interrupts
865
866
0x07BE to 0x07FF
867
Partition table passed to another boot loader
868
869
down from 8K-1
870
Real mode stack
871
872
0x2000 to ?
873
The optional Stage 1.5 is loaded here
874
875
0x2000 to 0x7FFF
876
Command-line buffer for Multiboot kernels and modules
877
878
0x7C00 to 0x7DFF
879
Stage 1 is loaded here by BIOS or another boot loader
880
881
0x7F00 to 0x7F42
882
LBA drive parameters
883
884
0x8000 to ?
885
Stage2 is loaded here
886
887
The end of Stage 2 to 416K-1
888
Heap, in particular used for the menu
889
890
down from 416K-1
891
Protected mode stack
892
893
416K to 448K-1
894
Filesystem buffer
895
896
448K to 479.5K-1
897
Raw device buffer
898
899
479.5K to 480K-1
900
512-byte scratch area
901
902
480K to 512K-1
903
Buffers for various functions, such as password, command-line, cut
904
and paste, and completion.
905
906
The last 1K of lower memory
907
Disk swapping code and data
908
909
See the file `stage2/shared.h', for more information.
910
911
912
File: grub.info, Node: Embedded data, Next: Filesystem interface, Prev: Memory map, Up: Internals
913
914
Embedded variables in GRUB
915
==========================
916
917
Stage 1 and Stage 2 have embedded variables whose locations are
918
well-defined, so that the installation can patch the binary file
919
directly without recompilation of the stages.
920
921
In Stage 1, these are defined:
922
923
`0x3E'
924
The version number (not GRUB's, but the installation mechanism's).
925
926
`0x40'
927
The boot drive. If it is 0xFF, use a drive passed by BIOS.
928
929
`0x41'
930
The flag for if forcing LBA.
931
932
`0x42'
933
The starting address of Stage 2.
934
935
`0x44'
936
The first sector of Stage 2.
937
938
`0x48'
939
The starting segment of Stage 2.
940
941
`0x1FE'
942
The signature (`0xAA55').
943
944
See the file `stage1/stage1.S', for more information.
945
946
In the first sector of Stage 1.5 and Stage 2, the block lists are
947
recorded between `firstlist' and `lastlist'. The address of `lastlist'
948
is determined when assembling the file `stage2/start.S'.
949
950
The trick here is that it is actually read backward, and the first
951
8-byte block list is not read here, but after the pointer is decremented
952
8 bytes, then after reading it, it decrements again, reads, and so on,
953
until it is finished. The terminating condition is when the number of
954
sectors to be read in the next block list is zero.
955
956
The format of a block list can be seen from the example in the code
957
just before the `firstlist' label. Note that it is always from the
958
beginning of the disk, but _not_ relative to the partition boundaries.
959
960
In the second sector of Stage 1.5 and Stage 2, these are defined:
961
962
`0x6'
963
The version number (likewise, the installation mechanism's).
964
965
`0x8'
966
The installed partition.
967
968
`0xC'
969
The saved entry number.
970
971
`0x10'
972
The identifier.
973
974
`0x11'
975
The flag for if forcing LBA.
976
977
`0x12'
978
The version string (GRUB's).
979
980
`0x12' + "the length of the version string"
981
The name of a configuration file.
982
983
See the file `stage2/asm.S', for more information.
984
985
986
File: grub.info, Node: Filesystem interface, Next: Command interface, Prev: Embedded data, Up: Internals
987
988
The generic interface for filesystems
989
=====================================
990
991
For any particular partition, it is presumed that only one of the
992
"normal" filesystems such as FAT, FFS, or ext2fs can be used, so there
993
is a switch table managed by the functions in `disk_io.c'. The notation
994
is that you can only "mount" one at a time.
995
996
The block list filesystem has a special place in the system. In
997
addition to the "normal" filesystem (or even without one mounted), you
998
can access disk blocks directly (in the indicated partition) via the
999
block list notation. Using the block list filesystem doesn't effect any
1000
other filesystem mounts.
1001
1002
The variables which can be read by the filesystem backend are:
1003
1004
`current_drive'
1005
The current BIOS drive number (numbered from 0, if a floppy, and
1006
numbered from 0x80, if a hard disk).
1007
1008
`current_partition'
1009
The current partition number.
1010
1011
`current_slice'
1012
The current partition type.
1013
1014
`saved_drive'
1015
The "drive" part of the root device.
1016
1017
`saved_partition'
1018
The "partition" part of the root device.
1019
1020
`part_start'
1021
The current partition starting address, in sectors.
1022
1023
`part_length'
1024
The current partition length, in sectors.
1025
1026
`print_possibilities'
1027
True when the `dir' function should print the possible completions
1028
of a file, and false when it should try to actually open a file of
1029
that name.
1030
1031
`FSYS_BUF'
1032
Filesystem buffer which is 32K in size, to use in any way which the
1033
filesystem backend desires.
1034
1035
The variables which need to be written by a filesystem backend are:
1036
1037
`filepos'
1038
The current position in the file, in sectors.
1039
1040
*Caution:* the value of FILEPOS can be changed out from under the
1041
filesystem code in the current implementation. Don't depend on it
1042
being the same for later calls into the backend code!
1043
1044
`filemax'
1045
The length of the file.
1046
1047
`disk_read_func'
1048
The value of DISK_READ_HOOK _only_ during reading of data for the
1049
file, not any other fs data, inodes, FAT tables, whatever, then
1050
set to `NULL' at all other times (it will be `NULL' by default).
1051
If this isn't done correctly, then the `testload' and `install'
1052
commands won't work correctly.
1053
1054
The functions expected to be used by the filesystem backend are:
1055
1056
`devread'
1057
Only read sectors from within a partition. Sector 0 is the first
1058
sector in the partition.
1059
1060
`grub_read'
1061
If the backend uses the block list code, then `grub_read' can be
1062
used, after setting BLOCK_FILE to 1.
1063
1064
`print_a_completion'
1065
If PRINT_POSSIBILITIES is true, call `print_a_completion' for each
1066
possible file name. Otherwise, the file name completion won't work.
1067
1068
The functions expected to be defined by the filesystem backend are
1069
described at least moderately in the file `filesys.h'. Their usage is
1070
fairly evident from their use in the functions in `disk_io.c', look for
1071
the use of the FSYS_TABLE array.
1072
1073
*Caution:* The semantics are such that then `mount'ing the
1074
filesystem, presume the filesystem buffer `FSYS_BUF' is corrupted, and
1075
(re-)load all important contents. When opening and reading a file,
1076
presume that the data from the `mount' is available, and doesn't get
1077
corrupted by the open/read (i.e. multiple opens and/or reads will be
1078
done with only one mount if in the same filesystem).
1079
1080
1081
File: grub.info, Node: Command interface, Next: Bootstrap tricks, Prev: Filesystem interface, Up: Internals
1082
1083
The generic interface for built-ins
1084
===================================
1085
1086
GRUB built-in commands are defined in a uniformal interface, whether
1087
they are menu-specific or can be used anywhere. The definition of a
1088
builtin command consists of two parts: the code itself and the table of
1089
the information.
1090
1091
The code must be a function which takes two arguments, a command-line
1092
string and flags, and returns an `int' value. The "flags" argument
1093
specifies how the function is called, using a bit mask. The return
1094
value must be zero if successful, otherwise non-zero. So it is normally
1095
enough to return ERRNUM.
1096
1097
The table of the information is represented by the structure `struct
1098
builtin', which contains the name of the command, a pointer to the
1099
function, flags, a short description of the command and a long
1100
description of the command. Since the descriptions are used only for
1101
help messages interactively, you don't have to define them, if the
1102
command may not be called interactively (such as `title').
1103
1104
The table is finally registered in the table BUILTIN_TABLE, so that
1105
`run_script' and `enter_cmdline' can find the command. See the files
1106
`cmdline.c' and `builtins.c', for more details.
1107
1108
1109
File: grub.info, Node: Bootstrap tricks, Next: I/O ports detection, Prev: Command interface, Up: Internals
1110
1111
The bootstrap mechanism used in GRUB
1112
====================================
1113
1114
The disk space can be used in a boot loader is very restricted
1115
because a MBR (*note MBR::) is only 512 bytes but it also contains a
1116
partition table (*note Partition table::) and a BPB. So the question is
1117
how to make a boot loader code enough small to be fit in a MBR.
1118
1119
However, GRUB is a very large program, so we break GRUB into 2 (or 3)
1120
distinct components, "Stage 1" and "Stage 2" (and optionally "Stage
1121
1.5"). *Note Memory map::, for more information.
1122
1123
We embed Stage 1 in a MBR or in the boot sector of a partition, and
1124
place Stage 2 in a filesystem. The optional Stage 1.5 can be installed
1125
in a filesystem, in the "boot loader" area in a FFS or a ReiserFS, and
1126
in the sectors right after a MBR, because Stage 1.5 is enough small and
1127
the sectors right after a MBR is normally an unused region. The size of
1128
this region is the number of sectors per head minus 1.
1129
1130
Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if
1131
Stage 1 needs not to support the user interface or the filesystem
1132
interface, it is impossible to make Stage 1 less than 400 bytes, because
1133
GRUB should support both the CHS mode and the LBA mode (*note Low-level
1134
disk I/O::).
1135
1136
The solution used by GRUB is that Stage 1 loads only the first
1137
sector of Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The
1138
flow of Stage 1 is:
1139
1140
1. Initialize the system briefly.
1141
1142
2. Detect the geometry and the accessing mode of the "loading drive".
1143
1144
3. Load the first sector of Stage 2.
1145
1146
4. Jump to the starting address of the Stage 2.
1147
1148
The flow of Stage 2 (and Stage 1.5) is:
1149
1150
1. Load the rest of itself to the real starting address, that is, the
1151
starting address plus 512 bytes. The block lists are stored in the
1152
last part of the first sector.
1153
1154
2. Long jump to the real starting address.
1155
1156
Note that Stage 2 (or Stage 1.5) does not probe the geometry or the
1157
accessing mode of the "loading drive", since Stage 1 has already probed
1158
them.
1159
1160
1161
File: grub.info, Node: I/O ports detection, Next: Memory detection, Prev: Bootstrap tricks, Up: Internals
1162
1163
How to probe I/O ports used by INT 13H
1164
======================================
1165
1166
FIXME: I will write this chapter after implementing the new
1167
technique.
1168
1169
1170
File: grub.info, Node: Memory detection, Next: Low-level disk I/O, Prev: I/O ports detection, Up: Internals
1171
1172
How to detect all installed RAM
1173
===============================
1174
1175
FIXME: I doubt if Erich didn't write this chapter only himself
1176
wholly, so I will rewrite this chapter.
1177
1178
1179
File: grub.info, Node: Low-level disk I/O, Next: MBR, Prev: Memory detection, Up: Internals
1180
1181
INT 13H disk I/O interrupts
1182
===========================
1183
1184
FIXME: I'm not sure where some part of the original chapter is
1185
derived, so I will rewrite this chapter.
1186
1187
1188
File: grub.info, Node: MBR, Next: Partition table, Prev: Low-level disk I/O, Up: Internals
1189
1190
The structure of Master Boot Record
1191
===================================
1192
1193
FIXME: Likewise.
1194
1195
1196
File: grub.info, Node: Partition table, Next: Submitting patches, Prev: MBR, Up: Internals
1197
1198
The format of partition tables
1199
==============================
1200
1201
FIXME: Probably the original chapter is derived from "How It Works",
1202
so I will rewrite this chapter.
1203
1204
1205
File: grub.info, Node: Submitting patches, Prev: Partition table, Up: Internals
1206
1207
Where and how you should send patches
1208
=====================================
1209
1210
When you write patches for GRUB, please send them to the mailing list
1211
<bug-grub@gnu.org>. Here is the list of items of which you should take
1212
care:
1213
1214
* Please make your patch as small as possible. Generally, it is not
1215
a good thing to make one big patch which changes many things.
1216
Instead, segregate features and produce many patches.
1217
1218
* Use as late code as possible, for the original code. The CVS
1219
repository always has the current version (*note Obtaining and
1220
Building GRUB::).
1221
1222
* Write ChangeLog entries. *Note Change Logs: (standards)Change
1223
Logs, if you don't know how to write ChangeLog.
1224
1225
* Make patches in unified diff format. `diff -urN' is appropriate in
1226
most cases.
1227
1228
* Don't make patches reversely. Reverse patches are difficult to
1229
read and use.
1230
1231
* Be careful enough of the license term and the copyright. Because
1232
GRUB is under GNU General Public License, you may not steal code
1233
from software whose license is incompatible against GPL. And, if
1234
you copy code written by others, you must not ignore their
1235
copyrights. Feel free to ask GRUB maintainers, whenever you are
1236
not sure what you should do.
1237
1238
* If your patch is too large to send in e-mail, put it at somewhere
1239
we can see. Usually, you shouldn't send e-mail over 20K.
1240
1241
1242
File: grub.info, Node: Index, Prev: Internals, Up: Top
1243
1244
Index
1245
*****
1246
1247
* Menu:
1248
1249
* blocklist: blocklist.
1250
* boot: boot.
1251
* bootp: bootp.
1252
* cat: cat.
1253
* chainloader: chainloader.
1254
* cmp: cmp.
1255
* color: color.
1256
* configfile: configfile.
1257
* current_drive: Filesystem interface.
1258
* current_partition: Filesystem interface.
1259
* current_slice: Filesystem interface.
1260
* debug: debug.
1261
* default: default.
1262
* device: device.
1263
* devread: Filesystem interface.
1264
* dhcp: dhcp.
1265
* disk_read_func: Filesystem interface.
1266
* displayapm: displayapm.
1267
* displaymem: displaymem.
1268
* embed: embed.
1269
* fallback: fallback.
1270
* filemax: Filesystem interface.
1271
* filepos: Filesystem interface.
1272
* find: find.
1273
* fstest: fstest.
1274
* FSYS_BUF: Filesystem interface.
1275
* geometry: geometry.
1276
* grub_read: Filesystem interface.
1277
* halt: halt.
1278
* help: help.
1279
* hiddenmenu: hiddenmenu.
1280
* hide: hide.
1281
* ifconfig: ifconfig.
1282
* impsprobe: impsprobe.
1283
* initrd: initrd.
1284
* install: install.
1285
* ioprobe: ioprobe.
1286
* kernel: kernel.
1287
* lock: lock.
1288
* makeactive: makeactive.
1289
* map: map.
1290
* md5crypt: md5crypt.
1291
* module: module.
1292
* modulenounzip: modulenounzip.
1293
* part_length: Filesystem interface.
1294
* part_start: Filesystem interface.
1295
* partnew: partnew.
1296
* parttype: parttype.
1297
* password: password.
1298
* pause: pause.
1299
* print_a_completion: Filesystem interface.
1300
* print_possibilities: Filesystem interface.
1301
* quit: quit.
1302
* rarp: rarp.
1303
* read: read.
1304
* reboot: reboot.
1305
* root: root.
1306
* rootnoverify: rootnoverify.
1307
* saved_drive: Filesystem interface.
1308
* saved_partition: Filesystem interface.
1309
* savedefault: savedefault.
1310
* serial: serial.
1311
* setkey: setkey.
1312
* setup: setup.
1313
* terminal: terminal.
1314
* testload: testload.
1315
* testvbe: testvbe.
1316
* tftpserver: tftpserver.
1317
* timeout: timeout.
1318
* title: title.
1319
* unhide: unhide.
1320
* uppermem: uppermem.
1321
* vbeprobe: vbeprobe.
1322
1323
Loggerhead is a web-based interface for Breezy
Version: 2.0.1