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

[Randy Dunlap]

Hi,

On 8/30/26 4:12 AM, hu.shengming@xxxxxxxxxx wrote:
> 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

Is there a way to clear the filter from (in) a shell script?

> +	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.

-- 
~Randy