Commit | Line | Data |
---|---|---|
1c97566d JDB |
1 | eBPF sample programs |
2 | ==================== | |
3 | ||
43371c83 JS |
4 | This directory contains a test stubs, verifier test-suite and examples |
5 | for using eBPF. The examples use libbpf from tools/lib/bpf. | |
1c97566d | 6 | |
5a9fd0f7 THJ |
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 | ||
1c97566d JDB |
13 | Build dependencies |
14 | ================== | |
15 | ||
16 | Compiling requires having installed: | |
89dc4037 ATP |
17 | * clang |
18 | * llvm | |
19 | * pahole | |
1c97566d | 20 | |
89dc4037 ATP |
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`` | |
1c97566d | 25 | |
1600c9c2 IK |
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 | ||
89dc4037 ATP |
36 | Configure kernel, defconfig for instance |
37 | (see "tools/testing/selftests/bpf/config" for a reference config):: | |
1600c9c2 IK |
38 | |
39 | make defconfig | |
40 | ||
1c97566d JDB |
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 | ||
2c4d72d6 DM |
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. | |
1c97566d JDB |
52 | |
53 | Compiling | |
54 | ========= | |
55 | ||
56 | For building the BPF samples, issue the below command from the kernel | |
57 | top level directory:: | |
58 | ||
6cc2c876 | 59 | make M=samples/bpf |
1c97566d | 60 | |
b62a796c | 61 | It is also possible to call make from this directory. This will just |
6cc2c876 | 62 | hide the invocation of make as above. |
b62a796c | 63 | |
1c97566d JDB |
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 | ||
628add78 TY |
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 | ||
1c97566d | 79 | Quick sniplet for manually compiling LLVM and clang |
628add78 | 80 | (build dependencies are ninja, cmake and gcc-c++):: |
1c97566d | 81 | |
628add78 TY |
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 | |
1c97566d | 90 | |
bdefbbf2 JDB |
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:: | |
1c97566d | 93 | |
628add78 | 94 | make M=samples/bpf LLC=~/git/llvm-project/llvm/build/bin/llc CLANG=~/git/llvm-project/llvm/build/bin/clang |
8bf2ac25 JF |
95 | |
96 | Cross compiling samples | |
97 | ----------------------- | |
98 | In order to cross-compile, say for arm64 targets, export CROSS_COMPILE and ARCH | |
1600c9c2 | 99 | environment variables before calling make. But do this before clean, |
3a07dcf8 | 100 | configuration and header install steps described above. This will direct make to |
1600c9c2 IK |
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 | ||
6cc2c876 | 115 | make M=samples/bpf |
1600c9c2 IK |
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:: | |
8bf2ac25 | 120 | |
6cc2c876 | 121 | make M=samples/bpf SYSROOT=~/some_sysroot |