From 25b0d73a7742d7415156c607f6278682efc12fc2 Mon Sep 17 00:00:00 2001 From: Yonghong Song Date: Fri, 28 Aug 2026 23:16:15 -0700 Subject: [PATCH] docs/bpf: Document arena pointers in a by-value return Section 2.9 describes the by-value return contract as scalars only, which no longer holds: a kfunc and a global subprogram may now return a struct or union whose members are scalars or arena pointers. Update it. Note that an arena pointer member is handed back as a scalar like every other member. That costs nothing: the program has to cast_kern() the value before it can be used, and the verifier allows that cast on any scalar, so the member gives the program no reach it did not already have. Signed-off-by: Yonghong Song Link: https://lore.kernel.org/r/20260829061615.1700421-1-yonghong.song@linux.dev Signed-off-by: Alexei Starovoitov --- Documentation/bpf/kfuncs.rst | 39 ++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index 89dea6b0b024..ebe37c1fe9d2 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -581,20 +581,29 @@ against the arena. Larger accesses must verify the range explicitly. A kfunc may return a scalar, a pointer, or a small struct or union by value. A scalar or pointer of up to 8 bytes is returned in R0, as usual. -A struct or union returned by value must be composed only of scalars -(recursively), where a scalar is an integer or an enum; arrays of scalars are -allowed as members. Its bytes are handed back to the program as the raw -contents of R0 (and R2), so a pointer field would be laundered into a scalar -and escape the verifier's pointer provenance and reference tracking. A struct -or union with a pointer member is therefore rejected at load time, and so is -one with a floating-point member, which the ABI may not return in R0:R2 at +A struct or union returned by value must be composed only of scalars and arena +pointers, where a scalar is an integer or an enum and an arena pointer is one +carrying the ``btf_type_tag("arena")`` attribute. Those may be nested in +structs and unions and in arrays of any number of dimensions, in any +combination, as long as what the nesting bottoms out in is a scalar or an arena +pointer. Its bytes are handed back to the program as the raw contents of R0 +(and R2), so a member of any other pointer type would be laundered into a +scalar and escape the verifier's pointer provenance and reference tracking. A +struct or union with such a member is therefore rejected at load time, and so +is one with a floating-point member, which the ABI may not return in R0:R2 at all. +An arena pointer member is handed back as a scalar too, but nothing is lost by +that. The program must ``cast_kern()`` the value before it can be used, and the +verifier allows that cast on any scalar, so a laundered arena address gives the +program no reach it did not already have. The result is confined to the +program's arena in either case. + A kfunc may also return a value larger than 8 bytes and up to 16 bytes -- a -scalar-only struct or union, or an ``__int128``. Such a value is returned -in the register pair R0:R2, matching the convention LLVM uses for the BPF -target: the first 8 bytes in R0 and the second 8 bytes in R2. A struct or -union of 8 bytes or less is returned in R0 alone. +struct or union of scalars and arena pointers, or an ``__int128``. Such a +value is returned in the register pair R0:R2, matching the convention LLVM +uses for the BPF target: the first 8 bytes in R0 and the second 8 bytes in R2. +A struct or union of 8 bytes or less is returned in R0 alone. :: @@ -620,10 +629,10 @@ used when the program is JITed, since the interpreter propagates only R0 out of a subprogram: without a JIT the return value stays in R0 alone, and a caller reading R2 is rejected for reading an uninitialized register. A global subprogram is verified in isolation, so its by-value struct or union return is -restricted to scalars just like a kfunc's; a static subprogram is verified -inline and has no such restriction. The main program is not covered: its return -value is the program's exit code, read out of R0 alone, so a declared upper -half is never looked at. +restricted to scalars and arena pointers just like a kfunc's; a static +subprogram is verified inline and has no such restriction. The main program is +not covered: its return value is the program's exit code, read out of R0 +alone, so a declared upper half is never looked at. A global subprogram must leave a scalar in *every* register of the pair, so both halves of the returned value have to be assigned. Leaving the upper half