diff --git a/README.md b/README.md index 987db99..3fd6a0d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 基于 libbpf 的 eBPF 开发者教程:通过 20 个小工具一步步学习 eBPF -这是一个基于 `CO-RE`(一次编译,到处运行)的 `libbpf` 的 eBPF 的开发教程,提供了从入门到进阶的 eBPF 开发实践,包括基本概念、代码实例、实际应用等内容。 +这是一个基于 `CO-RE`(一次编译,到处运行)的 `libbpf` 的 eBPF 的开发教程,提供了从入门到进阶的 eBPF 开发实践,包括基本概念、代码实例、实际应用等内容。除了通常的教程文本内容,我们也希望通过 ChatGPT 等工具,为您提供交互式的 eBPF 学习体验! 本教程不会进行复杂的概念讲解和场景介绍,主要希望提供一些 eBPF 小工具的案例(**非常短小,从二十行代码开始入门!**),来帮助 eBPF 应用的开发者快速上手 eBPF 的开发方法和技巧。教程内容可以在目录中找到,每个目录都是一个独立的 eBPF 工具案例。 @@ -12,7 +12,8 @@ Gitee 镜像: -> 我们还提供了一个使用 ChatGPT ,通过自然语言描述即可自动编写 eBPF 程序和追踪 Linux 系统的小工具,可以让您交互式地学习 eBPF 程序:[GPTtrace](https://github.com/eunomia-bpf/GPTtrace) +> - 我们还提供了一个使用 ChatGPT ,通过自然语言描述即可自动编写 eBPF 程序和追踪 Linux 系统的小工具,可以让您交互式地学习 eBPF 程序:[GPTtrace](https://github.com/eunomia-bpf/GPTtrace) +> - 欢迎在本仓库的 issue 或 discussion 中提出任意关于 eBPF 学习的疑惑和问题,或者生产实践中遇到的 bug,我们会尽力帮助您解答! ## 目录 diff --git a/bcc-documents/kernel-versions.md b/bcc-documents/kernel-versions.md new file mode 100644 index 0000000..23a9c55 --- /dev/null +++ b/bcc-documents/kernel-versions.md @@ -0,0 +1,507 @@ +# BPF Features by Linux Kernel Version + +## eBPF support + +Kernel version | Commit +---------------|------- +3.15 | [`bd4cf0ed331a`](https://github.com/torvalds/linux/commit/bd4cf0ed331a275e9bf5a49e6d0fd55dffc551b8) + +## JIT compiling + +The list of supported architectures for your kernel can be retrieved with: + + git grep HAVE_EBPF_JIT arch/ + +Feature / Architecture | Kernel version | Commit +-----------------------|----------------|------- +x86\_64 | 3.16 | [`622582786c9e`](https://github.com/torvalds/linux/commit/622582786c9e041d0bd52bde201787adeab249f8) +ARM64 | 3.18 | [`e54bcde3d69d`](https://github.com/torvalds/linux/commit/e54bcde3d69d40023ae77727213d14f920eb264a) +s390 | 4.1 | [`054623105728`](https://github.com/torvalds/linux/commit/054623105728b06852f077299e2bf1bf3d5f2b0b) +Constant blinding for JIT machines | 4.7 | [`4f3446bb809f`](https://github.com/torvalds/linux/commit/4f3446bb809f20ad56cadf712e6006815ae7a8f9) +PowerPC64 | 4.8 | [`156d0e290e96`](https://github.com/torvalds/linux/commit/156d0e290e969caba25f1851c52417c14d141b24) +Constant blinding - PowerPC64 | 4.9 | [`b7b7013cac55`](https://github.com/torvalds/linux/commit/b7b7013cac55d794940bd9cb7b7c55c9dececac4) +Sparc64 | 4.12 | [`7a12b5031c6b`](https://github.com/torvalds/linux/commit/7a12b5031c6b947cc13918237ae652b536243b76) +MIPS | 4.13 | [`f381bf6d82f0`](https://github.com/torvalds/linux/commit/f381bf6d82f032b7410185b35d000ea370ac706b) +ARM32 | 4.14 | [`39c13c204bb1`](https://github.com/torvalds/linux/commit/39c13c204bb1150d401e27d41a9d8b332be47c49) +x86\_32 | 4.18 | [`03f5781be2c7`](https://github.com/torvalds/linux/commit/03f5781be2c7b7e728d724ac70ba10799cc710d7) +RISC-V RV64G | 5.1 | [`2353ecc6f91f`](https://github.com/torvalds/linux/commit/2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2) +RISC-V RV32G | 5.7 | [`5f316b65e99f`](https://github.com/torvalds/linux/commit/5f316b65e99f109942c556dc8790abd4c75bcb34) +PowerPC32 | 5.13 | [`51c66ad849a7`](https://github.com/torvalds/linux/commit/51c66ad849a703d9bbfd7704c941827aed0fd9fd) +LoongArch | 6.1 | [`5dc615520c4d`](https://github.com/torvalds/linux/commit/5dc615520c4dfb358245680f1904bad61116648e) + +## Main features + +Several (but not all) of these _main features_ translate to an eBPF program type. +The list of such program types supported in your kernel can be found in file +[`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): + + git grep -W 'bpf_prog_type {' include/uapi/linux/bpf.h + +Feature | Kernel version | Commit +--------|----------------|------- +`AF_PACKET` (libpcap/tcpdump, `cls_bpf` classifier, netfilter's `xt_bpf`, team driver's load-balancing mode…) | 3.15 | [`bd4cf0ed331a`](https://github.com/torvalds/linux/commit/bd4cf0ed331a275e9bf5a49e6d0fd55dffc551b8) +Kernel helpers | 3.15 | [`bd4cf0ed331a`](https://github.com/torvalds/linux/commit/bd4cf0ed331a275e9bf5a49e6d0fd55dffc551b8) +`bpf()` syscall | 3.18 | [`99c55f7d47c0`](https://github.com/torvalds/linux/commit/99c55f7d47c0dc6fc64729f37bf435abf43f4c60) +Maps (_a.k.a._ Tables; details below) | 3.18 | [`99c55f7d47c0`](https://github.com/torvalds/linux/commit/99c55f7d47c0dc6fc64729f37bf435abf43f4c60) +BPF attached to sockets | 3.19 | [`89aa075832b0`](https://github.com/torvalds/linux/commit/89aa075832b0da4402acebd698d0411dcc82d03e) +BPF attached to `kprobes` | 4.1 | [`2541517c32be`](https://github.com/torvalds/linux/commit/2541517c32be2531e0da59dfd7efc1ce844644f5) +`cls_bpf` / `act_bpf` for `tc` | 4.1 | [`e2e9b6541dd4`](https://github.com/torvalds/linux/commit/e2e9b6541dd4b31848079da80fe2253daaafb549) +Tail calls | 4.2 | [`04fd61ab36ec`](https://github.com/torvalds/linux/commit/04fd61ab36ec065e194ab5e74ae34a5240d992bb) +Non-root programs on sockets | 4.4 | [`1be7f75d1668`](https://github.com/torvalds/linux/commit/1be7f75d1668d6296b80bf35dcf6762393530afc) +Persistent maps and programs (virtual FS) | 4.4 | [`b2197755b263`](https://github.com/torvalds/linux/commit/b2197755b2633e164a439682fb05a9b5ea48f706) +`tc`'s `direct-action` (`da`) mode | 4.4 | [`045efa82ff56`](https://github.com/torvalds/linux/commit/045efa82ff563cd4e656ca1c2e354fa5bf6bbda4) +`tc`'s `clsact` qdisc | 4.5 | [`1f211a1b929c`](https://github.com/torvalds/linux/commit/1f211a1b929c804100e138c5d3d656992cfd5622) +BPF attached to tracepoints | 4.7 | [`98b5c2c65c29`](https://github.com/torvalds/linux/commit/98b5c2c65c2951772a8fc661f50d675e450e8bce) +Direct packet access | 4.7 | [`969bf05eb3ce`](https://github.com/torvalds/linux/commit/969bf05eb3cedd5a8d4b7c346a85c2ede87a6d6d) +XDP (see below) | 4.8 | [`6a773a15a1e8`](https://github.com/torvalds/linux/commit/6a773a15a1e8874e5eccd2f29190c31085912c95) +BPF attached to perf events | 4.9 | [`0515e5999a46`](https://github.com/torvalds/linux/commit/0515e5999a466dfe6e1924f460da599bb6821487) +Hardware offload for `tc`'s `cls_bpf` | 4.9 | [`332ae8e2f6ec`](https://github.com/torvalds/linux/commit/332ae8e2f6ecda5e50c5c62ed62894963e3a83f5) +Verifier exposure and internal hooks | 4.9 | [`13a27dfc6697`](https://github.com/torvalds/linux/commit/13a27dfc669724564aafa2699976ee756029fed2) +BPF attached to cgroups for socket filtering | 4.10 | [`0e33661de493`](https://github.com/torvalds/linux/commit/0e33661de493db325435d565a4a722120ae4cbf3) +Lightweight tunnel encapsulation | 4.10 | [`3a0af8fd61f9`](https://github.com/torvalds/linux/commit/3a0af8fd61f90920f6fa04e4f1e9a6a73c1b4fd2) +**e**BPF support for `xt_bpf` module (iptables) | 4.10 | [`2c16d6033264`](https://github.com/torvalds/linux/commit/2c16d60332643e90d4fa244f4a706c454b8c7569) +BPF program tag | 4.10 | [`7bd509e311f4`](https://github.com/torvalds/linux/commit/7bd509e311f408f7a5132fcdde2069af65fa05ae) +Tracepoints to debug BPF | 4.11 (removed in 4.18) | [`a67edbf4fb6d`](https://github.com/torvalds/linux/commit/a67edbf4fb6deadcfe57a04a134abed4a5ba3bb5) [`4d220ed0f814`](https://github.com/torvalds/linux/commit/4d220ed0f8140c478ab7b0a14d96821da639b646) +Testing / benchmarking BPF programs | 4.12 | [`1cf1cae963c2`](https://github.com/torvalds/linux/commit/1cf1cae963c2e6032aebe1637e995bc2f5d330f4) +BPF programs and maps IDs | 4.13 | [`dc4bb0e23561`](https://github.com/torvalds/linux/commit/dc4bb0e2356149aee4cdae061936f3bbdd45595c) +BPF support for `sock_ops` | 4.13 | [`40304b2a1567`](https://github.com/torvalds/linux/commit/40304b2a1567fecc321f640ee4239556dd0f3ee0) +BPF support for skbs on sockets | 4.14 | [`b005fd189cec`](https://github.com/torvalds/linux/commit/b005fd189cec9407b700599e1e80e0552446ee79) +bpftool utility in kernel sources | 4.15 | [`71bb428fe2c1`](https://github.com/torvalds/linux/commit/71bb428fe2c19512ac671d5ee16ef3e73e1b49a8) +BPF attached to cgroups as device controller | 4.15 | [`ebc614f68736`](https://github.com/torvalds/linux/commit/ebc614f687369f9df99828572b1d85a7c2de3d92) +bpf2bpf function calls | 4.16 | [`cc8b0b92a169`](https://github.com/torvalds/linux/commit/cc8b0b92a1699bc32f7fec71daa2bfc90de43a4d) +BPF used for monitoring socket RX/TX data | 4.17 | [`4f738adba30a`](https://github.com/torvalds/linux/commit/4f738adba30a7cfc006f605707e7aee847ffefa0) +BPF attached to raw tracepoints | 4.17 | [`c4f6699dfcb8`](https://github.com/torvalds/linux/commit/c4f6699dfcb8558d138fe838f741b2c10f416cf9) +BPF attached to `bind()` system call | 4.17 | [`4fbac77d2d09`](https://github.com/torvalds/linux/commit/4fbac77d2d092b475dda9eea66da674369665427) [`aac3fc320d94`](https://github.com/torvalds/linux/commit/aac3fc320d9404f2665a8b1249dc3170d5fa3caf) +BPF attached to `connect()` system call | 4.17 | [`d74bad4e74ee`](https://github.com/torvalds/linux/commit/d74bad4e74ee373787a9ae24197c17b7cdc428d5) +BPF Type Format (BTF) | 4.18 | [`69b693f0aefa`](https://github.com/torvalds/linux/commit/69b693f0aefa0ed521e8bd02260523b5ae446ad7) +AF_XDP | 4.18 | [`fbfc504a24f5`](https://github.com/torvalds/linux/commit/fbfc504a24f53f7ebe128ab55cb5dba634f4ece8) +bpfilter | 4.18 | [`d2ba09c17a06`](https://github.com/torvalds/linux/commit/d2ba09c17a0647f899d6c20a11bab9e6d3382f07) +End.BPF action for seg6local LWT | 4.18 | [`004d4b274e2a`](https://github.com/torvalds/linux/commit/004d4b274e2a1a895a0e5dc66158b90a7d463d44) +BPF attached to LIRC devices | 4.18 | [`f4364dcfc86d`](https://github.com/torvalds/linux/commit/f4364dcfc86df7c1ca47b256eaf6b6d0cdd0d936) +Pass map values to map helpers | 4.18 | [`d71962f3e627`](https://github.com/torvalds/linux/commit/d71962f3e627b5941804036755c844fabfb65ff5) +BPF socket reuseport | 4.19 | [`2dbb9b9e6df6`](https://github.com/torvalds/linux/commit/2dbb9b9e6df67d444fbe425c7f6014858d337adf) +BPF flow dissector | 4.20 | [`d58e468b1112`](https://github.com/torvalds/linux/commit/d58e468b1112dcd1d5193c0a89ff9f98b5a3e8b9) +BPF 1M insn limit | 5.2 | [`c04c0d2b968a`](https://github.com/torvalds/linux/commit/c04c0d2b968ac45d6ef020316808ef6c82325a82) +BPF cgroup sysctl | 5.2 | [`7b146cebe30c`](https://github.com/torvalds/linux/commit/7b146cebe30cb481b0f70d85779da938da818637) +BPF raw tracepoint writable | 5.2 | [`9df1c28bb752`](https://github.com/torvalds/linux/commit/9df1c28bb75217b244257152ab7d788bb2a386d0) +BPF bounded loop | 5.3 | [`2589726d12a1`](https://github.com/torvalds/linux/commit/2589726d12a1b12eaaa93c7f1ea64287e383c7a5) +BPF trampoline | 5.5 | [`fec56f5890d9`](https://github.com/torvalds/linux/commit/fec56f5890d93fc2ed74166c397dc186b1c25951) +BPF LSM hook | 5.7 | [`fc611f47f218`](https://github.com/torvalds/linux/commit/fc611f47f2188ade2b48ff6902d5cce8baac0c58) [`641cd7b06c91`](https://github.com/torvalds/linux/commit/641cd7b06c911c5935c34f24850ea18690649917) +BPF iterator | 5.8 | [`180139dca8b3`](https://github.com/torvalds/linux/commit/180139dca8b38c858027b8360ee10064fdb2fbf7) +BPF socket lookup hook | 5.9 | [`e9ddbb7707ff`](https://github.com/torvalds/linux/commit/e9ddbb7707ff5891616240026062b8c1e29864ca) +Sleepable BPF programs | 5.10 | [`1e6c62a88215`](https://github.com/torvalds/linux/commit/1e6c62a8821557720a9b2ea9617359b264f2f67c) + +### Program types + +Program type | Kernel version | Commit | Enum +-------------|----------------|--------|----- +Socket filter | 3.19 | [`ddd872bc3098`](https://github.com/torvalds/linux/commit/ddd872bc3098f9d9abe1680a6b2013e59e3337f7) | BPF_PROG_TYPE_SOCKET_FILTER +Kprobe | 4.1 | [`2541517c32be`](https://github.com/torvalds/linux/commit/2541517c32be2531e0da59dfd7efc1ce844644f5) | BPF_PROG_TYPE_KPROBE +traffic control (TC) | 4.1 | [`96be4325f443`](https://github.com/torvalds/linux/commit/96be4325f443dbbfeb37d2a157675ac0736531a1) | BPF_PROG_TYPE_SCHED_CLS +traffic control (TC) | 4.1 | [`94caee8c312d`](https://github.com/torvalds/linux/commit/94caee8c312d96522bcdae88791aaa9ebcd5f22c) | BPF_PROG_TYPE_SCHED_ACT +Tracepoint | 4.7 | [`98b5c2c65c29`](https://github.com/torvalds/linux/commit/98b5c2c65c2951772a8fc661f50d675e450e8bce) | BPF_PROG_TYPE_TRACEPOINT +XDP | 4.8 | [`6a773a15a1e8`](https://github.com/torvalds/linux/commit/6a773a15a1e8874e5eccd2f29190c31085912c95) | BPF_PROG_TYPE_XDP +Perf event | 4.9 | [`0515e5999a46`](https://github.com/torvalds/linux/commit/0515e5999a466dfe6e1924f460da599bb6821487) | BPF_PROG_TYPE_PERF_EVENT +cgroup socket filtering | 4.10 | [`0e33661de493`](https://github.com/torvalds/linux/commit/0e33661de493db325435d565a4a722120ae4cbf3) | BPF_PROG_TYPE_CGROUP_SKB +cgroup sock modification | 4.10 | [`610236587600`](https://github.com/torvalds/linux/commit/61023658760032e97869b07d54be9681d2529e77) | BPF_PROG_TYPE_CGROUP_SOCK +lightweight tunnel (IN) | 4.10 | [`3a0af8fd61f9`](https://github.com/torvalds/linux/commit/3a0af8fd61f90920f6fa04e4f1e9a6a73c1b4fd2) | BPF_PROG_TYPE_LWT_IN +lightweight tunnel (OUT) | 4.10 | [`3a0af8fd61f9`](https://github.com/torvalds/linux/commit/3a0af8fd61f90920f6fa04e4f1e9a6a73c1b4fd2) | BPF_PROG_TYPE_LWT_OUT +lightweight tunnel (XMIT) | 4.10 | [`3a0af8fd61f9`](https://github.com/torvalds/linux/commit/3a0af8fd61f90920f6fa04e4f1e9a6a73c1b4fd2) | BPF_PROG_TYPE_LWT_XMIT +cgroup sock ops (per conn) | 4.13 | [`40304b2a1567`](https://github.com/torvalds/linux/commit/40304b2a1567fecc321f640ee4239556dd0f3ee0) | BPF_PROG_TYPE_SOCK_OPS +stream parser / stream verdict | 4.14 | [`b005fd189cec`](https://github.com/torvalds/linux/commit/b005fd189cec9407b700599e1e80e0552446ee79) | BPF_PROG_TYPE_SK_SKB +cgroup device manager | 4.15 | [`ebc614f68736`](https://github.com/torvalds/linux/commit/ebc614f687369f9df99828572b1d85a7c2de3d92) | BPF_PROG_TYPE_CGROUP_DEVICE +socket msg verdict | 4.17 | [`4f738adba30a`](https://github.com/torvalds/linux/commit/4f738adba30a7cfc006f605707e7aee847ffefa0) | BPF_PROG_TYPE_SK_MSG +Raw tracepoint | 4.17 | [`c4f6699dfcb8`](https://github.com/torvalds/linux/commit/c4f6699dfcb8558d138fe838f741b2c10f416cf9) | BPF_PROG_TYPE_RAW_TRACEPOINT +socket binding | 4.17 | [`4fbac77d2d09`](https://github.com/torvalds/linux/commit/4fbac77d2d092b475dda9eea66da674369665427) | BPF_PROG_TYPE_CGROUP_SOCK_ADDR +LWT seg6local | 4.18 | [`004d4b274e2a`](https://github.com/torvalds/linux/commit/004d4b274e2a1a895a0e5dc66158b90a7d463d44) | BPF_PROG_TYPE_LWT_SEG6LOCAL +lirc devices | 4.18 | [`f4364dcfc86d`](https://github.com/torvalds/linux/commit/f4364dcfc86df7c1ca47b256eaf6b6d0cdd0d936) | BPF_PROG_TYPE_LIRC_MODE2 +lookup SO_REUSEPORT socket | 4.19 | [`2dbb9b9e6df6`](https://github.com/torvalds/linux/commit/2dbb9b9e6df67d444fbe425c7f6014858d337adf) | BPF_PROG_TYPE_SK_REUSEPORT +flow dissector | 4.20 | [`d58e468b1112`](https://github.com/torvalds/linux/commit/d58e468b1112dcd1d5193c0a89ff9f98b5a3e8b9) | BPF_PROG_TYPE_FLOW_DISSECTOR +cgroup sysctl | 5.2 | [`7b146cebe30c`](https://github.com/torvalds/linux/commit/7b146cebe30cb481b0f70d85779da938da818637) | BPF_PROG_TYPE_CGROUP_SYSCTL +writable raw tracepoints | 5.2 | [`9df1c28bb752`](https://github.com/torvalds/linux/commit/9df1c28bb75217b244257152ab7d788bb2a386d0) | BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE +cgroup getsockopt/setsockopt | 5.3 | [`0d01da6afc54`](https://github.com/torvalds/linux/commit/0d01da6afc5402f60325c5da31b22f7d56689b49) | BPF_PROG_TYPE_CGROUP_SOCKOPT +Tracing (BTF/BPF trampoline) | 5.5 | [`f1b9509c2fb0`](https://github.com/torvalds/linux/commit/f1b9509c2fb0ef4db8d22dac9aef8e856a5d81f6) | BPF_PROG_TYPE_TRACING +struct ops | 5.6 | [`27ae7997a661`](https://github.com/torvalds/linux/commit/27ae7997a66174cb8afd6a75b3989f5e0c1b9e5a) | BPF_PROG_TYPE_STRUCT_OPS +extensions | 5.6 | [`be8704ff07d2`](https://github.com/torvalds/linux/commit/be8704ff07d2374bcc5c675526f95e70c6459683) | BPF_PROG_TYPE_EXT +LSM | 5.7 | [`fc611f47f218`](https://github.com/torvalds/linux/commit/fc611f47f2188ade2b48ff6902d5cce8baac0c58) | BPF_PROG_TYPE_LSM +lookup listening socket | 5.9 | [`e9ddbb7707ff`](https://github.com/torvalds/linux/commit/e9ddbb7707ff5891616240026062b8c1e29864ca) | BPF_PROG_TYPE_SK_LOOKUP +Allow executing syscalls | 5.15 | [`79a7f8bdb159`](https://github.com/torvalds/linux/commit/79a7f8bdb159d9914b58740f3d31d602a6e4aca8) | BPF_PROG_TYPE_SYSCALL + +## Maps (_a.k.a._ Tables, in BCC lingo) + +### Map types + +The list of map types supported in your kernel can be found in file +[`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): + + git grep -W 'bpf_map_type {' include/uapi/linux/bpf.h + + Map type | Kernel version | Commit | Enum +----------|----------------|--------|------ +Hash | 3.19 | [`0f8e4bd8a1fc`](https://github.com/torvalds/linux/commit/0f8e4bd8a1fc8c4185f1630061d0a1f2d197a475) | BPF_MAP_TYPE_HASH +Array | 3.19 | [`28fbcfa08d8e`](https://github.com/torvalds/linux/commit/28fbcfa08d8ed7c5a50d41a0433aad222835e8e3) | BPF_MAP_TYPE_ARRAY +Prog array | 4.2 | [`04fd61ab36ec`](https://github.com/torvalds/linux/commit/04fd61ab36ec065e194ab5e74ae34a5240d992bb) | BPF_MAP_TYPE_PROG_ARRAY +Perf events | 4.3 | [`ea317b267e9d`](https://github.com/torvalds/linux/commit/ea317b267e9d03a8241893aa176fba7661d07579) | BPF_MAP_TYPE_PERF_EVENT_ARRAY +Per-CPU hash | 4.6 | [`824bd0ce6c7c`](https://github.com/torvalds/linux/commit/824bd0ce6c7c43a9e1e210abf124958e54d88342) | BPF_MAP_TYPE_PERCPU_HASH +Per-CPU array | 4.6 | [`a10423b87a7e`](https://github.com/torvalds/linux/commit/a10423b87a7eae75da79ce80a8d9475047a674ee) | BPF_MAP_TYPE_PERCPU_ARRAY +Stack trace | 4.6 | [`d5a3b1f69186`](https://github.com/torvalds/linux/commit/d5a3b1f691865be576c2bffa708549b8cdccda19) | BPF_MAP_TYPE_STACK_TRACE +cgroup array | 4.8 | [`4ed8ec521ed5`](https://github.com/torvalds/linux/commit/4ed8ec521ed57c4e207ad464ca0388776de74d4b) | BPF_MAP_TYPE_CGROUP_ARRAY +LRU hash | 4.10 | [`29ba732acbee`](https://github.com/torvalds/linux/commit/29ba732acbeece1e34c68483d1ec1f3720fa1bb3) [`3a08c2fd7634`](https://github.com/torvalds/linux/commit/3a08c2fd763450a927d1130de078d6f9e74944fb) | BPF_MAP_TYPE_LRU_HASH +LRU per-CPU hash | 4.10 | [`8f8449384ec3`](https://github.com/torvalds/linux/commit/8f8449384ec364ba2a654f11f94e754e4ff719e0) [`961578b63474`](https://github.com/torvalds/linux/commit/961578b63474d13ad0e2f615fcc2901c5197dda6) | BPF_MAP_TYPE_LRU_PERCPU_HASH +LPM trie (longest-prefix match) | 4.11 | [`b95a5c4db09b`](https://github.com/torvalds/linux/commit/b95a5c4db09bc7c253636cb84dc9b12c577fd5a0) | BPF_MAP_TYPE_LPM_TRIE +Array of maps | 4.12 | [`56f668dfe00d`](https://github.com/torvalds/linux/commit/56f668dfe00dcf086734f1c42ea999398fad6572) | BPF_MAP_TYPE_ARRAY_OF_MAPS +Hash of maps | 4.12 | [`bcc6b1b7ebf8`](https://github.com/torvalds/linux/commit/bcc6b1b7ebf857a9fe56202e2be3361131588c15) | BPF_MAP_TYPE_HASH_OF_MAPS +Netdevice references (array) | 4.14 | [`546ac1ffb70d`](https://github.com/torvalds/linux/commit/546ac1ffb70d25b56c1126940e5ec639c4dd7413) | BPF_MAP_TYPE_DEVMAP +Socket references (array) | 4.14 | [`174a79ff9515`](https://github.com/torvalds/linux/commit/174a79ff9515f400b9a6115643dafd62a635b7e6) | BPF_MAP_TYPE_SOCKMAP +CPU references | 4.15 | [`6710e1126934`](https://github.com/torvalds/linux/commit/6710e1126934d8b4372b4d2f9ae1646cd3f151bf) | BPF_MAP_TYPE_CPUMAP +AF_XDP socket (XSK) references | 4.18 | [`fbfc504a24f5`](https://github.com/torvalds/linux/commit/fbfc504a24f53f7ebe128ab55cb5dba634f4ece8) | BPF_MAP_TYPE_XSKMAP +Socket references (hashmap) | 4.18 | [`81110384441a`](https://github.com/torvalds/linux/commit/81110384441a59cff47430f20f049e69b98c17f4) | BPF_MAP_TYPE_SOCKHASH +cgroup storage | 4.19 | [`de9cbbaadba5`](https://github.com/torvalds/linux/commit/de9cbbaadba5adf88a19e46df61f7054000838f6) | BPF_MAP_TYPE_CGROUP_STORAGE +reuseport sockarray | 4.19 | [`5dc4c4b7d4e8`](https://github.com/torvalds/linux/commit/5dc4c4b7d4e8115e7cde96a030f98cb3ab2e458c) | BPF_MAP_TYPE_REUSEPORT_SOCKARRAY +precpu cgroup storage | 4.20 | [`b741f1630346`](https://github.com/torvalds/linux/commit/b741f1630346defcbc8cc60f1a2bdae8b3b0036f) | BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE +queue | 4.20 | [`f1a2e44a3aec`](https://github.com/torvalds/linux/commit/f1a2e44a3aeccb3ff18d3ccc0b0203e70b95bd92) | BPF_MAP_TYPE_QUEUE +stack | 4.20 | [`f1a2e44a3aec`](https://github.com/torvalds/linux/commit/f1a2e44a3aeccb3ff18d3ccc0b0203e70b95bd92) | BPF_MAP_TYPE_STACK +socket local storage | 5.2 | [`6ac99e8f23d4`](https://github.com/torvalds/linux/commit/6ac99e8f23d4b10258406ca0dd7bffca5f31da9d) | BPF_MAP_TYPE_SK_STORAGE +Netdevice references (hashmap) | 5.4 | [`6f9d451ab1a3`](https://github.com/torvalds/linux/commit/6f9d451ab1a33728adb72d7ff66a7b374d665176) | BPF_MAP_TYPE_DEVMAP_HASH +struct ops | 5.6 | [`85d33df357b6`](https://github.com/torvalds/linux/commit/85d33df357b634649ddbe0a20fd2d0fc5732c3cb) | BPF_MAP_TYPE_STRUCT_OPS +ring buffer | 5.8 | [`457f44363a88`](https://github.com/torvalds/linux/commit/457f44363a8894135c85b7a9afd2bd8196db24ab) | BPF_MAP_TYPE_RINGBUF +inode storage | 5.10 | [`8ea636848aca`](https://github.com/torvalds/linux/commit/8ea636848aca35b9f97c5b5dee30225cf2dd0fe6) | BPF_MAP_TYPE_INODE_STORAGE +task storage | 5.11 | [`4cf1bc1f1045`](https://github.com/torvalds/linux/commit/4cf1bc1f10452065a29d576fc5693fc4fab5b919) | BPF_MAP_TYPE_TASK_STORAGE +Bloom filter | 5.16 | [`9330986c0300`](https://github.com/torvalds/linux/commit/9330986c03006ab1d33d243b7cfe598a7a3c1baa) | BPF_MAP_TYPE_BLOOM_FILTER +user ringbuf | 6.1 | [`583c1f420173`](https://github.com/torvalds/linux/commit/583c1f420173f7d84413a1a1fbf5109d798b4faa) | BPF_MAP_TYPE_USER_RINGBUF + +### Map userspace API + +Some (but not all) of these *API features* translate to a subcommand beginning with `BPF_MAP_`. +The list of subcommands supported in your kernel can be found in file +[`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): + + git grep -W 'bpf_cmd {' include/uapi/linux/bpf.h + +Feature | Kernel version | Commit +--------|----------------|------- +Basic operations (lookup, update, delete, `GET_NEXT_KEY`) | 3.18 | [`db20fd2b0108`](https://github.com/torvalds/linux/commit/db20fd2b01087bdfbe30bce314a198eefedcc42e) +Pass flags to `UPDATE_ELEM` | 3.19 | [`3274f52073d8`](https://github.com/torvalds/linux/commit/3274f52073d88b62f3c5ace82ae9d48546232e72) +Pre-alloc map memory by default | 4.6 | [`6c9059817432`](https://github.com/torvalds/linux/commit/6c90598174322b8888029e40dd84a4eb01f56afe) +Pass `NULL` to `GET_NEXT_KEY` | 4.12 | [`8fe45924387b`](https://github.com/torvalds/linux/commit/8fe45924387be6b5c1be59a7eb330790c61d5d10) +Creation: select NUMA node | 4.14 | [`96eabe7a40aa`](https://github.com/torvalds/linux/commit/96eabe7a40aa17e613cf3db2c742ee8b1fc764d0) +Restrict access from syscall side | 4.15 | [`6e71b04a8224`](https://github.com/torvalds/linux/commit/6e71b04a82248ccf13a94b85cbc674a9fefe53f5) +Creation: specify map name | 4.15 | [`ad5b177bd73f`](https://github.com/torvalds/linux/commit/ad5b177bd73f5107d97c36f56395c4281fb6f089) +`LOOKUP_AND_DELETE_ELEM` | 4.20 | [`bd513cd08f10`](https://github.com/torvalds/linux/commit/bd513cd08f10cbe28856f99ae951e86e86803861) +Creation: `BPF_F_ZERO_SEED` | 5.0 | [`96b3b6c9091d`](https://github.com/torvalds/linux/commit/96b3b6c9091d23289721350e32c63cc8749686be) +`BPF_F_LOCK` flag for lookup / update | 5.1 | [`96049f3afd50`](https://github.com/torvalds/linux/commit/96049f3afd50fe8db69fa0068cdca822e747b1e4) +Restrict access from BPF side | 5.2 | [`591fe9888d78`](https://github.com/torvalds/linux/commit/591fe9888d7809d9ee5c828020b6c6ae27c37229) +`FREEZE` | 5.2 | [`87df15de441b`](https://github.com/torvalds/linux/commit/87df15de441bd4add7876ef584da8cabdd9a042a) +mmap() support for array maps | 5.5 | [`fc9702273e2e`](https://github.com/torvalds/linux/commit/fc9702273e2edb90400a34b3be76f7b08fa3344b) +`LOOKUP_BATCH` | 5.6 | [`cb4d03ab499d`](https://github.com/torvalds/linux/commit/cb4d03ab499d4c040f4ab6fd4389d2b49f42b5a5) +`UPDATE_BATCH`, `DELETE_BATCH` | 5.6 | [`aa2e93b8e58e`](https://github.com/torvalds/linux/commit/aa2e93b8e58e18442edfb2427446732415bc215e) +`LOOKUP_AND_DELETE_BATCH` | 5.6 | [`057996380a42`](https://github.com/torvalds/linux/commit/057996380a42bb64ccc04383cfa9c0ace4ea11f0) +`LOOKUP_AND_DELETE_ELEM` support for hash maps | 5.14 | [`3e87f192b405`](https://github.com/torvalds/linux/commit/3e87f192b405960c0fe83e0925bd0dadf4f8cf43) + +## XDP + +An approximate list of drivers or components supporting XDP programs for your +kernel can be retrieved with: + + git grep -l XDP_SETUP_PROG drivers/ + +Feature / Driver | Kernel version | Commit +-----------------|----------------|------- +XDP core architecture | 4.8 | [`6a773a15a1e8`](https://github.com/torvalds/linux/commit/6a773a15a1e8874e5eccd2f29190c31085912c95) +Action: drop | 4.8 | [`6a773a15a1e8`](https://github.com/torvalds/linux/commit/6a773a15a1e8874e5eccd2f29190c31085912c95) +Action: pass on to stack | 4.8 | [`6a773a15a1e8`](https://github.com/torvalds/linux/commit/6a773a15a1e8874e5eccd2f29190c31085912c95) +Action: direct forwarding (on same port) | 4.8 | [`6ce96ca348a9`](https://github.com/torvalds/linux/commit/6ce96ca348a9e949f8c43f4d3e98db367d93cffd) +Direct packet data write | 4.8 | [`4acf6c0b84c9`](https://github.com/torvalds/linux/commit/4acf6c0b84c91243c705303cd9ff16421914150d) +Mellanox `mlx4` driver | 4.8 | [`47a38e155037`](https://github.com/torvalds/linux/commit/47a38e155037f417c5740e24ccae6482aedf4b68) +Mellanox `mlx5` driver | 4.9 | [`86994156c736`](https://github.com/torvalds/linux/commit/86994156c736978d113e7927455d4eeeb2128b9f) +Netronome `nfp` driver | 4.10 | [`ecd63a0217d5`](https://github.com/torvalds/linux/commit/ecd63a0217d5f1e8a92f7516f5586d1177b95de2) +QLogic (Cavium) `qed*` drivers | 4.10 | [`496e05170958`](https://github.com/torvalds/linux/commit/496e051709588f832d7a6a420f44f8642b308a87) +`virtio_net` driver | 4.10 | [`f600b6905015`](https://github.com/torvalds/linux/commit/f600b690501550b94e83e07295d9c8b9c4c39f4e) +Broadcom `bnxt_en` driver | 4.11 | [`c6d30e8391b8`](https://github.com/torvalds/linux/commit/c6d30e8391b85e00eb544e6cf047ee0160ee9938) +Intel `ixgbe*` drivers | 4.12 | [`924708081629`](https://github.com/torvalds/linux/commit/9247080816297de4e31abb684939c0e53e3a8a67) +Cavium `thunderx` driver | 4.12 | [`05c773f52b96`](https://github.com/torvalds/linux/commit/05c773f52b96ef3fbc7d9bfa21caadc6247ef7a8) +Generic XDP | 4.12 | [`b5cdae3291f7`](https://github.com/torvalds/linux/commit/b5cdae3291f7be7a34e75affe4c0ec1f7f328b64) +Intel `i40e` driver | 4.13 | [`0c8493d90b6b`](https://github.com/torvalds/linux/commit/0c8493d90b6bb0f5c4fe9217db8f7203f24c0f28) +Action: redirect | 4.14 | [`6453073987ba`](https://github.com/torvalds/linux/commit/6453073987ba392510ab6c8b657844a9312c67f7) +Support for tap | 4.14 | [`761876c857cb`](https://github.com/torvalds/linux/commit/761876c857cb2ef8489fbee01907151da902af91) +Support for veth | 4.14 | [`d445516966dc`](https://github.com/torvalds/linux/commit/d445516966dcb2924741b13b27738b54df2af01a) +Intel `ixgbevf` driver | 4.17 | [`c7aec59657b6`](https://github.com/torvalds/linux/commit/c7aec59657b60f3a29fc7d3274ebefd698879301) +Freescale `dpaa2` driver | 5.0 | [`7e273a8ebdd3`](https://github.com/torvalds/linux/commit/7e273a8ebdd3b83f94eb8b49fc8ee61464f47cc2) +Socionext `netsec` driver | 5.3 | [`ba2b232108d3`](https://github.com/torvalds/linux/commit/ba2b232108d3c2951bab02930a00f23b0cffd5af) +TI `cpsw` driver | 5.3 | [`9ed4050c0d75`](https://github.com/torvalds/linux/commit/9ed4050c0d75768066a07cf66eef4f8dc9d79b52) +Intel `ice` driver |5.5| [`efc2214b6047`](https://github.com/torvalds/linux/commit/efc2214b6047b6f5b4ca53151eba62521b9452d6) +Solarflare `sfc` driver | 5.5 | [`eb9a36be7f3e`](https://github.com/torvalds/linux/commit/eb9a36be7f3ec414700af9a616f035eda1f1e63e) +Marvell `mvneta` driver | 5.5 | [`0db51da7a8e9`](https://github.com/torvalds/linux/commit/0db51da7a8e99f0803ec3a8e25c1a66234a219cb) +Microsoft `hv_netvsc` driver | 5.6 | [`351e1581395f`](https://github.com/torvalds/linux/commit/351e1581395fcc7fb952bbd7dda01238f69968fd) +Amazon `ena` driver | 5.6 | [`838c93dc5449`](https://github.com/torvalds/linux/commit/838c93dc5449e5d6378bae117b0a65a122cf7361) +`xen-netfront` driver | 5.9 | [`6c5aa6fc4def`](https://github.com/torvalds/linux/commit/6c5aa6fc4defc2a0977a2c59e4710d50fa1e834c) +Intel `igb` driver | 5.10 | [`9cbc948b5a20`](https://github.com/torvalds/linux/commit/9cbc948b5a20c9c054d9631099c0426c16da546b) + +## Helpers + +The list of helpers supported in your kernel can be found in file +[`include/uapi/linux/bpf.h`](https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h): + + git grep ' FN(' include/uapi/linux/bpf.h + +Alphabetical order + +Helper | Kernel version | License | Commit | +-------|----------------|---------|--------| +`BPF_FUNC_bind()` | 4.17 | | [`d74bad4e74ee`](https://github.com/torvalds/linux/commit/d74bad4e74ee373787a9ae24197c17b7cdc428d5) | +`BPF_FUNC_bprm_opts_set()` | 5.11 | | [`3f6719c7b62f`](https://github.com/torvalds/linux/commit/3f6719c7b62f0327c9091e26d0da10e65668229e) +`BPF_FUNC_btf_find_by_name_kind()` | 5.14 | | [`3d78417b60fb`](https://github.com/torvalds/linux/commit/3d78417b60fba249cc555468cb72d96f5cde2964) +`BPF_FUNC_cgrp_storage_delete()` | 6.2 | | [`c4bcfb38a95e`](https://github.com/torvalds/linux/commit/c4bcfb38a95edb1021a53f2d0356a78120ecfbe4) +`BPF_FUNC_cgrp_storage_get()` | 6.2 | | [`c4bcfb38a95e`](https://github.com/torvalds/linux/commit/c4bcfb38a95edb1021a53f2d0356a78120ecfbe4) +`BPF_FUNC_check_mtu()` | 5.12 | | [`34b2021cc616`](https://github.com/torvalds/linux/commit/34b2021cc61642d61c3cf943d9e71925b827941b) +`BPF_FUNC_clone_redirect()` | 4.2 | | [`3896d655f4d4`](https://github.com/torvalds/linux/commit/3896d655f4d491c67d669a15f275a39f713410f8) +`BPF_FUNC_copy_from_user()` | 5.10 | | [`07be4c4a3e7a`](https://github.com/torvalds/linux/commit/07be4c4a3e7a0db148e44b16c5190e753d1c8569) +`BPF_FUNC_copy_from_user_task()` | 5.18 | GPL | [`376040e47334`](https://github.com/torvalds/linux/commit/376040e47334c6dc6a939a32197acceb00fe4acf) +`BPF_FUNC_csum_diff()` | 4.6 | | [`7d672345ed29`](https://github.com/torvalds/linux/commit/7d672345ed295b1356a5d9f7111da1d1d7d65867) +`BPF_FUNC_csum_level()` | 5.7 | | [`7cdec54f9713`](https://github.com/torvalds/linux/commit/7cdec54f9713256bb170873a1fc5c75c9127c9d2) +`BPF_FUNC_csum_update()` | 4.9 | | [`36bbef52c7eb`](https://github.com/torvalds/linux/commit/36bbef52c7eb646ed6247055a2acd3851e317857) +`BPF_FUNC_current_task_under_cgroup()` | 4.9 | | [`60d20f9195b2`](https://github.com/torvalds/linux/commit/60d20f9195b260bdf0ac10c275ae9f6016f9c069) +`BPF_FUNC_d_path()` | 5.10 | | [`6e22ab9da793`](https://github.com/torvalds/linux/commit/6e22ab9da79343532cd3cde39df25e5a5478c692) +`BPF_FUNC_dynptr_data()` | 5.19 | | [`34d4ef5775f7`](https://github.com/torvalds/linux/commit/34d4ef5775f776ec4b0d53a02d588bf3195cada6) +`BPF_FUNC_dynptr_from_mem()` | 5.19 | | [`263ae152e962`](https://github.com/torvalds/linux/commit/263ae152e96253f40c2c276faad8629e096b3bad) +`BPF_FUNC_dynptr_read()` | 5.19 | | [`13bbbfbea759`](https://github.com/torvalds/linux/commit/13bbbfbea7598ea9f8d9c3d73bf053bb57f9c4b2) +`BPF_FUNC_dynptr_write()` | 5.19 | | [`13bbbfbea759`](https://github.com/torvalds/linux/commit/13bbbfbea7598ea9f8d9c3d73bf053bb57f9c4b2) +`BPF_FUNC_fib_lookup()` | 4.18 | GPL | [`87f5fc7e48dd`](https://github.com/torvalds/linux/commit/87f5fc7e48dd3175b30dd03b41564e1a8e136323) +`BPF_FUNC_find_vma()` | 5.17 | | [`7c7e3d31e785`](https://github.com/torvalds/linux/commit/7c7e3d31e7856a8260a254f8c71db416f7f9f5a1) +`BPF_FUNC_for_each_map_elem()` | 5.13 | | [`69c087ba6225`](https://github.com/torvalds/linux/commit/69c087ba6225b574afb6e505b72cb75242a3d844) +`BPF_FUNC_get_attach_cookie()` | 5.15 | | [`7adfc6c9b315`](https://github.com/torvalds/linux/commit/7adfc6c9b315e174cf8743b21b7b691c8766791b) +`BPF_FUNC_get_branch_snapshot()` | 5.16 | GPL | [`856c02dbce4f`](https://github.com/torvalds/linux/commit/856c02dbce4f8d6a5644083db22c11750aa11481) +`BPF_FUNC_get_current_ancestor_cgroup_id()` | 5.6 | | [`b4490c5c4e02`](https://github.com/torvalds/linux/commit/b4490c5c4e023f09b7d27c9a9d3e7ad7d09ea6bf) +`BPF_FUNC_get_cgroup_classid()` | 4.3 | | [`8d20aabe1c76`](https://github.com/torvalds/linux/commit/8d20aabe1c76cccac544d9fcc3ad7823d9e98a2d) +`BPF_FUNC_get_current_cgroup_id()` | 4.18 | | [`bf6fa2c893c5`](https://github.com/torvalds/linux/commit/bf6fa2c893c5237b48569a13fa3c673041430b6c) +`BPF_FUNC_get_current_comm()` | 4.2 | | [`ffeedafbf023`](https://github.com/torvalds/linux/commit/ffeedafbf0236f03aeb2e8db273b3e5ae5f5bc89) +`BPF_FUNC_get_current_pid_tgid()` | 4.2 | | [`ffeedafbf023`](https://github.com/torvalds/linux/commit/ffeedafbf0236f03aeb2e8db273b3e5ae5f5bc89) +`BPF_FUNC_get_current_task()` | 4.8 | GPL | [`606274c5abd8`](https://github.com/torvalds/linux/commit/606274c5abd8e245add01bc7145a8cbb92b69ba8) +`BPF_FUNC_get_current_task_btf()` | 5.11 | GPL | [`3ca1032ab7ab`](https://github.com/torvalds/linux/commit/3ca1032ab7ab010eccb107aa515598788f7d93bb) +`BPF_FUNC_get_current_uid_gid()` | 4.2 | | [`ffeedafbf023`](https://github.com/torvalds/linux/commit/ffeedafbf0236f03aeb2e8db273b3e5ae5f5bc89) +`BPF_FUNC_get_func_arg()` | 5.17 | | [`f92c1e183604`](https://github.com/torvalds/linux/commit/f92c1e183604c20ce00eb889315fdaa8f2d9e509) +`BPF_FUNC_get_func_arg_cnt()` | 5.17 | | [`f92c1e183604`](https://github.com/torvalds/linux/commit/f92c1e183604c20ce00eb889315fdaa8f2d9e509) +`BPF_FUNC_get_func_ip()` | 5.15 | | [`5d8b583d04ae`](https://github.com/torvalds/linux/commit/5d8b583d04aedb3bd5f6d227a334c210c7d735f9) +`BPF_FUNC_get_func_ret()` | 5.17 | | [`f92c1e183604`](https://github.com/torvalds/linux/commit/f92c1e183604c20ce00eb889315fdaa8f2d9e509) +`BPF_FUNC_get_retval()` | 5.18 | | [`b44123b4a3dc`](https://github.com/torvalds/linux/commit/b44123b4a3dcad4664d3a0f72c011ffd4c9c4d93) +`BPF_FUNC_get_hash_recalc()` | 4.8 | | [`13c5c240f789`](https://github.com/torvalds/linux/commit/13c5c240f789bbd2bcacb14a23771491485ae61f) +`BPF_FUNC_get_listener_sock()` | 5.1 | | [`dbafd7ddd623`](https://github.com/torvalds/linux/commit/dbafd7ddd62369b2f3926ab847cbf8fc40e800b7) +`BPF_FUNC_get_local_storage()` | 4.19 | | [`cd3394317653`](https://github.com/torvalds/linux/commit/cd3394317653837e2eb5c5d0904a8996102af9fc) +`BPF_FUNC_get_netns_cookie()` | 5.7 | | [`f318903c0bf4`](https://github.com/torvalds/linux/commit/f318903c0bf42448b4c884732df2bbb0ef7a2284) +`BPF_FUNC_get_ns_current_pid_tgid()` | 5.7 | | [`b4490c5c4e02`](https://github.com/torvalds/linux/commit/b4490c5c4e023f09b7d27c9a9d3e7ad7d09ea6bf) +`BPF_FUNC_get_numa_node_id()` | 4.10 | | [`2d0e30c30f84`](https://github.com/torvalds/linux/commit/2d0e30c30f84d08dc16f0f2af41f1b8a85f0755e) +`BPF_FUNC_get_prandom_u32()` | 4.1 | | [`03e69b508b6f`](https://github.com/torvalds/linux/commit/03e69b508b6f7c51743055c9f61d1dfeadf4b635) +`BPF_FUNC_get_route_realm()` | 4.4 | | [`c46646d0484f`](https://github.com/torvalds/linux/commit/c46646d0484f5d08e2bede9b45034ba5b8b489cc) +`BPF_FUNC_get_smp_processor_id()` | 4.1 | | [`c04167ce2ca0`](https://github.com/torvalds/linux/commit/c04167ce2ca0ecaeaafef006cb0d65cf01b68e42) +`BPF_FUNC_get_socket_cookie()` | 4.12 | | [`91b8270f2a4d`](https://github.com/torvalds/linux/commit/91b8270f2a4d1d9b268de90451cdca63a70052d6) +`BPF_FUNC_get_socket_uid()` | 4.12 | | [`6acc5c291068`](https://github.com/torvalds/linux/commit/6acc5c2910689fc6ee181bf63085c5efff6a42bd) +`BPF_FUNC_get_stack()` | 4.18 | GPL | [`de2ff05f48af`](https://github.com/torvalds/linux/commit/de2ff05f48afcde816ff4edb217417f62f624ab5) +`BPF_FUNC_get_stackid()` | 4.6 | GPL | [`d5a3b1f69186`](https://github.com/torvalds/linux/commit/d5a3b1f691865be576c2bffa708549b8cdccda19) +`BPF_FUNC_get_task_stack()` | 5.9 | | [`fa28dcb82a38`](https://github.com/torvalds/linux/commit/fa28dcb82a38f8e3993b0fae9106b1a80b59e4f0) +`BPF_FUNC_getsockopt()` | 4.15 | | [`cd86d1fd2102`](https://github.com/torvalds/linux/commit/cd86d1fd21025fdd6daf23d1288da405e7ad0ec6) +`BPF_FUNC_ima_file_hash()` | 5.18 | | [`174b16946e39`](https://github.com/torvalds/linux/commit/174b16946e39ebd369097e0f773536c91a8c1a4c) +`BPF_FUNC_ima_inode_hash()` | 5.11 | | [`27672f0d280a`](https://github.com/torvalds/linux/commit/27672f0d280a3f286a410a8db2004f46ace72a17) +`BPF_FUNC_inode_storage_delete()` | 5.10 | | [`8ea636848aca`](https://github.com/torvalds/linux/commit/8ea636848aca35b9f97c5b5dee30225cf2dd0fe6) +`BPF_FUNC_inode_storage_get()` | 5.10 | | [`8ea636848aca`](https://github.com/torvalds/linux/commit/8ea636848aca35b9f97c5b5dee30225cf2dd0fe6) +`BPF_FUNC_jiffies64()` | 5.5 | | [`5576b991e9c1`](https://github.com/torvalds/linux/commit/5576b991e9c1a11d2cc21c4b94fc75ec27603896) +`BPF_FUNC_kallsyms_lookup_name()` | 5.16 | | [`d6aef08a872b`](https://github.com/torvalds/linux/commit/d6aef08a872b9e23eecc92d0e92393473b13c497) +`BPF_FUNC_kptr_xchg()` | 5.19 | | [`c0a5a21c25f3`](https://github.com/torvalds/linux/commit/c0a5a21c25f37c9fd7b36072f9968cdff1e4aa13) +`BPF_FUNC_ktime_get_boot_ns()` | 5.8 | | [`71d19214776e`](https://github.com/torvalds/linux/commit/71d19214776e61b33da48f7c1b46e522c7f78221) +`BPF_FUNC_ktime_get_coarse_ns()` | 5.11 | | [`d05512618056`](https://github.com/torvalds/linux/commit/d055126180564a57fe533728a4e93d0cb53d49b3) +`BPF_FUNC_ktime_get_ns()` | 4.1 | | [`d9847d310ab4`](https://github.com/torvalds/linux/commit/d9847d310ab4003725e6ed1822682e24bd406908) +`BPF_FUNC_ktime_get_tai_ns()` | 6.1 | | [`c8996c98f703`](https://github.com/torvalds/linux/commit/c8996c98f703b09afe77a1d247dae691c9849dc1) +`BPF_FUNC_l3_csum_replace()` | 4.1 | | [`91bc4822c3d6`](https://github.com/torvalds/linux/commit/91bc4822c3d61b9bb7ef66d3b77948a4f9177954) +`BPF_FUNC_l4_csum_replace()` | 4.1 | | [`91bc4822c3d6`](https://github.com/torvalds/linux/commit/91bc4822c3d61b9bb7ef66d3b77948a4f9177954) +`BPF_FUNC_load_hdr_opt()` | 5.10 | | [`0813a841566f`](https://github.com/torvalds/linux/commit/0813a841566f0962a5551be7749b43c45f0022a0) +`BPF_FUNC_loop()` | 5.17 | | [`e6f2dd0f8067`](https://github.com/torvalds/linux/commit/e6f2dd0f80674e9d5960337b3e9c2a242441b326) +`BPF_FUNC_lwt_push_encap()` | 4.18 | | [`fe94cc290f53`](https://github.com/torvalds/linux/commit/fe94cc290f535709d3c5ebd1e472dfd0aec7ee79) +`BPF_FUNC_lwt_seg6_action()` | 4.18 | | [`fe94cc290f53`](https://github.com/torvalds/linux/commit/fe94cc290f535709d3c5ebd1e472dfd0aec7ee79) +`BPF_FUNC_lwt_seg6_adjust_srh()` | 4.18 | | [`fe94cc290f53`](https://github.com/torvalds/linux/commit/fe94cc290f535709d3c5ebd1e472dfd0aec7ee79) +`BPF_FUNC_lwt_seg6_store_bytes()` | 4.18 | | [`fe94cc290f53`](https://github.com/torvalds/linux/commit/fe94cc290f535709d3c5ebd1e472dfd0aec7ee79) +`BPF_FUNC_map_delete_elem()` | 3.19 | | [`d0003ec01c66`](https://github.com/torvalds/linux/commit/d0003ec01c667b731c139e23de3306a8b328ccf5) +`BPF_FUNC_map_lookup_elem()` | 3.19 | | [`d0003ec01c66`](https://github.com/torvalds/linux/commit/d0003ec01c667b731c139e23de3306a8b328ccf5) +`BPF_FUNC_map_lookup_percpu_elem()` | 5.19 | | [`07343110b293`](https://github.com/torvalds/linux/commit/07343110b293456d30393e89b86c4dee1ac051c8) +`BPF_FUNC_map_peek_elem()` | 4.20 | | [`f1a2e44a3aec`](https://github.com/torvalds/linux/commit/f1a2e44a3aeccb3ff18d3ccc0b0203e70b95bd92) +`BPF_FUNC_map_pop_elem()` | 4.20 | | [`f1a2e44a3aec`](https://github.com/torvalds/linux/commit/f1a2e44a3aeccb3ff18d3ccc0b0203e70b95bd92) +`BPF_FUNC_map_push_elem()` | 4.20 | | [`f1a2e44a3aec`](https://github.com/torvalds/linux/commit/f1a2e44a3aeccb3ff18d3ccc0b0203e70b95bd92) +`BPF_FUNC_map_update_elem()` | 3.19 | | [`d0003ec01c66`](https://github.com/torvalds/linux/commit/d0003ec01c667b731c139e23de3306a8b328ccf5) +`BPF_FUNC_msg_apply_bytes()` | 4.17 | | [`2a100317c9eb`](https://github.com/torvalds/linux/commit/2a100317c9ebc204a166f16294884fbf9da074ce) +`BPF_FUNC_msg_cork_bytes()` | 4.17 | | [`91843d540a13`](https://github.com/torvalds/linux/commit/91843d540a139eb8070bcff8aa10089164436deb) +`BPF_FUNC_msg_pop_data()` | 5.0 | | [`7246d8ed4dcc`](https://github.com/torvalds/linux/commit/7246d8ed4dcce23f7509949a77be15fa9f0e3d28) +`BPF_FUNC_msg_pull_data()` | 4.17 | | [`015632bb30da`](https://github.com/torvalds/linux/commit/015632bb30daaaee64e1bcac07570860e0bf3092) +`BPF_FUNC_msg_push_data()` | 4.20 | | [`6fff607e2f14`](https://github.com/torvalds/linux/commit/6fff607e2f14bd7c63c06c464a6f93b8efbabe28) +`BPF_FUNC_msg_redirect_hash()` | 4.18 | | [`81110384441a`](https://github.com/torvalds/linux/commit/81110384441a59cff47430f20f049e69b98c17f4) +`BPF_FUNC_msg_redirect_map()` | 4.17 | | [`4f738adba30a`](https://github.com/torvalds/linux/commit/4f738adba30a7cfc006f605707e7aee847ffefa0) +`BPF_FUNC_per_cpu_ptr()` | 5.10 | | [`eaa6bcb71ef6`](https://github.com/torvalds/linux/commit/eaa6bcb71ef6ed3dc18fc525ee7e293b06b4882b) | +`BPF_FUNC_perf_event_output()` | 4.4 | GPL | [`a43eec304259`](https://github.com/torvalds/linux/commit/a43eec304259a6c637f4014a6d4767159b6a3aa3) +`BPF_FUNC_perf_event_read()` | 4.3 | GPL | [`35578d798400`](https://github.com/torvalds/linux/commit/35578d7984003097af2b1e34502bc943d40c1804) +`BPF_FUNC_perf_event_read_value()` | 4.15 | GPL | [`908432ca84fc`](https://github.com/torvalds/linux/commit/908432ca84fc229e906ba164219e9ad0fe56f755) +`BPF_FUNC_perf_prog_read_value()` | 4.15 | GPL | [`4bebdc7a85aa`](https://github.com/torvalds/linux/commit/4bebdc7a85aa400c0222b5329861e4ad9252f1e5) +`BPF_FUNC_probe_read()` | 4.1 | GPL | [`2541517c32be`](https://github.com/torvalds/linux/commit/2541517c32be2531e0da59dfd7efc1ce844644f5) +`BPF_FUNC_probe_read_kernel()` | 5.5 | GPL | [`6ae08ae3dea2`](https://github.com/torvalds/linux/commit/6ae08ae3dea2cfa03dd3665a3c8475c2d429ef47) +`BPF_FUNC_probe_read_kernel_str()` | 5.5 | GPL | [`6ae08ae3dea2`](https://github.com/torvalds/linux/commit/6ae08ae3dea2cfa03dd3665a3c8475c2d429ef47) +`BPF_FUNC_probe_read_user()` | 5.5 | GPL | [`6ae08ae3dea2`](https://github.com/torvalds/linux/commit/6ae08ae3dea2cfa03dd3665a3c8475c2d429ef47) +`BPF_FUNC_probe_read_user_str()` | 5.5 | GPL | [`6ae08ae3dea2`](https://github.com/torvalds/linux/commit/6ae08ae3dea2cfa03dd3665a3c8475c2d429ef47) +`BPF_FUNC_probe_read_str()` | 4.11 | GPL | [`a5e8c07059d0`](https://github.com/torvalds/linux/commit/a5e8c07059d0f0b31737408711d44794928ac218) +`BPF_FUNC_probe_write_user()` | 4.8 | GPL | [`96ae52279594`](https://github.com/torvalds/linux/commit/96ae52279594470622ff0585621a13e96b700600) +`BPF_FUNC_rc_keydown()` | 4.18 | GPL | [`f4364dcfc86d`](https://github.com/torvalds/linux/commit/f4364dcfc86df7c1ca47b256eaf6b6d0cdd0d936) +`BPF_FUNC_rc_pointer_rel()` | 5.0 | GPL | [`01d3240a04f4`](https://github.com/torvalds/linux/commit/01d3240a04f4c09392e13c77b54d4423ebce2d72) +`BPF_FUNC_rc_repeat()` | 4.18 | GPL | [`f4364dcfc86d`](https://github.com/torvalds/linux/commit/f4364dcfc86df7c1ca47b256eaf6b6d0cdd0d936) +`BPF_FUNC_read_branch_records()` | 5.6 | GPL | [`fff7b64355ea`](https://github.com/torvalds/linux/commit/fff7b64355eac6e29b50229ad1512315bc04b44e) +`BPF_FUNC_redirect()` | 4.4 | | [`27b29f63058d`](https://github.com/torvalds/linux/commit/27b29f63058d26c6c1742f1993338280d5a41dc6) +`BPF_FUNC_redirect_map()` | 4.14 | | [`97f91a7cf04f`](https://github.com/torvalds/linux/commit/97f91a7cf04ff605845c20948b8a80e54cbd3376) +`BPF_FUNC_redirect_neigh()` | 5.10 | | [`b4ab31414970`](https://github.com/torvalds/linux/commit/b4ab31414970a7a03a5d55d75083f2c101a30592) +`BPF_FUNC_redirect_peer()` | 5.10 | | [`9aa1206e8f48`](https://github.com/torvalds/linux/commit/9aa1206e8f48222f35a0c809f33b2f4aaa1e2661) +`BPF_FUNC_reserve_hdr_opt()` | 5.10 | | [`0813a841566f`](https://github.com/torvalds/linux/commit/0813a841566f0962a5551be7749b43c45f0022a0) +`BPF_FUNC_ringbuf_discard()` | 5.8 | | [`457f44363a88`](https://github.com/torvalds/linux/commit/457f44363a8894135c85b7a9afd2bd8196db24ab) +`BPF_FUNC_ringbuf_discard_dynptr()` | 5.19 | | [`bc34dee65a65`](https://github.com/torvalds/linux/commit/bc34dee65a65e9c920c420005b8a43f2a721a458) +`BPF_FUNC_ringbuf_output()` | 5.8 | | [`457f44363a88`](https://github.com/torvalds/linux/commit/457f44363a8894135c85b7a9afd2bd8196db24ab) +`BPF_FUNC_ringbuf_query()` | 5.8 | | [`457f44363a88`](https://github.com/torvalds/linux/commit/457f44363a8894135c85b7a9afd2bd8196db24ab) +`BPF_FUNC_ringbuf_reserve()` | 5.8 | | [`457f44363a88`](https://github.com/torvalds/linux/commit/457f44363a8894135c85b7a9afd2bd8196db24ab) +`BPF_FUNC_ringbuf_reserve_dynptr()` | 5.19 | | [`bc34dee65a65`](https://github.com/torvalds/linux/commit/bc34dee65a65e9c920c420005b8a43f2a721a458) +`BPF_FUNC_ringbuf_submit()` | 5.8 | | [`457f44363a88`](https://github.com/torvalds/linux/commit/457f44363a8894135c85b7a9afd2bd8196db24ab) +`BPF_FUNC_ringbuf_submit_dynptr()` | 5.19 | | [`bc34dee65a65`](https://github.com/torvalds/linux/commit/bc34dee65a65e9c920c420005b8a43f2a721a458) +`BPF_FUNC_send_signal()` | 5.3 | | [`8b401f9ed244`](https://github.com/torvalds/linux/commit/8b401f9ed2441ad9e219953927a842d24ed051fc) +`BPF_FUNC_send_signal_thread()` | 5.5 | | [`8482941f0906`](https://github.com/torvalds/linux/commit/8482941f09067da42f9c3362e15bfb3f3c19d610) +`BPF_FUNC_seq_printf()` | 5.7 | GPL | [`492e639f0c22`](https://github.com/torvalds/linux/commit/492e639f0c222784e2e0f121966375f641c61b15) +`BPF_FUNC_seq_printf_btf()` | 5.10 | | [`eb411377aed9`](https://github.com/torvalds/linux/commit/eb411377aed9e27835e77ee0710ee8f4649958f3) +`BPF_FUNC_seq_write()` | 5.7 | GPL | [`492e639f0c22`](https://github.com/torvalds/linux/commit/492e639f0c222784e2e0f121966375f641c61b15) +`BPF_FUNC_set_hash()` | 4.13 | | [`ded092cd73c2`](https://github.com/torvalds/linux/commit/ded092cd73c2c56a394b936f86897f29b2e131c0) +`BPF_FUNC_set_hash_invalid()` | 4.9 | | [`7a4b28c6cc9f`](https://github.com/torvalds/linux/commit/7a4b28c6cc9ffac50f791b99cc7e46106436e5d8) +`BPF_FUNC_set_retval()` | 5.18 | | [`b44123b4a3dc`](https://github.com/torvalds/linux/commit/b44123b4a3dcad4664d3a0f72c011ffd4c9c4d93) +`BPF_FUNC_setsockopt()` | 4.13 | | [`8c4b4c7e9ff0`](https://github.com/torvalds/linux/commit/8c4b4c7e9ff0447995750d9329949fa082520269) +`BPF_FUNC_sk_ancestor_cgroup_id()` | 5.7 | | [`f307fa2cb4c9`](https://github.com/torvalds/linux/commit/f307fa2cb4c935f7f1ff0aeb880c7b44fb9a642b) +`BPF_FUNC_sk_assign()` | 5.6 | | [`cf7fbe660f2d`](https://github.com/torvalds/linux/commit/cf7fbe660f2dbd738ab58aea8e9b0ca6ad232449) +`BPF_FUNC_sk_cgroup_id()` | 5.7 | | [`f307fa2cb4c9`](https://github.com/torvalds/linux/commit/f307fa2cb4c935f7f1ff0aeb880c7b44fb9a642b) +`BPF_FUNC_sk_fullsock()` | 5.1 | | [`46f8bc92758c`](https://github.com/torvalds/linux/commit/46f8bc92758c6259bcf945e9216098661c1587cd) +`BPF_FUNC_sk_lookup_tcp()` | 4.20 | | [`6acc9b432e67`](https://github.com/torvalds/linux/commit/6acc9b432e6714d72d7d77ec7c27f6f8358d0c71) +`BPF_FUNC_sk_lookup_udp()` | 4.20 | | [`6acc9b432e67`](https://github.com/torvalds/linux/commit/6acc9b432e6714d72d7d77ec7c27f6f8358d0c71) +`BPF_FUNC_sk_redirect_hash()` | 4.18 | | [`81110384441a`](https://github.com/torvalds/linux/commit/81110384441a59cff47430f20f049e69b98c17f4) +`BPF_FUNC_sk_redirect_map()` | 4.14 | | [`174a79ff9515`](https://github.com/torvalds/linux/commit/174a79ff9515f400b9a6115643dafd62a635b7e6) +`BPF_FUNC_sk_release()` | 4.20 | | [`6acc9b432e67`](https://github.com/torvalds/linux/commit/6acc9b432e6714d72d7d77ec7c27f6f8358d0c71) +`BPF_FUNC_sk_select_reuseport()` | 4.19 | | [`2dbb9b9e6df6`](https://github.com/torvalds/linux/commit/2dbb9b9e6df67d444fbe425c7f6014858d337adf) +`BPF_FUNC_sk_storage_delete()` | 5.2 | | [`6ac99e8f23d4`](https://github.com/torvalds/linux/commit/6ac99e8f23d4b10258406ca0dd7bffca5f31da9d) +`BPF_FUNC_sk_storage_get()` | 5.2 | | [`6ac99e8f23d4`](https://github.com/torvalds/linux/commit/6ac99e8f23d4b10258406ca0dd7bffca5f31da9d) +`BPF_FUNC_skb_adjust_room()` | 4.13 | | [`2be7e212d541`](https://github.com/torvalds/linux/commit/2be7e212d5419a400d051c84ca9fdd083e5aacac) +`BPF_FUNC_skb_ancestor_cgroup_id()` | 4.19 | | [`7723628101aa`](https://github.com/torvalds/linux/commit/7723628101aaeb1d723786747529b4ea65c5b5c5) +`BPF_FUNC_skb_change_head()` | 4.10 | | [`3a0af8fd61f9`](https://github.com/torvalds/linux/commit/3a0af8fd61f90920f6fa04e4f1e9a6a73c1b4fd2) +`BPF_FUNC_skb_change_proto()` | 4.8 | | [`6578171a7ff0`](https://github.com/torvalds/linux/commit/6578171a7ff0c31dc73258f93da7407510abf085) +`BPF_FUNC_skb_change_tail()` | 4.9 | | [`5293efe62df8`](https://github.com/torvalds/linux/commit/5293efe62df81908f2e90c9820c7edcc8e61f5e9) +`BPF_FUNC_skb_change_type()` | 4.8 | | [`d2485c4242a8`](https://github.com/torvalds/linux/commit/d2485c4242a826fdf493fd3a27b8b792965b9b9e) +`BPF_FUNC_skb_cgroup_classid()` | 5.10 | | [`b426ce83baa7`](https://github.com/torvalds/linux/commit/b426ce83baa7dff947fb354118d3133f2953aac8) +`BPF_FUNC_skb_cgroup_id()` | 4.18 | | [`cb20b08ead40`](https://github.com/torvalds/linux/commit/cb20b08ead401fd17627a36f035c0bf5bfee5567) +`BPF_FUNC_skb_ecn_set_ce()` | 5.1 | | [`f7c917ba11a6`](https://github.com/torvalds/linux/commit/f7c917ba11a67632a8452ea99fe132f626a7a2cc) +`BPF_FUNC_skb_get_tunnel_key()` | 4.3 | | [`d3aa45ce6b94`](https://github.com/torvalds/linux/commit/d3aa45ce6b94c65b83971257317867db13e5f492) +`BPF_FUNC_skb_get_tunnel_opt()` | 4.6 | | [`14ca0751c96f`](https://github.com/torvalds/linux/commit/14ca0751c96f8d3d0f52e8ed3b3236f8b34d3460) +`BPF_FUNC_skb_get_xfrm_state()` | 4.18 | | [`12bed760a78d`](https://github.com/torvalds/linux/commit/12bed760a78da6e12ac8252fec64d019a9eac523) +`BPF_FUNC_skb_load_bytes()` | 4.5 | | [`05c74e5e53f6`](https://github.com/torvalds/linux/commit/05c74e5e53f6cb07502c3e6a820f33e2777b6605) +`BPF_FUNC_skb_load_bytes_relative()` | 4.18 | | [`4e1ec56cdc59`](https://github.com/torvalds/linux/commit/4e1ec56cdc59746943b2acfab3c171b930187bbe) +`BPF_FUNC_skb_output()` | 5.5 | | [`a7658e1a4164`](https://github.com/torvalds/linux/commit/a7658e1a4164ce2b9eb4a11aadbba38586e93bd6) +`BPF_FUNC_skb_pull_data()` | 4.9 | | [`36bbef52c7eb`](https://github.com/torvalds/linux/commit/36bbef52c7eb646ed6247055a2acd3851e317857) +`BPF_FUNC_skb_set_tstamp()` | 5.18 | | [`9bb984f28d5b`](https://github.com/torvalds/linux/commit/9bb984f28d5bcb917d35d930fcfb89f90f9449fd) +`BPF_FUNC_skb_set_tunnel_key()` | 4.3 | | [`d3aa45ce6b94`](https://github.com/torvalds/linux/commit/d3aa45ce6b94c65b83971257317867db13e5f492) +`BPF_FUNC_skb_set_tunnel_opt()` | 4.6 | | [`14ca0751c96f`](https://github.com/torvalds/linux/commit/14ca0751c96f8d3d0f52e8ed3b3236f8b34d3460) +`BPF_FUNC_skb_store_bytes()` | 4.1 | | [`91bc4822c3d6`](https://github.com/torvalds/linux/commit/91bc4822c3d61b9bb7ef66d3b77948a4f9177954) +`BPF_FUNC_skb_under_cgroup()` | 4.8 | | [`4a482f34afcc`](https://github.com/torvalds/linux/commit/4a482f34afcc162d8456f449b137ec2a95be60d8) +`BPF_FUNC_skb_vlan_pop()` | 4.3 | | [`4e10df9a60d9`](https://github.com/torvalds/linux/commit/4e10df9a60d96ced321dd2af71da558c6b750078) +`BPF_FUNC_skb_vlan_push()` | 4.3 | | [`4e10df9a60d9`](https://github.com/torvalds/linux/commit/4e10df9a60d96ced321dd2af71da558c6b750078) +`BPF_FUNC_skc_lookup_tcp()` | 5.2 | | [`edbf8c01de5a`](https://github.com/torvalds/linux/commit/edbf8c01de5a104a71ed6df2bf6421ceb2836a8e) +`BPF_FUNC_skc_to_mctcp_sock()` | 5.19 | | [`3bc253c2e652`](https://github.com/torvalds/linux/commit/3bc253c2e652cf5f12cd8c00d80d8ec55d67d1a7) +`BPF_FUNC_skc_to_tcp_sock()` | 5.9 | | [`478cfbdf5f13`](https://github.com/torvalds/linux/commit/478cfbdf5f13dfe09cfd0b1cbac821f5e27f6108) +`BPF_FUNC_skc_to_tcp_request_sock()` | 5.9 | | [`478cfbdf5f13`](https://github.com/torvalds/linux/commit/478cfbdf5f13dfe09cfd0b1cbac821f5e27f6108) +`BPF_FUNC_skc_to_tcp_timewait_sock()` | 5.9 | | [`478cfbdf5f13`](https://github.com/torvalds/linux/commit/478cfbdf5f13dfe09cfd0b1cbac821f5e27f6108) +`BPF_FUNC_skc_to_tcp6_sock()` | 5.9 | | [`af7ec1383361`](https://github.com/torvalds/linux/commit/af7ec13833619e17f03aa73a785a2f871da6d66b) +`BPF_FUNC_skc_to_udp6_sock()` | 5.9 | | [`0d4fad3e57df`](https://github.com/torvalds/linux/commit/0d4fad3e57df2bf61e8ffc8d12a34b1caf9b8835) +`BPF_FUNC_skc_to_unix_sock()` | 5.16 | | [`9eeb3aa33ae0`](https://github.com/torvalds/linux/commit/9eeb3aa33ae005526f672b394c1791578463513f) +`BPF_FUNC_snprintf()` | 5.13 | | [`7b15523a989b`](https://github.com/torvalds/linux/commit/7b15523a989b63927c2bb08e9b5b0bbc10b58bef) +`BPF_FUNC_snprintf_btf()` | 5.10 | | [`c4d0bfb45068`](https://github.com/torvalds/linux/commit/c4d0bfb45068d853a478b9067a95969b1886a30f) +`BPF_FUNC_sock_from_file()` | 5.11 | | [`4f19cab76136`](https://github.com/torvalds/linux/commit/4f19cab76136e800a3f04d8c9aa4d8e770e3d3d8) +`BPF_FUNC_sock_hash_update()` | 4.18 | | [`81110384441a`](https://github.com/torvalds/linux/commit/81110384441a59cff47430f20f049e69b98c17f4) +`BPF_FUNC_sock_map_update()` | 4.14 | | [`174a79ff9515`](https://github.com/torvalds/linux/commit/174a79ff9515f400b9a6115643dafd62a635b7e6) +`BPF_FUNC_spin_lock()` | 5.1 | | [`d83525ca62cf`](https://github.com/torvalds/linux/commit/d83525ca62cf8ebe3271d14c36fb900c294274a2) +`BPF_FUNC_spin_unlock()` | 5.1 | | [`d83525ca62cf`](https://github.com/torvalds/linux/commit/d83525ca62cf8ebe3271d14c36fb900c294274a2) +`BPF_FUNC_store_hdr_opt()` | 5.10 | | [`0813a841566f`](https://github.com/torvalds/linux/commit/0813a841566f0962a5551be7749b43c45f0022a0) +`BPF_FUNC_strncmp()` | 5.17 | | [`c5fb19937455`](https://github.com/torvalds/linux/commit/c5fb19937455095573a19ddcbff32e993ed10e35) +`BPF_FUNC_strtol()` | 5.2 | | [`d7a4cb9b6705`](https://github.com/torvalds/linux/commit/d7a4cb9b6705a89937d12c8158a35a3145dc967a) +`BPF_FUNC_strtoul()` | 5.2 | | [`d7a4cb9b6705`](https://github.com/torvalds/linux/commit/d7a4cb9b6705a89937d12c8158a35a3145dc967a) +`BPF_FUNC_sys_bpf()` | 5.14 | | [`79a7f8bdb159`](https://github.com/torvalds/linux/commit/79a7f8bdb159d9914b58740f3d31d602a6e4aca8) +`BPF_FUNC_sys_close()` | 5.14 | | [`3abea089246f`](https://github.com/torvalds/linux/commit/3abea089246f76c1517b054ddb5946f3f1dbd2c0) +`BPF_FUNC_sysctl_get_current_value()` | 5.2 | | [`1d11b3016cec`](https://github.com/torvalds/linux/commit/1d11b3016cec4ed9770b98e82a61708c8f4926e7) +`BPF_FUNC_sysctl_get_name()` | 5.2 | | [`808649fb787d`](https://github.com/torvalds/linux/commit/808649fb787d918a48a360a668ee4ee9023f0c11) +`BPF_FUNC_sysctl_get_new_value()` | 5.2 | | [`4e63acdff864`](https://github.com/torvalds/linux/commit/4e63acdff864654cee0ac5aaeda3913798ee78f6) +`BPF_FUNC_sysctl_set_new_value()` | 5.2 | | [`4e63acdff864`](https://github.com/torvalds/linux/commit/4e63acdff864654cee0ac5aaeda3913798ee78f6) +`BPF_FUNC_tail_call()` | 4.2 | | [`04fd61ab36ec`](https://github.com/torvalds/linux/commit/04fd61ab36ec065e194ab5e74ae34a5240d992bb) +`BPF_FUNC_task_pt_regs()` | 5.15 | GPL | [`dd6e10fbd9f`](https://github.com/torvalds/linux/commit/dd6e10fbd9fb86a571d925602c8a24bb4d09a2a7) +`BPF_FUNC_task_storage_delete()` | 5.11 | | [`4cf1bc1f1045`](https://github.com/torvalds/linux/commit/4cf1bc1f10452065a29d576fc5693fc4fab5b919) +`BPF_FUNC_task_storage_get()` | 5.11 | | [`4cf1bc1f1045`](https://github.com/torvalds/linux/commit/4cf1bc1f10452065a29d576fc5693fc4fab5b919) +`BPF_FUNC_tcp_check_syncookie()` | 5.2 | | [`399040847084`](https://github.com/torvalds/linux/commit/399040847084a69f345e0a52fd62f04654e0fce3) +`BPF_FUNC_tcp_gen_syncookie()` | 5.3 | | [`70d66244317e`](https://github.com/torvalds/linux/commit/70d66244317e958092e9c971b08dd5b7fd29d9cb#diff-05da4bf36c7fbcd176254e1615d98b28) +`BPF_FUNC_tcp_raw_check_syncookie_ipv4()` | 6.0 | | [`33bf9885040c`](https://github.com/torvalds/linux/commit/33bf9885040c399cf6a95bd33216644126728e14) +`BPF_FUNC_tcp_raw_check_syncookie_ipv6()` | 6.0 | | [`33bf9885040c`](https://github.com/torvalds/linux/commit/33bf9885040c399cf6a95bd33216644126728e14) +`BPF_FUNC_tcp_raw_gen_syncookie_ipv4()` | 6.0 | | [`33bf9885040c`](https://github.com/torvalds/linux/commit/33bf9885040c399cf6a95bd33216644126728e14) +`BPF_FUNC_tcp_raw_gen_syncookie_ipv6()` | 6.0 | | [`33bf9885040c`](https://github.com/torvalds/linux/commit/33bf9885040c399cf6a95bd33216644126728e14) +`BPF_FUNC_tcp_send_ack()` | 5.5 | | [`206057fe020a`](https://github.com/torvalds/linux/commit/206057fe020ac5c037d5e2dd6562a9bd216ec765) +`BPF_FUNC_tcp_sock()` | 5.1 | | [`655a51e536c0`](https://github.com/torvalds/linux/commit/655a51e536c09d15ffa3603b1b6fce2b45b85a1f) +`BPF_FUNC_this_cpu_ptr()` | 5.10 | | [`63d9b80dcf2c`](https://github.com/torvalds/linux/commit/63d9b80dcf2c67bc5ade61cbbaa09d7af21f43f1) | +`BPF_FUNC_timer_init()` | 5.15 | | [`b00628b1c7d5`](https://github.com/torvalds/linux/commit/b00628b1c7d595ae5b544e059c27b1f5828314b4) +`BPF_FUNC_timer_set_callback()` | 5.15 | | [`b00628b1c7d5`](https://github.com/torvalds/linux/commit/b00628b1c7d595ae5b544e059c27b1f5828314b4) +`BPF_FUNC_timer_start()` | 5.15 | | [`b00628b1c7d5`](https://github.com/torvalds/linux/commit/b00628b1c7d595ae5b544e059c27b1f5828314b4) +`BPF_FUNC_timer_cancel()` | 5.15 | | [`b00628b1c7d5`](https://github.com/torvalds/linux/commit/b00628b1c7d595ae5b544e059c27b1f5828314b4) +`BPF_FUNC_trace_printk()` | 4.1 | GPL | [`9c959c863f82`](https://github.com/torvalds/linux/commit/9c959c863f8217a2ff3d7c296e8223654d240569) +`BPF_FUNC_trace_vprintk()` | 5.16 | GPL | [`10aceb629e19`](https://github.com/torvalds/linux/commit/10aceb629e198429c849d5e995c3bb1ba7a9aaa3) +`BPF_FUNC_user_ringbuf_drain()` | 6.1 | | [`205715673844`](https://github.com/torvalds/linux/commit/20571567384428dfc9fe5cf9f2e942e1df13c2dd) +`BPF_FUNC_xdp_adjust_head()` | 4.10 | | [`17bedab27231`](https://github.com/torvalds/linux/commit/17bedab2723145d17b14084430743549e6943d03) +`BPF_FUNC_xdp_adjust_meta()` | 4.15 | | [`de8f3a83b0a0`](https://github.com/torvalds/linux/commit/de8f3a83b0a0fddb2cf56e7a718127e9619ea3da) +`BPF_FUNC_xdp_adjust_tail()` | 4.18 | | [`b32cc5b9a346`](https://github.com/torvalds/linux/commit/b32cc5b9a346319c171e3ad905e0cddda032b5eb) +`BPF_FUNC_xdp_get_buff_len()` | 5.18 | | [`0165cc817075`](https://github.com/torvalds/linux/commit/0165cc817075cf701e4289838f1d925ff1911b3e) +`BPF_FUNC_xdp_load_bytes()` | 5.18 | | [`3f364222d032`](https://github.com/torvalds/linux/commit/3f364222d032eea6b245780e845ad213dab28cdd) +`BPF_FUNC_xdp_store_bytes()` | 5.18 | | [`3f364222d032`](https://github.com/torvalds/linux/commit/3f364222d032eea6b245780e845ad213dab28cdd) +`BPF_FUNC_xdp_output()` | 5.6 | GPL | [`d831ee84bfc9`](https://github.com/torvalds/linux/commit/d831ee84bfc9173eecf30dbbc2553ae81b996c60) +`BPF_FUNC_override_return()` | 4.16 | GPL | [`9802d86585db`](https://github.com/torvalds/linux/commit/9802d86585db91655c7d1929a4f6bbe0952ea88e) +`BPF_FUNC_sock_ops_cb_flags_set()` | 4.16 | | [`b13d88072172`](https://github.com/torvalds/linux/commit/b13d880721729384757f235166068c315326f4a1) + +Note: GPL-only BPF helpers require a GPL-compatible license. The current licenses considered GPL-compatible by the kernel are: + +* GPL +* GPL v2 +* GPL and additional rights +* Dual BSD/GPL +* Dual MIT/GPL +* Dual MPL/GPL + +Check the list of GPL-compatible licenses in your [kernel source code](https://github.com/torvalds/linux/blob/master/include/linux/license.h). + +## Program Types +The list of program types and supported helper functions can be retrieved with: + + git grep -W 'func_proto(enum bpf_func_id func_id' kernel/ net/ drivers/ + +|Program Type| Helper Functions| +|------------|-----------------| +|`BPF_PROG_TYPE_SOCKET_FILTER`|`BPF_FUNC_skb_load_bytes()`
`BPF_FUNC_skb_load_bytes_relative()`
`BPF_FUNC_get_socket_cookie()`
`BPF_FUNC_get_socket_uid()`
`BPF_FUNC_perf_event_output()`
`Base functions`| +|`BPF_PROG_TYPE_KPROBE`|`BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_stackid()`
`BPF_FUNC_get_stack()`
`BPF_FUNC_perf_event_read_value()`
`BPF_FUNC_override_return()`
`Tracing functions`| +|`BPF_PROG_TYPE_SCHED_CLS`
`BPF_PROG_TYPE_SCHED_ACT`|`BPF_FUNC_skb_store_bytes()`
`BPF_FUNC_skb_load_bytes()`
`BPF_FUNC_skb_load_bytes_relative()`
`BPF_FUNC_skb_pull_data()`
`BPF_FUNC_csum_diff()`
`BPF_FUNC_csum_update()`
`BPF_FUNC_l3_csum_replace()`
`BPF_FUNC_l4_csum_replace()`
`BPF_FUNC_clone_redirect()`
`BPF_FUNC_get_cgroup_classid()`
`BPF_FUNC_skb_vlan_push()`
`BPF_FUNC_skb_vlan_pop()`
`BPF_FUNC_skb_change_proto()`
`BPF_FUNC_skb_change_type()`
`BPF_FUNC_skb_adjust_room()`
`BPF_FUNC_skb_change_tail()`
`BPF_FUNC_skb_get_tunnel_key()`
`BPF_FUNC_skb_set_tunnel_key()`
`BPF_FUNC_skb_get_tunnel_opt()`
`BPF_FUNC_skb_set_tunnel_opt()`
`BPF_FUNC_redirect()`
`BPF_FUNC_get_route_realm()`
`BPF_FUNC_get_hash_recalc()`
`BPF_FUNC_set_hash_invalid()`
`BPF_FUNC_set_hash()`
`BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_smp_processor_id()`
`BPF_FUNC_skb_under_cgroup()`
`BPF_FUNC_get_socket_cookie()`
`BPF_FUNC_get_socket_uid()`
`BPF_FUNC_fib_lookup()`
`BPF_FUNC_skb_get_xfrm_state()`
`BPF_FUNC_skb_cgroup_id()`
`Base functions`| +|`BPF_PROG_TYPE_TRACEPOINT`|`BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_stackid()`
`BPF_FUNC_get_stack()`
`BPF_FUNC_d_path()`
`Tracing functions`| +|`BPF_PROG_TYPE_XDP`| `BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_smp_processor_id()`
`BPF_FUNC_csum_diff()`
`BPF_FUNC_xdp_adjust_head()`
`BPF_FUNC_xdp_adjust_meta()`
`BPF_FUNC_redirect()`
`BPF_FUNC_redirect_map()`
`BPF_FUNC_xdp_adjust_tail()`
`BPF_FUNC_fib_lookup()`
`Base functions`| +|`BPF_PROG_TYPE_PERF_EVENT`| `BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_stackid()`
`BPF_FUNC_get_stack()`
`BPF_FUNC_perf_prog_read_value()`
`Tracing functions`| +|`BPF_PROG_TYPE_CGROUP_SKB`|`BPF_FUNC_skb_load_bytes()`
`BPF_FUNC_skb_load_bytes_relative()`
`BPF_FUNC_get_socket_cookie()`
`BPF_FUNC_get_socket_uid()`
`Base functions`| +|`BPF_PROG_TYPE_CGROUP_SOCK`|`BPF_FUNC_get_current_uid_gid()`
`Base functions`| +|`BPF_PROG_TYPE_LWT_IN`|`BPF_FUNC_lwt_push_encap()`
`LWT functions`
`Base functions`| +|`BPF_PROG_TYPE_LWT_OUT`| `LWT functions`
`Base functions`| +|`BPF_PROG_TYPE_LWT_XMIT`| `BPF_FUNC_skb_get_tunnel_key()`
`BPF_FUNC_skb_set_tunnel_key()`
`BPF_FUNC_skb_get_tunnel_opt()`
`BPF_FUNC_skb_set_tunnel_opt()`
`BPF_FUNC_redirect()`
`BPF_FUNC_clone_redirect()`
`BPF_FUNC_skb_change_tail()`
`BPF_FUNC_skb_change_head()`
`BPF_FUNC_skb_store_bytes()`
`BPF_FUNC_csum_update()`
`BPF_FUNC_l3_csum_replace()`
`BPF_FUNC_l4_csum_replace()`
`BPF_FUNC_set_hash_invalid()`
`LWT functions`| +|`BPF_PROG_TYPE_SOCK_OPS`|`BPF_FUNC_setsockopt()`
`BPF_FUNC_getsockopt()`
`BPF_FUNC_sock_ops_cb_flags_set()`
`BPF_FUNC_sock_map_update()`
`BPF_FUNC_sock_hash_update()`
`BPF_FUNC_get_socket_cookie()`
`Base functions`| +|`BPF_PROG_TYPE_SK_SKB`|`BPF_FUNC_skb_store_bytes()`
`BPF_FUNC_skb_load_bytes()`
`BPF_FUNC_skb_pull_data()`
`BPF_FUNC_skb_change_tail()`
`BPF_FUNC_skb_change_head()`
`BPF_FUNC_get_socket_cookie()`
`BPF_FUNC_get_socket_uid()`
`BPF_FUNC_sk_redirect_map()`
`BPF_FUNC_sk_redirect_hash()`
`BPF_FUNC_sk_lookup_tcp()`
`BPF_FUNC_sk_lookup_udp()`
`BPF_FUNC_sk_release()`
`Base functions`| +|`BPF_PROG_TYPE_CGROUP_DEVICE`|`BPF_FUNC_map_lookup_elem()`
`BPF_FUNC_map_update_elem()`
`BPF_FUNC_map_delete_elem()`
`BPF_FUNC_get_current_uid_gid()`
`BPF_FUNC_trace_printk()`| +|`BPF_PROG_TYPE_SK_MSG`|`BPF_FUNC_msg_redirect_map()`
`BPF_FUNC_msg_redirect_hash()`
`BPF_FUNC_msg_apply_bytes()`
`BPF_FUNC_msg_cork_bytes()`
`BPF_FUNC_msg_pull_data()`
`BPF_FUNC_msg_push_data()`
`BPF_FUNC_msg_pop_data()`
`Base functions`| +|`BPF_PROG_TYPE_RAW_TRACEPOINT`|`BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_stackid()`
`BPF_FUNC_get_stack()`
`BPF_FUNC_skb_output()`
`Tracing functions`| +|`BPF_PROG_TYPE_CGROUP_SOCK_ADDR`|`BPF_FUNC_get_current_uid_gid()`
`BPF_FUNC_bind()`
`BPF_FUNC_get_socket_cookie()`
`Base functions`| +|`BPF_PROG_TYPE_LWT_SEG6LOCAL`|`BPF_FUNC_lwt_seg6_store_bytes()`
`BPF_FUNC_lwt_seg6_action()`
`BPF_FUNC_lwt_seg6_adjust_srh()`
`LWT functions`| +|`BPF_PROG_TYPE_LIRC_MODE2`|`BPF_FUNC_rc_repeat()`
`BPF_FUNC_rc_keydown()`
`BPF_FUNC_rc_pointer_rel()`
`BPF_FUNC_map_lookup_elem()`
`BPF_FUNC_map_update_elem()`
`BPF_FUNC_map_delete_elem()`
`BPF_FUNC_ktime_get_ns()`
`BPF_FUNC_tail_call()`
`BPF_FUNC_get_prandom_u32()`
`BPF_FUNC_trace_printk()`| +|`BPF_PROG_TYPE_SK_REUSEPORT`|`BPF_FUNC_sk_select_reuseport()`
`BPF_FUNC_skb_load_bytes()`
`BPF_FUNC_load_bytes_relative()`
`Base functions`| +|`BPF_PROG_TYPE_FLOW_DISSECTOR`|`BPF_FUNC_skb_load_bytes()`
`Base functions`| + +|Function Group| Functions| +|------------------|-------| +|`Base functions`| `BPF_FUNC_map_lookup_elem()`
`BPF_FUNC_map_update_elem()`
`BPF_FUNC_map_delete_elem()`
`BPF_FUNC_map_peek_elem()`
`BPF_FUNC_map_pop_elem()`
`BPF_FUNC_map_push_elem()`
`BPF_FUNC_get_prandom_u32()`
`BPF_FUNC_get_smp_processor_id()`
`BPF_FUNC_get_numa_node_id()`
`BPF_FUNC_tail_call()`
`BPF_FUNC_ktime_get_boot_ns()`
`BPF_FUNC_ktime_get_ns()`
`BPF_FUNC_trace_printk()`
`BPF_FUNC_spin_lock()`
`BPF_FUNC_spin_unlock()` | +|`Tracing functions`|`BPF_FUNC_map_lookup_elem()`
`BPF_FUNC_map_update_elem()`
`BPF_FUNC_map_delete_elem()`
`BPF_FUNC_probe_read()`
`BPF_FUNC_ktime_get_boot_ns()`
`BPF_FUNC_ktime_get_ns()`
`BPF_FUNC_tail_call()`
`BPF_FUNC_get_current_pid_tgid()`
`BPF_FUNC_get_current_task()`
`BPF_FUNC_get_current_uid_gid()`
`BPF_FUNC_get_current_comm()`
`BPF_FUNC_trace_printk()`
`BPF_FUNC_get_smp_processor_id()`
`BPF_FUNC_get_numa_node_id()`
`BPF_FUNC_perf_event_read()`
`BPF_FUNC_probe_write_user()`
`BPF_FUNC_current_task_under_cgroup()`
`BPF_FUNC_get_prandom_u32()`
`BPF_FUNC_probe_read_str()`
`BPF_FUNC_get_current_cgroup_id()`
`BPF_FUNC_send_signal()`
`BPF_FUNC_probe_read_kernel()`
`BPF_FUNC_probe_read_kernel_str()`
`BPF_FUNC_probe_read_user()`
`BPF_FUNC_probe_read_user_str()`
`BPF_FUNC_send_signal_thread()`
`BPF_FUNC_get_ns_current_pid_tgid()`
`BPF_FUNC_xdp_output()`
`BPF_FUNC_get_task_stack()`| +|`LWT functions`| `BPF_FUNC_skb_load_bytes()`
`BPF_FUNC_skb_pull_data()`
`BPF_FUNC_csum_diff()`
`BPF_FUNC_get_cgroup_classid()`
`BPF_FUNC_get_route_realm()`
`BPF_FUNC_get_hash_recalc()`
`BPF_FUNC_perf_event_output()`
`BPF_FUNC_get_smp_processor_id()`
`BPF_FUNC_skb_under_cgroup()`| diff --git a/bcc-documents/kernel_config.md b/bcc-documents/kernel_config.md new file mode 100644 index 0000000..c20dfc7 --- /dev/null +++ b/bcc-documents/kernel_config.md @@ -0,0 +1,48 @@ +# Kernel Configuration for BPF Features + +## BPF Related Kernel Configurations + +| Functionalities | Kernel Configuration | Description | +|:----------------|:---------------------|:------------| +| **Basic** | CONFIG_BPF_SYSCALL | Enable the bpf() system call | +| | CONFIG_BPF_JIT | BPF programs are normally handled by a BPF interpreter. This option allows the kernel to generate native code when a program is loaded into the kernel. This will significantly speed-up processing of BPF programs | +| | CONFIG_HAVE_BPF_JIT | Enable BPF Just In Time compiler | +| | CONFIG_HAVE_EBPF_JIT | Extended BPF JIT (eBPF) | +| | CONFIG_HAVE_CBPF_JIT | Classic BPF JIT (cBPF) | +| | CONFIG_MODULES | Enable to build loadable kernel modules | +| | CONFIG_BPF | BPF VM interpreter | +| | CONFIG_BPF_EVENTS | Allow the user to attach BPF programs to kprobe, uprobe, and tracepoint events | +| | CONFIG_PERF_EVENTS | Kernel performance events and counters | +| | CONFIG_HAVE_PERF_EVENTS | Enable perf events | +| | CONFIG_PROFILING | Enable the extended profiling support mechanisms used by profilers | +| **BTF** | CONFIG_DEBUG_INFO_BTF | Generate deduplicated BTF type information from DWARF debug info | +| | CONFIG_PAHOLE_HAS_SPLIT_BTF | Generate BTF for each selected kernel module | +| | CONFIG_DEBUG_INFO_BTF_MODULES | Generate compact split BTF type information for kernel modules | +| **Security** | CONFIG_BPF_JIT_ALWAYS_ON | Enable BPF JIT and removes BPF interpreter to avoid speculative execution | +| | CONFIG_BPF_UNPRIV_DEFAULT_OFF | Disable unprivileged BPF by default by setting | +| **Cgroup** | CONFIG_CGROUP_BPF | Support for BPF programs attached to cgroups | +| **Network** | CONFIG_BPFILTER | BPF based packet filtering framework (BPFILTER) | +| | CONFIG_BPFILTER_UMH | This builds bpfilter kernel module with embedded user mode helper | +| | CONFIG_NET_CLS_BPF | BPF-based classifier - to classify packets based on programmable BPF (JIT'ed) filters as an alternative to ematches | +| | CONFIG_NET_ACT_BPF | Execute BPF code on packets. The BPF code will decide if the packet should be dropped or not | +| | CONFIG_BPF_STREAM_PARSER | Enable this to allow a TCP stream parser to be used with BPF_MAP_TYPE_SOCKMAP | +| | CONFIG_LWTUNNEL_BPF | Allow to run BPF programs as a nexthop action following a route lookup for incoming and outgoing packets | +| | CONFIG_NETFILTER_XT_MATCH_BPF | BPF matching applies a linux socket filter to each packet and accepts those for which the filter returns non-zero | +| | CONFIG_IPV6_SEG6_BPF | To support BPF seg6local hook. bpf: Add IPv6 Segment Routing helpersy. [Reference](https://github.com/torvalds/linux/commit/fe94cc290f535709d3c5ebd1e472dfd0aec7ee7) | +| **kprobes** | CONFIG_KPROBE_EVENTS | This allows the user to add tracing events (similar to tracepoints) on the fly via the ftrace interface | +| | CONFIG_KPROBES | Enable kprobes-based dynamic events | +| | CONFIG_HAVE_KPROBES | Check if krpobes enabled | +| | CONFIG_HAVE_REGS_AND_STACK_ACCESS_API | This symbol should be selected by an architecture if it supports the API needed to access registers and stack entries from pt_regs. For example the kprobes-based event tracer needs this API. | +| | CONFIG_KPROBES_ON_FTRACE | Have kprobes on function tracer if arch supports full passing of pt_regs to function tracing | +| **kprobe multi** | CONFIG_FPROBE | Enable fprobe to attach the probe on multiple functions at once | +| **kprobe override** | CONFIG_BPF_KPROBE_OVERRIDE | Enable BPF programs to override a kprobed function | +| **uprobes** | CONFIG_UPROBE_EVENTS | Enable uprobes-based dynamic events | +| | CONFIG_ARCH_SUPPORTS_UPROBES | Arch specific uprobes support | +| | CONFIG_UPROBES | Uprobes is the user-space counterpart to kprobes: they enable instrumentation applications (such as 'perf probe') to establish unintrusive probes in user-space binaries and libraries, by executing handler functions when the probes are hit by user-space applications. | +| | CONFIG_MMU | MMU-based virtualised addressing space support by paged memory management | +| **Tracepoints** | CONFIG_TRACEPOINTS | Enable inserting tracepoints in the kernel and connect to proble functions | +| | CONFIG_HAVE_SYSCALL_TRACEPOINTS | Enable syscall enter/exit tracing | +| **Raw Tracepoints** | Same as Tracepoints | | +| **LSM** | CONFIG_BPF_LSM | Enable instrumentation of the security hooks with BPF programs for implementing dynamic MAC and Audit Policies | +| **LIRC** | CONFIG_BPF_LIRC_MODE2 | Allow attaching BPF programs to a lirc device | + diff --git a/bcc-documents/reference_guide.md b/bcc-documents/reference_guide.md new file mode 100644 index 0000000..8ac898b --- /dev/null +++ b/bcc-documents/reference_guide.md @@ -0,0 +1,2609 @@ +# bcc Reference Guide + +Intended for search (Ctrl-F) and reference. For tutorials, start with [tutorial.md](tutorial.md). + +This guide is incomplete. If something feels missing, check the bcc and kernel source. And if you confirm we're missing something, please send a pull request to fix it, and help out everyone. + +## Contents + +- [BPF C](#bpf-c) + - [Events & Arguments](#events--arguments) + - [1. kprobes](#1-kprobes) + - [2. kretprobes](#2-kretprobes) + - [3. Tracepoints](#3-tracepoints) + - [4. uprobes](#4-uprobes) + - [5. uretprobes](#5-uretprobes) + - [6. USDT probes](#6-usdt-probes) + - [7. Raw Tracepoints](#7-raw-tracepoints) + - [8. system call tracepoints](#8-system-call-tracepoints) + - [9. kfuncs](#9-kfuncs) + - [10. kretfuncs](#10-kretfuncs) + - [11. lsm probes](#11-lsm-probes) + - [12. bpf iterators](#12-bpf-iterators) + - [Data](#data) + - [1. bpf_probe_read_kernel()](#1-bpf_probe_read_kernel) + - [2. bpf_probe_read_kernel_str()](#2-bpf_probe_read_kernel_str) + - [3. bpf_ktime_get_ns()](#3-bpf_ktime_get_ns) + - [4. bpf_get_current_pid_tgid()](#4-bpf_get_current_pid_tgid) + - [5. bpf_get_current_uid_gid()](#5-bpf_get_current_uid_gid) + - [6. bpf_get_current_comm()](#6-bpf_get_current_comm) + - [7. bpf_get_current_task()](#7-bpf_get_current_task) + - [8. bpf_log2l()](#8-bpf_log2l) + - [9. bpf_get_prandom_u32()](#9-bpf_get_prandom_u32) + - [10. bpf_probe_read_user()](#10-bpf_probe_read_user) + - [11. bpf_probe_read_user_str()](#11-bpf_probe_read_user_str) + - [12. bpf_get_ns_current_pid_tgid()](#12-bpf_get_ns_current_pid_tgid) + - [Debugging](#debugging) + - [1. bpf_override_return()](#1-bpf_override_return) + - [Output](#output) + - [1. bpf_trace_printk()](#1-bpf_trace_printk) + - [2. BPF_PERF_OUTPUT](#2-bpf_perf_output) + - [3. perf_submit()](#3-perf_submit) + - [4. perf_submit_skb()](#4-perf_submit_skb) + - [5. BPF_RINGBUF_OUTPUT](#5-bpf_ringbuf_output) + - [6. ringbuf_output()](#6-ringbuf_output) + - [7. ringbuf_reserve()](#7-ringbuf_reserve) + - [8. ringbuf_submit()](#8-ringbuf_submit) + - [9. ringbuf_discard()](#9-ringbuf_discard) + - [Maps](#maps) + - [1. BPF_TABLE](#1-bpf_table) + - [2. BPF_HASH](#2-bpf_hash) + - [3. BPF_ARRAY](#3-bpf_array) + - [4. BPF_HISTOGRAM](#4-bpf_histogram) + - [5. BPF_STACK_TRACE](#5-bpf_stack_trace) + - [6. BPF_PERF_ARRAY](#6-bpf_perf_array) + - [7. BPF_PERCPU_HASH](#7-bpf_percpu_hash) + - [8. BPF_PERCPU_ARRAY](#8-bpf_percpu_array) + - [9. BPF_LPM_TRIE](#9-bpf_lpm_trie) + - [10. BPF_PROG_ARRAY](#10-bpf_prog_array) + - [11. BPF_DEVMAP](#11-bpf_devmap) + - [12. BPF_CPUMAP](#12-bpf_cpumap) + - [13. BPF_XSKMAP](#13-bpf_xskmap) + - [14. BPF_ARRAY_OF_MAPS](#14-bpf_array_of_maps) + - [15. BPF_HASH_OF_MAPS](#15-bpf_hash_of_maps) + - [16. BPF_STACK](#16-bpf_stack) + - [17. BPF_QUEUE](#17-bpf_queue) + - [18. BPF_SOCKHASH](#18-bpf_sockhash) + - [19. map.lookup()](#19-maplookup) + - [20. map.lookup_or_try_init()](#20-maplookup_or_try_init) + - [21. map.delete()](#21-mapdelete) + - [22. map.update()](#22-mapupdate) + - [23. map.insert()](#23-mapinsert) + - [24. map.increment()](#24-mapincrement) + - [25. map.get_stackid()](#25-mapget_stackid) + - [26. map.perf_read()](#26-mapperf_read) + - [27. map.call()](#27-mapcall) + - [28. map.redirect_map()](#28-mapredirect_map) + - [29. map.push()](#29-mappush) + - [30. map.pop()](#30-mappop) + - [31. map.peek()](#31-mappeek) + - [32. map.sock_hash_update()](#32-mapsock_hash_update) + - [33. map.msg_redirect_hash()](#33-mapmsg_redirect_hash) + - [34. map.sk_redirect_hash()](#34-mapsk_redirect_hash) + - [Licensing](#licensing) + - [Rewriter](#rewriter) + +- [bcc Python](#bcc-python) + - [Initialization](#initialization) + - [1. BPF](#1-bpf) + - [2. USDT](#2-usdt) + - [Events](#events) + - [1. attach_kprobe()](#1-attach_kprobe) + - [2. attach_kretprobe()](#2-attach_kretprobe) + - [3. attach_tracepoint()](#3-attach_tracepoint) + - [4. attach_uprobe()](#4-attach_uprobe) + - [5. attach_uretprobe()](#5-attach_uretprobe) + - [6. USDT.enable_probe()](#6-usdtenable_probe) + - [7. attach_raw_tracepoint()](#7-attach_raw_tracepoint) + - [8. attach_raw_socket()](#8-attach_raw_socket) + - [9. attach_xdp()](#9-attach_xdp) + - [10. attach_func()](#10-attach_func) + - [11. detach_func()](#11-detach_func) + - [12. detach_kprobe()](#12-detach_kprobe) + - [13. detach_kretprobe()](#13-detach_kretprobe) + - [Debug Output](#debug-output) + - [1. trace_print()](#1-trace_print) + - [2. trace_fields()](#2-trace_fields) + - [Output APIs](#output-apis) + - [1. perf_buffer_poll()](#1-perf_buffer_poll) + - [2. ring_buffer_poll()](#2-ring_buffer_poll) + - [3. ring_buffer_consume()](#3-ring_buffer_consume) + - [Map APIs](#map-apis) + - [1. get_table()](#1-get_table) + - [2. open_perf_buffer()](#2-open_perf_buffer) + - [3. items()](#3-items) + - [4. values()](#4-values) + - [5. clear()](#5-clear) + - [6. items_lookup_and_delete_batch()](#6-items_lookup_and_delete_batch) + - [7. items_lookup_batch()](#7-items_lookup_batch) + - [8. items_delete_batch()](#8-items_delete_batch) + - [9. items_update_batch()](#9-items_update_batch) + - [10. print_log2_hist()](#10-print_log2_hist) + - [11. print_linear_hist()](#11-print_linear_hist) + - [12. open_ring_buffer()](#12-open_ring_buffer) + - [13. push()](#13-push) + - [14. pop()](#14-pop) + - [15. peek()](#15-peek) + - [Helpers](#helpers) + - [1. ksym()](#1-ksym) + - [2. ksymname()](#2-ksymname) + - [3. sym()](#3-sym) + - [4. num_open_kprobes()](#4-num_open_kprobes) + - [5. get_syscall_fnname()](#5-get_syscall_fnname) + +- [BPF Errors](#bpf-errors) + - [1. Invalid mem access](#1-invalid-mem-access) + - [2. Cannot call GPL only function from proprietary program](#2-cannot-call-gpl-only-function-from-proprietary-program) + +- [Environment Variables](#Environment-Variables) + - [1. kernel source directory](#1-kernel-source-directory) + - [2. kernel version overriding](#2-kernel-version-overriding) + +# BPF C + +This section describes the C part of a bcc program. + +## Events & Arguments + +### 1. kprobes + +Syntax: kprobe__*kernel_function_name* + +```kprobe__``` is a special prefix that creates a kprobe (dynamic tracing of a kernel function call) for the kernel function name provided as the remainder. You can also use kprobes by declaring a normal C function, then using the Python ```BPF.attach_kprobe()``` (covered later) to associate it with a kernel function. + +Arguments are specified on the function declaration: kprobe__*kernel_function_name*(struct pt_regs *ctx [, *argument1* ...]) + +For example: + +```C +int kprobe__tcp_v4_connect(struct pt_regs *ctx, struct sock *sk) { + [...] +} +``` + +This instruments the tcp_v4_connect() kernel function using a kprobe, with the following arguments: + +- ```struct pt_regs *ctx```: Registers and BPF context. +- ```struct sock *sk```: First argument to tcp_v4_connect(). + +The first argument is always ```struct pt_regs *```, the remainder are the arguments to the function (they don't need to be specified, if you don't intend to use them). + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/4afa96a71c5dbfc4c507c3355e20baa6c184a3a8/examples/tracing/tcpv4connect.py#L28) ([output](https://github.com/iovisor/bcc/blob/5bd0eb21fd148927b078deb8ac29fff2fb044b66/examples/tracing/tcpv4connect_example.txt#L8)), +[code](https://github.com/iovisor/bcc/commit/310ab53710cfd46095c1f6b3e44f1dbc8d1a41d8#diff-8cd1822359ffee26e7469f991ce0ef00R26) ([output](https://github.com/iovisor/bcc/blob/3b9679a3bd9b922c736f6061dc65cb56de7e0250/examples/tracing/bitehist_example.txt#L6)) + + +### 2. kretprobes + +Syntax: kretprobe__*kernel_function_name* + +```kretprobe__``` is a special prefix that creates a kretprobe (dynamic tracing of a kernel function return) for the kernel function name provided as the remainder. You can also use kretprobes by declaring a normal C function, then using the Python ```BPF.attach_kretprobe()``` (covered later) to associate it with a kernel function. + +Return value is available as ```PT_REGS_RC(ctx)```, given a function declaration of: kretprobe__*kernel_function_name*(struct pt_regs *ctx) + +For example: + +```C +int kretprobe__tcp_v4_connect(struct pt_regs *ctx) +{ + int ret = PT_REGS_RC(ctx); + [...] +} +``` + +This instruments the return of the tcp_v4_connect() kernel function using a kretprobe, and stores the return value in ```ret```. + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/4afa96a71c5dbfc4c507c3355e20baa6c184a3a8/examples/tracing/tcpv4connect.py#L38) ([output](https://github.com/iovisor/bcc/blob/5bd0eb21fd148927b078deb8ac29fff2fb044b66/examples/tracing/tcpv4connect_example.txt#L8)) + +### 3. Tracepoints + +Syntax: TRACEPOINT_PROBE(*category*, *event*) + +This is a macro that instruments the tracepoint defined by *category*:*event*. + +The tracepoint name is `:`. +The probe function name is `tracepoint____`. + +Arguments are available in an ```args``` struct, which are the tracepoint arguments. One way to list these is to cat the relevant format file under /sys/kernel/debug/tracing/events/*category*/*event*/format. + +The ```args``` struct can be used in place of ``ctx`` in each functions requiring a context as an argument. This includes notably [perf_submit()](#3-perf_submit). + +For example: + +```C +TRACEPOINT_PROBE(random, urandom_read) { + // args is from /sys/kernel/debug/tracing/events/random/urandom_read/format + bpf_trace_printk("%d\\n", args->got_bits); + return 0; +} +``` + +This instruments the tracepoint `random:urandom_read tracepoint`, and prints the tracepoint argument ```got_bits```. +When using Python API, this probe is automatically attached to the right tracepoint target. +For C++, this tracepoint probe can be attached by specifying the tracepoint target and function name explicitly: +`BPF::attach_tracepoint("random:urandom_read", "tracepoint__random__urandom_read")` +Note the name of the probe function defined above is `tracepoint__random__urandom_read`. + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/a4159da8c4ea8a05a3c6e402451f530d6e5a8b41/examples/tracing/urandomread.py#L19) ([output](https://github.com/iovisor/bcc/commit/e422f5e50ecefb96579b6391a2ada7f6367b83c4#diff-41e5ecfae4a3b38de5f4e0887ed160e5R10)), +[search /examples](https://github.com/iovisor/bcc/search?q=TRACEPOINT_PROBE+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=TRACEPOINT_PROBE+path%3Atools&type=Code) + +### 4. uprobes + +These are instrumented by declaring a normal function in C, then associating it as a uprobe probe in Python via ```BPF.attach_uprobe()``` (covered later). + +Arguments can be examined using ```PT_REGS_PARM``` macros. + +For example: + +```C +int count(struct pt_regs *ctx) { + char buf[64]; + bpf_probe_read_user(&buf, sizeof(buf), (void *)PT_REGS_PARM1(ctx)); + bpf_trace_printk("%s %d", buf, PT_REGS_PARM2(ctx)); + return(0); +} +``` + +This reads the first argument as a string, and then prints it with the second argument as an integer. + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/4afa96a71c5dbfc4c507c3355e20baa6c184a3a8/examples/tracing/strlen_count.py#L26) + +### 5. uretprobes + +These are instrumented by declaring a normal function in C, then associating it as a uretprobe probe in Python via ```BPF.attach_uretprobe()``` (covered later). + +Return value is available as ```PT_REGS_RC(ctx)```, given a function declaration of: *function_name*(struct pt_regs *ctx) + +For example: + +```C +BPF_HISTOGRAM(dist); +int count(struct pt_regs *ctx) { + dist.increment(PT_REGS_RC(ctx)); + return 0; +} +``` + +This increments the bucket in the ```dist``` histogram that is indexed by the return value. + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/4afa96a71c5dbfc4c507c3355e20baa6c184a3a8/examples/tracing/strlen_hist.py#L39) ([output](https://github.com/iovisor/bcc/blob/4afa96a71c5dbfc4c507c3355e20baa6c184a3a8/examples/tracing/strlen_hist.py#L15)), +[code](https://github.com/iovisor/bcc/blob/4afa96a71c5dbfc4c507c3355e20baa6c184a3a8/tools/bashreadline.py) ([output](https://github.com/iovisor/bcc/commit/aa87997d21e5c1a6a20e2c96dd25eb92adc8e85d#diff-2fd162f9e594206f789246ce97d62cf0R7)) + +### 6. USDT probes + +These are User Statically-Defined Tracing (USDT) probes, which may be placed in some applications or libraries to provide a user-level equivalent of tracepoints. The primary BPF method provided for USDT support method is ```enable_probe()```. USDT probes are instrumented by declaring a normal function in C, then associating it as a USDT probe in Python via ```USDT.enable_probe()```. + +Arguments can be read via: bpf_usdt_readarg(*index*, ctx, &addr) + +For example: + +```C +int do_trace(struct pt_regs *ctx) { + uint64_t addr; + char path[128]; + bpf_usdt_readarg(6, ctx, &addr); + bpf_probe_read_user(&path, sizeof(path), (void *)addr); + bpf_trace_printk("path:%s\\n", path); + return 0; +}; +``` + +This reads the sixth USDT argument, and then pulls it in as a string to ```path```. + +When initializing USDTs via the third argument of ```BPF::init``` in the C API, if any USDT fails to ```init```, entire ```BPF::init``` will fail. If you're OK with some USDTs failing to ```init```, use ```BPF::init_usdt``` before calling ```BPF::init```. + +Examples in situ: +[code](https://github.com/iovisor/bcc/commit/4f88a9401357d7b75e917abd994aa6ea97dda4d3#diff-04a7cad583be5646080970344c48c1f4R24), +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_usdt_readarg+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_usdt_readarg+path%3Atools&type=Code) + +### 7. Raw Tracepoints + +Syntax: RAW_TRACEPOINT_PROBE(*event*) + +This is a macro that instruments the raw tracepoint defined by *event*. + +The argument is a pointer to struct ```bpf_raw_tracepoint_args```, which is defined in [bpf.h](https://github.com/iovisor/bcc/blob/master/src/cc/compat/linux/virtual_bpf.h). The struct field ```args``` contains all parameters of the raw tracepoint where you can found at linux tree [include/trace/events](https://github.com/torvalds/linux/tree/master/include/trace/events) +directory. + +For example: +```C +RAW_TRACEPOINT_PROBE(sched_switch) +{ + // TP_PROTO(bool preempt, struct task_struct *prev, struct task_struct *next) + struct task_struct *prev = (struct task_struct *)ctx->args[1]; + struct task_struct *next= (struct task_struct *)ctx->args[2]; + s32 prev_tgid, next_tgid; + + bpf_probe_read_kernel(&prev_tgid, sizeof(prev->tgid), &prev->tgid); + bpf_probe_read_kernel(&next_tgid, sizeof(next->tgid), &next->tgid); + bpf_trace_printk("%d -> %d\\n", prev_tgid, next_tgid); +} +``` + +This instruments the sched:sched_switch tracepoint, and prints the prev and next tgid. + +Examples in situ: +[search /tools](https://github.com/iovisor/bcc/search?q=RAW_TRACEPOINT_PROBE+path%3Atools&type=Code) + +### 8. system call tracepoints + +Syntax: ```syscall__SYSCALLNAME``` + +```syscall__``` is a special prefix that creates a kprobe for the system call name provided as the remainder. You can use it by declaring a normal C function, then using the Python ```BPF.get_syscall_fnname(SYSCALLNAME)``` and ```BPF.attach_kprobe()``` to associate it. + +Arguments are specified on the function declaration: ```syscall__SYSCALLNAME(struct pt_regs *ctx, [, argument1 ...])```. + +For example: +```C +int syscall__execve(struct pt_regs *ctx, + const char __user *filename, + const char __user *const __user *__argv, + const char __user *const __user *__envp) +{ + [...] +} +``` + +This instruments the execve system call. + +The first argument is always ```struct pt_regs *```, the remainder are the arguments to the function (they don't need to be specified, if you don't intend to use them). + +Corresponding Python code: +```Python +b = BPF(text=bpf_text) +execve_fnname = b.get_syscall_fnname("execve") +b.attach_kprobe(event=execve_fnname, fn_name="syscall__execve") +``` + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/552658edda09298afdccc8a4b5e17311a2d8a771/tools/execsnoop.py#L101) ([output](https://github.com/iovisor/bcc/blob/552658edda09298afdccc8a4b5e17311a2d8a771/tools/execsnoop_example.txt#L8)) + +### 9. kfuncs + +Syntax: KFUNC_PROBE(*function*, typeof(arg1) arg1, typeof(arg2) arge ...) + +This is a macro that instruments the kernel function via trampoline +*before* the function is executed. It's defined by *function* name and +the function arguments defined as *argX*. + +For example: +```C +KFUNC_PROBE(do_sys_open, int dfd, const char *filename, int flags, int mode) +{ + ... +``` + +This instruments the do_sys_open kernel function and make its arguments +accessible as standard argument values. + +Examples in situ: +[search /tools](https://github.com/iovisor/bcc/search?q=KFUNC_PROBE+path%3Atools&type=Code) + +### 10. kretfuncs + +Syntax: KRETFUNC_PROBE(*event*, typeof(arg1) arg1, typeof(arg2) arge ..., int ret) + +This is a macro that instruments the kernel function via trampoline +*after* the function is executed. It's defined by *function* name and +the function arguments defined as *argX*. + +The last argument of the probe is the return value of the instrumented function. + +For example: +```C +KRETFUNC_PROBE(do_sys_open, int dfd, const char *filename, int flags, int mode, int ret) +{ + ... +``` + +This instruments the do_sys_open kernel function and make its arguments +accessible as standard argument values together with its return value. + +Examples in situ: +[search /tools](https://github.com/iovisor/bcc/search?q=KRETFUNC_PROBE+path%3Atools&type=Code) + + +### 11. LSM Probes + +Syntax: LSM_PROBE(*hook*, typeof(arg1) arg1, typeof(arg2) arg2 ...) + +This is a macro that instruments an LSM hook as a BPF program. It can be +used to audit security events and implement MAC security policies in BPF. +It is defined by specifying the hook name followed by its arguments. + +Hook names can be found in +[include/linux/security.h](https://github.com/torvalds/linux/blob/v5.15/include/linux/security.h#L260) +by taking functions like `security_hookname` and taking just the `hookname` part. +For example, `security_bpf` would simply become `bpf`. + +Unlike other BPF program types, the return value specified in an LSM probe +matters. A return value of 0 allows the hook to succeed, whereas +any non-zero return value will cause the hook to fail and deny the +security operation. + +The following example instruments a hook that denies all future BPF operations: +```C +LSM_PROBE(bpf, int cmd, union bpf_attr *attr, unsigned int size) +{ + return -EPERM; +} +``` + +This instruments the `security_bpf` hook and causes it to return `-EPERM`. +Changing `return -EPERM` to `return 0` would cause the BPF program +to allow the operation instead. + +LSM probes require at least a 5.7+ kernel with the following configuation options set: +- `CONFIG_BPF_LSM=y` +- `CONFIG_LSM` comma separated string must contain "bpf" (for example, + `CONFIG_LSM="lockdown,yama,bpf"`) + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=LSM_PROBE+path%3Atests&type=Code) + +### 12. BPF ITERATORS + +Syntax: BPF_ITER(target) + +This is a macro to define a program signature for a bpf iterator program. The argument *target* specifies what to iterate for the program. + +Currently, kernel does not have interface to discover what targets are supported. A good place to find what is supported is in [tools/testing/selftests/bpf/prog_test/bpf_iter.c](https://github.com/torvalds/linux/blob/master/tools/testing/selftests/bpf/prog_tests/bpf_iter.c) and some sample bpf iter programs are in [tools/testing/selftests/bpf/progs](https://github.com/torvalds/linux/tree/master/tools/testing/selftests/bpf/progs) with file name prefix *bpf_iter*. + +The following example defines a program for target *task*, which traverses all tasks in the kernel. +```C +BPF_ITER(task) +{ + struct seq_file *seq = ctx->meta->seq; + struct task_struct *task = ctx->task; + + if (task == (void *)0) + return 0; + + ... task->pid, task->tgid, task->comm, ... + return 0; +} +``` + +BPF iterators are introduced in 5.8 kernel for task, task_file, bpf_map, netlink_sock and ipv6_route . In 5.9, support is added to tcp/udp sockets and bpf map element (hashmap, arraymap and sk_local_storage_map) traversal. + +## Data + +### 1. bpf_probe_read_kernel() + +Syntax: ```int bpf_probe_read_kernel(void *dst, int size, const void *src)``` + +Return: 0 on success + +This copies size bytes from kernel address space to the BPF stack, so that BPF can later operate on it. For safety, all kernel memory reads must pass through bpf_probe_read_kernel(). This happens automatically in some cases, such as dereferencing kernel variables, as bcc will rewrite the BPF program to include the necessary bpf_probe_read_kernel(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_probe_read_kernel+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_probe_read_kernel+path%3Atools&type=Code) + +### 2. bpf_probe_read_kernel_str() + +Syntax: ```int bpf_probe_read_kernel_str(void *dst, int size, const void *src)``` + +Return: + - \> 0 length of the string including the trailing NULL on success + - \< 0 error + +This copies a `NULL` terminated string from kernel address space to the BPF stack, so that BPF can later operate on it. In case the string length is smaller than size, the target is not padded with further `NULL` bytes. In case the string length is larger than size, just `size - 1` bytes are copied and the last byte is set to `NULL`. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_probe_read_kernel_str+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_probe_read_kernel_str+path%3Atools&type=Code) + +### 3. bpf_ktime_get_ns() + +Syntax: ```u64 bpf_ktime_get_ns(void)``` + +Return: u64 number of nanoseconds. Starts at system boot time but stops during suspend. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_ktime_get_ns+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_ktime_get_ns+path%3Atools&type=Code) + +### 4. bpf_get_current_pid_tgid() + +Syntax: ```u64 bpf_get_current_pid_tgid(void)``` + +Return: ```current->tgid << 32 | current->pid``` + +Returns the process ID in the lower 32 bits (kernel's view of the PID, which in user space is usually presented as the thread ID), and the thread group ID in the upper 32 bits (what user space often thinks of as the PID). By directly setting this to a u32, we discard the upper 32 bits. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_current_pid_tgid+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_current_pid_tgid+path%3Atools&type=Code) + +### 5. bpf_get_current_uid_gid() + +Syntax: ```u64 bpf_get_current_uid_gid(void)``` + +Return: ```current_gid << 32 | current_uid``` + +Returns the user ID and group IDs. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_current_uid_gid+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_current_uid_gid+path%3Atools&type=Code) + +### 6. bpf_get_current_comm() + +Syntax: ```bpf_get_current_comm(char *buf, int size_of_buf)``` + +Return: 0 on success + +Populates the first argument address with the current process name. It should be a pointer to a char array of at least size TASK_COMM_LEN, which is defined in linux/sched.h. For example: + +```C +#include + +int do_trace(struct pt_regs *ctx) { + char comm[TASK_COMM_LEN]; + bpf_get_current_comm(&comm, sizeof(comm)); +[...] +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_current_comm+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_current_comm+path%3Atools&type=Code) + +### 7. bpf_get_current_task() + +Syntax: ```bpf_get_current_task()``` + +Return: current task as a pointer to struct task_struct. + +Returns a pointer to the current task's task_struct object. This helper can be used to compute the on-CPU time for a process, identify kernel threads, get the current CPU's run queue, or retrieve many other pieces of information. + +With Linux 4.13, due to issues with field randomization, you may need two #define directives before the includes: +```C +#define randomized_struct_fields_start struct { +#define randomized_struct_fields_end }; +#include + +int do_trace(void *ctx) { + struct task_struct *t = (struct task_struct *)bpf_get_current_task(); +[...] +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_current_task+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_current_task+path%3Atools&type=Code) + +### 8. bpf_log2l() + +Syntax: ```unsigned int bpf_log2l(unsigned long v)``` + +Returns the log-2 of the provided value. This is often used to create indexes for histograms, to construct power-of-2 histograms. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_log2l+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_log2l+path%3Atools&type=Code) + +### 9. bpf_get_prandom_u32() + +Syntax: ```u32 bpf_get_prandom_u32()``` + +Returns a pseudo-random u32. + +Example in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_prandom_u32+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_prandom_u32+path%3Atools&type=Code) + +### 10. bpf_probe_read_user() + +Syntax: ```int bpf_probe_read_user(void *dst, int size, const void *src)``` + +Return: 0 on success + +This attempts to safely read size bytes from user address space to the BPF stack, so that BPF can later operate on it. For safety, all user address space memory reads must pass through bpf_probe_read_user(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_probe_read_user+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_probe_read_user+path%3Atools&type=Code) + +### 11. bpf_probe_read_user_str() + +Syntax: ```int bpf_probe_read_user_str(void *dst, int size, const void *src)``` + +Return: + - \> 0 length of the string including the trailing NULL on success + - \< 0 error + +This copies a `NULL` terminated string from user address space to the BPF stack, so that BPF can later operate on it. In case the string length is smaller than size, the target is not padded with further `NULL` bytes. In case the string length is larger than size, just `size - 1` bytes are copied and the last byte is set to `NULL`. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_probe_read_user_str+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_probe_read_user_str+path%3Atools&type=Code) + + +### 12. bpf_get_ns_current_pid_tgid() + +Syntax: ```u32 bpf_get_ns_current_pid_tgid(u64 dev, u64 ino, struct bpf_pidns_info* nsdata, u32 size)``` + +Values for *pid* and *tgid* as seen from the current *namespace* will be returned in *nsdata*. + +Return 0 on success, or one of the following in case of failure: + +- **-EINVAL** if dev and inum supplied don't match dev_t and inode number with nsfs of current task, or if dev conversion to dev_t lost high bits. + +- **-ENOENT** if pidns does not exists for the current task. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_ns_current_pid_tgid+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_ns_current_pid_tgid+path%3Atools&type=Code) + + +## Debugging + +### 1. bpf_override_return() + +Syntax: ```int bpf_override_return(struct pt_regs *, unsigned long rc)``` + +Return: 0 on success + +When used in a program attached to a function entry kprobe, causes the +execution of the function to be skipped, immediately returning `rc` instead. +This is used for targeted error injection. + +bpf_override_return will only work when the kprobed function is whitelisted to +allow error injections. Whitelisting entails tagging a function with +`ALLOW_ERROR_INJECTION()` in the kernel source tree; see `io_ctl_init` for +an example. If the kprobed function is not whitelisted, the bpf program will +fail to attach with ` ioctl(PERF_EVENT_IOC_SET_BPF): Invalid argument` + + +```C +int kprobe__io_ctl_init(void *ctx) { + bpf_override_return(ctx, -ENOMEM); + return 0; +} +``` + +## Output + +### 1. bpf_trace_printk() + +Syntax: ```int bpf_trace_printk(const char *fmt, ...)``` + +Return: 0 on success + +A simple kernel facility for printf() to the common trace_pipe (/sys/kernel/debug/tracing/trace_pipe). This is ok for some quick examples, but has limitations: 3 args max, 1 %s only, and trace_pipe is globally shared, so concurrent programs will have clashing output. A better interface is via BPF_PERF_OUTPUT(). Note that calling this helper is made simpler than the original kernel version, which has ```fmt_size``` as the second parameter. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=bpf_trace_printk+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=bpf_trace_printk+path%3Atools&type=Code) + +### 2. BPF_PERF_OUTPUT + +Syntax: ```BPF_PERF_OUTPUT(name)``` + +Creates a BPF table for pushing out custom event data to user space via a perf ring buffer. This is the preferred method for pushing per-event data to user space. + +For example: + +```C +struct data_t { + u32 pid; + u64 ts; + char comm[TASK_COMM_LEN]; +}; +BPF_PERF_OUTPUT(events); + +int hello(struct pt_regs *ctx) { + struct data_t data = {}; + + data.pid = bpf_get_current_pid_tgid(); + data.ts = bpf_ktime_get_ns(); + bpf_get_current_comm(&data.comm, sizeof(data.comm)); + + events.perf_submit(ctx, &data, sizeof(data)); + + return 0; +} +``` + +The output table is named ```events```, and data is pushed to it via ```events.perf_submit()```. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_PERF_OUTPUT+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_PERF_OUTPUT+path%3Atools&type=Code) + +### 3. perf_submit() + +Syntax: ```int perf_submit((void *)ctx, (void *)data, u32 data_size)``` + +Return: 0 on success + +A method of a BPF_PERF_OUTPUT table, for submitting custom event data to user space. See the BPF_PERF_OUTPUT entry. (This ultimately calls bpf_perf_event_output().) + +The ```ctx``` parameter is provided in [kprobes](#1-kprobes) or [kretprobes](#2-kretprobes). For ```SCHED_CLS``` or ```SOCKET_FILTER``` programs, the ```struct __sk_buff *skb``` must be used instead. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=perf_submit+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=perf_submit+path%3Atools&type=Code) + +### 4. perf_submit_skb() + +Syntax: ```int perf_submit_skb((void *)ctx, u32 packet_size, (void *)data, u32 data_size)``` + +Return: 0 on success + +A method of a BPF_PERF_OUTPUT table available in networking program types, for submitting custom event data to user space, along with the first ```packet_size``` bytes of the packet buffer. See the BPF_PERF_OUTPUT entry. (This ultimately calls bpf_perf_event_output().) + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=perf_submit_skb+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=perf_submit_skb+path%3Atools&type=Code) + +### 5. BPF_RINGBUF_OUTPUT + +Syntax: ```BPF_RINGBUF_OUTPUT(name, page_cnt)``` + +Creates a BPF table for pushing out custom event data to user space via a ringbuf ring buffer. +```BPF_RINGBUF_OUTPUT``` has several advantages over ```BPF_PERF_OUTPUT```, summarized as follows: + +- Buffer is shared across all CPUs, meaning no per-CPU allocation +- Supports two APIs for BPF programs + - ```map.ringbuf_output()``` works like ```map.perf_submit()``` (covered in [ringbuf_output](#6-ringbuf_output)) + - ```map.ringbuf_reserve()```/```map.ringbuf_submit()```/```map.ringbuf_discard()``` + split the process of reserving buffer space and submitting events into two steps + (covered in [ringbuf_reserve](#7-ringbuf_reserve), [ringbuf_submit](#8-ringbuf_submit), [ringbuf_discard](#9-ringbuf_discard)) +- BPF APIs do not require access to a CPU ctx argument +- Superior performance and latency in userspace thanks to a shared ring buffer manager +- Supports two ways of consuming data in userspace + +Starting in Linux 5.8, this should be the preferred method for pushing per-event data to user space. + +Example of both APIs: + +```C +struct data_t { + u32 pid; + u64 ts; + char comm[TASK_COMM_LEN]; +}; + +// Creates a ringbuf called events with 8 pages of space, shared across all CPUs +BPF_RINGBUF_OUTPUT(events, 8); + +int first_api_example(struct pt_regs *ctx) { + struct data_t data = {}; + + data.pid = bpf_get_current_pid_tgid(); + data.ts = bpf_ktime_get_ns(); + bpf_get_current_comm(&data.comm, sizeof(data.comm)); + + events.ringbuf_output(&data, sizeof(data), 0 /* flags */); + + return 0; +} + +int second_api_example(struct pt_regs *ctx) { + struct data_t *data = events.ringbuf_reserve(sizeof(struct data_t)); + if (!data) { // Failed to reserve space + return 1; + } + + data->pid = bpf_get_current_pid_tgid(); + data->ts = bpf_ktime_get_ns(); + bpf_get_current_comm(&data->comm, sizeof(data->comm)); + + events.ringbuf_submit(data, 0 /* flags */); + + return 0; +} +``` + +The output table is named ```events```. Data is allocated via ```events.ringbuf_reserve()``` and pushed to it via ```events.ringbuf_submit()```. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_RINGBUF_OUTPUT+path%3Aexamples&type=Code), + +### 6. ringbuf_output() + +Syntax: ```int ringbuf_output((void *)data, u64 data_size, u64 flags)``` + +Return: 0 on success + +Flags: + - ```BPF_RB_NO_WAKEUP```: Do not sent notification of new data availability + - ```BPF_RB_FORCE_WAKEUP```: Send notification of new data availability unconditionally + +A method of the BPF_RINGBUF_OUTPUT table, for submitting custom event data to user space. This method works like ```perf_submit()```, +although it does not require a ctx argument. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ringbuf_output+path%3Aexamples&type=Code), + +### 7. ringbuf_reserve() + +Syntax: ```void* ringbuf_reserve(u64 data_size)``` + +Return: Pointer to data struct on success, NULL on failure + +A method of the BPF_RINGBUF_OUTPUT table, for reserving space in the ring buffer and simultaenously +allocating a data struct for output. Must be used with one of ```ringbuf_submit``` or ```ringbuf_discard```. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ringbuf_reserve+path%3Aexamples&type=Code), + +### 8. ringbuf_submit() + +Syntax: ```void ringbuf_submit((void *)data, u64 flags)``` + +Return: Nothing, always succeeds + +Flags: + - ```BPF_RB_NO_WAKEUP```: Do not sent notification of new data availability + - ```BPF_RB_FORCE_WAKEUP```: Send notification of new data availability unconditionally + +A method of the BPF_RINGBUF_OUTPUT table, for submitting custom event data to user space. Must be preceded by a call to +```ringbuf_reserve()``` to reserve space for the data. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ringbuf_submit+path%3Aexamples&type=Code), + +### 9. ringbuf_discard() + +Syntax: ```void ringbuf_discard((void *)data, u64 flags)``` + +Return: Nothing, always succeeds + +Flags: + - ```BPF_RB_NO_WAKEUP```: Do not sent notification of new data availability + - ```BPF_RB_FORCE_WAKEUP```: Send notification of new data availability unconditionally + +A method of the BPF_RINGBUF_OUTPUT table, for discarding custom event data; userspace +ignores the data associated with the discarded event. Must be preceded by a call to +```ringbuf_reserve()``` to reserve space for the data. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ringbuf_submit+path%3Aexamples&type=Code), + +## Maps + +Maps are BPF data stores, and are the basis for higher level object types including tables, hashes, and histograms. + +### 1. BPF_TABLE + +Syntax: ```BPF_TABLE(_table_type, _key_type, _leaf_type, _name, _max_entries)``` + +Creates a map named ```_name```. Most of the time this will be used via higher-level macros, like BPF_HASH, BPF_ARRAY, BPF_HISTOGRAM, etc. + +`BPF_F_TABLE` is a variant that takes a flag in the last parameter. `BPF_TABLE(https://github.com/iovisor/bcc/tree/master.)` is actually a wrapper to `BPF_F_TABLE(https://github.com/iovisor/bcc/tree/master., 0 /* flag */)`. + +Methods (covered later): map.lookup(), map.lookup_or_try_init(), map.delete(), map.update(), map.insert(), map.increment(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_TABLE+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_TABLE+path%3Atools&type=Code) + +#### Pinned Maps + +Syntax: ```BPF_TABLE_PINNED(_table_type, _key_type, _leaf_type, _name, _max_entries, "/sys/fs/bpf/xyz")``` + +Create a new map if it doesn't exist and pin it to the bpffs as a FILE, otherwise use the map that was pinned to the bpffs. The type information is not enforced and the actual map type depends on the map that got pinned to the location. + +For example: + +```C +BPF_TABLE_PINNED("hash", u64, u64, ids, 1024, "/sys/fs/bpf/ids"); +``` + +### 2. BPF_HASH + +Syntax: ```BPF_HASH(name [, key_type [, leaf_type [, size]]])``` + +Creates a hash map (associative array) named ```name```, with optional parameters. + +Defaults: ```BPF_HASH(name, key_type=u64, leaf_type=u64, size=10240)``` + +For example: + +```C +BPF_HASH(start, struct request *); +``` + +This creates a hash named ```start``` where the key is a ```struct request *```, and the value defaults to u64. This hash is used by the disksnoop.py example for saving timestamps for each I/O request, where the key is the pointer to struct request, and the value is the timestamp. + +This is a wrapper macro for `BPF_TABLE("hash", ...)`. + +Methods (covered later): map.lookup(), map.lookup_or_try_init(), map.delete(), map.update(), map.insert(), map.increment(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_HASH+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_HASH+path%3Atools&type=Code) + +### 3. BPF_ARRAY + +Syntax: ```BPF_ARRAY(name [, leaf_type [, size]])``` + +Creates an int-indexed array which is optimized for fastest lookup and update, named ```name```, with optional parameters. + +Defaults: ```BPF_ARRAY(name, leaf_type=u64, size=10240)``` + +For example: + +```C +BPF_ARRAY(counts, u64, 32); +``` + +This creates an array named ```counts``` where with 32 buckets and 64-bit integer values. This array is used by the funccount.py example for saving call count of each function. + +This is a wrapper macro for `BPF_TABLE("array", ...)`. + +Methods (covered later): map.lookup(), map.update(), map.increment(). Note that all array elements are pre-allocated with zero values and can not be deleted. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_ARRAY+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_ARRAY+path%3Atools&type=Code) + +### 4. BPF_HISTOGRAM + +Syntax: ```BPF_HISTOGRAM(name [, key_type [, size ]])``` + +Creates a histogram map named ```name```, with optional parameters. + +Defaults: ```BPF_HISTOGRAM(name, key_type=int, size=64)``` + +For example: + +```C +BPF_HISTOGRAM(dist); +``` + +This creates a histogram named ```dist```, which defaults to 64 buckets indexed by keys of type int. + +This is a wrapper macro for `BPF_TABLE("histgram", ...)`. + +Methods (covered later): map.increment(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_HISTOGRAM+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_HISTOGRAM+path%3Atools&type=Code) + +### 5. BPF_STACK_TRACE + +Syntax: ```BPF_STACK_TRACE(name, max_entries)``` + +Creates stack trace map named ```name```, with a maximum entry count provided. These maps are used to store stack traces. + +For example: + +```C +BPF_STACK_TRACE(stack_traces, 1024); +``` + +This creates stack trace map named ```stack_traces```, with a maximum number of stack trace entries of 1024. + +This is a wrapper macro for `BPF_TABLE("stacktrace", ...)`. + +Methods (covered later): map.get_stackid(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_STACK_TRACE+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_STACK_TRACE+path%3Atools&type=Code) + +### 6. BPF_PERF_ARRAY + +Syntax: ```BPF_PERF_ARRAY(name, max_entries)``` + +Creates perf array named ```name```, with a maximum entry count provided, which must be equal to the number of system cpus. These maps are used to fetch hardware performance counters. + +For example: + +```C +text=""" +BPF_PERF_ARRAY(cpu_cycles, NUM_CPUS); +""" +b = bcc.BPF(text=text, cflags=["-DNUM_CPUS=%d" % multiprocessing.cpu_count()]) +b["cpu_cycles"].open_perf_event(b["cpu_cycles"].HW_CPU_CYCLES) +``` + +This creates a perf array named ```cpu_cycles```, with number of entries equal to the number of cpus/cores. The array is configured so that later calling map.perf_read() will return a hardware-calculated counter of the number of cycles elapsed from some point in the past. Only one type of hardware counter may be configured per table at a time. + +Methods (covered later): map.perf_read(). + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=BPF_PERF_ARRAY+path%3Atests&type=Code) + +### 7. BPF_PERCPU_HASH + +Syntax: ```BPF_PERCPU_HASH(name [, key_type [, leaf_type [, size]]])``` + +Creates NUM_CPU int-indexed hash maps (associative arrays) named ```name```, with optional parameters. Each CPU will have a separate copy of this array. The copies are not kept synchronized in any way. + +Note that due to limits defined in the kernel (in linux/mm/percpu.c), the ```leaf_type``` cannot have a size of more than 32KB. +In other words, ```BPF_PERCPU_HASH``` elements cannot be larger than 32KB in size. + + +Defaults: ```BPF_PERCPU_HASH(name, key_type=u64, leaf_type=u64, size=10240)``` + +For example: + +```C +BPF_PERCPU_HASH(start, struct request *); +``` + +This creates NUM_CPU hashes named ```start``` where the key is a ```struct request *```, and the value defaults to u64. + +This is a wrapper macro for `BPF_TABLE("percpu_hash", ...)`. + +Methods (covered later): map.lookup(), map.lookup_or_try_init(), map.delete(), map.update(), map.insert(), map.increment(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_PERCPU_HASH+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_PERCPU_HASH+path%3Atools&type=Code) + + +### 8. BPF_PERCPU_ARRAY + +Syntax: ```BPF_PERCPU_ARRAY(name [, leaf_type [, size]])``` + +Creates NUM_CPU int-indexed arrays which are optimized for fastest lookup and update, named ```name```, with optional parameters. Each CPU will have a separate copy of this array. The copies are not kept synchronized in any way. + +Note that due to limits defined in the kernel (in linux/mm/percpu.c), the ```leaf_type``` cannot have a size of more than 32KB. +In other words, ```BPF_PERCPU_ARRAY``` elements cannot be larger than 32KB in size. + + +Defaults: ```BPF_PERCPU_ARRAY(name, leaf_type=u64, size=10240)``` + +For example: + +```C +BPF_PERCPU_ARRAY(counts, u64, 32); +``` + +This creates NUM_CPU arrays named ```counts``` where with 32 buckets and 64-bit integer values. + +This is a wrapper macro for `BPF_TABLE("percpu_array", ...)`. + +Methods (covered later): map.lookup(), map.update(), map.increment(). Note that all array elements are pre-allocated with zero values and can not be deleted. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_PERCPU_ARRAY+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_PERCPU_ARRAY+path%3Atools&type=Code) + +### 9. BPF_LPM_TRIE + +Syntax: `BPF_LPM_TRIE(name [, key_type [, leaf_type [, size]]])` + +Creates a longest prefix match trie map named `name`, with optional parameters. + +Defaults: `BPF_LPM_TRIE(name, key_type=u64, leaf_type=u64, size=10240)` + +For example: + +```c +BPF_LPM_TRIE(trie, struct key_v6); +``` + +This creates an LPM trie map named `trie` where the key is a `struct key_v6`, and the value defaults to u64. + +This is a wrapper macro to `BPF_F_TABLE("lpm_trie", ..., BPF_F_NO_PREALLOC)`. + +Methods (covered later): map.lookup(), map.lookup_or_try_init(), map.delete(), map.update(), map.insert(), map.increment(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_LPM_TRIE+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF_LPM_TRIE+path%3Atools&type=Code) + +### 10. BPF_PROG_ARRAY + +Syntax: ```BPF_PROG_ARRAY(name, size)``` + +This creates a program array named ```name``` with ```size``` entries. Each entry of the array is either a file descriptor to a bpf program or ```NULL```. The array acts as a jump table so that bpf programs can "tail-call" other bpf programs. + +This is a wrapper macro for `BPF_TABLE("prog", ...)`. + +Methods (covered later): map.call(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_PROG_ARRAY+path%3Aexamples&type=Code), +[search /tests](https://github.com/iovisor/bcc/search?q=BPF_PROG_ARRAY+path%3Atests&type=Code), +[assign fd](https://github.com/iovisor/bcc/blob/master/examples/networking/tunnel_monitor/monitor.py#L24-L26) + +### 11. BPF_DEVMAP + +Syntax: ```BPF_DEVMAP(name, size)``` + +This creates a device map named ```name``` with ```size``` entries. Each entry of the map is an `ifindex` to a network interface. This map is only used in XDP. + +For example: +```C +BPF_DEVMAP(devmap, 10); +``` + +Methods (covered later): map.redirect_map(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_DEVMAP+path%3Aexamples&type=Code), + +### 12. BPF_CPUMAP + +Syntax: ```BPF_CPUMAP(name, size)``` + +This creates a cpu map named ```name``` with ```size``` entries. The index of the map represents the CPU id and each entry is the size of the ring buffer allocated for the CPU. This map is only used in XDP. + +For example: +```C +BPF_CPUMAP(cpumap, 16); +``` + +Methods (covered later): map.redirect_map(). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_CPUMAP+path%3Aexamples&type=Code), + +### 13. BPF_XSKMAP + +Syntax: ```BPF_XSKMAP(name, size [, "/sys/fs/bpf/xyz"])``` + +This creates a xsk map named ```name``` with ```size``` entries and pin it to the bpffs as a FILE. Each entry represents one NIC's queue id. This map is only used in XDP to redirect packet to an AF_XDP socket. If the AF_XDP socket is binded to a queue which is different than the current packet's queue id, the packet will be dropped. For kernel v5.3 and latter, `lookup` method is available and can be used to check whether and AF_XDP socket is available for the current packet's queue id. More details at [AF_XDP](https://www.kernel.org/doc/html/latest/networking/af_xdp.html). + +For example: +```C +BPF_XSKMAP(xsks_map, 8); +``` + +Methods (covered later): map.redirect_map(). map.lookup() + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF_XSKMAP+path%3Aexamples&type=Code), + +### 14. BPF_ARRAY_OF_MAPS + +Syntax: ```BPF_ARRAY_OF_MAPS(name, inner_map_name, size)``` + +This creates an array map with a map-in-map type (BPF_MAP_TYPE_HASH_OF_MAPS) map named ```name``` with ```size``` entries. The inner map meta data is provided by map ```inner_map_name``` and can be most of array or hash maps except ```BPF_MAP_TYPE_PROG_ARRAY```, ```BPF_MAP_TYPE_CGROUP_STORAGE``` and ```BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE```. + +For example: +```C +BPF_TABLE("hash", int, int, ex1, 1024); +BPF_TABLE("hash", int, int, ex2, 1024); +BPF_ARRAY_OF_MAPS(maps_array, "ex1", 10); +``` + +### 15. BPF_HASH_OF_MAPS + +Syntax: ```BPF_HASH_OF_MAPS(name, key_type, inner_map_name, size)``` + +This creates a hash map with a map-in-map type (BPF_MAP_TYPE_HASH_OF_MAPS) map named ```name``` with ```size``` entries. The inner map meta data is provided by map ```inner_map_name``` and can be most of array or hash maps except ```BPF_MAP_TYPE_PROG_ARRAY```, ```BPF_MAP_TYPE_CGROUP_STORAGE``` and ```BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE```. + +For example: +```C +BPF_ARRAY(ex1, int, 1024); +BPF_ARRAY(ex2, int, 1024); +BPF_HASH_OF_MAPS(maps_hash, struct custom_key, "ex1", 10); +``` + +### 16. BPF_STACK + +Syntax: ```BPF_STACK(name, leaf_type, max_entries[, flags])``` + +Creates a stack named ```name``` with value type ```leaf_type``` and max entries ```max_entries```. +Stack and Queue maps are only available from Linux 4.20+. + +For example: + +```C +BPF_STACK(stack, struct event, 10240); +``` + +This creates a stack named ```stack``` where the value type is ```struct event```, that holds up to 10240 entries. + +Methods (covered later): map.push(), map.pop(), map.peek(). + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=BPF_STACK+path%3Atests&type=Code), + +### 17. BPF_QUEUE + +Syntax: ```BPF_QUEUE(name, leaf_type, max_entries[, flags])``` + +Creates a queue named ```name``` with value type ```leaf_type``` and max entries ```max_entries```. +Stack and Queue maps are only available from Linux 4.20+. + +For example: + +```C +BPF_QUEUE(queue, struct event, 10240); +``` + +This creates a queue named ```queue``` where the value type is ```struct event```, that holds up to 10240 entries. + +Methods (covered later): map.push(), map.pop(), map.peek(). + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=BPF_QUEUE+path%3Atests&type=Code), + +### 18. BPF_SOCKHASH + +Syntax: ```BPF_SOCKHASH(name[, key_type [, max_entries)``` + +Creates a hash named ```name```, with optional parameters. sockhash is only available from Linux 4.18+. + +Default: ```BPF_SOCKHASH(name, key_type=u32, max_entries=10240)``` + +For example: + +```C +struct sock_key { + u32 remote_ip4; + u32 local_ip4; + u32 remote_port; + u32 local_port; +}; +BPF_HASH(skh, struct sock_key, 65535); +``` + +This creates a hash named ```skh``` where the key is a ```struct sock_key```. + +A sockhash is a BPF map type that holds references to sock structs. Then with a new sk/msg redirect bpf helper BPF programs can use the map to redirect skbs/msgs between sockets (```map.sk_redirect_hash()/map.msg_redirect_hash()```). + +The difference between ```BPF_SOCKHASH``` and ```BPF_SOCKMAP``` is that ```BPF_SOCKMAP``` is implemented based on an array, and enforces keys to be four bytes. While ```BPF_SOCKHASH``` is implemented based on hash table, and the type of key can be specified freely. + +Methods (covered later): map.sock_hash_update(), map.msg_redirect_hash(), map.sk_redirect_hash(). + +[search /tests](https://github.com/iovisor/bcc/search?q=BPF_SOCKHASH+path%3Atests&type=Code) + +### 19. map.lookup() + +Syntax: ```*val map.lookup(&key)``` + +Lookup the key in the map, and return a pointer to its value if it exists, else NULL. We pass the key in as an address to a pointer. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=lookup+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=lookup+path%3Atools&type=Code) + +### 20. map.lookup_or_try_init() + +Syntax: ```*val map.lookup_or_try_init(&key, &zero)``` + +Lookup the key in the map, and return a pointer to its value if it exists, else initialize the key's value to the second argument. This is often used to initialize values to zero. If the key cannot be inserted (e.g. the map is full) then NULL is returned. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=lookup_or_try_init+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=lookup_or_try_init+path%3Atools&type=Code) + +Note: The old map.lookup_or_init() may cause return from the function, so lookup_or_try_init() is recommended as it +does not have this side effect. + +### 21. map.delete() + +Syntax: ```map.delete(&key)``` + +Delete the key from the hash. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=delete+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=delete+path%3Atools&type=Code) + +### 22. map.update() + +Syntax: ```map.update(&key, &val)``` + +Associate the value in the second argument to the key, overwriting any previous value. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=update+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=update+path%3Atools&type=Code) + +### 23. map.insert() + +Syntax: ```map.insert(&key, &val)``` + +Associate the value in the second argument to the key, only if there was no previous value. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=insert+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=insert+path%3Atools&type=Code) + +### 24. map.increment() + +Syntax: ```map.increment(key[, increment_amount])``` + +Increments the key's value by `increment_amount`, which defaults to 1. Used for histograms. + +```map.increment()``` are not atomic. In the concurrency case. If you want more accurate results, use ```map.atomic_increment()``` instead of ```map.increment()```. The overhead of ```map.increment()``` and ```map.atomic_increment()``` is similar. + +Note. When using ```map.atomic_increment()``` to operate on a BPF map of type ```BPF_MAP_TYPE_HASH```, ```map.atomic_increment()``` does not guarantee the atomicity of the operation when the specified key does not exist. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=increment+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=increment+path%3Atools&type=Code) + +### 25. map.get_stackid() + +Syntax: ```int map.get_stackid(void *ctx, u64 flags)``` + +This walks the stack found via the struct pt_regs in ```ctx```, saves it in the stack trace map, and returns a unique ID for the stack trace. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=get_stackid+path%3Aexamples&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=get_stackid+path%3Atools&type=Code) + +### 26. map.perf_read() + +Syntax: ```u64 map.perf_read(u32 cpu)``` + +This returns the hardware performance counter as configured in [5. BPF_PERF_ARRAY](#5-bpf_perf_array) + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=perf_read+path%3Atests&type=Code) + +### 27. map.call() + +Syntax: ```void map.call(void *ctx, int index)``` + +This invokes ```bpf_tail_call()``` to tail-call the bpf program which the ```index``` entry in [BPF_PROG_ARRAY](#10-bpf_prog_array) points to. A tail-call is different from the normal call. It reuses the current stack frame after jumping to another bpf program and never goes back. If the ```index``` entry is empty, it won't jump anywhere and the program execution continues as normal. + +For example: + +```C +BPF_PROG_ARRAY(prog_array, 10); + +int tail_call(void *ctx) { + bpf_trace_printk("Tail-call\n"); + return 0; +} + +int do_tail_call(void *ctx) { + bpf_trace_printk("Original program\n"); + prog_array.call(ctx, 2); + return 0; +} +``` + +```Python +b = BPF(src_file="example.c") +tail_fn = b.load_func("tail_call", BPF.KPROBE) +prog_array = b.get_table("prog_array") +prog_array[c_int(2)] = c_int(tail_fn.fd) +b.attach_kprobe(event="some_kprobe_event", fn_name="do_tail_call") +``` + +This assigns ```tail_call()``` to ```prog_array[2]```. In the end of ```do_tail_call()```, ```prog_array.call(ctx, 2)``` tail-calls ```tail_call()``` and executes it. + +**NOTE:** To prevent infinite loop, the maximum number of tail-calls is 32 ([```MAX_TAIL_CALL_CNT```](https://github.com/torvalds/linux/search?l=C&q=MAX_TAIL_CALL_CNT+path%3Ainclude%2Flinux&type=Code)). + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?l=C&q=call+path%3Aexamples&type=Code), +[search /tests](https://github.com/iovisor/bcc/search?l=C&q=call+path%3Atests&type=Code) + +### 28. map.redirect_map() + +Syntax: ```int map.redirect_map(int index, int flags)``` + +This redirects the incoming packets based on the ```index``` entry. If the map is [BPF_DEVMAP](#11-bpf_devmap), the packet will be sent to the transmit queue of the network interface that the entry points to. If the map is [BPF_CPUMAP](#12-bpf_cpumap), the packet will be sent to the ring buffer of the ```index``` CPU and be processed by the CPU later. If the map is [BPF_XSKMAP](#13-bpf_xskmap), the packet will be sent to the AF_XDP socket attached to the queue. + +If the packet is redirected successfully, the function will return XDP_REDIRECT. Otherwise, it will return XDP_ABORTED to discard the packet. + +For example: +```C +BPF_DEVMAP(devmap, 1); + +int redirect_example(struct xdp_md *ctx) { + return devmap.redirect_map(0, 0); +} +int xdp_dummy(struct xdp_md *ctx) { + return XDP_PASS; +} +``` + +```Python +ip = pyroute2.IPRoute() +idx = ip.link_lookup(ifname="eth1")[0] + +b = bcc.BPF(src_file="example.c") + +devmap = b.get_table("devmap") +devmap[c_uint32(0)] = c_int(idx) + +in_fn = b.load_func("redirect_example", BPF.XDP) +out_fn = b.load_func("xdp_dummy", BPF.XDP) +b.attach_xdp("eth0", in_fn, 0) +b.attach_xdp("eth1", out_fn, 0) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?l=C&q=redirect_map+path%3Aexamples&type=Code), + +### 29. map.push() + +Syntax: ```int map.push(&val, int flags)``` + +Push an element onto a Stack or Queue table. +Passing BPF_EXIST as a flag causes the Queue or Stack to discard the oldest element if it is full. +Returns 0 on success, negative error on failure. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=push+path%3Atests&type=Code), + +### 30. map.pop() + +Syntax: ```int map.pop(&val)``` + +Pop an element from a Stack or Queue table. ```*val``` is populated with the result. +Unlike peeking, popping removes the element. +Returns 0 on success, negative error on failure. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=pop+path%3Atests&type=Code), + +### 31. map.peek() + +Syntax: ```int map.peek(&val)``` + +Peek an element at the head of a Stack or Queue table. ```*val``` is populated with the result. +Unlike popping, peeking does not remove the element. +Returns 0 on success, negative error on failure. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=peek+path%3Atests&type=Code), + +### 32. map.sock_hash_update() + +Syntax: ```int map.sock_hash_update(struct bpf_sock_ops *skops, &key, int flags)``` + +Add an entry to, or update a sockhash map referencing sockets. The skops is used as a new value for the entry associated to key. flags is one of: + +``` +BPF_NOEXIST: The entry for key must not exist in the map. +BPF_EXIST: The entry for key must already exist in the map. +BPF_ANY: No condition on the existence of the entry for key. +``` + +If the map has eBPF programs (parser and verdict), those will be inherited by the socket being added. If the socket is already attached to eBPF programs, this results in an error. + +Return 0 on success, or a negative error in case of failure. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=sock_hash_update+path%3Atests&type=Code), + +### 33. map.msg_redirect_hash() + +Syntax: ```int map.msg_redirect_hash(struct sk_msg_buff *msg, void *key, u64 flags)``` + +This helper is used in programs implementing policies at the socket level. If the message msg is allowed to pass (i.e. if the verdict eBPF program returns SK_PASS), redirect it to the socket referenced by map (of type BPF_MAP_TYPE_SOCKHASH) using hash key. Both ingress and egress interfaces can be used for redirection. The BPF_F_INGRESS value in flags is used to make the distinction (ingress path is selected if the flag is present, egress path otherwise). This is the only flag supported for now. + +Return SK_PASS on success, or SK_DROP on error. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=msg_redirect_hash+path%3Atests&type=Code), + +### 34. map.sk_redirect_hash() + +Syntax: ```int map.sk_redirect_hash(struct sk_buff *skb, void *key, u64 flags)``` + +This helper is used in programs implementing policies at the skb socket level. If the sk_buff skb is allowed to pass (i.e. if the verdict eBPF program returns SK_PASS), redirect it to the socket referenced by map (of type BPF_MAP_TYPE_SOCKHASH) using hash key. Both ingress and egress interfaces can be used for redirection. The BPF_F_INGRESS value in flags is used to make the distinction (ingress path is selected if the flag is present, egress otherwise). This is the only flag supported for now. + +Return SK_PASS on success, or SK_DROP on error. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=sk_redirect_hash+path%3Atests&type=Code), + +## Licensing + +Depending on which [BPF helpers](kernel-versions.md#helpers) are used, a GPL-compatible license is required. + +The special BCC macro `BPF_LICENSE` specifies the license of the BPF program. You can set the license as a comment in your source code, but the kernel has a special interface to specify it programmatically. If you need to use GPL-only helpers, it is recommended to specify the macro in your C code so that the kernel can understand it: + +```C +// SPDX-License-Identifier: GPL-2.0+ +#define BPF_LICENSE GPL +``` + +Otherwise, the kernel may reject loading your program (see the [error description](#2-cannot-call-gpl-only-function-from-proprietary-program) below). Note that it supports multiple words and quotes are not necessary: + +```C +// SPDX-License-Identifier: GPL-2.0+ OR BSD-2-Clause +#define BPF_LICENSE Dual BSD/GPL +``` + +Check the [BPF helpers reference](kernel-versions.md#helpers) to see which helpers are GPL-only and what the kernel understands as GPL-compatible. + +**If the macro is not specified, BCC will automatically define the license of the program as GPL.** + +## Rewriter + +One of jobs for rewriter is to turn implicit memory accesses to explicit ones using kernel helpers. Recent kernel introduced a config option ARCH_HAS_NON_OVERLAPPING_ADDRESS_SPACE which will be set for architectures who user address space and kernel address are disjoint. x86 and arm has this config option set while s390 does not. If ARCH_HAS_NON_OVERLAPPING_ADDRESS_SPACE is not set, the bpf old helper `bpf_probe_read()` will not be available. Some existing users may have implicit memory accesses to access user memory, so using `bpf_probe_read_kernel()` will cause their application to fail. Therefore, for non-s390, the rewriter will use `bpf_probe_read()` for these implicit memory accesses. For s390, `bpf_probe_read_kernel()` is used as default and users should use `bpf_probe_read_user()` explicitly when accessing user memories. + +# bcc Python + +## Initialization + +Constructors. + +### 1. BPF + +Syntax: ```BPF({text=BPF_program | src_file=filename} [, usdt_contexts=[USDT_object, ...]] [, cflags=[arg1, ...]] [, debug=int])``` + +Creates a BPF object. This is the main object for defining a BPF program, and interacting with its output. + +Exactly one of `text` or `src_file` must be supplied (not both). + +The `cflags` specifies additional arguments to be passed to the compiler, for example `-DMACRO_NAME=value` or `-I/include/path`. The arguments are passed as an array, with each element being an additional argument. Note that strings are not split on whitespace, so each argument must be a different element of the array, e.g. `["-include", "header.h"]`. + +The `debug` flags control debug output, and can be or'ed together: +- `DEBUG_LLVM_IR = 0x1` compiled LLVM IR +- `DEBUG_BPF = 0x2` loaded BPF bytecode and register state on branches +- `DEBUG_PREPROCESSOR = 0x4` pre-processor result +- `DEBUG_SOURCE = 0x8` ASM instructions embedded with source +- `DEBUG_BPF_REGISTER_STATE = 0x10` register state on all instructions in addition to DEBUG_BPF +- `DEBUG_BTF = 0x20` print the messages from the `libbpf` library. + +Examples: + +```Python +# define entire BPF program in one line: +BPF(text='int do_trace(void *ctx) { bpf_trace_printk("hit!\\n"); return 0; }'); + +# define program as a variable: +prog = """ +int hello(void *ctx) { + bpf_trace_printk("Hello, World!\\n"); + return 0; +} +""" +b = BPF(text=prog) + +# source a file: +b = BPF(src_file = "vfsreadlat.c") + +# include a USDT object: +u = USDT(pid=int(pid)) +[...] +b = BPF(text=bpf_text, usdt_contexts=[u]) + +# add include paths: +u = BPF(text=prog, cflags=["-I/path/to/include"]) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=BPF+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=BPF+path%3Atools+language%3Apython&type=Code) + +### 2. USDT + +Syntax: ```USDT({pid=pid | path=path})``` + +Creates an object to instrument User Statically-Defined Tracing (USDT) probes. Its primary method is ```enable_probe()```. + +Arguments: + +- pid: attach to this process ID. +- path: instrument USDT probes from this binary path. + +Examples: + +```Python +# include a USDT object: +u = USDT(pid=int(pid)) +[...] +b = BPF(text=bpf_text, usdt_contexts=[u]) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=USDT+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=USDT+path%3Atools+language%3Apython&type=Code) + +## Events + +### 1. attach_kprobe() + +Syntax: ```BPF.attach_kprobe(event="event", fn_name="name")``` + +Instruments the kernel function ```event()``` using kernel dynamic tracing of the function entry, and attaches our C defined function ```name()``` to be called when the kernel function is called. + +For example: + +```Python +b.attach_kprobe(event="sys_clone", fn_name="do_trace") +``` + +This will instrument the kernel ```sys_clone()``` function, which will then run our BPF defined ```do_trace()``` function each time it is called. + +You can call attach_kprobe() more than once, and attach your BPF function to multiple kernel functions. +You can also call attach_kprobe() more than once to attach multiple BPF functions to the same kernel function. + +See the previous kprobes section for how to instrument arguments from BPF. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=attach_kprobe+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=attach_kprobe+path%3Atools+language%3Apython&type=Code) + +### 2. attach_kretprobe() + +Syntax: ```BPF.attach_kretprobe(event="event", fn_name="name" [, maxactive=int])``` + +Instruments the return of the kernel function ```event()``` using kernel dynamic tracing of the function return, and attaches our C defined function ```name()``` to be called when the kernel function returns. + +For example: + +```Python +b.attach_kretprobe(event="vfs_read", fn_name="do_return") +``` + +This will instrument the kernel ```vfs_read()``` function, which will then run our BPF defined ```do_return()``` function each time it is called. + +You can call attach_kretprobe() more than once, and attach your BPF function to multiple kernel function returns. +You can also call attach_kretprobe() more than once to attach multiple BPF functions to the same kernel function return. + +When a kretprobe is installed on a kernel function, there is a limit on how many parallel calls it can catch. You can change that limit with ```maxactive```. See the kprobes documentation for its default value. + +See the previous kretprobes section for how to instrument the return value from BPF. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=attach_kretprobe+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=attach_kretprobe+path%3Atools+language%3Apython&type=Code) + +### 3. attach_tracepoint() + +Syntax: ```BPF.attach_tracepoint(tp="tracepoint", fn_name="name")``` + +Instruments the kernel tracepoint described by ```tracepoint```, and when hit, runs the BPF function ```name()```. + +This is an explicit way to instrument tracepoints. The ```TRACEPOINT_PROBE``` syntax, covered in the earlier tracepoints section, is an alternate method with the advantage of auto-declaring an ```args``` struct containing the tracepoint arguments. With ```attach_tracepoint()```, the tracepoint arguments need to be declared in the BPF program. + +For example: + +```Python +# define BPF program +bpf_text = """ +#include + +struct urandom_read_args { + // from /sys/kernel/debug/tracing/events/random/urandom_read/format + u64 __unused__; + u32 got_bits; + u32 pool_left; + u32 input_left; +}; + +int printarg(struct urandom_read_args *args) { + bpf_trace_printk("%d\\n", args->got_bits); + return 0; +}; +""" + +# load BPF program +b = BPF(text=bpf_text) +b.attach_tracepoint("random:urandom_read", "printarg") +``` + +Notice how the first argument to ```printarg()``` is now our defined struct. + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/a4159da8c4ea8a05a3c6e402451f530d6e5a8b41/examples/tracing/urandomread-explicit.py#L41), +[search /examples](https://github.com/iovisor/bcc/search?q=attach_tracepoint+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=attach_tracepoint+path%3Atools+language%3Apython&type=Code) + +### 4. attach_uprobe() + +Syntax: ```BPF.attach_uprobe(name="location", sym="symbol", fn_name="name" [, sym_off=int])```, ```BPF.attach_uprobe(name="location", sym_re="regex", fn_name="name")```, ```BPF.attach_uprobe(name="location", addr=int, fn_name="name")``` + + +Instruments the user-level function ```symbol()``` from either the library or binary named by ```location``` using user-level dynamic tracing of the function entry, and attach our C defined function ```name()``` to be called whenever the user-level function is called. If ```sym_off``` is given, the function is attached to the offset within the symbol. + +The real address ```addr``` may be supplied in place of ```sym```, in which case ```sym``` must be set to its default value. If the file is a non-PIE executable, ```addr``` must be a virtual address, otherwise it must be an offset relative to the file load address. + +Instead of a symbol name, a regular expression can be provided in ```sym_re```. The uprobe will then attach to symbols that match the provided regular expression. + +Libraries can be given in the name argument without the lib prefix, or with the full path (/usr/lib/...). Binaries can be given only with the full path (/bin/sh). + +For example: + +```Python +b.attach_uprobe(name="c", sym="strlen", fn_name="count") +``` + +This will instrument ```strlen()``` function from libc, and call our BPF function ```count()``` when it is called. Note how the "lib" in "libc" is not necessary to specify. + +Other examples: + +```Python +b.attach_uprobe(name="c", sym="getaddrinfo", fn_name="do_entry") +b.attach_uprobe(name="/usr/bin/python", sym="main", fn_name="do_main") +``` + +You can call attach_uprobe() more than once, and attach your BPF function to multiple user-level functions. + +See the previous uprobes section for how to instrument arguments from BPF. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=attach_uprobe+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=attach_uprobe+path%3Atools+language%3Apython&type=Code) + +### 5. attach_uretprobe() + +Syntax: ```BPF.attach_uretprobe(name="location", sym="symbol", fn_name="name")``` + +Instruments the return of the user-level function ```symbol()``` from either the library or binary named by ```location``` using user-level dynamic tracing of the function return, and attach our C defined function ```name()``` to be called whenever the user-level function returns. + +For example: + +```Python +b.attach_uretprobe(name="c", sym="strlen", fn_name="count") +``` + +This will instrument ```strlen()``` function from libc, and call our BPF function ```count()``` when it returns. + +Other examples: + +```Python +b.attach_uretprobe(name="c", sym="getaddrinfo", fn_name="do_return") +b.attach_uretprobe(name="/usr/bin/python", sym="main", fn_name="do_main") +``` + +You can call attach_uretprobe() more than once, and attach your BPF function to multiple user-level functions. + +See the previous uretprobes section for how to instrument the return value from BPF. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=attach_uretprobe+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=attach_uretprobe+path%3Atools+language%3Apython&type=Code) + +### 6. USDT.enable_probe() + +Syntax: ```USDT.enable_probe(probe=probe, fn_name=name)``` + +Attaches a BPF C function ```name``` to the USDT probe ```probe```. + +Example: + +```Python +# enable USDT probe from given PID +u = USDT(pid=int(pid)) +u.enable_probe(probe="http__server__request", fn_name="do_trace") +``` + +To check if your binary has USDT probes, and what they are, you can run ```readelf -n binary``` and check the stap debug section. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=enable_probe+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=enable_probe+path%3Atools+language%3Apython&type=Code) + +### 7. attach_raw_tracepoint() + +Syntax: ```BPF.attach_raw_tracepoint(tp="tracepoint", fn_name="name")``` + +Instruments the kernel raw tracepoint described by ```tracepoint``` (```event``` only, no ```category```), and when hit, runs the BPF function ```name()```. + +This is an explicit way to instrument tracepoints. The ```RAW_TRACEPOINT_PROBE``` syntax, covered in the earlier raw tracepoints section, is an alternate method. + +For example: + +```Python +b.attach_raw_tracepoint("sched_switch", "do_trace") +``` + +Examples in situ: +[search /tools](https://github.com/iovisor/bcc/search?q=attach_raw_tracepoint+path%3Atools+language%3Apython&type=Code) + +### 8. attach_raw_socket() + +Syntax: ```BPF.attach_raw_socket(fn, dev)``` + +Attaches a BPF function to the specified network interface. + +The ```fn``` must be the type of ```BPF.function``` and the bpf_prog type needs to be ```BPF_PROG_TYPE_SOCKET_FILTER``` (```fn=BPF.load_func(func_name, BPF.SOCKET_FILTER)```) + +```fn.sock``` is a non-blocking raw socket that was created and bound to ```dev```. + +All network packets processed by ```dev``` are copied to the ```recv-q``` of ```fn.sock``` after being processed by bpf_prog. Try to recv packet form ```fn.sock``` with rev/recvfrom/recvmsg. Note that if the ```recv-q``` is not read in time after the ```recv-q``` is full, the copied packets will be discarded. + +We can use this feature to capture network packets just like ```tcpdump```. + +We can use ```ss --bpf --packet -p``` to observe ```fn.sock```. + +Example: + +```Python +BPF.attach_raw_socket(bpf_func, ifname) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=attach_raw_socket+path%3Aexamples+language%3Apython&type=Code) +### 9. attach_xdp() +Syntax: ```BPF.attach_xdp(dev="device", fn=b.load_func("fn_name",BPF.XDP), flags)``` + +Instruments the network driver described by ```dev``` , and then receives the packet, run the BPF function ```fn_name()``` with flags. + +Here is a list of optional flags. + +```Python +# from xdp_flags uapi/linux/if_link.h +XDP_FLAGS_UPDATE_IF_NOEXIST = (1 << 0) +XDP_FLAGS_SKB_MODE = (1 << 1) +XDP_FLAGS_DRV_MODE = (1 << 2) +XDP_FLAGS_HW_MODE = (1 << 3) +XDP_FLAGS_REPLACE = (1 << 4) +``` + +You can use flags like this ```BPF.attach_xdp(dev="device", fn=b.load_func("fn_name",BPF.XDP), flags=BPF.XDP_FLAGS_UPDATE_IF_NOEXIST)``` + +The default value of flags is 0. This means if there is no xdp program with `device`, the fn will run with that device. If there is an xdp program running with device, the old program will be replaced with new fn program. + +Currently, bcc does not support XDP_FLAGS_REPLACE flag. The following are the descriptions of other flags. + +#### 1. XDP_FLAGS_UPDATE_IF_NOEXIST +If an XDP program is already attached to the specified driver, attaching the XDP program again will fail. + +#### 2. XDP_FLAGS_SKB_MODE +Driver doesn’t have support for XDP, but the kernel fakes it. +XDP program works, but there’s no real performance benefit because packets are handed to kernel stack anyways which then emulates XDP – this is usually supported with generic network drivers used in home computers, laptops, and virtualized HW. + +#### 3. XDP_FLAGS_DRV_MODE +A driver has XDP support and can hand then to XDP without kernel stack interaction – Few drivers can support it and those are usually for enterprise HW. + +#### 4. XDP_FLAGS_HW_MODE +XDP can be loaded and executed directly on the NIC – just a handful of NICs can do that. + + +For example: + +```Python +b.attach_xdp(dev="ens1", fn=b.load_func("do_xdp", BPF.XDP)) +``` + +This will instrument the network device ```ens1``` , which will then run our BPF defined ```do_xdp()``` function each time it receives packets. + +Don't forget to call ```b.remove_xdp("ens1")``` at the end! + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=attach_xdp+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=attach_xdp+path%3Atools+language%3Apython&type=Code) + +### 10. attach_func() + +Syntax: ```BPF.attach_func(fn, attachable_fd, attach_type [, flags])``` + +Attaches a BPF function of the specified type to a particular ```attachable_fd```. if the ```attach_type``` is ```BPF_FLOW_DISSECTOR```, the function is expected to attach to current net namespace and ```attachable_fd``` must be 0. + +For example: + +```Python +b.attach_func(fn, cgroup_fd, BPFAttachType.CGROUP_SOCK_OPS) +b.attach_func(fn, map_fd, BPFAttachType.SK_MSG_VERDICT) +``` + +Note. When attached to "global" hooks (xdp, tc, lwt, cgroup). If the "BPF function" is no longer needed after the program terminates, be sure to call `detach_func` when the program exits. + +Examples in situ: + +[search /examples](https://github.com/iovisor/bcc/search?q=attach_func+path%3Aexamples+language%3Apython&type=Code), + +### 11. detach_func() + +Syntax: ```BPF.detach_func(fn, attachable_fd, attach_type)``` + +Detaches a BPF function of the specified type. + +For example: + +```Python +b.detach_func(fn, cgroup_fd, BPFAttachType.CGROUP_SOCK_OPS) +b.detach_func(fn, map_fd, BPFAttachType.SK_MSG_VERDICT) +``` + +Examples in situ: + +[search /examples](https://github.com/iovisor/bcc/search?q=detach_func+path%3Aexamples+language%3Apython&type=Code), + +### 12. detach_kprobe() + +Syntax: ```BPF.detach_kprobe(event="event", fn_name="name")``` + +Detach a kprobe handler function of the specified event. + +For example: + +```Python +b.detach_kprobe(event="__page_cache_alloc", fn_name="trace_func_entry") +``` + +### 13. detach_kretprobe() + +Syntax: ```BPF.detach_kretprobe(event="event", fn_name="name")``` + +Detach a kretprobe handler function of the specified event. + +For example: + +```Python +b.detach_kretprobe(event="__page_cache_alloc", fn_name="trace_func_return") +``` + +## Debug Output + +### 1. trace_print() + +Syntax: ```BPF.trace_print(fmt="fields")``` + +This method continually reads the globally shared /sys/kernel/debug/tracing/trace_pipe file and prints its contents. This file can be written to via BPF and the bpf_trace_printk() function, however, that method has limitations, including a lack of concurrent tracing support. The BPF_PERF_OUTPUT mechanism, covered earlier, is preferred. + +Arguments: + +- ```fmt```: optional, and can contain a field formatting string. It defaults to ```None```. + +Examples: + +```Python +# print trace_pipe output as-is: +b.trace_print() + +# print PID and message: +b.trace_print(fmt="{1} {5}") +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=trace_print+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=trace_print+path%3Atools+language%3Apython&type=Code) + +### 2. trace_fields() + +Syntax: ```BPF.trace_fields(nonblocking=False)``` + +This method reads one line from the globally shared /sys/kernel/debug/tracing/trace_pipe file and returns it as fields. This file can be written to via BPF and the bpf_trace_printk() function, however, that method has limitations, including a lack of concurrent tracing support. The BPF_PERF_OUTPUT mechanism, covered earlier, is preferred. + +Arguments: + +- ```nonblocking```: optional, defaults to ```False```. When set to ```True```, the program will not block waiting for input. + +Examples: + +```Python +while 1: + try: + (task, pid, cpu, flags, ts, msg) = b.trace_fields() + except ValueError: + continue + [...] +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=trace_fields+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=trace_fields+path%3Atools+language%3Apython&type=Code) + +## Output APIs + +Normal output from a BPF program is either: + +- per-event: using PERF_EVENT_OUTPUT, open_perf_buffer(), and perf_buffer_poll(). +- map summary: using items(), or print_log2_hist(), covered in the Maps section. + +### 1. perf_buffer_poll() + +Syntax: ```BPF.perf_buffer_poll(timeout=T)``` + +This polls from all open perf ring buffers, calling the callback function that was provided when calling open_perf_buffer for each entry. + +The timeout parameter is optional and measured in milliseconds. In its absence, polling continues indefinitely. + +Example: + +```Python +# loop with callback to print_event +b["events"].open_perf_buffer(print_event) +while 1: + try: + b.perf_buffer_poll() + except KeyboardInterrupt: + exit(); +``` + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/v0.9.0/examples/tracing/hello_perf_output.py#L55), +[search /examples](https://github.com/iovisor/bcc/search?q=perf_buffer_poll+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=perf_buffer_poll+path%3Atools+language%3Apython&type=Code) + +### 2. ring_buffer_poll() + +Syntax: ```BPF.ring_buffer_poll(timeout=T)``` + +This polls from all open ringbuf ring buffers, calling the callback function that was provided when calling open_ring_buffer for each entry. + +The timeout parameter is optional and measured in milliseconds. In its absence, polling continues until +there is no more data or the callback returns a negative value. + +Example: + +```Python +# loop with callback to print_event +b["events"].open_ring_buffer(print_event) +while 1: + try: + b.ring_buffer_poll(30) + except KeyboardInterrupt: + exit(); +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ring_buffer_poll+path%3Aexamples+language%3Apython&type=Code), + +### 3. ring_buffer_consume() + +Syntax: ```BPF.ring_buffer_consume()``` + +This consumes from all open ringbuf ring buffers, calling the callback function that was provided when calling open_ring_buffer for each entry. + +Unlike ```ring_buffer_poll```, this method **does not poll for data** before attempting to consume. +This reduces latency at the expense of higher CPU consumption. If you are unsure which to use, +use ```ring_buffer_poll```. + +Example: + +```Python +# loop with callback to print_event +b["events"].open_ring_buffer(print_event) +while 1: + try: + b.ring_buffer_consume() + except KeyboardInterrupt: + exit(); +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ring_buffer_consume+path%3Aexamples+language%3Apython&type=Code), + +## Map APIs + +Maps are BPF data stores, and are used in bcc to implement a table, and then higher level objects on top of tables, including hashes and histograms. + +### 1. get_table() + +Syntax: ```BPF.get_table(name)``` + +Returns a table object. This is no longer used, as tables can now be read as items from BPF. Eg: ```BPF[name]```. + +Examples: + +```Python +counts = b.get_table("counts") + +counts = b["counts"] +``` + +These are equivalent. + +### 2. open_perf_buffer() + +Syntax: ```table.open_perf_buffers(callback, page_cnt=N, lost_cb=None)``` + +This operates on a table as defined in BPF as BPF_PERF_OUTPUT(), and associates the callback Python function ```callback``` to be called when data is available in the perf ring buffer. This is part of the recommended mechanism for transferring per-event data from kernel to user space. The size of the perf ring buffer can be specified via the ```page_cnt``` parameter, which must be a power of two number of pages and defaults to 8. If the callback is not processing data fast enough, some submitted data may be lost. ```lost_cb``` will be called to log / monitor the lost count. If ```lost_cb``` is the default ```None``` value, it will just print a line of message to ```stderr```. + +Example: + +```Python +# process event +def print_event(cpu, data, size): + event = ct.cast(data, ct.POINTER(Data)).contents + [...] + +# loop with callback to print_event +b["events"].open_perf_buffer(print_event) +while 1: + try: + b.perf_buffer_poll() + except KeyboardInterrupt: + exit() +``` + +Note that the data structure transferred will need to be declared in C in the BPF program. For example: + +```C +// define output data structure in C +struct data_t { + u32 pid; + u64 ts; + char comm[TASK_COMM_LEN]; +}; +BPF_PERF_OUTPUT(events); +[...] +``` + +In Python, you can either let bcc generate the data structure from C declaration automatically (recommended): + +```Python +def print_event(cpu, data, size): + event = b["events"].event(data) +[...] +``` + +or define it manually: + +```Python +# define output data structure in Python +TASK_COMM_LEN = 16 # linux/sched.h +class Data(ct.Structure): + _fields_ = [("pid", ct.c_ulonglong), + ("ts", ct.c_ulonglong), + ("comm", ct.c_char * TASK_COMM_LEN)] + +def print_event(cpu, data, size): + event = ct.cast(data, ct.POINTER(Data)).contents +[...] +``` + +Examples in situ: +[code](https://github.com/iovisor/bcc/blob/v0.9.0/examples/tracing/hello_perf_output.py#L52), +[search /examples](https://github.com/iovisor/bcc/search?q=open_perf_buffer+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=open_perf_buffer+path%3Atools+language%3Apython&type=Code) + +### 3. items() + +Syntax: ```table.items()``` + +Returns an array of the keys in a table. This can be used with BPF_HASH maps to fetch, and iterate, over the keys. + +Example: + +```Python +# print output +print("%10s %s" % ("COUNT", "STRING")) +counts = b.get_table("counts") +for k, v in sorted(counts.items(), key=lambda counts: counts[1].value): + print("%10d \"%s\"" % (v.value, k.c.encode('string-escape'))) +``` + +This example also uses the ```sorted()``` method to sort by value. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=items+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=items+path%3Atools+language%3Apython&type=Code) + +### 4. values() + +Syntax: ```table.values()``` + +Returns an array of the values in a table. + +### 5. clear() + +Syntax: ```table.clear()``` + +Clears the table: deletes all entries. + +Example: + +```Python +# print map summary every second: +while True: + time.sleep(1) + print("%-8s\n" % time.strftime("%H:%M:%S"), end="") + dist.print_log2_hist(sym + " return:") + dist.clear() +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=clear+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=clear+path%3Atools+language%3Apython&type=Code) + +### 6. items_lookup_and_delete_batch() + +Syntax: ```table.items_lookup_and_delete_batch()``` + +Returns an array of the keys in a table with a single call to BPF syscall. This can be used with BPF_HASH maps to fetch, and iterate, over the keys. It also clears the table: deletes all entries. +You should rather use table.items_lookup_and_delete_batch() than table.items() followed by table.clear(). It requires kernel v5.6. + +Example: + +```Python +# print call rate per second: +print("%9s-%9s-%8s-%9s" % ("PID", "COMM", "fname", "counter")) +while True: + for k, v in sorted(b['map'].items_lookup_and_delete_batch(), key=lambda kv: (kv[0]).pid): + print("%9s-%9s-%8s-%9d" % (k.pid, k.comm, k.fname, v.counter)) + sleep(1) +``` + +### 7. items_lookup_batch() + +Syntax: ```table.items_lookup_batch()``` + +Returns an array of the keys in a table with a single call to BPF syscall. This can be used with BPF_HASH maps to fetch, and iterate, over the keys. +You should rather use table.items_lookup_batch() than table.items(). It requires kernel v5.6. + +Example: + +```Python +# print current value of map: +print("%9s-%9s-%8s-%9s" % ("PID", "COMM", "fname", "counter")) +while True: + for k, v in sorted(b['map'].items_lookup_batch(), key=lambda kv: (kv[0]).pid): + print("%9s-%9s-%8s-%9d" % (k.pid, k.comm, k.fname, v.counter)) +``` + +### 8. items_delete_batch() + +Syntax: ```table.items_delete_batch(keys)``` + +It clears all entries of a BPF_HASH map when keys is None. It is more efficient than table.clear() since it generates only one system call. You can delete a subset of a map by giving an array of keys as parameter. Those keys and their associated values will be deleted. It requires kernel v5.6. + +Arguments: + +- keys is optional and by default is None. + + + +### 9. items_update_batch() + +Syntax: ```table.items_update_batch(keys, values)``` + +Update all the provided keys with new values. The two arguments must be the same length and within the map limits (between 1 and the maximum entries). It requires kernel v5.6. + +Arguments: + +- keys is the list of keys to be updated +- values is the list containing the new values. + + +### 10. print_log2_hist() + +Syntax: ```table.print_log2_hist(val_type="value", section_header="Bucket ptr", section_print_fn=None)``` + +Prints a table as a log2 histogram in ASCII. The table must be stored as log2, which can be done using the BPF function ```bpf_log2l()```. + +Arguments: + +- val_type: optional, column header. +- section_header: if the histogram has a secondary key, multiple tables will print and section_header can be used as a header description for each. +- section_print_fn: if section_print_fn is not None, it will be passed the bucket value. + +Example: + +```Python +b = BPF(text=""" +BPF_HISTOGRAM(dist); + +int kprobe__blk_account_io_done(struct pt_regs *ctx, struct request *req) +{ + dist.increment(bpf_log2l(req->__data_len / 1024)); + return 0; +} +""") +[...] + +b["dist"].print_log2_hist("kbytes") +``` + +Output: + +``` + kbytes : count distribution + 0 -> 1 : 3 | | + 2 -> 3 : 0 | | + 4 -> 7 : 211 |********** | + 8 -> 15 : 0 | | + 16 -> 31 : 0 | | + 32 -> 63 : 0 | | + 64 -> 127 : 1 | | + 128 -> 255 : 800 |**************************************| +``` + +This output shows a multi-modal distribution, with the largest mode of 128->255 kbytes and a count of 800. + +This is an efficient way to summarize data, as the summarization is performed in-kernel, and only the count column is passed to user space. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=print_log2_hist+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=print_log2_hist+path%3Atools+language%3Apython&type=Code) + +### 11. print_linear_hist() + +Syntax: ```table.print_linear_hist(val_type="value", section_header="Bucket ptr", section_print_fn=None)``` + +Prints a table as a linear histogram in ASCII. This is intended to visualize small integer ranges, eg, 0 to 100. + +Arguments: + +- val_type: optional, column header. +- section_header: if the histogram has a secondary key, multiple tables will print and section_header can be used as a header description for each. +- section_print_fn: if section_print_fn is not None, it will be passed the bucket value. + +Example: + +```Python +b = BPF(text=""" +BPF_HISTOGRAM(dist); + +int kprobe__blk_account_io_done(struct pt_regs *ctx, struct request *req) +{ + dist.increment(req->__data_len / 1024); + return 0; +} +""") +[...] + +b["dist"].print_linear_hist("kbytes") +``` + +Output: + +``` + kbytes : count distribution + 0 : 3 |****** | + 1 : 0 | | + 2 : 0 | | + 3 : 0 | | + 4 : 19 |****************************************| + 5 : 0 | | + 6 : 0 | | + 7 : 0 | | + 8 : 4 |******** | + 9 : 0 | | + 10 : 0 | | + 11 : 0 | | + 12 : 0 | | + 13 : 0 | | + 14 : 0 | | + 15 : 0 | | + 16 : 2 |**** | +[...] +``` + +This is an efficient way to summarize data, as the summarization is performed in-kernel, and only the values in the count column are passed to user space. + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=print_linear_hist+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=print_linear_hist+path%3Atools+language%3Apython&type=Code) + +### 12. open_ring_buffer() + +Syntax: ```table.open_ring_buffer(callback, ctx=None)``` + +This operates on a table as defined in BPF as BPF_RINGBUF_OUTPUT(), and associates the callback Python function ```callback``` to be called when data is available in the ringbuf ring buffer. This is part of the new (Linux 5.8+) recommended mechanism for transferring per-event data from kernel to user space. Unlike perf buffers, ringbuf sizes are specified within the BPF program, as part of the ```BPF_RINGBUF_OUTPUT``` macro. If the callback is not processing data fast enough, some submitted data may be lost. In this case, the events should be polled more frequently and/or the size of the ring buffer should be increased. + +Example: + +```Python +# process event +def print_event(ctx, data, size): + event = ct.cast(data, ct.POINTER(Data)).contents + [...] + +# loop with callback to print_event +b["events"].open_ring_buffer(print_event) +while 1: + try: + b.ring_buffer_poll() + except KeyboardInterrupt: + exit() +``` + +Note that the data structure transferred will need to be declared in C in the BPF program. For example: + +```C +// define output data structure in C +struct data_t { + u32 pid; + u64 ts; + char comm[TASK_COMM_LEN]; +}; +BPF_RINGBUF_OUTPUT(events, 8); +[...] +``` + +In Python, you can either let bcc generate the data structure from C declaration automatically (recommended): + +```Python +def print_event(ctx, data, size): + event = b["events"].event(data) +[...] +``` + +or define it manually: + +```Python +# define output data structure in Python +TASK_COMM_LEN = 16 # linux/sched.h +class Data(ct.Structure): + _fields_ = [("pid", ct.c_ulonglong), + ("ts", ct.c_ulonglong), + ("comm", ct.c_char * TASK_COMM_LEN)] + +def print_event(ctx, data, size): + event = ct.cast(data, ct.POINTER(Data)).contents +[...] +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=open_ring_buffer+path%3Aexamples+language%3Apython&type=Code), + +### 13. push() + +Syntax: ```table.push(leaf, flags=0)``` + +Push an element onto a Stack or Queue table. Raises an exception if the operation does not succeed. +Passing QueueStack.BPF_EXIST as a flag causes the Queue or Stack to discard the oldest element if it is full. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=push+path%3Atests+language%3Apython&type=Code), + +### 14. pop() + +Syntax: ```leaf = table.pop()``` + +Pop an element from a Stack or Queue table. Unlike ```peek()```, ```pop()``` +removes the element from the table before returning it. +Raises a KeyError exception if the operation does not succeed. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=pop+path%3Atests+language%3Apython&type=Code), + +### 15. peek() + +Syntax: ```leaf = table.peek()``` + +Peek the element at the head of a Stack or Queue table. Unlike ```pop()```, ```peek()``` +does not remove the element from the table. Raises an exception if the operation does not succeed. + +Examples in situ: +[search /tests](https://github.com/iovisor/bcc/search?q=peek+path%3Atests+language%3Apython&type=Code), + +## Helpers + +Some helper methods provided by bcc. Note that since we're in Python, we can import any Python library and their methods, including, for example, the libraries: argparse, collections, ctypes, datetime, re, socket, struct, subprocess, sys, and time. + +### 1. ksym() + +Syntax: ```BPF.ksym(addr)``` + +Translate a kernel memory address into a kernel function name, which is returned. + +Example: + +```Python +print("kernel function: " + b.ksym(addr)) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ksym+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=ksym+path%3Atools+language%3Apython&type=Code) + +### 2. ksymname() + +Syntax: ```BPF.ksymname(name)``` + +Translate a kernel name into an address. This is the reverse of ksym. Returns -1 when the function name is unknown. + +Example: + +```Python +print("kernel address: %x" % b.ksymname("vfs_read")) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=ksymname+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=ksymname+path%3Atools+language%3Apython&type=Code) + +### 3. sym() + +Syntax: ```BPF.sym(addr, pid, show_module=False, show_offset=False)``` + +Translate a memory address into a function name for a pid, which is returned. A pid of less than zero will access the kernel symbol cache. The `show_module` and `show_offset` parameters control whether the module in which the symbol lies should be displayed, and whether the instruction offset from the beginning of the symbol should be displayed. These extra parameters default to `False`. + +Example: + +```Python +print("function: " + b.sym(addr, pid)) +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=sym+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=sym+path%3Atools+language%3Apython&type=Code) + +### 4. num_open_kprobes() + +Syntax: ```BPF.num_open_kprobes()``` + +Returns the number of open k[ret]probes. Can be useful for scenarios where event_re is used while attaching and detaching probes. Excludes perf_events readers. + +Example: + +```Python +b.attach_kprobe(event_re=pattern, fn_name="trace_count") +matched = b.num_open_kprobes() +if matched == 0: + print("0 functions matched by \"%s\". Exiting." % args.pattern) + exit() +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=num_open_kprobes+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=num_open_kprobes+path%3Atools+language%3Apython&type=Code) + +### 5. get_syscall_fnname() + +Syntax: ```BPF.get_syscall_fnname(name : str)``` + +Return the corresponding kernel function name of the syscall. This helper function will try different prefixes and use the right one to concatenate with the syscall name. Note that the return value may vary in different versions of linux kernel and sometimes it will causing trouble. (see [#2590](https://github.com/iovisor/bcc/issues/2590)) + +Example: + +```Python +print("The function name of %s in kernel is %s" % ("clone", b.get_syscall_fnname("clone"))) +# sys_clone or __x64_sys_clone or ... +``` + +Examples in situ: +[search /examples](https://github.com/iovisor/bcc/search?q=get_syscall_fnname+path%3Aexamples+language%3Apython&type=Code), +[search /tools](https://github.com/iovisor/bcc/search?q=get_syscall_fnname+path%3Atools+language%3Apython&type=Code) + +# BPF Errors + +See the "Understanding eBPF verifier messages" section in the kernel source under Documentation/networking/filter.txt. + +## 1. Invalid mem access + +This can be due to trying to read memory directly, instead of operating on memory on the BPF stack. All kernel memory reads must be passed via bpf_probe_read_kernel() to copy kernel memory into the BPF stack, which can be automatic by the bcc rewriter in some cases of simple dereferencing. bpf_probe_read_kernel() does all the required checks. + +Example: + +``` +bpf: Permission denied +0: (bf) r6 = r1 +1: (79) r7 = *(u64 *)(r6 +80) +2: (85) call 14 +3: (bf) r8 = r0 +[...] +23: (69) r1 = *(u16 *)(r7 +16) +R7 invalid mem access 'inv' + +Traceback (most recent call last): + File "./tcpaccept", line 179, in + b = BPF(text=bpf_text) + File "/usr/lib/python2.7/dist-packages/bcc/__init__.py", line 172, in __init__ + self._trace_autoload() + File "/usr/lib/python2.7/dist-packages/bcc/__init__.py", line 612, in _trace_autoload + fn = self.load_func(func_name, BPF.KPROBE) + File "/usr/lib/python2.7/dist-packages/bcc/__init__.py", line 212, in load_func + raise Exception("Failed to load BPF program %s" % func_name) +Exception: Failed to load BPF program kretprobe__inet_csk_accept +``` + +## 2. Cannot call GPL only function from proprietary program + +This error happens when a GPL-only helper is called from a non-GPL BPF program. To fix this error, do not use GPL-only helpers from a proprietary BPF program, or relicense the BPF program under a GPL-compatible license. Check which [BPF helpers](https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md#helpers) are GPL-only, and what licenses are considered GPL-compatible. + +Example calling `bpf_get_stackid()`, a GPL-only BPF helper, from a proprietary program (`#define BPF_LICENSE Proprietary`): + +``` +bpf: Failed to load program: Invalid argument +[...] +8: (85) call bpf_get_stackid#27 +cannot call GPL only function from proprietary program +``` + +# Environment Variables + +## 1. Kernel source directory + +eBPF program compilation needs kernel sources or kernel headers with headers +compiled. In case your kernel sources are at a non-standard location where BCC +cannot find then, its possible to provide BCC the absolute path of the location +by setting `BCC_KERNEL_SOURCE` to it. + +## 2. Kernel version overriding + +By default, BCC stores the `LINUX_VERSION_CODE` in the generated eBPF object +which is then passed along to the kernel when the eBPF program is loaded. +Sometimes this is quite inconvenient especially when the kernel is slightly +updated such as an LTS kernel release. Its extremely unlikely the slight +mismatch would cause any issues with the loaded eBPF program. By setting +`BCC_LINUX_VERSION_CODE` to the version of the kernel that's running, the check +for verifying the kernel version can be bypassed. This is needed for programs +that use kprobes. This needs to be encoded in the format: `(VERSION * 65536) + +(PATCHLEVEL * 256) + SUBLEVEL`. For example, if the running kernel is `4.9.10`, +then can set `export BCC_LINUX_VERSION_CODE=264458` to override the kernel +version check successfully. diff --git a/bcc-documents/special_filtering.md b/bcc-documents/special_filtering.md new file mode 100644 index 0000000..9b15260 --- /dev/null +++ b/bcc-documents/special_filtering.md @@ -0,0 +1,125 @@ +# Special Filtering + +Some tools have special filtering capabitilies, the main use case is to trace +processes running in containers, but those mechanisms are generic and could +be used in other cases as well. + +## Filtering by cgroups + +Some tools have an option to filter by cgroup by referencing a pinned BPF hash +map managed externally. + +Examples of commands: + +``` +# ./opensnoop --cgroupmap /sys/fs/bpf/test01 +# ./execsnoop --cgroupmap /sys/fs/bpf/test01 +# ./tcpconnect --cgroupmap /sys/fs/bpf/test01 +# ./tcpaccept --cgroupmap /sys/fs/bpf/test01 +# ./tcptracer --cgroupmap /sys/fs/bpf/test01 +``` + +The commands above will only display results from processes that belong to one +of the cgroups whose id, returned by `bpf_get_current_cgroup_id()`, is in the +pinned BPF hash map. + +The BPF hash map can be created by: + +``` +# bpftool map create /sys/fs/bpf/test01 type hash key 8 value 8 entries 128 \ + name cgroupset flags 0 +``` + +To get a shell in a new cgroup, you can use: + +``` +# systemd-run --pty --unit test bash +``` + +The shell will be running in the cgroup +`/sys/fs/cgroup/unified/system.slice/test.service`. + +The cgroup id can be discovered using the `name_to_handle_at()` system call. In +the examples/cgroupid, you will find an example of program to get the cgroup +id. + +``` +# cd examples/cgroupid +# make +# ./cgroupid hex /sys/fs/cgroup/unified/system.slice/test.service +``` + +or, using Docker: + +``` +# cd examples/cgroupid +# docker build -t cgroupid . +# docker run --rm --privileged -v /sys/fs/cgroup:/sys/fs/cgroup \ + cgroupid cgroupid hex /sys/fs/cgroup/unified/system.slice/test.service +``` + +This prints the cgroup id as a hexadecimal string in the host endianness such +as `77 16 00 00 01 00 00 00`. + +``` +# FILE=/sys/fs/bpf/test01 +# CGROUPID_HEX="77 16 00 00 01 00 00 00" +# bpftool map update pinned $FILE key hex $CGROUPID_HEX value hex 00 00 00 00 00 00 00 00 any +``` + +Now that the shell started by systemd-run has its cgroup id in the BPF hash +map, bcc tools will display results from this shell. Cgroups can be added and +removed from the BPF hash map without restarting the bcc tool. + +This feature is useful for integrating bcc tools in external projects. + +## Filtering by mount by namespace + +The BPF hash map can be created by: + +``` +# bpftool map create /sys/fs/bpf/mnt_ns_set type hash key 8 value 4 entries 128 \ + name mnt_ns_set flags 0 +``` + +Execute the `execsnoop` tool filtering only the mount namespaces +in `/sys/fs/bpf/mnt_ns_set`: + +``` +# tools/execsnoop.py --mntnsmap /sys/fs/bpf/mnt_ns_set +``` + +Start a terminal in a new mount namespace: + +``` +# unshare -m bash +``` + +Update the hash map with the mount namespace ID of the terminal above: + +``` +FILE=/sys/fs/bpf/mnt_ns_set +if [ $(printf '\1' | od -dAn) -eq 1 ]; then + HOST_ENDIAN_CMD=tac +else + HOST_ENDIAN_CMD=cat +fi + +NS_ID_HEX="$(printf '%016x' $(stat -Lc '%i' /proc/self/ns/mnt) | sed 's/.\{2\}/&\n/g' | $HOST_ENDIAN_CMD)" +bpftool map update pinned $FILE key hex $NS_ID_HEX value hex 00 00 00 00 any +``` + +Execute a command in this terminal: + +``` +# ping kinvolk.io +``` + +You'll see how on the `execsnoop` terminal you started above the call is logged: + +``` +# tools/execsnoop.py --mntnsmap /sys/fs/bpf/mnt_ns_set +[sudo] password for mvb: +PCOMM PID PPID RET ARGS +ping 8096 7970 0 /bin/ping kinvolk.io +``` diff --git a/bcc-documents/tutorial.md b/bcc-documents/tutorial.md new file mode 100644 index 0000000..4a6766a --- /dev/null +++ b/bcc-documents/tutorial.md @@ -0,0 +1,422 @@ +# bcc Tutorial + +This tutorial covers how to use [bcc](https://github.com/iovisor/bcc) tools to quickly solve performance, troubleshooting, and networking issues. If you want to develop new bcc tools, see [tutorial_bcc_python_developer.md](tutorial_bcc_python_developer.md) for that tutorial. + +It is assumed for this tutorial that bcc is already installed, and you can run tools like execsnoop successfully. See [INSTALL.md](https://github.com/iovisor/bcc/tree/master/INSTALL.md). This uses enhancements added to the Linux 4.x series. + +## Observability + +Some quick wins. + +### 0. Before bcc + +Before using bcc, you should start with the Linux basics. One reference is the [Linux Performance Analysis in 60,000 Milliseconds](https://netflixtechblog.com/linux-performance-analysis-in-60-000-milliseconds-accc10403c55) post, which covers these commands: + +1. uptime +1. dmesg | tail +1. vmstat 1 +1. mpstat -P ALL 1 +1. pidstat 1 +1. iostat -xz 1 +1. free -m +1. sar -n DEV 1 +1. sar -n TCP,ETCP 1 +1. top + +### 1. General Performance + +Here is a generic checklist for performance investigations with bcc, first as a list, then in detail: + +1. execsnoop +1. opensnoop +1. ext4slower (or btrfs\*, xfs\*, zfs\*) +1. biolatency +1. biosnoop +1. cachestat +1. tcpconnect +1. tcpaccept +1. tcpretrans +1. runqlat +1. profile + +These tools may be installed on your system under /usr/share/bcc/tools, or you can run them from the bcc github repo under /tools where they have a .py extension. Browse the 50+ tools available for more analysis options. + +#### 1.1 execsnoop + +``` +# ./execsnoop +PCOMM PID RET ARGS +supervise 9660 0 ./run +supervise 9661 0 ./run +mkdir 9662 0 /bin/mkdir -p ./main +run 9663 0 ./run +[...] +``` + +execsnoop prints one line of output for each new process. Check for short-lived processes. These can consume CPU resources, but not show up in most monitoring tools that periodically take snapshots of which processes are running. + +It works by tracing exec(), not the fork(), so it will catch many types of new processes but not all (eg, it won't see an application launching working processes, that doesn't exec() anything else). + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/execsnoop_example.txt). + +#### 1.2. opensnoop + +``` +# ./opensnoop +PID COMM FD ERR PATH +1565 redis-server 5 0 /proc/1565/stat +1565 redis-server 5 0 /proc/1565/stat +1565 redis-server 5 0 /proc/1565/stat +1603 snmpd 9 0 /proc/net/dev +1603 snmpd 11 0 /proc/net/if_inet6 +1603 snmpd -1 2 /sys/class/net/eth0/device/vendor +1603 snmpd 11 0 /proc/sys/net/ipv4/neigh/eth0/retrans_time_ms +1603 snmpd 11 0 /proc/sys/net/ipv6/neigh/eth0/retrans_time_ms +1603 snmpd 11 0 /proc/sys/net/ipv6/conf/eth0/forwarding +[...] +``` + +opensnoop prints one line of output for each open() syscall, including details. + +Files that are opened can tell you a lot about how applications work: identifying their data files, config files, and log files. Sometimes applications can misbehave, and perform poorly, when they are constantly attempting to read files that do not exist. opensnoop gives you a quick look. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/opensnoop_example.txt). + +#### 1.3. ext4slower (or btrfs\*, xfs\*, zfs\*) + +``` +# ./ext4slower +Tracing ext4 operations slower than 10 ms +TIME COMM PID T BYTES OFF_KB LAT(ms) FILENAME +06:35:01 cron 16464 R 1249 0 16.05 common-auth +06:35:01 cron 16463 R 1249 0 16.04 common-auth +06:35:01 cron 16465 R 1249 0 16.03 common-auth +06:35:01 cron 16465 R 4096 0 10.62 login.defs +06:35:01 cron 16464 R 4096 0 10.61 login.defs +``` + +ext4slower traces the ext4 file system and times common operations, and then only prints those that exceed a threshold. + +This is great for identifying or exonerating one type of performance issue: show individually slow disk i/O via the file system. Disks process I/O asynchronously, and it can be difficult to associate latency at that layer with the latency applications experience. Tracing higher up in the kernel stack, at the VFS -> file system interface, will more closely match what an application suffers. Use this tool to identify if file system latency exceeds a given threshold. + +Similar tools exist in bcc for other file systems: btrfsslower, xfsslower, and zfsslower. There is also fileslower, which works at the VFS layer and traces everything (although at some higher overhead). + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/ext4slower_example.txt). + +#### 1.4. biolatency + +``` +# ./biolatency +Tracing block device I/O... Hit Ctrl-C to end. +^C + usecs : count distribution + 0 -> 1 : 0 | | + 2 -> 3 : 0 | | + 4 -> 7 : 0 | | + 8 -> 15 : 0 | | + 16 -> 31 : 0 | | + 32 -> 63 : 0 | | + 64 -> 127 : 1 | | + 128 -> 255 : 12 |******** | + 256 -> 511 : 15 |********** | + 512 -> 1023 : 43 |******************************* | + 1024 -> 2047 : 52 |**************************************| + 2048 -> 4095 : 47 |********************************** | + 4096 -> 8191 : 52 |**************************************| + 8192 -> 16383 : 36 |************************** | + 16384 -> 32767 : 15 |********** | + 32768 -> 65535 : 2 |* | + 65536 -> 131071 : 2 |* | +``` + +biolatency traces disk I/O latency (time from device issue to completion), and when the tool ends (Ctrl-C, or a given interval), it prints a histogram summary of the latency. + +This is great for understanding disk I/O latency beyond the average times given by tools like iostat. I/O latency outliers will be visible at the end of the distribution, as well as multi-mode distributions. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/biolatency_example.txt). + +#### 1.5. biosnoop + +``` +# ./biosnoop +TIME(s) COMM PID DISK T SECTOR BYTES LAT(ms) +0.000004001 supervise 1950 xvda1 W 13092560 4096 0.74 +0.000178002 supervise 1950 xvda1 W 13092432 4096 0.61 +0.001469001 supervise 1956 xvda1 W 13092440 4096 1.24 +0.001588002 supervise 1956 xvda1 W 13115128 4096 1.09 +1.022346001 supervise 1950 xvda1 W 13115272 4096 0.98 +1.022568002 supervise 1950 xvda1 W 13188496 4096 0.93 +[...] +``` + +biosnoop prints a line of output for each disk I/O, with details including latency (time from device issue to completion). + +This allows you to examine disk I/O in more detail, and look for time-ordered patterns (eg, reads queueing behind writes). Note that the output will be verbose if your system performs disk I/O at a high rate. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/biosnoop_example.txt). + +#### 1.6. cachestat + +``` +# ./cachestat + HITS MISSES DIRTIES READ_HIT% WRITE_HIT% BUFFERS_MB CACHED_MB + 1074 44 13 94.9% 2.9% 1 223 + 2195 170 8 92.5% 6.8% 1 143 + 182 53 56 53.6% 1.3% 1 143 + 62480 40960 20480 40.6% 19.8% 1 223 + 7 2 5 22.2% 22.2% 1 223 + 348 0 0 100.0% 0.0% 1 223 +[...] +``` + +cachestat prints a one line summary every second (or every custom interval) showing statistics from the file system cache. + +Use this to identify a low cache hit ratio, and a high rate of misses: which gives one lead for performance tuning. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/cachestat_example.txt). + +#### 1.7. tcpconnect + +``` +# ./tcpconnect +PID COMM IP SADDR DADDR DPORT +1479 telnet 4 127.0.0.1 127.0.0.1 23 +1469 curl 4 10.201.219.236 54.245.105.25 80 +1469 curl 4 10.201.219.236 54.67.101.145 80 +1991 telnet 6 ::1 ::1 23 +2015 ssh 6 fe80::2000:bff:fe82:3ac fe80::2000:bff:fe82:3ac 22 +[...] +``` + +tcpconnect prints one line of output for every active TCP connection (eg, via connect()), with details including source and destination addresses. + +Look for unexpected connections that may point to inefficiencies in application configuration, or an intruder. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/tcpconnect_example.txt). + +#### 1.8. tcpaccept + +``` +# ./tcpaccept +PID COMM IP RADDR LADDR LPORT +907 sshd 4 192.168.56.1 192.168.56.102 22 +907 sshd 4 127.0.0.1 127.0.0.1 22 +5389 perl 6 1234:ab12:2040:5020:2299:0:5:0 1234:ab12:2040:5020:2299:0:5:0 7001 +[...] +``` + +tcpaccept prints one line of output for every passive TCP connection (eg, via accept()), with details including source and destination addresses. + +Look for unexpected connections that may point to inefficiencies in application configuration, or an intruder. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/tcpaccept_example.txt). + +#### 1.9. tcpretrans + +``` +# ./tcpretrans +TIME PID IP LADDR:LPORT T> RADDR:RPORT STATE +01:55:05 0 4 10.153.223.157:22 R> 69.53.245.40:34619 ESTABLISHED +01:55:05 0 4 10.153.223.157:22 R> 69.53.245.40:34619 ESTABLISHED +01:55:17 0 4 10.153.223.157:22 R> 69.53.245.40:22957 ESTABLISHED +[...] +``` + +tcprerans prints one line of output for every TCP retransmit packet, with details including source and destination addresses, and kernel state of the TCP connection. + +TCP retransmissions cause latency and throughput issues. For ESTABLISHED retransmits, look for patterns with networks. For SYN_SENT, this may point to target kernel CPU saturation and kernel packet drops. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/tcpretrans_example.txt). + +#### 1.10. runqlat + +``` +# ./runqlat +Tracing run queue latency... Hit Ctrl-C to end. +^C + usecs : count distribution + 0 -> 1 : 233 |*********** | + 2 -> 3 : 742 |************************************ | + 4 -> 7 : 203 |********** | + 8 -> 15 : 173 |******** | + 16 -> 31 : 24 |* | + 32 -> 63 : 0 | | + 64 -> 127 : 30 |* | + 128 -> 255 : 6 | | + 256 -> 511 : 3 | | + 512 -> 1023 : 5 | | + 1024 -> 2047 : 27 |* | + 2048 -> 4095 : 30 |* | + 4096 -> 8191 : 20 | | + 8192 -> 16383 : 29 |* | + 16384 -> 32767 : 809 |****************************************| + 32768 -> 65535 : 64 |*** | +``` + +runqlat times how long threads were waiting on the CPU run queues, and prints this as a histogram. + +This can help quantify time lost waiting for a turn on CPU, during periods of CPU saturation. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/runqlat_example.txt). + +#### 1.11. profile + +``` +# ./profile +Sampling at 49 Hertz of all threads by user + kernel stack... Hit Ctrl-C to end. +^C + 00007f31d76c3251 [unknown] + 47a2c1e752bf47f7 [unknown] + - sign-file (8877) + 1 + + ffffffff813d0af8 __clear_user + ffffffff813d5277 iov_iter_zero + ffffffff814ec5f2 read_iter_zero + ffffffff8120be9d __vfs_read + ffffffff8120c385 vfs_read + ffffffff8120d786 sys_read + ffffffff817cc076 entry_SYSCALL_64_fastpath + 00007fc5652ad9b0 read + - dd (25036) + 4 + + 0000000000400542 func_a + 0000000000400598 main + 00007f12a133e830 __libc_start_main + 083e258d4c544155 [unknown] + - func_ab (13549) + 5 + +[...] + + ffffffff8105eb66 native_safe_halt + ffffffff8103659e default_idle + ffffffff81036d1f arch_cpu_idle + ffffffff810bba5a default_idle_call + ffffffff810bbd07 cpu_startup_entry + ffffffff8104df55 start_secondary + - swapper/1 (0) + 75 +``` + +profile is a CPU profiler, which takes samples of stack traces at timed intervals, and prints a summary of unique stack traces and a count of their occurrence. + +Use this tool to understand the code paths that are consuming CPU resources. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/profile_example.txt). + +### 2. Observability with Generic Tools + +In addition to the above tools for performance tuning, below is a checklist for bcc generic tools, first as a list, and in detail: + +1. trace +1. argdist +1. funccount + +These generic tools may be useful to provide visibility to solve your specific problems. + +#### 2.1. trace + +##### Example 1 + +Suppose you want to track file ownership change. There are three syscalls, `chown`, `fchown` and `lchown` which users can use to change file ownership. The corresponding syscall entry is `SyS_[f|l]chown`. The following command can be used to print out syscall parameters and the calling process user id. You can use `id` command to find the uid of a particular user. + +``` +$ trace.py \ + 'p::SyS_chown "file = %s, to_uid = %d, to_gid = %d, from_uid = %d", arg1, arg2, arg3, $uid' \ + 'p::SyS_fchown "fd = %d, to_uid = %d, to_gid = %d, from_uid = %d", arg1, arg2, arg3, $uid' \ + 'p::SyS_lchown "file = %s, to_uid = %d, to_gid = %d, from_uid = %d", arg1, arg2, arg3, $uid' +PID TID COMM FUNC - +1269255 1269255 python3.6 SyS_lchown file = /tmp/dotsync-usisgezu/tmp, to_uid = 128203, to_gid = 100, from_uid = 128203 +1269441 1269441 zstd SyS_chown file = /tmp/dotsync-vic7ygj0/dotsync-package.zst, to_uid = 128203, to_gid = 100, from_uid = 128203 +1269255 1269255 python3.6 SyS_lchown file = /tmp/dotsync-a40zd7ev/tmp, to_uid = 128203, to_gid = 100, from_uid = 128203 +1269442 1269442 zstd SyS_chown file = /tmp/dotsync-gzp413o_/dotsync-package.zst, to_uid = 128203, to_gid = 100, from_uid = 128203 +1269255 1269255 python3.6 SyS_lchown file = /tmp/dotsync-whx4fivm/tmp/.bash_profile, to_uid = 128203, to_gid = 100, from_uid = 128203 +``` + +##### Example 2 + +Suppose you want to count nonvoluntary context switches (`nvcsw`) in your bpf based performance monitoring tools and you do not know what is the proper method. `/proc//status` already tells you the number (`nonvoluntary_ctxt_switches`) for a pid and you can use `trace.py` to do a quick experiment to verify your method. With kernel source code, the `nvcsw` is counted at file `linux/kernel/sched/core.c` function `__schedule` and under condition +``` +!(!preempt && prev->state) // i.e., preempt || !prev->state +``` + +The `__schedule` function is marked as `notrace`, and the best place to evaluate the above condition seems in `sched/sched_switch` tracepoint called inside function `__schedule` and defined in `linux/include/trace/events/sched.h`. `trace.py` already has `args` being the pointer to the tracepoint `TP_STRUCT__entry`. The above condition in function `__schedule` can be represented as +``` +args->prev_state == TASK_STATE_MAX || args->prev_state == 0 +``` + +The below command can be used to count the involuntary context switches (per process or per pid) and compare to `/proc//status` or `/proc//task//status` for correctness, as in typical cases, involuntary context switches are not very common. +``` +$ trace.py -p 1134138 't:sched:sched_switch (args->prev_state == TASK_STATE_MAX || args->prev_state == 0)' +PID TID COMM FUNC +1134138 1134140 contention_test sched_switch +1134138 1134142 contention_test sched_switch +... +$ trace.py -L 1134140 't:sched:sched_switch (args->prev_state == TASK_STATE_MAX || args->prev_state == 0)' +PID TID COMM FUNC +1134138 1134140 contention_test sched_switch +1134138 1134140 contention_test sched_switch +... +``` + +##### Example 3 + +This example is related to issue [1231](https://github.com/iovisor/bcc/issues/1231) and [1516](https://github.com/iovisor/bcc/issues/1516) where uprobe does not work at all in certain cases. First, you can do a `strace` as below + +``` +$ strace trace.py 'r:bash:readline "%s", retval' +... +perf_event_open(0x7ffd968212f0, -1, 0, -1, 0x8 /* PERF_FLAG_??? */) = -1 EIO (Input/output error) +... +``` + +The `perf_event_open` syscall returns `-EIO`. Digging into kernel uprobe related codes in `/kernel/trace` and `/kernel/events` directories to search `EIO`, the function `uprobe_register` is the most suspicious. Let us find whether this function is called or not and what is the return value if it is called. In one terminal using the following command to print out the return value of uprobe_register, +``` +$ trace.py 'r::uprobe_register "ret = %d", retval' +``` +In another terminal run the same bash uretprobe tracing example, and you should get +``` +$ trace.py 'r::uprobe_register "ret = %d", retval' +PID TID COMM FUNC - +1041401 1041401 python2.7 uprobe_register ret = -5 +``` + +The `-5` error code is EIO. This confirms that the following code in function `uprobe_register` is the most suspicious culprit. +``` + if (!inode->i_mapping->a_ops->readpage && !shmem_mapping(inode->i_mapping)) + return -EIO; +``` +The `shmem_mapping` function is defined as +``` +bool shmem_mapping(struct address_space *mapping) +{ + return mapping->a_ops == &shmem_aops; +} +``` + +To confirm the theory, find what is `inode->i_mapping->a_ops` with the following command +``` +$ trace.py -I 'linux/fs.h' 'p::uprobe_register(struct inode *inode) "a_ops = %llx", inode->i_mapping->a_ops' +PID TID COMM FUNC - +814288 814288 python2.7 uprobe_register a_ops = ffffffff81a2adc0 +^C$ grep ffffffff81a2adc0 /proc/kallsyms +ffffffff81a2adc0 R empty_aops +``` + +The kernel symbol `empty_aops` does not have `readpage` defined and hence the above suspicious condition is true. Further examining the kernel source code shows that `overlayfs` does not provide its own `a_ops` while some other file systems (e.g., ext4) define their own `a_ops` (e.g., `ext4_da_aops`), and `ext4_da_aops` defines `readpage`. Hence, uprobe works fine on ext4 while not on overlayfs. + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/trace_example.txt). + +#### 2.2. argdist + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/argdist_example.txt). + +#### 2.3. funccount + +More [examples](https://github.com/iovisor/bcc/tree/master/tools/funccount_example.txt). + +## Networking + +To do. diff --git a/bcc-documents/tutorial_bcc_python_developer.md b/bcc-documents/tutorial_bcc_python_developer.md new file mode 100644 index 0000000..c56864e --- /dev/null +++ b/bcc-documents/tutorial_bcc_python_developer.md @@ -0,0 +1,724 @@ +# bcc Python Developer Tutorial + +This tutorial is about developing [bcc](https://github.com/iovisor/bcc) tools and programs using the Python interface. There are two parts: observability then networking. Snippets are taken from various programs in bcc: see their files for licences. + +Also see the bcc developer's [reference_guide.md](reference_guide.md), and a tutorial for end-users of tools: [tutorial.md](tutorial.md). There is also a lua interface for bcc. + +## Observability + +This observability tutorial contains 17 lessons, and 46 enumerated things to learn. + +### Lesson 1. Hello World + +Start by running [examples/hello_world.py](https://github.com/iovisor/bcc/tree/master/examples/hello_world.py), while running some commands (eg, "ls") in another session. It should print "Hello, World!" for new processes. If not, start by fixing bcc: see [INSTALL.md](https://github.com/iovisor/bcc/tree/master/INSTALL.md). + +``` +# ./examples/hello_world.py + bash-13364 [002] d... 24573433.052937: : Hello, World! + bash-13364 [003] d... 24573436.642808: : Hello, World! +[...] +``` + +Here's the code for hello_world.py: + +```Python +from bcc import BPF +BPF(text='int kprobe__sys_clone(void *ctx) { bpf_trace_printk("Hello, World!\\n"); return 0; }').trace_print() +``` + +There are six things to learn from this: + +1. ```text='...'```: This defines a BPF program inline. The program is written in C. + +1. ```kprobe__sys_clone()```: This is a short-cut for kernel dynamic tracing via kprobes. If the C function begins with ``kprobe__``, the rest is treated as a kernel function name to instrument, in this case, ```sys_clone()```. + +1. ```void *ctx```: ctx has arguments, but since we aren't using them here, we'll just cast it to ```void *```. + +1. ```bpf_trace_printk()```: A simple kernel facility for printf() to the common trace_pipe (/sys/kernel/debug/tracing/trace_pipe). This is ok for some quick examples, but has limitations: 3 args max, 1 %s only, and trace_pipe is globally shared, so concurrent programs will have clashing output. A better interface is via BPF_PERF_OUTPUT(), covered later. + +1. ```return 0;```: Necessary formality (if you want to know why, see [#139](https://github.com/iovisor/bcc/issues/139)). + +1. ```.trace_print()```: A bcc routine that reads trace_pipe and prints the output. + +### Lesson 2. sys_sync() + +Write a program that traces the sys_sync() kernel function. Print "sys_sync() called" when it runs. Test by running ```sync``` in another session while tracing. The hello_world.py program has everything you need for this. + +Improve it by printing "Tracing sys_sync()... Ctrl-C to end." when the program first starts. Hint: it's just Python. + +### Lesson 3. hello_fields.py + +This program is in [examples/tracing/hello_fields.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/hello_fields.py). Sample output (run commands in another session): + +``` +# ./examples/tracing/hello_fields.py +TIME(s) COMM PID MESSAGE +24585001.174885999 sshd 1432 Hello, World! +24585001.195710000 sshd 15780 Hello, World! +24585001.991976000 systemd-udevd 484 Hello, World! +24585002.276147000 bash 15787 Hello, World! +``` + +Code: + +```Python +from bcc import BPF + +# define BPF program +prog = """ +int hello(void *ctx) { + bpf_trace_printk("Hello, World!\\n"); + return 0; +} +""" + +# load BPF program +b = BPF(text=prog) +b.attach_kprobe(event=b.get_syscall_fnname("clone"), fn_name="hello") + +# header +print("%-18s %-16s %-6s %s" % ("TIME(s)", "COMM", "PID", "MESSAGE")) + +# format output +while 1: + try: + (task, pid, cpu, flags, ts, msg) = b.trace_fields() + except ValueError: + continue + print("%-18.9f %-16s %-6d %s" % (ts, task, pid, msg)) +``` + +This is similar to hello_world.py, and traces new processes via sys_clone() again, but has a few more things to learn: + +1. ```prog =```: This time we declare the C program as a variable, and later refer to it. This is useful if you want to add some string substitutions based on command line arguments. + +1. ```hello()```: Now we're just declaring a C function, instead of the ```kprobe__``` shortcut. We'll refer to this later. All C functions declared in the BPF program are expected to be executed on a probe, hence they all need to take a ```pt_reg* ctx``` as first argument. If you need to define some helper function that will not be executed on a probe, they need to be defined as ```static inline``` in order to be inlined by the compiler. Sometimes you would also need to add ```_always_inline``` function attribute to it. + +1. ```b.attach_kprobe(event=b.get_syscall_fnname("clone"), fn_name="hello")```: Creates a kprobe for the kernel clone system call function, which will execute our defined hello() function. You can call attach_kprobe() more than once, and attach your C function to multiple kernel functions. + +1. ```b.trace_fields()```: Returns a fixed set of fields from trace_pipe. Similar to trace_print(), this is handy for hacking, but for real tooling we should switch to BPF_PERF_OUTPUT(). + +### Lesson 4. sync_timing.py + +Remember the days of sysadmins typing ```sync``` three times on a slow console before ```reboot```, to give the first asynchronous sync time to complete? Then someone thought ```sync;sync;sync``` was clever, to run them all on one line, which became industry practice despite defeating the original purpose! And then sync became synchronous, so more reasons it was silly. Anyway. + +The following example times how quickly the ```do_sync``` function is called, and prints output if it has been called more recently than one second ago. A ```sync;sync;sync``` will print output for the 2nd and 3rd sync's: + +``` +# ./examples/tracing/sync_timing.py +Tracing for quick sync's... Ctrl-C to end +At time 0.00 s: multiple syncs detected, last 95 ms ago +At time 0.10 s: multiple syncs detected, last 96 ms ago +``` + +This program is [examples/tracing/sync_timing.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/sync_timing.py): + +```Python +from __future__ import print_function +from bcc import BPF + +# load BPF program +b = BPF(text=""" +#include + +BPF_HASH(last); + +int do_trace(struct pt_regs *ctx) { + u64 ts, *tsp, delta, key = 0; + + // attempt to read stored timestamp + tsp = last.lookup(&key); + if (tsp != NULL) { + delta = bpf_ktime_get_ns() - *tsp; + if (delta < 1000000000) { + // output if time is less than 1 second + bpf_trace_printk("%d\\n", delta / 1000000); + } + last.delete(&key); + } + + // update stored timestamp + ts = bpf_ktime_get_ns(); + last.update(&key, &ts); + return 0; +} +""") + +b.attach_kprobe(event=b.get_syscall_fnname("sync"), fn_name="do_trace") +print("Tracing for quick sync's... Ctrl-C to end") + +# format output +start = 0 +while 1: + (task, pid, cpu, flags, ts, ms) = b.trace_fields() + if start == 0: + start = ts + ts = ts - start + print("At time %.2f s: multiple syncs detected, last %s ms ago" % (ts, ms)) +``` + +Things to learn: + +1. ```bpf_ktime_get_ns()```: Returns the time as nanoseconds. +1. ```BPF_HASH(last)```: Creates a BPF map object that is a hash (associative array), called "last". We didn't specify any further arguments, so it defaults to key and value types of u64. +1. ```key = 0```: We'll only store one key/value pair in this hash, where the key is hardwired to zero. +1. ```last.lookup(&key)```: Lookup the key in the hash, and return a pointer to its value if it exists, else NULL. We pass the key in as an address to a pointer. +1. ```if (tsp != NULL) {```: The verifier requires that pointer values derived from a map lookup must be checked for a null value before they can be dereferenced and used. +1. ```last.delete(&key)```: Delete the key from the hash. This is currently required because of [a kernel bug in `.update()`](https://git.kernel.org/cgit/linux/kernel/git/davem/net.git/commit/?id=a6ed3ea65d9868fdf9eff84e6fe4f666b8d14b02) (fixed in 4.8.10). +1. ```last.update(&key, &ts)```: Associate the value in the 2nd argument to the key, overwriting any previous value. This records the timestamp. + +### Lesson 5. sync_count.py + +Modify the sync_timing.py program (prior lesson) to store the count of all kernel sync system calls (both fast and slow), and print it with the output. This count can be recorded in the BPF program by adding a new key index to the existing hash. + +### Lesson 6. disksnoop.py + +Browse the [examples/tracing/disksnoop.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/disksnoop.py) program to see what is new. Here is some sample output: + +``` +# ./disksnoop.py +TIME(s) T BYTES LAT(ms) +16458043.436012 W 4096 3.13 +16458043.437326 W 4096 4.44 +16458044.126545 R 4096 42.82 +16458044.129872 R 4096 3.24 +[...] +``` + +And a code snippet: + +```Python +[...] +REQ_WRITE = 1 # from include/linux/blk_types.h + +# load BPF program +b = BPF(text=""" +#include +#include + +BPF_HASH(start, struct request *); + +void trace_start(struct pt_regs *ctx, struct request *req) { + // stash start timestamp by request ptr + u64 ts = bpf_ktime_get_ns(); + + start.update(&req, &ts); +} + +void trace_completion(struct pt_regs *ctx, struct request *req) { + u64 *tsp, delta; + + tsp = start.lookup(&req); + if (tsp != 0) { + delta = bpf_ktime_get_ns() - *tsp; + bpf_trace_printk("%d %x %d\\n", req->__data_len, + req->cmd_flags, delta / 1000); + start.delete(&req); + } +} +""") +if BPF.get_kprobe_functions(b'blk_start_request'): + b.attach_kprobe(event="blk_start_request", fn_name="trace_start") +b.attach_kprobe(event="blk_mq_start_request", fn_name="trace_start") +if BPF.get_kprobe_functions(b'__blk_account_io_done'): + b.attach_kprobe(event="__blk_account_io_done", fn_name="trace_completion") +else: + b.attach_kprobe(event="blk_account_io_done", fn_name="trace_completion") +[...] +``` + +Things to learn: + +1. ```REQ_WRITE```: We're defining a kernel constant in the Python program because we'll use it there later. If we were using REQ_WRITE in the BPF program, it should just work (without needing to be defined) with the appropriate #includes. +1. ```trace_start(struct pt_regs *ctx, struct request *req)```: This function will later be attached to kprobes. The arguments to kprobe functions are ```struct pt_regs *ctx```, for registers and BPF context, and then the actual arguments to the function. We'll attach this to blk_start_request(), where the first argument is ```struct request *```. +1. ```start.update(&req, &ts)```: We're using the pointer to the request struct as a key in our hash. What? This is commonplace in tracing. Pointers to structs turn out to be great keys, as they are unique: two structs can't have the same pointer address. (Just be careful about when it gets free'd and reused.) So what we're really doing is tagging the request struct, which describes the disk I/O, with our own timestamp, so that we can time it. There's two common keys used for storing timestamps: pointers to structs, and, thread IDs (for timing function entry to return). +1. ```req->__data_len```: We're dereferencing members of ```struct request```. See its definition in the kernel source for what members are there. bcc actually rewrites these expressions to be a series of ```bpf_probe_read_kernel()``` calls. Sometimes bcc can't handle a complex dereference, and you need to call ```bpf_probe_read_kernel()``` directly. + +This is a pretty interesting program, and if you can understand all the code, you'll understand many important basics. We're still using the bpf_trace_printk() hack, so let's fix that next. + +### Lesson 7. hello_perf_output.py + +Let's finally stop using bpf_trace_printk() and use the proper BPF_PERF_OUTPUT() interface. This will also mean we stop getting the free trace_field() members like PID and timestamp, and will need to fetch them directly. Sample output while commands are run in another session: + +``` +# ./hello_perf_output.py +TIME(s) COMM PID MESSAGE +0.000000000 bash 22986 Hello, perf_output! +0.021080275 systemd-udevd 484 Hello, perf_output! +0.021359520 systemd-udevd 484 Hello, perf_output! +0.021590610 systemd-udevd 484 Hello, perf_output! +[...] +``` + +Code is [examples/tracing/hello_perf_output.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/hello_perf_output.py): + +```Python +from bcc import BPF + +# define BPF program +prog = """ +#include + +// define output data structure in C +struct data_t { + u32 pid; + u64 ts; + char comm[TASK_COMM_LEN]; +}; +BPF_PERF_OUTPUT(events); + +int hello(struct pt_regs *ctx) { + struct data_t data = {}; + + data.pid = bpf_get_current_pid_tgid(); + data.ts = bpf_ktime_get_ns(); + bpf_get_current_comm(&data.comm, sizeof(data.comm)); + + events.perf_submit(ctx, &data, sizeof(data)); + + return 0; +} +""" + +# load BPF program +b = BPF(text=prog) +b.attach_kprobe(event=b.get_syscall_fnname("clone"), fn_name="hello") + +# header +print("%-18s %-16s %-6s %s" % ("TIME(s)", "COMM", "PID", "MESSAGE")) + +# process event +start = 0 +def print_event(cpu, data, size): + global start + event = b["events"].event(data) + if start == 0: + start = event.ts + time_s = (float(event.ts - start)) / 1000000000 + print("%-18.9f %-16s %-6d %s" % (time_s, event.comm, event.pid, + "Hello, perf_output!")) + +# loop with callback to print_event +b["events"].open_perf_buffer(print_event) +while 1: + b.perf_buffer_poll() +``` + +Things to learn: + +1. ```struct data_t```: This defines the C struct we'll use to pass data from kernel to user space. +1. ```BPF_PERF_OUTPUT(events)```: This names our output channel "events". +1. ```struct data_t data = {};```: Create an empty data_t struct that we'll then populate. +1. ```bpf_get_current_pid_tgid()```: Returns the process ID in the lower 32 bits (kernel's view of the PID, which in user space is usually presented as the thread ID), and the thread group ID in the upper 32 bits (what user space often thinks of as the PID). By directly setting this to a u32, we discard the upper 32 bits. Should you be presenting the PID or the TGID? For a multi-threaded app, the TGID will be the same, so you need the PID to differentiate them, if that's what you want. It's also a question of expectations for the end user. +1. ```bpf_get_current_comm()```: Populates the first argument address with the current process name. +1. ```events.perf_submit()```: Submit the event for user space to read via a perf ring buffer. +1. ```def print_event()```: Define a Python function that will handle reading events from the ```events``` stream. +1. ```b["events"].event(data)```: Now get the event as a Python object, auto-generated from the C declaration. +1. ```b["events"].open_perf_buffer(print_event)```: Associate the Python ```print_event``` function with the ```events``` stream. +1. ```while 1: b.perf_buffer_poll()```: Block waiting for events. + +### Lesson 8. sync_perf_output.py + +Rewrite sync_timing.py, from a prior lesson, to use ```BPF_PERF_OUTPUT```. + +### Lesson 9. bitehist.py + +The following tool records a histogram of disk I/O sizes. Sample output: + +``` +# ./bitehist.py +Tracing... Hit Ctrl-C to end. +^C + kbytes : count distribution + 0 -> 1 : 3 | | + 2 -> 3 : 0 | | + 4 -> 7 : 211 |********** | + 8 -> 15 : 0 | | + 16 -> 31 : 0 | | + 32 -> 63 : 0 | | + 64 -> 127 : 1 | | + 128 -> 255 : 800 |**************************************| +``` + +Code is [examples/tracing/bitehist.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/bitehist.py): + +```Python +from __future__ import print_function +from bcc import BPF +from time import sleep + +# load BPF program +b = BPF(text=""" +#include +#include + +BPF_HISTOGRAM(dist); + +int kprobe__blk_account_io_done(struct pt_regs *ctx, struct request *req) +{ + dist.increment(bpf_log2l(req->__data_len / 1024)); + return 0; +} +""") + +# header +print("Tracing... Hit Ctrl-C to end.") + +# trace until Ctrl-C +try: + sleep(99999999) +except KeyboardInterrupt: + print() + +# output +b["dist"].print_log2_hist("kbytes") +``` + +A recap from earlier lessons: + +- ```kprobe__```: This prefix means the rest will be treated as a kernel function name that will be instrumented using kprobe. +- ```struct pt_regs *ctx, struct request *req```: Arguments to kprobe. The ```ctx``` is registers and BPF context, the ```req``` is the first argument to the instrumented function: ```blk_account_io_done()```. +- ```req->__data_len```: Dereferencing that member. + +New things to learn: + +1. ```BPF_HISTOGRAM(dist)```: Defines a BPF map object that is a histogram, and names it "dist". +1. ```dist.increment()```: Increments the histogram bucket index provided as first argument by one by default. Optionally, custom increments can be passed as the second argument. +1. ```bpf_log2l()```: Returns the log-2 of the provided value. This becomes the index of our histogram, so that we're constructing a power-of-2 histogram. +1. ```b["dist"].print_log2_hist("kbytes")```: Prints the "dist" histogram as power-of-2, with a column header of "kbytes". The only data transferred from kernel to user space is the bucket counts, making this efficient. + +### Lesson 10. disklatency.py + +Write a program that times disk I/O, and prints a histogram of their latency. Disk I/O instrumentation and timing can be found in the disksnoop.py program from a prior lesson, and histogram code can be found in bitehist.py from a prior lesson. + +### Lesson 11. vfsreadlat.py + +This example is split into separate Python and C files. Example output: + +``` +# ./vfsreadlat.py 1 +Tracing... Hit Ctrl-C to end. + usecs : count distribution + 0 -> 1 : 0 | | + 2 -> 3 : 2 |*********** | + 4 -> 7 : 7 |****************************************| + 8 -> 15 : 4 |********************** | + + usecs : count distribution + 0 -> 1 : 29 |****************************************| + 2 -> 3 : 28 |************************************** | + 4 -> 7 : 4 |***** | + 8 -> 15 : 8 |*********** | + 16 -> 31 : 0 | | + 32 -> 63 : 0 | | + 64 -> 127 : 0 | | + 128 -> 255 : 0 | | + 256 -> 511 : 2 |** | + 512 -> 1023 : 0 | | + 1024 -> 2047 : 0 | | + 2048 -> 4095 : 0 | | + 4096 -> 8191 : 4 |***** | + 8192 -> 16383 : 6 |******** | + 16384 -> 32767 : 9 |************ | + 32768 -> 65535 : 6 |******** | + 65536 -> 131071 : 2 |** | + + usecs : count distribution + 0 -> 1 : 11 |****************************************| + 2 -> 3 : 2 |******* | + 4 -> 7 : 10 |************************************ | + 8 -> 15 : 8 |***************************** | + 16 -> 31 : 1 |*** | + 32 -> 63 : 2 |******* | +[...] +``` + +Browse the code in [examples/tracing/vfsreadlat.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/vfsreadlat.py) and [examples/tracing/vfsreadlat.c](https://github.com/iovisor/bcc/tree/master/examples/tracing/vfsreadlat.c). Things to learn: + +1. ```b = BPF(src_file = "vfsreadlat.c")```: Read the BPF C program from a separate source file. +1. ```b.attach_kretprobe(event="vfs_read", fn_name="do_return")```: Attaches the BPF C function ```do_return()``` to the return of the kernel function ```vfs_read()```. This is a kretprobe: instrumenting the return from a function, rather than its entry. +1. ```b["dist"].clear()```: Clears the histogram. + +### Lesson 12. urandomread.py + +Tracing while a ```dd if=/dev/urandom of=/dev/null bs=8k count=5``` is run: + +``` +# ./urandomread.py +TIME(s) COMM PID GOTBITS +24652832.956994001 smtp 24690 384 +24652837.726500999 dd 24692 65536 +24652837.727111001 dd 24692 65536 +24652837.727703001 dd 24692 65536 +24652837.728294998 dd 24692 65536 +24652837.728888001 dd 24692 65536 +``` + +Hah! I caught smtp by accident. Code is [examples/tracing/urandomread.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/urandomread.py): + +```Python +from __future__ import print_function +from bcc import BPF + +# load BPF program +b = BPF(text=""" +TRACEPOINT_PROBE(random, urandom_read) { + // args is from /sys/kernel/debug/tracing/events/random/urandom_read/format + bpf_trace_printk("%d\\n", args->got_bits); + return 0; +} +""") + +# header +print("%-18s %-16s %-6s %s" % ("TIME(s)", "COMM", "PID", "GOTBITS")) + +# format output +while 1: + try: + (task, pid, cpu, flags, ts, msg) = b.trace_fields() + except ValueError: + continue + print("%-18.9f %-16s %-6d %s" % (ts, task, pid, msg)) +``` + +Things to learn: + +1. ```TRACEPOINT_PROBE(random, urandom_read)```: Instrument the kernel tracepoint ```random:urandom_read```. These have a stable API, and thus are recommend to use instead of kprobes, wherever possible. You can run ```perf list``` for a list of tracepoints. Linux >= 4.7 is required to attach BPF programs to tracepoints. +1. ```args->got_bits```: ```args``` is auto-populated to be a structure of the tracepoint arguments. The comment above says where you can see that structure. Eg: + +``` +# cat /sys/kernel/debug/tracing/events/random/urandom_read/format +name: urandom_read +ID: 972 +format: + field:unsigned short common_type; offset:0; size:2; signed:0; + field:unsigned char common_flags; offset:2; size:1; signed:0; + field:unsigned char common_preempt_count; offset:3; size:1; signed:0; + field:int common_pid; offset:4; size:4; signed:1; + + field:int got_bits; offset:8; size:4; signed:1; + field:int pool_left; offset:12; size:4; signed:1; + field:int input_left; offset:16; size:4; signed:1; + +print fmt: "got_bits %d nonblocking_pool_entropy_left %d input_entropy_left %d", REC->got_bits, REC->pool_left, REC->input_left +``` + +In this case, we were printing the ```got_bits``` member. + +### Lesson 13. disksnoop.py fixed + +Convert disksnoop.py from a previous lesson to use the ```block:block_rq_issue``` and ```block:block_rq_complete``` tracepoints. + +### Lesson 14. strlen_count.py + +This program instruments a user-level function, the ```strlen()``` library function, and frequency counts its string argument. Example output: + +``` +# ./strlen_count.py +Tracing strlen()... Hit Ctrl-C to end. +^C COUNT STRING + 1 " " + 1 "/bin/ls" + 1 "." + 1 "cpudist.py.1" + 1 ".bashrc" + 1 "ls --color=auto" + 1 "key_t" +[...] + 10 "a7:~# " + 10 "/root" + 12 "LC_ALL" + 12 "en_US.UTF-8" + 13 "en_US.UTF-8" + 20 "~" + 70 "#%^,~:-=?+/}" + 340 "\x01\x1b]0;root@bgregg-test: ~\x07\x02root@bgregg-test:~# " +``` + +These are various strings that are being processed by this library function while tracing, along with their frequency counts. ```strlen()``` was called on "LC_ALL" 12 times, for example. + +Code is [examples/tracing/strlen_count.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/strlen_count.py): + +```Python +from __future__ import print_function +from bcc import BPF +from time import sleep + +# load BPF program +b = BPF(text=""" +#include + +struct key_t { + char c[80]; +}; +BPF_HASH(counts, struct key_t); + +int count(struct pt_regs *ctx) { + if (!PT_REGS_PARM1(ctx)) + return 0; + + struct key_t key = {}; + u64 zero = 0, *val; + + bpf_probe_read_user(&key.c, sizeof(key.c), (void *)PT_REGS_PARM1(ctx)); + // could also use `counts.increment(key)` + val = counts.lookup_or_try_init(&key, &zero); + if (val) { + (*val)++; + } + return 0; +}; +""") +b.attach_uprobe(name="c", sym="strlen", fn_name="count") + +# header +print("Tracing strlen()... Hit Ctrl-C to end.") + +# sleep until Ctrl-C +try: + sleep(99999999) +except KeyboardInterrupt: + pass + +# print output +print("%10s %s" % ("COUNT", "STRING")) +counts = b.get_table("counts") +for k, v in sorted(counts.items(), key=lambda counts: counts[1].value): + print("%10d \"%s\"" % (v.value, k.c.encode('string-escape'))) +``` + +Things to learn: + +1. ```PT_REGS_PARM1(ctx)```: This fetches the first argument to ```strlen()```, which is the string. +1. ```b.attach_uprobe(name="c", sym="strlen", fn_name="count")```: Attach to library "c" (if this is the main program, use its pathname), instrument the user-level function ```strlen()```, and on execution call our C function ```count()```. + +### Lesson 15. nodejs_http_server.py + +This program instruments a user statically-defined tracing (USDT) probe, which is the user-level version of a kernel tracepoint. Sample output: + +``` +# ./nodejs_http_server.py 24728 +TIME(s) COMM PID ARGS +24653324.561322998 node 24728 path:/index.html +24653335.343401998 node 24728 path:/images/welcome.png +24653340.510164998 node 24728 path:/images/favicon.png +``` + +Relevant code from [examples/tracing/nodejs_http_server.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/nodejs_http_server.py): + +```Python +from __future__ import print_function +from bcc import BPF, USDT +import sys + +if len(sys.argv) < 2: + print("USAGE: nodejs_http_server PID") + exit() +pid = sys.argv[1] +debug = 0 + +# load BPF program +bpf_text = """ +#include +int do_trace(struct pt_regs *ctx) { + uint64_t addr; + char path[128]={0}; + bpf_usdt_readarg(6, ctx, &addr); + bpf_probe_read_user(&path, sizeof(path), (void *)addr); + bpf_trace_printk("path:%s\\n", path); + return 0; +}; +""" + +# enable USDT probe from given PID +u = USDT(pid=int(pid)) +u.enable_probe(probe="http__server__request", fn_name="do_trace") +if debug: + print(u.get_text()) + print(bpf_text) + +# initialize BPF +b = BPF(text=bpf_text, usdt_contexts=[u]) +``` + +Things to learn: + +1. ```bpf_usdt_readarg(6, ctx, &addr)```: Read the address of argument 6 from the USDT probe into ```addr```. +1. ```bpf_probe_read_user(&path, sizeof(path), (void *)addr)```: Now the string ```addr``` points to into our ```path``` variable. +1. ```u = USDT(pid=int(pid))```: Initialize USDT tracing for the given PID. +1. ```u.enable_probe(probe="http__server__request", fn_name="do_trace")```: Attach our ```do_trace()``` BPF C function to the Node.js ```http__server__request``` USDT probe. +1. ```b = BPF(text=bpf_text, usdt_contexts=[u])```: Need to pass in our USDT object, ```u```, to BPF object creation. + +### Lesson 16. task_switch.c + +This is an older tutorial included as a bonus lesson. Use this for recap and to reinforce what you've already learned. + +This is a slightly more complex tracing example than Hello World. This program +will be invoked for every task change in the kernel, and record in a BPF map +the new and old pids. + +The C program below introduces a new concept: the prev argument. This +argument is treated specially by the BCC frontend, such that accesses +to this variable are read from the saved context that is passed by the +kprobe infrastructure. The prototype of the args starting from +position 1 should match the prototype of the kernel function being +kprobed. If done so, the program will have seamless access to the +function parameters. + +```c +#include +#include + +struct key_t { + u32 prev_pid; + u32 curr_pid; +}; + +BPF_HASH(stats, struct key_t, u64, 1024); +int count_sched(struct pt_regs *ctx, struct task_struct *prev) { + struct key_t key = {}; + u64 zero = 0, *val; + + key.curr_pid = bpf_get_current_pid_tgid(); + key.prev_pid = prev->pid; + + // could also use `stats.increment(key);` + val = stats.lookup_or_try_init(&key, &zero); + if (val) { + (*val)++; + } + return 0; +} +``` + +The userspace component loads the file shown above, and attaches it to the +`finish_task_switch` kernel function. +The `[]` operator of the BPF object gives access to each BPF_HASH in the +program, allowing pass-through access to the values residing in the kernel. Use +the object as you would any other python dict object: read, update, and deletes +are all allowed. +```python +from bcc import BPF +from time import sleep + +b = BPF(src_file="task_switch.c") +b.attach_kprobe(event="finish_task_switch", fn_name="count_sched") + +# generate many schedule events +for i in range(0, 100): sleep(0.01) + +for k, v in b["stats"].items(): + print("task_switch[%5d->%5d]=%u" % (k.prev_pid, k.curr_pid, v.value)) +``` + +These programs can be found in the files [examples/tracing/task_switch.c](https://github.com/iovisor/bcc/tree/master/examples/tracing/task_switch.c) and [examples/tracing/task_switch.py](https://github.com/iovisor/bcc/tree/master/examples/tracing/task_switch.py) respectively. + +### Lesson 17. Further Study + +For further study, see Sasha Goldshtein's [linux-tracing-workshop](https://github.com/goldshtn/linux-tracing-workshop), which contains additional labs. There are also many tools in bcc /tools to study. + +Please read [CONTRIBUTING-SCRIPTS.md](https://github.com/iovisor/bcc/tree/master/CONTRIBUTING-SCRIPTS.md) if you wish to contribute tools to bcc. At the bottom of the main [README.md](https://github.com/iovisor/bcc/tree/master/README.md), you'll also find methods for contacting us. Good luck, and happy tracing! + +## Networking + +To do.