[RFC PATCH 2/2] tracing: Add documentation for event stack filter

[Sicheng Liu]

A new chapter describing how to use trace event stack
filter is added to the documentation.

Signed-off-by: Sicheng Liu <lsc2001@xxxxxxxxxxx>
---
 Documentation/trace/events.rst | 88 ++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst
index 759907c20e75..718a6d078e24 100644
--- a/Documentation/trace/events.rst
+++ b/Documentation/trace/events.rst
@@ -350,6 +350,94 @@ To add more PIDs without losing the PIDs already included, use '>>'.
 
 	# echo 123 244 1 >> set_event_pid
 
+5.6 Stack filters
+---------------------
+
+Trace events can be filtered by their call stacks.  There could exist
+various paths to tigger an trace event, but people sometimes only care
+about some of them.  Once the stack filter is set, call stack of the
+corresponding event will be compared with the stack filter.  An event
+with matched call stack will appear in the trace output and the rest will
+be discarded.
+
+5.6.1 Expression syntax
+------------------------
+
+Stack filters have the form (in regular expression style) below::
+
+  '!'?((function|'**')'/')*(function|'**')
+
+In the expression, '!' means negating the filter and '**' matches any
+call path (maybe empty).  The top of call stack will be ``stack_filter_match``,
+which means the call path will be something like ``**/stack_filter_match``.
+
+A stack filter matches if the call stack contains it, which means that
+``ret_from_fork/**/schedule`` has the same effect as
+``**/ret_from_fork/**/schedule/**``.
+
+A call stack is matched successfully if the following conditions are
+met simultaneously:
+[1] It matches any positive stack filter.
+[2] It doesn't match any negative stack filter.
+If no positive filter are set, condition 1 don't need to be satisified.
+
+5.6.2 Setting stack filters
+---------------------------
+
+Stack filters are add by echo commands to 'stack_filter' file for a given
+event, and unset by echo 0 or blank string to the same file.
+
+An usage example (on x86_64 platform):
+
+The call stack contains ``ret_from_fork`` but not ``do_syscall_64``::
+
+  # cd /sys/kernel/tracing/events/sched/sched_switch
+  # echo 'ret_from_fork' > stack_filter
+  # echo '!do_syscall_64' >> stack_filter
+  # cat stack_filter
+
+Another example (on arm64 platform):
+
+Set up a kprobe::
+
+  # echo 1 > /sys/kernel/tracing/options/stacktrace
+  # echo 'p alloc_pages' > /sys/kernel/tracing/kprobe_events
+
+The call stack contains ``copy_process``::
+
+  # echo 'copy_process' > \
+      /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter
+
+The call stack doesn't contain ``copy_process``::
+
+  # echo '!copy_process' > \
+      /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter
+
+The call stack contains ``copy_process`` or ``do_exit``,
+but not ``free_pgtables``::
+
+  # echo 'copy_process' > \
+      /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter
+  # echo 'do_exit' >> \
+      /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter
+  # echo '!free_pgtables' >> \
+      /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter
+
+The call stack contains ``invoke_syscall -> ... -> copy_process``::
+
+  # echo 'invoke_syscall/**/copy_process' > \
+      /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter
+
+Enable the kprobe event and check the trace log::
+
+  # echo 1 > /sys/kernel/tracing/events/kprobes/enable
+  # cat /sys/kernel/tracing/trace
+
+Disable the stack filter::
+
+  # echo 0 > stack_filter
+  or
+  # echo > stack_filter
 
 6. Event triggers
 =================
-- 
2.25.1