On Tue, 7 Dec 2021, at 14:53, Jonathan Corbet wrote: > Dave Tucker <dave@xxxxxxxxxxxxx> writes: > >> This commit adds documentation for the BPF_MAP_TYPE_ARRAY including >> kernel version introduced, usage and examples. >> It also documents BPF_MAP_TYPE_PERCPU_ARRAY since this is similar. >> >> Signed-off-by: Dave Tucker <dave@xxxxxxxxxxxxx> >> --- >> Documentation/bpf/map_array.rst | 182 ++++++++++++++++++++++++++++++++ >> 1 file changed, 182 insertions(+) >> create mode 100644 Documentation/bpf/map_array.rst > > When you add a new file, you need to add it to index.rst as well to > bring it into the docs build. I believe I responded to this comment in an earlier version of this patch set. The glob pattern in Documentaion/bpf/maps.rst includes this in the docs build. >> diff --git a/Documentation/bpf/map_array.rst b/Documentation/bpf/map_array.rst >> new file mode 100644 >> index 000000000000..7ed5f7654ee8 >> --- /dev/null >> +++ b/Documentation/bpf/map_array.rst >> @@ -0,0 +1,182 @@ >> +.. SPDX-License-Identifier: GPL-2.0-only >> +.. Copyright (C) 2021 Red Hat, Inc. >> + >> +================================================ >> +BPF_MAP_TYPE_ARRAY and BPF_MAP_TYPE_PERCPU_ARRAY >> +================================================ >> + >> +.. note:: ``BPF_MAP_TYPE_ARRAY`` was introduced in Kernel version 3.19 and >> + ``BPF_MAP_TYPE_PERCPU_ARRAY`` in version 4.6 >> + >> +``BPF_MAP_TYPE_ARRAY`` and ``BPF_MAP_TYPE_PERCPU_ARRAY`` provide generic array >> +storage. The key type is an unsigned 32-bit integer (4 bytes) and the map is of >> +constant size. All array elements are pre-allocated and zero initialized when >> +created. ``BPF_MAP_TYPE_PERCPU_ARRAY`` uses a different memory region for each >> +CPU whereas ``BPF_MAP_TYPE_ARRAY`` uses the same memory region. The maximum >> +size of an array, defined in max_entries, is limited to 2^32. The value stored >> +can be of any size, however, small values will be rounded up to 8 bytes. >> + >> +Since Kernel 5.4, memory mapping may be enabled for ``BPF_MAP_TYPE_ARRAY`` by >> +setting the flag ``BPF_F_MMAPABLE``. The map definition is page-aligned and >> +starts on the first page. Sufficient page-sized and page-aligned blocks of >> +memory are allocated to store all array values, starting on the second page, >> +which in some cases will result in over-allocation of memory. The benefit of >> +using this is increased performance and ease of use since userspace programs >> +would not be required to use helper functions to access and mutate data. >> + >> +Usage >> +===== >> + >> +Array elements can be retrieved using the ``bpf_map_lookup_elem()`` helper. > > It's really better not to use ``literal markup`` for function names. > Just write function() and the right thing will happen, including > cross-reference links to the kerneldoc for that function if it exists. I've just tested this out, and for some reason it's not working as expected. It's not formatted as ``literal markup`` nor is it linked to kerneldoc. Perhaps because the issue is because these are part of tools/lib/bpf/bpf_helpers.h? I also noticed I introduced a warning due to missing a newline after a code block :( I'll fix that and push a v4, but will wait for confirmation on the use of `` for the helper functions. - Dave > Thanks, > > jon
