Merge branch 'tracing-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip

	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \

	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \

	    mac80211.xml debugobjects.xml sh.xml regulator.xml \

	    alsa-driver-api.xml writing-an-alsa-driver.xml

	    alsa-driver-api.xml writing-an-alsa-driver.xml \

	    tracepoint.xml

###

# The build process is as follows (targets):

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="Tracepoints">

 <bookinfo>

  <title>The Linux Kernel Tracepoint API</title>

  <authorgroup>

   <author>

    <firstname>Jason</firstname>

    <surname>Baron</surname>

    <affiliation>

     <address>

      <email>jbaron@redhat.com</email>

     </address>

    </affiliation>

   </author>

  </authorgroup>

  <legalnotice>

   <para>

     This documentation is free software; you can redistribute

     it and/or modify it under the terms of the GNU General Public

     License as published by the Free Software Foundation; either

     version 2 of the License, or (at your option) any later

     version.

   </para>

   <para>

     This program is distributed in the hope that it will be

     useful, but WITHOUT ANY WARRANTY; without even the implied

     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

     See the GNU General Public License for more details.

   </para>

   <para>

     You should have received a copy of the GNU General Public

     License along with this program; if not, write to the Free

     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,

     MA 02111-1307 USA

   </para>

   <para>

     For more details see the file COPYING in the source

     distribution of Linux.

   </para>

  </legalnotice>

 </bookinfo>

 <toc></toc>

  <chapter id="intro">

   <title>Introduction</title>

   <para>

     Tracepoints are static probe points that are located in strategic points

     throughout the kernel. 'Probes' register/unregister with tracepoints

     via a callback mechanism. The 'probes' are strictly typed functions that

     are passed a unique set of parameters defined by each tracepoint.

   </para>

   <para>

     From this simple callback mechanism, 'probes' can be used to profile, debug,

     and understand kernel behavior. There are a number of tools that provide a

     framework for using 'probes'. These tools include Systemtap, ftrace, and

     LTTng.

   </para>

   <para>

     Tracepoints are defined in a number of header files via various macros. Thus,

     the purpose of this document is to provide a clear accounting of the available

     tracepoints. The intention is to understand not only what tracepoints are

     available but also to understand where future tracepoints might be added.

   </para>

   <para>

     The API presented has functions of the form:

     <function>trace_tracepointname(function parameters)</function>. These are the

     tracepoints callbacks that are found throughout the code. Registering and

     unregistering probes with these callback sites is covered in the

     <filename>Documentation/trace/*</filename> directory.

   </para>

  </chapter>

  <chapter id="irq">

   <title>IRQ</title>

!Iinclude/trace/events/irq.h

  </chapter>

</book>

	ISAPNP	ISA PnP code is enabled.

	ISDN	Appropriate ISDN support is enabled.

	JOY	Appropriate joystick support is enabled.

	KMEMTRACE kmemtrace is enabled.

	LIBATA  Libata driver is enabled

	LP	Printer support is enabled.

	LOOP	Loopback device support is enabled.

			ia64_pal_cache_flush instead of SAL_CACHE_FLUSH.

	ftrace=[tracer]

			[ftrace] will set and start the specified tracer

			[FTRACE] will set and start the specified tracer

			as early as possible in order to facilitate early

			boot debugging.

	ftrace_dump_on_oops

			[ftrace] will dump the trace buffers on oops.

			[FTRACE] will dump the trace buffers on oops.

	ftrace_filter=[function-list]

			[FTRACE] Limit the functions traced by the function

			tracer at boot up. function-list is a comma separated

			list of functions. This list can be changed at run

			time by the set_ftrace_filter file in the debugfs

			tracing directory. 

	ftrace_notrace=[function-list]

			[FTRACE] Do not trace the functions specified in

			function-list. This list can be changed at run time

			by the set_ftrace_notrace file in the debugfs

			tracing directory.

	gamecon.map[2|3]=

			[HW,JOY] Multisystem joystick and NES/SNES/PSX pad

			use the HighMem zone if it exists, and the Normal

			zone if it does not.

	kmemtrace.enable=	[KNL,KMEMTRACE] Format: { yes | no }

				Controls whether kmemtrace is enabled

				at boot-time.

	kmemtrace.subbufs=n	[KNL,KMEMTRACE] Overrides the number of

			subbufs kmemtrace's relay channel has. Set this

			higher than default (KMEMTRACE_N_SUBBUFS in code) if

			you experience buffer overruns.

	kgdboc=		[HW] kgdb over consoles.

			Requires a tty driver that supports console polling.

			(only serial suported for now)

			     Event Tracing

		Documentation written by Theodore Ts'o

			Updated by Li Zefan

1. Introduction

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

Tracepoints (see Documentation/trace/tracepoints.txt) can be used

without creating custom kernel modules to register probe functions

using the event tracing infrastructure.

Not all tracepoints can be traced using the event tracing system;

the kernel developer must provide code snippets which define how the

tracing information is saved into the tracing buffer, and how the

tracing information should be printed.

2. Using Event Tracing

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

2.1 Via the 'set_event' interface

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

The events which are available for tracing can be found in the file

/debug/tracing/available_events.

To enable a particular event, such as 'sched_wakeup', simply echo it

to /debug/tracing/set_event. For example:

	# echo sched_wakeup >> /debug/tracing/set_event

[ Note: '>>' is necessary, otherwise it will firstly disable

  all the events. ]

To disable an event, echo the event name to the set_event file prefixed

with an exclamation point:

	# echo '!sched_wakeup' >> /debug/tracing/set_event

To disable all events, echo an empty line to the set_event file:

	# echo > /debug/tracing/set_event

To enable all events, echo '*:*' or '*:' to the set_event file:

	# echo *:* > /debug/tracing/set_event

The events are organized into subsystems, such as ext4, irq, sched,

etc., and a full event name looks like this: <subsystem>:<event>.  The

subsystem name is optional, but it is displayed in the available_events

file.  All of the events in a subsystem can be specified via the syntax

"<subsystem>:*"; for example, to enable all irq events, you can use the

command:

	# echo 'irq:*' > /debug/tracing/set_event

2.2 Via the 'enable' toggle

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

The events available are also listed in /debug/tracing/events/ hierarchy

of directories.

To enable event 'sched_wakeup':

	# echo 1 > /debug/tracing/events/sched/sched_wakeup/enable

To disable it:

	# echo 0 > /debug/tracing/events/sched/sched_wakeup/enable

To enable all events in sched subsystem:

	# echo 1 > /debug/tracing/events/sched/enable

To eanble all events:

	# echo 1 > /debug/tracing/events/enable

When reading one of these enable files, there are four results:

 0 - all events this file affects are disabled

 1 - all events this file affects are enabled

 X - there is a mixture of events enabled and disabled

 ? - this file does not affect any event

3. Defining an event-enabled tracepoint

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

See The example provided in samples/trace_events

	Function call tracer to trace all kernel functions.

  "function_graph_tracer"

  "function_graph"

	Similar to the function tracer except that the

	function tracer probes the functions on their entry