docs/bpf: document BPF ARRAY_OF_MAPS and HASH_OF_MAPS
Subsystems (2)
PATCH v4 1/1 docs/bpf: document BPF ARRAY_OF_MAPS and HASH_OF_MAPS
Add documentation for the ARRAY_OF_MAPS and HASH_OF_MAPS map types, including usage and examples.
---
v3 -> v4:
- Fix typo in filename, as reported by Yonghong Song
- Add lookup to list of ops, as reported by Yonghong Song
- Clean up declaration in example, as reported by Yonghong Song
v2 -> v3:
- Update BPF example to show declarative initialisation, as suggested by Andrii Nakryiko
- Use LIBBPF_OPTS inline initialisation, as suggested by Andrii Nakryiko
- Fix duplicate label warning,
v1 -> v2:
- Fix formatting nits
- Tidy up code snippets as suggested by Maryam Tahhan
--- Documentation/bpf/map_of_maps.rst | 126 ++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 Documentation/bpf/map_of_maps.rst
Documentation/bpf/map_of_maps.rst new file +126 -0
@@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright (C) 2022 Red Hat, Inc. + +======================================================== +BPF_MAP_TYPE_ARRAY_OF_MAPS and BPF_MAP_TYPE_HASH_OF_MAPS +======================================================== + +.. note:: + - ``BPF_MAP_TYPE_ARRAY_OF_MAPS`` and ``BPF_MAP_TYPE_HASH_OF_MAPS`` were + introduced in kernel version 4.12 + +``BPF_MAP_TYPE_ARRAY_OF_MAPS`` and ``BPF_MAP_TYPE_HASH_OF_MAPS`` provide general +purpose support for map in map storage. One level of nesting is supported, where +an outer map contains instances of a single type of inner map, for example +``array_of_maps->sock_map``. + +When creating an outer map, an inner map instance is used to initialize the +metadata that the outer map holds about its inner maps. This inner map has a +separate lifetime from the outer map and can be deleted after the outer map has +been created. + +The outer map supports element lookup, update and delete from user space using +the syscall API. A BPF program is only allowed to do element lookup in the outer +map. + +.. note:: + - Multi-level nesting is not supported. + - Any BPF map type can be used as an inner map, except for + ``BPF_MAP_TYPE_PROG_ARRAY``. + - A BPF program cannot update or delete outer map entries. + +For ``BPF_MAP_TYPE_ARRAY_OF_MAPS`` the key is an unsigned 32-bit integer index +into the array. The array is a fixed size with ``max_entries`` elements that are +zero initialized when created. + +For ``BPF_MAP_TYPE_HASH_OF_MAPS`` the key type can be chosen when defining the +map. The kernel is responsible for allocating and freeing key/value pairs, up to +the max_entries limit that you specify. Hash maps use pre-allocation of hash +table elements by default. The ``BPF_F_NO_PREALLOC`` flag can be used to disable +pre-allocation when it is too memory expensive. + +Usage +===== + +Kernel BPF Helper +----------------- + +.. c:function:: + void *bpf_map_lookup_elem(struct bpf_map *map, const void *key) + +Inner maps can be retrieved using the ``bpf_map_lookup_elem()`` helper. This +helper returns a pointer to the inner map, or ``NULL`` if no entry was found. + +Examples +======== + +Kernel BPF Example +------------------ + +This snippet shows how to create and initialise an array of devmaps in a BPF +program. Note that the outer array can only be modified from user space using +the syscall API. + +.. code-block:: c + + struct inner_map { + __uint(type, BPF_MAP_TYPE_DEVMAP); + __uint(max_entries, 10); + __type(key, __u32); + __type(value, __u32); + } inner_map1 SEC(".maps"), inner_map2 SEC(".maps"); + + struct { + __uint(type, BPF_MAP_TYPE_ARRAY_OF_MAPS); + __uint(max_entries, 2); + __type(key, __u32); + __array(values, struct inner_map); + } outer_map SEC(".maps") = { + .values = { &inner_map1, + &inner_map2 } + }; + +See ``progs/test_btf_map_in_map.c`` in ``tools/testing/selftests/bpf`` for more +examples of declarative initialisation of outer maps. + +User Space +---------- + +This snippet shows how to create an array based outer map: + +.. code-block:: c + + int create_outer_array(int inner_fd) { + LIBBPF_OPTS(bpf_map_create_opts, opts, .inner_map_fd = inner_fd); + int fd; + + fd = bpf_map_create(BPF_MAP_TYPE_ARRAY_OF_MAPS, + "example_array", /* name */ + sizeof(__u32), /* key size */ + sizeof(__u32), /* value size */ + 256, /* max entries */ + &opts); /* create opts */ + return fd; + } + + +This snippet shows how to add an inner map to an outer map: + +.. code-block:: c + + int add_devmap(int outer_fd, int index, const char *name) { + int fd; + + fd = bpf_map_create(BPF_MAP_TYPE_DEVMAP, name, + sizeof(__u32), sizeof(__u32), 256, NULL); + if (fd < 0) + return fd; + + return bpf_map_update_elem(outer_fd, &index, &fd, BPF_ANY); + } + +References +========== + +- https://lore.kernel.org/netdev/[email protected]/ +- https://lore.kernel.org/netdev/[email protected]/
Signature · 1 line
2.35.1
Quoted 4 lines · Donald Hunter
Add documentation for the
ARRAY_OF_MAPSandHASH_OF_MAPSmap types, including usage and examples.Signed-off-by Donald Hunter <[email protected]>
This patch was applied to bpf/bpf-next.git (master) by Andrii Nakryiko <[email protected]>:
Hello:
This patch was applied to bpf/bpf-next.git (master) by Andrii Nakryiko <[email protected]>:
Quoted 11 lines · On Tue, 8 Nov 2022 10:22:15 +0000 you wrote:
Add documentation for the
ARRAY_OF_MAPSandHASH_OF_MAPSmap types, including usage and examples.Signed-off-by Donald Hunter <[email protected]>---
v3 -> v4:
- Fix typo in filename, as reported by Yonghong Song
- Add lookup to list of ops, as reported by Yonghong Song
- Clean up declaration in example, as reported by Yonghong Song[...]
Here is the summary with links:
- [bpf-next,v4] docs/bpf: document BPF ARRAY_OF_MAPS and HASH_OF_MAPS
https://git.kernel.org/bpf/bpf-next/c/f720b84811b2
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html