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

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

On 8/29/26 6:33 PM, Kumar Kartikeya Dwivedi wrote:
> On Sat Aug 29, 2026 at 8:16 AM CEST, Yonghong Song wrote:
>> 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.
>> +
> I think it would make more sense to support translation for returned arena
> pointers as well, i.e. KF_ARENA_RET + the case you describe above. Like, anyone
> who would use this tag in a struct being returned to the user would probably we
> working with the kernel pointer into the arena.
>
> I think permitting them in the verifier is a good first step, but it isn't all
> that useful unless the translation is supported as well. Otherwise, the kfunc
> has to do it manually, which is a bit of a pain, esp. without access to the
> program's arena's base addresses, which isn't always easily possible across
> various program types.

Probably you mean something like below for input argument 'addr'.

+__bpf_kfunc struct prog_test_ret_arena bpf_kfunc_call_test_ret_arena(u64 addr)
+{
+	struct prog_test_ret_arena r = { .a = (void *)addr, .b = (void *)(addr + 4) };
+
+	return r;
+}

Yes, if kfunc itself wants to do something (esp. dereference of the addr), it cannot
do it.

>
> I can look into doing this in case you don't have cycles, but overall should be
> fairly simple to plumb support.

Sure. Please do it. Thanks!


>
>> [...]