* [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable
@ 2022-10-12 15:27 Donald Hunter
2022-10-13 4:13 ` Bagas Sanjaya
2022-10-21 2:00 ` patchwork-bot+netdevbpf
0 siblings, 2 replies; 4+ messages in thread
From: Donald Hunter @ 2022-10-12 15:27 UTC (permalink / raw)
To: bpf, linux-doc; +Cc: Donald Hunter
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)`_.
+
+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
--
2.35.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable
2022-10-12 15:27 [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable Donald Hunter
@ 2022-10-13 4:13 ` Bagas Sanjaya
2022-10-18 14:45 ` Donald Hunter
2022-10-21 2:00 ` patchwork-bot+netdevbpf
1 sibling, 1 reply; 4+ messages in thread
From: Bagas Sanjaya @ 2022-10-13 4:13 UTC (permalink / raw)
To: Donald Hunter; +Cc: bpf, linux-doc
[-- Attachment #1: Type: text/plain, Size: 1863 bytes --]
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.
--
An old man doll... just what I always wanted! - Clara
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable
2022-10-13 4:13 ` Bagas Sanjaya
@ 2022-10-18 14:45 ` Donald Hunter
0 siblings, 0 replies; 4+ messages in thread
From: Donald Hunter @ 2022-10-18 14:45 UTC (permalink / raw)
To: Bagas Sanjaya; +Cc: bpf, linux-doc
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable
2022-10-12 15:27 [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable Donald Hunter
2022-10-13 4:13 ` Bagas Sanjaya
@ 2022-10-21 2:00 ` patchwork-bot+netdevbpf
1 sibling, 0 replies; 4+ messages in thread
From: patchwork-bot+netdevbpf @ 2022-10-21 2:00 UTC (permalink / raw)
To: Donald Hunter; +Cc: bpf, linux-doc
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!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2022-10-21 2:00 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-10-12 15:27 [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable Donald Hunter
2022-10-13 4:13 ` Bagas Sanjaya
2022-10-18 14:45 ` Donald Hunter
2022-10-21 2:00 ` patchwork-bot+netdevbpf
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).