Re: [PATCH v2 2/2] Documentation: tracing: Add documentation about eprobes

[Randy Dunlap <rdunlap@infradead.org>]

Hi Steven,


On 7/29/25 9:18 AM, Steven Rostedt wrote:
> From: Steven Rostedt <rostedt@goodmis.org>
> 
> Eprobes was added back in 5.15, but was never documented. It became a
> "secret" interface even though it has been a topic of several
> presentations. For some reason, when eprobes was added, documenting it
> never became a priority, until now.
> 
> Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
> ---
> Changes since v1: https://lore.kernel.org/20250728171522.7d54e116@batman.local.home
> 
> - Renamed to eprobetrace.rst (Masami Hiramatsu)
> 
> - Fixed title of document (Masami Hiramatsu)
> 
> - Fixed grammar and spellings (Randy Dunlap)
> 
>  Documentation/trace/eprobetrace.rst | 269 ++++++++++++++++++++++++++++
>  Documentation/trace/index.rst       |   1 +
>  2 files changed, 270 insertions(+)
>  create mode 100644 Documentation/trace/eprobetrace.rst
> 
> diff --git a/Documentation/trace/eprobetrace.rst b/Documentation/trace/eprobetrace.rst
> new file mode 100644
> index 000000000000..6d8946983466
> --- /dev/null
> +++ b/Documentation/trace/eprobetrace.rst
> @@ -0,0 +1,269 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==================================
> +Eprobe - Event-based Probe Tracing
> +==================================
> +
> +:Author: Steven Rostedt <rostedt@goodmis.org>
> +
> +- Written for v6.17
> +
> +Overview
> +========
> +
> +Eprobes are dynamic events that are placed on existing events to either
> +dereference a field that is a pointer, or simply to limit what fields are
> +recorded in the trace event.
> +
> +Eprobes depend on kprobe events so to enable this feature; build your kernel

I mucked that one up also. :(
Please s/;/,/ above. Sorry.


> +with CONFIG_EPROBE_EVENTS=y.
> +
> +Eprobes are created via the /sys/kernel/tracing/dynamic_events file.
> +
> +Synopsis of eprobe_events
> +-------------------------
> +::
> +
> +  e[:[EGRP/][EEVENT]] GRP.EVENT [FETCHARGS]	: Set a probe
> +  -:[EGRP/][EEVENT]				: Clear a probe
> +
> + EGRP		: Group name of the new event. If omitted, use "eprobes" for it.
> + EEVENT		: Event name. If omitted, the event name is generated and will
> +		  be the same event name as the event it attached to.
> + GRP		: Group name of the event to attach to.
> + EVENT		: Event name of the event to attach to.
> +
> + FETCHARGS	: Arguments. Each probe can have up to 128 args.
> +  $FIELD	: Fetch the value of the event field called FIELD.
> +  @ADDR		: Fetch memory at ADDR (ADDR should be in kernel)
> +  @SYM[+|-offs]	: Fetch memory at SYM +|- offs (SYM should be a data symbol)
> +  $comm		: Fetch current task comm.
> +  +|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*3)(\*4)
> +  \IMM		: Store an immediate value to the argument.
> +  NAME=FETCHARG : Set NAME as the argument name of FETCHARG.
> +  FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types
> +		  (u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types
> +		  (x8/x16/x32/x64), VFS layer common type(%pd/%pD), "char",
> +                  "string", "ustring", "symbol", "symstr" and "bitfield" are
> +                  supported.
> +
> +Types
> +-----
> +The FETCHARGS above is very similar to the kprobe events as described in
> +Documentation/trace/kprobetrace.rst.
> +
> +The difference between eprobes and kprobes FETCHARGS is that eprobes has a
> +$FIELD command that returns the content of the event field of the event
> +that is attached. Eprobes do not have access to registers, stacks and function
> +arguments that kprobes has.
> +
> +If a field argument is a pointer, it may be dereferenced just like a memory
> +address using the FETCHARGS syntax.
> +
> +
> +Attaching to dynamic events
> +---------------------------
> +
> +Eprobes may attach to dynamic events as well as to normal events. It may
> +attach to a kprobe event, a synthetic event or a fprobe event. This is useful

                                                  an fprobe event.

> +if the type of a field needs to be changed. See Example 2 below.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

-- 
~Randy