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 6 7 __ /Documentation/bpf/bpf_devel_QA.rst#q-how-t 7 __ /Documentation/bpf/bpf_devel_QA.rst#q-how-to-run-bpf-selftests 8 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 ========================= 9 ========================= 49 Running Selftests in a VM 10 Running Selftests in a VM 50 ========================= 11 ========================= 51 12 52 It's now possible to run the selftests using ` 13 It's now possible to run the selftests using ``tools/testing/selftests/bpf/vmtest.sh``. 53 The script tries to ensure that the tests are 14 The script tries to ensure that the tests are run with the same environment as they 54 would be run post-submit in the CI used by the !! 15 would be run post-submit in the CI used by the Maintainers. 55 that deny lists are not automatically honored. << 56 16 57 This script uses the in-tree kernel configurat !! 17 This script downloads a suitable Kconfig and VM userspace image from the system used by 58 image from the system used by the CI. It build !! 18 the CI. It builds the kernel (without overwriting your existing Kconfig), recompiles the 59 your existing Kconfig), recompiles the bpf sel !! 19 bpf selftests, runs them (by default ``tools/testing/selftests/bpf/test_progs``) and 60 ``tools/testing/selftests/bpf/test_progs``) an !! 20 saves the resulting output (by default in ``~/.bpf_selftests``). 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 21 70 For more information about using the script, r !! 22 For more information on about using the script, run: 71 23 72 .. code-block:: console 24 .. code-block:: console 73 25 74 $ tools/testing/selftests/bpf/vmtest.sh -h 26 $ tools/testing/selftests/bpf/vmtest.sh -h 75 27 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 28 .. note:: The script uses pahole and clang based on host environment setting. 85 If you want to change pahole and llv 29 If you want to change pahole and llvm, you can change `PATH` environment 86 variable in the beginning of script. 30 variable in the beginning of script. 87 31 88 Running vmtest on RV64 !! 32 .. note:: The script currently only supports x86_64. 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 33 120 Additional information about selftest failures 34 Additional information about selftest failures are 121 documented here. 35 documented here. 122 36 123 profiler[23] test failures with clang/llvm <12 37 profiler[23] test failures with clang/llvm <12.0.0 124 ============================================== 38 ================================================== 125 39 126 With clang/llvm <12.0.0, the profiler[23] test 40 With clang/llvm <12.0.0, the profiler[23] test may fail. 127 The symptom looks like 41 The symptom looks like 128 42 129 .. code-block:: c 43 .. code-block:: c 130 44 131 // r9 is a pointer to map_value 45 // r9 is a pointer to map_value 132 // r7 is a scalar 46 // r7 is a scalar 133 17: bf 96 00 00 00 00 00 00 r6 = r9 47 17: bf 96 00 00 00 00 00 00 r6 = r9 134 18: 0f 76 00 00 00 00 00 00 r6 += r7 48 18: 0f 76 00 00 00 00 00 00 r6 += r7 135 math between map_value pointer and register 49 math between map_value pointer and register with unbounded min value is not allowed 136 50 137 // the instructions below will not be seen i 51 // the instructions below will not be seen in the verifier log 138 19: a5 07 01 00 01 01 00 00 if r7 < 25 52 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 53 20: bf 96 00 00 00 00 00 00 r6 = r9 140 // r6 is used here 54 // r6 is used here 141 55 142 The verifier will reject such code with above 56 The verifier will reject such code with above error. 143 At insn 18 the r7 is indeed unbounded. The lat 57 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 58 the insn 20 undoes map_value addition. It is currently impossible for the 145 verifier to understand such speculative pointe 59 verifier to understand such speculative pointer arithmetic. 146 Hence `this patch`__ addresses it on the compi 60 Hence `this patch`__ addresses it on the compiler side. It was committed on llvm 12. 147 61 148 __ https://github.com/llvm/llvm-project/commit !! 62 __ https://reviews.llvm.org/D85570 149 63 150 The corresponding C code 64 The corresponding C code 151 65 152 .. code-block:: c 66 .. code-block:: c 153 67 154 for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH; 68 for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH; i++) { 155 filepart_length = bpf_probe_read_str 69 filepart_length = bpf_probe_read_str(payload, ...); 156 if (filepart_length <= MAX_PATH) { 70 if (filepart_length <= MAX_PATH) { 157 barrier_var(filepart_length) 71 barrier_var(filepart_length); // workaround 158 payload += filepart_length; 72 payload += filepart_length; 159 } 73 } 160 } 74 } 161 75 162 bpf_iter test failures with clang/llvm 10.0.0 76 bpf_iter test failures with clang/llvm 10.0.0 163 ============================================= 77 ============================================= 164 78 165 With clang/llvm 10.0.0, the following two bpf_ 79 With clang/llvm 10.0.0, the following two bpf_iter tests failed: 166 * ``bpf_iter/ipv6_route`` 80 * ``bpf_iter/ipv6_route`` 167 * ``bpf_iter/netlink`` 81 * ``bpf_iter/netlink`` 168 82 169 The symptom for ``bpf_iter/ipv6_route`` looks 83 The symptom for ``bpf_iter/ipv6_route`` looks like 170 84 171 .. code-block:: c 85 .. code-block:: c 172 86 173 2: (79) r8 = *(u64 *)(r1 +8) 87 2: (79) r8 = *(u64 *)(r1 +8) 174 ... 88 ... 175 14: (bf) r2 = r8 89 14: (bf) r2 = r8 176 15: (0f) r2 += r1 90 15: (0f) r2 += r1 177 ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib 91 ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib6_dst.addr, rt->fib6_dst.plen); 178 16: (7b) *(u64 *)(r8 +64) = r2 92 16: (7b) *(u64 *)(r8 +64) = r2 179 only read is supported 93 only read is supported 180 94 181 The symptom for ``bpf_iter/netlink`` looks lik 95 The symptom for ``bpf_iter/netlink`` looks like 182 96 183 .. code-block:: c 97 .. code-block:: c 184 98 185 ; struct netlink_sock *nlk = ctx->sk; 99 ; struct netlink_sock *nlk = ctx->sk; 186 2: (79) r7 = *(u64 *)(r1 +8) 100 2: (79) r7 = *(u64 *)(r1 +8) 187 ... 101 ... 188 15: (bf) r2 = r7 102 15: (bf) r2 = r7 189 16: (0f) r2 += r1 103 16: (0f) r2 += r1 190 ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_ 104 ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_protocol); 191 17: (7b) *(u64 *)(r7 +0) = r2 105 17: (7b) *(u64 *)(r7 +0) = r2 192 only read is supported 106 only read is supported 193 107 194 This is due to a llvm BPF backend bug. `The fi 108 This is due to a llvm BPF backend bug. `The fix`__ 195 has been pushed to llvm 10.x release branch an 109 has been pushed to llvm 10.x release branch and will be 196 available in 10.0.1. The patch is available in 110 available in 10.0.1. The patch is available in llvm 11.0.0 trunk. 197 111 198 __ https://github.com/llvm/llvm-project/commi !! 112 __ https://reviews.llvm.org/D78466 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 113 239 BPF CO-RE-based tests and Clang version 114 BPF CO-RE-based tests and Clang version 240 ======================================= 115 ======================================= 241 116 242 A set of selftests use BPF target-specific bui 117 A set of selftests use BPF target-specific built-ins, which might require 243 bleeding-edge Clang versions (Clang 12 nightly 118 bleeding-edge Clang versions (Clang 12 nightly at this time). 244 119 245 Few sub-tests of core_reloc test suit (part of 120 Few sub-tests of core_reloc test suit (part of test_progs test runner) require 246 the following built-ins, listed with correspon 121 the following built-ins, listed with corresponding Clang diffs introducing 247 them to Clang/LLVM. These sub-tests are going 122 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 123 old to support them, they shouldn't cause build failures or runtime test 249 failures: 124 failures: 250 125 251 - __builtin_btf_type_id() [0_, 1_, 2_]; 126 - __builtin_btf_type_id() [0_, 1_, 2_]; 252 - __builtin_preserve_type_info(), __builtin_pr 127 - __builtin_preserve_type_info(), __builtin_preserve_enum_value() [3_, 4_]. 253 128 254 .. _0: https://github.com/llvm/llvm-project/co !! 129 .. _0: https://reviews.llvm.org/D74572 255 .. _1: https://github.com/llvm/llvm-project/co !! 130 .. _1: https://reviews.llvm.org/D74668 256 .. _2: https://github.com/llvm/llvm-project/co !! 131 .. _2: https://reviews.llvm.org/D85174 257 .. _3: https://github.com/llvm/llvm-project/co !! 132 .. _3: https://reviews.llvm.org/D83878 258 .. _4: https://github.com/llvm/llvm-project/co !! 133 .. _4: https://reviews.llvm.org/D83242 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.

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.12.19)

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.12.19)

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