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@xxxxxxxxx> > --- > 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@xxxxxxxxxxxxx>
