perf record: Add support for using symbols in address filters

Symbols come from either the DSO or /proc/kallsyms for the kernel.
Details of the functionality can be found in Documentation/perf-record.txt.

Signed-off-by: Adrian Hunter <adrian.hunter@intel.com>
Cc: Jiri Olsa <jolsa@redhat.com>
Cc: Masami Hiramatsu <mhiramat@kernel.org>
Cc: Mathieu Poirier <mathieu.poirier@linaro.org>
Link: http://lkml.kernel.org/r/1474641528-18776-8-git-send-email-adrian.hunter@intel.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

1 files changed, 54 insertions, 1 deletions

diff --git a/tools/perf/Documentation/perf-record.txt b/tools/perf/Documentation/perf-record.txt
index babbb63e6d9d..92335193dc33 100644
--- a/tools/perf/Documentation/perf-record.txt
+++ b/tools/perf/Documentation/perf-record.txt
@@ -89,9 +89,62 @@ OPTIONS
 
 --filter=<filter>::
         Event filter. This option should follow a event selector (-e) which
-        selects tracepoint event(s). Multiple '--filter' options are combined
+        selects either tracepoint event(s) or a hardware trace PMU
+        (e.g. Intel PT or CoreSight).
+
+        - tracepoint filters
+
+        In the case of tracepoints, multiple '--filter' options are combined
         using '&&'.
 
+        - address filters
+
+        A hardware trace PMU advertises its ability to accept a number of
+        address filters by specifying a non-zero value in
+        /sys/bus/event_source/devices/<pmu>/nr_addr_filters.
+
+        Address filters have the format:
+
+        filter|start|stop|tracestop <start> [/ <size>] [@<file name>]
+
+        Where:
+        - 'filter': defines a region that will be traced.
+        - 'start': defines an address at which tracing will begin.
+        - 'stop': defines an address at which tracing will stop.
+        - 'tracestop': defines a region in which tracing will stop.
+
+        <file name> is the name of the object file, <start> is the offset to the
+        code to trace in that file, and <size> is the size of the region to
+        trace. 'start' and 'stop' filters need not specify a <size>.
+
+        If no object file is specified then the kernel is assumed, in which case
+        the start address must be a current kernel memory address.
+
+        <start> can also be specified by providing the name of a symbol. If the
+        symbol name is not unique, it can be disambiguated by inserting #n where
+        'n' selects the n'th symbol in address order. Alternately #0, #g or #G
+        select only a global symbol. <size> can also be specified by providing
+        the name of a symbol, in which case the size is calculated to the end
+        of that symbol. For 'filter' and 'tracestop' filters, if <size> is
+        omitted and <start> is a symbol, then the size is calculated to the end
+        of that symbol.
+
+        If <size> is omitted and <start> is '*', then the start and size will
+        be calculated from the first and last symbols, i.e. to trace the whole
+        file.
+
+        If symbol names (or '*') are provided, they must be surrounded by white
+        space.
+
+        The filter passed to the kernel is not necessarily the same as entered.
+        To see the filter that is passed, use the -v option.
+
+        The kernel may not be able to configure a trace region if it is not
+        within a single mapping.  MMAP events (or /proc/<pid>/maps) can be
+        examined to determine if that is a possibility.
+
+        Multiple filters can be separated with space or comma.
+
 --exclude-perf::
         Don't record events issued by perf itself. This option should follow
         a event selector (-e) which selects tracepoint event(s). It adds a