[PATCH bpf-next v4 12/12] docs/bpf: Document arena pointers in a by-value return

[Yonghong Song <yonghong.song@linux.dev>]

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 <yonghong.song@linux.dev>
---
 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
-- 
2.53.0-Meta