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 Quick sniplet for manually compiling LLVM and clang
  66 (build dependencies are cmake and gcc-c++)::
  67
  68  $ git clone http://llvm.org/git/llvm.git
  69  $ cd llvm/tools
  70  $ git clone --depth 1 http://llvm.org/git/clang.git
  71  $ cd ..; mkdir build; cd build
  72  $ cmake .. -DLLVM_TARGETS_TO_BUILD="BPF;X86"
  73  $ make -j $(getconf _NPROCESSORS_ONLN)
  74
  75 It is also possible to point make to the newly compiled 'llc' or
  76 'clang' command via redefining LLC or CLANG on the make command line::
  77
  78  make M=samples/bpf LLC=~/git/llvm/build/bin/llc CLANG=~/git/llvm/build/bin/clang
  79
  80 Cross compiling samples
  81 -----------------------
  82 In order to cross-compile, say for arm64 targets, export CROSS_COMPILE and ARCH
  83 environment variables before calling make. But do this before clean,
  84 cofiguration and header install steps described above. This will direct make to
  85 build samples for the cross target::
  86
  87  export ARCH=arm64
  88  export CROSS_COMPILE="aarch64-linux-gnu-"
  89
  90 Headers can be also installed on RFS of target board if need to keep them in
  91 sync (not necessarily and it creates a local "usr/include" directory also)::
  92
  93  make INSTALL_HDR_PATH=~/some_sysroot/usr headers_install
  94
  95 Pointing LLC and CLANG is not necessarily if it's installed on HOST and have
  96 in its targets appropriate arm64 arch (usually it has several arches).
  97 Build samples::
  98
  99  make M=samples/bpf
 100
 101 Or build samples with SYSROOT if some header or library is absent in toolchain,
 102 say libelf, providing address to file system containing headers and libs,
 103 can be RFS of target board::
 104
 105  make M=samples/bpf SYSROOT=~/some_sysroot