samples/bpf/README.rst

   1 eBPF sample programs
   2 ====================
   3
   4 This directory contains a test stubs, verifier test-suite and examples
   5 for using eBPF. The examples use libbpf from tools/lib/bpf.
   6
   7 Build dependencies
   8 ==================
   9
  10 Compiling requires having installed:
  11  * clang
  12  * llvm
  13  * pahole
  14
  15 Consult :ref:`Documentation/process/changes.rst <changes>` for the minimum
  16 version numbers required and how to update them. Note that LLVM's tool
  17 'llc' must support target 'bpf', list version and supported targets with
  18 command: ``llc --version``
  19
  20 Clean and configuration
  21 -----------------------
  22
  23 It can be needed to clean tools, samples or kernel before trying new arch or
  24 after some changes (on demand)::
  25
  26  make -C tools clean
  27  make -C samples/bpf clean
  28  make clean
  29
  30 Configure kernel, defconfig for instance
  31 (see "tools/testing/selftests/bpf/config" for a reference config)::
  32
  33  make defconfig
  34
  35 Kernel headers
  36 --------------
  37
  38 There are usually dependencies to header files of the current kernel.
  39 To avoid installing devel kernel headers system wide, as a normal
  40 user, simply call::
  41
  42  make headers_install
  43
  44 This will create a local "usr/include" directory in the git/build top
  45 level directory, that the make system will automatically pick up first.
  46
  47 Compiling
  48 =========
  49
  50 For building the BPF samples, issue the below command from the kernel
  51 top level directory::
  52
  53  make M=samples/bpf
  54
  55 It is also possible to call make from this directory.  This will just
  56 hide the invocation of make as above.
  57
  58 Manually compiling LLVM with 'bpf' support
  59 ------------------------------------------
  60
  61 Since version 3.7.0, LLVM adds a proper LLVM backend target for the
  62 BPF bytecode architecture.
  63
  64 By default llvm will build all non-experimental backends including bpf.
  65 To generate a smaller llc binary one can use::
  66
  67  -DLLVM_TARGETS_TO_BUILD="BPF"
  68
  69 We recommend that developers who want the fastest incremental builds
  70 use the Ninja build system, you can find it in your system's package
  71 manager, usually the package is ninja or ninja-build.
  72
  73 Quick sniplet for manually compiling LLVM and clang
  74 (build dependencies are ninja, cmake and gcc-c++)::
  75
  76  $ git clone https://github.com/llvm/llvm-project.git
  77  $ mkdir -p llvm-project/llvm/build
  78  $ cd llvm-project/llvm/build
  79  $ cmake .. -G "Ninja" -DLLVM_TARGETS_TO_BUILD="BPF;X86" \
  80             -DLLVM_ENABLE_PROJECTS="clang"    \
  81             -DCMAKE_BUILD_TYPE=Release        \
  82             -DLLVM_BUILD_RUNTIME=OFF
  83  $ ninja
  84
  85 It is also possible to point make to the newly compiled 'llc' or
  86 'clang' command via redefining LLC or CLANG on the make command line::
  87
  88  make M=samples/bpf LLC=~/git/llvm-project/llvm/build/bin/llc CLANG=~/git/llvm-project/llvm/build/bin/clang
  89
  90 Cross compiling samples
  91 -----------------------
  92 In order to cross-compile, say for arm64 targets, export CROSS_COMPILE and ARCH
  93 environment variables before calling make. But do this before clean,
  94 configuration and header install steps described above. This will direct make to
  95 build samples for the cross target::
  96
  97  export ARCH=arm64
  98  export CROSS_COMPILE="aarch64-linux-gnu-"
  99
 100 Headers can be also installed on RFS of target board if need to keep them in
 101 sync (not necessarily and it creates a local "usr/include" directory also)::
 102
 103  make INSTALL_HDR_PATH=~/some_sysroot/usr headers_install
 104
 105 Pointing LLC and CLANG is not necessarily if it's installed on HOST and have
 106 in its targets appropriate arm64 arch (usually it has several arches).
 107 Build samples::
 108
 109  make M=samples/bpf
 110
 111 Or build samples with SYSROOT if some header or library is absent in toolchain,
 112 say libelf, providing address to file system containing headers and libs,
 113 can be RFS of target board::
 114
 115  make M=samples/bpf SYSROOT=~/some_sysroot