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