lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Date:   Wed, 24 Apr 2019 17:21:03 +0000
From:   Yonghong Song <yhs@...com>
To:     "andrii.nakryiko@...il.com" <andrii.nakryiko@...il.com>,
        Kernel Team <Kernel-team@...com>,
        "netdev@...r.kernel.org" <netdev@...r.kernel.org>,
        "bpf@...r.kernel.org" <bpf@...r.kernel.org>,
        Alexei Starovoitov <ast@...com>,
        "daniel@...earbox.net" <daniel@...earbox.net>,
        Song Liu <songliubraving@...com>, Martin Lau <kafai@...com>,
        "acme@...nel.org" <acme@...nel.org>
CC:     Andrii Nakryiko <andriin@...com>,
        Arnaldo Carvalho de Melo <acme@...hat.com>
Subject: Re: [PATCH bpf-next 2/2] bpftool/docs: add btf sub-command
 documentation



On 4/23/19 10:22 PM, andrii.nakryiko@...il.com wrote:
> From: Andrii Nakryiko <andriin@...com>
> 
> Document usage and sample output format for `btf dump` sub-command.

When applying the patch, I see a few trailing spaces.

===
p2.txt:113: trailing whitespace.

p2.txt:118: trailing whitespace.

p2.txt:120: trailing whitespace.

p2.txt:129: trailing whitespace.

p2.txt:134: trailing whitespace.
===

You may want to take a look.

Could you add bash completion as well?

> 
> Cc: Daniel Borkmann <daniel@...earbox.net>
> Cc: Alexei Starovoitov <ast@...com>
> Cc: Yonghong Song <yhs@...com>
> Cc: Martin KaFai Lau <kafai@...com>
> Cc: Song Liu <songliubraving@...com>
> Cc: Arnaldo Carvalho de Melo <acme@...hat.com>
> Signed-off-by: Andrii Nakryiko <andriin@...com>
> ---
>   .../bpf/bpftool/Documentation/bpftool-btf.rst | 205 ++++++++++++++++++
>   .../bpftool/Documentation/bpftool-cgroup.rst  |   3 +-
>   .../bpftool/Documentation/bpftool-feature.rst |   3 +-
>   .../bpf/bpftool/Documentation/bpftool-map.rst |   3 +-
>   .../bpf/bpftool/Documentation/bpftool-net.rst |   3 +-
>   .../bpftool/Documentation/bpftool-perf.rst    |   3 +-
>   .../bpftool/Documentation/bpftool-prog.rst    |   3 +-
>   tools/bpf/bpftool/Documentation/bpftool.rst   |   3 +-
>   8 files changed, 219 insertions(+), 7 deletions(-)
>   create mode 100644 tools/bpf/bpftool/Documentation/bpftool-btf.rst
> 
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-btf.rst b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> new file mode 100644
> index 000000000000..955aaaba93a0
> --- /dev/null
> +++ b/tools/bpf/bpftool/Documentation/bpftool-btf.rst
> @@ -0,0 +1,205 @@
> +================
> +bpftool-btf
> +================
> +-------------------------------------------------------------------------------
> +tool for inspection of BTF data
> +-------------------------------------------------------------------------------
> +
> +:Manual section: 8
> +
> +SYNOPSIS
> +========
> +
> +	**bpftool** [*OPTIONS*] **btf** *COMMAND*
> +
> +	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
> +
> +	*COMMANDS* :=
> +	{ **dump** | **help** }
> +
> +MAP COMMANDS
> +=============
> +
> +|	**bpftool** **btf dump**       *BTF_SRC*
> +|	**bpftool** **btf help**
> +|
> +|	*BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
> +|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
> +|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
> +
> +DESCRIPTION
> +===========
> +	**bpftool map dump**    *MAP*
> +		  Dump BTF entries from a given *BTF_SRC*.
> +
> +	**bpftool map help**
> +		  Print short help message.
> +
> +OPTIONS
> +=======
> +	-h, --help
> +		  Print short generic help message (similar to **bpftool help**).
> +
> +	-V, --version
> +		  Print version number (similar to **bpftool version**).
> +
> +	-j, --json
> +		  Generate JSON output. For commands that cannot produce JSON, this
> +		  option has no effect.
> +
> +	-p, --pretty
> +		  Generate human-readable JSON output. Implies **-j**.
> +
> +EXAMPLES
> +========
> +**# bpftool btf dump id 1226**
> +::
> +
> +  [1] PTR '(anon)' type_id=2
> +  [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
> +          'pad' type_id=3 bits_offset=0
> +          'sock' type_id=4 bits_offset=64
> +  [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
> +  [4] PTR '(anon)' type_id=5
> +  [5] FWD 'sock' fwd_kind=union
> +
> +This gives an example of default output for all supported BTF kinds.
> +
> +**$ cat prog.c**
> +::
> +
> +  struct fwd_struct;
> +
> +  enum my_enum {
> +          VAL1 = 3,
> +          VAL2 = 7,
> +  };
> +
> +  typedef struct my_struct my_struct_t;
> +
> +  struct my_struct {
> +          const unsigned int const_int_field;
> +          int bitfield_field: 4;
> +          char arr_field[16];
> +          const struct fwd_struct *restrict fwd_field;
> +          enum my_enum enum_field;
> +          volatile my_struct_t *typedef_ptr_field;
> +  };
> +
> +  union my_union {
> +          int a;
> +          struct my_struct b;
> +  };
> +
> +  struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
> +          .bitfield_field = 3,
> +          .enum_field = VAL1,
> +  };
> +  int global_var __attribute__((section("data_sec"))) = 7;
> +
> +  __attribute__((noinline))
> +  int my_func(union my_union *arg1, int arg2)
> +  {
> +          static int static_var __attribute__((section("data_sec"))) = 123;
> +          static_var++;
> +          return static_var;
> +  }
> +
> +**$ bpftool btf dump file prog.o**
> +::
> +
> +  [1] PTR '(anon)' type_id=2
> +  [2] UNION 'my_union' size=48 vlen=2
> +          'a' type_id=3 bits_offset=0
> +          'b' type_id=4 bits_offset=0
> +  [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
> +  [4] STRUCT 'my_struct' size=48 vlen=6
> +          'const_int_field' type_id=5 bits_offset=0
> +          'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
> +          'arr_field' type_id=8 bits_offset=40
> +          'fwd_field' type_id=10 bits_offset=192
> +          'enum_field' type_id=14 bits_offset=256
> +          'typedef_ptr_field' type_id=15 bits_offset=320
> +  [5] CONST '(anon)' type_id=6
> +  [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
> +  [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
> +  [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
> +  [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
> +  [10] RESTRICT '(anon)' type_id=11
> +  [11] PTR '(anon)' type_id=12
> +  [12] CONST '(anon)' type_id=13
> +  [13] FWD 'fwd_struct' fwd_kind=union
> +  [14] ENUM 'my_enum' size=4 vlen=2
> +          'VAL1' val=3
> +          'VAL2' val=7
> +  [15] PTR '(anon)' type_id=16
> +  [16] VOLATILE '(anon)' type_id=17
> +  [17] TYPEDEF 'my_struct_t' type_id=4
> +  [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
> +          'arg1' type_id=1
> +          'arg2' type_id=3
> +  [19] FUNC 'my_func' type_id=18
> +  [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
> +  [21] VAR 'global_var' type_id=3, linkage=global-alloc
> +  [22] VAR 'my_func.static_var' type_id=3, linkage=static
> +  [23] DATASEC 'data_sec' size=0 vlen=3
> +          type_id=20 offset=0 size=48
> +          type_id=21 offset=0 size=4
> +          type_id=22 offset=52 size=4
> +
> +The following commands print BTF types associated with specified map's key,
> +value, both key and value, and all BTF types, respectively. By default, both
> +key and value types will be printed.
> +
> +**# bpftool btf dump map id 123 key**
> +
> +::
> +
> +  [39] TYPEDEF 'u32' type_id=37
> +
> +**# bpftool btf dump map id 123 value**
> +
> +::
> +
> +  [86] PTR '(anon)' type_id=87
> +
> +**# bpftool btf dump map id 123 kv**
> +
> +::
> +
> +  [39] TYPEDEF 'u32' type_id=37
> +  [86] PTR '(anon)' type_id=87
> +
> +**# bpftool btf dump map id 123 all**
> +
> +::
> +
> +  [1] PTR '(anon)' type_id=0
> +  .
> +  .
> +  .
> +  [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
> +
> +All the standard ways to specify map or program is supported:
> +
> +**# bpftool btf dump map id 123**
> +
> +**# bpftool btf dump map pinned /sys/fs/bpf/map_name**
> +
> +**# bpftool btf dump prog id 456**
> +
> +**# bpftool btf dump prog tag b88e0a09b1d9759d**
> +
> +**# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
> +
> +SEE ALSO
> +========
> +	**bpf**\ (2),
> +	**bpf-helpers**\ (7),
> +	**bpftool**\ (8),
> +	**bpftool-map**\ (8),
> +	**bpftool-prog**\ (8),
> +	**bpftool-cgroup**\ (8),
> +	**bpftool-feature**\ (8),
> +	**bpftool-net**\ (8),
> +	**bpftool-perf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
> index 89b6b10e2183..ac26876389c2 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-cgroup.rst
> @@ -145,4 +145,5 @@ SEE ALSO
>   	**bpftool-map**\ (8),
>   	**bpftool-feature**\ (8),
>   	**bpftool-net**\ (8),
> -	**bpftool-perf**\ (8)
> +	**bpftool-perf**\ (8),
> +	**bpftool-btf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-feature.rst b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
> index 10177343b7ce..14180e887082 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-feature.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-feature.rst
> @@ -82,4 +82,5 @@ SEE ALSO
>   	**bpftool-map**\ (8),
>   	**bpftool-cgroup**\ (8),
>   	**bpftool-net**\ (8),
> -	**bpftool-perf**\ (8)
> +	**bpftool-perf**\ (8),
> +	**bpftool-btf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-map.rst b/tools/bpf/bpftool/Documentation/bpftool-map.rst
> index 55ecf80ca03e..13ef27b39f20 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-map.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-map.rst
> @@ -258,4 +258,5 @@ SEE ALSO
>   	**bpftool-cgroup**\ (8),
>   	**bpftool-feature**\ (8),
>   	**bpftool-net**\ (8),
> -	**bpftool-perf**\ (8)
> +	**bpftool-perf**\ (8),
> +	**bpftool-btf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-net.rst b/tools/bpf/bpftool/Documentation/bpftool-net.rst
> index 6b692b428373..934580850f42 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-net.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-net.rst
> @@ -143,4 +143,5 @@ SEE ALSO
>   	**bpftool-map**\ (8),
>   	**bpftool-cgroup**\ (8),
>   	**bpftool-feature**\ (8),
> -	**bpftool-perf**\ (8)
> +	**bpftool-perf**\ (8),
> +	**bpftool-btf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-perf.rst b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
> index 86154740fabb..0c7576523a21 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-perf.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-perf.rst
> @@ -85,4 +85,5 @@ SEE ALSO
>   	**bpftool-map**\ (8),
>   	**bpftool-cgroup**\ (8),
>   	**bpftool-feature**\ (8),
> -	**bpftool-net**\ (8)
> +	**bpftool-net**\ (8),
> +	**bpftool-btf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool-prog.rst b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
> index 2f183ffd8351..e8118544d118 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool-prog.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool-prog.rst
> @@ -271,4 +271,5 @@ SEE ALSO
>   	**bpftool-cgroup**\ (8),
>   	**bpftool-feature**\ (8),
>   	**bpftool-net**\ (8),
> -	**bpftool-perf**\ (8)
> +	**bpftool-perf**\ (8),
> +	**bpftool-btf**\ (8)
> diff --git a/tools/bpf/bpftool/Documentation/bpftool.rst b/tools/bpf/bpftool/Documentation/bpftool.rst
> index deb2ca911ddf..3e562d7fd56f 100644
> --- a/tools/bpf/bpftool/Documentation/bpftool.rst
> +++ b/tools/bpf/bpftool/Documentation/bpftool.rst
> @@ -76,4 +76,5 @@ SEE ALSO
>   	**bpftool-cgroup**\ (8),
>   	**bpftool-feature**\ (8),
>   	**bpftool-net**\ (8),
> -	**bpftool-perf**\ (8)
> +	**bpftool-perf**\ (8),
> +	**bpftool-btf**\ (8)
> 

Powered by blists - more mailing lists