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. > 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. Thanks, jon
