1==================
2BPF Selftest Notes
3==================
4General instructions on running selftests can be found in
5`Documentation/bpf/bpf_devel_QA.rst`__.
6
7__ /Documentation/bpf/bpf_devel_QA.rst#q-how-to-run-bpf-selftests
8
9=========================
10Running Selftests in a VM
11=========================
12
13It's now possible to run the selftests using ``tools/testing/selftests/bpf/vmtest.sh``.
14The script tries to ensure that the tests are run with the same environment as they
15would be run post-submit in the CI used by the Maintainers.
16
17This script downloads a suitable Kconfig and VM userspace image from the system used by
18the CI. It builds the kernel (without overwriting your existing Kconfig), recompiles the
19bpf selftests, runs them (by default ``tools/testing/selftests/bpf/test_progs``) and
20saves the resulting output (by default in ``~/.bpf_selftests``).
21
22For more information on about using the script, run:
23
24.. code-block:: console
25
26  $ tools/testing/selftests/bpf/vmtest.sh -h
27
28.. note:: The script uses pahole and clang based on host environment setting.
29          If you want to change pahole and llvm, you can change `PATH` environment
30          variable in the beginning of script.
31
32.. note:: The script currently only supports x86_64.
33
34Additional information about selftest failures are
35documented here.
36
37profiler[23] test failures with clang/llvm <12.0.0
38==================================================
39
40With clang/llvm <12.0.0, the profiler[23] test may fail.
41The symptom looks like
42
43.. code-block:: c
44
45  // r9 is a pointer to map_value
46  // r7 is a scalar
47  17:       bf 96 00 00 00 00 00 00 r6 = r9
48  18:       0f 76 00 00 00 00 00 00 r6 += r7
49  math between map_value pointer and register with unbounded min value is not allowed
50
51  // the instructions below will not be seen in the verifier log
52  19:       a5 07 01 00 01 01 00 00 if r7 < 257 goto +1
53  20:       bf 96 00 00 00 00 00 00 r6 = r9
54  // r6 is used here
55
56The verifier will reject such code with above error.
57At insn 18 the r7 is indeed unbounded. The later insn 19 checks the bounds and
58the insn 20 undoes map_value addition. It is currently impossible for the
59verifier to understand such speculative pointer arithmetic.
60Hence `this patch`__ addresses it on the compiler side. It was committed on llvm 12.
61
62__ https://reviews.llvm.org/D85570
63
64The corresponding C code
65
66.. code-block:: c
67
68  for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH; i++) {
69          filepart_length = bpf_probe_read_str(payload, ...);
70          if (filepart_length <= MAX_PATH) {
71                  barrier_var(filepart_length); // workaround
72                  payload += filepart_length;
73          }
74  }
75
76bpf_iter test failures with clang/llvm 10.0.0
77=============================================
78
79With clang/llvm 10.0.0, the following two bpf_iter tests failed:
80  * ``bpf_iter/ipv6_route``
81  * ``bpf_iter/netlink``
82
83The symptom for ``bpf_iter/ipv6_route`` looks like
84
85.. code-block:: c
86
87  2: (79) r8 = *(u64 *)(r1 +8)
88  ...
89  14: (bf) r2 = r8
90  15: (0f) r2 += r1
91  ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib6_dst.addr, rt->fib6_dst.plen);
92  16: (7b) *(u64 *)(r8 +64) = r2
93  only read is supported
94
95The symptom for ``bpf_iter/netlink`` looks like
96
97.. code-block:: c
98
99  ; struct netlink_sock *nlk = ctx->sk;
100  2: (79) r7 = *(u64 *)(r1 +8)
101  ...
102  15: (bf) r2 = r7
103  16: (0f) r2 += r1
104  ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_protocol);
105  17: (7b) *(u64 *)(r7 +0) = r2
106  only read is supported
107
108This is due to a llvm BPF backend bug. `The fix`__
109has been pushed to llvm 10.x release branch and will be
110available in 10.0.1. The patch is available in llvm 11.0.0 trunk.
111
112__  https://reviews.llvm.org/D78466
113
114BPF CO-RE-based tests and Clang version
115=======================================
116
117A set of selftests use BPF target-specific built-ins, which might require
118bleeding-edge Clang versions (Clang 12 nightly at this time).
119
120Few sub-tests of core_reloc test suit (part of test_progs test runner) require
121the following built-ins, listed with corresponding Clang diffs introducing
122them to Clang/LLVM. These sub-tests are going to be skipped if Clang is too
123old to support them, they shouldn't cause build failures or runtime test
124failures:
125
126- __builtin_btf_type_id() [0_, 1_, 2_];
127- __builtin_preserve_type_info(), __builtin_preserve_enum_value() [3_, 4_].
128
129.. _0: https://reviews.llvm.org/D74572
130.. _1: https://reviews.llvm.org/D74668
131.. _2: https://reviews.llvm.org/D85174
132.. _3: https://reviews.llvm.org/D83878
133.. _4: https://reviews.llvm.org/D83242
134