Message-Id: <20180801050908.29970-5-me@tobin.cc>
Date:   Wed,  1 Aug 2018 15:08:59 +1000
From:   "Tobin C. Harding" <me@...in.cc>
To:     Daniel Borkmann <daniel@...earbox.net>,
        Alexei Starovoitov <ast@...nel.org>
Cc:     "Tobin C. Harding" <me@...in.cc>, Jonathan Corbet <corbet@....net>,
        "David S. Miller" <davem@...emloft.net>, linux-doc@...r.kernel.org,
        netdev@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [PATCH bpf-next 04/13] docs: net: Use correct heading adornments

Conversion to RST format requires the use of correct RST heading
adornments.  While we are at it we can make sure spacing around headings
is uniform.  Choose to use one empty line after any heading.

Use correct levels of heading adornment.

Signed-off-by: Tobin C. Harding <me@...in.cc>
---
 Documentation/networking/filter.rst | 36 +++++++++++++++++------------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst
index 14ce8901c245..19325286780b 100644
--- a/Documentation/networking/filter.rst
+++ b/Documentation/networking/filter.rst
@@ -1,10 +1,11 @@
+=======================================================
 Linux Socket Filtering aka Berkeley Packet Filter (BPF)
 =======================================================
 
 .. _bpf_filter:
 
 Introduction
-------------
+============
 
 Linux Socket Filtering (LSF) is derived from the Berkeley Packet Filter.
 Though there are some distinct differences between the BSD and Linux
@@ -58,7 +59,7 @@ Conference Proceedings (USENIX'93). USENIX Association, Berkeley,
 CA, USA, 2-2. [http://www.tcpdump.org/papers/bpf-usenix93.pdf]
 
 Structure
----------
+=========
 
 User space applications include <linux/filter.h> which contains the
 following relevant structures:
@@ -169,7 +170,7 @@ implementors may wish to manually write test cases and thus need low-level
 access to BPF code as well.
 
 BPF engine and instruction set
-------------------------------
+==============================
 
 Under tools/bpf/ there's a small helper tool called bpf_asm which can
 be used to write low-level filters for example scenarios mentioned in the
@@ -462,7 +463,7 @@ breakpoints: 0 1
   Exits bpf_dbg.
 
 JIT compiler
-------------
+============
 
 The Linux kernel has a built-in BPF JIT compiler for x86_64, SPARC, PowerPC,
 ARM, ARM64, MIPS and s390 and can be enabled through CONFIG_BPF_JIT. The JIT
@@ -569,7 +570,8 @@ For BPF JIT developers, bpf_jit_disasm, bpf_asm and bpf_dbg provides a useful
 toolchain for developing and testing the kernel's JIT compiler.
 
 BPF kernel internals
---------------------
+====================
+
 Internally, for the kernel interpreter, a different instruction set
 format with similar underlying principles from BPF described in previous
 paragraphs is being used. However, the instruction set format is modelled
@@ -843,7 +845,7 @@ descends all possible paths. It simulates execution of every insn and observes
 the state change of registers and stack.
 
 eBPF opcode encoding
---------------------
+====================
 
 eBPF is reusing most of the opcode encoding from classic to simplify conversion
 of classic BPF to eBPF. For arithmetic and jump instructions the 8-bit 'code'
@@ -1014,7 +1016,8 @@ Classic BPF has similar instruction: BPF_LD | BPF_W | BPF_IMM which loads
 32-bit immediate value into a register.
 
 eBPF verifier
--------------
+=============
+
 The safety of the eBPF program is determined in two steps.
 
 First step does DAG check to disallow loops and other CFG validation.
@@ -1107,7 +1110,8 @@ all use cases.
 See details of eBPF verifier in kernel/bpf/verifier.c
 
 Register value tracking
------------------------
+=======================
+
 In order to determine the safety of an eBPF program, the verifier must track
 the range of possible values in each register and also in each stack slot.
 This is done with 'struct bpf_reg_state', defined in include/linux/
@@ -1175,7 +1179,7 @@ bytes (NET_IP_ALIGN) gives a 4-byte alignment and so word-sized accesses through
 that pointer are safe.
 
 Direct packet access
---------------------
+====================
 In cls_bpf and act_bpf programs the verifier allows direct access to the packet
 data via skb->data and skb->data_end pointers.
 Ex:
@@ -1261,7 +1265,8 @@ which makes such programs easier to write comparing to LD_ABS insn
 and significantly faster.
 
 eBPF maps
----------
+=========
+
 'maps' is a generic storage of different types for sharing data between kernel
 and userspace.
 
@@ -1300,7 +1305,8 @@ The map is defined by:
   . value size in bytes
 
 Pruning
--------
+=======
+
 The verifier does not actually walk all possible paths through the program.  For
 each new branch to analyse, the verifier looks at all the states it's previously
 been in when at this instruction.  If any of them contain the current state as a
@@ -1316,7 +1322,7 @@ registers it may hold).  They must all be safe for the branch to be pruned.
 This is implemented in states_equal().
 
 Understanding eBPF verifier messages
-------------------------------------
+====================================
 
 The following are few examples of invalid eBPF programs and verifier error
 messages as seen in the log:
@@ -1447,7 +1453,7 @@ Error:
   R0 invalid mem access 'imm'
 
 Testing
--------
+=======
 
 Next to the BPF toolchain, the kernel also ships a test module that contains
 various test cases for classic and internal BPF that can be executed against
@@ -1461,13 +1467,13 @@ via insmod or modprobe against 'test_bpf' module. Results of the test cases
 including timings in nsec can be found in the kernel log (dmesg).
 
 Misc
-----
+====
 
 Also trinity, the Linux syscall fuzzer, has built-in support for BPF and
 SECCOMP-BPF kernel fuzzing.
 
 Written by
-----------
+==========
 
 The document was written in the hope that it is found useful and in order
 to give potential BPF hackers or security auditors a better overview of
-- 
2.17.1

Powered by blists - more mailing lists