Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-14 08:02:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

tools: bpftool: Document and add bash completion for -L, -B options

Browse Source 
The -L|--use-loader option for using loader programs when loading, or
when generating a skeleton, did not have any documentation or bash
completion. Same thing goes for -B|--base-btf, used to pass a path to a
base BTF object for split BTF such as BTF for kernel modules.

This patch documents and adds bash completion for those options.

Fixes: 75fa177769 ("tools/bpftool: Add bpftool support for split BTF")
Fixes: d510296d33 ("bpftool: Use syscall/loader program in "prog load" and "gen skeleton" command.")
Signed-off-by: Quentin Monnet <quentin@isovalent.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20210730215435.7095-7-quentin@isovalent.com
This commit is contained in:
Quentin Monnet 2021-07-30 22:54:34 +01:00 committed by Andrii Nakryiko
parent da87772f08
commit 8cc8c6357c
8 changed files with 96 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
tools/bpf/bpftool/Documentation/bpftool-btf.rst
View File

@ -12,7 +12,8 @@ SYNOPSIS
**bpftool** [*OPTIONS*] **btf** *COMMAND*
*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | {**-d** | **--debug** } }
*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | {**-d** | **--debug** } |
{ **-B** | **--base-btf** } }
*COMMANDS* := { **dump** | **help** }
@ -73,6 +74,20 @@ OPTIONS
=======
.. include:: common_options.rst
-B, --base-btf *FILE*
Pass a base BTF object. Base BTF objects are typically used
with BTF objects for kernel modules. To avoid duplicating
all kernel symbols required by modules, BTF objects for
modules are "split", they are built incrementally on top of
the kernel (vmlinux) BTF object. So the base BTF reference
should usually point to the kernel BTF.
When the main BTF object to process (for example, the
module BTF to dump) is passed as a *FILE*, bpftool attempts
to autodetect the path for the base object, and passing
this option is optional. When the main BTF object is passed
through other handles, this option becomes necessary.
EXAMPLES
========
**# bpftool btf dump id 1226**
@ -217,3 +232,34 @@ All the standard ways to specify map or program are supported:
**# bpftool btf dump prog tag b88e0a09b1d9759d**
**# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
|
| **# bpftool btf dump file /sys/kernel/btf/i2c_smbus**
| (or)
| **# I2C_SMBUS_ID=$(bpftool btf show -p | jq '.[] | select(.name=="i2c_smbus").id')**
| **# bpftool btf dump id ${I2C_SMBUS_ID} -B /sys/kernel/btf/vmlinux**
::
[104848] STRUCT 'i2c_smbus_alert' size=40 vlen=2
'alert' type_id=393 bits_offset=0
'ara' type_id=56050 bits_offset=256
[104849] STRUCT 'alert_data' size=12 vlen=3
'addr' type_id=16 bits_offset=0
'type' type_id=56053 bits_offset=32
'data' type_id=7 bits_offset=64
[104850] PTR '(anon)' type_id=104848
[104851] PTR '(anon)' type_id=104849
[104852] FUNC 'i2c_register_spd' type_id=84745 linkage=static
[104853] FUNC 'smbalert_driver_init' type_id=1213 linkage=static
[104854] FUNC_PROTO '(anon)' ret_type_id=18 vlen=1
'ara' type_id=56050
[104855] FUNC 'i2c_handle_smbus_alert' type_id=104854 linkage=static
[104856] FUNC 'smbalert_remove' type_id=104854 linkage=static
[104857] FUNC_PROTO '(anon)' ret_type_id=18 vlen=2
'ara' type_id=56050
'id' type_id=56056
[104858] FUNC 'smbalert_probe' type_id=104857 linkage=static
[104859] FUNC 'smbalert_work' type_id=9695 linkage=static
[104860] FUNC 'smbus_alert' type_id=71367 linkage=static
[104861] FUNC 'smbus_do_alert' type_id=84827 linkage=static

9
tools/bpf/bpftool/Documentation/bpftool-gen.rst
View File

@ -12,7 +12,8 @@ SYNOPSIS
**bpftool** [*OPTIONS*] **gen** *COMMAND*
*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } |
{ **-L** | **--use-loader** } }
*COMMAND* := { **object** | **skeleton** | **help** }
@ -152,6 +153,12 @@ OPTIONS
=======
.. include:: common_options.rst
-L, --use-loader
For skeletons, generate a "light" skeleton (also known as "loader"
skeleton). A light skeleton contains a loader eBPF program. It does
not use the majority of the libbpf infrastructure, and does not need
libelf.
EXAMPLES
========
**$ cat example1.bpf.c**

30
tools/bpf/bpftool/Documentation/bpftool-prog.rst
View File

@ -13,7 +13,8 @@ SYNOPSIS
**bpftool** [*OPTIONS*] **prog** *COMMAND*
*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } |
{ **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } }
{ **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } |
{ **-L** | **--use-loader** } }
*COMMANDS* :=
{ **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load**
@ -224,6 +225,20 @@ OPTIONS
Do not automatically attempt to mount any virtual file system
(such as tracefs or BPF virtual file system) when necessary.
-L, --use-loader
Load program as a "loader" program. This is useful to debug
the generation of such programs. When this option is in
use, bpftool attempts to load the programs from the object
file into the kernel, but does not pin them (therefore, the
*PATH* must not be provided).
When combined with the **-d**\ \|\ **--debug** option,
additional debug messages are generated, and the execution
of the loader program will use the **bpf_trace_printk**\ ()
helper to log each step of loading BTF, creating the maps,
and loading the programs (see **bpftool prog tracelog** as
a way to dump those messages).
EXAMPLES
========
**# bpftool prog show**
@ -327,3 +342,16 @@ EXAMPLES
40176203 cycles (83.05%)
42518139 instructions # 1.06 insns per cycle (83.39%)
123 llc_misses # 2.89 LLC misses per million insns (83.15%)
|
| Output below is for the trace logs.
| Run in separate terminals:
| **# bpftool prog tracelog**
| **# bpftool prog load -L -d file.o**
::
bpftool-620059 [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
bpftool-620059 [004] d... 2634685.517912: bpf_trace_printk: map_create sample_map idx 0 type 2 value_size 4 value_btf_id 0 r=6
bpftool-620059 [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
bpftool-620059 [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0

8
tools/bpf/bpftool/bash-completion/bpftool
View File

@ -260,7 +260,8 @@ _bpftool()
# Deal with options
if [[ ${words[cword]} == -* ]]; then
local c='--version --json --pretty --bpffs --mapcompat --debug'
local c='--version --json --pretty --bpffs --mapcompat --debug \
--use-loader --base-btf'
COMPREPLY=( $( compgen -W "$c" -- "$cur" ) )
return 0
fi
@ -278,7 +279,7 @@ _bpftool()
_sysfs_get_netdevs
return 0
;;
file|pinned)
file|pinned|-B|--base-btf)
_filedir
return 0
;;
@ -291,7 +292,8 @@ _bpftool()
# Remove all options so completions don't have to deal with them.
local i
for (( i=1; i < ${#words[@]}; )); do
if [[ ${words[i]::1} == - ]]; then
if [[ ${words[i]::1} == - ]] &&
[[ ${words[i]} != "-B" ]] && [[ ${words[i]} != "--base-btf" ]]; then
words=( "${words[@]:0:i}" "${words[@]:i+1}" )
[[ $i -le $cword ]] && cword=$(( cword - 1 ))
else

3
tools/bpf/bpftool/btf.c
View File

@ -981,7 +981,8 @@ static int do_help(int argc, char **argv)
" FORMAT := { raw | c }\n"
" " HELP_SPEC_MAP "\n"
" " HELP_SPEC_PROGRAM "\n"
" " HELP_SPEC_OPTIONS " }\n"
" " HELP_SPEC_OPTIONS " |\n"
" {-B|--base-btf} }\n"
"",
bin_name, "btf");

2
tools/bpf/bpftool/cgroup.c
View File

@ -502,7 +502,7 @@ static int do_help(int argc, char **argv)
" " HELP_SPEC_ATTACH_FLAGS "\n"
" " HELP_SPEC_PROGRAM "\n"
" " HELP_SPEC_OPTIONS " |\n"
" {-f|--bpffs} }
" {-f|--bpffs} }\n"
"",
bin_name, argv[-2]);

3
tools/bpf/bpftool/gen.c
View File

@ -1026,7 +1026,8 @@ static int do_help(int argc, char **argv)
" %1$s %2$s skeleton FILE [name OBJECT_NAME]\n"
" %1$s %2$s help\n"
"\n"
" " HELP_SPEC_OPTIONS " }\n"
" " HELP_SPEC_OPTIONS " |\n"
" {-L|--use-loader} }\n"
"",
bin_name, "gen");

3
tools/bpf/bpftool/prog.c
View File

@ -2260,7 +2260,8 @@ static int do_help(int argc, char **argv)
" stream_parser | flow_dissector }\n"
" METRIC := { cycles | instructions | l1d_loads | llc_misses | itlb_misses | dtlb_misses }\n"
" " HELP_SPEC_OPTIONS " |\n"
" {-f|--bpffs} | {-m|--mapcompat} | {-n|--nomount} }\n"
" {-f|--bpffs} | {-m|--mapcompat} | {-n|--nomount} |\n"
" {-L|--use-loader} }\n"
"",
bin_name, argv[-2]);