1 ==================
2 BPF Selftest Notes
3 ==================
4 General instructions on running selftests can
5 `Documentation/bpf/bpf_devel_QA.rst`__.
6
7 __ /Documentation/bpf/bpf_devel_QA.rst#q-how-t
8
9 =============
10 BPF CI System
11 =============
12
13 BPF employs a continuous integration (CI) syst
14 automated fashion. The system runs selftests f
15 are propagated to patchwork, where failures ar
16 violations of other checks (such as additional
17 ``scripts/checkpatch.pl`` reported deficiency)
18
19 https://patchwork.kernel.org/project/netdevb
20
21 The CI system executes tests on multiple archi
22 configuration derived from both the generic an
23 file fragments below ``tools/testing/selftests
24 ``config.x86_64``).
25
26 Denylisting Tests
27 =================
28
29 It is possible for some architectures to not h
30 In such a case tests in CI may fail. An exampl
31 trampoline support on IBM's s390x architecture
32 deny list file, located at ``tools/testing/sel
33 be used to prevent the test from running on su
34
35 In addition to that, the generic ``tools/testi
36 honored on every architecture running tests.
37
38 These files are organized in three columns. Th
39 question. This can be the name of a test suite
40 remaining two columns provide additional meta
41 classify the entry: column two is a copy and p
42 when running the test in the setting in questi
43 available, summarizes the underlying problem.
44 example, indicates that lack of trampoline sup
45 This last entry helps identify tests that can
46 added.
47
48 =========================
49 Running Selftests in a VM
50 =========================
51
52 It's now possible to run the selftests using `
53 The script tries to ensure that the tests are
54 would be run post-submit in the CI used by the
55 that deny lists are not automatically honored.
56
57 This script uses the in-tree kernel configurat
58 image from the system used by the CI. It build
59 your existing Kconfig), recompiles the bpf sel
60 ``tools/testing/selftests/bpf/test_progs``) an
61 default in ``~/.bpf_selftests``).
62
63 Script dependencies:
64 - clang (preferably built from sources, https:
65 - pahole (preferably built from sources, https
66 - qemu;
67 - docutils (for ``rst2man``);
68 - libcap-devel.
69
70 For more information about using the script, r
71
72 .. code-block:: console
73
74 $ tools/testing/selftests/bpf/vmtest.sh -h
75
76 In case of linker errors when running selftest
77
78 .. code-block:: console
79
80 $ LDLIBS=-static PKG_CONFIG='pkg-config --st
81
82 .. note:: Some distros may not support static
83
84 .. note:: The script uses pahole and clang bas
85 If you want to change pahole and llv
86 variable in the beginning of script.
87
88 Running vmtest on RV64
89 ======================
90 To speed up testing and avoid various dependen
91 run vmtest in a Docker container. Before runni
92 Docker container and local rootfs image. The o
93
94 1. Create Docker container as shown in link [0
95
96 2. Use mkrootfs_debian.sh script [1] to build
97
98 .. code-block:: console
99
100 $ sudo ./mkrootfs_debian.sh --arch riscv64 -
101
102 3. Start Docker container [0] and run vmtest i
103
104 .. code-block:: console
105
106 $ PLATFORM=riscv64 CROSS_COMPILE=riscv64-lin
107 tools/testing/selftests/bpf/vmtest.sh \
108 -l <path of local rootfs image> -- \
109 ./test_progs -d \
110 \"$(cat tools/testing/selftests/bpf/DE
111 | cut -d'#' -f1 \
112 | sed -e 's/^[[:space:]]*//' \
113 -e 's/[[:space:]]*$//' \
114 | tr -s '\n' ',' \
115 )\"
116
117 Link: https://github.com/pulehui/riscv-bpf-vmt
118 Link: https://github.com/libbpf/ci/blob/main/r
119
120 Additional information about selftest failures
121 documented here.
122
123 profiler[23] test failures with clang/llvm <12
124 ==============================================
125
126 With clang/llvm <12.0.0, the profiler[23] test
127 The symptom looks like
128
129 .. code-block:: c
130
131 // r9 is a pointer to map_value
132 // r7 is a scalar
133 17: bf 96 00 00 00 00 00 00 r6 = r9
134 18: 0f 76 00 00 00 00 00 00 r6 += r7
135 math between map_value pointer and register
136
137 // the instructions below will not be seen i
138 19: a5 07 01 00 01 01 00 00 if r7 < 25
139 20: bf 96 00 00 00 00 00 00 r6 = r9
140 // r6 is used here
141
142 The verifier will reject such code with above
143 At insn 18 the r7 is indeed unbounded. The lat
144 the insn 20 undoes map_value addition. It is c
145 verifier to understand such speculative pointe
146 Hence `this patch`__ addresses it on the compi
147
148 __ https://github.com/llvm/llvm-project/commit
149
150 The corresponding C code
151
152 .. code-block:: c
153
154 for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH;
155 filepart_length = bpf_probe_read_str
156 if (filepart_length <= MAX_PATH) {
157 barrier_var(filepart_length)
158 payload += filepart_length;
159 }
160 }
161
162 bpf_iter test failures with clang/llvm 10.0.0
163 =============================================
164
165 With clang/llvm 10.0.0, the following two bpf_
166 * ``bpf_iter/ipv6_route``
167 * ``bpf_iter/netlink``
168
169 The symptom for ``bpf_iter/ipv6_route`` looks
170
171 .. code-block:: c
172
173 2: (79) r8 = *(u64 *)(r1 +8)
174 ...
175 14: (bf) r2 = r8
176 15: (0f) r2 += r1
177 ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib
178 16: (7b) *(u64 *)(r8 +64) = r2
179 only read is supported
180
181 The symptom for ``bpf_iter/netlink`` looks lik
182
183 .. code-block:: c
184
185 ; struct netlink_sock *nlk = ctx->sk;
186 2: (79) r7 = *(u64 *)(r1 +8)
187 ...
188 15: (bf) r2 = r7
189 16: (0f) r2 += r1
190 ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_
191 17: (7b) *(u64 *)(r7 +0) = r2
192 only read is supported
193
194 This is due to a llvm BPF backend bug. `The fi
195 has been pushed to llvm 10.x release branch an
196 available in 10.0.1. The patch is available in
197
198 __ https://github.com/llvm/llvm-project/commi
199
200 bpf_verif_scale/loop6.bpf.o test failure with
201 ==============================================
202
203 With Clang 12, the following bpf_verif_scale t
204 * ``bpf_verif_scale/loop6.bpf.o``
205
206 The verifier output looks like
207
208 .. code-block:: c
209
210 R1 type=ctx expected=fp
211 The sequence of 8193 jumps is too complex.
212
213 The reason is compiler generating the followin
214
215 .. code-block:: c
216
217 ; for (i = 0; (i < VIRTIO_MAX_SGS) &&
218 14: 16 05 40 00 00 00 00 00 if w5
219 15: bc 51 00 00 00 00 00 00 w1 = w
220 16: 04 01 00 00 ff ff ff ff w1 +=
221 17: 67 05 00 00 20 00 00 00 r5 <<=
222 18: 77 05 00 00 20 00 00 00 r5 >>=
223 19: a6 01 01 00 05 00 00 00 if w1
224 20: b7 05 00 00 06 00 00 00 r5 = 6
225 00000000000000a8 <LBB0_4>:
226 21: b7 02 00 00 00 00 00 00 r2 = 0
227 22: b7 01 00 00 00 00 00 00 r1 = 0
228 ; for (i = 0; (i < VIRTIO_MAX_SGS) &&
229 23: 7b 1a e0 ff 00 00 00 00 *(u64
230 24: 7b 5a c0 ff 00 00 00 00 *(u64
231
232 Note that insn #15 has w1 = w5 and w1 is refin
233 r5(w5) is eventually saved on stack at insn #2
234 This cause later verifier failure. The bug has
235 Clang 13.
236
237 __ https://github.com/llvm/llvm-project/commi
238
239 BPF CO-RE-based tests and Clang version
240 =======================================
241
242 A set of selftests use BPF target-specific bui
243 bleeding-edge Clang versions (Clang 12 nightly
244
245 Few sub-tests of core_reloc test suit (part of
246 the following built-ins, listed with correspon
247 them to Clang/LLVM. These sub-tests are going
248 old to support them, they shouldn't cause buil
249 failures:
250
251 - __builtin_btf_type_id() [0_, 1_, 2_];
252 - __builtin_preserve_type_info(), __builtin_pr
253
254 .. _0: https://github.com/llvm/llvm-project/co
255 .. _1: https://github.com/llvm/llvm-project/co
256 .. _2: https://github.com/llvm/llvm-project/co
257 .. _3: https://github.com/llvm/llvm-project/co
258 .. _4: https://github.com/llvm/llvm-project/co
259
260 Floating-point tests and Clang version
261 ======================================
262
263 Certain selftests, e.g. core_reloc, require su
264 types, which was introduced in `Clang 13`__. T
265 either crash when compiling these tests, or ge
266
267 __ https://github.com/llvm/llvm-project/commi
268
269 Kernel function call test and Clang version
270 ===========================================
271
272 Some selftests (e.g. kfunc_call and bpf_tcp_ca
273 to generate extern function in BTF. It was in
274
275 Without it, the error from compiling bpf selft
276
277 .. code-block:: console
278
279 libbpf: failed to find BTF for extern 'tcp_s
280
281 __ https://github.com/llvm/llvm-project/commit
282
283 btf_tag test and Clang version
284 ==============================
285
286 The btf_tag selftest requires LLVM support to
287 btf_type_tag attributes. They are introduced i
288 The subtests ``btf_type_tag_user_{mod1, mod2,
289 pahole version ``1.23``.
290
291 Without them, the btf_tag selftest will be ski
292
293 .. code-block:: console
294
295 #<test_num> btf_tag:SKIP
296
297 .. _0: https://github.com/llvm/llvm-project/co
298 .. _1: https://github.com/llvm/llvm-project/co
299
300 Clang dependencies for static linking tests
301 ===========================================
302
303 linked_vars, linked_maps, and linked_funcs tes
304 generate valid BTF information for weak variab
305 Clang that contains the fix.
306
307 __ https://github.com/llvm/llvm-project/commit
308
309 Clang relocation changes
310 ========================
311
312 Clang 13 patch `clang reloc patch`_ made some
313 that existing relocation types are broken into
314 each new type corresponds to only one way to r
315 See `kernel llvm reloc`_ for more explanation
316 Using clang 13 to compile old libbpf which has
317 there will be a compilation failure::
318
319 libbpf: ELF relo #0 in section #6 has unexpe
320
321 Here, ``type 2`` refers to new relocation type
322 To fix this issue, user newer libbpf.
323
324 .. Links
325 .. _clang reloc patch: https://github.com/llvm
326 .. _kernel llvm reloc: /Documentation/bpf/llvm
327
328 Clang dependencies for the u32 spill test (xdp
329 ==============================================
330 The xdpwall selftest requires a change in `Cla
331
332 Without it, the xdpwall selftest will fail and
333 from running test_progs will look like:
334
335 .. code-block:: console
336
337 test_xdpwall:FAIL:Does LLVM have https://git
338
339 __ https://github.com/llvm/llvm-project/commit
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.