[PATCH v2 1/1] x86/Documentation: Update algo in init_size description of boot protocol

[PATCH v2 1/1] x86/Documentation: Update algo in init_size description of boot protocol

[Andy Shevchenko]

The init_size description of boot protocol has an example of the runtime
start address for the compressed bzImage. For non-relocatable kernel
it relies on the pref_address value (if not 0), but for relocatable case
only pays respect to the load_addres and kernel_alignment, and it is
inaccurate for the latter. Boot loader must consider the pref_address
as the Linux kernel relocates to it before being decompressed as nicely
described in the commit 43b1d3e68ee7 message.

Due to this inaccuracy some of the bootloaders (*) made a mistake in
the calculations and if kernel image is big enough, this may lead to
unbootable configurations.

*)
  In particular, kexec-tools missed that and resently got a couple of
  changes which will be part of v2.0.30 release. For the record,
  the 43b1d3e68ee7 fixed only kernel kexec implementation and also missed
  to update the init_size description.

While at it, make an example C-like looking as it's done elsewhere in
the document and fix indentation as presribed by the reStructuredText
specifications, so the syntax highliting will work properly.

Fixes: 43b1d3e68ee7 ("kexec: Allocate kernel above bzImage's pref_address")
Fixes: d297366ba692 ("x86: document new bzImage fields")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---

v2: fixed the style to follow both rST and kernel conventions (Ingo, Randy)

 Documentation/arch/x86/boot.rst | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst
index 4fd492cb4970..ad2d8ddad27f 100644
--- a/Documentation/arch/x86/boot.rst
+++ b/Documentation/arch/x86/boot.rst
@@ -896,10 +896,19 @@ Offset/size:	0x260/4
 
   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
+   	if (relocatable_kernel) {
+   		if (load_address < pref_address)
+   			load_address = pref_address;
+   		runtime_start = align_up(load_address, kernel_alignment);
+   	} else {
+   		runtime_start = pref_address;
+   	}
+
+Hence the necessary memory window location and size can be estimated by
+a boot loader as::
+
+   	memory_window_start = runtime_start;
+   	memory_window_size = init_size;
 
 ============	===============
 Field name:	handover_offset
-- 
2.43.0.rc1.1336.g36b5255a03ac

Re: [PATCH v2 1/1] x86/Documentation: Update algo in init_size description of boot protocol

[Randy Dunlap]

On 11/25/24 2:49 AM, Andy Shevchenko wrote:
> The init_size description of boot protocol has an example of the runtime
> start address for the compressed bzImage. For non-relocatable kernel
> it relies on the pref_address value (if not 0), but for relocatable case
> only pays respect to the load_addres and kernel_alignment, and it is
> inaccurate for the latter. Boot loader must consider the pref_address
> as the Linux kernel relocates to it before being decompressed as nicely
> described in the commit 43b1d3e68ee7 message.
> 
> Due to this inaccuracy some of the bootloaders (*) made a mistake in
> the calculations and if kernel image is big enough, this may lead to
> unbootable configurations.
> 
> *)
>   In particular, kexec-tools missed that and resently got a couple of
>   changes which will be part of v2.0.30 release. For the record,
>   the 43b1d3e68ee7 fixed only kernel kexec implementation and also missed
>   to update the init_size description.
> 
> While at it, make an example C-like looking as it's done elsewhere in
> the document and fix indentation as presribed by the reStructuredText
> specifications, so the syntax highliting will work properly.
> 
> Fixes: 43b1d3e68ee7 ("kexec: Allocate kernel above bzImage's pref_address")
> Fixes: d297366ba692 ("x86: document new bzImage fields")
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> ---
> 
> v2: fixed the style to follow both rST and kernel conventions (Ingo, Randy)
> 
>  Documentation/arch/x86/boot.rst | 17 +++++++++++++----
>  1 file changed, 13 insertions(+), 4 deletions(-)


Acked-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

-- 
~Randy

[tip: x86/urgent] x86/Documentation: Update algo in init_size description of boot protocol

[tip-bot2 for Andy Shevchenko]

The following commit has been merged into the x86/urgent branch of tip:

Commit-ID:     be4ca6c53e66cb275cf0d71f32dac0c4606b9dc0
Gitweb:        https://git.kernel.org/tip/be4ca6c53e66cb275cf0d71f32dac0c4606b9dc0
Author:        Andy Shevchenko <andriy.shevchenko@linux.intel.com>
AuthorDate:    Mon, 25 Nov 2024 12:49:14 +02:00
Committer:     Ingo Molnar <mingo@kernel.org>
CommitterDate: Mon, 25 Nov 2024 21:40:56 +01:00

x86/Documentation: Update algo in init_size description of boot protocol

The init_size description of boot protocol has an example of the runtime
start address for the compressed bzImage. For non-relocatable kernel
it relies on the pref_address value (if not 0), but for relocatable case
only pays respect to the load_addres and kernel_alignment, and it is
inaccurate for the latter. Boot loader must consider the pref_address
as the Linux kernel relocates to it before being decompressed as nicely
described in this commit message a year ago:

  43b1d3e68ee7 ("kexec: Allocate kernel above bzImage's pref_address")

Due to this documentation inaccuracy some of the bootloaders (*) made a
mistake in the calculations and if kernel image is big enough, this may
lead to unbootable configurations.

*)
  In particular, kexec-tools missed that and resently got a couple of
  changes which will be part of v2.0.30 release. For the record,
  commit 43b1d3e68ee7 only fixed the kernel kexec implementation and
  also missed to update the init_size description.

While at it, make an example C-like looking as it's done elsewhere in
the document and fix indentation as presribed by the reStructuredText
specifications, so the syntax highliting will work properly.

Fixes: 43b1d3e68ee7 ("kexec: Allocate kernel above bzImage's pref_address")
Fixes: d297366ba692 ("x86: document new bzImage fields")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Link: https://lore.kernel.org/r/20241125105005.1616154-1-andriy.shevchenko@linux.intel.com
---
 Documentation/arch/x86/boot.rst | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst
index 4fd492c..ad2d8dd 100644
--- a/Documentation/arch/x86/boot.rst
+++ b/Documentation/arch/x86/boot.rst
@@ -896,10 +896,19 @@ Offset/size:	0x260/4
 
   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
+   	if (relocatable_kernel) {
+   		if (load_address < pref_address)
+   			load_address = pref_address;
+   		runtime_start = align_up(load_address, kernel_alignment);
+   	} else {
+   		runtime_start = pref_address;
+   	}
+
+Hence the necessary memory window location and size can be estimated by
+a boot loader as::
+
+   	memory_window_start = runtime_start;
+   	memory_window_size = init_size;
 
 ============	===============
 Field name:	handover_offset