From patchwork Sat Nov 19 00:34:15 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 83040 Delivered-To: patch@linaro.org Received: by 10.140.97.165 with SMTP id m34csp376975qge; Fri, 18 Nov 2016 16:34:58 -0800 (PST) X-Received: by 10.13.214.206 with SMTP id y197mr2406590ywd.161.1479515698132; Fri, 18 Nov 2016 16:34:58 -0800 (PST) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id g67si2218128ywc.191.2016.11.18.16.34.57; Fri, 18 Nov 2016 16:34:58 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932241AbcKSAev (ORCPT + 26 others); Fri, 18 Nov 2016 19:34:51 -0500 Received: from ms.lwn.net ([45.79.88.28]:40508 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753853AbcKSAem (ORCPT ); Fri, 18 Nov 2016 19:34:42 -0500 Received: from tpad.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 8AAC27310; Sat, 19 Nov 2016 00:34:41 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thomas Gleixner , Jason Baron , William Cohen , Jonathan Corbet Subject: [PATCH 3/3] doc: Sphinxify the tracepoint docbook Date: Fri, 18 Nov 2016 17:34:15 -0700 Message-Id: <1479515655-20556-4-git-send-email-corbet@lwn.net> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1479515655-20556-1-git-send-email-corbet@lwn.net> References: <1479515655-20556-1-git-send-email-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 Cc: William Cohen Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 3 +- Documentation/DocBook/tracepoint.tmpl | 112 ---------------------------------- Documentation/core-api/index.rst | 3 +- Documentation/core-api/tracepoint.rst | 55 +++++++++++++++++ 4 files changed, 58 insertions(+), 115 deletions(-) delete mode 100644 Documentation/DocBook/tracepoint.tmpl create mode 100644 Documentation/core-api/tracepoint.rst -- 2.7.4 diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index bc6278d18090..caab9039362f 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -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),) diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl deleted file mode 100644 index b57a9ede3224..000000000000 --- a/Documentation/DocBook/tracepoint.tmpl +++ /dev/null @@ -1,112 +0,0 @@ - - - - - - The Linux Kernel Tracepoint API - - - - Jason - Baron - -
- jbaron@redhat.com -
- - - - William - Cohen - -
- wcohen@redhat.com -
- - - - - - - 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. - - - - 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. - - - - 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 - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - 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 -!Iinclude/trace/events/irq.h - - - - SIGNAL -!Iinclude/trace/events/signal.h - - - - Block IO -!Iinclude/trace/events/block.h - - - - Workqueue -!Iinclude/trace/events/workqueue.h - - diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index c3a1402da0cd..91b3a010817a 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -19,7 +19,8 @@ Interfaces for kernel debugging .. toctree:: :maxdepth: 1 - debug-objects + debug-objects + tracepoint .. only:: subproject diff --git a/Documentation/core-api/tracepoint.rst b/Documentation/core-api/tracepoint.rst new file mode 100644 index 000000000000..6b44bec0de43 --- /dev/null +++ b/Documentation/core-api/tracepoint.rst @@ -0,0 +1,55 @@ +=============================== +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: