[RFC PATCH 4/4] Documentation/ftrace: Document function comm filters

[hu.shengming]

From: Shengming Hu <hu.shengming@xxxxxxxxxx>

Document set_ftrace_comm and set_ftrace_notrace_comm, including their
write and O_TRUNC behavior, accepted comm names, interaction with PID
filters, and when a task is rechecked after its comm changes.

Signed-off-by: Shengming Hu <hu.shengming@xxxxxxxxxx>
---
 Documentation/trace/ftrace.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 7261f25f8b4b..a96fc436ec16 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -313,6 +313,37 @@ of ftrace. Here is a list of some of the key files:
         If a PID is in both this file and "set_ftrace_pid", then this
         file takes precedence, and the thread will not be traced.

+  set_ftrace_comm:
+
+	Have the function and function_graph tracers trace only threads whose
+	task comm is listed in this file. Names are matched exactly and must
+	contain between 1 and TASK_COMM_LEN - 1 bytes.
+
+	Each write adds one name. A single trailing newline is ignored, while
+	embedded newlines are rejected. A zero-length write or a write containing
+	only a newline adds no entry. Duplicate entries have no effect.
+
+	Opening the file with O_TRUNC clears the filter. Otherwise, writes add
+	names to the existing filter. From a shell, use >> to add a name without
+	clearing the filter. Reading an empty filter prints `no comm`.
+
+	If both set_ftrace_pid and set_ftrace_comm contain entries, a thread must
+	match both filters to be traced.
+
+  set_ftrace_notrace_comm:
+
+	Have the function and function_graph tracers ignore threads whose task
+	comm is listed in this file. Matching and file operations have the same
+	semantics as set_ftrace_comm.
+
+	A match in either set_ftrace_notrace_pid or set_ftrace_notrace_comm
+	excludes the thread and takes precedence over all include filters.
+
+	Function-tracer task filters are evaluated when a task is scheduled in,
+	and the result is cached per CPU. Changing a filter refreshes the result
+	for currently running tasks. If a running task changes its comm, it is
+	rechecked the next time it is scheduled in.
+
   set_event_pid:

 	Have the events only trace a task with a PID listed in this file.
-- 
2.25.1