[media] DocBook/frontend.xml: Recomend the usage of the new API
[linux-2.6.git] / Documentation / DocBook / tracepoint.tmpl
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5 <book id="Tracepoints">
6  <bookinfo>
7   <title>The Linux Kernel Tracepoint API</title>
8
9   <authorgroup>
10    <author>
11     <firstname>Jason</firstname>
12     <surname>Baron</surname>
13     <affiliation>
14      <address>
15       <email>jbaron@redhat.com</email>
16      </address>
17     </affiliation>
18    </author>
19    <author>
20     <firstname>William</firstname>
21     <surname>Cohen</surname>
22     <affiliation>
23      <address>
24       <email>wcohen@redhat.com</email>
25      </address>
26     </affiliation>
27    </author>
28   </authorgroup>
29
30   <legalnotice>
31    <para>
32      This documentation is free software; you can redistribute
33      it and/or modify it under the terms of the GNU General Public
34      License as published by the Free Software Foundation; either
35      version 2 of the License, or (at your option) any later
36      version.
37    </para>
38
39    <para>
40      This program is distributed in the hope that it will be
41      useful, but WITHOUT ANY WARRANTY; without even the implied
42      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
43      See the GNU General Public License for more details.
44    </para>
45
46    <para>
47      You should have received a copy of the GNU General Public
48      License along with this program; if not, write to the Free
49      Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
50      MA 02111-1307 USA
51    </para>
52
53    <para>
54      For more details see the file COPYING in the source
55      distribution of Linux.
56    </para>
57   </legalnotice>
58  </bookinfo>
59
60  <toc></toc>
61   <chapter id="intro">
62    <title>Introduction</title>
63    <para>
64      Tracepoints are static probe points that are located in strategic points
65      throughout the kernel. 'Probes' register/unregister with tracepoints
66      via a callback mechanism. The 'probes' are strictly typed functions that
67      are passed a unique set of parameters defined by each tracepoint.
68    </para>
69
70    <para>
71      From this simple callback mechanism, 'probes' can be used to profile, debug,
72      and understand kernel behavior. There are a number of tools that provide a
73      framework for using 'probes'. These tools include Systemtap, ftrace, and
74      LTTng.
75    </para>
76
77    <para>
78      Tracepoints are defined in a number of header files via various macros. Thus,
79      the purpose of this document is to provide a clear accounting of the available
80      tracepoints. The intention is to understand not only what tracepoints are
81      available but also to understand where future tracepoints might be added.
82    </para>
83
84    <para>
85      The API presented has functions of the form:
86      <function>trace_tracepointname(function parameters)</function>. These are the
87      tracepoints callbacks that are found throughout the code. Registering and
88      unregistering probes with these callback sites is covered in the
89      <filename>Documentation/trace/*</filename> directory.
90    </para>
91   </chapter>
92
93   <chapter id="irq">
94    <title>IRQ</title>
95 !Iinclude/trace/events/irq.h
96   </chapter>
97
98   <chapter id="signal">
99    <title>SIGNAL</title>
100 !Iinclude/trace/events/signal.h
101   </chapter>
102
103   <chapter id="block">
104    <title>Block IO</title>
105 !Iinclude/trace/events/block.h
106   </chapter>
107
108   <chapter id="workqueue">
109    <title>Workqueue</title>
110 !Iinclude/trace/events/workqueue.h
111   </chapter>
112 </book>