summaryrefslogtreecommitdiff
path: root/doc/www.kernel.org_doc_html_latest_x86_boot.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/www.kernel.org_doc_html_latest_x86_boot.txt')
-rw-r--r--doc/www.kernel.org_doc_html_latest_x86_boot.txt2349
1 files changed, 2349 insertions, 0 deletions
diff --git a/doc/www.kernel.org_doc_html_latest_x86_boot.txt b/doc/www.kernel.org_doc_html_latest_x86_boot.txt
new file mode 100644
index 0000000..0ef56f7
--- /dev/null
+++ b/doc/www.kernel.org_doc_html_latest_x86_boot.txt
@@ -0,0 +1,2349 @@
+ #[1]Index [2]Search [3]2. DeviceTree Booting [4]x86-specific
+ Documentation
+
+[5]The Linux Kernel
+
+ 6.3.0-rc6
+
+Quick search
+
+ ____________________ Go
+
+Contents
+
+ [X]
+ * [6]A guide to the Kernel Development Process
+ * [7]Submitting patches: the essential guide to getting your code
+ into the kernel
+ * [8]Code of conduct
+ * [9]Kernel Maintainer Handbook
+ * [10]All development-process docs
+
+ * [11]Core API Documentation
+ * [12]Driver implementer's API guide
+ * [13]Kernel subsystem documentation
+ * [14]Locking in the kernel
+
+ * [15]Linux kernel licensing rules
+ * [16]How to write kernel documentation
+ * [17]Development tools for the kernel
+ * [18]Kernel Testing Guide
+ * [19]Kernel Hacking Guides
+ * [20]Linux Tracing Technologies
+ * [21]fault-injection
+ * [22]Kernel Livepatching
+ * [23]Rust
+
+ * [24]The Linux kernel user's and administrator's guide
+ * [25]The kernel build system
+ * [26]Reporting issues
+ * [27]User-space tools
+ * [28]The Linux kernel user-space API guide
+
+ * [29]The Linux kernel firmware guide
+ * [30]Open Firmware and Devicetree
+
+ * [31]CPU Architectures
+ + [32]ARC architecture
+ + [33]ARM Architecture
+ + [34]ARM64 Architecture
+ + [35]IA-64 Architecture
+ + [36]LoongArch Architecture
+ + [37]m68k Architecture
+ + [38]MIPS-specific Documentation
+ + [39]Nios II Specific Documentation
+ + [40]OpenRISC Architecture
+ + [41]PA-RISC Architecture
+ + [42]powerpc
+ + [43]RISC-V architecture
+ + [44]s390 Architecture
+ + [45]SuperH Interfaces Guide
+ + [46]Sparc Architecture
+ + [47]x86-specific Documentation
+ o [48]1. The Linux/x86 Boot Protocol
+ o [49]2. DeviceTree Booting
+ o [50]3. x86 Feature Flags
+ o [51]4. x86 Topology
+ o [52]5. Kernel level exception handling
+ o [53]6. Kernel Stacks
+ o [54]7. Kernel Entries
+ o [55]8. Early Printk
+ o [56]9. ORC unwinder
+ o [57]10. Zero Page
+ o [58]11. The TLB
+ o [59]12. MTRR (Memory Type Range Register) control
+ o [60]13. PAT (Page Attribute Table)
+ o [61]14. Hardware-Feedback Interface for scheduling on
+ Intel Hardware
+ o [62]15. x86 IOMMU Support
+ o [63]16. Intel(R) TXT Overview
+ o [64]17. AMD Memory Encryption
+ o [65]18. AMD HSMP interface
+ o [66]19. Intel Trust Domain Extensions (TDX)
+ o [67]20. Page Table Isolation (PTI)
+ o [68]21. Microarchitectural Data Sampling (MDS) mitigation
+ o [69]22. The Linux Microcode Loader
+ o [70]23. User Interface for Resource Control feature
+ o [71]24. TSX Async Abort (TAA) mitigation
+ o [72]25. Bus lock detection and handling
+ o [73]26. USB Legacy support
+ o [74]27. i386 Support
+ o [75]28. x86_64 Support
+ o [76]29. In-Field Scan
+ o [77]30. Shared Virtual Addressing (SVA) with ENQCMD
+ o [78]31. Software Guard eXtensions (SGX)
+ o [79]32. Feature status on x86 architecture
+ o [80]33. x86-specific ELF Auxiliary Vectors
+ o [81]34. Using XSTATE features in user space applications
+ + [82]Xtensa Architecture
+
+ * [83]Unsorted Documentation
+
+ * [84]Translations
+
+This Page
+
+ * [85]Show Source
+
+1. The Linux/x86 Boot Protocol[86]¶
+
+ On the x86 platform, the Linux kernel uses a rather complicated boot
+ convention. This has evolved partially due to historical aspects, as
+ well as the desire in the early days to have the kernel itself be a
+ bootable image, the complicated PC memory model and due to changed
+ expectations in the PC industry caused by the effective demise of
+ 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 may not even support
+ a command line.
+
+ 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.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 initrd
+ address available to the bootloader.
+
+ 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. Introduce
+ relocatable_kernel and kernel_alignment fields.
+
+ 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. 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 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 pointer to single
+ linked list of struct setup_data.
+
+ 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 entry
+ point.
+
+ 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 xloadflags to
+ support booting a 64-bit kernel from 32-bit EFI
+
+ Protocol 2.14
+
+ BURNT BY INCORRECT COMMIT ae7e1238e68f2a472a125673ab506d49158c1889
+ (x86/boot: Add ACPI RSDP address to setup_header) DO NOT USE!!! ASSUME
+ SAME AS 2.13.
+
+ Protocol 2.15
+
+ (Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max.
+
+ Note
+
+ The protocol version number should be changed only if the setup header
+ is changed. There is no need to update the version number if
+ boot_params or kernel_info are changed. Additionally, it is recommended
+ to use xloadflags (in this case the protocol version number should not
+ be updated either) or kernel_info to communicate supported Linux kernel
+ features to the boot loader. Due to very limited space available in the
+ original setup header every update to it should be considered with
+ great care. Starting from the protocol 2.15 the primary way to
+ communicate things to the boot loader is the kernel_info.
+
+1.1. Memory Layout[87]¶
+
+ 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, 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
+ 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 some
+ newer BIOSes have begun to allocate some rather large amounts of
+ memory, called the Extended BIOS Data Area, near the top of low memory.
+ The boot loader should use the "INT 12h" BIOS call to verify how much
+ low memory is available.
+
+ Unfortunately, if INT 12h reports that the amount of memory is too low,
+ there is usually nothing the boot loader can do but to report an error
+ to the user. The boot loader should therefore be designed to take up as
+ little space in low memory as it reasonably can. For 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 mar
+k)
+ X+10000 +------------------------+
+ | Stack/heap | For use by the kernel real-mode co
+de.
+ 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:7C
+00
+ 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.
+
+1.2. The Real-Mode Kernel Header[88]¶
+
+ In the following text, and anywhere in the kernel boot sequence, "a
+ sector" refers to 512 bytes. It is independent of the actual sector
+ size of the underlying medium.
+
+ The first step in loading a Linux kernel should be to load the
+ real-mode code (boot sector and setup code) and then examine the
+ following header at offset 0x01f1. The real-mode code can total up to
+ 32K, although the boot loader may choose to load only the first two
+ sectors (1K) and then examine the bootup sector size.
+
+ The header looks like:
+
+ 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
+
+ 0268/4
+
+ 2.15+
+
+ kernel_info_offset
+
+ Offset of the kernel_info
+
+ 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:
+Image type = zImage
+initrd not supported
+Real-mode kernel must be located at 0x90000.
+
+ Otherwise, the "version" field contains the protocol version, 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.
+
+1.3. Details of Header Fields[89]¶
+
+ 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_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
+
+ 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 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
+ 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.
+
+ Field name:
+
+ type_of_loader
+
+ Type:
+
+ write (obligatory)
+
+ Offset/size:
+
+ 0x210/1
+
+ Protocol:
+
+ 2.00+
+
+ 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.
+
+ For boot loader IDs above T = 0xD, write T = 0xE to this field and
+ write the extended ID minus 0x10 to the ext_loader_type field.
+ Similarly, the ext_loader_ver field can be used to provide more than
+ four bits for the bootloader version.
+
+ For example, for T = 0x15, V = 0x234, write:
+type_of_loader <- 0xE4
+ext_loader_type <- 0x05
+ext_loader_ver <- 0x23
+
+ Assigned boot loader ids (hexadecimal):
+
+ 0
+
+ LILO (0x00 reserved for pre-2.00 bootloader)
+
+ 1
+
+ Loadlin
+
+ 2
+
+ bootsect-loader (0x20, all other values reserved)
+
+ 3
+
+ Syslinux
+
+ 4
+
+ Etherboot/gPXE/iPXE
+
+ 5
+
+ ELILO
+
+ 7
+
+ GRUB
+
+ 8
+
+ U-Boot
+
+ 9
+
+ Xen
+
+ A
+
+ Gujin
+
+ B
+
+ Qemu
+
+ C
+
+ Arcturus Networks uCbootloader
+
+ D
+
+ kexec-tools
+
+ E
+
+ Extended (see ext_loader_type)
+
+ F
+
+ Special (0xFF = undefined)
+
+ 10
+
+ Reserved
+
+ 11
+
+ Minimal Linux Bootloader <[90]http://sebastian-plotz.blogspot.de>
+
+ 12
+
+ OVMF UEFI virtualization stack
+
+ 13
+
+ barebox
+
+ Please contact <[91]hpa@zytor.com> if you need a bootloader ID value
+ assigned.
+
+ Field name:
+
+ loadflags
+
+ Type:
+
+ modify (obligatory)
+
+ Offset/size:
+
+ 0x211/1
+
+ Protocol:
+
+ 2.00+
+
+ This field is a bitmask.
+
+ Bit 0 (read): LOADED_HIGH
+
+ * If 0, the protected-mode code is loaded at 0x10000.
+ * If 1, the protected-mode code is loaded at 0x100000.
+
+ Bit 1 (kernel internal): KASLR_FLAG
+
+ * Used internally by the compressed kernel to communicate KASLR
+ status to kernel proper.
+
+ + If 1, KASLR enabled.
+ + If 0, KASLR disabled.
+
+ Bit 5 (write): QUIET_FLAG
+
+ * If 0, print early messages.
+ * If 1, suppress early messages.
+
+ This requests to the kernel (decompressor and early kernel) to not
+ write early messages that require accessing the display hardware
+ directly.
+
+ Bit 6 (obsolete): KEEP_SEGMENTS
+
+ Protocol: 2.07+
+ * This flag is obsolete.
+
+ Bit 7 (write): CAN_USE_HEAP
+
+ Set this bit to 1 to indicate that the value entered in the
+ heap_end_ptr is valid. If this field is clear, some setup code
+ functionality will be disabled.
+
+ Field name:
+
+ setup_move_size
+
+ Type:
+
+ modify (obligatory)
+
+ Offset/size:
+
+ 0x212/2
+
+ Protocol:
+
+ 2.00-2.01
+
+ When using protocol 2.00 or 2.01, if the real mode kernel is not loaded
+ at 0x90000, it gets moved there later in the loading sequence. Fill in
+ this field if you want additional data (such as the kernel command
+ line) moved in addition to the real-mode kernel itself.
+
+ The unit is bytes starting with the beginning of the boot sector.
+
+ This field is can be ignored when the protocol is 2.02 or higher, or if
+ the real-mode code is loaded at 0x90000.
+
+ Field name:
+
+ code32_start
+
+ Type:
+
+ modify (optional, reloc)
+
+ Offset/size:
+
+ 0x214/4
+
+ Protocol:
+
+ 2.00+
+
+ The address to jump to in protected mode. This defaults to the load
+ address of the kernel, and can be used by the boot loader to determine
+ the proper load address.
+
+ This field can be modified for two purposes:
+
+ 1. as a boot loader hook (see Advanced Boot Loader Hooks below.)
+ 2. if a bootloader which does not install a hook loads a relocatable
+ kernel at a nonstandard address it will have to modify this field
+ to point to the load address.
+
+ Field name:
+
+ ramdisk_image
+
+ Type:
+
+ write (obligatory)
+
+ Offset/size:
+
+ 0x218/4
+
+ Protocol:
+
+ 2.00+
+
+ The 32-bit linear address of the initial ramdisk or ramfs. Leave at
+ zero if there is no initial ramdisk/ramfs.
+
+ Field name:
+
+ ramdisk_size
+
+ Type:
+
+ write (obligatory)
+
+ Offset/size:
+
+ 0x21c/4
+
+ Protocol:
+
+ 2.00+
+
+ Size of the initial ramdisk or ramfs. Leave at zero if there is no
+ initial ramdisk/ramfs.
+
+ Field name:
+
+ bootsect_kludge
+
+ Type:
+
+ kernel internal
+
+ Offset/size:
+
+ 0x220/4
+
+ Protocol:
+
+ 2.00+
+
+ This field is obsolete.
+
+ Field name:
+
+ heap_end_ptr
+
+ Type:
+
+ write (obligatory)
+
+ Offset/size:
+
+ 0x224/2
+
+ Protocol:
+
+ 2.01+
+
+ Set this field to the offset (from the beginning of the real-mode code)
+ of the end of the setup stack/heap, minus 0x0200.
+
+ Field name:
+
+ ext_loader_ver
+
+ Type:
+
+ write (optional)
+
+ Offset/size:
+
+ 0x226/1
+
+ Protocol:
+
+ 2.02+
+
+ This field is used as an extension of the version number in the
+ type_of_loader field. The total version number is considered to be
+ (type_of_loader & 0x0f) + (ext_loader_ver << 4).
+
+ The use of this field is boot loader specific. If not written, it is
+ zero.
+
+ Kernels prior to 2.6.31 did not recognize this field, but it is safe to
+ write for protocol version 2.02 or higher.
+
+ Field name:
+
+ ext_loader_type
+
+ Type:
+
+ write (obligatory if (type_of_loader & 0xf0) == 0xe0)
+
+ Offset/size:
+
+ 0x227/1
+
+ Protocol:
+
+ 2.02+
+
+ This field is used as an extension of the type number in type_of_loader
+ field. If the type in type_of_loader is 0xE, then the actual type is
+ (ext_loader_type + 0x10).
+
+ This field is ignored if the type in type_of_loader is not 0xE.
+
+ Kernels prior to 2.6.31 did not recognize this field, but it is safe to
+ write for protocol version 2.02 or higher.
+
+ Field name:
+
+ cmd_line_ptr
+
+ Type:
+
+ write (obligatory)
+
+ Offset/size:
+
+ 0x228/4
+
+ Protocol:
+
+ 2.02+
+
+ Set this field to the linear address of the kernel command line. The
+ kernel command line can be located anywhere between the end of the
+ setup heap and 0xA0000; it does not have to be located in the same 64K
+ segment as the real-mode code itself.
+
+ Fill in this field even if your boot loader does not support a command
+ line, in which case you can point this to an empty string (or better
+ yet, to the string "auto".) If this field is left at zero, the kernel
+ will assume that your boot loader does not support the 2.02+ protocol.
+
+ Field name:
+
+ initrd_addr_max
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x22c/4
+
+ Protocol:
+
+ 2.03+
+
+ The maximum address that may be occupied by the initial ramdisk/ramfs
+ contents. For boot protocols 2.02 or earlier, this field is not
+ present, and the maximum address is 0x37FFFFFF. (This address is
+ defined as the address of the highest safe byte, so if your ramdisk is
+ exactly 131072 bytes long and this field is 0x37FFFFFF, you can start
+ your ramdisk at 0x37FE0000.)
+
+ Field name:
+
+ kernel_alignment
+
+ Type:
+
+ read/modify (reloc)
+
+ Offset/size:
+
+ 0x230/4
+
+ Protocol:
+
+ 2.05+ (read), 2.10+ (modify)
+
+ Alignment unit required by the kernel (if relocatable_kernel is true.)
+ A relocatable kernel that is loaded at an alignment incompatible with
+ the value in this field will be realigned during kernel initialization.
+
+ Starting with protocol version 2.10, this reflects the kernel alignment
+ preferred for optimal performance; it is possible for the loader to
+ modify this field to permit a lesser alignment. See the min_alignment
+ and pref_address field below.
+
+ Field name:
+
+ relocatable_kernel
+
+ Type:
+
+ read (reloc)
+
+ Offset/size:
+
+ 0x234/1
+
+ Protocol:
+
+ 2.05+
+
+ If this field is nonzero, the protected-mode part of the kernel can be
+ loaded at any address that satisfies the kernel_alignment field. After
+ loading, the boot loader must set the code32_start field to point to
+ the loaded code, or to a boot loader hook.
+
+ Field name:
+
+ min_alignment
+
+ Type:
+
+ read (reloc)
+
+ Offset/size:
+
+ 0x235/1
+
+ Protocol:
+
+ 2.10+
+
+ This field, if nonzero, indicates as a power of two the minimum
+ alignment required, as opposed to preferred, by the kernel to boot. If
+ a boot loader makes use of this field, it should update the
+ kernel_alignment field with the alignment unit desired; typically:
+kernel_alignment = 1 << min_alignment
+
+ There may be a considerable performance cost with an excessively
+ misaligned kernel. Therefore, a loader should typically try each
+ power-of-two alignment from kernel_alignment down to this alignment.
+
+ Field name:
+
+ xloadflags
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x236/2
+
+ Protocol:
+
+ 2.12+
+
+ This field is a bitmask.
+
+ Bit 0 (read): XLF_KERNEL_64
+
+ * If 1, this kernel has the legacy 64-bit entry point at 0x200.
+
+ Bit 1 (read): XLF_CAN_BE_LOADED_ABOVE_4G
+
+ * If 1, kernel/boot_params/cmdline/ramdisk can be above 4G.
+
+ Bit 2 (read): XLF_EFI_HANDOVER_32
+
+ * If 1, the kernel supports the 32-bit EFI handoff entry point given
+ at handover_offset.
+
+ Bit 3 (read): XLF_EFI_HANDOVER_64
+
+ * If 1, the kernel supports the 64-bit EFI handoff entry point given
+ at handover_offset + 0x200.
+
+ Bit 4 (read): XLF_EFI_KEXEC
+
+ * If 1, the kernel supports kexec EFI boot with EFI runtime support.
+
+ Field name:
+
+ cmdline_size
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x238/4
+
+ Protocol:
+
+ 2.06+
+
+ The maximum size of the command line without the terminating zero. This
+ means that the command line can contain at most cmdline_size
+ characters. With protocol version 2.05 and earlier, the maximum size
+ was 255.
+
+ Field name:
+
+ hardware_subarch
+
+ Type:
+
+ write (optional, defaults to x86/PC)
+
+ Offset/size:
+
+ 0x23c/4
+
+ Protocol:
+
+ 2.07+
+
+ In a paravirtualized environment the hardware low level architectural
+ pieces such as interrupt handling, page table handling, and accessing
+ process control registers needs to be done differently.
+
+ This field allows the bootloader to inform the kernel we are in one one
+ of those environments.
+
+ 0x00000000
+
+ The default x86/PC environment
+
+ 0x00000001
+
+ lguest
+
+ 0x00000002
+
+ Xen
+
+ 0x00000003
+
+ Moorestown MID
+
+ 0x00000004
+
+ CE4100 TV Platform
+
+ Field name:
+
+ hardware_subarch_data
+
+ Type:
+
+ write (subarch-dependent)
+
+ Offset/size:
+
+ 0x240/8
+
+ Protocol:
+
+ 2.07+
+
+ A pointer to data that is specific to hardware subarch This field is
+ currently unused for the default x86/PC environment, do not modify.
+
+ Field name:
+
+ payload_offset
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x248/4
+
+ Protocol:
+
+ 2.08+
+
+ If non-zero then this field contains the offset from the beginning of
+ the protected-mode code to the payload.
+
+ The payload may be compressed. The format of both the compressed and
+ uncompressed data should be determined using the standard magic
+ numbers. The currently supported compression formats are gzip (magic
+ numbers 1F 8B or 1F 9E), bzip2 (magic number 42 5A), LZMA (magic number
+ 5D 00), XZ (magic number FD 37), LZ4 (magic number 02 21) and ZSTD
+ (magic number 28 B5). The uncompressed payload is currently always ELF
+ (magic number 7F 45 4C 46).
+
+ Field name:
+
+ payload_length
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x24c/4
+
+ Protocol:
+
+ 2.08+
+
+ The length of the payload.
+
+ Field name:
+
+ setup_data
+
+ Type:
+
+ write (special)
+
+ Offset/size:
+
+ 0x250/8
+
+ Protocol:
+
+ 2.09+
+
+ The 64-bit physical pointer to NULL terminated single linked list of
+ struct setup_data. This is used to define a more extensible boot
+ parameters passing mechanism. The definition of struct setup_data is as
+ follow:
+struct setup_data {
+ u64 next;
+ u32 type;
+ u32 len;
+ u8 data[0];
+};
+
+ Where, the next is a 64-bit physical pointer to the next node of linked
+ list, the next field of the last node is 0; the type is used to
+ identify the contents of data; the len is the length of data field; the
+ data holds the real payload.
+
+ This list may be modified at a number of points during the bootup
+ process. Therefore, when modifying this list one should always make
+ sure to consider the case where the linked list already contains
+ entries.
+
+ The setup_data is a bit awkward to use for extremely large data
+ objects, both because the setup_data header has to be adjacent to the
+ data object and because it has a 32-bit length field. However, it is
+ important that intermediate stages of the boot process have a way to
+ identify which chunks of memory are occupied by kernel data.
+
+ Thus setup_indirect struct and SETUP_INDIRECT type were introduced in
+ protocol 2.15:
+struct setup_indirect {
+ __u32 type;
+ __u32 reserved; /* Reserved, must be set to zero. */
+ __u64 len;
+ __u64 addr;
+};
+
+ The type member is a SETUP_INDIRECT | SETUP_* type. However, it cannot
+ be SETUP_INDIRECT itself since making the setup_indirect a tree
+ structure could require a lot of stack space in something that needs to
+ parse it and stack space can be limited in boot contexts.
+
+ Let's give an example how to point to SETUP_E820_EXT data using
+ setup_indirect. In this case setup_data and setup_indirect will look
+ like this:
+struct setup_data {
+ __u64 next = 0 or <addr_of_next_setup_data_struct>;
+ __u32 type = SETUP_INDIRECT;
+ __u32 len = sizeof(setup_indirect);
+ __u8 data[sizeof(setup_indirect)] = struct setup_indirect {
+ __u32 type = SETUP_INDIRECT | SETUP_E820_EXT;
+ __u32 reserved = 0;
+ __u64 len = <len_of_SETUP_E820_EXT_data>;
+ __u64 addr = <addr_of_SETUP_E820_EXT_data>;
+ }
+}
+
+ Note
+
+ SETUP_INDIRECT | SETUP_NONE objects cannot be properly distinguished
+ from SETUP_INDIRECT itself. So, this kind of objects cannot be provided
+ by the bootloaders.
+
+ Field name:
+
+ pref_address
+
+ Type:
+
+ read (reloc)
+
+ Offset/size:
+
+ 0x258/8
+
+ Protocol:
+
+ 2.10+
+
+ This field, if nonzero, represents a preferred load address for the
+ kernel. A relocating bootloader should attempt to load at this address
+ if possible.
+
+ A non-relocatable kernel will unconditionally move itself and to run at
+ this address.
+
+ Field name:
+
+ init_size
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x260/4
+
+ This field indicates the amount of linear contiguous memory starting at
+ the kernel runtime start address that the kernel needs before it is
+ capable of examining its memory map. This is not the same thing as the
+ total amount of memory the kernel needs to boot, but it can be used by
+ a relocating boot loader to help select a safe load address for the
+ kernel.
+
+ The kernel runtime start address is determined by the following
+ algorithm:
+if (relocatable_kernel)
+runtime_start = align_up(load_address, kernel_alignment)
+else
+runtime_start = pref_address
+
+ Field name:
+
+ handover_offset
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x264/4
+
+ This field is the offset from the beginning of the kernel image to the
+ EFI handover protocol entry point. Boot loaders using the EFI handover
+ protocol to boot the kernel should jump to this offset.
+
+ See EFI HANDOVER PROTOCOL below for more details.
+
+ Field name:
+
+ kernel_info_offset
+
+ Type:
+
+ read
+
+ Offset/size:
+
+ 0x268/4
+
+ Protocol:
+
+ 2.15+
+
+ This field is the offset from the beginning of the kernel image to the
+ kernel_info. The kernel_info structure is embedded in the Linux image
+ in the uncompressed protected mode region.
+
+1.4. The kernel_info[92]¶
+
+ The relationships between the headers are analogous to the various data
+ sections:
+
+ setup_header = .data boot_params/setup_data = .bss
+
+ What is missing from the above list? That's right:
+
+ kernel_info = .rodata
+
+ We have been (ab)using .data for things that could go into .rodata or
+ .bss for a long time, for lack of alternatives and - especially early
+ on - inertia. Also, the BIOS stub is responsible for creating
+ boot_params, so it isn't available to a BIOS-based loader (setup_data
+ is, though).
+
+ setup_header is permanently limited to 144 bytes due to the reach of
+ the 2-byte jump field, which doubles as a length field for the
+ structure, combined with the size of the "hole" in struct boot_params
+ that a protected-mode loader or the BIOS stub has to copy it into. It
+ is currently 119 bytes long, which leaves us with 25 very precious
+ bytes. This isn't something that can be fixed without revising the boot
+ protocol entirely, breaking backwards compatibility.
+
+ boot_params proper is limited to 4096 bytes, but can be arbitrarily
+ extended by adding setup_data entries. It cannot be used to communicate
+ properties of the kernel image, because it is .bss and has no
+ image-provided content.
+
+ kernel_info solves this by providing an extensible place for
+ information about the kernel image. It is readonly, because the kernel
+ cannot rely on a bootloader copying its contents anywhere, but that is
+ OK; if it becomes necessary it can still contain data items that an
+ enabled bootloader would be expected to copy into a setup_data chunk.
+
+ All kernel_info data should be part of this structure. Fixed size data
+ have to be put before kernel_info_var_len_data label. Variable size
+ data have to be put after kernel_info_var_len_data label. Each chunk of
+ variable size data has to be prefixed with header/magic and its size,
+ e.g.:
+kernel_info:
+ .ascii "LToP" /* Header, Linux top (structure). */
+ .long kernel_info_var_len_data - kernel_info
+ .long kernel_info_end - kernel_info
+ .long 0x01234567 /* Some fixed size data for the bootloaders. */
+kernel_info_var_len_data:
+example_struct: /* Some variable size data for the bootloaders.
+*/
+ .ascii "0123" /* Header/Magic. */
+ .long example_struct_end - example_struct
+ .ascii "Struct"
+ .long 0x89012345
+example_struct_end:
+example_strings: /* Some variable size data for the bootloaders.
+*/
+ .ascii "ABCD" /* Header/Magic. */
+ .long example_strings_end - example_strings
+ .asciz "String_0"
+ .asciz "String_1"
+example_strings_end:
+kernel_info_end:
+
+ This way the kernel_info is self-contained blob.
+
+ Note
+
+ Each variable size data header/magic can be any 4-character string,
+ without 0 at the end of the string, which does not collide with
+ existing variable length data headers/magics.
+
+1.5. Details of the kernel_info Fields[93]¶
+
+ Field name:
+
+ header
+
+ Offset/size:
+
+ 0x0000/4
+
+ Contains the magic number "LToP" (0x506f544c).
+
+ Field name:
+
+ size
+
+ Offset/size:
+
+ 0x0004/4
+
+ This field contains the size of the kernel_info including
+ kernel_info.header. It does not count
+ kernel_info.kernel_info_var_len_data size. This field should be used by
+ the bootloaders to detect supported fixed size fields in the
+ kernel_info and beginning of kernel_info.kernel_info_var_len_data.
+
+ Field name:
+
+ size_total
+
+ Offset/size:
+
+ 0x0008/4
+
+ This field contains the size of the kernel_info including
+ kernel_info.header and kernel_info.kernel_info_var_len_data.
+
+ Field name:
+
+ setup_type_max
+
+ Offset/size:
+
+ 0x000c/4
+
+ This field contains maximal allowed type for setup_data and
+ setup_indirect structs.
+
+1.6. The Image Checksum[94]¶
+
+ From boot protocol version 2.08 onwards the CRC-32 is calculated over
+ the entire file using the characteristic polynomial 0x04C11DB7 and an
+ initial remainder of 0xffffffff. The checksum is appended to the file;
+ therefore the CRC of the file up to the limit specified in the syssize
+ field of the header is always 0.
+
+1.7. The Kernel Command Line[95]¶
+
+ The kernel command line has become an important way for the boot loader
+ to communicate with the kernel. Some of its options are also relevant
+ to the boot loader itself, see "special command line options" below.
+
+ The kernel command line is a null-terminated string. The maximum length
+ can be retrieved from the field cmdline_size. Before protocol version
+ 2.06, the maximum was 255 characters. A string that is too long will be
+ automatically truncated by the kernel.
+
+ If the boot protocol version is 2.02 or later, the address of the
+ kernel command line is given by the header field cmd_line_ptr (see
+ above.) This address can be anywhere between the end of the setup heap
+ and 0xA0000.
+
+ If the protocol version is not 2.02 or higher, the kernel command line
+ is entered using the following protocol:
+
+ * At offset 0x0020 (word), "cmd_line_magic", enter the magic number
+ 0xA33F.
+ * At offset 0x0022 (word), "cmd_line_offset", enter the offset of the
+ kernel command line (relative to the start of the real-mode
+ kernel).
+ * The kernel command line must be within the memory region covered by
+ setup_move_size, so you may need to adjust this field.
+
+1.8. Memory Layout of The Real-Mode Code[96]¶
+
+ The real-mode code requires a stack/heap to be set up, as well as
+ memory allocated for the kernel command line. This needs to be done in
+ the real-mode accessible memory in bottom megabyte.
+
+ It should be noted that modern machines often have a sizable Extended
+ BIOS Data Area (EBDA). As a result, it is advisable to use as little of
+ the low megabyte as possible.
+
+ Unfortunately, under the following circumstances the 0x90000 memory
+ segment has to be used:
+
+ * When loading a zImage kernel ((loadflags & 0x01) == 0).
+ * When loading a 2.01 or earlier boot protocol kernel.
+
+ Note
+
+ For the 2.00 and 2.01 boot protocols, the real-mode code can be loaded
+ at another address, but it is internally relocated to 0x90000. For the
+ "old" protocol, the real-mode code must be loaded at 0x90000.
+
+ When loading at 0x90000, avoid using memory above 0x9a000.
+
+ For boot protocol 2.02 or higher, the command line does not have to be
+ located in the same 64K segment as the real-mode setup code; it is thus
+ permitted to give the stack/heap the full 64K segment and locate the
+ command line above it.
+
+ The kernel command line should not be located below the real-mode code,
+ nor should it be located in high memory.
+
+1.9. Sample Boot Configuartion[97]¶
+
+ As a sample configuration, assume the following layout of the real mode
+ segment.
+
+ When loading below 0x90000, use the entire segment:
+
+ 0x0000-0x7fff
+
+ Real mode kernel
+
+ 0x8000-0xdfff
+
+ Stack and heap
+
+ 0xe000-0xffff
+
+ Kernel command line
+
+ When loading at 0x90000 OR the protocol version is 2.01 or earlier:
+
+ 0x0000-0x7fff
+
+ Real mode kernel
+
+ 0x8000-0x97ff
+
+ Stack and heap
+
+ 0x9800-0x9fff
+
+ Kernel command line
+
+ Such a boot loader should enter the following fields in the header:
+unsigned long base_ptr; /* base address for real-mode segment */
+
+if ( setup_sects == 0 ) {
+ setup_sects = 4;
+}
+
+if ( protocol >= 0x0200 ) {
+ type_of_loader = <type code>;
+ if ( loading_initrd ) {
+ ramdisk_image = <initrd_address>;
+ ramdisk_size = <initrd_size>;
+ }
+
+ if ( protocol >= 0x0202 && loadflags & 0x01 )
+ heap_end = 0xe000;
+ else
+ heap_end = 0x9800;
+
+ if ( protocol >= 0x0201 ) {
+ heap_end_ptr = heap_end - 0x200;
+ loadflags |= 0x80; /* CAN_USE_HEAP */
+ }
+
+ if ( protocol >= 0x0202 ) {
+ cmd_line_ptr = base_ptr + heap_end;
+ strcpy(cmd_line_ptr, cmdline);
+ } else {
+ cmd_line_magic = 0xA33F;
+ cmd_line_offset = heap_end;
+ setup_move_size = heap_end + strlen(cmdline)+1;
+ strcpy(base_ptr+cmd_line_offset, cmdline);
+ }
+} else {
+ /* Very old kernel */
+
+ heap_end = 0x9800;
+
+ cmd_line_magic = 0xA33F;
+ cmd_line_offset = heap_end;
+
+ /* A very old kernel MUST have its real-mode code
+ loaded at 0x90000 */
+
+ if ( base_ptr != 0x90000 ) {
+ /* Copy the real-mode kernel */
+ memcpy(0x90000, base_ptr, (setup_sects+1)*512);
+ base_ptr = 0x90000; /* Relocated */
+ }
+
+ strcpy(0x90000+cmd_line_offset, cmdline);
+
+ /* It is recommended to clear memory up to the 32K mark */
+ memset(0x90000 + (setup_sects+1)*512, 0,
+ (64-(setup_sects+1))*512);
+}
+
+1.10. Loading The Rest of The Kernel[98]¶
+
+ The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512
+ in the kernel file (again, if setup_sects == 0 the real value is 4.) It
+ should be loaded at address 0x10000 for Image/zImage kernels and
+ 0x100000 for bzImage kernels.
+
+ The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 bit
+ (LOAD_HIGH) in the loadflags field is set:
+is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01);
+load_address = is_bzImage ? 0x100000 : 0x10000;
+
+ Note that Image/zImage kernels can be up to 512K in size, and thus use
+ the entire 0x10000-0x90000 range of memory. This means it is pretty
+ much a requirement for these kernels to load the real-mode part at
+ 0x90000. bzImage kernels allow much more flexibility.
+
+1.11. Special Command Line Options[99]¶
+
+ If the command line provided by the boot loader is entered by the user,
+ the user may expect the following command line options to work. They
+ should normally not be deleted from the kernel command line even though
+ not all of them are actually meaningful to the kernel. Boot loader
+ authors who need additional command line options for the boot loader
+ itself should get them registered in [100]The kernel's command-line
+ parameters to make sure they will not conflict with actual kernel
+ options now or in the future.
+
+ vga=<mode>
+ <mode> here is either an integer (in C notation, either decimal,
+ octal, or hexadecimal) or one of the strings "normal" (meaning
+ 0xFFFF), "ext" (meaning 0xFFFE) or "ask" (meaning 0xFFFD). This
+ value should be entered into the vid_mode field, as it is used
+ by the kernel before the command line is parsed.
+
+ mem=<size>
+ <size> is an integer in C notation optionally followed by (case
+ insensitive) K, M, G, T, P or E (meaning << 10, << 20, << 30, <<
+ 40, << 50 or << 60). This specifies the end of memory to the
+ kernel. This affects the possible placement of an initrd, since
+ an initrd should be placed near end of memory. Note that this is
+ an option to both the kernel and the bootloader!
+
+ initrd=<file>
+ An initrd should be loaded. The meaning of <file> is obviously
+ bootloader-dependent, and some boot loaders (e.g. LILO) do not
+ have such a command.
+
+ In addition, some boot loaders add the following options to the
+ user-specified command line:
+
+ BOOT_IMAGE=<file>
+ The boot image which was loaded. Again, the meaning of <file> is
+ obviously bootloader-dependent.
+
+ auto
+ The kernel was booted without explicit user intervention.
+
+ If these options are added by the boot loader, it is highly recommended
+ that they are located first, before the user-specified or
+ configuration-specified command line. Otherwise, "init=/bin/sh" gets
+ confused by the "auto" option.
+
+1.12. Running the Kernel[101]¶
+
+ The kernel is started by jumping to the kernel entry point, which is
+ located at segment offset 0x20 from the start of the real mode kernel.
+ This means that if you loaded your real-mode kernel code at 0x90000,
+ the kernel entry point is 9020:0000.
+
+ At entry, ds = es = ss should point to the start of the real-mode
+ kernel code (0x9000 if the code is loaded at 0x90000), sp should be set
+ up properly, normally pointing to the top of the heap, and interrupts
+ should be disabled. Furthermore, to guard against bugs in the kernel,
+ it is recommended that the boot loader sets fs = gs = ds = es = ss.
+
+ In our example from above, we would do:
+/* Note: in the case of the "old" kernel protocol, base_ptr must
+ be == 0x90000 at this point; see the previous sample code */
+
+seg = base_ptr >> 4;
+
+cli(); /* Enter with interrupts disabled! */
+
+/* Set up the real-mode kernel stack */
+_SS = seg;
+_SP = heap_end;
+
+_DS = _ES = _FS = _GS = seg;
+jmp_far(seg+0x20, 0); /* Run the kernel */
+
+ If your boot sector accesses a floppy drive, it is recommended to
+ switch off the floppy motor before running the kernel, since the kernel
+ boot leaves interrupts off and thus the motor will not be switched off,
+ especially if the loaded kernel has the floppy driver as a
+ demand-loaded module!
+
+1.13. Advanced Boot Loader Hooks[102]¶
+
+ If the boot loader runs in a particularly hostile environment (such as
+ LOADLIN, which runs under DOS) it may be impossible to follow the
+ standard memory location requirements. Such a boot loader may use the
+ following hooks that, if set, are invoked by the kernel at the
+ appropriate time. The use of these hooks should probably be considered
+ an absolutely last resort!
+
+ IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and
+ %edi across invocation.
+
+ realmode_swtch:
+ A 16-bit real mode far subroutine invoked immediately before
+ entering protected mode. The default routine disables NMI, so
+ your routine should probably do so, too.
+
+ code32_start:
+ A 32-bit flat-mode routine jumped to immediately after the
+ transition to protected mode, but before the kernel is
+ uncompressed. No segments, except CS, are guaranteed to be set
+ up (current kernels do, but older ones do not); you should set
+ them up to BOOT_DS (0x18) yourself.
+
+ After completing your hook, you should jump to the address that
+ was in this field before your boot loader overwrote it
+ (relocated, if appropriate.)
+
+1.14. 32-bit Boot Protocol[103]¶
+
+ For machine with some new BIOS other than legacy BIOS, such as EFI,
+ LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
+ based on legacy BIOS can not be used, so a 32-bit boot protocol needs
+ to be defined.
+
+ In 32-bit boot protocol, the first step in loading a Linux kernel
+ should be to setup the boot parameters (struct boot_params,
+ traditionally known as "zero page"). The memory for struct boot_params
+ should be allocated and initialized to all zero. Then the setup header
+ from offset 0x01f1 of kernel image on should be loaded into struct
+ boot_params and examined. The end of setup header can be calculated as
+ follow:
+0x0202 + byte value at offset 0x0201
+
+ In addition to read/modify/write the setup header of the struct
+ boot_params as that of 16-bit boot protocol, the boot loader should
+ also fill the additional fields of the struct boot_params as described
+ in chapter [104]Zero Page.
+
+ After setting up the struct boot_params, the boot loader can load the
+ 32/64-bit kernel in the same way as that of 16-bit boot protocol.
+
+ In 32-bit boot protocol, the kernel is started by jumping to the 32-bit
+ kernel entry point, which is the start address of loaded 32/64-bit
+ kernel.
+
+ At entry, the CPU must be in 32-bit protected mode with paging
+ disabled; a GDT must be loaded with the descriptors for selectors
+ __BOOT_CS(0x10) and __BOOT_DS(0x18); both descriptors must be 4G flat
+ segment; __BOOT_CS must have execute/read permission, and __BOOT_DS
+ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS
+ must be __BOOT_DS; interrupt must be disabled; %esi must hold the base
+ address of the struct boot_params; %ebp, %edi and %ebx must be zero.
+
+1.15. 64-bit Boot Protocol[105]¶
+
+ For machine with 64bit cpus and 64bit kernel, we could use 64bit
+ bootloader and we need a 64-bit boot protocol.
+
+ In 64-bit boot protocol, the first step in loading a Linux kernel
+ should be to setup the boot parameters (struct boot_params,
+ traditionally known as "zero page"). The memory for struct boot_params
+ could be allocated anywhere (even above 4G) and initialized to all
+ zero. Then, the setup header at offset 0x01f1 of kernel image on should
+ be loaded into struct boot_params and examined. The end of setup header
+ can be calculated as follows:
+0x0202 + byte value at offset 0x0201
+
+ In addition to read/modify/write the setup header of the struct
+ boot_params as that of 16-bit boot protocol, the boot loader should
+ also fill the additional fields of the struct boot_params as described
+ in chapter [106]Zero Page.
+
+ After setting up the struct boot_params, the boot loader can load
+ 64-bit kernel in the same way as that of 16-bit boot protocol, but
+ kernel could be loaded above 4G.
+
+ In 64-bit boot protocol, the kernel is started by jumping to the 64-bit
+ kernel entry point, which is the start address of loaded 64-bit kernel
+ plus 0x200.
+
+ At entry, the CPU must be in 64-bit mode with paging enabled. The range
+ with setup_header.init_size from start address of loaded kernel and
+ zero page and command line buffer get ident mapping; a GDT must be
+ loaded with the descriptors for selectors __BOOT_CS(0x10) and
+ __BOOT_DS(0x18); both descriptors must be 4G flat segment; __BOOT_CS
+ must have execute/read permission, and __BOOT_DS must have read/write
+ permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS;
+ interrupt must be disabled; %rsi must hold the base address of the
+ struct boot_params.
+
+1.16. EFI Handover Protocol (deprecated)[107]¶
+
+ This protocol allows boot loaders to defer initialisation to the EFI
+ boot stub. The boot loader is required to load the kernel/initrd(s)
+ from the boot media and jump to the EFI handover protocol entry point
+ which is hdr->handover_offset bytes from the beginning of
+ startup_{32,64}.
+
+ The boot loader MUST respect the kernel's PE/COFF metadata when it
+ comes to section alignment, the memory footprint of the executable
+ image beyond the size of the file itself, and any other aspect of the
+ PE/COFF header that may affect correct operation of the image as a
+ PE/COFF binary in the execution context provided by the EFI firmware.
+
+ The function prototype for the handover entry point looks like this:
+efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp)
+
+ `handle' is the EFI image handle passed to the boot loader by the EFI
+ firmware, `table' is the EFI system table - these are the first two
+ arguments of the "handoff state" as described in section 2.3 of the
+ UEFI specification. `bp' is the boot loader-allocated boot params.
+
+ The boot loader must fill out the following fields in bp:
+- hdr.cmd_line_ptr
+- hdr.ramdisk_image (if applicable)
+- hdr.ramdisk_size (if applicable)
+
+ All other fields should be zero.
+
+ NOTE: The EFI Handover Protocol is deprecated in favour of the ordinary
+ PE/COFF
+ entry point, combined with the LINUX_EFI_INITRD_MEDIA_GUID based
+ initrd loading protocol (refer to [0] for an example of the
+ bootloader side of this), which removes the need for any
+ knowledge on the part of the EFI bootloader regarding the
+ internal representation of boot_params or any
+ requirements/limitations regarding the placement of the command
+ line and ramdisk in memory, or the placement of the kernel image
+ itself.
+
+ [0]
+ [108]https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5
+ d717d4739b0fd0
+
+ ©The kernel development community. | Powered by [109]Sphinx 5.0.1 &
+ [110]Alabaster 0.7.12 | [111]Page source
+
+References
+
+ 1. https://www.kernel.org/doc/html/latest/genindex.html
+ 2. https://www.kernel.org/doc/html/latest/search.html
+ 3. https://www.kernel.org/doc/html/latest/x86/booting-dt.html
+ 4. https://www.kernel.org/doc/html/latest/x86/index.html
+ 5. https://www.kernel.org/doc/html/latest/index.html
+ 6. https://www.kernel.org/doc/html/latest/process/development-process.html
+ 7. https://www.kernel.org/doc/html/latest/process/submitting-patches.html
+ 8. https://www.kernel.org/doc/html/latest/process/code-of-conduct.html
+ 9. https://www.kernel.org/doc/html/latest/maintainer/index.html
+ 10. https://www.kernel.org/doc/html/latest/process/index.html
+ 11. https://www.kernel.org/doc/html/latest/core-api/index.html
+ 12. https://www.kernel.org/doc/html/latest/driver-api/index.html
+ 13. https://www.kernel.org/doc/html/latest/subsystem-apis.html
+ 14. https://www.kernel.org/doc/html/latest/locking/index.html
+ 15. https://www.kernel.org/doc/html/latest/process/license-rules.html
+ 16. https://www.kernel.org/doc/html/latest/doc-guide/index.html
+ 17. https://www.kernel.org/doc/html/latest/dev-tools/index.html
+ 18. https://www.kernel.org/doc/html/latest/dev-tools/testing-overview.html
+ 19. https://www.kernel.org/doc/html/latest/kernel-hacking/index.html
+ 20. https://www.kernel.org/doc/html/latest/trace/index.html
+ 21. https://www.kernel.org/doc/html/latest/fault-injection/index.html
+ 22. https://www.kernel.org/doc/html/latest/livepatch/index.html
+ 23. https://www.kernel.org/doc/html/latest/rust/index.html
+ 24. https://www.kernel.org/doc/html/latest/admin-guide/index.html
+ 25. https://www.kernel.org/doc/html/latest/kbuild/index.html
+ 26. https://www.kernel.org/doc/html/latest/admin-guide/reporting-issues.html
+ 27. https://www.kernel.org/doc/html/latest/tools/index.html
+ 28. https://www.kernel.org/doc/html/latest/userspace-api/index.html
+ 29. https://www.kernel.org/doc/html/latest/firmware-guide/index.html
+ 30. https://www.kernel.org/doc/html/latest/devicetree/index.html
+ 31. https://www.kernel.org/doc/html/latest/arch.html
+ 32. https://www.kernel.org/doc/html/latest/arc/index.html
+ 33. https://www.kernel.org/doc/html/latest/arm/index.html
+ 34. https://www.kernel.org/doc/html/latest/arm64/index.html
+ 35. https://www.kernel.org/doc/html/latest/ia64/index.html
+ 36. https://www.kernel.org/doc/html/latest/loongarch/index.html
+ 37. https://www.kernel.org/doc/html/latest/m68k/index.html
+ 38. https://www.kernel.org/doc/html/latest/mips/index.html
+ 39. https://www.kernel.org/doc/html/latest/nios2/index.html
+ 40. https://www.kernel.org/doc/html/latest/openrisc/index.html
+ 41. https://www.kernel.org/doc/html/latest/parisc/index.html
+ 42. https://www.kernel.org/doc/html/latest/powerpc/index.html
+ 43. https://www.kernel.org/doc/html/latest/riscv/index.html
+ 44. https://www.kernel.org/doc/html/latest/s390/index.html
+ 45. https://www.kernel.org/doc/html/latest/sh/index.html
+ 46. https://www.kernel.org/doc/html/latest/sparc/index.html
+ 47. https://www.kernel.org/doc/html/latest/x86/index.html
+ 48. https://www.kernel.org/doc/html/latest/x86/boot.html
+ 49. https://www.kernel.org/doc/html/latest/x86/booting-dt.html
+ 50. https://www.kernel.org/doc/html/latest/x86/cpuinfo.html
+ 51. https://www.kernel.org/doc/html/latest/x86/topology.html
+ 52. https://www.kernel.org/doc/html/latest/x86/exception-tables.html
+ 53. https://www.kernel.org/doc/html/latest/x86/kernel-stacks.html
+ 54. https://www.kernel.org/doc/html/latest/x86/entry_64.html
+ 55. https://www.kernel.org/doc/html/latest/x86/earlyprintk.html
+ 56. https://www.kernel.org/doc/html/latest/x86/orc-unwinder.html
+ 57. https://www.kernel.org/doc/html/latest/x86/zero-page.html
+ 58. https://www.kernel.org/doc/html/latest/x86/tlb.html
+ 59. https://www.kernel.org/doc/html/latest/x86/mtrr.html
+ 60. https://www.kernel.org/doc/html/latest/x86/pat.html
+ 61. https://www.kernel.org/doc/html/latest/x86/intel-hfi.html
+ 62. https://www.kernel.org/doc/html/latest/x86/iommu.html
+ 63. https://www.kernel.org/doc/html/latest/x86/intel_txt.html
+ 64. https://www.kernel.org/doc/html/latest/x86/amd-memory-encryption.html
+ 65. https://www.kernel.org/doc/html/latest/x86/amd_hsmp.html
+ 66. https://www.kernel.org/doc/html/latest/x86/tdx.html
+ 67. https://www.kernel.org/doc/html/latest/x86/pti.html
+ 68. https://www.kernel.org/doc/html/latest/x86/mds.html
+ 69. https://www.kernel.org/doc/html/latest/x86/microcode.html
+ 70. https://www.kernel.org/doc/html/latest/x86/resctrl.html
+ 71. https://www.kernel.org/doc/html/latest/x86/tsx_async_abort.html
+ 72. https://www.kernel.org/doc/html/latest/x86/buslock.html
+ 73. https://www.kernel.org/doc/html/latest/x86/usb-legacy-support.html
+ 74. https://www.kernel.org/doc/html/latest/x86/i386/index.html
+ 75. https://www.kernel.org/doc/html/latest/x86/x86_64/index.html
+ 76. https://www.kernel.org/doc/html/latest/x86/ifs.html
+ 77. https://www.kernel.org/doc/html/latest/x86/sva.html
+ 78. https://www.kernel.org/doc/html/latest/x86/sgx.html
+ 79. https://www.kernel.org/doc/html/latest/x86/features.html
+ 80. https://www.kernel.org/doc/html/latest/x86/elf_auxvec.html
+ 81. https://www.kernel.org/doc/html/latest/x86/xstate.html
+ 82. https://www.kernel.org/doc/html/latest/xtensa/index.html
+ 83. https://www.kernel.org/doc/html/latest/staging/index.html
+ 84. https://www.kernel.org/doc/html/latest/translations/index.html
+ 85. https://www.kernel.org/doc/html/latest/_sources/x86/boot.rst.txt
+ 86. https://www.kernel.org/doc/html/latest/x86/boot.html#the-linux-x86-boot-protocol
+ 87. https://www.kernel.org/doc/html/latest/x86/boot.html#memory-layout
+ 88. https://www.kernel.org/doc/html/latest/x86/boot.html#the-real-mode-kernel-header
+ 89. https://www.kernel.org/doc/html/latest/x86/boot.html#details-of-header-fields
+ 90. http://sebastian-plotz.blogspot.de/
+ 91. mailto:hpa%40zytor.com
+ 92. https://www.kernel.org/doc/html/latest/x86/boot.html#the-kernel-info
+ 93. https://www.kernel.org/doc/html/latest/x86/boot.html#details-of-the-kernel-info-fields
+ 94. https://www.kernel.org/doc/html/latest/x86/boot.html#the-image-checksum
+ 95. https://www.kernel.org/doc/html/latest/x86/boot.html#the-kernel-command-line
+ 96. https://www.kernel.org/doc/html/latest/x86/boot.html#memory-layout-of-the-real-mode-code
+ 97. https://www.kernel.org/doc/html/latest/x86/boot.html#sample-boot-configuartion
+ 98. https://www.kernel.org/doc/html/latest/x86/boot.html#loading-the-rest-of-the-kernel
+ 99. https://www.kernel.org/doc/html/latest/x86/boot.html#special-command-line-options
+ 100. https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
+ 101. https://www.kernel.org/doc/html/latest/x86/boot.html#running-the-kernel
+ 102. https://www.kernel.org/doc/html/latest/x86/boot.html#advanced-boot-loader-hooks
+ 103. https://www.kernel.org/doc/html/latest/x86/boot.html#bit-boot-protocol
+ 104. https://www.kernel.org/doc/html/latest/x86/zero-page.html
+ 105. https://www.kernel.org/doc/html/latest/x86/boot.html#id1
+ 106. https://www.kernel.org/doc/html/latest/x86/zero-page.html
+ 107. https://www.kernel.org/doc/html/latest/x86/boot.html#efi-handover-protocol-deprecated
+ 108. https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0
+ 109. http://sphinx-doc.org/
+ 110. https://github.com/bitprophet/alabaster
+ 111. https://www.kernel.org/doc/html/latest/_sources/x86/boot.rst.txt
generated by cgit v1.2.3-54-g00ecf (git 2.44.0) at 2024-05-10 14:50:19 +0000