[bpf-next,0/3] Document kfunc lifecycle / stability expectations

Message

David Vernet Feb. 2, 2023, 4:30 p.m. UTC

BPF kernel <-> kernel API stability has been discussed at length over
the last several weeks and months. Now that we've largely aligned over
kfuncs being the way forward, and BPF helpers being considered frozen,
it's time to document the expectations for kfunc lifecycles and
stability so that everyone (BPF users, kfunc developers, and
maintainers) are all aligned, and have a crystal-clear understanding of
the expectations surrounding kfuncs.

This patch set adds that documentation to the main kfuncs documentation
page via a new 'kfunc lifecycle expectations' section. The documentation
describes how decisions are made in the kernel regarding whether to
include, keep, deprecate, or change / remove a kfunc. As described very
overtly in the patch set itself, but likely worth highlighting here:

"kfunc stability" does not mean, nor ever will mean, "BPF APIs may block
development elsewhere in the kernel".

Rather, the intention and expectation is for kfuncs to be treated like
EXPORT_SYMBOL_GPL symbols in the kernel. The goal is for kfuncs to be a
safe and valuable option for maintainers and kfunc developers to extend
the kernel, without tying anyone's hands, or imposing any kind of
restrictions on maintainers in the same way that UAPI changes do.

Note that other proposals for this documentation have been made as well.
Toke has proposed several iterations to this doc, with the latest being
[0].

[0]: https://lore.kernel.org/all/[e-mail]/

David Vernet (3):
  bpf/docs: Document kfunc lifecycle / stability expectations
  bpf: Add KF_DEPRECATED kfunc flag
  selftests/bpf: Add a selftest for the KF_DEPRECATED kfunc flag

 Documentation/bpf/kfuncs.rst                  | 125 +++++++++++++++++-
 include/linux/btf.h                           |   1 +
 kernel/bpf/verifier.c                         |   8 ++
 net/bpf/test_run.c                            |   5 +
 .../selftests/bpf/prog_tests/kfunc_call.c     |   2 +
 .../selftests/bpf/progs/kfunc_call_test.c     |  10 ++
 6 files changed, 146 insertions(+), 5 deletions(-)