| Message ID | 20221012152715.25073-1-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | fb73a20ebe15b16dee68e226ec82f8e55c4d64f9 |
| Delegated to: | BPF |
| Headers | show |
| Series | [bpf-next,v1] bpf, docs: Reformat BPF maps page to be more readable | expand |
On Wed, Oct 12, 2022 at 04:27:15PM +0100, Donald Hunter wrote: > Add a more complete introduction, with links to man pages. > Move toctree of map types above usage notes. > Format usage notes to improve readability. > > Signed-off-by: Donald Hunter <donald.hunter@gmail.com> > --- > Documentation/bpf/maps.rst | 101 ++++++++++++++++++++++++------------- > 1 file changed, 65 insertions(+), 36 deletions(-) > > diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst > index f41619e312ac..4906ff0f8382 100644 > --- a/Documentation/bpf/maps.rst > +++ b/Documentation/bpf/maps.rst > @@ -1,52 +1,81 @@ > > -========= > -eBPF maps > +======== > +BPF maps > +======== > + > +BPF 'maps' provide generic storage of different types for sharing data between > +kernel and user space. There are several storage types available, including > +hash, array, bloom filter and radix-tree. Several of the map types exist to > +support specific BPF helpers that perform actions based on the map contents. The > +maps are accessed from BPF programs via BPF helpers which are documented in the > +`man-pages`_ for `bpf-helpers(7)`_. > + > +BPF maps are accessed from user space via the ``bpf`` syscall, which provides > +commands to create maps, lookup elements, update elements and delete > +elements. More details of the BPF syscall are available in > +:doc:`/userspace-api/ebpf/syscall` and in the `man-pages`_ for `bpf(2)`_. > <snipped>... > +.. Links: > +.. _man-pages: https://www.kernel.org/doc/man-pages/ > +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html > +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html I think you can just write "see :manpage:`bpf(2)`" without linking to external site. Otherwise LGTM.
Bagas Sanjaya <bagasdotme@gmail.com> writes: > On Wed, Oct 12, 2022 at 04:27:15PM +0100, Donald Hunter wrote: >> Add a more complete introduction, with links to man pages. >> Move toctree of map types above usage notes. >> Format usage notes to improve readability. >> >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> >> --- >> Documentation/bpf/maps.rst | 101 ++++++++++++++++++++++++------------- >> 1 file changed, 65 insertions(+), 36 deletions(-) >> >> diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst >> index f41619e312ac..4906ff0f8382 100644 >> --- a/Documentation/bpf/maps.rst >> +++ b/Documentation/bpf/maps.rst >> @@ -1,52 +1,81 @@ >> >> -========= >> -eBPF maps >> +======== >> +BPF maps >> +======== >> + >> +BPF 'maps' provide generic storage of different types for sharing data between >> +kernel and user space. There are several storage types available, including >> +hash, array, bloom filter and radix-tree. Several of the map types exist to >> +support specific BPF helpers that perform actions based on the map contents. The >> +maps are accessed from BPF programs via BPF helpers which are documented in the >> +`man-pages`_ for `bpf-helpers(7)`_. >> + >> +BPF maps are accessed from user space via the ``bpf`` syscall, which provides >> +commands to create maps, lookup elements, update elements and delete >> +elements. More details of the BPF syscall are available in >> +:doc:`/userspace-api/ebpf/syscall` and in the `man-pages`_ for `bpf(2)`_. >> <snipped>... >> +.. Links: >> +.. _man-pages: https://www.kernel.org/doc/man-pages/ >> +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html >> +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html > > I think you can just write "see :manpage:`bpf(2)`" without linking to > external site. I tried your suggestion but it just renders italicized text. I think it is more helpful to provide a clickable link to the relevant man page. Other documentation pages already provide clickable manpage links and I followed existing practise from Documentation/bpf/syscall_api.rst I would prefer to keep the clickable links. > Otherwise LGTM.
Hello: This patch was applied to bpf/bpf-next.git (master) by Alexei Starovoitov <ast@kernel.org>: On Wed, 12 Oct 2022 16:27:15 +0100 you wrote: > Add a more complete introduction, with links to man pages. > Move toctree of map types above usage notes. > Format usage notes to improve readability. > > Signed-off-by: Donald Hunter <donald.hunter@gmail.com> > --- > Documentation/bpf/maps.rst | 101 ++++++++++++++++++++++++------------- > 1 file changed, 65 insertions(+), 36 deletions(-) Here is the summary with links: - [bpf-next,v1] bpf, docs: Reformat BPF maps page to be more readable https://git.kernel.org/bpf/bpf-next/c/fb73a20ebe15 You are awesome, thank you!
diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst index f41619e312ac..4906ff0f8382 100644 --- a/Documentation/bpf/maps.rst +++ b/Documentation/bpf/maps.rst @@ -1,52 +1,81 @@ -========= -eBPF maps +======== +BPF maps +======== + +BPF 'maps' provide generic storage of different types for sharing data between +kernel and user space. There are several storage types available, including +hash, array, bloom filter and radix-tree. Several of the map types exist to +support specific BPF helpers that perform actions based on the map contents. The +maps are accessed from BPF programs via BPF helpers which are documented in the +`man-pages`_ for `bpf-helpers(7)`_. + +BPF maps are accessed from user space via the ``bpf`` syscall, which provides +commands to create maps, lookup elements, update elements and delete +elements. More details of the BPF syscall are available in +:doc:`/userspace-api/ebpf/syscall` and in the `man-pages`_ for `bpf(2)`_. + +Map Types ========= -'maps' is a generic storage of different types for sharing data between kernel -and userspace. +.. toctree:: + :maxdepth: 1 + :glob: -The maps are accessed from user space via BPF syscall, which has commands: + map_* -- create a map with given type and attributes - ``map_fd = bpf(BPF_MAP_CREATE, union bpf_attr *attr, u32 size)`` - using attr->map_type, attr->key_size, attr->value_size, attr->max_entries - returns process-local file descriptor or negative error +Usage Notes +=========== -- lookup key in a given map - ``err = bpf(BPF_MAP_LOOKUP_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key, attr->value - returns zero and stores found elem into value or negative error +.. c:function:: + int bpf(int command, union bpf_attr *attr, u32 size) -- create or update key/value pair in a given map - ``err = bpf(BPF_MAP_UPDATE_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key, attr->value - returns zero or negative error +Use the ``bpf()`` system call to perform the operation specified by +``command``. The operation takes parameters provided in ``attr``. The ``size`` +argument is the size of the ``union bpf_attr`` in ``attr``. -- find and delete element by key in a given map - ``err = bpf(BPF_MAP_DELETE_ELEM, union bpf_attr *attr, u32 size)`` - using attr->map_fd, attr->key +**BPF_MAP_CREATE** -- to delete map: close(fd) - Exiting process will delete maps automatically +Create a map with the desired type and attributes in ``attr``: -userspace programs use this syscall to create/access maps that eBPF programs -are concurrently updating. +.. code-block:: c -maps can have different types: hash, array, bloom filter, radix-tree, etc. + int fd; + union bpf_attr attr = { + .map_type = BPF_MAP_TYPE_ARRAY; /* mandatory */ + .key_size = sizeof(__u32); /* mandatory */ + .value_size = sizeof(__u32); /* mandatory */ + .max_entries = 256; /* mandatory */ + .map_flags = BPF_F_MMAPABLE; + .map_name = "example_array"; + }; -The map is defined by: + fd = bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); - - type - - max number of elements - - key size in bytes - - value size in bytes +Returns a process-local file descriptor on success, or negative error in case of +failure. The map can be deleted by calling ``close(fd)``. Maps held by open +file descriptors will be deleted automatically when a process exits. -Map Types -========= +.. note:: Valid characters for ``map_name`` are ``A-Z``, ``a-z``, ``0-9``, + ``'_'`` and ``'.'``. -.. toctree:: - :maxdepth: 1 - :glob: +**BPF_MAP_LOOKUP_ELEM** + +Lookup key in a given map using ``attr->map_fd``, ``attr->key``, +``attr->value``. Returns zero and stores found elem into ``attr->value`` on +success, or negative error on failure. + +**BPF_MAP_UPDATE_ELEM** + +Create or update key/value pair in a given map using ``attr->map_fd``, ``attr->key``, +``attr->value``. Returns zero on success or negative error on failure. + +**BPF_MAP_DELETE_ELEM** + +Find and delete element by key in a given map using ``attr->map_fd``, +``attr->key``. Returns zero on success or negative error on failure. - map_* \ No newline at end of file +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
Add a more complete introduction, with links to man pages. Move toctree of map types above usage notes. Format usage notes to improve readability. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> --- Documentation/bpf/maps.rst | 101 ++++++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 36 deletions(-)