Re: [PATCH bpf-next v2] bpf/docs: Update design QA to be consistent with kfunc lifecycle docs

[David Vernet <void@manifault.com>]

On Wed, Feb 08, 2023 at 02:57:30PM +0100, Toke Høiland-Jørgensen wrote:
> Cong pointed out that there are some inconsistencies between the BPF design
> QA and the lifecycle expectations documentation we added for kfuncs. Let's
> update the QA file to be consistent with the kfunc docs, and add references
> where it makes sense. Also document that modules may export kfuncs now.
> 
> v2:
> - Fix repeated word (s/defined defined/defined/)
> 
> Reported-by: Cong Wang <xiyou.wangcong@gmail.com>
> Signed-off-by: Toke Høiland-Jørgensen <toke@redhat.com>

Thanks for fixing this. LGTM modulo one small grammar nit.

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

> ---
>  Documentation/bpf/bpf_design_QA.rst | 25 ++++++++++++++++++-------
>  1 file changed, 18 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> index cec2371173d7..4d3135187e0c 100644
> --- a/Documentation/bpf/bpf_design_QA.rst
> +++ b/Documentation/bpf/bpf_design_QA.rst
> @@ -208,6 +208,10 @@ data structures and compile with kernel internal headers. Both of these
>  kernel internals are subject to change and can break with newer kernels
>  such that the program needs to be adapted accordingly.
>  
> +New BPF functionality is generally added through the use of kfuncs instead of
> +new helpers. Kfuncs are not considered part of the stable API, but has their own

s/but has/and have

> +lifecycle expectations as described in :ref:`BPF_kfunc_lifecycle_expectations`.
> +
>  Q: Are tracepoints part of the stable ABI?
>  ------------------------------------------
>  A: NO. Tracepoints are tied to internal implementation details hence they are
> @@ -236,8 +240,8 @@ A: NO. Classic BPF programs are converted into extend BPF instructions.
>  
>  Q: Can BPF call arbitrary kernel functions?
>  -------------------------------------------
> -A: NO. BPF programs can only call a set of helper functions which
> -is defined for every program type.
> +A: NO. BPF programs can only call specific functions exposed as BPF helpers or
> +kfuncs. The set of available functions is defined for every program type.
>  
>  Q: Can BPF overwrite arbitrary kernel memory?
>  ---------------------------------------------
> @@ -263,7 +267,12 @@ Q: New functionality via kernel modules?
>  Q: Can BPF functionality such as new program or map types, new
>  helpers, etc be added out of kernel module code?
>  
> -A: NO.
> +A: Yes, through kfuncs and kptrs
> +
> +The core BPF functionality such as program types, maps and helpers cannot be
> +added to by modules. However, modules can expose functionality to BPF programs
> +by exporting kfuncs (which may return pointers to module-internal data
> +structures as kptrs).
>  
>  Q: Directly calling kernel function is an ABI?
>  ----------------------------------------------
> @@ -278,7 +287,8 @@ kernel functions have already been used by other kernel tcp
>  cc (congestion-control) implementations.  If any of these kernel
>  functions has changed, both the in-tree and out-of-tree kernel tcp cc
>  implementations have to be changed.  The same goes for the bpf
> -programs and they have to be adjusted accordingly.
> +programs and they have to be adjusted accordingly. See
> +:ref:`BPF_kfunc_lifecycle_expectations` for details.
>  
>  Q: Attaching to arbitrary kernel functions is an ABI?
>  -----------------------------------------------------
> @@ -340,6 +350,7 @@ compatibility for these features?
>  
>  A: NO.
>  
> -Unlike map value types, there are no stability guarantees for this case. The
> -whole API to work with allocated objects and any support for special fields
> -inside them is unstable (since it is exposed through kfuncs).
> +Unlike map value types, the API to work with allocated objects and any support
> +for special fields inside them is exposed through kfuncs, and thus has the same
> +lifecycle expectations as the kfuncs themselves. See
> +:ref:`BPF_kfunc_lifecycle_expectations` for details.
> -- 
> 2.39.1
>