[PATCH] docs: arm64: Document that text_offset is always 0

[PATCH] docs: arm64: Document that text_offset is always 0

[Rasmus Villemoes]

When trying to figure out where to place and call an arm64 Image in
memory, reading booting.rst should provide the answer. However, it
requires quite some digging to figure out that text_offset is set via
".quad 0" in head.S and is thus actually always 0 since v5.10.

Update the documentation and make that explicit. Reword the 2MB
requirement accordingly, and remove the paragraphs that only apply to
the ancient versions where text_offset could be non-zero, as they only
confuse a current reader.

Fixes: 120dc60d0bdb ("arm64: get rid of TEXT_OFFSET")
Signed-off-by: Rasmus Villemoes <linux@rasmusvillemoes.dk>
---
I've included a Fixes tag since I spent way too much time tracking
down where that text_offset might be defined. The mentioned commit did
get rid of all references to TEXT_OFFSET-the-macro, but not
text_offset-the-concept.

 Documentation/arch/arm64/booting.rst | 20 +++++---------------
 1 file changed, 5 insertions(+), 15 deletions(-)

diff --git a/Documentation/arch/arm64/booting.rst b/Documentation/arch/arm64/booting.rst
index 13ef311dace8..f4cc25b1fd56 100644
--- a/Documentation/arch/arm64/booting.rst
+++ b/Documentation/arch/arm64/booting.rst
@@ -55,9 +55,6 @@ not exceed 2 megabytes in size. Since the dtb will be mapped cacheable
 using blocks of up to 2 megabytes in size, it must not be placed within
 any 2M region which must be mapped with any specific attributes.
 
-NOTE: versions prior to v4.2 also require that the DTB be placed within
-the 512 MB region starting at text_offset bytes below the kernel Image.
-
 3. Decompress the kernel image
 ------------------------------
 
@@ -93,6 +90,8 @@ Header notes:
 
 - As of v3.17, all fields are little endian unless stated otherwise.
 
+- As of v5.10, text_offset is always 0.
+
 - code0/code1 are responsible for branching to stext.
 
 - when booting through EFI, code0/code1 are initially skipped.
@@ -100,12 +99,6 @@ Header notes:
   entry point (efi_stub_entry).  When the stub has done its work, it
   jumps to code0 to resume the normal boot process.
 
-- Prior to v3.17, the endianness of text_offset was not specified.  In
-  these cases image_size is zero and text_offset is 0x80000 in the
-  endianness of the kernel.  Where image_size is non-zero image_size is
-  little-endian and must be respected.  Where image_size is zero,
-  text_offset can be assumed to be 0x80000.
-
 - The flags field (introduced in v3.17) is a little-endian 64-bit field
   composed as follows:
 
@@ -135,12 +128,9 @@ Header notes:
   end of the kernel image. The amount of space required will vary
   depending on selected features, and is effectively unbound.
 
-The Image must be placed text_offset bytes from a 2MB aligned base
-address anywhere in usable system RAM and called there. The region
-between the 2 MB aligned base address and the start of the image has no
-special significance to the kernel, and may be used for other purposes.
-At least image_size bytes from the start of the image must be free for
-use by the kernel.
+The Image must be placed at a 2MB aligned base address anywhere in
+usable system RAM and called there.  At least image_size bytes from
+the start of the image must be free for use by the kernel.
 NOTE: versions prior to v4.6 cannot make use of memory below the
 physical offset of the Image so it is recommended that the Image be
 placed as close as possible to the start of system RAM.
-- 
2.54.0

Re: [PATCH] docs: arm64: Document that text_offset is always 0

[Rasmus Villemoes]

On Thu, Jun 04 2026, "Rasmus Villemoes" <linux@rasmusvillemoes.dk> wrote:

> When trying to figure out where to place and call an arm64 Image in
> memory, reading booting.rst should provide the answer. However, it
> requires quite some digging to figure out that text_offset is set via
> ".quad 0" in head.S and is thus actually always 0 since v5.10.
>
> Update the documentation and make that explicit. Reword the 2MB
> requirement accordingly, and remove the paragraphs that only apply to
> the ancient versions where text_offset could be non-zero, as they only
> confuse a current reader.
>

ping

Re: [PATCH] docs: arm64: Document that text_offset is always 0

[Will Deacon]

On Thu, Jun 04, 2026 at 04:08:39PM +0200, Rasmus Villemoes wrote:
> When trying to figure out where to place and call an arm64 Image in
> memory, reading booting.rst should provide the answer. However, it
> requires quite some digging to figure out that text_offset is set via
> ".quad 0" in head.S and is thus actually always 0 since v5.10.
> 
> Update the documentation and make that explicit. Reword the 2MB
> requirement accordingly, and remove the paragraphs that only apply to
> the ancient versions where text_offset could be non-zero, as they only
> confuse a current reader.

Doesn't this needlessly prevent us from having a non-zero offset in future,
if we wanted that for some reason?

Will

Re: [PATCH] docs: arm64: Document that text_offset is always 0

[Mark Rutland]

On Thu, Jun 04, 2026 at 04:08:39PM +0200, Rasmus Villemoes wrote:
> When trying to figure out where to place and call an arm64 Image in
> memory, reading booting.rst should provide the answer. However, it
> requires quite some digging to figure out that text_offset is set via
> ".quad 0" in head.S and is thus actually always 0 since v5.10.

What is the actual problem?

The documentation in booting.rst is accurate; I don't see why it's
necessary to read the source code to look at text_offset. Immediately
above the text in your diff, the documentation has:

| 4. Call the kernel image
| ------------------------
| 
| Requirement: MANDATORY
| 
| The decompressed kernel image contains a 64-byte header as follows::
| 
|   u32 code0;                    /* Executable code */
|   u32 code1;                    /* Executable code */
|   u64 text_offset;              /* Image load offset, little endian */
|   u64 image_size;               /* Effective Image size, little endian */
|   u64 flags;                    /* kernel flags, little endian */
|   u64 res2      = 0;            /* reserved */
|   u64 res3      = 0;            /* reserved */
|   u64 res4      = 0;            /* reserved */
|   u32 magic     = 0x644d5241;   /* Magic number, little endian, "ARM\x64" */
|   u32 res5;                     /* reserved (used for PE COFF offset) */

Can you explain the problem you're facing? e.g.

* Is the documentation unclear, in a way that could be better?

* Is there some aspect of the boot protocol that is hard for a
  bootloader to follow?

* Is there some problem with *testing* that bootloaders respect the
  text_offset requirements?

* Something else?

> Update the documentation and make that explicit. Reword the 2MB
> requirement accordingly, and remove the paragraphs that only apply to
> the ancient versions where text_offset could be non-zero, as they only
> confuse a current reader.
> 
> Fixes: 120dc60d0bdb ("arm64: get rid of TEXT_OFFSET")
> Signed-off-by: Rasmus Villemoes <linux@rasmusvillemoes.dk>
> ---
> I've included a Fixes tag since I spent way too much time tracking
> down where that text_offset might be defined. The mentioned commit did
> get rid of all references to TEXT_OFFSET-the-macro, but not
> text_offset-the-concept.

Keeping text_offset as a concept was deliberate. That allows us to keep
the documentation accruate for older kernel versions, and allows for the
possiblity that a non-zero offset is introduced in future (though I
admit that might be a tough sell).

>  Documentation/arch/arm64/booting.rst | 20 +++++---------------
>  1 file changed, 5 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/arch/arm64/booting.rst b/Documentation/arch/arm64/booting.rst
> index 13ef311dace8..f4cc25b1fd56 100644
> --- a/Documentation/arch/arm64/booting.rst
> +++ b/Documentation/arch/arm64/booting.rst
> @@ -55,9 +55,6 @@ not exceed 2 megabytes in size. Since the dtb will be mapped cacheable
>  using blocks of up to 2 megabytes in size, it must not be placed within
>  any 2M region which must be mapped with any specific attributes.
>  
> -NOTE: versions prior to v4.2 also require that the DTB be placed within
> -the 512 MB region starting at text_offset bytes below the kernel Image.
> -
>  3. Decompress the kernel image
>  ------------------------------
>  
> @@ -93,6 +90,8 @@ Header notes:
>  
>  - As of v3.17, all fields are little endian unless stated otherwise.
>  
> +- As of v5.10, text_offset is always 0.
> +
>  - code0/code1 are responsible for branching to stext.
>  
>  - when booting through EFI, code0/code1 are initially skipped.
> @@ -100,12 +99,6 @@ Header notes:
>    entry point (efi_stub_entry).  When the stub has done its work, it
>    jumps to code0 to resume the normal boot process.
>  
> -- Prior to v3.17, the endianness of text_offset was not specified.  In
> -  these cases image_size is zero and text_offset is 0x80000 in the
> -  endianness of the kernel.  Where image_size is non-zero image_size is
> -  little-endian and must be respected.  Where image_size is zero,
> -  text_offset can be assumed to be 0x80000.
> -

So far we've tried to ensure that the documentation covers current *and*
older kernel versions. If we're going to drop text covering older
versions we'd need an explciit statemnt as to which kernel versions the
document is accurate for.

I would prefer that we retained documentation regarding the text_offset
field in the header, even if it happens to be zero today.

Mark.

>  - The flags field (introduced in v3.17) is a little-endian 64-bit field
>    composed as follows:
>  
> @@ -135,12 +128,9 @@ Header notes:
>    end of the kernel image. The amount of space required will vary
>    depending on selected features, and is effectively unbound.
>  
> -The Image must be placed text_offset bytes from a 2MB aligned base
> -address anywhere in usable system RAM and called there. The region
> -between the 2 MB aligned base address and the start of the image has no
> -special significance to the kernel, and may be used for other purposes.
> -At least image_size bytes from the start of the image must be free for
> -use by the kernel.
> +The Image must be placed at a 2MB aligned base address anywhere in
> +usable system RAM and called there.  At least image_size bytes from
> +the start of the image must be free for use by the kernel.
>  NOTE: versions prior to v4.6 cannot make use of memory below the
>  physical offset of the Image so it is recommended that the Image be
>  placed as close as possible to the start of system RAM.
> -- 
> 2.54.0
> 

Re: [PATCH] docs: arm64: Document that text_offset is always 0

[Rasmus Villemoes]

On Fri, Jun 19 2026, "Mark Rutland" <mark.rutland@arm.com> wrote:

> On Thu, Jun 04, 2026 at 04:08:39PM +0200, Rasmus Villemoes wrote:
>> When trying to figure out where to place and call an arm64 Image in
>> memory, reading booting.rst should provide the answer. However, it
>> requires quite some digging to figure out that text_offset is set via
>> ".quad 0" in head.S and is thus actually always 0 since v5.10.
>
> What is the actual problem?
>
> The documentation in booting.rst is accurate; I don't see why it's
> necessary to read the source code to look at text_offset. Immediately
> above the text in your diff, the documentation has:
>
> | 4. Call the kernel image
> | ------------------------
> |
> | Requirement: MANDATORY
> |
> | The decompressed kernel image contains a 64-byte header as follows::
> |
> |   u32 code0;                    /* Executable code */
> |   u32 code1;                    /* Executable code */
> |   u64 text_offset;              /* Image load offset, little endian */
> |   u64 image_size;               /* Effective Image size, little endian */
> |   u64 flags;                    /* kernel flags, little endian */
> |   u64 res2      = 0;            /* reserved */
> |   u64 res3      = 0;            /* reserved */
> |   u64 res4      = 0;            /* reserved */
> |   u32 magic     = 0x644d5241;   /* Magic number, little endian, "ARM\x64" */
> |   u32 res5;                     /* reserved (used for PE COFF offset) */
>
> Can you explain the problem you're facing? e.g.
>
> * Is the documentation unclear, in a way that could be better?
>
> * Is there some aspect of the boot protocol that is hard for a
>   bootloader to follow?
>
> * Is there some problem with *testing* that bootloaders respect the
>   text_offset requirements?
>
> * Something else?

Yes, the structure of the header is documented. But nowhere is it
explained how the text_offset field gets its value.

So imagine I've just built an arm64 kernel. Now I want to put that into
a FIT image, where I tell the bootloader where to place it and what
address to jump to, via the load= and entry= properties. Now, the
documentation

  The Image must be placed text_offset bytes from a 2MB aligned base
  address anywhere in usable system RAM and called there.

is clear enough that those two have to be the same value. What is not at
all clear is how I'm suppose to determine what that text_offset value is
that I'm suppose to add to some 2MB aligned address I choose.

Prior to 120dc60d0, one could at least 'git grep TEXT_OFFSET --
arch/arm64/' and see 'TEXT_OFFSET := 0x0'.

>> I've included a Fixes tag since I spent way too much time tracking
>> down where that text_offset might be defined. The mentioned commit did
>> get rid of all references to TEXT_OFFSET-the-macro, but not
>> text_offset-the-concept.
>
> Keeping text_offset as a concept was deliberate. That allows us to keep
> the documentation accruate for older kernel versions, and allows for the
> possiblity that a non-zero offset is introduced in future (though I
> admit that might be a tough sell).

Fair enough. But would you at least consider adding just this part:

>> +- As of v5.10, text_offset is always 0.
>> +

One can, using the documented header, read it post-factum from the
kernel binary itself, and perhaps that's what's intended. But to answer
your first question, yes, I did find the documenation unclear and
expected to find some explicit mention of how one is supposed to know
the value of text_offset.

Rasmus

Re: [PATCH] docs: arm64: Document that text_offset is always 0

[Mark Rutland]

On Fri, Jun 26, 2026 at 03:52:39PM +0200, Rasmus Villemoes wrote:
> On Fri, Jun 19 2026, "Mark Rutland" <mark.rutland@arm.com> wrote:
> 
> > On Thu, Jun 04, 2026 at 04:08:39PM +0200, Rasmus Villemoes wrote:
> >> When trying to figure out where to place and call an arm64 Image in
> >> memory, reading booting.rst should provide the answer. However, it
> >> requires quite some digging to figure out that text_offset is set via
> >> ".quad 0" in head.S and is thus actually always 0 since v5.10.
> >
> > What is the actual problem?
> >
> > The documentation in booting.rst is accurate; I don't see why it's
> > necessary to read the source code to look at text_offset. Immediately
> > above the text in your diff, the documentation has:
> >
> > | 4. Call the kernel image
> > | ------------------------
> > |
> > | Requirement: MANDATORY
> > |
> > | The decompressed kernel image contains a 64-byte header as follows::
> > |
> > |   u32 code0;                    /* Executable code */
> > |   u32 code1;                    /* Executable code */
> > |   u64 text_offset;              /* Image load offset, little endian */
> > |   u64 image_size;               /* Effective Image size, little endian */
> > |   u64 flags;                    /* kernel flags, little endian */
> > |   u64 res2      = 0;            /* reserved */
> > |   u64 res3      = 0;            /* reserved */
> > |   u64 res4      = 0;            /* reserved */
> > |   u32 magic     = 0x644d5241;   /* Magic number, little endian, "ARM\x64" */
> > |   u32 res5;                     /* reserved (used for PE COFF offset) */
> >
> > Can you explain the problem you're facing? e.g.
> >
> > * Is the documentation unclear, in a way that could be better?
> >
> > * Is there some aspect of the boot protocol that is hard for a
> >   bootloader to follow?
> >
> > * Is there some problem with *testing* that bootloaders respect the
> >   text_offset requirements?
> >
> > * Something else?
> 
> Yes, the structure of the header is documented. But nowhere is it
> explained how the text_offset field gets its value.
> 
> So imagine I've just built an arm64 kernel. Now I want to put that into
> a FIT image, where I tell the bootloader where to place it and what
> address to jump to, via the load= and entry= properties. Now, the
> documentation
> 
>   The Image must be placed text_offset bytes from a 2MB aligned base
>   address anywhere in usable system RAM and called there.
> 
> is clear enough that those two have to be the same value. What is not at
> all clear is how I'm suppose to determine what that text_offset value is
> that I'm suppose to add to some 2MB aligned address I choose.

To determine that you should read the text_offset field from the header
in the Image binary.

That's the *entire* point of having the header -- bootloaders and
scripts should read that, and don't need to know anything about the
kernel source code or build process.

For example, see the aarch64 boot-wrapper:

  https://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git/commit/?id=4a50f69c550473b989f0d38f096d4d9a3a6804c7

> Prior to 120dc60d0, one could at least 'git grep TEXT_OFFSET --
> arch/arm64/' and see 'TEXT_OFFSET := 0x0'.

That was never necessary, and never a good idea, because the internals
of the kernel source code can change (as they have now). Bootloaders
and/or scripting should consume the Image header.

> >> I've included a Fixes tag since I spent way too much time tracking
> >> down where that text_offset might be defined. The mentioned commit did
> >> get rid of all references to TEXT_OFFSET-the-macro, but not
> >> text_offset-the-concept.
> >
> > Keeping text_offset as a concept was deliberate. That allows us to keep
> > the documentation accruate for older kernel versions, and allows for the
> > possiblity that a non-zero offset is introduced in future (though I
> > admit that might be a tough sell).
> 
> Fair enough. But would you at least consider adding just this part:
> 
> >> +- As of v5.10, text_offset is always 0.
> >> +

If we add that, then we're tacitly saying that people don't need to read
the text_offset field from the header, and we're removing our ability to
ever change that.

I don't think we should add such a statement unless we're certain we'll
never want a non-zero text_offset in future.

> One can, using the documented header, read it post-factum from the
> kernel binary itself, and perhaps that's what's intended. But to answer
> your first question, yes, I did find the documenation unclear and
> expected to find some explicit mention of how one is supposed to know
> the value of text_offset.

As above, reading the header from the Image binary is *exactly* what is
intended.

If that's not clear from the documentation, what do you think would
clarify that?

Mark.