x86: document new bzImage fields

Document the new bzImage fields for kernel memory placement. [ Impact: adds documentation ] Signed-off-by: H. Peter Anvin <hpa@zytor.com>

x86: document new bzImage fields
Document the new bzImage fields for kernel memory placement. [ Impact: adds documentation ] Signed-off-by: H. Peter Anvin <hpa@zytor.com>
H. Peter Anvin
1 parent 37ba7ab5e3
Showing 1 changed file with 65 additions and 4 deletions Side-by-side Diff
Documentation/x86/boot.txt
@@ -50,6 +50,11 @@
 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 @@
 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 @@
 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,12 +489,20 @@
   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.)
+  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
@@ -498,6 +513,22 @@
   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
@@ -581,6 +612,36 @@
   process.  Therefore, when modifying this list one should always make
   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
...	...	@@ -50,6 +50,11 @@
50	50	Protocol 2.09: (Kernel 2.6.26) Added a field of 64-bit physical
51	51	pointer to single linked list of struct setup_data.
52	52
	53	+Protocol 2.10: (Kernel 2.6.31) A protocol for relaxed alignment
	54	+ beyond the kernel_alignment added, new init_size and
	55	+ pref_address fields.
	56	+
	57	+
53	58	**** MEMORY LAYOUT
54	59
55	60	The traditional memory map for the kernel loader, used for Image or
...	...	@@ -173,7 +178,7 @@
173	178	022C/4 2.03+ ramdisk_max Highest legal initrd address
174	179	0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel
175	180	0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not
176		-0235/1 N/A pad2 Unused
	181	+0235/1 2.10+ min_alignment Minimum alignment, as a power of two
177	182	0236/2 N/A pad3 Unused
178	183	0238/4 2.06+ cmdline_size Maximum size of the kernel command line
179	184	023C/4 2.07+ hardware_subarch Hardware subarchitecture
...	...	@@ -182,6 +187,8 @@
182	187	024C/4 2.08+ payload_length Length of kernel payload
183	188	0250/8 2.09+ setup_data 64-bit physical pointer to linked list
184	189	of struct setup_data
	190	+0258/8 2.10+ pref_address Preferred loading address
	191	+0260/4 2.10+ init_size Linear memory required during initialization
185	192
186	193	(1) For backwards compatibility, if the setup_sects field contains 0, the
187	194	real value is 4.
188	195
189	196
190	197
...	...	@@ -482,12 +489,20 @@
482	489	0x37FFFFFF, you can start your ramdisk at 0x37FE0000.)
483	490
484	491	Field name: kernel_alignment
485		-Type: read (reloc)
	492	+Type: read/modify (reloc)
486	493	Offset/size: 0x230/4
487		-Protocol: 2.05+
	494	+Protocol: 2.05+ (read), 2.10+ (modify)
488	495
489		- Alignment unit required by the kernel (if relocatable_kernel is true.)
	496	+ Alignment unit required by the kernel (if relocatable_kernel is
	497	+ true.) A relocatable kernel that is loaded at an alignment
	498	+ incompatible with the value in this field will be realigned during
	499	+ kernel initialization.
490	500
	501	+ Starting with protocol version 2.10, this reflects the kernel
	502	+ alignment preferred for optimal performance; it is possible for the
	503	+ loader to modify this field to permit a lesser alignment. See the
	504	+ min_alignment and pref_address field below.
	505	+
491	506	Field name: relocatable_kernel
492	507	Type: read (reloc)
493	508	Offset/size: 0x234/1
...	...	@@ -498,6 +513,22 @@
498	513	After loading, the boot loader must set the code32_start field to
499	514	point to the loaded code, or to a boot loader hook.
500	515
	516	+Field name: min_alignment
	517	+Type: read (reloc)
	518	+Offset/size: 0x235/1
	519	+Protocol: 2.10+
	520	+
	521	+ This field, if nonzero, indicates as a power of two the minimum
	522	+ alignment required, as opposed to preferred, by the kernel to boot.
	523	+ If a boot loader makes use of this field, it should update the
	524	+ kernel_alignment field with the alignment unit desired; typically:
	525	+
	526	+ kernel_alignment = 1 << min_alignment
	527	+
	528	+ There may be a considerable performance cost with an excessively
	529	+ misaligned kernel. Therefore, a loader should typically try each
	530	+ power-of-two alignment from kernel_alignment down to this alignment.
	531	+
501	532	Field name: cmdline_size
502	533	Type: read
503	534	Offset/size: 0x238/4
...	...	@@ -581,6 +612,36 @@
581	612	process. Therefore, when modifying this list one should always make
582	613	sure to consider the case where the linked list already contains
583	614	entries.
	615	+
	616	+Field name: pref_address
	617	+Type: read (reloc)
	618	+Offset/size: 0x258/8
	619	+Protocol: 2.10+
	620	+
	621	+ This field, if nonzero, represents a preferred load address for the
	622	+ kernel. A relocating bootloader should attempt to load at this
	623	+ address if possible.
	624	+
	625	+ A non-relocatable kernel will unconditionally move itself and to run
	626	+ at this address.
	627	+
	628	+Field name: init_size
	629	+Type: read
	630	+Offset/size: 0x25c/4
	631	+
	632	+ This field indicates the amount of linear contiguous memory starting
	633	+ at the kernel runtime start address that the kernel needs before it
	634	+ is capable of examining its memory map. This is not the same thing
	635	+ as the total amount of memory the kernel needs to boot, but it can
	636	+ be used by a relocating boot loader to help select a safe load
	637	+ address for the kernel.
	638	+
	639	+ The kernel runtime start address is determined by the following algorithm:
	640	+
	641	+ if (relocatable_kernel)
	642	+ runtime_start = align_up(load_address, kernel_alignment)
	643	+ else
	644	+ runtime_start = pref_address
584	645
585	646
586	647	**** THE IMAGE CHECKSUM