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@xxxxxxxx> --- 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
