ipc: do not recompute msgmni anymore if explicitly set by user
[linux-2.6.git] / Documentation / i386 / boot.txt
1                      THE LINUX/I386 BOOT PROTOCOL
2                      ----------------------------
3
4                     H. Peter Anvin <hpa@zytor.com>
5                         Last update 2007-05-23
6
7 On the i386 platform, the Linux kernel uses a rather complicated boot
8 convention.  This has evolved partially due to historical aspects, as
9 well as the desire in the early days to have the kernel itself be a
10 bootable image, the complicated PC memory model and due to changed
11 expectations in the PC industry caused by the effective demise of
12 real-mode DOS as a mainstream operating system.
13
14 Currently, the following versions of the Linux/i386 boot protocol exist.
15
16 Old kernels:    zImage/Image support only.  Some very early kernels
17                 may not even support a command line.
18
19 Protocol 2.00:  (Kernel 1.3.73) Added bzImage and initrd support, as
20                 well as a formalized way to communicate between the
21                 boot loader and the kernel.  setup.S made relocatable,
22                 although the traditional setup area still assumed
23                 writable.
24
25 Protocol 2.01:  (Kernel 1.3.76) Added a heap overrun warning.
26
27 Protocol 2.02:  (Kernel 2.4.0-test3-pre3) New command line protocol.
28                 Lower the conventional memory ceiling.  No overwrite
29                 of the traditional setup area, thus making booting
30                 safe for systems which use the EBDA from SMM or 32-bit
31                 BIOS entry points.  zImage deprecated but still
32                 supported.
33
34 Protocol 2.03:  (Kernel 2.4.18-pre1) Explicitly makes the highest possible
35                 initrd address available to the bootloader.
36
37 Protocol 2.04:  (Kernel 2.6.14) Extend the syssize field to four bytes.
38
39 Protocol 2.05:  (Kernel 2.6.20) Make protected mode kernel relocatable.
40                 Introduce relocatable_kernel and kernel_alignment fields.
41
42 Protocol 2.06:  (Kernel 2.6.22) Added a field that contains the size of
43                 the boot command line
44
45 Protocol 2.09:  (kernel 2.6.26) Added a field of 64-bit physical
46                 pointer to single linked list of struct setup_data.
47
48 **** MEMORY LAYOUT
49
50 The traditional memory map for the kernel loader, used for Image or
51 zImage kernels, typically looks like:
52
53         |                        |
54 0A0000  +------------------------+
55         |  Reserved for BIOS     |      Do not use.  Reserved for BIOS EBDA.
56 09A000  +------------------------+
57         |  Command line          |
58         |  Stack/heap            |      For use by the kernel real-mode code.
59 098000  +------------------------+      
60         |  Kernel setup          |      The kernel real-mode code.
61 090200  +------------------------+
62         |  Kernel boot sector    |      The kernel legacy boot sector.
63 090000  +------------------------+
64         |  Protected-mode kernel |      The bulk of the kernel image.
65 010000  +------------------------+
66         |  Boot loader           |      <- Boot sector entry point 0000:7C00
67 001000  +------------------------+
68         |  Reserved for MBR/BIOS |
69 000800  +------------------------+
70         |  Typically used by MBR |
71 000600  +------------------------+ 
72         |  BIOS use only         |
73 000000  +------------------------+
74
75
76 When using bzImage, the protected-mode kernel was relocated to
77 0x100000 ("high memory"), and the kernel real-mode block (boot sector,
78 setup, and stack/heap) was made relocatable to any address between
79 0x10000 and end of low memory. Unfortunately, in protocols 2.00 and
80 2.01 the 0x90000+ memory range is still used internally by the kernel;
81 the 2.02 protocol resolves that problem.
82
83 It is desirable to keep the "memory ceiling" -- the highest point in
84 low memory touched by the boot loader -- as low as possible, since
85 some newer BIOSes have begun to allocate some rather large amounts of
86 memory, called the Extended BIOS Data Area, near the top of low
87 memory.  The boot loader should use the "INT 12h" BIOS call to verify
88 how much low memory is available.
89
90 Unfortunately, if INT 12h reports that the amount of memory is too
91 low, there is usually nothing the boot loader can do but to report an
92 error to the user.  The boot loader should therefore be designed to
93 take up as little space in low memory as it reasonably can.  For
94 zImage or old bzImage kernels, which need data written into the
95 0x90000 segment, the boot loader should make sure not to use memory
96 above the 0x9A000 point; too many BIOSes will break above that point.
97
98 For a modern bzImage kernel with boot protocol version >= 2.02, a
99 memory layout like the following is suggested:
100
101         ~                        ~
102         |  Protected-mode kernel |
103 100000  +------------------------+
104         |  I/O memory hole       |
105 0A0000  +------------------------+
106         |  Reserved for BIOS     |      Leave as much as possible unused
107         ~                        ~
108         |  Command line          |      (Can also be below the X+10000 mark)
109 X+10000 +------------------------+
110         |  Stack/heap            |      For use by the kernel real-mode code.
111 X+08000 +------------------------+      
112         |  Kernel setup          |      The kernel real-mode code.
113         |  Kernel boot sector    |      The kernel legacy boot sector.
114 X       +------------------------+
115         |  Boot loader           |      <- Boot sector entry point 0000:7C00
116 001000  +------------------------+
117         |  Reserved for MBR/BIOS |
118 000800  +------------------------+
119         |  Typically used by MBR |
120 000600  +------------------------+ 
121         |  BIOS use only         |
122 000000  +------------------------+
123
124 ... where the address X is as low as the design of the boot loader
125 permits.
126
127
128 **** THE REAL-MODE KERNEL HEADER
129
130 In the following text, and anywhere in the kernel boot sequence, "a
131 sector" refers to 512 bytes.  It is independent of the actual sector
132 size of the underlying medium.
133
134 The first step in loading a Linux kernel should be to load the
135 real-mode code (boot sector and setup code) and then examine the
136 following header at offset 0x01f1.  The real-mode code can total up to
137 32K, although the boot loader may choose to load only the first two
138 sectors (1K) and then examine the bootup sector size.
139
140 The header looks like:
141
142 Offset  Proto   Name            Meaning
143 /Size
144
145 01F1/1  ALL(1   setup_sects     The size of the setup in sectors
146 01F2/2  ALL     root_flags      If set, the root is mounted readonly
147 01F4/4  2.04+(2 syssize         The size of the 32-bit code in 16-byte paras
148 01F8/2  ALL     ram_size        DO NOT USE - for bootsect.S use only
149 01FA/2  ALL     vid_mode        Video mode control
150 01FC/2  ALL     root_dev        Default root device number
151 01FE/2  ALL     boot_flag       0xAA55 magic number
152 0200/2  2.00+   jump            Jump instruction
153 0202/4  2.00+   header          Magic signature "HdrS"
154 0206/2  2.00+   version         Boot protocol version supported
155 0208/4  2.00+   realmode_swtch  Boot loader hook (see below)
156 020C/2  2.00+   start_sys       The load-low segment (0x1000) (obsolete)
157 020E/2  2.00+   kernel_version  Pointer to kernel version string
158 0210/1  2.00+   type_of_loader  Boot loader identifier
159 0211/1  2.00+   loadflags       Boot protocol option flags
160 0212/2  2.00+   setup_move_size Move to high memory size (used with hooks)
161 0214/4  2.00+   code32_start    Boot loader hook (see below)
162 0218/4  2.00+   ramdisk_image   initrd load address (set by boot loader)
163 021C/4  2.00+   ramdisk_size    initrd size (set by boot loader)
164 0220/4  2.00+   bootsect_kludge DO NOT USE - for bootsect.S use only
165 0224/2  2.01+   heap_end_ptr    Free memory after setup end
166 0226/2  N/A     pad1            Unused
167 0228/4  2.02+   cmd_line_ptr    32-bit pointer to the kernel command line
168 022C/4  2.03+   initrd_addr_max Highest legal initrd address
169 0230/4  2.05+   kernel_alignment Physical addr alignment required for kernel
170 0234/1  2.05+   relocatable_kernel Whether kernel is relocatable or not
171 0235/3  N/A     pad2            Unused
172 0238/4  2.06+   cmdline_size    Maximum size of the kernel command line
173 023C/4  2.07+   hardware_subarch Hardware subarchitecture
174 0240/8  2.07+   hardware_subarch_data Subarchitecture-specific data
175 0248/4  2.08+   payload_offset  Offset of kernel payload
176 024C/4  2.08+   payload_length  Length of kernel payload
177 0250/8  2.09+   setup_data      64-bit physical pointer to linked list
178                                 of struct setup_data
179
180 (1) For backwards compatibility, if the setup_sects field contains 0, the
181     real value is 4.
182
183 (2) For boot protocol prior to 2.04, the upper two bytes of the syssize
184     field are unusable, which means the size of a bzImage kernel
185     cannot be determined.
186
187 If the "HdrS" (0x53726448) magic number is not found at offset 0x202,
188 the boot protocol version is "old".  Loading an old kernel, the
189 following parameters should be assumed:
190
191         Image type = zImage
192         initrd not supported
193         Real-mode kernel must be located at 0x90000.
194
195 Otherwise, the "version" field contains the protocol version,
196 e.g. protocol version 2.01 will contain 0x0201 in this field.  When
197 setting fields in the header, you must make sure only to set fields
198 supported by the protocol version in use.
199
200
201 **** DETAILS OF HEADER FIELDS
202
203 For each field, some are information from the kernel to the bootloader
204 ("read"), some are expected to be filled out by the bootloader
205 ("write"), and some are expected to be read and modified by the
206 bootloader ("modify").
207
208 All general purpose boot loaders should write the fields marked
209 (obligatory).  Boot loaders who want to load the kernel at a
210 nonstandard address should fill in the fields marked (reloc); other
211 boot loaders can ignore those fields.
212
213 The byte order of all fields is littleendian (this is x86, after all.)
214
215 Field name:     setup_sects
216 Type:           read
217 Offset/size:    0x1f1/1
218 Protocol:       ALL
219
220   The size of the setup code in 512-byte sectors.  If this field is
221   0, the real value is 4.  The real-mode code consists of the boot
222   sector (always one 512-byte sector) plus the setup code.
223
224 Field name:      root_flags
225 Type:            modify (optional)
226 Offset/size:     0x1f2/2
227 Protocol:        ALL
228
229   If this field is nonzero, the root defaults to readonly.  The use of
230   this field is deprecated; use the "ro" or "rw" options on the
231   command line instead.
232
233 Field name:     syssize
234 Type:           read
235 Offset/size:    0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL)
236 Protocol:       2.04+
237
238   The size of the protected-mode code in units of 16-byte paragraphs.
239   For protocol versions older than 2.04 this field is only two bytes
240   wide, and therefore cannot be trusted for the size of a kernel if
241   the LOAD_HIGH flag is set.
242
243 Field name:     ram_size
244 Type:           kernel internal
245 Offset/size:    0x1f8/2
246 Protocol:       ALL
247
248   This field is obsolete.
249
250 Field name:     vid_mode
251 Type:           modify (obligatory)
252 Offset/size:    0x1fa/2
253
254   Please see the section on SPECIAL COMMAND LINE OPTIONS.
255
256 Field name:     root_dev
257 Type:           modify (optional)
258 Offset/size:    0x1fc/2
259 Protocol:       ALL
260
261   The default root device device number.  The use of this field is
262   deprecated, use the "root=" option on the command line instead.
263
264 Field name:     boot_flag
265 Type:           read
266 Offset/size:    0x1fe/2
267 Protocol:       ALL
268
269   Contains 0xAA55.  This is the closest thing old Linux kernels have
270   to a magic number.
271
272 Field name:     jump
273 Type:           read
274 Offset/size:    0x200/2
275 Protocol:       2.00+
276
277   Contains an x86 jump instruction, 0xEB followed by a signed offset
278   relative to byte 0x202.  This can be used to determine the size of
279   the header.
280
281 Field name:     header
282 Type:           read
283 Offset/size:    0x202/4
284 Protocol:       2.00+
285
286   Contains the magic number "HdrS" (0x53726448).
287
288 Field name:     version
289 Type:           read
290 Offset/size:    0x206/2
291 Protocol:       2.00+
292
293   Contains the boot protocol version, in (major << 8)+minor format,
294   e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version
295   10.17.
296
297 Field name:     readmode_swtch
298 Type:           modify (optional)
299 Offset/size:    0x208/4
300 Protocol:       2.00+
301
302   Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
303
304 Field name:     start_sys
305 Type:           read
306 Offset/size:    0x20c/4
307 Protocol:       2.00+
308
309   The load low segment (0x1000).  Obsolete.
310
311 Field name:     kernel_version
312 Type:           read
313 Offset/size:    0x20e/2
314 Protocol:       2.00+
315
316   If set to a nonzero value, contains a pointer to a NUL-terminated
317   human-readable kernel version number string, less 0x200.  This can
318   be used to display the kernel version to the user.  This value
319   should be less than (0x200*setup_sects).
320
321   For example, if this value is set to 0x1c00, the kernel version
322   number string can be found at offset 0x1e00 in the kernel file.
323   This is a valid value if and only if the "setup_sects" field
324   contains the value 15 or higher, as:
325
326         0x1c00  < 15*0x200 (= 0x1e00) but
327         0x1c00 >= 14*0x200 (= 0x1c00)
328
329         0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15.
330
331 Field name:     type_of_loader
332 Type:           write (obligatory)
333 Offset/size:    0x210/1
334 Protocol:       2.00+
335
336   If your boot loader has an assigned id (see table below), enter
337   0xTV here, where T is an identifier for the boot loader and V is
338   a version number.  Otherwise, enter 0xFF here.
339
340   Assigned boot loader ids:
341         0  LILO                 (0x00 reserved for pre-2.00 bootloader)
342         1  Loadlin
343         2  bootsect-loader      (0x20, all other values reserved)
344         3  SYSLINUX
345         4  EtherBoot
346         5  ELILO
347         7  GRuB
348         8  U-BOOT
349         9  Xen
350         A  Gujin
351         B  Qemu
352
353   Please contact <hpa@zytor.com> if you need a bootloader ID
354   value assigned.
355
356 Field name:     loadflags
357 Type:           modify (obligatory)
358 Offset/size:    0x211/1
359 Protocol:       2.00+
360
361   This field is a bitmask.
362
363   Bit 0 (read): LOADED_HIGH
364         - If 0, the protected-mode code is loaded at 0x10000.
365         - If 1, the protected-mode code is loaded at 0x100000.
366
367   Bit 6 (write): KEEP_SEGMENTS
368         Protocol: 2.07+
369         - if 0, reload the segment registers in the 32bit entry point.
370         - if 1, do not reload the segment registers in the 32bit entry point.
371                 Assume that %cs %ds %ss %es are all set to flat segments with
372                 a base of 0 (or the equivalent for their environment).
373
374   Bit 7 (write): CAN_USE_HEAP
375         Set this bit to 1 to indicate that the value entered in the
376         heap_end_ptr is valid.  If this field is clear, some setup code
377         functionality will be disabled.
378
379 Field name:     setup_move_size
380 Type:           modify (obligatory)
381 Offset/size:    0x212/2
382 Protocol:       2.00-2.01
383
384   When using protocol 2.00 or 2.01, if the real mode kernel is not
385   loaded at 0x90000, it gets moved there later in the loading
386   sequence.  Fill in this field if you want additional data (such as
387   the kernel command line) moved in addition to the real-mode kernel
388   itself.
389
390   The unit is bytes starting with the beginning of the boot sector.
391   
392   This field is can be ignored when the protocol is 2.02 or higher, or
393   if the real-mode code is loaded at 0x90000.
394
395 Field name:     code32_start
396 Type:           modify (optional, reloc)
397 Offset/size:    0x214/4
398 Protocol:       2.00+
399
400   The address to jump to in protected mode.  This defaults to the load
401   address of the kernel, and can be used by the boot loader to
402   determine the proper load address.
403
404   This field can be modified for two purposes:
405
406   1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
407
408   2. if a bootloader which does not install a hook loads a
409      relocatable kernel at a nonstandard address it will have to modify
410      this field to point to the load address.
411
412 Field name:     ramdisk_image
413 Type:           write (obligatory)
414 Offset/size:    0x218/4
415 Protocol:       2.00+
416
417   The 32-bit linear address of the initial ramdisk or ramfs.  Leave at
418   zero if there is no initial ramdisk/ramfs.
419
420 Field name:     ramdisk_size
421 Type:           write (obligatory)
422 Offset/size:    0x21c/4
423 Protocol:       2.00+
424
425   Size of the initial ramdisk or ramfs.  Leave at zero if there is no
426   initial ramdisk/ramfs.
427
428 Field name:     bootsect_kludge
429 Type:           kernel internal
430 Offset/size:    0x220/4
431 Protocol:       2.00+
432
433   This field is obsolete.
434
435 Field name:     heap_end_ptr
436 Type:           write (obligatory)
437 Offset/size:    0x224/2
438 Protocol:       2.01+
439
440   Set this field to the offset (from the beginning of the real-mode
441   code) of the end of the setup stack/heap, minus 0x0200.
442
443 Field name:     cmd_line_ptr
444 Type:           write (obligatory)
445 Offset/size:    0x228/4
446 Protocol:       2.02+
447
448   Set this field to the linear address of the kernel command line.
449   The kernel command line can be located anywhere between the end of
450   the setup heap and 0xA0000; it does not have to be located in the
451   same 64K segment as the real-mode code itself.
452
453   Fill in this field even if your boot loader does not support a
454   command line, in which case you can point this to an empty string
455   (or better yet, to the string "auto".)  If this field is left at
456   zero, the kernel will assume that your boot loader does not support
457   the 2.02+ protocol.
458
459 Field name:     initrd_addr_max
460 Type:           read
461 Offset/size:    0x22c/4
462 Protocol:       2.03+
463
464   The maximum address that may be occupied by the initial
465   ramdisk/ramfs contents.  For boot protocols 2.02 or earlier, this
466   field is not present, and the maximum address is 0x37FFFFFF.  (This
467   address is defined as the address of the highest safe byte, so if
468   your ramdisk is exactly 131072 bytes long and this field is
469   0x37FFFFFF, you can start your ramdisk at 0x37FE0000.)
470
471 Field name:     kernel_alignment
472 Type:           read (reloc)
473 Offset/size:    0x230/4
474 Protocol:       2.05+
475
476   Alignment unit required by the kernel (if relocatable_kernel is true.)
477
478 Field name:     relocatable_kernel
479 Type:           read (reloc)
480 Offset/size:    0x234/1
481 Protocol:       2.05+
482
483   If this field is nonzero, the protected-mode part of the kernel can
484   be loaded at any address that satisfies the kernel_alignment field.
485   After loading, the boot loader must set the code32_start field to
486   point to the loaded code, or to a boot loader hook.
487
488 Field name:     cmdline_size
489 Type:           read
490 Offset/size:    0x238/4
491 Protocol:       2.06+
492
493   The maximum size of the command line without the terminating
494   zero. This means that the command line can contain at most
495   cmdline_size characters. With protocol version 2.05 and earlier, the
496   maximum size was 255.
497
498 Field name:     hardware_subarch
499 Type:           write
500 Offset/size:    0x23c/4
501 Protocol:       2.07+
502
503   In a paravirtualized environment the hardware low level architectural
504   pieces such as interrupt handling, page table handling, and
505   accessing process control registers needs to be done differently.
506
507   This field allows the bootloader to inform the kernel we are in one
508   one of those environments.
509
510   0x00000000    The default x86/PC environment
511   0x00000001    lguest
512   0x00000002    Xen
513
514 Field name:     hardware_subarch_data
515 Type:           write
516 Offset/size:    0x240/8
517 Protocol:       2.07+
518
519   A pointer to data that is specific to hardware subarch
520
521 Field name:     payload_offset
522 Type:           read
523 Offset/size:    0x248/4
524 Protocol:       2.08+
525
526   If non-zero then this field contains the offset from the end of the
527   real-mode code to the payload.
528
529   The payload may be compressed. The format of both the compressed and
530   uncompressed data should be determined using the standard magic
531   numbers. Currently only gzip compressed ELF is used.
532   
533 Field name:     payload_length
534 Type:           read
535 Offset/size:    0x24c/4
536 Protocol:       2.08+
537
538   The length of the payload.
539
540 **** THE IMAGE CHECKSUM
541
542 From boot protocol version 2.08 onwards the CRC-32 is calculated over
543 the entire file using the characteristic polynomial 0x04C11DB7 and an
544 initial remainder of 0xffffffff.  The checksum is appended to the
545 file; therefore the CRC of the file up to the limit specified in the
546 syssize field of the header is always 0.
547
548 **** THE KERNEL COMMAND LINE
549
550 The kernel command line has become an important way for the boot
551 loader to communicate with the kernel.  Some of its options are also
552 relevant to the boot loader itself, see "special command line options"
553 below.
554
555 The kernel command line is a null-terminated string. The maximum
556 length can be retrieved from the field cmdline_size.  Before protocol
557 version 2.06, the maximum was 255 characters.  A string that is too
558 long will be automatically truncated by the kernel.
559
560 If the boot protocol version is 2.02 or later, the address of the
561 kernel command line is given by the header field cmd_line_ptr (see
562 above.)  This address can be anywhere between the end of the setup
563 heap and 0xA0000.
564
565 If the protocol version is *not* 2.02 or higher, the kernel
566 command line is entered using the following protocol:
567
568         At offset 0x0020 (word), "cmd_line_magic", enter the magic
569         number 0xA33F.
570
571         At offset 0x0022 (word), "cmd_line_offset", enter the offset
572         of the kernel command line (relative to the start of the
573         real-mode kernel).
574         
575         The kernel command line *must* be within the memory region
576         covered by setup_move_size, so you may need to adjust this
577         field.
578
579 Field name:     setup_data
580 Type:           write (obligatory)
581 Offset/size:    0x250/8
582 Protocol:       2.09+
583
584   The 64-bit physical pointer to NULL terminated single linked list of
585   struct setup_data. This is used to define a more extensible boot
586   parameters passing mechanism. The definition of struct setup_data is
587   as follow:
588
589   struct setup_data {
590           u64 next;
591           u32 type;
592           u32 len;
593           u8  data[0];
594   };
595
596   Where, the next is a 64-bit physical pointer to the next node of
597   linked list, the next field of the last node is 0; the type is used
598   to identify the contents of data; the len is the length of data
599   field; the data holds the real payload.
600
601
602 **** MEMORY LAYOUT OF THE REAL-MODE CODE
603
604 The real-mode code requires a stack/heap to be set up, as well as
605 memory allocated for the kernel command line.  This needs to be done
606 in the real-mode accessible memory in bottom megabyte.
607
608 It should be noted that modern machines often have a sizable Extended
609 BIOS Data Area (EBDA).  As a result, it is advisable to use as little
610 of the low megabyte as possible.
611
612 Unfortunately, under the following circumstances the 0x90000 memory
613 segment has to be used:
614
615         - When loading a zImage kernel ((loadflags & 0x01) == 0).
616         - When loading a 2.01 or earlier boot protocol kernel.
617
618           -> For the 2.00 and 2.01 boot protocols, the real-mode code
619              can be loaded at another address, but it is internally
620              relocated to 0x90000.  For the "old" protocol, the
621              real-mode code must be loaded at 0x90000.
622
623 When loading at 0x90000, avoid using memory above 0x9a000.
624
625 For boot protocol 2.02 or higher, the command line does not have to be
626 located in the same 64K segment as the real-mode setup code; it is
627 thus permitted to give the stack/heap the full 64K segment and locate
628 the command line above it.
629
630 The kernel command line should not be located below the real-mode
631 code, nor should it be located in high memory.
632
633
634 **** SAMPLE BOOT CONFIGURATION
635
636 As a sample configuration, assume the following layout of the real
637 mode segment:
638
639     When loading below 0x90000, use the entire segment:
640
641         0x0000-0x7fff   Real mode kernel
642         0x8000-0xdfff   Stack and heap
643         0xe000-0xffff   Kernel command line
644
645     When loading at 0x90000 OR the protocol version is 2.01 or earlier:
646
647         0x0000-0x7fff   Real mode kernel
648         0x8000-0x97ff   Stack and heap
649         0x9800-0x9fff   Kernel command line
650
651 Such a boot loader should enter the following fields in the header:
652
653         unsigned long base_ptr; /* base address for real-mode segment */
654
655         if ( setup_sects == 0 ) {
656                 setup_sects = 4;
657         }
658
659         if ( protocol >= 0x0200 ) {
660                 type_of_loader = <type code>;
661                 if ( loading_initrd ) {
662                         ramdisk_image = <initrd_address>;
663                         ramdisk_size = <initrd_size>;
664                 }
665
666                 if ( protocol >= 0x0202 && loadflags & 0x01 )
667                         heap_end = 0xe000;
668                 else
669                         heap_end = 0x9800;
670
671                 if ( protocol >= 0x0201 ) {
672                         heap_end_ptr = heap_end - 0x200;
673                         loadflags |= 0x80; /* CAN_USE_HEAP */
674                 }
675
676                 if ( protocol >= 0x0202 ) {
677                         cmd_line_ptr = base_ptr + heap_end;
678                         strcpy(cmd_line_ptr, cmdline);
679                 } else {
680                         cmd_line_magic  = 0xA33F;
681                         cmd_line_offset = heap_end;
682                         setup_move_size = heap_end + strlen(cmdline)+1;
683                         strcpy(base_ptr+cmd_line_offset, cmdline);
684                 }
685         } else {
686                 /* Very old kernel */
687
688                 heap_end = 0x9800;
689
690                 cmd_line_magic  = 0xA33F;
691                 cmd_line_offset = heap_end;
692
693                 /* A very old kernel MUST have its real-mode code
694                    loaded at 0x90000 */
695
696                 if ( base_ptr != 0x90000 ) {
697                         /* Copy the real-mode kernel */
698                         memcpy(0x90000, base_ptr, (setup_sects+1)*512);
699                         base_ptr = 0x90000;              /* Relocated */
700                 }
701
702                 strcpy(0x90000+cmd_line_offset, cmdline);
703
704                 /* It is recommended to clear memory up to the 32K mark */
705                 memset(0x90000 + (setup_sects+1)*512, 0,
706                        (64-(setup_sects+1))*512);
707         }
708
709
710 **** LOADING THE REST OF THE KERNEL
711
712 The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512
713 in the kernel file (again, if setup_sects == 0 the real value is 4.)
714 It should be loaded at address 0x10000 for Image/zImage kernels and
715 0x100000 for bzImage kernels.
716
717 The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01
718 bit (LOAD_HIGH) in the loadflags field is set:
719
720         is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01);
721         load_address = is_bzImage ? 0x100000 : 0x10000;
722
723 Note that Image/zImage kernels can be up to 512K in size, and thus use
724 the entire 0x10000-0x90000 range of memory.  This means it is pretty
725 much a requirement for these kernels to load the real-mode part at
726 0x90000.  bzImage kernels allow much more flexibility.
727
728
729 **** SPECIAL COMMAND LINE OPTIONS
730
731 If the command line provided by the boot loader is entered by the
732 user, the user may expect the following command line options to work.
733 They should normally not be deleted from the kernel command line even
734 though not all of them are actually meaningful to the kernel.  Boot
735 loader authors who need additional command line options for the boot
736 loader itself should get them registered in
737 Documentation/kernel-parameters.txt to make sure they will not
738 conflict with actual kernel options now or in the future.
739
740   vga=<mode>
741         <mode> here is either an integer (in C notation, either
742         decimal, octal, or hexadecimal) or one of the strings
743         "normal" (meaning 0xFFFF), "ext" (meaning 0xFFFE) or "ask"
744         (meaning 0xFFFD).  This value should be entered into the
745         vid_mode field, as it is used by the kernel before the command
746         line is parsed.
747
748   mem=<size>
749         <size> is an integer in C notation optionally followed by
750         (case insensitive) K, M, G, T, P or E (meaning << 10, << 20,
751         << 30, << 40, << 50 or << 60).  This specifies the end of
752         memory to the kernel. This affects the possible placement of
753         an initrd, since an initrd should be placed near end of
754         memory.  Note that this is an option to *both* the kernel and
755         the bootloader!
756
757   initrd=<file>
758         An initrd should be loaded.  The meaning of <file> is
759         obviously bootloader-dependent, and some boot loaders
760         (e.g. LILO) do not have such a command.
761
762 In addition, some boot loaders add the following options to the
763 user-specified command line:
764
765   BOOT_IMAGE=<file>
766         The boot image which was loaded.  Again, the meaning of <file>
767         is obviously bootloader-dependent.
768
769   auto
770         The kernel was booted without explicit user intervention.
771
772 If these options are added by the boot loader, it is highly
773 recommended that they are located *first*, before the user-specified
774 or configuration-specified command line.  Otherwise, "init=/bin/sh"
775 gets confused by the "auto" option.
776
777
778 **** RUNNING THE KERNEL
779
780 The kernel is started by jumping to the kernel entry point, which is
781 located at *segment* offset 0x20 from the start of the real mode
782 kernel.  This means that if you loaded your real-mode kernel code at
783 0x90000, the kernel entry point is 9020:0000.
784
785 At entry, ds = es = ss should point to the start of the real-mode
786 kernel code (0x9000 if the code is loaded at 0x90000), sp should be
787 set up properly, normally pointing to the top of the heap, and
788 interrupts should be disabled.  Furthermore, to guard against bugs in
789 the kernel, it is recommended that the boot loader sets fs = gs = ds =
790 es = ss.
791
792 In our example from above, we would do:
793
794         /* Note: in the case of the "old" kernel protocol, base_ptr must
795            be == 0x90000 at this point; see the previous sample code */
796
797         seg = base_ptr >> 4;
798
799         cli();  /* Enter with interrupts disabled! */
800
801         /* Set up the real-mode kernel stack */
802         _SS = seg;
803         _SP = heap_end;
804
805         _DS = _ES = _FS = _GS = seg;
806         jmp_far(seg+0x20, 0);   /* Run the kernel */
807
808 If your boot sector accesses a floppy drive, it is recommended to
809 switch off the floppy motor before running the kernel, since the
810 kernel boot leaves interrupts off and thus the motor will not be
811 switched off, especially if the loaded kernel has the floppy driver as
812 a demand-loaded module!
813
814
815 **** ADVANCED BOOT LOADER HOOKS
816
817 If the boot loader runs in a particularly hostile environment (such as
818 LOADLIN, which runs under DOS) it may be impossible to follow the
819 standard memory location requirements.  Such a boot loader may use the
820 following hooks that, if set, are invoked by the kernel at the
821 appropriate time.  The use of these hooks should probably be
822 considered an absolutely last resort!
823
824 IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
825 %edi across invocation.
826
827   realmode_swtch:
828         A 16-bit real mode far subroutine invoked immediately before
829         entering protected mode.  The default routine disables NMI, so
830         your routine should probably do so, too.
831
832   code32_start:
833         A 32-bit flat-mode routine *jumped* to immediately after the
834         transition to protected mode, but before the kernel is
835         uncompressed.  No segments, except CS, are guaranteed to be
836         set up (current kernels do, but older ones do not); you should
837         set them up to BOOT_DS (0x18) yourself.
838
839         After completing your hook, you should jump to the address
840         that was in this field before your boot loader overwrote it
841         (relocated, if appropriate.)
842
843
844 **** 32-bit BOOT PROTOCOL
845
846 For machine with some new BIOS other than legacy BIOS, such as EFI,
847 LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
848 based on legacy BIOS can not be used, so a 32-bit boot protocol needs
849 to be defined.
850
851 In 32-bit boot protocol, the first step in loading a Linux kernel
852 should be to setup the boot parameters (struct boot_params,
853 traditionally known as "zero page"). The memory for struct boot_params
854 should be allocated and initialized to all zero. Then the setup header
855 from offset 0x01f1 of kernel image on should be loaded into struct
856 boot_params and examined. The end of setup header can be calculated as
857 follow:
858
859         0x0202 + byte value at offset 0x0201
860
861 In addition to read/modify/write the setup header of the struct
862 boot_params as that of 16-bit boot protocol, the boot loader should
863 also fill the additional fields of the struct boot_params as that
864 described in zero-page.txt.
865
866 After setupping the struct boot_params, the boot loader can load the
867 32/64-bit kernel in the same way as that of 16-bit boot protocol.
868
869 In 32-bit boot protocol, the kernel is started by jumping to the
870 32-bit kernel entry point, which is the start address of loaded
871 32/64-bit kernel.
872
873 At entry, the CPU must be in 32-bit protected mode with paging
874 disabled; a GDT must be loaded with the descriptors for selectors
875 __BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
876 segment; __BOOS_CS must have execute/read permission, and __BOOT_DS
877 must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
878 must be __BOOT_DS; interrupt must be disabled; %esi must hold the base
879 address of the struct boot_params; %ebp, %edi and %ebx must be zero.