Impact: extend documentation with notice of using wild cards correctly

We know that we can use wild cards to set set_ftrace_filter, but there's
problem when using them naively such as:

   echo h* > /debug/tracing/set_ftrace_filter

If there are files named with "h" prefix in current directory,
echo "h*" will echo these filenames to set_ftrace_filter, not the
intended "h*".

For example:

  $ cat /debug/tracing/available_filter_functions |grep ^hr |wc -l
  23
  $ ls
  $ touch hraa hrdd
  $ ls
  hraa  hrdd
  $ echo hr* > /debug/tracing/set_ftrace_filter
  $ cat /debug/tracing/set_ftrace_filter

No output in /debug/tracing/set_ftrace_filter!

If we use '' to escape wild cards, it works:

  $ ls
  hraa  hrdd
  $ echo "hr*" > /debug/tracing/set_ftrace_filter
  $ cat /debug/tracing/set_ftrace_filter |wc -l
  23

This problem can lead to unexpected result if current directory has a
lot of files.
Signed-off-by: Nwalimis <walimisdev@gmail.com>
Acked-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: feature to function trace a single thread

This patch adds the ability to function trace a single thread.
The file:

  /debugfs/tracing/set_ftrace_pid

contains the pid to trace. Valid pids are any positive integer.
Writing any negative number to this file will disable the pid
tracing and the function tracer will go back to tracing all of
threads.

This feature works with both static and dynamic function tracing.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: modify+improve the userstacktrace tracing visualization feature

Store thread group leader id, and use it to lookup the address in the
process's map. We could have looked up the address on thread's map,
but the thread might not exist by the time we are called. The process
might not exist either, but if you are reading trace_pipe, that is
unlikely.

Example usage:

 mount -t debugfs nodev /sys/kernel/debug
 cd /sys/kernel/debug/tracing
 echo userstacktrace >iter_ctrl
 echo sym-userobj >iter_ctrl
 echo sched_switch >current_tracer
 echo 1 >tracing_enabled
 cat trace_pipe >/tmp/trace&
 .... run application ...
 echo 0 >tracing_enabled
 cat /tmp/trace

You'll see stack entries like:

   /lib/libpthread-2.7.so[+0xd370]

You can convert them to function/line using:

   addr2line -fie /lib/libpthread-2.7.so 0xd370

Or:

   addr2line -fie /usr/lib/debug/libpthread-2.7.so 0xd370

For non-PIC/PIE executables this won't work:

   a.out[+0x73b]

You need to run the following: addr2line -fie a.out 0x40073b
(where 0x400000 is the default load address of a.out)
Signed-off-by: NTörök Edwin <edwintorok@gmail.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: add new (default-off) tracing visualization feature

Usage example:

 mount -t debugfs nodev /sys/kernel/debug
 cd /sys/kernel/debug/tracing
 echo userstacktrace >iter_ctrl
 echo sched_switch >current_tracer
 echo 1 >tracing_enabled
 .... run application ...
 echo 0 >tracing_enabled

Then read one of 'trace','latency_trace','trace_pipe'.

To get the best output you can compile your userspace programs with
frame pointers (at least glibc + the app you are tracing).
Signed-off-by: NTörök Edwin <edwintorok@gmail.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: rename file /debug/tracing/iter_ctrl to /debug/tracing/trace_options

The original ftrace had a file called "iter_ctrl" that would control
the way the output was iterated. But this file grew into a catch all
for different trace options. This patch renames the file from iter_ctrl
to trace_options to reflect this change.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: change the units of buffer_size_kb to kilobytes

This patch changes the units of the buffer_size_kb file to kilobytes.
Reading and writing to the file uses kilobytes as units. To help
users to know what units are used, the output of the file now
looks like:

  # cat /debug/tracing/buffer_size_kb
  1408
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: rename of debugfs file trace_entries to buffer_size_kb

The original ftrace had fixed size entries, and the number of entries
was shown and modified via the file called trace_entries. By converting
to the unified trace buffer, we now allow for variable size entries
which makes the meaning of trace_entries pointless.

Since trace_size might be confused to the size of the trace, this patch
names it "buffer_size_kb" (thanks to Arjan van de Ven for this idea).

[ mingo@elte.hu: changed from buffer_size to buffer_size_kb ]

( Note, the units are still bytes - the next patch changes that,
  to keep the wide rename patch separate from the unit-change patch. )
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: Documentation update only

Update the version that the ftrace document was written for.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: Documentation update only

A lot of changes have gone into ftrace. This patch updates
the ftrace.txt document.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Acked-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

Impact: build fix on non-lockdep architectures

Some architectures do not support a way to read the irq flags that
is set from "local_irq_save(flags)" to determine if interrupts were
disabled or enabled. Ftrace uses this information to display to the user
if the trace occurred with interrupts enabled or disabled.

Besides the fact that those archs that do not support this will fail to
compile, unless they fix it, we do not want to have the trace simply
say interrupts were not disabled or they were enabled, without knowing
the real answer.

This patch adds a 'X' in the output to let the user know that the
architecture they are running on does not support a way for the tracer
to determine if interrupts were enabled or disabled. It also lets those
same archs compile with tracing enabled.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NIngo Molnar <mingo@elte.hu>

I asked legal about the licensing of ftrace.txt, and they told me that,
unless the Documentation directory is specifically set up to handle non
GPL licenses (which it does not appear to be), then it would be best to
put ftrace.txt under the GPL.

This patch adds a dual license to ftrace.txt such that it is under both
the FDL and the GPL.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

This patch includes ftrace.txt updates that address (mostly) comments from
Andrew Morton. It also includes updates that were suggested by Randy
Dunlap, John Kacur and David Teigland.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

This is the long awaited ftrace.txt. It explains in quite detail how to
use ftrace and the various tracers.
Signed-off-by: NSteven Rostedt <srostedt@redhat.com>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>