leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

bpf, docs: Change underline in btf to match style guide

Browse Source 
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

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
Link: https://lore.kernel.org/bpf/981b27485cc294206480df36fca46817e2553e39.1636749493.git.dave@dtucker.co.uk
This commit is contained in:
Dave Tucker
2021-11-12 21:17:22 +00:00
committed by Daniel Borkmann
parent db813d7bd9
commit 3ff36bffaf
1 changed files with 22 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
Documentation/bpf/btf.rst
View File

@@ -3,7 +3,7 @@ BPF Type Format (BTF)
===================== =====================
1. Introduction 1. Introduction
*************** ===============
BTF (BPF Type Format) is the metadata format which encodes the debug info 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 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: .. _BTF_Type_String:
2. BTF Type and String Encoding 2. BTF Type and String Encoding
******************************* ===============================
The file ``include/uapi/linux/btf.h`` provides high-level definition of how The file ``include/uapi/linux/btf.h`` provides high-level definition of how
types/strings are encoded. types/strings are encoded.
@@ -57,13 +57,13 @@ little-endian target. The ``btf_header`` is designed to be extensible with
generated. generated.
2.1 String Encoding 2.1 String Encoding
=================== -------------------
The first string in the string section must be a null string. The rest of 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. string table is a concatenation of other null-terminated strings.
2.2 Type Encoding 2.2 Type Encoding
================= -----------------
The type id ``0`` is reserved for ``void`` type. The type section is parsed 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 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 * ``type``: the type with ``btf_type_tag`` attribute
3. BTF Kernel API 3. BTF Kernel API
***************** =================
The following bpf syscall command involves BTF: The following bpf syscall command involves BTF:
* BPF_BTF_LOAD: load a blob of BTF data into kernel * 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 3.1 BPF_BTF_LOAD
================ ----------------
Load a blob of BTF data into kernel. A blob of data, described in 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`` :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd``
is returned to a userspace. is returned to a userspace.
3.2 BPF_MAP_CREATE 3.2 BPF_MAP_CREATE
================== ------------------
A map can be created with ``btf_fd`` and specified key/value type id.:: A map can be created with ``btf_fd`` and specified key/value type id.::
@@ -581,7 +581,7 @@ automatically.
.. _BPF_Prog_Load: .. _BPF_Prog_Load:
3.3 BPF_PROG_LOAD 3.3 BPF_PROG_LOAD
================= -----------------
During prog_load, func_info and line_info can be passed to kernel with proper During prog_load, func_info and line_info can be passed to kernel with proper
values for the following attributes: 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) #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff)
3.4 BPF_{PROG,MAP}_GET_NEXT_ID 3.4 BPF_{PROG,MAP}_GET_NEXT_ID
============================== ------------------------------
In kernel, every loaded program, map or btf has a unique id. The id won't 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. 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. inspection tool can inspect all programs and maps.
3.5 BPF_{PROG,MAP}_GET_FD_BY_ID 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID
=============================== -------------------------------
An introspection tool cannot use id to get details about program or maps. 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. A file descriptor needs to be obtained first for reference-counting purpose.
3.6 BPF_OBJ_GET_INFO_BY_FD 3.6 BPF_OBJ_GET_INFO_BY_FD
========================== --------------------------
Once a program/map fd is acquired, an introspection tool can get the detailed 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 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. bpf byte codes, and jited_line_info.
3.7 BPF_BTF_GET_FD_BY_ID 3.7 BPF_BTF_GET_FD_BY_ID
======================== ------------------------
With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf 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 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. func signatures and line info, along with byte/jit codes.
4. ELF File Format Interface 4. ELF File Format Interface
**************************** ============================
4.1 .BTF section 4.1 .BTF section
================ ----------------
The .BTF section contains type and string data. The format of this section is The .BTF section contains type and string data. The format of this section is
same as the one describe in :ref:`BTF_Type_String`. 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: .. _BTF_Ext_Section:
4.2 .BTF.ext section 4.2 .BTF.ext section
==================== --------------------
The .BTF.ext section encodes func_info and line_info which needs loader The .BTF.ext section encodes func_info and line_info which needs loader
manipulation before loading into the kernel. 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``). beginning of section (``btf_ext_info_sec->sec_name_off``).
4.2 .BTF_ids section 4.2 .BTF_ids section
==================== --------------------
The .BTF_ids section encodes BTF ID values that are used within the kernel. 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. resolved during the linking phase of kernel build by ``resolve_btfids`` tool.
5. Using BTF 5. Using BTF
************ ============
5.1 bpftool map pretty print 5.1 bpftool map pretty print
============================ ----------------------------
With BTF, the map key/value can be printed based on fields rather than simply 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 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 5.2 bpftool prog dump
===================== ---------------------
The following is an example showing how func_info and line_info can help prog 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 dump with better kernel symbol names, function prototypes and line
@@ -883,7 +883,7 @@ information.::
[...] [...]
5.3 Verifier Log 5.3 Verifier Log
================ ----------------
The following is an example of how line_info can help debugging verification The following is an example of how line_info can help debugging verification
failure.:: failure.::
@@ -909,7 +909,7 @@ failure.::
R2 offset is outside of the packet R2 offset is outside of the packet
6. BTF Generation 6. BTF Generation
***************** =================
You need latest pahole You need latest pahole
@@ -1016,6 +1016,6 @@ format.::
.long 8206 # Line 8 Col 14 .long 8206 # Line 8 Col 14
7. Testing 7. Testing
********** ==========
Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests. Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests.