summaryrefslogtreecommitdiffstats
path: root/tools/perf/Documentation/perf-ftrace.txt
diff options
context:
space:
mode:
Diffstat (limited to 'tools/perf/Documentation/perf-ftrace.txt')
-rw-r--r--tools/perf/Documentation/perf-ftrace.txt148
1 files changed, 148 insertions, 0 deletions
diff --git a/tools/perf/Documentation/perf-ftrace.txt b/tools/perf/Documentation/perf-ftrace.txt
new file mode 100644
index 000000000..df4595563
--- /dev/null
+++ b/tools/perf/Documentation/perf-ftrace.txt
@@ -0,0 +1,148 @@
+perf-ftrace(1)
+==============
+
+NAME
+----
+perf-ftrace - simple wrapper for kernel's ftrace functionality
+
+
+SYNOPSIS
+--------
+[verse]
+'perf ftrace' {trace|latency} <command>
+
+DESCRIPTION
+-----------
+The 'perf ftrace' command provides a collection of subcommands which use
+kernel's ftrace infrastructure.
+
+ 'perf ftrace trace' is a simple wrapper of the ftrace. It only supports
+ single thread tracing currently and just reads trace_pipe in text and then
+ write it to stdout.
+
+ 'perf ftrace latency' calculates execution latency of a given function
+ (optionally with BPF) and display it as a histogram.
+
+The following options apply to perf ftrace.
+
+COMMON OPTIONS
+--------------
+
+-p::
+--pid=::
+ Trace on existing process id (comma separated list).
+
+--tid=::
+ Trace on existing thread id (comma separated list).
+
+-a::
+--all-cpus::
+ Force system-wide collection. Scripts run without a <command>
+ normally use -a by default, while scripts run with a <command>
+ normally don't - this option allows the latter to be run in
+ system-wide mode.
+
+-C::
+--cpu=::
+ Only trace for the list of CPUs provided. Multiple CPUs can
+ be provided as a comma separated list with no space like: 0,1.
+ Ranges of CPUs are specified with -: 0-2.
+ Default is to trace on all online CPUs.
+
+-v::
+--verbose::
+ Increase the verbosity level.
+
+
+OPTIONS for 'perf ftrace trace'
+-------------------------------
+
+-t::
+--tracer=::
+ Tracer to use when neither -G nor -F option is not
+ specified: function_graph or function.
+
+-F::
+--funcs::
+ List available functions to trace. It accepts a pattern to
+ only list interested functions.
+
+-D::
+--delay::
+ Time (ms) to wait before starting tracing after program start.
+
+-m::
+--buffer-size::
+ Set the size of per-cpu tracing buffer, <size> is expected to
+ be a number with appended unit character - B/K/M/G.
+
+--inherit::
+ Trace children processes spawned by our target.
+
+-T::
+--trace-funcs=::
+ Select function tracer and set function filter on the given
+ function (or a glob pattern). Multiple functions can be given
+ by using this option more than once. The function argument also
+ can be a glob pattern. It will be passed to 'set_ftrace_filter'
+ in tracefs.
+
+-N::
+--notrace-funcs=::
+ Select function tracer and do not trace functions given by the
+ argument. Like -T option, this can be used more than once to
+ specify multiple functions (or glob patterns). It will be
+ passed to 'set_ftrace_notrace' in tracefs.
+
+--func-opts::
+ List of options allowed to set:
+ call-graph - Display kernel stack trace for function tracer.
+ irq-info - Display irq context info for function tracer.
+
+-G::
+--graph-funcs=::
+ Select function_graph tracer and set graph filter on the given
+ function (or a glob pattern). This is useful to trace for
+ functions executed from the given function. This can be used more
+ than once to specify multiple functions. It will be passed to
+ 'set_graph_function' in tracefs.
+
+-g::
+--nograph-funcs=::
+ Select function_graph tracer and set graph notrace filter on the
+ given function (or a glob pattern). Like -G option, this is useful
+ for the function_graph tracer only and disables tracing for function
+ executed from the given function. This can be used more than once to
+ specify multiple functions. It will be passed to 'set_graph_notrace'
+ in tracefs.
+
+--graph-opts::
+ List of options allowed to set:
+ nosleep-time - Measure on-CPU time only for function_graph tracer.
+ noirqs - Ignore functions that happen inside interrupt.
+ verbose - Show process names, PIDs, timestamps, etc.
+ thresh=<n> - Setup trace duration threshold in microseconds.
+ depth=<n> - Set max depth for function graph tracer to follow.
+
+
+OPTIONS for 'perf ftrace latency'
+---------------------------------
+
+-T::
+--trace-funcs=::
+ Set the function name to get the histogram. Unlike perf ftrace trace,
+ it only allows single function to calculate the histogram.
+
+-b::
+--use-bpf::
+ Use BPF to measure function latency instead of using the ftrace (it
+ uses function_graph tracer internally).
+
+-n::
+--use-nsec::
+ Use nano-second instead of micro-second as a base unit of the histogram.
+
+
+SEE ALSO
+--------
+linkperf:perf-record[1], linkperf:perf-trace[1]