diff mbox series

[bpf-next,v4,01/24] bpf: Document UAPI details for special BPF types

Message ID 20221103191013.1236066-2-memxor@gmail.com (mailing list archive)
State Superseded
Commit 9805af8d8a5b17f9ea0a16f636f3440b970049f3
Delegated to: BPF
Headers show
Series Local kptrs, BPF linked lists | expand

Checks

Context Check Description
netdev/tree_selection success Clearly marked for bpf-next, async
netdev/fixes_present success Fixes tag not required for -next series
netdev/subject_prefix success Link
netdev/cover_letter success Series has a cover letter
netdev/patch_count fail Series longer than 15 patches (and no cover letter)
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 0 this patch: 0
netdev/cc_maintainers warning 10 maintainers not CCed: sdf@google.com kpsingh@kernel.org haoluo@google.com corbet@lwn.net yhs@fb.com jolsa@kernel.org martin.lau@linux.dev linux-doc@vger.kernel.org song@kernel.org john.fastabend@gmail.com
netdev/build_clang success Errors and warnings before: 0 this patch: 0
netdev/module_param success Was 0 now: 0
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 0 this patch: 0
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 47 lines checked
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0
bpf/vmtest-bpf-next-VM_Test-2 fail Logs for build for s390x with gcc
bpf/vmtest-bpf-next-VM_Test-1 pending Logs for ${{ matrix.test }} on ${{ matrix.arch }} with ${{ matrix.toolchain }}
bpf/vmtest-bpf-next-VM_Test-3 fail Logs for build for s390x with gcc
bpf/vmtest-bpf-next-VM_Test-4 fail Logs for build for x86_64 with gcc
bpf/vmtest-bpf-next-VM_Test-5 fail Logs for build for x86_64 with llvm-16
bpf/vmtest-bpf-next-VM_Test-6 success Logs for llvm-toolchain
bpf/vmtest-bpf-next-VM_Test-7 success Logs for set-matrix
bpf/vmtest-bpf-next-PR fail merge-conflict

Commit Message

Kumar Kartikeya Dwivedi Nov. 3, 2022, 7:09 p.m. UTC
The kernel recognizes some special BPF types in map values or local
kptrs. Document that only bpf_spin_lock and bpf_timer will preserve
backwards compatibility, and kptr will preserve backwards compatibility
for the operations on the pointer, not the types supported for such
kptrs.

For local kptrs, document that there are no stability guarantees at all.

Finally, document that 'bpf_' namespace is reserved for adding future
special fields, hence BPF programs must not declare types with such
names in their programs and still expect backwards compatibility.

Signed-off-by: Kumar Kartikeya Dwivedi <memxor@gmail.com>
---
 Documentation/bpf/bpf_design_QA.rst | 44 +++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

Comments

David Vernet Nov. 3, 2022, 8:38 p.m. UTC | #1
On Fri, Nov 04, 2022 at 12:39:50AM +0530, Kumar Kartikeya Dwivedi wrote:
> The kernel recognizes some special BPF types in map values or local
> kptrs. Document that only bpf_spin_lock and bpf_timer will preserve
> backwards compatibility, and kptr will preserve backwards compatibility
> for the operations on the pointer, not the types supported for such
> kptrs.
> 
> For local kptrs, document that there are no stability guarantees at all.
> 
> Finally, document that 'bpf_' namespace is reserved for adding future
> special fields, hence BPF programs must not declare types with such
> names in their programs and still expect backwards compatibility.
> 
> Signed-off-by: Kumar Kartikeya Dwivedi <memxor@gmail.com>
> ---
>  Documentation/bpf/bpf_design_QA.rst | 44 +++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> index a210b8a4df00..b5273148497c 100644
> --- a/Documentation/bpf/bpf_design_QA.rst
> +++ b/Documentation/bpf/bpf_design_QA.rst
> @@ -298,3 +298,47 @@ A: NO.
>  
>  The BTF_ID macro does not cause a function to become part of the ABI
>  any more than does the EXPORT_SYMBOL_GPL macro.
> +
> +Q: What is the compatibility story for special BPF types in map values?
> +-----------------------------------------------------------------------
> +Q: Users are allowed to embed bpf_spin_lock, bpf_timer fields in their BPF map
> +values (when using BTF support for BPF maps). This allows to use helpers for
> +such objects on these fields inside map values. Users are also allowed to embed
> +pointers to some kernel types (with __kptr and __kptr_ref BTF tags). Will the
> +kernel preserve backwards compatibility for these features?
> +
> +A: It depends. For bpf_spin_lock, bpf_timer: YES, for kptr and everything else:
> +NO, but see below.
> +
> +For struct types that have been added already, like bpf_spin_lock and bpf_timer,
> +the kernel will preserve backwards compatibility, as they are part of UAPI.
> +
> +For kptrs, they are also part of UAPI, but only with respect to the kptr
> +mechanism. The types that you can use with a __kptr and __kptr_ref tagged
> +pointer in your struct is NOT part of the UAPI contract. The supported types can

s/is NOT/are NOT

> +and will change across kernel releases. However, operations like accessing kptr
> +fields and bpf_kptr_xchg() helper will continue to be supported across kernel
> +releases for the supported types.
> +
> +For any other supported struct type, unless explicitly stated in this document
> +and added to bpf.h UAPI header, such types can and will arbitrarily change their
> +size, type, and alignment, or any other user visible API or ABI detail across
> +kernel releases. The users must adapt their BPF programs to the new changes and
> +update them to make sure their programs continue to work correctly.
> +
> +NOTE: BPF subsystem specially reserves the 'bpf_' prefix for type names, in
> +order to introduce more special fields in the future. Hence, user programs must
> +avoid defining types with 'bpf_' prefix to not be broken in future releases. In
> +other words, no backwards compatibility is guaranteed if one using a type in BTF
> +with 'bpf_' prefix.
> +
> +Q: What is the compatibility story for special BPF types in local kptrs?
> +------------------------------------------------------------------------
> +Q: Same as above, but for local kptrs (i.e. pointers to objects allocated using
> +bpf_obj_new for user defined structures). Will the kernel preserve backwards
> +compatibility for these features?
> +
> +A: NO.
> +
> +Unlike map value types, there are no stability guarantees for this case. The
> +whole local kptr API itself is unstable (since it is exposed through kfuncs).
> -- 
> 2.38.1
> 

Looks good otherwise.

Acked-by: David Vernet <void@manifault.com>
diff mbox series

Patch

diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
index a210b8a4df00..b5273148497c 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -298,3 +298,47 @@  A: NO.
 
 The BTF_ID macro does not cause a function to become part of the ABI
 any more than does the EXPORT_SYMBOL_GPL macro.
+
+Q: What is the compatibility story for special BPF types in map values?
+-----------------------------------------------------------------------
+Q: Users are allowed to embed bpf_spin_lock, bpf_timer fields in their BPF map
+values (when using BTF support for BPF maps). This allows to use helpers for
+such objects on these fields inside map values. Users are also allowed to embed
+pointers to some kernel types (with __kptr and __kptr_ref BTF tags). Will the
+kernel preserve backwards compatibility for these features?
+
+A: It depends. For bpf_spin_lock, bpf_timer: YES, for kptr and everything else:
+NO, but see below.
+
+For struct types that have been added already, like bpf_spin_lock and bpf_timer,
+the kernel will preserve backwards compatibility, as they are part of UAPI.
+
+For kptrs, they are also part of UAPI, but only with respect to the kptr
+mechanism. The types that you can use with a __kptr and __kptr_ref tagged
+pointer in your struct is NOT part of the UAPI contract. The supported types can
+and will change across kernel releases. However, operations like accessing kptr
+fields and bpf_kptr_xchg() helper will continue to be supported across kernel
+releases for the supported types.
+
+For any other supported struct type, unless explicitly stated in this document
+and added to bpf.h UAPI header, such types can and will arbitrarily change their
+size, type, and alignment, or any other user visible API or ABI detail across
+kernel releases. The users must adapt their BPF programs to the new changes and
+update them to make sure their programs continue to work correctly.
+
+NOTE: BPF subsystem specially reserves the 'bpf_' prefix for type names, in
+order to introduce more special fields in the future. Hence, user programs must
+avoid defining types with 'bpf_' prefix to not be broken in future releases. In
+other words, no backwards compatibility is guaranteed if one using a type in BTF
+with 'bpf_' prefix.
+
+Q: What is the compatibility story for special BPF types in local kptrs?
+------------------------------------------------------------------------
+Q: Same as above, but for local kptrs (i.e. pointers to objects allocated using
+bpf_obj_new for user defined structures). Will the kernel preserve backwards
+compatibility for these features?
+
+A: NO.
+
+Unlike map value types, there are no stability guarantees for this case. The
+whole local kptr API itself is unstable (since it is exposed through kfuncs).