ftrace: document updates

The following updates were recommended by Elias Oltmanns and Randy Dunlap.

[ updates based on Andrew Morton's comments are still to come. ]

Signed-off-by: Steven Rostedt <[e-mail]>
Signed-off-by: Linus Torvalds <[e-mail]>

Documentation/ftrace.txt

···
 		========================
 
 Copyright 2008 Red Hat Inc.
-Author: Steven Rostedt <[e-mail]>
+   Author:   Steven Rostedt <[e-mail]>
+  License:   The GNU Free Documentation License, Version 1.2
+Reviewers:   Elias Oltmanns and Randy Dunlap
 
+Writen for: 2.6.26-rc8 linux-2.6-tip.git tip/tracing/ftrace branch
 
 Introduction
 ------------
···
 		that is configured.
 
   available_tracers : This holds the different types of tracers that
-		has been compiled into the kernel. The tracers
+		have been compiled into the kernel. The tracers
 		listed here can be configured by echoing in their
 		name into current_tracer.
 
···
   trace_entries : This sets or displays the number of trace
 		entries each CPU buffer can hold. The tracer buffers
 		are the same size for each CPU, so care must be
-		taken when modifying the trace_entries. The number
-		of actually entries will be the number given
-		times the number of possible CPUS. The buffers
-		are saved as individual pages, and the actual entries
-		will always be rounded up to entries per page.
+		taken when modifying the trace_entries. The trace
+		buffers are allocated in pages (blocks of memory that
+		the kernel uses for allocation, usually 4 KB in size).
+		Since each entry is smaller than a page, if the last
+		allocated page has room for more entries than were
+		requested, the rest of the page is used to allocate
+		entries.
 
 		This can only be updated when the current_tracer
 		is set to "none".
···
 		in performance.  This also has a side effect of
 		enabling or disabling specific functions to be
 		traced.  Echoing in names of functions into this
-		file will limit the trace to only those files.
+		file will limit the trace to only these functions.
 
   set_ftrace_notrace: This has the opposite effect that
 		set_ftrace_filter has. Any function that is added
 		here will not be traced. If a function exists
-		in both set_ftrace_filter and set_ftrace_notrace
-		the function will _not_ bet traced.
+		in both set_ftrace_filter and set_ftrace_notrace,
+		the function will _not_ be traced.
 
   available_filter_functions : When a function is encountered the first
 		time by the dynamic tracer, it is recorded and
···
 
   ftrace - function tracer that uses mcount to trace all functions.
 		It is possible to filter out which functions that are
-		traced when dynamic ftrace is configured in.
+		to be traced when dynamic ftrace is configured in.
 
   sched_switch - traces the context switches between tasks.
 
···
 
 The above is mostly meaningful for kernel developers.
 
-  time: This differs from the trace output where as the trace output
-	contained a absolute timestamp. This timestamp is relative
-	to the start of the first entry in the the trace.
+  time: This differs from the trace file output. The trace file output
+	included an absolute timestamp. The timestamp used by the
+	latency_trace file is relative to the start of the trace.
 
   delay: This is just to help catch your eye a bit better. And
 	needs to be fixed to be only relative to the same CPU.
-	The marks is determined by the difference between this
+	The marks are determined by the difference between this
 	current trace and the next trace.
 	 '!' - greater than preempt_mark_thresh (default 100)
 	 '+' - greater than 1 microsecond
···
   print-parent nosym-offset nosym-addr noverbose noraw nohex nobin \
  noblock nostacktrace nosched-tree
 
-To disable one of the options, echo in the option appended with "no".
+To disable one of the options, echo in the option prepended with "no".
 
   echo noprint-parent > /debug/tracing/iter_ctrl
 
 To enable an option, leave off the "no".
 
-  echo sym-offest > /debug/tracing/iter_ctrl
+  echo sym-offset > /debug/tracing/iter_ctrl
 
 Here are the available options:
 
···
 
   sym-offset - Display not only the function name, but also the offset
 		in the function. For example, instead of seeing just
-		"ktime_get" you will see "ktime_get+0xb/0x20"
+		"ktime_get", you will see "ktime_get+0xb/0x20".
 
   sym-offset:
    bash-4000  [01]  1477.606694: simple_strtoul+0x6/0xa0
···
 	user applications that can translate the raw numbers better than
 	having it done in the kernel.
 
-  hex - similar to raw, but the numbers will be in a hexadecimal format.
+  hex - Similar to raw, but the numbers will be in a hexadecimal format.
 
   bin - This will print out the formats in raw binary.
 
···
 ------------
 
 This tracer simply records schedule switches. Here's an example
-on how to implement it.
+of how to use it.
 
  # echo sched_switch > /debug/tracing/current_tracer
  # echo 1 > /debug/tracing/tracing_enabled
···
 kernel know of a new mouse event. The result is a latency with the
 reaction time.
 
-The irqsoff tracer tracks the time interrupts are disabled and when
+The irqsoff tracer tracks the time interrupts are disabled to the time
 they are re-enabled. When a new maximum latency is hit, it saves off
 the trace so that it may be retrieved at a later time. Every time a
 new maximum in reached, the old saved trace is discarded and the new
···
 because the clock must have incremented between the time of recording
 the max latency and recording the function that had that latency.
 
-Note the above had ftrace_enabled not set. If we set the ftrace_enabled
+Note the above had ftrace_enabled not set. If we set the ftrace_enabled,
 we get a much larger output:
 
 # tracer: irqsoff
···
 
 
 Here we traced a 50 microsecond latency. But we also see all the
-functions that were called during that time. Note that enabling
-function tracing we endure an added overhead. This overhead may
-extend the latency times. But never the less, this trace has provided
-some very helpful debugging.
+functions that were called during that time. Note that by enabling
+function tracing, we endure an added overhead. This overhead may
+extend the latency times. But nevertheless, this trace has provided
+some very helpful debugging information.
 
 
 preemptoff
 ----------
 
-When preemption is disabled we may be able to receive interrupts but
-the task can not be preempted and a higher priority task must wait
+When preemption is disabled, we may be able to receive interrupts but
+the task cannot be preempted and a higher priority task must wait
 for preemption to be enabled again before it can preempt a lower
 priority task.
 
-The preemptoff tracer traces the places that disables preemption.
+The preemptoff tracer traces the places that disable preemption.
 Like the irqsoff, it records the maximum latency that preemption
 was disabled. The control of preemptoff is much like the irqsoff.
 
···
 It may seem that we missed a preempt enabled. What really happened
 is that the preempt count is held on the threads stack and we
 switched to the softirq stack (4K stacks in effect). The code
-does not copy the preempt count, but because interrupts are disabled
+does not copy the preempt count, but because interrupts are disabled,
 we don't need to worry about it. Having a tracer like this is good
 to let people know what really happens inside the kernel.
 
···
 
 Again, using this trace is much like the irqsoff and preemptoff tracers.
 
- # echo preemptoff > /debug/tracing/current_tracer
+ # echo preemptirqsoff > /debug/tracing/current_tracer
  # echo 0 > /debug/tracing/tracing_max_latency
  # echo 1 > /debug/tracing/tracing_enabled
  # ls -ltr
···
 the ls task. We see that the task had the "need_resched" bit set
 with the 'N' in the trace.  Interrupts are disabled in the spin_lock
 and the trace started. We see that a schedule took place to run
-sshd.  When the interrupts were enabled we took an interrupt.
-On return of the interrupt the softirq ran. We took another interrupt
-while running the softirq as we see with the capital 'H'.
+sshd.  When the interrupts were enabled, we took an interrupt.
+On return from the interrupt handler, the softirq ran. We took another
+interrupt while running the softirq as we see with the capital 'H'.
 
 
 wakeup
···
 I stress the point that this is about RT tasks. It is also important
 to know the scheduling latency of non-RT tasks, but the average
 schedule latency is better for non-RT tasks. Tools like
-LatencyTop is more appropriate for such measurements.
+LatencyTop are more appropriate for such measurements.
 
-Real-Time environments is interested in the worst case latency.
+Real-Time environments are interested in the worst case latency.
 That is the longest latency it takes for something to happen, and
 not the average. We can have a very fast scheduler that may only
 have a large latency once in a while, but that would not work well
···
 of RT tasks.
 
 Since this tracer only deals with RT tasks, we will run this slightly
-different than we did with the previous tracers. Instead of performing
-an 'ls' we will run 'sleep 1' under 'chrt' which changes the
+differently than we did with the previous tracers. Instead of performing
+an 'ls', we will run 'sleep 1' under 'chrt' which changes the
 priority of the task.
 
  # echo wakeup > /debug/tracing/current_tracer
···
 vim:ft=help
 
 
-Running this on an idle system we see that it only took 4 microseconds
+Running this on an idle system, we see that it only took 4 microseconds
 to perform the task switch.  Note, since the trace marker in the
-schedule is before the actual "switch" we stop the tracing when
+schedule is before the actual "switch", we stop the tracing when
 the recorded task is about to schedule in. This may change if
 we add a new marker at the end of the scheduler.
 
···
 
 The interrupt went off while running ksoftirqd. This task runs at
 SCHED_OTHER. Why didn't we see the 'N' set early? This may be
-a harmless bug with x86_32 and 4K stacks. The need_reched() function
-that tests if we need to reschedule looks on the actual stack.
-Where as the setting of the NEED_RESCHED bit happens on the
-task's stack. But because we are in a hard interrupt, the test
-is with the interrupts stack which has that to be false. We don't
-see the 'N' until we switch back to the task's stack.
+a harmless bug with x86_32 and 4K stacks. On x86_32 with 4K stacks
+configured, the interrupt and softirq runs with their own stack.
+Some information is held on the top of the task's stack (need_resched
+and preempt_count are both stored there). The setting of the NEED_RESCHED
+bit is done directly to the task's stack, but the reading of the
+NEED_RESCHED is done by looking at the current stack, which in this case
+is the stack for the hard interrupt. This hides the fact that NEED_RESCHED
+has been set. We don't see the 'N' until we switch back to the task's
+assigned stack.
 
 ftrace
 ------
···
 every kernel function, produced by the -pg switch in gcc), starts
 of pointing to a simple return.
 
-When dynamic ftrace is initialized, it calls kstop_machine to make it
-act like a uniprocessor so that it can freely modify code without
-worrying about other processors executing that same code.  At
-initialization, the mcount calls are change to call a "record_ip"
+When dynamic ftrace is initialized, it calls kstop_machine to make
+the machine act like a uniprocessor so that it can freely modify code
+without worrying about other processors executing that same code.  At
+initialization, the mcount calls are changed to call a "record_ip"
 function.  After this, the first time a kernel function is called,
 it has the calling address saved in a hash table.
 
···
 want to trace and which ones we want the mcount calls to remain as
 nops.
 
-Two files that contain to the enabling and disabling of recorded
-functions are:
+Two files are used, one for enabling and one for disabling the tracing
+of recorded functions. They are:
 
   set_ftrace_filter
 
···
 
   set_ftrace_notrace
 
-A list of available functions that you can add to this files is listed
+A list of available functions that you can add to these files is listed
 in:
 
    available_filter_functions
···
 
 
 Perhaps this isn't enough. The filters also allow simple wild cards.
-Only the following is currently available
+Only the following are currently available
 
-  <match>*  - will match functions that begins with <match>
+  <match>*  - will match functions that begin with <match>
   *<match>  - will match functions that end with <match>
   *<match>* - will match functions that have <match> in it
 
···
 To rewrite the filters, use '>'
 To append to the filters, use '>>'
 
-To clear out a filter so that all functions will be recorded again.
+To clear out a filter so that all functions will be recorded again:
 
  # echo > /debug/tracing/set_ftrace_filter
  # cat /debug/tracing/set_ftrace_filter
···
 
 As mentioned above, when dynamic ftrace is configured in, a kernel
 thread wakes up once a second and checks to see if there are mcount
-calls that need to be converted into nops. If there is not, then
-it simply goes back to sleep. But if there is, it will call
+calls that need to be converted into nops. If there are not any, then
+it simply goes back to sleep. But if there are some, it will call
 kstop_machine to convert the calls to nops.
 
 There may be a case that you do not want this added latency.
···
 to calling mcount. Without this kernel thread, that overhead will
 exist.
 
-Any write to the ftraced_enabled file will cause the kstop_machine
-to run if there are recorded calls to mcount. This means that a
+If there are recorded calls to mcount, any write to the ftraced_enabled
+file will cause the kstop_machine to run. This means that a
 user can manually perform the updates when they want to by simply
 echoing a '0' into the ftraced_enabled file.
 
···
 
 Having too much or not enough data can be troublesome in diagnosing
 some issue in the kernel. The file trace_entries is used to modify
-the size of the internal trace buffers. The numbers listed
+the size of the internal trace buffers. The number listed
 is the number of entries that can be recorded per CPU. To know
 the full size, multiply the number of possible CPUS with the
 number of entries.
···
  # cat /debug/tracing/trace_entries
 65620
 
-Note, to modify this you must have tracing fulling disabled. To do that,
+Note, to modify this, you must have tracing completely disabled. To do that,
 echo "none" into the current_tracer.
 
  # echo none > /debug/tracing/current_tracer
···
 This shows us that 85 entries can fit on a single page.
 
 The number of pages that will be allocated is a percentage of available
-memory. Allocating too much will produces an error.
+memory. Allocating too much will produce an error.
 
  # echo 1000000000000 > /debug/tracing/trace_entries
 -bash: echo: write error: Cannot allocate memory