Documentation/bpf: Fix stale references in map docs
Subsystems (2)
cover Documentation/bpf: Fix stale references in map docs
Two documentation fixes for the BPF map pages.
Patch 1 records that since commit be39165224d0 ("bpf, sockmap: Disallow update and delete from tc, xdp, socket_filter and flow_dissector"), only BPF_TRACE_ITER tracing, sock_ops (delete only), sk_reuseport and sk_lookup programs may mutate a sockmap or sockhash; anything else is rejected with "cannot update sockmap in this context". The kernel-side sections of map_sockmap.rst did not mention this. It also drops the reference to progs/test_sockmap_update.c, removed by
commit 5de7a6eaed89 ("selftests/bpf: Drop tc/xdp/flow_dissector/socket_filter sockmap mutation tests").
Patch 2 fixes two moved selftests paths: test_lpm_map.c, now map_tests/lpm_trie_map_basic_ops.c, and test_xdp_noinline.c, now under progs/.
Documentation only; no functional change.
Ahmad Wicaksono (2):
Documentation/bpf: Update sockmap docs for mutation restrictions Documentation/bpf: Fix stale selftests file references
Documentation/bpf/btf.rst | 2 +- Documentation/bpf/map_lpm_trie.rst | 6 +++--- Documentation/bpf/map_sockmap.rst | 18 ++++++++++++++++-- 3 files changed, 20 insertions(+), 6 deletions(-)
checkpatch.pl --strict is clean. make SPHINXDIRS=bpf htmldocs gives identical warnings before and after. Documentation only, so nothing to run-test.
base-commit: ca4181cacb0c6a5632018f1c94f29d9dbc0e9270
Signature · 1 line
2.43.0
PATCH 1/2 Documentation/bpf: Update sockmap docs for mutation restrictions
Commit be39165224d0 ("bpf, sockmap: Disallow update and delete from tc, xdp, socket_filter and flow_dissector") dropped those program types from may_update_sockmap(), so tc, tc act, XDP, socket_filter and flow_dissector programs can no longer call bpf_map_update_elem() or bpf_map_delete_elem() on a sockmap or sockhash; the verifier now rejects them at load time with "cannot update sockmap in this context". The kernel-side sections of map_sockmap.rst did not mention this at all.
Record which program types may still mutate these maps, and note that sock_ops programs may delete entries but have to use bpf_sock_map_update() or bpf_sock_hash_update() to add them.
Also drop the reference to tools/testing/selftests/bpf/progs/test_sockmap_update.c and its link target. That file was removed by commit 5de7a6eaed89 ("selftests/bpf:
Drop tc/xdp/flow_dissector/socket_filter sockmap mutation tests").
--- Documentation/bpf/map_sockmap.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)
Documentation/bpf/map_sockmap.rst +16 -2
@@ -285,6 +285,16 @@ The flags argument can be one of the following: Returns 0 on success, or a negative error in case of failure. +.. note:: + The verifier only accepts this helper on a sockmap or sockhash from + ``BPF_PROG_TYPE_SK_REUSEPORT`` and ``BPF_PROG_TYPE_SK_LOOKUP`` + programs, and from ``BPF_PROG_TYPE_TRACING`` programs attached as + ``BPF_TRACE_ITER``. Other program types, such as tc, XDP, + socket_filter and flow_dissector, are rejected at load time with + "cannot update sockmap in this context". ``BPF_PROG_TYPE_SOCK_OPS`` + programs must use ``bpf_sock_map_update()`` or + ``bpf_sock_hash_update()`` instead. + bpf_map_delete_elem() ^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: c
@@ -295,6 +305,12 @@ Delete a socket entry from a sockmap or a sockhash. Returns 0 on success, or a negative error in case of failure. +.. note:: + The same program type restriction as for ``bpf_map_update_elem()`` + applies, except that ``BPF_PROG_TYPE_SOCK_OPS`` programs may delete + entries. Other program types are rejected at load time with + "cannot update sockmap in this context". + User space ---------- bpf_map_update_elem()
@@ -349,7 +365,6 @@ Several examples of the use of sockmap APIs can be found in: - `tools/testing/selftests/bpf/progs/sockmap_parse_prog.c`_ - `tools/testing/selftests/bpf/progs/sockmap_verdict_prog.c`_ - `tools/testing/selftests/bpf/progs/test_sockmap_listen.c`_ -- `tools/testing/selftests/bpf/progs/test_sockmap_update.c`_ The following code snippet shows how to declare a sockmap.
@@ -495,4 +510,3 @@ References .. _`tools/testing/selftests/bpf/test_sockmap.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/test_sockmap.c .. _`tools/testing/selftests/bpf/test_maps.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/test_maps.c .. _`tools/testing/selftests/bpf/progs/test_sockmap_listen.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/test_sockmap_listen.c -.. _`tools/testing/selftests/bpf/progs/test_sockmap_update.c`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/progs/test_sockmap_update.c
Signature · 1 line
2.43.0
Re: [PATCH bpf-next 1/2] Documentation/bpf: Update sockmap docs for mutation restrictions
Quoted 12 lines · Ahmad Wicaksono
Commit
be39165224d0("bpf, sockmap: Disallow update and delete from tc, xdp,socket_filterandflow_dissector") dropped those program types frommay_update_sockmap(), so tc, tc act, XDP,socket_filterandflow_dissectorprograms can no longer callbpf_map_update_elem()orbpf_map_delete_elem()on a sockmap or sockhash; the verifier now rejects them at load time with "cannot update sockmap in this context". The kernel-side sections ofmap_sockmap.rstdid not mention this at all.Record which program types may still mutate these maps, and note that
sock_opsprograms may delete entries but have to usebpf_sock_map_update()orbpf_sock_hash_update()to add them.
Quoted 7 lines
Also drop the reference to
tools/testing/selftests/bpf/progs/test_sockmap_update.cand its link target. That file was removed by commit5de7a6eaed89("selftests/bpf:
Drop tc/xdp/flow_dissector/socket_filter sockmap mutation tests").Signed-off-by Ahmad Wicaksono <[email protected]>---
Re: [PATCH bpf-next 1/2] Documentation/bpf: Update sockmap docs for mutation restrictions
In reply to Ahmad WicaksonoDocumentation/bpf/map_sockmap.rst The flags argument can be one of the following: · line 292
Quoted 5 lines · Ahmad Wicaksono
+.. note::
Documentation/bpf/map_sockmap.rst +4
-0+ The verifier only accepts this helper on a sockmap or sockhash from + ``BPF_PROG_TYPE_SK_REUSEPORT`` and ``BPF_PROG_TYPE_SK_LOOKUP`` + programs, and from ``BPF_PROG_TYPE_TRACING`` programs attached as + ``BPF_TRACE_ITER``. Other program types, such as tc, XDP,
This already not accurate after Michal's series narrowed BPF_TRACE_ITER to iter/sockmap:
https://lore.kernel.org/bpf/[email protected]/
Pls wait for bpf tree to make it to bpf-next and resend keeping acks.
pw-bot: cr
PATCH 2/2 Documentation/bpf: Fix stale selftests file references
In reply to Ahmad WicaksonoTwo selftests paths in the BPF docs no longer exist:
map_lpm_trie.rst points at tools/testing/selftests/bpf/test_lpm_map.c, which was moved by commit 3e18f5f1e5a1 ("selftests/bpf: Move test_lpm_map.c to map_tests") and now lives at tools/testing/selftests/bpf/map_tests/lpm_trie_map_basic_ops.c.
btf.rst points at tools/testing/selftests/bpf/test_xdp_noinline.c, which is now tools/testing/selftests/bpf/progs/test_xdp_noinline.c.
Update both so readers can find the code.
--- Documentation/bpf/btf.rst | 2 +- Documentation/bpf/map_lpm_trie.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-)
Documentation/bpf/btf.rst +1 -1
@@ -1148,7 +1148,7 @@ information.:: The following is an example of how line_info can help debugging verification failure.:: - /* The code at tools/testing/selftests/bpf/test_xdp_noinline.c + /* The code at tools/testing/selftests/bpf/progs/test_xdp_noinline.c * is modified as below. */ data = (void *)(long)xdp->data;
Documentation/bpf/map_lpm_trie.rst +3 -3
@@ -108,9 +108,9 @@ specific keys before less specific ones. Examples ======== -Please see ``tools/testing/selftests/bpf/test_lpm_map.c`` for examples -of LPM trie usage from userspace. The code snippets below demonstrate -API usage. +Please see ``tools/testing/selftests/bpf/map_tests/lpm_trie_map_basic_ops.c`` +for examples of LPM trie usage from userspace. The code snippets below +demonstrate API usage. Kernel BPF ----------
Signature · 1 line
2.43.0
Re: [PATCH bpf-next 2/2] Documentation/bpf: Fix stale selftests file references
Quoted 7 lines · Ahmad Wicaksono
Two selftests paths in the BPF docs no longer exist:
map_lpm_trie.rstpoints attools/testing/selftests/bpf/test_lpm_map.c, which was moved by commit3e18f5f1e5a1("selftests/bpf: Movetest_lpm_map.ctomap_tests") and now lives attools/testing/selftests/bpf/map_tests/lpm_trie_map_basic_ops.c.
Quoted 7 lines
btf.rstpoints attools/testing/selftests/bpf/test_xdp_noinline.c, which is nowtools/testing/selftests/bpf/progs/test_xdp_noinline.c.Update both so readers can find the code.
Signed-off-by Ahmad Wicaksono <[email protected]>---