Linux/tools/testing/selftests/bpf/README.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 ================== 1 ================== 2 BPF Selftest Notes 2 BPF Selftest Notes 3 ================== 3 ================== 4 General instructions on running selftests can 4 General instructions on running selftests can be found in 5 `Documentation/bpf/bpf_devel_QA.rst`__. !! 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 6 120 Additional information about selftest failures 7 Additional information about selftest failures are 121 documented here. 8 documented here. 122 9 123 profiler[23] test failures with clang/llvm <12 10 profiler[23] test failures with clang/llvm <12.0.0 124 ============================================== 11 ================================================== 125 12 126 With clang/llvm <12.0.0, the profiler[23] test 13 With clang/llvm <12.0.0, the profiler[23] test may fail. 127 The symptom looks like 14 The symptom looks like 128 15 129 .. code-block:: c 16 .. code-block:: c 130 17 131 // r9 is a pointer to map_value 18 // r9 is a pointer to map_value 132 // r7 is a scalar 19 // r7 is a scalar 133 17: bf 96 00 00 00 00 00 00 r6 = r9 20 17: bf 96 00 00 00 00 00 00 r6 = r9 134 18: 0f 76 00 00 00 00 00 00 r6 += r7 21 18: 0f 76 00 00 00 00 00 00 r6 += r7 135 math between map_value pointer and register 22 math between map_value pointer and register with unbounded min value is not allowed 136 23 137 // the instructions below will not be seen i 24 // the instructions below will not be seen in the verifier log 138 19: a5 07 01 00 01 01 00 00 if r7 < 25 25 19: a5 07 01 00 01 01 00 00 if r7 < 257 goto +1 139 20: bf 96 00 00 00 00 00 00 r6 = r9 26 20: bf 96 00 00 00 00 00 00 r6 = r9 140 // r6 is used here 27 // r6 is used here 141 28 142 The verifier will reject such code with above 29 The verifier will reject such code with above error. 143 At insn 18 the r7 is indeed unbounded. The lat 30 At insn 18 the r7 is indeed unbounded. The later insn 19 checks the bounds and 144 the insn 20 undoes map_value addition. It is c 31 the insn 20 undoes map_value addition. It is currently impossible for the 145 verifier to understand such speculative pointe 32 verifier to understand such speculative pointer arithmetic. 146 Hence `this patch`__ addresses it on the compi !! 33 Hence 147 !! 34 https://reviews.llvm.org/D85570 148 __ https://github.com/llvm/llvm-project/commit !! 35 addresses it on the compiler side. It was committed on llvm 12. 149 36 150 The corresponding C code 37 The corresponding C code 151 << 152 .. code-block:: c 38 .. code-block:: c 153 39 154 for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH; 40 for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH; i++) { 155 filepart_length = bpf_probe_read_str 41 filepart_length = bpf_probe_read_str(payload, ...); 156 if (filepart_length <= MAX_PATH) { 42 if (filepart_length <= MAX_PATH) { 157 barrier_var(filepart_length) 43 barrier_var(filepart_length); // workaround 158 payload += filepart_length; 44 payload += filepart_length; 159 } 45 } 160 } 46 } 161 47 162 bpf_iter test failures with clang/llvm 10.0.0 48 bpf_iter test failures with clang/llvm 10.0.0 163 ============================================= 49 ============================================= 164 50 165 With clang/llvm 10.0.0, the following two bpf_ 51 With clang/llvm 10.0.0, the following two bpf_iter tests failed: 166 * ``bpf_iter/ipv6_route`` 52 * ``bpf_iter/ipv6_route`` 167 * ``bpf_iter/netlink`` 53 * ``bpf_iter/netlink`` 168 54 169 The symptom for ``bpf_iter/ipv6_route`` looks 55 The symptom for ``bpf_iter/ipv6_route`` looks like 170 56 171 .. code-block:: c 57 .. code-block:: c 172 58 173 2: (79) r8 = *(u64 *)(r1 +8) 59 2: (79) r8 = *(u64 *)(r1 +8) 174 ... 60 ... 175 14: (bf) r2 = r8 61 14: (bf) r2 = r8 176 15: (0f) r2 += r1 62 15: (0f) r2 += r1 177 ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib 63 ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib6_dst.addr, rt->fib6_dst.plen); 178 16: (7b) *(u64 *)(r8 +64) = r2 64 16: (7b) *(u64 *)(r8 +64) = r2 179 only read is supported 65 only read is supported 180 66 181 The symptom for ``bpf_iter/netlink`` looks lik 67 The symptom for ``bpf_iter/netlink`` looks like 182 68 183 .. code-block:: c 69 .. code-block:: c 184 70 185 ; struct netlink_sock *nlk = ctx->sk; 71 ; struct netlink_sock *nlk = ctx->sk; 186 2: (79) r7 = *(u64 *)(r1 +8) 72 2: (79) r7 = *(u64 *)(r1 +8) 187 ... 73 ... 188 15: (bf) r2 = r7 74 15: (bf) r2 = r7 189 16: (0f) r2 += r1 75 16: (0f) r2 += r1 190 ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_ 76 ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_protocol); 191 17: (7b) *(u64 *)(r7 +0) = r2 77 17: (7b) *(u64 *)(r7 +0) = r2 192 only read is supported 78 only read is supported 193 79 194 This is due to a llvm BPF backend bug. `The fi !! 80 This is due to a llvm BPF backend bug. The fix >> 81 https://reviews.llvm.org/D78466 195 has been pushed to llvm 10.x release branch an 82 has been pushed to llvm 10.x release branch and will be 196 available in 10.0.1. The patch is available in !! 83 available in 10.0.1. The fix is available in llvm 11.0.0 trunk. 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 84 239 BPF CO-RE-based tests and Clang version 85 BPF CO-RE-based tests and Clang version 240 ======================================= 86 ======================================= 241 87 242 A set of selftests use BPF target-specific bui 88 A set of selftests use BPF target-specific built-ins, which might require 243 bleeding-edge Clang versions (Clang 12 nightly 89 bleeding-edge Clang versions (Clang 12 nightly at this time). 244 90 245 Few sub-tests of core_reloc test suit (part of 91 Few sub-tests of core_reloc test suit (part of test_progs test runner) require 246 the following built-ins, listed with correspon 92 the following built-ins, listed with corresponding Clang diffs introducing 247 them to Clang/LLVM. These sub-tests are going 93 them to Clang/LLVM. These sub-tests are going to be skipped if Clang is too 248 old to support them, they shouldn't cause buil 94 old to support them, they shouldn't cause build failures or runtime test 249 failures: 95 failures: 250 96 251 - __builtin_btf_type_id() [0_, 1_, 2_]; !! 97 - __builtin_btf_type_id() ([0], [1], [2]); 252 - __builtin_preserve_type_info(), __builtin_pr !! 98 - __builtin_preserve_type_info(), __builtin_preserve_enum_value() ([3], [4]). 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 99 339 __ https://github.com/llvm/llvm-project/commit !! 100 [0] https://reviews.llvm.org/D74572 >> 101 [1] https://reviews.llvm.org/D74668 >> 102 [2] https://reviews.llvm.org/D85174 >> 103 [3] https://reviews.llvm.org/D83878 >> 104 [4] https://reviews.llvm.org/D83242

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/tools/testing/selftests/bpf/README.rst

Diff markup

Differences between /tools/testing/selftests/bpf/README.rst (Version linux-6.12-rc7) and /tools/testing/selftests/bpf/README.rst (Version linux-5.10.229)

TOMOYO Linux Cross Reference Linux/tools/testing/selftests/bpf/README.rst

Diff markup

Differences between /tools/testing/selftests/bpf/README.rst (Version linux-6.12-rc7) and /tools/testing/selftests/bpf/README.rst (Version linux-5.10.229)

TOMOYO Linux Cross Reference
Linux/tools/testing/selftests/bpf/README.rst