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

Commit c1043fcd authored by Hiraku Toyooka's avatar Hiraku Toyooka Committed by Steven Rostedt
Browse files

tracing: Add documentation of snapshot utility 

This patch adds snapshot description in ftrace documentation.
This description includes what the snapshot is and how to use it.

Link: http://lkml.kernel.org/r/20121226025309.3252.150.stgit@liselsia



Cc: Rob Landley <rob@landley.net>
Signed-off-by: default avatarHiraku Toyooka <hiraku.toyooka.gu@hitachi.com>
Signed-off-by: default avatarSteven Rostedt <rostedt@goodmis.org>
parent debdd57f

Documentation/trace/ftrace.txt

+83 −0
Original line number Diff line number Diff line
@@ -1842,6 +1842,89 @@ an error. 
 # cat buffer_size_kb

85



Snapshot

--------

CONFIG_TRACER_SNAPSHOT makes a generic snapshot feature

available to all non latency tracers. (Latency tracers which

record max latency, such as "irqsoff" or "wakeup", can't use

this feature, since those are already using the snapshot

mechanism internally.)



Snapshot preserves a current trace buffer at a particular point

in time without stopping tracing. Ftrace swaps the current

buffer with a spare buffer, and tracing continues in the new

current (=previous spare) buffer.



The following debugfs files in "tracing" are related to this

feature:



  snapshot:



	This is used to take a snapshot and to read the output

	of the snapshot. Echo 1 into this file to allocate a

	spare buffer and to take a snapshot (swap), then read

	the snapshot from this file in the same format as

	"trace" (described above in the section "The File

	System"). Both reads snapshot and tracing are executable

	in parallel. When the spare buffer is allocated, echoing

	0 frees it, and echoing else (positive) values clear the

	snapshot contents.

	More details are shown in the table below.



	status\input  |     0      |     1      |    else    |

	--------------+------------+------------+------------+

	not allocated |(do nothing)| alloc+swap |   EINVAL   |

	--------------+------------+------------+------------+

	allocated     |    free    |    swap    |   clear    |

	--------------+------------+------------+------------+



Here is an example of using the snapshot feature.



 # echo 1 > events/sched/enable

 # echo 1 > snapshot

 # cat snapshot

# tracer: nop

#

# entries-in-buffer/entries-written: 71/71   #P:8

#

#                              _-----=> irqs-off

#                             / _----=> need-resched

#                            | / _---=> hardirq/softirq

#                            || / _--=> preempt-depth

#                            ||| /     delay

#           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION

#              | |       |   ||||       |         |

          <idle>-0     [005] d...  2440.603828: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2242 next_prio=120

           sleep-2242  [005] d...  2440.603846: sched_switch: prev_comm=snapshot-test-2 prev_pid=2242 prev_prio=120 prev_state=R ==> next_comm=kworker/5:1 next_pid=60 next_prio=120

[...]

          <idle>-0     [002] d...  2440.707230: sched_switch: prev_comm=swapper/2 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2229 next_prio=120



 # cat trace

# tracer: nop

#

# entries-in-buffer/entries-written: 77/77   #P:8

#

#                              _-----=> irqs-off

#                             / _----=> need-resched

#                            | / _---=> hardirq/softirq

#                            || / _--=> preempt-depth

#                            ||| /     delay

#           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION

#              | |       |   ||||       |         |

          <idle>-0     [007] d...  2440.707395: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=snapshot-test-2 next_pid=2243 next_prio=120

 snapshot-test-2-2229  [002] d...  2440.707438: sched_switch: prev_comm=snapshot-test-2 prev_pid=2229 prev_prio=120 prev_state=S ==> next_comm=swapper/2 next_pid=0 next_prio=120

[...]





If you try to use this snapshot feature when current tracer is

one of the latency tracers, you will get the following results.



 # echo wakeup > current_tracer

 # echo 1 > snapshot

bash: echo: write error: Device or resource busy

 # cat snapshot

cat: snapshot: Device or resource busy



-----------



More details can be found in the source code, in the