Skip to contentSkip to conversation

Documentation/bpf: Fix stale references in map docs

PATCH In review Ahmad Wicaksono 3 participants 6 messages Nov 14 – Nov 17

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 2d630686a00..8bb6d74cf36 100644
@@ -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
Reviewed-by on v1 1/2
#2 lore raw

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_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.

Quoted 7 lines

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").

---

#3 lore raw

Re: [PATCH bpf-next 1/2] Documentation/bpf: Update sockmap docs for mutation restrictions

In reply to Ahmad Wicaksono

Documentation/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

#4 lore raw

PATCH 2/2 Documentation/bpf: Fix stale selftests file references

In reply to Ahmad Wicaksono

Two 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
index b618812390e..94a81a9e99b 100644
@@ -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
index f9cd579496c..37ef39d0b39 100644
@@ -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
Reviewed-by on v1 2/2
#5 lore raw

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.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.

Quoted 7 lines

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.

---