Re: [PATCH 8/8] trace_uprobe/sdt: Document about reference counter

From: Masami Hiramatsu
Date: Wed Mar 14 2018 - 09:50:35 EST


On Tue, 13 Mar 2018 18:26:03 +0530
Ravi Bangoria <ravi.bangoria@xxxxxxxxxxxxxxxxxx> wrote:

> No functionality changes.

Please consider to describe what is this change and why, here.

>
> Signed-off-by: Ravi Bangoria <ravi.bangoria@xxxxxxxxxxxxxxxxxx>
> ---
> Documentation/trace/uprobetracer.txt | 16 +++++++++++++---
> kernel/trace/trace.c | 2 +-
> 2 files changed, 14 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/trace/uprobetracer.txt b/Documentation/trace/uprobetracer.txt
> index bf526a7c..8fb13b0 100644
> --- a/Documentation/trace/uprobetracer.txt
> +++ b/Documentation/trace/uprobetracer.txt
> @@ -19,15 +19,25 @@ user to calculate the offset of the probepoint in the object.
>
> Synopsis of uprobe_tracer
> -------------------------
> - p[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a uprobe
> - r[:[GRP/]EVENT] PATH:OFFSET [FETCHARGS] : Set a return uprobe (uretprobe)
> - -:[GRP/]EVENT : Clear uprobe or uretprobe event
> + p[:[GRP/]EVENT] PATH:OFFSET[(REF_CTR_OFFSET)] [FETCHARGS]
> + r[:[GRP/]EVENT] PATH:OFFSET[(REF_CTR_OFFSET)] [FETCHARGS]

Ah, OK in this context, [] means optional syntax :)

> + -:[GRP/]EVENT
> +
> + p : Set a uprobe
> + r : Set a return uprobe (uretprobe)
> + - : Clear uprobe or uretprobe event
>
> GRP : Group name. If omitted, "uprobes" is the default value.
> EVENT : Event name. If omitted, the event name is generated based
> on PATH+OFFSET.
> PATH : Path to an executable or a library.
> OFFSET : Offset where the probe is inserted.
> + REF_CTR_OFFSET: Reference counter offset. Optional field. Reference count
> + gate the invocation of probe. If present, by default
> + reference count is 0. Kernel needs to increment it before
> + tracing the probe and decrement it when done. This is
> + identical to semaphore in Userspace Statically Defined
> + Tracepoints (USDT).
>
> FETCHARGS : Arguments. Each probe can have up to 128 args.
> %REG : Fetch register REG
> diff --git a/kernel/trace/trace.c b/kernel/trace/trace.c
> index 20a2300..2104d03 100644
> --- a/kernel/trace/trace.c
> +++ b/kernel/trace/trace.c
> @@ -4604,7 +4604,7 @@ static int tracing_trace_options_open(struct inode *inode, struct file *file)
> "place (kretprobe): [<module>:]<symbol>[+<offset>]|<memaddr>\n"
> #endif
> #ifdef CONFIG_UPROBE_EVENTS
> - "\t place: <path>:<offset>\n"
> + " place (uprobe): <path>:<offset>[(ref_ctr_offset)]\n"
> #endif
> "\t args: <name>=fetcharg[:type]\n"
> "\t fetcharg: %<register>, @<address>, @<symbol>[+|-<offset>],\n"
> --
> 1.8.3.1
>


--
Masami Hiramatsu <mhiramat@xxxxxxxxxx>