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

[David Vernet <void@manifault.com>]

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>