From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from 66-220-144-179.mail-mxout.facebook.com (66-220-144-179.mail-mxout.facebook.com [66.220.144.179]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 247EB1DED5B for ; Tue, 11 Aug 2026 00:10:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=66.220.144.179 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786407021; cv=none; b=eZsdUHaZDLotPjbWvku2OQYFErQv8TDL61SGCk0PgnbGdjYRm9xAYTnITS3WSlyF+gLmyEJWatm3RdvIsI4pIMu5PyrH4velMNaNeTvZhhm4jdS5AFYNW0O260e5+pCAyxHF/rYsRCUsVl7cc65M0gXcOCy1IRZvq6Hg6sjFa2s= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786407021; c=relaxed/simple; bh=qZolSQLjJyVxkjxAg0pGQPrKOpCmLi6GLr/h3KrkJis=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=pUL23go6TbFr35WENZl0r+ONpWuA8e15NyiLIT4zeGDdMLRlwtRsPoYh2thvMnqbPAGM4CdBYpgVRixyfSMU9AEJOQsil9csek4/g7095JnDjxms6R3eN9svUm7gJg57jWAIDRi5em1nu0fKU7U+Uo86HkKgtRXTdB/e1xOVBfE= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=fail (p=none dis=none) header.from=linux.dev; spf=fail smtp.mailfrom=linux.dev; arc=none smtp.client-ip=66.220.144.179 Authentication-Results: smtp.subspace.kernel.org; dmarc=fail (p=none dis=none) header.from=linux.dev Authentication-Results: smtp.subspace.kernel.org; spf=fail smtp.mailfrom=linux.dev Received: by devvm16039.vll0.facebook.com (Postfix, from userid 128203) id 4C054233CF2898; Mon, 10 Aug 2026 17:10:18 -0700 (PDT) From: Yonghong Song To: bpf@vger.kernel.org Cc: Alexei Starovoitov , Andrii Nakryiko , Daniel Borkmann , Eduard Zingerman , kernel-team@fb.com Subject: [PATCH bpf-next v4 13/13] Documentation/bpf: Document up to 16-byte kfunc return values in R0:R2 Date: Mon, 10 Aug 2026 17:10:18 -0700 Message-ID: <20260811001018.2386016-1-yonghong.song@linux.dev> X-Mailer: git-send-email 2.53.0 In-Reply-To: <20260811000911.2378679-1-yonghong.song@linux.dev> References: <20260811000911.2378679-1-yonghong.song@linux.dev> Precedence: bulk X-Mailing-List: bpf@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable kfuncs may now return a value larger than 8 bytes and up to 16 bytes (a scalar-only struct or union, or an __int128), passed back in the R0:R2 register pair. Add a kfunc return-value section documenting this, including that a struct or union up to 8 bytes is returned in R0 alone, which struct and union members are accepted, that the R0:R2 register pair requires JIT support (bpf_jit_supports_kfunc_ret_reg_pair()), and that a return value larger than 16 bytes is unsupported. Also note that the same convention applies to BPF subprogram returns, and document the consequence for a global subprogram: it must assign both halves of a register-pair return, since an unassigned R2 may be left holding a pointer argument and is then rejected as a leak. Signed-off-by: Yonghong Song --- Documentation/bpf/kfuncs.rst | 62 ++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index 1004eb0bec61..71d3ff869599 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -575,6 +575,68 @@ is also covered by this recovery. A kfunc handed an = arena pointer may therefore access up to ``GUARD_SZ / 2`` past it without bounds-checking against the arena. Larger accesses must verify the range explicitly. =20 +2.9 kfunc Return Values +----------------------- + +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 scalar= s 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 sc= alar +and escape the verifier's pointer provenance and reference tracking. A s= truct +or union with a pointer member is therefore rejected at load time, and s= o is +one with a floating-point member, which the ABI may not return in R0:R2 = at +all. + +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 returne= d +in the register pair R0:R2, matching the convention LLVM uses for the BP= F +target: the first 8 bytes in R0 and the second 8 bytes in R2. A struct o= r +union of 8 bytes or less is returned in R0 alone. + +:: + + struct bpf_pair { __u64 a, b; }; /* 16 bytes */ + + __bpf_kfunc struct bpf_pair bpf_kfunc_get_pair(void) + { + struct bpf_pair p =3D { .a =3D 1, .b =3D 2 }; + + return p; /* p.a in R0, p.b in R2 */ + } + +Returning a value in the R0:R2 pair requires the JIT to place the second +half of the return value into R2, which not every architecture supports +right now. A kfunc with a return value larger than 8 bytes is therefore +rejected at load time on a JIT that does not advertise this capability (= see +``bpf_jit_supports_kfunc_ret_reg_pair()``), and such a program is never = run +by the interpreter. A return value larger than 16 bytes is not supported= . + +The same R0:R2 convention applies to a BPF subprogram, global or static, +that returns an ``__int128`` or a struct or union larger than 8 bytes. S= uch a +program also requires the JIT, since the interpreter propagates only R0 = out +of a subprogram. A global subprogram is verified in isolation, so its +by-value struct or union return is restricted to scalars just like a kfu= nc's; +a static subprogram is verified inline and has no such restriction. The = main +program cannot return more than 8 bytes, as its return value is the prog= ram's +exit code. + +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 +uninitialized is not merely untidy: the compiler is then free to leave R= 2 +holding whatever it happened to hold, which for a subprogram taking a po= inter +argument is typically that pointer. Handing the caller an unknown scalar= built +from a pointer is a leak, so the verifier rejects it with:: + + At subprogram exit the register R2 is not a scalar value (...) + +Initialize the whole return value, for example ``struct pair p =3D {};``= , to +avoid this. A static subprogram is exempt: it is verified inline, so an +unassigned R2 is simply passed back to the caller as uninitialized and o= nly a +caller that reads it fails. + .. _BPF_kfunc_lifecycle_expectations: =20 3. kfunc lifecycle expectations --=20 2.53.0-Meta