Re: [PATCH v3 1/5] docs: tracing: fprobe: document list filters and :entry/:exit

[Masami Hiramatsu (Google) <mhiramat@kernel.org>]

On Sun,  5 Oct 2025 08:46:55 +0900
Ryan Chung <seokwoo.chung130@gmail.com> wrote:

> Signed-off-by: Ryan Chung <seokwoo.chung130@gmail.com>
> ---
>  Documentation/trace/fprobetrace.rst | 27 +++++++++++++++++++++------
>  1 file changed, 21 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/trace/fprobetrace.rst b/Documentation/trace/fprobetrace.rst
> index b4c2ca3d02c1..629e2d7402bd 100644
> --- a/Documentation/trace/fprobetrace.rst
> +++ b/Documentation/trace/fprobetrace.rst
> @@ -25,21 +25,36 @@ Synopsis of fprobe-events
>  -------------------------
>  ::
>  
> -  f[:[GRP1/][EVENT1]] SYM [FETCHARGS]                       : Probe on function entry
> -  f[MAXACTIVE][:[GRP1/][EVENT1]] SYM%return [FETCHARGS]     : Probe on function exit
> -  t[:[GRP2/][EVENT2]] TRACEPOINT [FETCHARGS]                : Probe on tracepoint
> +  # fprobe (function entry/exit)
> +  f[:[GRP1/][EVENT1]] SYM_OR_LIST[:entry|:exit] [FETCHARGS]
> +
> +  # legacy single-symbol exit
> +  f[MAXACTIVE][:[GRP1/][EVENT1]] SYM%return [FETCHARGS]
> +
> +  # Probe on tracepoint
> +  t[:[GRP2/][EVENT2]] TRACEPOINT [FETCHARGS]
>  
>   GRP1           : Group name for fprobe. If omitted, use "fprobes" for it.
>   GRP2           : Group name for tprobe. If omitted, use "tracepoints" for it.
> - EVENT1         : Event name for fprobe. If omitted, the event name is
> -                  "SYM__entry" or "SYM__exit".
> + EVENT1         : Event name for fprobe. If omitted,
> +                  - For a single literal symbol, the event name is
> +                    "SYM__entry" or "SYM__exit".
> +                  - For a *list or any wildcard*, an explicit [GRP1/][EVENT1]
> +                    is required; otherwise the parser rejects it.
>   EVENT2         : Event name for tprobe. If omitted, the event name is
>                    the same as "TRACEPOINT", but if the "TRACEPOINT" starts
>                    with a digit character, "_TRACEPOINT" is used.
>   MAXACTIVE      : Maximum number of instances of the specified function that
>                    can be probed simultaneously, or 0 for the default value
>                    as defined in Documentation/trace/fprobe.rst
> -
> + SYM_OR_LIST    : Either a single symbol, or a comma-separated list of
> +                  include/exclude patterns:
> +                  - Tokens are matched as symbols; wildcards may be used.
> +                  - Tokens prefixed with '!' are exclusions.
> +                  - Examples:
> +                        foo             # single literal (entry)
> +                        foo:exit        # single literal exit
> +                        foo%return      # legacy single-symbol exit

So you can explain it in syntax formats:

Single function (including wildcard):

  f[:[GRP1/][EVENT1]] SYM[%return] [FETCHARGS]

Multiple functions:

  f[:[GRP1/]EVENT3 SYM[,[!]SYM[,...]][:entry|:exit] [FETCHARGS]

Where,
 - SYM prefixed with '!' are exclusions.
 - ":entry" suffix means it probes entry of given symbols. (default)
 - ":exit" suffix means it probes exit of given symbols.
 - "%return" suffix means it probes exit of SYM (single symbol).

Thank you,


>   FETCHARGS      : Arguments. Each probe can have up to 128 args.
>    ARG           : Fetch "ARG" function argument using BTF (only for function
>                    entry or tracepoint.) (\*1)
> -- 
> 2.43.0
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>