iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
26759bee43
linux/Documentation/bpf
History
David Vernet 16c294a6aa bpf/docs: Document kfunc lifecycle / stability expectations 
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
functionally 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.

To do that, this patch adds that documentation to the main kfuncs
documentation page via a new 'kfunc lifecycle expectations' section. The
patch 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 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.

In addition to the 'kfunc lifecycle expectations' section, this patch
also adds documentation for a new KF_DEPRECATED kfunc flag which kfunc
authors or maintainers can choose to add to kfuncs if and when they
decide to deprecate them. Note that as described in the patch itself, a
kfunc need not be deprecated before being changed or removed -- this
flag is simply provided as an available deprecation mechanism for those
that want to provide a deprecation story / timeline to their users.
When necessary, kfuncs may be changed or removed to accommodate changes
elsewhere in the kernel without any deprecation at all.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Co-developed-by: Toke Høiland-Jørgensen <toke@redhat.com>
Signed-off-by: David Vernet <void@manifault.com>
Link: https://lore.kernel.org/r/20230203155727.793518-2-void@manifault.com
Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2023-02-03 09:01:29 -08:00
..
libbpf Documentation: bpf: correct spelling 2023-01-28 12:22:20 -08:00
bpf_design_QA.rst bpf: Remove local kptr references in documentation 2022-11-14 21:52:45 -08:00
bpf_devel_QA.rst bpf/docs: Include blank lines between bullet points in bpf_devel_QA.rst 2022-11-17 16:26:42 +01:00
bpf_iterators.rst bpf, docs: BPF Iterator Document 2022-12-04 16:41:22 -08:00
bpf_licensing.rst bpf: Document BPF licensing. 2021-09-22 23:13:13 +02:00
bpf_prog_run.rst Documentation/bpf: Add documentation for BPF_PROG_RUN 2022-03-09 14:19:22 -08:00
btf.rst docs/bpf: Update btf selftests program and add link 2022-11-25 00:00:15 +01:00
clang-notes.rst bpf, docs: Add Clang note about BPF_ALU 2022-09-30 13:41:25 -07:00
classic_vs_extended.rst bpf, docs: Split the comparism to classic BPF from instruction-set.rst 2021-12-30 16:31:44 -08:00
cpumasks.rst bpf/docs: Document cpumask kfuncs in a new file 2023-01-25 07:57:50 -08:00
drgn.rst bpf: Document bpf_inspect drgn tool 2020-03-26 00:08:36 +01:00
faq.rst bpf, docs: Fix ordering of bpf documentation 2021-11-17 23:24:01 +01:00
helpers.rst bpf, docs: Fix ordering of bpf documentation 2021-11-17 23:24:01 +01:00
index.rst bpf/docs: Document cpumask kfuncs in a new file 2023-01-25 07:57:50 -08:00
instruction-set.rst bpf, docs: Fix modulo zero, division by zero, overflow, and underflow 2023-01-24 16:46:40 +01:00
kfuncs.rst bpf/docs: Document kfunc lifecycle / stability expectations 2023-02-03 09:01:29 -08:00
linux-notes.rst bpf, docs: Delete misformatted table. 2022-10-01 08:51:26 -07:00
llvm_reloc.rst bpf, docs: Add llvm_reloc.rst to explain llvm bpf relocations 2021-05-28 22:12:04 +02:00
map_array.rst docs/bpf: Fix sphinx warnings in BPF map docs 2022-11-24 01:05:04 +01:00
map_bloom_filter.rst docs/bpf: Document BPF_MAP_TYPE_BLOOM_FILTER 2022-11-23 22:47:32 +01:00
map_cgroup_storage.rst Remove duplicate words inside documentation 2022-09-27 13:21:43 -06:00
map_cgrp_storage.rst docs/bpf: Add documentation for new cgroup local storage 2022-10-25 23:19:20 -07:00
map_cpumap.rst docs/bpf: Fix sphinx warnings for cpumap 2022-11-23 22:38:53 +01:00
map_devmap.rst docs/bpf: Fix sphinx warnings for devmap 2022-11-23 22:40:27 +01:00
map_hash.rst docs/bpf: Fix sphinx warnings in BPF map docs 2022-11-24 01:05:04 +01:00
map_lpm_trie.rst docs/bpf: Fix sphinx warnings in BPF map docs 2022-11-24 01:05:04 +01:00
map_of_maps.rst docs/bpf: Fix sphinx warnings in BPF map docs 2022-11-24 01:05:04 +01:00
map_queue_stack.rst docs/bpf: Fix sphinx warnings in BPF map docs 2022-11-24 01:05:04 +01:00
map_sk_storage.rst docs/bpf: Reword docs for BPF_MAP_TYPE_SK_STORAGE 2022-12-14 18:35:41 +01:00
map_sockmap.rst docs: BPF_MAP_TYPE_SOCK[MAP|HASH] 2022-12-20 15:54:05 -08:00
map_xskmap.rst Documentation: bpf: correct spelling 2023-01-28 12:22:20 -08:00
maps.rst bpf, docs: Reformat BPF maps page to be more readable 2022-10-20 18:53:34 -07:00
other.rst bpf, docs: Fix ordering of bpf documentation 2021-11-17 23:24:01 +01:00
prog_cgroup_sockopt.rst bpf: Document optval > PAGE_SIZE behavior for sockopt hooks 2020-06-17 10:54:05 -07:00
prog_cgroup_sysctl.rst bpf: Document BPF_PROG_TYPE_CGROUP_SYSCTL 2019-04-18 16:05:36 -07:00
prog_flow_dissector.rst bpf/flow_dissector: add mode to enforce global BPF flow dissector 2019-10-07 20:16:33 -07:00
prog_lsm.rst bpf, docs: Rename bpf_lsm.rst to prog_lsm.rst 2021-11-17 23:23:58 +01:00
prog_sk_lookup.rst bpf: sk_lookup: Add user documentation 2020-08-24 14:46:50 -07:00
programs.rst docs/bpf: Add table of BPF program types to libbpf docs 2022-11-23 13:31:20 -08:00
redirect.rst bpf, docs: DEVMAPs and XDP_REDIRECT 2022-11-18 23:16:31 +01:00
ringbuf.rst Documentation: bpf: correct spelling 2023-01-28 12:22:20 -08:00
s390.rst bpf: Add s390 testing documentation 2019-10-30 16:25:31 +01:00
syscall_api.rst bpf, docs: Fix ordering of bpf documentation 2021-11-17 23:24:01 +01:00
test_debug.rst bpf, docs: Fix ordering of bpf documentation 2021-11-17 23:24:01 +01:00
verifier.rst docs/bpf: Add description of register liveness tracking algorithm 2023-02-02 20:21:59 -08:00