Re: [PATCH v3 bpf-next 2/2] bpf, docs: document BPF_MAP_TYPE_ARRAY

["Dave Tucker" <dave@dtucker.co.uk>]

On Tue, 7 Dec 2021, at 14:53, Jonathan Corbet wrote:
> Dave Tucker <dave@dtucker.co.uk> 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@dtucker.co.uk>
>> ---
>>  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