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