Commit d297366b authored by H. Peter Anvin's avatar H. Peter Anvin
Browse files

x86: document new bzImage fields 



Document the new bzImage fields for kernel memory placement.

[ Impact: adds documentation ]

Signed-off-by: default avatarH. Peter Anvin <hpa@zytor.com>
parent 37ba7ab5

Documentation/x86/boot.txt

+65 −4
Original line number Diff line number Diff line
@@ -50,6 +50,11 @@ Protocol 2.08: (Kernel 2.6.26) Added crc32 checksum and ELF format 
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) A protocol for relaxed alignment

		beyond the kernel_alignment added, new init_size and

		pref_address fields.





**** MEMORY LAYOUT



The traditional memory map for the kernel loader, used for Image or
@@ -173,7 +178,7 @@ Offset Proto Name Meaning 
022C/4	2.03+	ramdisk_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	N/A	pad2		Unused

0235/1	2.10+	min_alignment	Minimum alignment, as a power of two

0236/2	N/A	pad3		Unused

0238/4	2.06+	cmdline_size	Maximum size of the kernel command line

023C/4	2.07+	hardware_subarch Hardware subarchitecture
@@ -182,6 +187,8 @@ Offset Proto Name Meaning 
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



(1) For backwards compatibility, if the setup_sects field contains 0, the

    real value is 4.
@@ -482,11 +489,19 @@ Protocol: 2.03+ 
  0x37FFFFFF, you can start your ramdisk at 0x37FE0000.)



Field name:	kernel_alignment

Type:		read (reloc)

Type:		read/modify (reloc)

Offset/size:	0x230/4

Protocol:	2.05+

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.



  Alignment unit required by the kernel (if relocatable_kernel is true.)

  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)
@@ -498,6 +513,22 @@ Protocol: 2.05+ 
  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:	cmdline_size

Type:		read

Offset/size:	0x238/4
@@ -582,6 +613,36 @@ Protocol: 2.09+ 
  sure to consider the case where the linked list already contains

  entries.



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:	0x25c/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





**** THE IMAGE CHECKSUM