README.OpenSource
README.md
1<picture>
2 <source media="(prefers-color-scheme: dark)" srcset="assets/libbpf-logo-sideways-darkbg.png" width="40%">
3 <img src="assets/libbpf-logo-sideways.png" width="40%">
4</picture>
5
6libbpf
7[](https://github.com/libbpf/libbpf/actions/workflows/test.yml)
8[](https://scan.coverity.com/projects/libbpf)
9[](https://github.com/libbpf/libbpf/actions?query=workflow%3ACodeQL+branch%3Amaster)
10[](https://oss-fuzz-build-logs.storage.googleapis.com/index.html#libbpf)
11[](https://libbpf.readthedocs.io/en/latest/)
12======
13
14**This is the official home of the libbpf library.**
15
16*Please use this Github repository for building and packaging libbpf
17and when using it in your projects through Git submodule.*
18
19Libbpf *authoritative source code* is developed as part of [bpf-next Linux source
20tree](https://kernel.googlesource.com/pub/scm/linux/kernel/git/bpf/bpf-next) under
21`tools/lib/bpf` subdirectory and is periodically synced to Github. As such, all the
22libbpf changes should be sent to [BPF mailing list](http://vger.kernel.org/vger-lists.html#bpf),
23please don't open PRs here unless you are changing Github-specific parts of libbpf
24(e.g., Github-specific Makefile).
25
26Libbpf and general BPF usage questions
27======================================
28
29Libbpf documentation can be found [here](https://libbpf.readthedocs.io/en/latest/api.html).
30It's an ongoing effort and has ways to go, but please take a look and consider contributing as well.
31
32Please check out [libbpf-bootstrap](https://github.com/libbpf/libbpf-bootstrap)
33and [the companion blog post](https://nakryiko.com/posts/libbpf-bootstrap/) for
34the examples of building BPF applications with libbpf.
35[libbpf-tools](https://github.com/iovisor/bcc/tree/master/libbpf-tools) are also
36a good source of the real-world libbpf-based tracing tools.
37
38See also ["BPF CO-RE reference guide"](https://nakryiko.com/posts/bpf-core-reference-guide/)
39for the coverage of practical aspects of building BPF CO-RE applications and
40["BPF CO-RE"](https://nakryiko.com/posts/bpf-portability-and-co-re/) for
41general introduction into BPF portability issues and BPF CO-RE origins.
42
43All general BPF questions, including kernel functionality, libbpf APIs and
44their application, should be sent to bpf@vger.kernel.org mailing list. You can
45subscribe to it [here](http://vger.kernel.org/vger-lists.html#bpf) and search
46its archive [here](https://lore.kernel.org/bpf/). Please search the archive
47before asking new questions. It very well might be that this was already
48addressed or answered before.
49
50bpf@vger.kernel.org is monitored by many more people and they will happily try
51to help you with whatever issue you have. This repository's PRs and issues
52should be opened only for dealing with issues pertaining to specific way this
53libbpf mirror repo is set up and organized.
54
55Building libbpf
56===============
57libelf is an internal dependency of libbpf and thus it is required to link
58against and must be installed on the system for applications to work.
59pkg-config is used by default to find libelf, and the program called can be
60overridden with `PKG_CONFIG`.
61
62If using `pkg-config` at build time is not desired, it can be disabled by
63setting `NO_PKG_CONFIG=1` when calling make.
64
65To build both static libbpf.a and shared libbpf.so:
66```bash
67$ cd src
68$ make
69```
70
71To build only static libbpf.a library in directory
72build/ and install them together with libbpf headers in a staging directory
73root/:
74```bash
75$ cd src
76$ mkdir build root
77$ BUILD_STATIC_ONLY=y OBJDIR=build DESTDIR=root make install
78```
79
80To build both static libbpf.a and shared libbpf.so against a custom libelf
81dependency installed in /build/root/ and install them together with libbpf
82headers in a build directory /build/root/:
83```bash
84$ cd src
85$ PKG_CONFIG_PATH=/build/root/lib64/pkgconfig DESTDIR=/build/root make install
86```
87
88BPF CO-RE (Compile Once – Run Everywhere)
89=========================================
90
91Libbpf supports building BPF CO-RE-enabled applications, which, in contrast to
92[BCC](https://github.com/iovisor/bcc/), do not require Clang/LLVM runtime
93being deployed to target servers and doesn't rely on kernel-devel headers
94being available.
95
96It does rely on kernel to be built with [BTF type
97information](https://www.kernel.org/doc/html/latest/bpf/btf.html), though.
98Some major Linux distributions come with kernel BTF already built in:
99 - Fedora 31+
100 - RHEL 8.2+
101 - OpenSUSE Tumbleweed (in the next release, as of 2020-06-04)
102 - Arch Linux (from kernel 5.7.1.arch1-1)
103 - Manjaro (from kernel 5.4 if compiled after 2021-06-18)
104 - Ubuntu 20.10
105 - Debian 11 (amd64/arm64)
106
107If your kernel doesn't come with BTF built-in, you'll need to build custom
108kernel. You'll need:
109 - `pahole` 1.16+ tool (part of `dwarves` package), which performs DWARF to
110 BTF conversion;
111 - kernel built with `CONFIG_DEBUG_INFO_BTF=y` option;
112 - you can check if your kernel has BTF built-in by looking for
113 `/sys/kernel/btf/vmlinux` file:
114
115```shell
116$ ls -la /sys/kernel/btf/vmlinux
117-r--r--r--. 1 root root 3541561 Jun 2 18:16 /sys/kernel/btf/vmlinux
118```
119
120To develop and build BPF programs, you'll need Clang/LLVM 10+. The following
121distributions have Clang/LLVM 10+ packaged by default:
122 - Fedora 32+
123 - Ubuntu 20.04+
124 - Arch Linux
125 - Ubuntu 20.10 (LLVM 11)
126 - Debian 11 (LLVM 11)
127 - Alpine 3.13+
128
129Otherwise, please make sure to update it on your system.
130
131The following resources are useful to understand what BPF CO-RE is and how to
132use it:
133- [BPF CO-RE reference guide](https://nakryiko.com/posts/bpf-core-reference-guide/)
134- [BPF Portability and CO-RE](https://nakryiko.com/posts/bpf-portability-and-co-re/)
135- [HOWTO: BCC to libbpf conversion](https://nakryiko.com/posts/bcc-to-libbpf-howto-guide/)
136- [libbpf-tools in BCC repo](https://github.com/iovisor/bcc/tree/master/libbpf-tools)
137 contain lots of real-world tools converted from BCC to BPF CO-RE. Consider
138 converting some more to both contribute to the BPF community and gain some
139 more experience with it.
140
141Distributions
142=============
143
144Distributions packaging libbpf from this mirror:
145 - [Fedora](https://src.fedoraproject.org/rpms/libbpf)
146 - [Gentoo](https://packages.gentoo.org/packages/dev-libs/libbpf)
147 - [Debian](https://packages.debian.org/source/sid/libbpf)
148 - [Arch](https://archlinux.org/packages/core/x86_64/libbpf/)
149 - [Ubuntu](https://packages.ubuntu.com/source/impish/libbpf)
150 - [Alpine](https://pkgs.alpinelinux.org/packages?name=libbpf)
151
152Benefits of packaging from the mirror over packaging from kernel sources:
153 - Consistent versioning across distributions.
154 - No ties to any specific kernel, transparent handling of older kernels.
155 Libbpf is designed to be kernel-agnostic and work across multitude of
156 kernel versions. It has built-in mechanisms to gracefully handle older
157 kernels, that are missing some of the features, by working around or
158 gracefully degrading functionality. Thus libbpf is not tied to a specific
159 kernel version and can/should be packaged and versioned independently.
160 - Continuous integration testing via
161 [GitHub Actions](https://github.com/libbpf/libbpf/actions).
162 - Static code analysis via [LGTM](https://lgtm.com/projects/g/libbpf/libbpf)
163 and [Coverity](https://scan.coverity.com/projects/libbpf).
164
165Package dependencies of libbpf, package names may vary across distros:
166 - zlib
167 - libelf
168
169[](https://repology.org/project/libbpf/versions)
170
171
172bpf-next to Github sync
173=======================
174
175All the gory details of syncing can be found in `scripts/sync-kernel.sh`
176script.
177
178Some header files in this repo (`include/linux/*.h`) are reduced versions of
179their counterpart files at
180[bpf-next](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/)'s
181`tools/include/linux/*.h` to make compilation successful.
182
183License
184=======
185
186This work is dual-licensed under BSD 2-clause license and GNU LGPL v2.1 license.
187You can choose between one of them if you use this work.
188
189`SPDX-License-Identifier: BSD-2-Clause OR LGPL-2.1`
190
README_OH.md
1# libbpf
2
3仓库包含第三方开源软件libbpf，libbpf是eBPF技术的一种实现，eBPF提供给开发者一种内核事件和用户进程事件发生时安全注入代码的机制，避免开发者直接进行内核编程时可能导致的系统锁定、内存损坏、进程崩溃和安全漏洞等问题。开发者基于libbpf第三方开源库高效便捷开发eBPF程序，应用于网络过滤、程序跟踪、性能分析以及调试等需求场景。
4
5## 目录结构
6
7```
8docs/ 文档
9fuzz/ fuzz测试
10include/ 头文件
11scripts/ 脚本
12src/ 源文件
13LICENSE 证书文件
14README.md 英文说明
15README_zh.md 中文说明
16```
17
18## OpenHarmony如何集成libbpf
19
20### 1.头文件引入
21
22```
23#include "libbpf.h"
24#include "bpf.h"
25```
26
27### 2.BUILD.gn添加引用
28
29```
30deps += ["//third_party/libbpf:libbpf"]
31```
32### 3.示例代码
33```
34# kprobe.bpf.c BPF程序
35# 指定LICENSE
36char LICENSE[] SEC("license") = "Dual BSD/GPL";
37# 进入do_unlinkat函数时调用
38SEC("kprobe/do_unlinkat")
39int BPF_KPROBE(do_unlinkat, int dfd, struct filename *name)
40{
41 pid_t pid;
42 const char *filename;
43
44 pid = bpf_get_current_pid_tgid() >> 32;
45 filename = BPF_CORE_READ(name, name);
46 bpf_printk("KPROBE ENTRY pid = %d, filename = %s\n", pid, filename);
47 return 0;
48}
49# 退出do_unlinkat函数时调用
50SEC("kretprobe/do_unlinkat")
51int BPF_KRETPROBE(do_unlinkat_exit, long ret)
52{
53 pid_t pid;
54
55 pid = bpf_get_current_pid_tgid() >> 32;
56 bpf_printk("KPROBE EXIT: pid = %d, ret = %ld\n", pid, ret);
57 return 0;
58}
59```
60```
61# 用bpftool生成BPF skeleton脚手架文件
62$ bpftool gen skeleton kprobe.bpf.o > kprobe.skel.h
63```
64```
65# kprobe.c 将BPF程序加载进内核并附着到内核指定位置
66#include kprobe.skel.h
67struct kprobe_bpf *skel;
68int err;
69libbpf_set_strict_mode(LIBBPF_STRICT_ALL);
70/* 加载并验证BPF程序 */
71skel = kprobe_bpf__open_and_load();
72if (!skel) {
73 fprintf(stderr, "Failed to open BPF skeleton\n");
74 return 1;
75}
76/* 将BPF程序附加到跟踪点 */
77err = kprobe_bpf__attach(skel);
78/* 销毁和回收资源 */
79kprobe_bpf__destroy(skel);
80```
81## libbpf相关知识文档
82
83[bpf参考指南](https://nakryiko.com/posts/bpf-core-reference-guide/)
84
85[libbpf开发指导](https://nakryiko.com/posts/bcc-to-libbpf-howto-guide/)
86
87[libbpf开发示例](https://github.com/libbpf/libbpf-bootstrap)
88## License
89
90`SPDX-License-Identifier: BSD-2-Clause OR LGPL-2.1`
91
92
93
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}