diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingStyle | 49 | ||||
| -rw-r--r-- | Documentation/DocBook/gadget.tmpl | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/kernel-locking.tmpl | 123 | ||||
| -rw-r--r-- | Documentation/DocBook/usb.tmpl | 28 | ||||
| -rw-r--r-- | Documentation/HOWTO | 20 | ||||
| -rw-r--r-- | Documentation/block/capability.txt | 15 | ||||
| -rw-r--r-- | Documentation/dontdiff | 42 | ||||
| -rw-r--r-- | Documentation/feature-removal-schedule.txt | 27 | ||||
| -rw-r--r-- | Documentation/filesystems/directory-locking | 5 | ||||
| -rw-r--r-- | Documentation/filesystems/porting | 8 | ||||
| -rw-r--r-- | Documentation/gpio.txt | 8 | ||||
| -rw-r--r-- | Documentation/i386/boot.txt | 401 | ||||
| -rw-r--r-- | Documentation/initrd.txt | 74 | ||||
| -rw-r--r-- | Documentation/kernel-parameters.txt | 24 | ||||
| -rw-r--r-- | Documentation/ldm.txt | 21 | ||||
| -rw-r--r-- | Documentation/memory-barriers.txt | 98 | ||||
| -rw-r--r-- | Documentation/networking/netdevices.txt | 2 | ||||
| -rw-r--r-- | Documentation/s390/cds.txt | 82 | ||||
| -rw-r--r-- | Documentation/spi/spi-summary | 53 | ||||
| -rw-r--r-- | Documentation/vm/slabinfo.c | 26 |
20 files changed, 725 insertions, 383 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index afc28677589..b49b92edb39 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -495,29 +495,40 @@ re-formatting you may want to take a look at the man page. But remember: "indent" is not a fix for bad programming. - Chapter 10: Configuration-files + Chapter 10: Kconfig configuration files -For configuration options (arch/xxx/Kconfig, and all the Kconfig files), -somewhat different indentation is used. +For all of the Kconfig* configuration files throughout the source tree, +the indentation is somewhat different. Lines under a "config" definition +are indented with one tab, while help text is indented an additional two +spaces. Example: -Help text is indented with 2 spaces. - -if CONFIG_EXPERIMENTAL - tristate CONFIG_BOOM - default n - help - Apply nitroglycerine inside the keyboard (DANGEROUS) - bool CONFIG_CHEER - depends on CONFIG_BOOM - default y +config AUDIT + bool "Auditing support" + depends on NET help - Output nice messages when you explode -endif + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +Features that might still be considered unstable should be defined as +dependent on "EXPERIMENTAL": + +config SLUB + depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT + bool "SLUB (Unqueued Allocator)" + ... + +while seriously dangerous features (such as write support for certain +filesystems) should advertise this prominently in their prompt string: + +config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... -Generally, CONFIG_EXPERIMENTAL should surround all options not considered -stable. All options that are known to trash data (experimental write- -support for file-systems, for instance) should be denoted (DANGEROUS), other -experimental options should be denoted (EXPERIMENTAL). +For full documentation on the configuration files, see the file +Documentation/kbuild/kconfig-language.txt. Chapter 11: Data structures diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index e7fc9643340..6996d977bf8 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -52,7 +52,7 @@ <toc></toc> -<chapter><title>Introduction</title> +<chapter id="intro"><title>Introduction</title> <para>This document presents a Linux-USB "Gadget" kernel mode diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 644c3884fab..0a441f73261 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -551,10 +551,12 @@ <function>spin_lock_irqsave()</function>, which is a superset of all other spinlock primitives. </para> + <table> <title>Table of Locking Requirements</title> <tgroup cols="11"> <tbody> + <row> <entry></entry> <entry>IRQ Handler A</entry> @@ -576,97 +578,128 @@ <row> <entry>IRQ Handler B</entry> -<entry>spin_lock_irqsave</entry> +<entry>SLIS</entry> <entry>None</entry> </row> <row> <entry>Softirq A</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> </row> <row> <entry>Softirq B</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> </row> <row> <entry>Tasklet A</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> <entry>None</entry> </row> <row> <entry>Tasklet B</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> <entry>None</entry> </row> <row> <entry>Timer A</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> <entry>None</entry> </row> <row> <entry>Timer B</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> -<entry>spin_lock</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> <entry>None</entry> </row> <row> <entry>User Context A</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> <entry>None</entry> </row> <row> <entry>User Context B</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>DI</entry> +<entry>None</entry> +</row> + +</tbody> +</tgroup> +</table> + + <table> +<title>Legend for Locking Requirements Table</title> +<tgroup cols="2"> +<tbody> + +<row> +<entry>SLIS</entry> +<entry>spin_lock_irqsave</entry> +</row> +<row> +<entry>SLI</entry> <entry>spin_lock_irq</entry> -<entry>spin_lock_irq</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> -<entry>spin_lock_bh</entry> +</row> +<row> +<entry>SL</entry> +<entry>spin_lock</entry> +</row> +<row> +<entry>SLBH</entry> <entry>spin_lock_bh</entry> +</row> +<row> +<entry>DI</entry> <entry>down_interruptible</entry> -<entry>None</entry> </row> </tbody> </tgroup> </table> + </sect1> </chapter> diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index a2ebd651b05..af293606fbe 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -185,7 +185,7 @@ </chapter> -<chapter><title>USB-Standard Types</title> +<chapter id="types"><title>USB-Standard Types</title> <para>In <filename><linux/usb/ch9.h></filename> you will find the USB data types defined in chapter 9 of the USB specification. @@ -197,7 +197,7 @@ </chapter> -<chapter><title>Host-Side Data Types and Macros</title> +<chapter id="hostside"><title>Host-Side Data Types and Macros</title> <para>The host side API exposes several layers to drivers, some of which are more necessary than others. @@ -211,7 +211,7 @@ </chapter> - <chapter><title>USB Core APIs</title> + <chapter id="usbcore"><title>USB Core APIs</title> <para>There are two basic I/O models in the USB API. The most elemental one is asynchronous: drivers submit requests @@ -248,7 +248,7 @@ !Edrivers/usb/core/hub.c </chapter> - <chapter><title>Host Controller APIs</title> + <chapter id="hcd"><title>Host Controller APIs</title> <para>These APIs are only for use by host controller drivers, most of which implement standard register interfaces such as @@ -285,7 +285,7 @@ !Idrivers/usb/core/buffer.c </chapter> - <chapter> + <chapter id="usbfs"> <title>The USB Filesystem (usbfs)</title> <para>This chapter presents the Linux <emphasis>usbfs</emphasis>. @@ -317,7 +317,7 @@ not it has a kernel driver. </para> - <sect1> + <sect1 id="usbfs-files"> <title>What files are in "usbfs"?</title> <para>Conventionally mounted at @@ -356,7 +356,7 @@ </sect1> - <sect1> + <sect1 id="usbfs-fstab"> <title>Mounting and Access Control</title> <para>There are a number of mount options for usbfs, which will @@ -439,7 +439,7 @@ </sect1> - <sect1> + <sect1 id="usbfs-devices"> <title>/proc/bus/usb/devices</title> <para>This file is handy for status viewing tools in user @@ -473,7 +473,7 @@ for (;;) { </para> </sect1> - <sect1> + <sect1 id="usbfs-bbbddd"> <title>/proc/bus/usb/BBB/DDD</title> <para>Use these files in one of these basic ways: @@ -510,7 +510,7 @@ for (;;) { </sect1> - <sect1> + <sect1 id="usbfs-lifecycle"> <title>Life Cycle of User Mode Drivers</title> <para>Such a driver first needs to find a device file @@ -565,7 +565,7 @@ for (;;) { </sect1> - <sect1><title>The ioctl() Requests</title> + <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title> <para>To use these ioctls, you need to include the following headers in your userspace program: @@ -604,7 +604,7 @@ for (;;) { </para> - <sect2> + <sect2 id="usbfs-mgmt"> <title>Management/Status Requests</title> <para>A number of usbfs requests don't deal very directly @@ -736,7 +736,7 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param) </sect2> - <sect2> + <sect2 id="usbfs-sync"> <title>Synchronous I/O Support</title> <para>Synchronous requests involve the kernel blocking @@ -865,7 +865,7 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param) </variablelist> </sect2> - <sect2> + <sect2 id="usbfs-async"> <title>Asynchronous I/O Support</title> <para>As mentioned above, there are situations where it may be diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 48123dba5e6..ced9207bedc 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -396,26 +396,6 @@ bugme-janitor mailing list (every change in the bugzilla is mailed here) -Managing bug reports --------------------- - -One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, you'll learn to fix real world problems and you will improve -your skills, and other developers will be aware of your presence. Fixing -bugs is one of the best ways to get merits among other developers, because -not many people like wasting time fixing other people's bugs. - -To work in the already reported bug reports, go to http://bugzilla.kernel.org. -If you want to be advised of the future bug reports, you can subscribe to the -bugme-new mailing list (only new bug reports are mailed here) or to the -bugme-janitor mailing list (every change in the bugzilla is mailed here) - - http://lists.osdl.org/mailman/listinfo/bugme-new - http://lists.osdl.org/mailman/listinfo/bugme-janitors - - - Mailing lists ------------- diff --git a/Documentation/block/capability.txt b/Documentation/block/capability.txt new file mode 100644 index 00000000000..2f1729424ef --- /dev/null +++ b/Documentation/block/capability.txt @@ -0,0 +1,15 @@ +Generic Block Device Capability +=============================================================================== +This file documents the sysfs file block/<disk>/capability + +capability is a hex word indicating which capabilities a specific disk +supports. For more information on bits not listed here, see +include/linux/genhd.h + +Capability Value +------------------------------------------------------------------------------- +GENHD_FL_MEDIA_CHANGE_NOTIFY 4 + When this bit is set, the disk supports Asynchronous Notification + of media change events. These events will be broadcast to user + space via kernel uevent. + diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 64e9f6c4826..595a5ea4c69 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -10,10 +10,12 @@ *.grp *.gz *.html +*.i *.jpeg *.ko *.log *.lst +*.moc *.mod.c *.o *.orig @@ -25,6 +27,9 @@ *.s *.sgml *.so +*.symtypes +*.tab.c +*.tab.h *.tex *.ver *.xml @@ -32,9 +37,13 @@ *_vga16.c *cscope* *~ +*.9 +*.9.gz .* .cscope 53c700_d.h +53c7xx_d.h +53c7xx_u.h 53c8xx_d.h* BitKeeper COPYING @@ -70,9 +79,11 @@ bzImage* classlist.h* comp*.log compile.h* +conf config config-* config_data.h* +config_data.gz* conmakehash consolemap_deftbl.c* crc32table.h* @@ -81,18 +92,23 @@ defkeymap.c* devlist.h* docproc dummy_sym.c* +elf2ecoff elfconfig.h* filelist fixdep fore200e_mkfirm fore200e_pca_fw.c* +gconf gen-devlist gen-kdb_cmds.c* gen_crc32table gen_init_cpio genksyms gentbl +*_gray256.c ikconfig.h* +initramfs_data.cpio +initramfs_data.cpio.gz initramfs_list kallsyms kconfig @@ -100,19 +116,30 @@ kconfig.tk keywords.c* ksym.c* ksym.h* +kxgettext +lkc_defs.h lex.c* +lex.*.c +lk201-map.c logo_*.c logo_*_clut224.c logo_*_mono.c lxdialog mach-types mach-types.h +machtypes.h make_times_h map maui_boot.h +mconf +miboot* mk_elfconfig +mkboot +mkbugboot mkdep +mkprep mktables +mktree modpost modversions.h* offset.h @@ -120,18 +147,28 @@ offsets.h oui.c* parse.c* parse.h* +patches* +pca200e.bin +pca200e_ecd.bin2 +piggy.gz +piggyback pnmtologo ppc_defs.h* promcon_tbl.c* pss_boot.h +qconf raid6altivec*.c raid6int*.c raid6tables.c +relocs +series setup sim710_d.h* +sImage sm_tbl* split-include tags +tftpboot.img times.h* tkparse trix_boot.h @@ -139,8 +176,11 @@ utsrelease.h* version.h* vmlinux vmlinux-* +vmlinux.aout vmlinux.lds vsyscall.lds wanxlfw.inc uImage -zImage +unifdef +zImage* +zconf.hash.c diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 498ff31f3aa..2d7ea85075b 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -62,7 +62,7 @@ Who: Dan Dennedy <dan@dennedy.org>, Stefan Richter <stefanr@s5r6.in-berlin.de> What: old NCR53C9x driver When: October 2007 Why: Replaced by the much better esp_scsi driver. Actual low-level - driver can ported over almost trivially. + driver can be ported over almost trivially. Who: David Miller <davem@davemloft.net> Christoph Hellwig <hch@lst.de> @@ -328,21 +328,20 @@ Who: Adrian Bunk <bunk@stusta.de> --------------------------- -What: libata.spindown_compat module parameter +What: libata spindown skipping and warning When: Dec 2008 -Why: halt(8) synchronizes caches for and spins down libata disks - because libata didn't use to spin down disk on system halt - (only synchronized caches). - Spin down on system halt is now implemented and can be tested - using sysfs node /sys/class/scsi_disk/h:c:i:l/manage_start_stop. +Why: Some halt(8) implementations synchronize caches for and spin + down libata disks because libata didn't use to spin down disk on + system halt (only synchronized caches). + Spin down on system halt is now implemented. sysfs node + /sys/class/scsi_disk/h:c:i:l/manage_start_stop is present if + spin down support is available. Because issuing spin down command to an already spun down disk - makes some disks spin up just to spin down again, the old - behavior needs to be maintained till userspace tool is updated - to check the sysfs node and not to spin down disks with the - node set to one. - This module parameter is to give userspace tool the time to - get updated and should be removed after userspace is - reasonably updated. + makes some disks spin up just to spin down again, libata tracks + device spindown status to skip the extra spindown command and + warn about it. + This is to give userspace tools the time to get updated and will + be removed after userspace is reasonably updated. Who: Tejun Heo <htejun@gmail.com> --------------------------- diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking index d7099a9266f..ff7b611abf3 100644 --- a/Documentation/filesystems/directory-locking +++ b/Documentation/filesystems/directory-locking @@ -1,5 +1,6 @@ Locking scheme used for directory operations is based on two -kinds of locks - per-inode (->i_sem) and per-filesystem (->s_vfs_rename_sem). +kinds of locks - per-inode (->i_mutex) and per-filesystem +(->s_vfs_rename_mutex). For our purposes all operations fall in 5 classes: @@ -63,7 +64,7 @@ objects - A < B iff A is an ancestor of B. attempt to acquire some lock and already holds at least one lock. Let's consider the set of contended locks. First of all, filesystem lock is not contended, since any process blocked on it is not holding any locks. -Thus all processes are blocked on ->i_sem. +Thus all processes are blocked on ->i_mutex. Non-directory objects are not contended due to (3). Thus link creation can't be a part of deadlock - it can't be blocked on source diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 5531694059a..dac45c92d87 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -107,7 +107,7 @@ free to drop it... --- [informational] -->link() callers hold ->i_sem on the object we are linking to. Some of your +->link() callers hold ->i_mutex on the object we are linking to. Some of your problems might be over... --- @@ -130,9 +130,9 @@ went in - and hadn't been documented ;-/). Just remove it from fs_flags --- [mandatory] -->setattr() is called without BKL now. Caller _always_ holds ->i_sem, so -watch for ->i_sem-grabbing code that might be used by your ->setattr(). -Callers of notify_change() need ->i_sem now. +->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so +watch for ->i_mutex-grabbing code that might be used by your ->setattr(). +Callers of notify_change() need ->i_mutex now. --- [recommended] diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index e8be0abb346..36af58eba13 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -111,7 +111,9 @@ setting up a platform_device using the GPIO, is mark its direction: The return value is zero for success, else a negative errno. It should be checked, since the get/set calls don't have error returns and since -misconfiguration is possible. (These calls could sleep.) +misconfiguration is possible. You should normally issue these calls from +a task context. However, for spinlock-safe GPIOs it's OK to use them +before tasking is enabled, as part of early board setup. For output GPIOs, the value provided becomes the initial output value. This helps avoid signal glitching during system startup. @@ -197,7 +199,9 @@ However, many platforms don't currently support this mechanism. Passing invalid GPIO numbers to gpio_request() will fail, as will requesting GPIOs that have already been claimed with that call. The return value of -gpio_request() must be checked. (These calls could sleep.) +gpio_request() must be checked. You should normally issue these calls from +a task context. However, for spinlock-safe GPIOs it's OK to request GPIOs +before tasking is enabled, as part of early board setup. These calls serve two basic purposes. One is marking the signals which are actually in use as GPIOs, for better diagnostics; systems may have diff --git a/Documentation/i386/boot.txt b/Documentation/i386/boot.txt index d01b7a2a0f2..35985b34d5a 100644 --- a/Documentation/i386/boot.txt +++ b/Documentation/i386/boot.txt @@ -2,7 +2,7 @@ ---------------------------- H. Peter Anvin <hpa@zytor.com> - Last update 2007-05-07 + Last update 2007-05-23 On the i386 platform, the Linux kernel uses a rather complicated boot convention. This has evolved partially due to historical aspects, as @@ -52,7 +52,8 @@ zImage kernels, typically looks like: 0A0000 +------------------------+ | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. 09A000 +------------------------+ - | Stack/heap/cmdline | For use by the kernel real-mode code. + | Command line | + | Stack/heap | For use by the kernel real-mode code. 098000 +------------------------+ | Kernel setup | The kernel real-mode code. 090200 +------------------------+ @@ -73,10 +74,9 @@ zImage kernels, typically looks like: When using bzImage, the protected-mode kernel was relocated to 0x100000 ("high memory"), and the kernel real-mode block (boot sector, setup, and stack/heap) was made relocatable to any address between -0x10000 and end of low memory. Unfortunately, in protocols 2.00 and -2.01 the command line is still required to live in the 0x9XXXX memory -range, and that memory range is still overwritten by the early kernel. -The 2.02 protocol resolves that problem. +0x10000 and end of low memory. Unfortunately, in protocols 2.00 and +2.01 the 0x90000+ memory range is still used internally by the kernel; +the 2.02 protocol resolves that problem. It is desirable to keep the "memory ceiling" -- the highest point in low memory touched by the boot loader -- as low as possible, since @@ -93,6 +93,35 @@ zImage or old bzImage kernels, which need data written into the 0x90000 segment, the boot loader should make sure not to use memory above the 0x9A000 point; too many BIOSes will break above that point. +For a modern bzImage kernel with boot protocol version >= 2.02, a +memory layout like the following is suggested: + + ~ ~ + | Protected-mode kernel | +100000 +------------------------+ + | I/O memory hole | +0A0000 +------------------------+ + | Reserved for BIOS | Leave as much as possible unused + ~ ~ + | Command line | (Can also be below the X+10000 mark) +X+10000 +------------------------+ + | Stack/heap | For use by the kernel real-mode code. +X+08000 +------------------------+ + | Kernel setup | The kernel real-mode code. + | Kernel boot sector | The kernel legacy boot sector. +X +------------------------+ + | Boot loader | <- Boot sector entry point 0000:7C00 +001000 +------------------------+ + | Reserved for MBR/BIOS | +000800 +------------------------+ + | Typically used by MBR | +000600 +------------------------+ + | BIOS use only | +000000 +------------------------+ + +... where the address X is as low as the design of the boot loader +permits. + **** THE REAL-MODE KERNEL HEADER @@ -160,29 +189,147 @@ e.g. protocol version 2.01 will contain 0x0201 in this field. When setting fields in the header, you must make sure only to set fields supported by the protocol version in use. -The "kernel_version" field, if set to a nonzero value, contains a -pointer to a null-terminated human-readable kernel version number -string, less 0x200. This can be used to display the kernel version to -the user. This value should be less than (0x200*setup_sects). For -example, if this value is set to 0x1c00, the kernel version number -string can be found at offset 0x1e00 in the kernel file. This is a -valid value if and only if the "setup_sects" field contains the value -14 or higher. - -Most boot loaders will simply load the kernel at its target address -directly. Such boot loaders do not need to worry about filling in -most of the fields in the header. The following fields should be -filled out, however: - - vid_mode: - Please see the section on SPECIAL COMMAND LINE OPTIONS. - - type_of_loader: - If your boot loader has an assigned id (see table below), enter - 0xTV here, where T is an identifier for the boot loader and V is - a version number. Otherwise, enter 0xFF here. - - Assigned boot loader ids: + +**** DETAILS OF HEADER FIELDS + +For each field, some are information from the kernel to the bootloader +("read"), some are expected to be filled out by the bootloader +("write"), and some are expected to be read and modified by the +bootloader ("modify"). + +All general purpose boot loaders should write the fields marked +(obligatory). Boot loaders who want to load the kernel at a +nonstandard address should fill in the fields marked (reloc); other +boot loaders can ignore those fields. + +The byte order of all fields is littleendian (this is x86, after all.) + +Field name: setup_secs +Type: read +Offset/size: 0x1f1/1 +Protocol: ALL + + The size of the setup code in 512-byte sectors. If this field is + 0, the real value is 4. The real-mode code consists of the boot + sector (always one 512-byte sector) plus the setup code. + +Field name: root_flags +Type: modify (optional) +Offset/size: 0x1f2/2 +Protocol: ALL + + If this field is nonzero, the root defaults to readonly. The use of + this field is deprecated; use the "ro" or "rw" options on the + command line instead. + +Field name: syssize +Type: read +Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL) +Protocol: 2.04+ + + The size of the protected-mode code in units of 16-byte paragraphs. + For protocol versions older than 2.04 this field is only two bytes + wide, and therefore cannot be trusted for the size of a kernel if + the LOAD_HIGH flag is set. + +Field name: ram_size +Type: kernel internal +Offset/size: 0x1f8/2 +Protocol: ALL + + This field is obsolete. + +Field name: vid_mode +Type: modify (obligatory) +Offset/size: 0x1fa/2 + + Please see the section on SPECIAL COMMAND LINE OPTIONS. + +Field name: root_dev +Type: modify (optional) +Offset/size: 0x1fc/2 +Protocol: ALL + + The default root device device number. The use of this field is + deprecated, use the "root=" option on the command line instead. + +Field name: boot_flag +Type: read +Offset/size: 0x1fe/2 +Protocol: ALL + + Contains 0xAA55. This is the closest thing old Linux kernels have + to a magic number. + +Field name: jump +Type: read +Offset/size: 0x200/2 +Protocol: 2.00+ + + Contains an x86 jump instruction, 0xEB followed by a signed offset + relative to byte 0x202. This can be used to determine the size of + the header. + +Field name: header +Type: read +Offset/size: 0x202/4 +Protocol: 2.00+ + + Contains the magic number "HdrS" (0x53726448). + +Field name: version +Type: read +Offset/size: 0x206/2 +Protocol: 2.00+ + + Contains the boot protocol version, in (major << 8)+minor format, + e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version + 10.17. + +Field name: readmode_swtch +Type: modify (optional) +Offset/size: 0x208/4 +Protocol: 2.00+ + + Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) + +Field name: start_sys +Type: read +Offset/size: 0x20c/4 +Protocol: 2.00+ + + The load low segment (0x1000). Obsolete. + +Field name: kernel_version +Type: read +Offset/size: 0x20e/2 +Protocol: 2.00+ + + If set to a nonzero value, contains a pointer to a NUL-terminated + human-readable kernel version number string, less 0x200. This can + be used to display the kernel version to the user. This value + should be less than (0x200*setup_sects). |