tools/testing/selftests/bpf/README.rst

   1 ==================
   2 BPF Selftest Notes
   3 ==================
   4 General 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 =============
  10 BPF CI System
  11 =============
  12
  13 BPF employs a continuous integration (CI) system to check patch submission in an
  14 automated fashion. The system runs selftests for each patch in a series. Results
  15 are propagated to patchwork, where failures are highlighted similar to
  16 violations of other checks (such as additional warnings being emitted or a
  17 ``scripts/checkpatch.pl`` reported deficiency):
  18
  19   https://patchwork.kernel.org/project/netdevbpf/list/?delegate=121173
  20
  21 The CI system executes tests on multiple architectures. It uses a kernel
  22 configuration derived from both the generic and architecture specific config
  23 file fragments below ``tools/testing/selftests/bpf/`` (e.g., ``config`` and
  24 ``config.x86_64``).
  25
  26 Denylisting Tests
  27 =================
  28
  29 It is possible for some architectures to not have support for all BPF features.
  30 In such a case tests in CI may fail. An example of such a shortcoming is BPF
  31 trampoline support on IBM's s390x architecture. For cases like this, an in-tree
  32 deny list file, located at ``tools/testing/selftests/bpf/DENYLIST.<arch>``, can
  33 be used to prevent the test from running on such an architecture.
  34
  35 In addition to that, the generic ``tools/testing/selftests/bpf/DENYLIST`` is
  36 honored on every architecture running tests.
  37
  38 These files are organized in three columns. The first column lists the test in
  39 question. This can be the name of a test suite or of an individual test. The
  40 remaining two columns provide additional meta data that helps identify and
  41 classify the entry: column two is a copy and paste of the error being reported
  42 when running the test in the setting in question. The third column, if
  43 available, summarizes the underlying problem. A value of ``trampoline``, for
  44 example, indicates that lack of trampoline support is causing the test to fail.
  45 This last entry helps identify tests that can be re-enabled once such support is
  46 added.
  47
  48 =========================
  49 Running Selftests in a VM
  50 =========================
  51
  52 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 run with the same environment as they
  54 would be run post-submit in the CI used by the Maintainers, with the exception
  55 that deny lists are not automatically honored.
  56
  57 This script uses the in-tree kernel configuration and downloads a VM userspace
  58 image from the system used by the CI. It builds the kernel (without overwriting
  59 your existing Kconfig), recompiles the bpf selftests, runs them (by default
  60 ``tools/testing/selftests/bpf/test_progs``) and saves the resulting output (by
  61 default in ``~/.bpf_selftests``).
  62
  63 Script dependencies:
  64 - clang (preferably built from sources, https://github.com/llvm/llvm-project);
  65 - pahole (preferably built from sources, https://git.kernel.org/pub/scm/devel/pahole/pahole.git/);
  66 - qemu;
  67 - docutils (for ``rst2man``);
  68 - libcap-devel.
  69
  70 For more information about using the script, run:
  71
  72 .. code-block:: console
  73
  74   $ tools/testing/selftests/bpf/vmtest.sh -h
  75
  76 In case of linker errors when running selftests, try using static linking:
  77
  78 .. code-block:: console
  79
  80   $ LDLIBS=-static PKG_CONFIG='pkg-config --static' vmtest.sh
  81
  82 .. note:: Some distros may not support static linking.
  83
  84 .. note:: The script uses pahole and clang based on host environment setting.
  85           If you want to change pahole and llvm, you can change `PATH` environment
  86           variable in the beginning of script.
  87
  88 .. note:: The script currently only supports x86_64 and s390x architectures.
  89
  90 Additional information about selftest failures are
  91 documented here.
  92
  93 profiler[23] test failures with clang/llvm <12.0.0
  94 ==================================================
  95
  96 With clang/llvm <12.0.0, the profiler[23] test may fail.
  97 The symptom looks like
  98
  99 .. code-block:: c
 100
 101   // r9 is a pointer to map_value
 102   // r7 is a scalar
 103   17:       bf 96 00 00 00 00 00 00 r6 = r9
 104   18:       0f 76 00 00 00 00 00 00 r6 += r7
 105   math between map_value pointer and register with unbounded min value is not allowed
 106
 107   // the instructions below will not be seen in the verifier log
 108   19:       a5 07 01 00 01 01 00 00 if r7 < 257 goto +1
 109   20:       bf 96 00 00 00 00 00 00 r6 = r9
 110   // r6 is used here
 111
 112 The verifier will reject such code with above error.
 113 At insn 18 the r7 is indeed unbounded. The later insn 19 checks the bounds and
 114 the insn 20 undoes map_value addition. It is currently impossible for the
 115 verifier to understand such speculative pointer arithmetic.
 116 Hence `this patch`__ addresses it on the compiler side. It was committed on llvm 12.
 117
 118 __ https://github.com/llvm/llvm-project/commit/ddf1864ace484035e3cde5e83b3a31ac81e059c6
 119
 120 The corresponding C code
 121
 122 .. code-block:: c
 123
 124   for (int i = 0; i < MAX_CGROUPS_PATH_DEPTH; i++) {
 125           filepart_length = bpf_probe_read_str(payload, ...);
 126           if (filepart_length <= MAX_PATH) {
 127                   barrier_var(filepart_length); // workaround
 128                   payload += filepart_length;
 129           }
 130   }
 131
 132 bpf_iter test failures with clang/llvm 10.0.0
 133 =============================================
 134
 135 With clang/llvm 10.0.0, the following two bpf_iter tests failed:
 136   * ``bpf_iter/ipv6_route``
 137   * ``bpf_iter/netlink``
 138
 139 The symptom for ``bpf_iter/ipv6_route`` looks like
 140
 141 .. code-block:: c
 142
 143   2: (79) r8 = *(u64 *)(r1 +8)
 144   ...
 145   14: (bf) r2 = r8
 146   15: (0f) r2 += r1
 147   ; BPF_SEQ_PRINTF(seq, "%pi6 %02x ", &rt->fib6_dst.addr, rt->fib6_dst.plen);
 148   16: (7b) *(u64 *)(r8 +64) = r2
 149   only read is supported
 150
 151 The symptom for ``bpf_iter/netlink`` looks like
 152
 153 .. code-block:: c
 154
 155   ; struct netlink_sock *nlk = ctx->sk;
 156   2: (79) r7 = *(u64 *)(r1 +8)
 157   ...
 158   15: (bf) r2 = r7
 159   16: (0f) r2 += r1
 160   ; BPF_SEQ_PRINTF(seq, "%pK %-3d ", s, s->sk_protocol);
 161   17: (7b) *(u64 *)(r7 +0) = r2
 162   only read is supported
 163
 164 This is due to a llvm BPF backend bug. `The fix`__
 165 has been pushed to llvm 10.x release branch and will be
 166 available in 10.0.1. The patch is available in llvm 11.0.0 trunk.
 167
 168 __  https://github.com/llvm/llvm-project/commit/3cb7e7bf959dcd3b8080986c62e10a75c7af43f0
 169
 170 bpf_verif_scale/loop6.bpf.o test failure with Clang 12
 171 ======================================================
 172
 173 With Clang 12, the following bpf_verif_scale test failed:
 174   * ``bpf_verif_scale/loop6.bpf.o``
 175
 176 The verifier output looks like
 177
 178 .. code-block:: c
 179
 180   R1 type=ctx expected=fp
 181   The sequence of 8193 jumps is too complex.
 182
 183 The reason is compiler generating the following code
 184
 185 .. code-block:: c
 186
 187   ;       for (i = 0; (i < VIRTIO_MAX_SGS) && (i < num); i++) {
 188       14:       16 05 40 00 00 00 00 00 if w5 == 0 goto +64 <LBB0_6>
 189       15:       bc 51 00 00 00 00 00 00 w1 = w5
 190       16:       04 01 00 00 ff ff ff ff w1 += -1
 191       17:       67 05 00 00 20 00 00 00 r5 <<= 32
 192       18:       77 05 00 00 20 00 00 00 r5 >>= 32
 193       19:       a6 01 01 00 05 00 00 00 if w1 < 5 goto +1 <LBB0_4>
 194       20:       b7 05 00 00 06 00 00 00 r5 = 6
 195   00000000000000a8 <LBB0_4>:
 196       21:       b7 02 00 00 00 00 00 00 r2 = 0
 197       22:       b7 01 00 00 00 00 00 00 r1 = 0
 198   ;       for (i = 0; (i < VIRTIO_MAX_SGS) && (i < num); i++) {
 199       23:       7b 1a e0 ff 00 00 00 00 *(u64 *)(r10 - 32) = r1
 200       24:       7b 5a c0 ff 00 00 00 00 *(u64 *)(r10 - 64) = r5
 201
 202 Note that insn #15 has w1 = w5 and w1 is refined later but
 203 r5(w5) is eventually saved on stack at insn #24 for later use.
 204 This cause later verifier failure. The bug has been `fixed`__ in
 205 Clang 13.
 206
 207 __  https://github.com/llvm/llvm-project/commit/1959ead525b8830cc8a345f45e1c3ef9902d3229
 208
 209 BPF CO-RE-based tests and Clang version
 210 =======================================
 211
 212 A set of selftests use BPF target-specific built-ins, which might require
 213 bleeding-edge Clang versions (Clang 12 nightly at this time).
 214
 215 Few sub-tests of core_reloc test suit (part of test_progs test runner) require
 216 the following built-ins, listed with corresponding Clang diffs introducing
 217 them to Clang/LLVM. These sub-tests are going to be skipped if Clang is too
 218 old to support them, they shouldn't cause build failures or runtime test
 219 failures:
 220
 221 - __builtin_btf_type_id() [0_, 1_, 2_];
 222 - __builtin_preserve_type_info(), __builtin_preserve_enum_value() [3_, 4_].
 223
 224 .. _0: https://github.com/llvm/llvm-project/commit/6b01b465388b204d543da3cf49efd6080db094a9
 225 .. _1: https://github.com/llvm/llvm-project/commit/072cde03aaa13a2c57acf62d79876bf79aa1919f
 226 .. _2: https://github.com/llvm/llvm-project/commit/00602ee7ef0bf6c68d690a2bd729c12b95c95c99
 227 .. _3: https://github.com/llvm/llvm-project/commit/6d218b4adb093ff2e9764febbbc89f429412006c
 228 .. _4: https://github.com/llvm/llvm-project/commit/6d6750696400e7ce988d66a1a00e1d0cb32815f8
 229
 230 Floating-point tests and Clang version
 231 ======================================
 232
 233 Certain selftests, e.g. core_reloc, require support for the floating-point
 234 types, which was introduced in `Clang 13`__. The older Clang versions will
 235 either crash when compiling these tests, or generate an incorrect BTF.
 236
 237 __  https://github.com/llvm/llvm-project/commit/a7137b238a07d9399d3ae96c0b461571bd5aa8b2
 238
 239 Kernel function call test and Clang version
 240 ===========================================
 241
 242 Some selftests (e.g. kfunc_call and bpf_tcp_ca) require a LLVM support
 243 to generate extern function in BTF.  It was introduced in `Clang 13`__.
 244
 245 Without it, the error from compiling bpf selftests looks like:
 246
 247 .. code-block:: console
 248
 249   libbpf: failed to find BTF for extern 'tcp_slow_start' [25] section: -2
 250
 251 __ https://github.com/llvm/llvm-project/commit/886f9ff53155075bd5f1e994f17b85d1e1b7470c
 252
 253 btf_tag test and Clang version
 254 ==============================
 255
 256 The btf_tag selftest requires LLVM support to recognize the btf_decl_tag and
 257 btf_type_tag attributes. They are introduced in `Clang 14` [0_, 1_].
 258 The subtests ``btf_type_tag_user_{mod1, mod2, vmlinux}`` also requires
 259 pahole version ``1.23``.
 260
 261 Without them, the btf_tag selftest will be skipped and you will observe:
 262
 263 .. code-block:: console
 264
 265   #<test_num> btf_tag:SKIP
 266
 267 .. _0: https://github.com/llvm/llvm-project/commit/a162b67c98066218d0d00aa13b99afb95d9bb5e6
 268 .. _1: https://github.com/llvm/llvm-project/commit/3466e00716e12e32fdb100e3fcfca5c2b3e8d784
 269
 270 Clang dependencies for static linking tests
 271 ===========================================
 272
 273 linked_vars, linked_maps, and linked_funcs tests depend on `Clang fix`__ to
 274 generate valid BTF information for weak variables. Please make sure you use
 275 Clang that contains the fix.
 276
 277 __ https://github.com/llvm/llvm-project/commit/968292cb93198442138128d850fd54dc7edc0035
 278
 279 Clang relocation changes
 280 ========================
 281
 282 Clang 13 patch `clang reloc patch`_  made some changes on relocations such
 283 that existing relocation types are broken into more types and
 284 each new type corresponds to only one way to resolve relocation.
 285 See `kernel llvm reloc`_ for more explanation and some examples.
 286 Using clang 13 to compile old libbpf which has static linker support,
 287 there will be a compilation failure::
 288
 289   libbpf: ELF relo #0 in section #6 has unexpected type 2 in .../bpf_tcp_nogpl.bpf.o
 290
 291 Here, ``type 2`` refers to new relocation type ``R_BPF_64_ABS64``.
 292 To fix this issue, user newer libbpf.
 293
 294 .. Links
 295 .. _clang reloc patch: https://github.com/llvm/llvm-project/commit/6a2ea84600ba4bd3b2733bd8f08f5115eb32164b
 296 .. _kernel llvm reloc: /Documentation/bpf/llvm_reloc.rst
 297
 298 Clang dependencies for the u32 spill test (xdpwall)
 299 ===================================================
 300 The xdpwall selftest requires a change in `Clang 14`__.
 301
 302 Without it, the xdpwall selftest will fail and the error message
 303 from running test_progs will look like:
 304
 305 .. code-block:: console
 306
 307   test_xdpwall:FAIL:Does LLVM have https://github.com/llvm/llvm-project/commit/ea72b0319d7b0f0c2fcf41d121afa5d031b319d5? unexpected error: -4007
 308
 309 __ https://github.com/llvm/llvm-project/commit/ea72b0319d7b0f0c2fcf41d121afa5d031b319d5