diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-10 13:24:53 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-10 13:24:53 -0400 |
commit | 1fb3b526df3bd7647e7854915ae6b22299408baf (patch) | |
tree | b1fd6c9eaad0b1aff2b1df28ef1d5efcd6d7532a | |
parent | e290e6af1d22c3f5225c9d46faabdde80e27aef2 (diff) | |
parent | afbd4d42470e91470bc59040094b89cd717530bd (diff) |
Merge tag 'docs-5.2a' of git://git.lwn.net/linux
Pull more documentation updates from Jonathan Corbet:
"Some late arriving documentation changes. In particular, this contains
the conversion of the x86 docs to RST, which has been in the works for
some time but needed a couple of final tweaks"
* tag 'docs-5.2a' of git://git.lwn.net/linux: (29 commits)
Documentation: x86: convert x86_64/machinecheck to reST
Documentation: x86: convert x86_64/cpu-hotplug-spec to reST
Documentation: x86: convert x86_64/fake-numa-for-cpusets to reST
Documentation: x86: convert x86_64/5level-paging.txt to reST
Documentation: x86: convert x86_64/mm.txt to reST
Documentation: x86: convert x86_64/uefi.txt to reST
Documentation: x86: convert x86_64/boot-options.txt to reST
Documentation: x86: convert i386/IO-APIC.txt to reST
Documentation: x86: convert usb-legacy-support.txt to reST
Documentation: x86: convert orc-unwinder.txt to reST
Documentation: x86: convert resctrl_ui.txt to reST
Documentation: x86: convert microcode.txt to reST
Documentation: x86: convert pti.txt to reST
Documentation: x86: convert amd-memory-encryption.txt to reST
Documentation: x86: convert intel_mpx.txt to reST
Documentation: x86: convert protection-keys.txt to reST
Documentation: x86: convert pat.txt to reST
Documentation: x86: convert mtrr.txt to reST
Documentation: x86: convert tlb.txt to reST
Documentation: x86: convert zero-page.txt to reST
...
-rw-r--r-- | Documentation/index.rst | 1 | ||||
-rw-r--r-- | Documentation/trace/histogram.rst | 11 | ||||
-rw-r--r-- | Documentation/translations/it_IT/process/license-rules.rst | 60 | ||||
-rw-r--r-- | Documentation/x86/amd-memory-encryption.rst (renamed from Documentation/x86/amd-memory-encryption.txt) | 13 | ||||
-rw-r--r-- | Documentation/x86/boot.rst (renamed from Documentation/x86/boot.txt) | 528 | ||||
-rw-r--r-- | Documentation/x86/earlyprintk.rst (renamed from Documentation/x86/earlyprintk.txt) | 122 | ||||
-rw-r--r-- | Documentation/x86/entry_64.rst (renamed from Documentation/x86/entry_64.txt) | 12 | ||||
-rw-r--r-- | Documentation/x86/exception-tables.rst (renamed from Documentation/x86/exception-tables.txt) | 247 | ||||
-rw-r--r-- | Documentation/x86/i386/IO-APIC.rst (renamed from Documentation/x86/i386/IO-APIC.txt) | 28 | ||||
-rw-r--r-- | Documentation/x86/i386/index.rst | 10 | ||||
-rw-r--r-- | Documentation/x86/index.rst | 30 | ||||
-rw-r--r-- | Documentation/x86/intel_mpx.rst (renamed from Documentation/x86/intel_mpx.txt) | 120 | ||||
-rw-r--r-- | Documentation/x86/kernel-stacks.rst (renamed from Documentation/x86/kernel-stacks) | 20 | ||||
-rw-r--r-- | Documentation/x86/microcode.rst (renamed from Documentation/x86/microcode.txt) | 62 | ||||
-rw-r--r-- | Documentation/x86/mtrr.rst | 354 | ||||
-rw-r--r-- | Documentation/x86/mtrr.txt | 329 | ||||
-rw-r--r-- | Documentation/x86/orc-unwinder.rst (renamed from Documentation/x86/orc-unwinder.txt) | 27 | ||||
-rw-r--r-- | Documentation/x86/pat.rst | 242 | ||||
-rw-r--r-- | Documentation/x86/pat.txt | 230 | ||||
-rw-r--r-- | Documentation/x86/protection-keys.rst (renamed from Documentation/x86/protection-keys.txt) | 33 | ||||
-rw-r--r-- | Documentation/x86/pti.rst (renamed from Documentation/x86/pti.txt) | 17 | ||||
-rw-r--r-- | Documentation/x86/resctrl_ui.rst (renamed from Documentation/x86/resctrl_ui.txt) | 916 | ||||
-rw-r--r-- | Documentation/x86/tlb.rst (renamed from Documentation/x86/tlb.txt) | 30 | ||||
-rw-r--r-- | Documentation/x86/topology.rst (renamed from Documentation/x86/topology.txt) | 92 | ||||
-rw-r--r-- | Documentation/x86/usb-legacy-support.rst (renamed from Documentation/x86/usb-legacy-support.txt) | 40 | ||||
-rw-r--r-- | Documentation/x86/x86_64/5level-paging.rst (renamed from Documentation/x86/x86_64/5level-paging.txt) | 16 | ||||
-rw-r--r-- | Documentation/x86/x86_64/boot-options.rst | 335 | ||||
-rw-r--r-- | Documentation/x86/x86_64/boot-options.txt | 278 | ||||
-rw-r--r-- | Documentation/x86/x86_64/cpu-hotplug-spec.rst (renamed from Documentation/x86/x86_64/cpu-hotplug-spec) | 5 | ||||
-rw-r--r-- | Documentation/x86/x86_64/fake-numa-for-cpusets.rst (renamed from Documentation/x86/x86_64/fake-numa-for-cpusets) | 25 | ||||
-rw-r--r-- | Documentation/x86/x86_64/index.rst | 16 | ||||
-rw-r--r-- | Documentation/x86/x86_64/machinecheck.rst (renamed from Documentation/x86/x86_64/machinecheck) | 12 | ||||
-rw-r--r-- | Documentation/x86/x86_64/mm.rst | 161 | ||||
-rw-r--r-- | Documentation/x86/x86_64/mm.txt | 153 | ||||
-rw-r--r-- | Documentation/x86/x86_64/uefi.rst (renamed from Documentation/x86/x86_64/uefi.txt) | 30 | ||||
-rw-r--r-- | Documentation/x86/zero-page.rst | 45 | ||||
-rw-r--r-- | Documentation/x86/zero-page.txt | 40 |
37 files changed, 2620 insertions, 2070 deletions
diff --git a/Documentation/index.rst b/Documentation/index.rst index fec80fee512a..9e01aace4f48 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -112,6 +112,7 @@ implementation. .. toctree:: :maxdepth: 2 + x86/index sh/index Filesystem Documentation diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index f95d94d19c22..ddbaffa530f9 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -1915,7 +1915,10 @@ The following commonly-used handler.action pairs are available: The 'matching.event' specification is simply the fully qualified event name of the event that matches the target event for the - onmatch() functionality, in the form 'system.event_name'. + onmatch() functionality, in the form 'system.event_name'. Histogram + keys of both events are compared to find if events match. In case + multiple histogram keys are used, they all must match in the specified + order. Finally, the number and type of variables/fields in the 'param list' must match the number and types of the fields in the @@ -1978,9 +1981,9 @@ The following commonly-used handler.action pairs are available: /sys/kernel/debug/tracing/events/sched/sched_waking/trigger Then, when the corresponding thread is actually scheduled onto the - CPU by a sched_switch event, calculate the latency and use that - along with another variable and an event field to generate a - wakeup_latency synthetic event:: + CPU by a sched_switch event (saved_pid matches next_pid), calculate + the latency and use that along with another variable and an event field + to generate a wakeup_latency synthetic event:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\ diff --git a/Documentation/translations/it_IT/process/license-rules.rst b/Documentation/translations/it_IT/process/license-rules.rst index 91a8794ffd79..f058e06996dc 100644 --- a/Documentation/translations/it_IT/process/license-rules.rst +++ b/Documentation/translations/it_IT/process/license-rules.rst @@ -249,13 +249,13 @@ essere categorizzate in: | -2. Licenze non raccomandate: +2. Licenze deprecate: Questo tipo di licenze dovrebbero essere usate solo per codice già esistente o quando si prende codice da altri progetti. Le licenze sono disponibili nei sorgenti del kernel nella cartella:: - LICENSES/other/ + LICENSES/deprecated/ I file in questa cartella contengono il testo completo della licenza e i `Metatag`_. Il nome di questi file è lo stesso usato come identificatore @@ -263,14 +263,14 @@ essere categorizzate in: Esempi:: - LICENSES/other/ISC + LICENSES/deprecated/ISC Contiene il testo della licenza Internet System Consortium e i suoi metatag:: - LICENSES/other/ZLib + LICENSES/deprecated/GPL-1.0 - Contiene il testo della licenza ZLIB e i suoi metatag. + Contiene il testo della versione 1 della licenza GPL e i suoi metatag. Metatag: @@ -294,7 +294,55 @@ essere categorizzate in: | -3. _`Eccezioni`: +3. Solo per doppie licenze + + Queste licenze dovrebbero essere usate solamente per codice licenziato in + combinazione con un'altra licenza che solitamente è quella preferita. + Queste licenze sono disponibili nei sorgenti del kernel nella cartella:: + + LICENSES/dual + + I file in questa cartella contengono il testo completo della rispettiva + licenza e i suoi `Metatags`_. I nomi dei file sono identici agli + identificatori di licenza SPDX che dovrebbero essere usati nei file + sorgenti. + + Esempi:: + + LICENSES/dual/MPL-1.1 + + Questo file contiene il testo della versione 1.1 della licenza *Mozilla + Pulic License* e i metatag necessari:: + + LICENSES/dual/Apache-2.0 + + Questo file contiene il testo della versione 2.0 della licenza Apache e i + metatag necessari. + + Metatag: + + I requisiti per le 'altre' ('*other*') licenze sono identici a quelli per le + `Licenze raccomandate`_. + + Esempio del formato del file:: + + Valid-License-Identifier: MPL-1.1 + SPDX-URL: https://spdx.org/licenses/MPL-1.1.html + Usage-Guide: + Do NOT use. The MPL-1.1 is not GPL2 compatible. It may only be used for + dual-licensed files where the other license is GPL2 compatible. + If you end up using this it MUST be used together with a GPL2 compatible + license using "OR". + To use the Mozilla Public License version 1.1 put the following SPDX + tag/value pair into a comment according to the placement guidelines in + the licensing rules documentation: + SPDX-License-Identifier: MPL-1.1 + License-Text: + Full license text + +| + +4. _`Eccezioni`: Alcune licenze possono essere corrette con delle eccezioni che forniscono diritti aggiuntivi. Queste eccezioni sono disponibili nei sorgenti del diff --git a/Documentation/x86/amd-memory-encryption.txt b/Documentation/x86/amd-memory-encryption.rst index afc41f544dab..c48d452d0718 100644 --- a/Documentation/x86/amd-memory-encryption.txt +++ b/Documentation/x86/amd-memory-encryption.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +AMD Memory Encryption +===================== + Secure Memory Encryption (SME) and Secure Encrypted Virtualization (SEV) are features found on AMD processors. @@ -34,7 +40,7 @@ is operating in 64-bit or 32-bit PAE mode, in all other modes the SEV hardware forces the memory encryption bit to 1. Support for SME and SEV can be determined through the CPUID instruction. The -CPUID function 0x8000001f reports information related to SME: +CPUID function 0x8000001f reports information related to SME:: 0x8000001f[eax]: Bit[0] indicates support for SME @@ -48,14 +54,14 @@ CPUID function 0x8000001f reports information related to SME: addresses) If support for SME is present, MSR 0xc00100010 (MSR_K8_SYSCFG) can be used to -determine if SME is enabled and/or to enable memory encryption: +determine if SME is enabled and/or to enable memory encryption:: 0xc0010010: Bit[23] 0 = memory encryption features are disabled 1 = memory encryption features are enabled If SEV is supported, MSR 0xc0010131 (MSR_AMD64_SEV) can be used to determine if -SEV is active: +SEV is active:: 0xc0010131: Bit[0] 0 = memory encryption is not active @@ -68,6 +74,7 @@ requirements for the system. If this bit is not set upon Linux startup then Linux itself will not set it and memory encryption will not be possible. The state of SME in the Linux kernel can be documented as follows: + - Supported: The CPU supports SME (determined through CPUID instruction). diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.rst index 223e484a1304..08a2f100c0e6 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.rst @@ -1,5 +1,8 @@ - THE LINUX/x86 BOOT PROTOCOL - --------------------------- +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +The Linux/x86 Boot Protocol +=========================== On the x86 platform, the Linux kernel uses a rather complicated boot convention. This has evolved partially due to historical aspects, as @@ -10,88 +13,91 @@ real-mode DOS as a mainstream operating system. Currently, the following versions of the Linux/x86 boot protocol exist. -Old kernels: zImage/Image support only. Some very early kernels +============= ============================================================ +Old kernels zImage/Image support only. Some very early kernels may not even support a command line. -Protocol 2.00: (Kernel 1.3.73) Added bzImage and initrd support, as +Protocol 2.00 (Kernel 1.3.73) Added bzImage and initrd support, as well as a formalized way to communicate between the boot loader and the kernel. setup.S made relocatable, although the traditional setup area still assumed writable. -Protocol 2.01: (Kernel 1.3.76) Added a heap overrun warning. +Protocol 2.01 (Kernel 1.3.76) Added a heap overrun warning. -Protocol 2.02: (Kernel 2.4.0-test3-pre3) New command line protocol. +Protocol 2.02 (Kernel 2.4.0-test3-pre3) New command line protocol. Lower the conventional memory ceiling. No overwrite of the traditional setup area, thus making booting safe for systems which use the EBDA from SMM or 32-bit BIOS entry points. zImage deprecated but still supported. -Protocol 2.03: (Kernel 2.4.18-pre1) Explicitly makes the highest possible +Protocol 2.03 (Kernel 2.4.18-pre1) Explicitly makes the highest possible initrd address available to the bootloader. -Protocol 2.04: (Kernel 2.6.14) Extend the syssize field to four bytes. +Protocol 2.04 (Kernel 2.6.14) Extend the syssize field to four bytes. -Protocol 2.05: (Kernel 2.6.20) Make protected mode kernel relocatable. +Protocol 2.05 (Kernel 2.6.20) Make protected mode kernel relocatable. Introduce relocatable_kernel and kernel_alignment fields. -Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of +Protocol 2.06 (Kernel 2.6.22) Added a field that contains the size of the boot command line. -Protocol 2.07: (Kernel 2.6.24) Added paravirtualised boot protocol. +Protocol 2.07 (Kernel 2.6.24) Added paravirtualised boot protocol. Introduced hardware_subarch and hardware_subarch_data and KEEP_SEGMENTS flag in load_flags. -Protocol 2.08: (Kernel 2.6.26) Added crc32 checksum and ELF format +Protocol 2.08 (Kernel 2.6.26) Added crc32 checksum and ELF format payload. Introduced payload_offset and payload_length fields to aid in locating the payload. -Protocol 2.09: (Kernel 2.6.26) Added a field of 64-bit physical +Protocol 2.09 (Kernel 2.6.26) Added a field of 64-bit physical pointer to single linked list of struct setup_data. -Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment +Protocol 2.10 (Kernel 2.6.31) Added a protocol for relaxed alignment beyond the kernel_alignment added, new init_size and pref_address fields. Added extended boot loader IDs. -Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover +Protocol 2.11 (Kernel 3.6) Added a field for offset of EFI handover protocol entry point. -Protocol 2.12: (Kernel 3.8) Added the xloadflags field and extension fields +Protocol 2.12 (Kernel 3.8) Added the xloadflags field and extension fields to struct boot_params for loading bzImage and ramdisk above 4G in 64bit. -Protocol 2.13: (Kernel 3.14) Support 32- and 64-bit flags being set in +Protocol 2.13 (Kernel 3.14) Support 32- and 64-bit flags being set in xloadflags to support booting a 64-bit kernel from 32-bit EFI +============= ============================================================ -**** MEMORY LAYOUT -The traditional memory map for the kernel loader, used for Image or -zImage kernels, typically looks like: - - | | -0A0000 +------------------------+ - | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. -09A000 +------------------------+ - | Command line | - | Stack/heap | For use by the kernel real-mode code. -098000 +------------------------+ - | Kernel setup | The kernel real-mode code. -090200 +------------------------+ - | Kernel boot sector | The kernel legacy boot sector. -090000 +------------------------+ - | Protected-mode kernel | The bulk of the kernel image. -010000 +------------------------+ - | Boot loader | <- Boot sector entry point 0000:7C00 -001000 +------------------------+ - | Reserved for MBR/BIOS | -000800 +------------------------+ - | Typically used by MBR | -000600 +------------------------+ - | BIOS use only | -000000 +------------------------+ +Memory Layout +============= +The traditional memory map for the kernel loader, used for Image or +zImage kernels, typically looks like:: + + | | + 0A0000 +------------------------+ + | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. + 09A000 +------------------------+ + | Command line | + | Stack/heap | For use by the kernel real-mode code. + 098000 +------------------------+ + | Kernel setup | The kernel real-mode code. + 090200 +------------------------+ + | Kernel boot sector | The kernel legacy boot sector. + 090000 +------------------------+ + | Protected-mode kernel | The bulk of the kernel image. + 010000 +------------------------+ + | Boot loader | <- Boot sector entry point 0000:7C00 + 001000 +------------------------+ + | Reserved for MBR/BIOS | + 000800 +------------------------+ + | Typically used by MBR | + 000600 +------------------------+ + | BIOS use only | + 000000 +------------------------+ When using bzImage, the protected-mode kernel was relocated to 0x100000 ("high memory"), and the kernel real-mode block (boot sector, @@ -116,36 +122,36 @@ zImage or old bzImage kernels, which need data written into the 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 +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 +=========================== In the following text, and anywhere in the kernel boot sequence, "a sector" refers to 512 bytes. It is independent of the actual sector @@ -159,61 +165,63 @@ sectors (1K) and then examine the bootup sector size. The header looks like: -Offset Proto Name Meaning -/Size - -01F1/1 ALL(1 setup_sects The size of the setup in sectors -01F2/2 ALL root_flags If set, the root is mounted readonly -01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras -01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only -01FA/2 ALL vid_mode Video mode control -01FC/2 ALL root_dev Default root device number -01FE/2 ALL boot_flag 0xAA55 magic number -0200/2 2.00+ jump Jump instruction -0202/4 2.00+ header Magic signature "HdrS" -0206/2 2.00+ version Boot protocol version supported -0208/4 2.00+ realmode_swtch Boot loader hook (see below) -020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete) -020E/2 2.00+ kernel_version Pointer to kernel version string -0210/1 2.00+ type_of_loader Boot loader identifier -0211/1 2.00+ loadflags Boot protocol option flags -0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) -0214/4 2.00+ code32_start Boot loader hook (see below) -0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) -021C/4 2.00+ ramdisk_size initrd size (set by boot loader) -0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only -0224/2 2.01+ heap_end_ptr Free memory after setup end -0226/1 2.02+(3 ext_loader_ver Extended boot loader version -0227/1 2.02+(3 ext_loader_type Extended boot loader ID -0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line -022C/4 2.03+ initrd_addr_max Highest legal initrd address -0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel -0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not -0235/1 2.10+ min_alignment Minimum alignment, as a power of two -0236/2 2.12+ xloadflags Boot protocol option flags -0238/4 2.06+ cmdline_size Maximum size of the kernel command line -023C/4 2.07+ hardware_subarch Hardware subarchitecture -0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data -0248/4 2.08+ payload_offset Offset of kernel payload -024C/4 2.08+ payload_length Length of kernel payload -0250/8 2.09+ setup_data 64-bit physical pointer to linked list - of struct setup_data -0258/8 2.10+ pref_address Preferred loading address -0260/4 2.10+ init_size Linear memory required during initialization -0264/4 2.11+ handover_offset Offset of handover entry point - -(1) For backwards compatibility, if the setup_sects field contains 0, the - real value is 4. - -(2) For boot protocol prior to 2.04, the upper two bytes of the syssize - field are unusable, which means the size of a bzImage kernel - cannot be determined. - -(3) Ignored, but safe to set, for boot protocols 2.02-2.09. +=========== ======== ===================== ============================================ +Offset/Size Proto Name Meaning +=========== ======== ===================== ============================================ +01F1/1 ALL(1) setup_sects The size of the setup in sectors +01F2/2 ALL root_flags If set, the root is mounted readonly +01F4/4 2.04+(2) syssize The size of the 32-bit code in 16-byte paras +01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only +01FA/2 ALL vid_mode Video mode control +01FC/2 ALL root_dev Default root device number +01FE/2 ALL boot_flag 0xAA55 magic number +0200/2 2.00+ jump Jump instruction +0202/4 2.00+ header Magic signature "HdrS" +0206/2 2.00+ version Boot protocol version supported +0208/4 2.00+ realmode_swtch Boot loader hook (see below) +020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete) +020E/2 2.00+ kernel_version Pointer to kernel version string +0210/1 2.00+ type_of_loader Boot loader identifier +0211/1 2.00+ loadflags Boot protocol option flags +0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) +0214/4 2.00+ code32_start Boot loader hook (see below) +0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) +021C/4 2.00+ ramdisk_size initrd size (set by boot loader) +0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only +0224/2 2.01+ heap_end_ptr Free memory after setup end +0226/1 2.02+(3) ext_loader_ver Extended boot loader version +0227/1 2.02+(3) ext_loader_type Extended boot loader ID +0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line +022C/4 2.03+ initrd_addr_max Highest legal initrd address +0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel +0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not +0235/1 2.10+ min_alignment Minimum alignment, as a power of two +0236/2 2.12+ xloadflags Boot protocol option flags +0238/4 2.06+ cmdline_size Maximum size of the kernel command line +023C/4 2.07+ hardware_subarch Hardware subarchitecture +0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data +0248/4 2.08+ payload_offset Offset of kernel payload +024C/4 2.08+ payload_length Length of kernel payload +0250/8 2.09+ setup_data 64-bit physical pointer to linked list + of struct setup_data +0258/8 2.10+ pref_address Preferred loading address +0260/4 2.10+ init_size Linear memory required during initialization +0264/4 2.11+ handover_offset Offset of handover entry point +=========== ======== ===================== ============================================ + +.. note:: + (1) For backwards compatibility, if the setup_sects field contains 0, the + real value is 4. + + (2) For boot protocol prior to 2.04, the upper two bytes of the syssize + field are unusable, which means the size of a bzImage kernel + cannot be determined. + + (3) Ignored, but safe to set, for boot protocols 2.02-2.09. If the "HdrS" (0x53726448) magic number is not found at offset 0x202, the boot protocol version is "old". Loading an old kernel, the -following parameters should be assumed: +following parameters should be assumed:: Image type = zImage initrd not supported @@ -225,7 +233,8 @@ setting fields in the header, you must make sure only to set fields supported by the protocol version in use. -**** DETAILS OF HEADER FIELDS +Details of Harder Fileds +======================== For each field, some are information from the kernel to the bootloader ("read"), some are expected to be filled out by the bootloader @@ -239,106 +248,132 @@ boot loaders can ignore those fields. The byte order of all fields is littleendian (this is x86, after all.) +============ =========== Field name: setup_sects 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 +============ ================= +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: realmode_swtch Type: modify (optional) Offset/size: 0x208/4 Protocol: 2.00+ +============ ================= Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) +============ ============= Field name: start_sys_seg Type: read Offset/size: 0x20c/2 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 @@ -348,17 +383,19 @@ Protocol: 2.00+ 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 15 or higher, as: + contains the value 15 or higher, as:: 0x1c00 < 15*0x200 (= 0x1e00) but 0x1c00 >= 14*0x200 (= 0x1c00) - 0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15. + 0x1c00 >> 9 = 14, So the minimum value for |