143448428SQuentin Monnet.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 243448428SQuentin Monnet 39406b485SYonghong Song============ 49406b485SYonghong Songbpftool-iter 59406b485SYonghong Song============ 69406b485SYonghong Song------------------------------------------------------------------------------- 79406b485SYonghong Songtool to create BPF iterators 89406b485SYonghong Song------------------------------------------------------------------------------- 99406b485SYonghong Song 109406b485SYonghong Song:Manual section: 8 119406b485SYonghong Song 12*b6231815SQuentin Monnet.. include:: substitutions.rst 13*b6231815SQuentin Monnet 149406b485SYonghong SongSYNOPSIS 159406b485SYonghong Song======== 169406b485SYonghong Song 179406b485SYonghong Song **bpftool** [*OPTIONS*] **iter** *COMMAND* 189406b485SYonghong Song 19*b6231815SQuentin Monnet *OPTIONS* := { |COMMON_OPTIONS| } 20c07ba629SQuentin Monnet 219406b485SYonghong Song *COMMANDS* := { **pin** | **help** } 229406b485SYonghong Song 239406b485SYonghong SongITER COMMANDS 249406b485SYonghong Song=================== 259406b485SYonghong Song 26d8793acaSYonghong Song| **bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*] 279406b485SYonghong Song| **bpftool** **iter help** 289406b485SYonghong Song| 299406b485SYonghong Song| *OBJ* := /a/file/of/bpf_iter_target.o 30d8793acaSYonghong Song| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 319406b485SYonghong Song 329406b485SYonghong SongDESCRIPTION 339406b485SYonghong Song=========== 34d8793acaSYonghong Song **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*] 359406b485SYonghong Song A bpf iterator combines a kernel iterating of 369406b485SYonghong Song particular kernel data (e.g., tasks, bpf_maps, etc.) 379406b485SYonghong Song and a bpf program called for each kernel data object 389406b485SYonghong Song (e.g., one task, one bpf_map, etc.). User space can 399406b485SYonghong Song *read* kernel iterator output through *read()* syscall. 409406b485SYonghong Song 419406b485SYonghong Song The *pin* command creates a bpf iterator from *OBJ*, 429406b485SYonghong Song and pin it to *PATH*. The *PATH* should be located 439406b485SYonghong Song in *bpffs* mount. It must not contain a dot 449406b485SYonghong Song character ('.'), which is reserved for future extensions 459406b485SYonghong Song of *bpffs*. 469406b485SYonghong Song 47d8793acaSYonghong Song Map element bpf iterator requires an additional parameter 48d8793acaSYonghong Song *MAP* so bpf program can iterate over map elements for 49d8793acaSYonghong Song that map. User can have a bpf program in kernel to run 50d8793acaSYonghong Song with each map element, do checking, filtering, aggregation, 51d8793acaSYonghong Song etc. without copying data to user space. 52d8793acaSYonghong Song 539406b485SYonghong Song User can then *cat PATH* to see the bpf iterator output. 549406b485SYonghong Song 559406b485SYonghong Song **bpftool iter help** 569406b485SYonghong Song Print short help message. 579406b485SYonghong Song 589406b485SYonghong SongOPTIONS 599406b485SYonghong Song======= 60f28ef96dSQuentin Monnet .. include:: common_options.rst 619406b485SYonghong Song 629406b485SYonghong SongEXAMPLES 639406b485SYonghong Song======== 649406b485SYonghong Song**# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink** 659406b485SYonghong Song 669406b485SYonghong Song:: 679406b485SYonghong Song 689406b485SYonghong Song Create a file-based bpf iterator from bpf_iter_netlink.o and pin it 699406b485SYonghong Song to /sys/fs/bpf/my_netlink 709406b485SYonghong Song 71d8793acaSYonghong Song**# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20** 72d8793acaSYonghong Song 73d8793acaSYonghong Song:: 74d8793acaSYonghong Song 75d8793acaSYonghong Song Create a file-based bpf iterator from bpf_iter_hashmap.o and map with 76d8793acaSYonghong Song id 20, and pin it to /sys/fs/bpf/my_hashmap 77