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@xxxxxxxxx> > Signed-off-by: Toke Høiland-Jørgensen <toke@xxxxxxxxxx> Thanks for fixing this. LGTM modulo one small grammar nit. Acked-by: David Vernet <void@xxxxxxxxxxxxx> > --- > 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 >
