Fix Navigation Issues in Docs
Subsystems (3)
cover Fix Navigation Issues in Docs
This patch set fixes a couple of documentation issues that was causing some strange behaviour when the sidebar was rendered in the HTML docs.
1. The underlines in the BTF document weren't following the docs guidelines, which I believe caused an issue rendering the TOC with my other patches applied
2. Mixing the Sphix toctree with named sections was causing name stutter in the sidebar navigation. For example:
| BPF Type Format
| - BPF Type Format
3. The libbpf API documentation wasn't referenced in a toctree
It also renames bpf_lsm.rst to prog_lsm.rst such that documentation for program types can be included in the toctree via glob for prog_*
Dave Tucker (3):
docs: change underline in btf to match style guide
docs: Rename bpf_lsm.rst to prog_lsm.rst
docs: fix ordering of bpf documentation
Documentation/bpf/btf.rst | 44 ++++-----
Documentation/bpf/faq.rst | 11 +++
Documentation/bpf/helpers.rst | 7 ++
Documentation/bpf/index.rst | 97 +++----------------
Documentation/bpf/libbpf/index.rst | 4 +-
Documentation/bpf/maps.rst | 9 ++
Documentation/bpf/other.rst | 9 ++
.../bpf/{bpf_lsm.rst => prog_lsm.rst} | 0
Documentation/bpf/programs.rst | 9 ++
Documentation/bpf/syscall_api.rst | 11 +++
Documentation/bpf/test_debug.rst | 9 ++
MAINTAINERS | 2 +-
12 files changed, 103 insertions(+), 109 deletions(-)
create mode 100644 Documentation/bpf/faq.rst
create mode 100644 Documentation/bpf/helpers.rst
create mode 100644 Documentation/bpf/maps.rst
create mode 100644 Documentation/bpf/other.rst
rename Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} (100%)
create mode 100644 Documentation/bpf/programs.rst
create mode 100644 Documentation/bpf/syscall_api.rst
create mode 100644 Documentation/bpf/test_debug.rstSignature · 1 line
2.33.1
PATCH 1/3 docs: change underline in btf to match style guide
This changes the type of underline used to follow the guidelines in Documentation/doc-guide/sphinx.rst which also ensures that the headings are rendered at the correct level in the HTML sidebar
--- Documentation/bpf/btf.rst | 44 +++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 22 deletions(-)
Documentation/bpf/btf.rst +22 -22
@@ -3,7 +3,7 @@ BPF Type Format (BTF) ===================== 1. Introduction -*************** +=============== BTF (BPF Type Format) is the metadata format which encodes the debug info related to BPF program/map. The name BTF was used initially to describe data
@@ -30,7 +30,7 @@ sections are discussed in details in :ref:`BTF_Type_String`. .. _BTF_Type_String: 2. BTF Type and String Encoding -******************************* +=============================== The file ``include/uapi/linux/btf.h`` provides high-level definition of how types/strings are encoded.
@@ -57,13 +57,13 @@ little-endian target. The ``btf_header`` is designed to be extensible with generated. 2.1 String Encoding -=================== +------------------- The first string in the string section must be a null string. The rest of string table is a concatenation of other null-terminated strings. 2.2 Type Encoding -================= +----------------- The type id ``0`` is reserved for ``void`` type. The type section is parsed sequentially and type id is assigned to each recognized type starting from id
@@ -504,7 +504,7 @@ valid index (starting from 0) pointing to a member or an argument. * ``type``: the type with ``btf_type_tag`` attribute 3. BTF Kernel API -***************** +================= The following bpf syscall command involves BTF: * BPF_BTF_LOAD: load a blob of BTF data into kernel
@@ -547,14 +547,14 @@ The workflow typically looks like: 3.1 BPF_BTF_LOAD -================ +---------------- Load a blob of BTF data into kernel. A blob of data, described in :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd`` is returned to a userspace. 3.2 BPF_MAP_CREATE -================== +------------------ A map can be created with ``btf_fd`` and specified key/value type id.::
@@ -581,7 +581,7 @@ automatically. .. _BPF_Prog_Load: 3.3 BPF_PROG_LOAD -================= +----------------- During prog_load, func_info and line_info can be passed to kernel with proper values for the following attributes:
@@ -631,7 +631,7 @@ For line_info, the line number and column number are defined as below: #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff) 3.4 BPF_{PROG,MAP}_GET_NEXT_ID -============================== +------------------------------ In kernel, every loaded program, map or btf has a unique id. The id won't change during the lifetime of a program, map, or btf.
@@ -641,13 +641,13 @@ each command, to user space, for bpf program or maps, respectively, so an inspection tool can inspect all programs and maps. 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID -=============================== +------------------------------- An introspection tool cannot use id to get details about program or maps. A file descriptor needs to be obtained first for reference-counting purpose. 3.6 BPF_OBJ_GET_INFO_BY_FD -========================== +-------------------------- Once a program/map fd is acquired, an introspection tool can get the detailed information from kernel about this fd, some of which are BTF-related. For
@@ -656,7 +656,7 @@ example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids. bpf byte codes, and jited_line_info. 3.7 BPF_BTF_GET_FD_BY_ID -======================== +------------------------ With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with
@@ -668,10 +668,10 @@ tool has full btf knowledge and is able to pretty print map key/values, dump func signatures and line info, along with byte/jit codes. 4. ELF File Format Interface -**************************** +============================ 4.1 .BTF section -================ +---------------- The .BTF section contains type and string data. The format of this section is same as the one describe in :ref:`BTF_Type_String`.
@@ -679,7 +679,7 @@ same as the one describe in :ref:`BTF_Type_String`. .. _BTF_Ext_Section: 4.2 .BTF.ext section -==================== +-------------------- The .BTF.ext section encodes func_info and line_info which needs loader manipulation before loading into the kernel.
@@ -743,7 +743,7 @@ bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the beginning of section (``btf_ext_info_sec->sec_name_off``). 4.2 .BTF_ids section -==================== +-------------------- The .BTF_ids section encodes BTF ID values that are used within the kernel.
@@ -804,10 +804,10 @@ All the BTF ID lists and sets are compiled in the .BTF_ids section and resolved during the linking phase of kernel build by ``resolve_btfids`` tool. 5. Using BTF -************ +============ 5.1 bpftool map pretty print -============================ +---------------------------- With BTF, the map key/value can be printed based on fields rather than simply raw bytes. This is especially valuable for large structure or if your data
@@ -849,7 +849,7 @@ bpftool is able to pretty print like below: ] 5.2 bpftool prog dump -===================== +--------------------- The following is an example showing how func_info and line_info can help prog dump with better kernel symbol names, function prototypes and line
@@ -883,7 +883,7 @@ information.:: [...] 5.3 Verifier Log -================ +---------------- The following is an example of how line_info can help debugging verification failure.::
@@ -909,7 +909,7 @@ failure.:: R2 offset is outside of the packet 6. BTF Generation -***************** +================= You need latest pahole
@@ -1016,6 +1016,6 @@ format.:: .long 8206 # Line 8 Col 14 7. Testing -********** +========== Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests.
Signature · 1 line
2.33.1
PATCH 2/3 docs: Rename bpf_lsm.rst to prog_lsm.rst
In reply to Dave TuckerThis allows for documentation relating to BPF Program Types to be matched by the glob pattern prog_* for inclusion in a sphinx toctree
---
Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} | 0
MAINTAINERS | 2 +-
2 files changed, 1 insertion(+), 1 deletion(-)
rename Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} (100%)Documentation/bpf/prog_lsm.rst renamed from Documentation/bpf/bpf_lsm.rst +0 -0
MAINTAINERS +1 -1
@@ -3529,7 +3529,7 @@ R: Florent Revest <[email protected]> R: Brendan Jackman <[email protected]> L: [email protected] S: Maintained -F: Documentation/bpf/bpf_lsm.rst +F: Documentation/bpf/prog_lsm.rst F: include/linux/bpf_lsm.h F: kernel/bpf/bpf_lsm.c F: security/bpf/
Signature · 1 line
2.33.1
PATCH 3/3 docs: fix ordering of bpf documentation
In reply to Dave TuckerThis commit fixes the display of the BPF documentation in the sidebar when rendered as HTML.
Before this patch, the sidebar would render as follows for some sections:
| BPF Documentation
|- BPF Type Format (BTF)
|- BPF Type Format (BTF)
This was due to creating a heading in index.rst followed by a sphinx toctree, where the file referenced carries the same title as the section heading.
To fix this I applied a pattern that has been established in other subfolders of Documentation:
1. Re-wrote index.rst to have a single toctree
2. Split the sections out in to their own files
Additionally maps.rst and programs.rst make use of a glob pattern to include map_* or prog_* rst files in their toctree, meaning future map or program type documentation will be automatically included.
--- Documentation/bpf/faq.rst | 11 ++++ Documentation/bpf/helpers.rst | 7 +++ Documentation/bpf/index.rst | 97 ++++-------------------------- Documentation/bpf/libbpf/index.rst | 4 +- Documentation/bpf/maps.rst | 9 +++ Documentation/bpf/other.rst | 9 +++ Documentation/bpf/programs.rst | 9 +++ Documentation/bpf/syscall_api.rst | 11 ++++ Documentation/bpf/test_debug.rst | 9 +++ 9 files changed, 80 insertions(+), 86 deletions(-) create mode 100644 Documentation/bpf/faq.rst create mode 100644 Documentation/bpf/helpers.rst create mode 100644 Documentation/bpf/maps.rst create mode 100644 Documentation/bpf/other.rst create mode 100644 Documentation/bpf/programs.rst create mode 100644 Documentation/bpf/syscall_api.rst create mode 100644 Documentation/bpf/test_debug.rst
Documentation/bpf/faq.rst new file +11 -0
@@ -0,0 +1,11 @@ +================================ +Frequently asked questions (FAQ) +================================ + +Two sets of Questions and Answers (Q&A) are maintained. + +.. toctree:: + :maxdepth: 1 + + bpf_design_QA + bpf_devel_QA
Documentation/bpf/helpers.rst new file +7 -0
@@ -0,0 +1,7 @@ +Helper functions +================ + +* `bpf-helpers(7)`_ maintains a list of helpers available to eBPF programs. + +.. Links +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
Documentation/bpf/index.rst +13 -84
111 lines not on this page · raw message
Documentation/bpf/libbpf/index.rst +2 -2
@@ -3,8 +3,6 @@ libbpf ====== -For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_. - .. toctree:: :maxdepth: 1
@@ -14,6 +12,8 @@ For API documentation see the `versioned API documentation site <https://libbpf. This is documentation for libbpf, a userspace library for loading and interacting with bpf programs. +For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_. + All general BPF questions, including kernel functionality, libbpf APIs and their application, should be sent to [email protected] mailing list. You can `subscribe <http://vger.kernel.org/vger-lists.html#bpf>`_ to the
Documentation/bpf/maps.rst new file +9 -0
@@ -0,0 +1,9 @@ +========= +Map Types +========= + +.. toctree:: + :maxdepth: 1 + :glob: + + map_*
Documentation/bpf/other.rst new file +9 -0
@@ -0,0 +1,9 @@ +===== +Other +===== + +.. toctree:: + :maxdepth: 1 + + ringbuf + llvm_reloc
Documentation/bpf/programs.rst new file +9 -0
@@ -0,0 +1,9 @@ +============= +Program Types +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + prog_*
Documentation/bpf/syscall_api.rst new file +11 -0
@@ -0,0 +1,11 @@ +=========== +Syscall API +=========== + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. For more information about the userspace API, see +Documentation/userspace-api/ebpf/index.rst. + +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
Documentation/bpf/test_debug.rst new file +9 -0
@@ -0,0 +1,9 @@ +========================= +Testing and debugging BPF +========================= + +.. toctree:: + :maxdepth: 1 + + drgn + s390
Signature · 1 line
2.33.1
Re: [PATCH bpf-next 2/3] docs: Rename bpf_lsm.rst to prog_lsm.rst
In reply to Dave TuckerQuoted 20 lines · Dave Tucker
This allows for documentation relating to BPF Program Types to be matched by the glob pattern prog_* for inclusion in a sphinx toctree
Signed-off-by Dave Tucker <[email protected]>--- Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} | 0 MAINTAINERS | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} (100%)Documentation/bpf/prog_lsm.rst renamed from Documentation/bpf/bpf_lsm.rst +0
-0MAINTAINERS +0
-0
MAINTAINERS R: Florent Revest <[email protected]>
Quoted 9 lines
MAINTAINERS +1
-2@@ -3529,7 +3529,7 @@ R: Florent Revest <[email protected]> R: Brendan Jackman <[email protected]> L: [email protected] S: Maintained -F: Documentation/bpf/bpf_lsm.rst +F: Documentation/bpf/prog_lsm.rst F: include/linux/bpf_lsm.h F: kernel/bpf/bpf_lsm.c F: security/bpf/ --
This series was applied to bpf/bpf-next.git (master) by Daniel Borkmann <[email protected]>:
Hello:
This series was applied to bpf/bpf-next.git (master) by Daniel Borkmann <[email protected]>:
Quoted 10 lines · On Fri, 12 Nov 2021 21:17:21 +0000 you wrote:
This patch set fixes a couple of documentation issues that was causing some strange behaviour when the sidebar was rendered in the HTML docs.
1. The underlines in the BTF document weren't following the docs guidelines, which I believe caused an issue rendering the TOC with my other patches applied
2. Mixing the Sphix toctree with named sections was causing name stutter in the sidebar navigation. For example:[...]
Here is the summary with links:
- [bpf-next,1/3] docs: change underline in btf to match style guide
https://git.kernel.org/bpf/bpf-next/c/3ff36bffaf35 - [bpf-next,2/3] docs: Rename bpf_lsm.rst to prog_lsm.rst https://git.kernel.org/bpf/bpf-next/c/f5b1c2ef43d7 - [bpf-next,3/3] docs: fix ordering of bpf documentation https://git.kernel.org/bpf/bpf-next/c/5931d9a3d052
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html