Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 .. SPDX-License-Identifier: (GPL-2.0-only OR B << 2 << 3 ================ 1 ================ 4 bpftool-prog 2 bpftool-prog 5 ================ 3 ================ 6 ---------------------------------------------- 4 ------------------------------------------------------------------------------- 7 tool for inspection and simple manipulation of 5 tool for inspection and simple manipulation of eBPF progs 8 ---------------------------------------------- 6 ------------------------------------------------------------------------------- 9 7 10 :Manual section: 8 8 :Manual section: 8 11 9 12 .. include:: substitutions.rst << 13 << 14 SYNOPSIS 10 SYNOPSIS 15 ======== 11 ======== 16 12 17 **bpftool** [*OPTIONS*] **prog** *COMMAND* !! 13 **bpftool** [*OPTIONS*] **prog** *COMMAND* 18 14 19 *OPTIONS* := { |COMMON_OPTIONS| | !! 15 *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 20 { **-f** | **--bpffs** } | { **-m** | **--mapc << 21 { **-L** | **--use-loader** } } << 22 16 23 *COMMANDS* := !! 17 *COMMANDS* := 24 { **show** | **list** | **dump xlated** | **du !! 18 { **show** | **dump xlated** | **dump jited** | **pin** | **help** } 25 **loadall** | **help** } << 26 19 27 PROG COMMANDS !! 20 MAP COMMANDS 28 ============= 21 ============= 29 22 30 | **bpftool** **prog** { **show** | **list** } !! 23 | **bpftool** **prog show** [*PROG*] 31 | **bpftool** **prog dump xlated** *PROG* [{ * !! 24 | **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes**}] 32 | **bpftool** **prog dump jited** *PROG* [{ * !! 25 | **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes**}] 33 | **bpftool** **prog pin** *PROG* *FILE* !! 26 | **bpftool** **prog pin** *PROG* *FILE* 34 | **bpftool** **prog** { **load** | **loadall* !! 27 | **bpftool** **prog help** 35 | **bpftool** **prog attach** *PROG* *ATTACH_T << 36 | **bpftool** **prog detach** *PROG* *ATTACH_T << 37 | **bpftool** **prog tracelog** << 38 | **bpftool** **prog run** *PROG* **data_in** << 39 | **bpftool** **prog profile** *PROG* [**durat << 40 | **bpftool** **prog help** << 41 | 28 | 42 | *MAP* := { **id** *MAP_ID* | **pinned** *FIL !! 29 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 43 | *PROG* := { **id** *PROG_ID* | **pinned** *F << 44 | *TYPE* := { << 45 | **socket** | **kprobe** | **kretprobe** << 46 | **tracepoint** | **raw_tracepoint** | ** << 47 | **cgroup/sock** | **cgroup/dev** | **lwt << 48 | **lwt_seg6local** | **sockops** | **sk_s << 49 | **cgroup/bind4** | **cgroup/bind6** | ** << 50 | **cgroup/connect4** | **cgroup/connect6* << 51 | **cgroup/getpeername4** | **cgroup/getpe << 52 | **cgroup/getsockname4** | **cgroup/getso << 53 | **cgroup/sendmsg4** | **cgroup/sendmsg6* << 54 | **cgroup/recvmsg4** | **cgroup/recvmsg6* << 55 | **cgroup/getsockopt** | **cgroup/setsock << 56 | **struct_ops** | **fentry** | **fexit** << 57 | } << 58 | *ATTACH_TYPE* := { << 59 | **sk_msg_verdict** | **sk_skb_verdict** << 60 | **sk_skb_stream_parser** | **flow_dissec << 61 | } << 62 | *METRICs* := { << 63 | **cycles** | **instructions** | **l1d_lo << 64 | **itlb_misses** | **dtlb_misses** << 65 | } << 66 << 67 30 68 DESCRIPTION 31 DESCRIPTION 69 =========== 32 =========== 70 bpftool prog { show | list } [*PROG*] !! 33 **bpftool prog show** [*PROG*] 71 Show information about loaded programs. I !! 34 Show information about loaded programs. If *PROG* is 72 information only about given programs, oth !! 35 specified show information only about given program, otherwise 73 currently loaded on the system. In case of !! 36 list all programs currently loaded on the system. 74 match several programs which will all be s !! 37 75 !! 38 Output will start with program ID followed by program type and 76 Output will start with program ID followed !! 39 zero or more named attributes (depending on kernel version). 77 named attributes (depending on kernel vers !! 40 78 !! 41 **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** }] 79 Since Linux 5.1 the kernel can collect sta !! 42 Dump eBPF instructions of the program from the kernel. 80 the total time spent running the program, !! 43 If *FILE* is specified image will be written to a file, 81 run). If available, bpftool shows such sta !! 44 otherwise it will be disassembled and printed to stdout. 82 not collect them by defaults, as it slight !! 45 83 program run. Activation or deactivation of !! 46 **opcodes** controls if raw opcodes will be printed. 84 **kernel.bpf_stats_enabled** sysctl knob. !! 47 85 !! 48 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** }] 86 Since Linux 5.8 bpftool is able to discove !! 49 Dump jited image (host machine code) of the program. 87 that hold open file descriptors (FDs) agai !! 50 If *FILE* is specified image will be written to a file, 88 bpftool will automatically emit this infor !! 51 otherwise it will be disassembled and printed to stdout. 89 !! 52 90 bpftool prog dump xlated *PROG* [{ file *FILE* !! 53 **opcodes** controls if raw opcodes will be printed. 91 Dump eBPF instructions of the programs fro !! 54 92 will be disassembled and printed to standa !! 55 **bpftool prog pin** *PROG* *FILE* 93 format. In this case, **opcodes** controls !! 56 Pin program *PROG* as *FILE*. 94 as well. << 95 << 96 In case of **tag** or **name**, *PROG* may << 97 will all be dumped. However, if **file** << 98 *PROG* must match a single program. << 99 << 100 If **file** is specified, the binary image << 101 *FILE*. << 102 << 103 If **visual** is specified, control flow g << 104 and eBPF instructions will be presented wi << 105 output. << 106 << 107 If the programs have line_info available, << 108 displayed. If **linum** is specified, the << 109 column will also be displayed. << 110 << 111 bpftool prog dump jited *PROG* [{ file *FILE* << 112 Dump jited image (host machine code) of th << 113 << 114 If *FILE* is specified image will be writt << 115 be disassembled and printed to stdout. *PR << 116 when **file** is specified. << 117 << 118 **opcodes** controls if raw opcodes will b << 119 << 120 If the prog has line_info available, the s << 121 **linum** is specified, the filename, line << 122 be displayed. << 123 << 124 bpftool prog pin *PROG* *FILE* << 125 Pin program *PROG* as *FILE*. << 126 << 127 Note: *FILE* must be located in *bpffs* mo << 128 character ('.'), which is reserved for fut << 129 << 130 bpftool prog { load | loadall } *OBJ* *PATH* [ << 131 Load bpf program(s) from binary *OBJ* and << 132 load** pins only the first program from th << 133 loadall** pins all programs from the *OBJ* << 134 is optional, if not specified program type << 135 names. By default bpftool will create new << 136 object being loaded. **map** parameter al << 137 maps. It can be specified multiple times, << 138 *IDX* refers to index of the map to be rep << 139 from 0, while *NAME* allows to replace a m << 140 map to use, referring to it by **id** or t << 141 **offload_dev** *NAME* is specified progra << 142 networking device (offload). If **xdpmeta_ << 143 will become device-bound without offloadin << 144 metadata. Optional **pinmaps** argument ca << 145 under *MAP_DIR* directory. << 146 << 147 If **autoattach** is specified program wil << 148 case, only the link (representing the prog << 149 pinned, not the program as such, so the pa << 150 show -f**, only show in **bpftool link sho << 151 when bpftool (libbpf) is able to infer all << 152 object file, in particular, it's not suppo << 153 program does not support autoattach, bpfto << 154 for that program instead. << 155 << 156 Note: *PATH* must be located in *bpffs* mo << 157 character ('.'), which is reserved for fut << 158 << 159 bpftool prog attach *PROG* *ATTACH_TYPE* [*MAP << 160 Attach bpf program *PROG* (with type speci << 161 *ATTACH_TYPEs* require a *MAP* parameter, << 162 *flow_dissector* which is attached to curr << 163 << 164 bpftool prog detach *PROG* *ATTACH_TYPE* [*MAP << 165 Detach bpf program *PROG* (with type speci << 166 *ATTACH_TYPEs* require a *MAP* parameter, << 167 *flow_dissector* which is detached from th << 168 << 169 bpftool prog tracelog << 170 Dump the trace pipe of the system to the c << 171 stop printing. BPF programs can write to t << 172 the **bpf_trace_printk**\ () helper. This << 173 purposes. For streaming data from BPF prog << 174 perf events (see also **bpftool-map**\ (8) << 175 << 176 bpftool prog run *PROG* data_in *FILE* [data_o << 177 Run BPF program *PROG* in the kernel testi << 178 meaning that the program works on the data << 179 user, and not on actual packets or monitor << 180 and duration for the test run are printed << 181 << 182 Input data is read from the *FILE* passed << 183 is "**-**", input data is read from standa << 184 is read from *FILE* passed with **ctx_in** << 185 read from standard input, but only if stan << 186 for input data. If a *FILE* is passed with << 187 written to that file. Similarly, output co << 188 passed with **ctx_out**. For both output f << 189 print to the standard output (as plain tex << 190 passed). If output keywords are omitted, o << 191 discarded. Keywords **data_size_out** and << 192 the size (in bytes) for the output buffers << 193 default of 32 kB should be more than enoug << 194 << 195 Keyword **repeat** is used to indicate the << 196 perform. Note that output data and context << 197 the last of those runs. The duration print << 198 an average over all runs performed by the << 199 << 200 Not all program types support test run. Am << 201 them can take the **ctx_in**/**ctx_out** a << 202 perform checks on program types. << 203 << 204 bpftool prog profile *PROG* [duration *DURATIO << 205 Profile *METRICs* for bpf program *PROG* f << 206 user hits <Ctrl+C>. *DURATION* is optional << 207 the profiling will run up to **UINT_MAX** << 208 57 209 bpftool prog help !! 58 Note: *FILE* must be located in *bpffs* mount. 210 Print short help message. !! 59 >> 60 **bpftool prog help** >> 61 Print short help message. 211 62 212 OPTIONS 63 OPTIONS 213 ======= 64 ======= 214 .. include:: common_options.rst !! 65 -h, --help >> 66 Print short generic help message (similar to **bpftool help**). >> 67 >> 68 -v, --version >> 69 Print version number (similar to **bpftool version**). 215 70 216 -f, --bpffs !! 71 -j, --json 217 When showing BPF programs, show file names !! 72 Generate JSON output. For commands that cannot produce JSON, this >> 73 option has no effect. 218 74 219 -m, --mapcompat !! 75 -p, --pretty 220 Allow loading maps with unknown map defini !! 76 Generate human-readable JSON output. Implies **-j**. 221 77 222 -n, --nomount !! 78 -f, --bpffs 223 Do not automatically attempt to mount any !! 79 Show file names of pinned programs. 224 tracefs or BPF virtual file system) when n << 225 << 226 -L, --use-loader << 227 Load program as a "loader" program. This i << 228 of such programs. When this option is in u << 229 programs from the object file into the ker << 230 (therefore, the *PATH* must not be provide << 231 << 232 When combined with the **-d**\ \|\ **--deb << 233 messages are generated, and the execution << 234 the **bpf_trace_printk**\ () helper to log << 235 creating the maps, and loading the program << 236 as a way to dump those messages). << 237 80 238 EXAMPLES 81 EXAMPLES 239 ======== 82 ======== 240 **# bpftool prog show** 83 **# bpftool prog show** 241 << 242 :: 84 :: 243 85 244 10: xdp name some_prog tag 005a3d2123620 !! 86 10: xdp name some_prog tag 005a3d2123620c8b 245 loaded_at 2017-09-29T20:11:00+0000 !! 87 loaded_at Sep 29/20:11 uid 0 246 xlated 528B jited 370B memlock 4 !! 88 xlated 528B jited 370B memlock 4096B map_ids 10 247 pids systemd(1) << 248 89 249 **# bpftool --json --pretty prog show** 90 **# bpftool --json --pretty prog show** 250 91 251 :: 92 :: 252 93 253 [{ !! 94 { 254 "id": 10, !! 95 "programs": [{ 255 "type": "xdp", !! 96 "id": 10, 256 "tag": "005a3d2123620c8b", !! 97 "type": "xdp", 257 "gpl_compatible": true, !! 98 "tag": "005a3d2123620c8b", 258 "run_time_ns": 81632, !! 99 "loaded_at": "Sep 29/20:11", 259 "run_cnt": 10, !! 100 "uid": 0, 260 "loaded_at": 1506715860, !! 101 "bytes_xlated": 528, 261 "uid": 0, !! 102 "jited": true, 262 "bytes_xlated": 528, !! 103 "bytes_jited": 370, 263 "jited": true, !! 104 "bytes_memlock": 4096, 264 "bytes_jited": 370, !! 105 "map_ids": [10 265 "bytes_memlock": 4096, !! 106 ] 266 "map_ids": [10 !! 107 } 267 ], !! 108 ] 268 "pids": [{ !! 109 } 269 "pid": 1, << 270 "comm": "systemd" << 271 } << 272 ] << 273 } << 274 ] << 275 110 276 | 111 | 277 | **# bpftool prog dump xlated id 10 file /tmp 112 | **# bpftool prog dump xlated id 10 file /tmp/t** 278 | **$ ls -l /tmp/t** !! 113 | **# ls -l /tmp/t** 279 !! 114 | -rw------- 1 root root 560 Jul 22 01:42 /tmp/t 280 :: << 281 << 282 -rw------- 1 root root 560 Jul 22 01:42 /t << 283 115 284 **# bpftool prog dump jited tag 005a3d2123620c !! 116 **# bpftool prog dum jited tag 005a3d2123620c8b** 285 117 286 :: 118 :: 287 119 288 0: push %rbp !! 120 push %rbp 289 1: mov %rsp,%rbp !! 121 mov %rsp,%rbp 290 2: sub $0x228,%rsp !! 122 sub $0x228,%rsp 291 3: sub $0x28,%rbp !! 123 sub $0x28,%rbp 292 4: mov %rbx,0x0(%rbp) !! 124 mov %rbx,0x0(%rbp) 293 125 294 | 126 | 295 | **# mount -t bpf none /sys/fs/bpf/** 127 | **# mount -t bpf none /sys/fs/bpf/** 296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog* 128 | **# bpftool prog pin id 10 /sys/fs/bpf/prog** 297 | **# bpftool prog load ./my_prog.o /sys/fs/bp << 298 | **# ls -l /sys/fs/bpf/** 129 | **# ls -l /sys/fs/bpf/** >> 130 | -rw------- 1 root root 0 Jul 22 01:43 prog 299 131 300 :: !! 132 **# bpftool prog dum jited pinned /sys/fs/bpf/prog opcodes** 301 << 302 -rw------- 1 root root 0 Jul 22 01:43 prog << 303 -rw------- 1 root root 0 Jul 22 01:44 prog << 304 << 305 **# bpftool prog dump jited pinned /sys/fs/bpf << 306 << 307 :: << 308 << 309 0: push %rbp << 310 55 << 311 1: mov %rsp,%rbp << 312 48 89 e5 << 313 4: sub $0x228,%rsp << 314 48 81 ec 28 02 00 00 << 315 b: sub $0x28,%rbp << 316 48 83 ed 28 << 317 f: mov %rbx,0x0(%rbp) << 318 48 89 5d 00 << 319 << 320 | << 321 | **# bpftool prog load xdp1_kern.o /sys/fs/bp << 322 | **# bpftool prog show pinned /sys/fs/bpf/xdp << 323 << 324 :: << 325 << 326 9: xdp name xdp_prog1 tag 539ec6ce11b52f << 327 loaded_at 2018-06-25T16:17:31-0700 << 328 xlated 488B jited 336B memlock 4 << 329 << 330 **# rm /sys/fs/bpf/xdp1** << 331 << 332 | << 333 | **# bpftool prog profile id 337 duration 10 << 334 133 335 :: 134 :: 336 135 337 51397 run_cnt !! 136 push %rbp 338 40176203 cycles !! 137 55 339 42518139 instructions # 1.06 insns !! 138 mov %rsp,%rbp 340 123 llc_misses # 2.89 LLC mi !! 139 48 89 e5 >> 140 sub $0x228,%rsp >> 141 48 81 ec 28 02 00 00 >> 142 sub $0x28,%rbp >> 143 48 83 ed 28 >> 144 mov %rbx,0x0(%rbp) >> 145 48 89 5d 00 341 146 342 | << 343 | Output below is for the trace logs. << 344 | Run in separate terminals: << 345 | **# bpftool prog tracelog** << 346 | **# bpftool prog load -L -d file.o** << 347 << 348 :: << 349 147 350 bpftool-620059 [004] d... 2634685.517903: !! 148 SEE ALSO 351 bpftool-620059 [004] d... 2634685.517912: !! 149 ======== 352 bpftool-620059 [004] d... 2634685.517997: !! 150 **bpftool**\ (8), **bpftool-map**\ (8) 353 bpftool-620059 [004] d... 2634685.517999: <<

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst

Diff markup

Differences between /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-6.12-rc7) and /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-4.15.18)

TOMOYO Linux Cross Reference Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst

Diff markup

Differences between /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-6.12-rc7) and /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-4.15.18)

TOMOYO Linux Cross Reference
Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst