doc: ebpf maps implementation details

Implementation details section moved to ebpf_maps_types.rst
and improved.

Signed-off-by: Jesper Dangaard Brouer <brouer@redhat.com>

kernel/Documentation/bpf/ebpf_maps.rst

@@ -29,6 +29,7 @@ and accessed by multiple programs (from man-page `bpf(2)`_):
  up to the user process and eBPF program to decide what they store
  inside maps.
 
+.. _`Creating a map`:
 
 Creating a map
 ==============
@@ -51,6 +52,8 @@ sizeof(bpf_attr), as compiler can size-align the struct differently,
 to avoid garbage data to be interpreted as parameters by future
 kernels.
 
+The following configuration attributes are needed when creating the map:
+
 .. code-block:: c
 
  union bpf_attr {
@@ -247,24 +250,6 @@ is understood by LLVM when generating eBPF instructions.
 .. _kernel/bpf/helpers.c:
    https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/kernel/bpf/helpers.c
 
-
-Kernel map implementation
--------------------------
-
-It might be useful to understand how the kernel implement a map type,
-in-order to help choosing the right type of map.
-
-On the kernel side, implementing a map type requires defining some
-function (pointers) via `struct bpf_map_ops`_.  And eBPF programs have
-access to ``map_lookup_elem``, ``map_update_elem`` and
-``map_delete_elem``, which get invoked from eBPF via bpf-helpers in
-`kernel/bpf/helpers.c`_.
-
-.. section links
-
-.. _struct bpf_map_ops: http://lxr.free-electrons.com/ident?i=bpf_map_ops
-
-
 .. links
 
 .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html

kernel/Documentation/bpf/ebpf_maps_types.rst

@@ -34,9 +34,38 @@ but remember to `lookup latest`_ available maps in the source code.
 .. _lookup latest:
    http://lxr.free-electrons.com/ident?i=bpf_map_type
 
+Implementation details
+======================
+
+In-order to understand and follow the descriptions of the different
+map types, in is useful for the reader to understand how a map type is
+implemented by the kernel.
+
+On the kernel side, implementing a map type requires defining some
+function call (pointers) via `struct bpf_map_ops`_.  The eBPF programs
+(and userspace) have access to the functions calls
+``map_lookup_elem``, ``map_update_elem`` and ``map_delete_elem``,
+which get invoked from eBPF via bpf-helpers in `kernel/bpf/helpers.c`_,
+or via userspace the bpf syscall (as described in :doc:`ebpf_maps`).
+
+:ref:`Creating a map` requires supplying the following configuration
+attributes: map_type, key_size, value_size, max_entries and map_flags.
+
+.. section links
+
+.. _struct bpf_map_ops: http://lxr.free-electrons.com/ident?i=bpf_map_ops
+
+.. _kernel/bpf/helpers.c:
+   https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/kernel/bpf/helpers.c
+
+
 BPF_MAP_TYPE_ARRAY
 ==================
 
+Implementation defined in `kernel/bpf/arraymap.c`_ via struct
+bpf_map_ops `array_ops`_.
+
+
 As the name ``BPF_MAP_TYPE_ARRAY`` indicates, this can be seen as an
 array.  All array elements are pre-allocated and zero initialized at
 init time.  Key is an index in array and can only be 4 bytes (32-bit).
@@ -49,8 +78,6 @@ life of the eBPF program, which allows verifier+JIT to perform a wider
 range of optimizations.  E.g. `array_map_lookup_elem()`_ may be
 'inlined' by JIT.
 
-To inspect kernel code look at bpf_map_ops `array_ops`_ in
-kernel/bpf/arraymap.c.
 
 Small size gotcha, the ``value_size`` is rounded up to 8 bytes.
 
@@ -78,6 +105,9 @@ when updating the value in-place.
 
 .. section links
 
+.. _kernel/bpf/arraymap.c:
+   http://lxr.free-electrons.com/source/kernel/bpf/arraymap.c
+
 .. _array_ops:
    http://lxr.free-electrons.com/ident?i=array_ops