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

[Rasmus Villemoes]

On Fri, Jun 19 2026, "Mark Rutland" <mark.rutland@xxxxxxx> 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