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

Commit d6ba7a9c authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

doc: Sphinxify the tracepoint docbook 



Convert the tracepoint docbook template to RST and add it to the core-api
manual.  No changes to the actual text beyond the mechanical formatting
conversion.

Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 8da3dc53

Documentation/DocBook/Makefile

+1 −2
Original line number Diff line number Diff line
@@ -12,8 +12,7 @@ DOCBOOKS := z8530book.xml \ 
	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \

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

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

	    80211.xml sh.xml regulator.xml \

	    tracepoint.xml w1.xml \

	    80211.xml sh.xml regulator.xml w1.xml \

	    writing_musb_glue_layer.xml crypto-API.xml iio.xml



ifeq ($(DOCBOOKS),)

Documentation/DocBook/tracepoint.tmpl

deleted100644 → 0
+0 −112
Original line number Diff line number Diff line 
<?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>

   <author>

    <firstname>William</firstname>

    <surname>Cohen</surname>

    <affiliation>

     <address>

      <email>wcohen@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>



  <chapter id="signal">

   <title>SIGNAL</title>

!Iinclude/trace/events/signal.h

  </chapter>



  <chapter id="block">

   <title>Block IO</title>

!Iinclude/trace/events/block.h

  </chapter>



  <chapter id="workqueue">

   <title>Workqueue</title>

!Iinclude/trace/events/workqueue.h

  </chapter>

</book>

Documentation/core-api/index.rst

+2 −1
Original line number Diff line number Diff line
@@ -20,6 +20,7 @@ Interfaces for kernel debugging 
   :maxdepth: 1



   debug-objects

   tracepoint



.. only::  subproject

Documentation/core-api/tracepoint.rst

0 → 100644
+55 −0
Original line number Diff line number Diff line 
===============================

The Linux Kernel Tracepoint API

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



:Author: Jason Baron

:Author: William Cohen



Introduction

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



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.



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.



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.



The API presented has functions of the form:

``trace_tracepointname(function parameters)``. These are the tracepoints

callbacks that are found throughout the code. Registering and

unregistering probes with these callback sites is covered in the

``Documentation/trace/*`` directory.



IRQ

===



.. kernel-doc:: include/trace/events/irq.h

   :internal:



SIGNAL

======



.. kernel-doc:: include/trace/events/signal.h

   :internal:



Block IO

========



.. kernel-doc:: include/trace/events/block.h

   :internal:



Workqueue

=========



.. kernel-doc:: include/trace/events/workqueue.h

   :internal: