Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 263ee775 authored by Changbin Du's avatar Changbin Du Committed by Jonathan Corbet
Browse files

trace doc: convert trace/kprobetrace.txt to rst format 



This converts the plain text documentation to reStructuredText format and
add it into Sphinx TOC tree. No essential content change.

Cc: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: default avatarChangbin Du <changbin.du@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 1f198e22

Documentation/trace/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -9,3 +9,4 @@ Linux Tracing Technologies 
   tracepoint-analysis

   ftrace

   ftrace-uses

   kprobetrace

Documentation/trace/kprobetrace.txt→Documentation/trace/kprobetrace.rst

+54 −46
Original line number Diff line number Diff line 
==========================

Kprobe-based Event Tracing

==========================



                 Documentation is written by Masami Hiramatsu



:Author: Masami Hiramatsu



Overview

--------
@@ -23,6 +23,8 @@ current_tracer. Instead of that, add probe points via 


Synopsis of kprobe_events

-------------------------

::



  p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS]	: Set a probe

  r[MAXACTIVE][:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS]	: Set a return probe

  -:[GRP/]EVENT						: Clear a probe
@@ -66,7 +68,7 @@ String type is a special type, which fetches a "null-terminated" string from 
kernel space. This means it will fail and store NULL if the string container

has been paged out.

Bitfield is another special type, which takes 3 parameters, bit-width, bit-

offset, and container-size (usually 32). The syntax is;

offset, and container-size (usually 32). The syntax is::



 b<bit-width>@<bit-offset>/<container-size>
@@ -105,7 +107,7 @@ the third is the number of probe miss-hits. 
Usage examples

--------------

To add a probe as a new event, write a new definition to kprobe_events

as below.

as below::



  echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events
@@ -115,6 +117,7 @@ assigned to each function argument depends on arch-specific ABI. If you unsure 
the ABI, please try to use probe subcommand of perf-tools (you can find it

under tools/perf/).

As this example shows, users can choose more familiar names for each arguments.

::



  echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events
@@ -122,6 +125,7 @@ As this example shows, users can choose more familiar names for each arguments. 
recording return value as "myretprobe" event.

You can see the format of these events via

/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.

::



  cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format

  name: myprobe
@@ -144,12 +148,14 @@ print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip, 
  REC->dfd, REC->filename, REC->flags, REC->mode



You can see that the event has 4 arguments as in the expressions you specified.

::



  echo > /sys/kernel/debug/tracing/kprobe_events



This clears all probe points.



Or,

::



  echo -:myprobe >> kprobe_events
@@ -157,11 +163,13 @@ REC->dfd, REC->filename, REC->flags, REC->mode 


Right after definition, each event is disabled by default. For tracing these

events, you need to enable it.

::



  echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable

  echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable



And you can see the traced information via /sys/kernel/debug/tracing/trace.

::



  cat /sys/kernel/debug/tracing/trace

  # tracer: nop