Bagas Sanjaya <bagasdotme@xxxxxxxxx> 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@xxxxxxxxx> >> --- >> 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.
