[PATCH] perf record: Add doc for bpf event selection

[PATCH] perf record: Add doc for bpf event selection

[Changbin Du]

Add document for how to pass bpf program with perf.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 tools/perf/Documentation/perf-record.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
index d232b13ea713..0925d987cad0 100644
--- a/tools/perf/Documentation/perf-record.txt
+++ b/tools/perf/Documentation/perf-record.txt
@@ -88,6 +88,19 @@ OPTIONS
           If you want to profile write accesses in [0x1000~1008), just set
           'mem:0x1000/8:w'.
 
+        - a bpf source file or object file to select events by a bpf program.
+          The bpf program can attach to variant perf events based on section
+          names.
+
+          When passing '.c', perf searches installed LLVM to compile it into
+          object file first. Optional clang options can be pased by option
+          '--clang-opt'.
+
+          perf record --clang-opt "-DLINUX_VERSION_CODE=0x50000" \
+                      -e ./tests/bpf-script-example.c
+
+          Note: '--clang-opt' must place before '--event'.
+
 	- a group of events surrounded by a pair of brace ("{event1,event2,...}").
 	  Each event is separated by commas and the group should be quoted to
 	  prevent the shell interpretation.  You also need to use --group on
-- 
2.17.1

Re: [PATCH] perf record: Add doc for bpf event selection

[Arnaldo Carvalho de Melo]

Em Fri, Feb 01, 2019 at 03:06:41AM +0000, Changbin Du escreveu:
> Add document for how to pass bpf program with perf.

That is a good start, see some comments below.
 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  tools/perf/Documentation/perf-record.txt | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
> index d232b13ea713..0925d987cad0 100644
> --- a/tools/perf/Documentation/perf-record.txt
> +++ b/tools/perf/Documentation/perf-record.txt
> @@ -88,6 +88,19 @@ OPTIONS
>            If you want to profile write accesses in [0x1000~1008), just set
>            'mem:0x1000/8:w'.
>  
> +        - a bpf source file or object file to select events by a bpf program.

             A source file (ending in .c) or a precompiled object file (ending in .o)
	     selects one or more BPF events.

> +          The bpf program can attach to variant perf events based on section
             The BPFa                      various
> +          names.
> +
> +          When passing '.c', perf searches installed LLVM to compile it into
                                             a
> +          object file first. Optional clang options can be pased by option
           an
> +          '--clang-opt'.
> +
> +          perf record --clang-opt "-DLINUX_VERSION_CODE=0x50000" \
> +                      -e ./tests/bpf-script-example.c
> +
> +          Note: '--clang-opt' must place before '--event'.

Please mention ~/.perfconfig, that needs a section in the
tools/perf/Documentation/perf-config.txt, for instance I have right now:

[root@quaco ~]# cat ~/.perfconfig
[llvm]
	dump-obj = true
	clang-opt = -g

The 'clang-opt' is the same as the command line arg you documented
above, dump object may be used to update a .o file, like:

[root@quaco ~]# vim /home/acme/git/perf/tools/perf/examples/bpf/augmented_raw_syscalls.c 
 
 # Do some changes, save

[root@quaco ~]# perf record -e /home/acme/git/perf/tools/perf/examples/bpf/augmented_raw_syscalls.c sleep 1
LLVM: dumping /home/acme/git/perf/tools/perf/examples/bpf/augmented_raw_syscalls.o
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 0.023 MB perf.data ]
[root@quaco ~]# 

And if you are up to documenting the remaining features, which I'd
encourage you, please take a look at:

tools/perf/util/llvm-utils.c

In the perf_llvm_config function. there are more things that needs
documenting, and doing a:

  git blame tools/perf/util/llvm-utils.c

Helps in getting the needed explanations, for instance, the original
patch adding the .perfconfig section was this:

git show aa61fd05ca796

And it has, for instance, among others:

            # kbuild directory. If not set, use /lib/modules/`uname -r`/build.
            # If set to "" deliberately, skip kernel header auto-detector.
            kbuild-dir = "/path/to/kernel/build"

            # Options passed to 'make' when detecting kernel header options.
            kbuild-opts = "ARCH=x86_64"

Thanks for working on documenting these features!

- Arnaldo


> +
>  	- a group of events surrounded by a pair of brace ("{event1,event2,...}").
>  	  Each event is separated by commas and the group should be quoted to
>  	  prevent the shell interpretation.  You also need to use --group on
> -- 
> 2.17.1

-- 

- Arnaldo

Re: [PATCH] perf record: Add doc for bpf event selection

[Changbin Du]

Sure, please check them in v2. Thanks!

On Fri, Feb 01, 2019 at 09:10:50AM +0100, Arnaldo Carvalho de Melo wrote:
> Em Fri, Feb 01, 2019 at 03:06:41AM +0000, Changbin Du escreveu:
> > Add document for how to pass bpf program with perf.
> 
> That is a good start, see some comments below.
>  
> > Signed-off-by: Changbin Du <changbin.du@gmail.com>
> > ---
> >  tools/perf/Documentation/perf-record.txt | 13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> > 
> > diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
> > index d232b13ea713..0925d987cad0 100644
> > --- a/tools/perf/Documentation/perf-record.txt
> > +++ b/tools/perf/Documentation/perf-record.txt
> > @@ -88,6 +88,19 @@ OPTIONS
> >            If you want to profile write accesses in [0x1000~1008), just set
> >            'mem:0x1000/8:w'.
> >  
> > +        - a bpf source file or object file to select events by a bpf program.
> 
>              A source file (ending in .c) or a precompiled object file (ending in .o)
> 	     selects one or more BPF events.
> 
> > +          The bpf program can attach to variant perf events based on section
>              The BPFa                      various
> > +          names.
> > +
> > +          When passing '.c', perf searches installed LLVM to compile it into
>                                              a
> > +          object file first. Optional clang options can be pased by option
>            an
> > +          '--clang-opt'.
> > +
> > +          perf record --clang-opt "-DLINUX_VERSION_CODE=0x50000" \
> > +                      -e ./tests/bpf-script-example.c
> > +
> > +          Note: '--clang-opt' must place before '--event'.
> 
> Please mention ~/.perfconfig, that needs a section in the
> tools/perf/Documentation/perf-config.txt, for instance I have right now:
> 
> [root@quaco ~]# cat ~/.perfconfig
> [llvm]
> 	dump-obj = true
> 	clang-opt = -g
> 
> The 'clang-opt' is the same as the command line arg you documented
> above, dump object may be used to update a .o file, like:
> 
> [root@quaco ~]# vim /home/acme/git/perf/tools/perf/examples/bpf/augmented_raw_syscalls.c 
>  
>  # Do some changes, save
> 
> [root@quaco ~]# perf record -e /home/acme/git/perf/tools/perf/examples/bpf/augmented_raw_syscalls.c sleep 1
> LLVM: dumping /home/acme/git/perf/tools/perf/examples/bpf/augmented_raw_syscalls.o
> [ perf record: Woken up 1 times to write data ]
> [ perf record: Captured and wrote 0.023 MB perf.data ]
> [root@quaco ~]# 
> 
> And if you are up to documenting the remaining features, which I'd
> encourage you, please take a look at:
> 
> tools/perf/util/llvm-utils.c
> 
> In the perf_llvm_config function. there are more things that needs
> documenting, and doing a:
> 
>   git blame tools/perf/util/llvm-utils.c
> 
> Helps in getting the needed explanations, for instance, the original
> patch adding the .perfconfig section was this:
> 
> git show aa61fd05ca796
> 
> And it has, for instance, among others:
> 
>             # kbuild directory. If not set, use /lib/modules/`uname -r`/build.
>             # If set to "" deliberately, skip kernel header auto-detector.
>             kbuild-dir = "/path/to/kernel/build"
> 
>             # Options passed to 'make' when detecting kernel header options.
>             kbuild-opts = "ARCH=x86_64"
> 
> Thanks for working on documenting these features!
> 
> - Arnaldo
> 
> 
> > +
> >  	- a group of events surrounded by a pair of brace ("{event1,event2,...}").
> >  	  Each event is separated by commas and the group should be quoted to
> >  	  prevent the shell interpretation.  You also need to use --group on
> > -- 
> > 2.17.1
> 
> -- 
> 
> - Arnaldo

-- 
Cheers,
Changbin Du