[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 at 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.