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

[Bagas Sanjaya <bagasdotme@gmail.com>]

On Thu, Jun 30, 2022 at 01:04:09PM +0100, Dave Tucker wrote:
> 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.
> 

Use imperative mood instead of descriptive one for patch description.

> Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
> ---
>  Documentation/bpf/map_array.rst | 183 ++++++++++++++++++++++++++++++++
>  1 file changed, 183 insertions(+)
>  create mode 100644 Documentation/bpf/map_array.rst
> 
> diff --git a/Documentation/bpf/map_array.rst b/Documentation/bpf/map_array.rst
> new file mode 100644
> index 000000000000..eadc714591d2
> --- /dev/null
> +++ b/Documentation/bpf/map_array.rst
> @@ -0,0 +1,183 @@
> +.. 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
> +

nit: s/Kernel/kernel/

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

same nit above

> +Examples
> +========
> +
> +Please see the `tools/testing/selftests/bpf`_ directory for functional examples.
> +This sample code simply demonstrates the API.

Shouldn't the examples in this doc be put somewhere else in the tree? Or
where do they come from?

> +
> +.. section links
> +.. _tools/testing/selftests/bpf:
> +   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf

I think the link isn't needed, since kernel developers will simply look at
their own tree instead.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara