doc: update/correct eBPF doc on map creation

based on feedback from Alexei and Daniel Borkmann

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

kernel/Documentation/bpf/ebpf_maps.rst

@@ -28,27 +28,50 @@ Creating a map
 
 A map is created based on a request from userspace, via the `bpf`_
 syscall (`bpf_cmd`_ BPF_MAP_CREATE), which returns a new file descriptor
-that refers to the map. These are the setup arguments to use when
-creating a map.
+that refers to the map.  On error, -1 is returned and errno is set to
+EINVAL, EPERM, or ENOMEM. These are the struct ``bpf_attr`` setup
+arguments to use when creating a map via the syscall:
 
 .. code-block:: c
 
+ bpf(BPF_MAP_CREATE, &bpf_attr, sizeof(bpf_attr));
+
+Notice how this kernel ABI is extensible, as more struct arguments can
+easily be added later as the sizeof(bpf_attr) is passed along to the
+syscall.  This also implies that API users must clear/zero
+sizeof(bpf_attr), as compiler can size-align the struct differently,
+to avoid garbage data to be interpreted as parameters by future
+kernels.
+
+.. code-block:: c
+
+ union bpf_attr {
   struct { /* anonymous struct used by BPF_MAP_CREATE command */
          __u32   map_type;       /* one of enum bpf_map_type */
          __u32   key_size;       /* size of key in bytes */
          __u32   value_size;     /* size of value in bytes */
          __u32   max_entries;    /* max number of entries in a map */
          __u32   map_flags;      /* prealloc or not */
   };
-
-For programs under samples/bpf/ the ``load_bpf_file()`` call (from
-`samples/bpf/bpf_load`_) takes care of parsing elf file compiled by
-LLVM, pickups 'maps' section and creates maps via BPF syscall.  This is
-done by defining a ``struct bpf_map_def`` with an elf section
-__attribute__ ``SEC("maps")``, in the xxx_kern.c file.  The maps file
-descriptor is available in the userspace xxx_user.c file, via global
-array variable ``map_fd[]``, and the array map index corresponds to the
-order the maps sections were defined in elf file of xxx_kern.c file.
+ }
+
+Kernel sample/bpf ELF convention
+--------------------------------
+
+For programs under samples/bpf/, defining a map have been integrated
+with ELF binary generated by LLVM.  This is purely one example of a
+userspace convention and not part of the kernel ABI.  It still invokes
+the bpf syscall.
+
+Map definitions are done by defining a ``struct bpf_map_def`` with an
+elf section __attribute__ ``SEC("maps")``, in the xxx_kern.c file.
+The maps file descriptor is available in the userspace xxx_user.c
+file, via global array variable ``map_fd[]``, and the array map index
+corresponds to the order the maps sections were defined in elf file of
+xxx_kern.c file.  Behind the scenes it is the ``load_bpf_file()`` call
+(from `samples/bpf/bpf_load`_) that takes care of parsing ELF file
+compiled by LLVM, pickup 'maps' section and creates maps via BPF
+syscall.
 
 .. code-block:: c
 
@@ -68,9 +91,23 @@ order the maps sections were defined in elf file of xxx_kern.c file.
 	.map_flags   = 0
   };
 
+.. section links
+
 .. _samples/bpf/bpf_load:
    https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/samples/bpf/bpf_load.c
 
+Qdisc Traffic Control convention
+--------------------------------
+
+It is worth mentioning, that qdisc TC (Traffic Control), also use ELF
+files for defining the maps, but it uses another layout.  See man-page
+`tc-bpf(8)`_ and `tc bpf examples`_ in iproute2.git_ tree.
+
+.. _iproute2.git:
+   https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/about/
+
+.. _tc bpf examples:
+   https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/tree/examples/bpf
 
 Interacting with maps
 =====================
@@ -226,6 +263,8 @@ when updating the value in-place.
 
 .. _bpf: http://man7.org/linux/man-pages/man2/bpf.2.html
 
+.. _tc-bpf(8): http://man7.org/linux/man-pages/man8/tc-bpf.8.html
+
 .. _bpf_map_type:
    http://lxr.free-electrons.com/source/tools/include/uapi/linux/bpf.h?v=4.9#L78