From: changbin.du@intel.com
To: corbet@lwn.net, rostedt@goodmis.org
Cc: mingo@kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, Changbin Du <changbin.du@intel.com>
Subject: [PATCH 08/17] trace doc: convert trace/tracepoints.txt to rst format
Date: Sat, 17 Feb 2018 13:39:41 +0800 [thread overview]
Message-ID: <1518845990-20733-9-git-send-email-changbin.du@intel.com> (raw)
In-Reply-To: <1518845990-20733-1-git-send-email-changbin.du@intel.com>
From: Changbin Du <changbin.du@intel.com>
This converts the plain text documentation to reStructuredText format and
add it into Sphinx TOC tree. No essential content change.
Cc: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Changbin Du <changbin.du@intel.com>
---
Documentation/trace/index.rst | 1 +
.../trace/{tracepoints.txt => tracepoints.rst} | 77 +++++++++++-----------
2 files changed, 41 insertions(+), 37 deletions(-)
rename Documentation/trace/{tracepoints.txt => tracepoints.rst} (74%)
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 353fb8a..c8bbdfc 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -11,3 +11,4 @@ Linux Tracing Technologies
ftrace-uses
kprobetrace
uprobetracer
+ tracepoints
diff --git a/Documentation/trace/tracepoints.txt b/Documentation/trace/tracepoints.rst
similarity index 74%
rename from Documentation/trace/tracepoints.txt
rename to Documentation/trace/tracepoints.rst
index a3efac6..6e3ce3b 100644
--- a/Documentation/trace/tracepoints.txt
+++ b/Documentation/trace/tracepoints.rst
@@ -1,6 +1,8 @@
- Using the Linux Kernel Tracepoints
+==================================
+Using the Linux Kernel Tracepoints
+==================================
- Mathieu Desnoyers
+:Author: Mathieu Desnoyers
This document introduces Linux Kernel Tracepoints and their use. It
@@ -9,8 +11,8 @@ connect probe functions to them and provides some examples of probe
functions.
-* Purpose of tracepoints
-
+Purpose of tracepoints
+----------------------
A tracepoint placed in code provides a hook to call a function (probe)
that you can provide at runtime. A tracepoint can be "on" (a probe is
connected to it) or "off" (no probe is attached). When a tracepoint is
@@ -31,8 +33,8 @@ header file.
They can be used for tracing and performance accounting.
-* Usage
-
+Usage
+-----
Two elements are required for tracepoints :
- A tracepoint definition, placed in a header file.
@@ -40,52 +42,53 @@ Two elements are required for tracepoints :
In order to use tracepoints, you should include linux/tracepoint.h.
-In include/trace/events/subsys.h :
+In include/trace/events/subsys.h::
-#undef TRACE_SYSTEM
-#define TRACE_SYSTEM subsys
+ #undef TRACE_SYSTEM
+ #define TRACE_SYSTEM subsys
-#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
-#define _TRACE_SUBSYS_H
+ #if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
+ #define _TRACE_SUBSYS_H
-#include <linux/tracepoint.h>
+ #include <linux/tracepoint.h>
-DECLARE_TRACE(subsys_eventname,
- TP_PROTO(int firstarg, struct task_struct *p),
- TP_ARGS(firstarg, p));
+ DECLARE_TRACE(subsys_eventname,
+ TP_PROTO(int firstarg, struct task_struct *p),
+ TP_ARGS(firstarg, p));
-#endif /* _TRACE_SUBSYS_H */
+ #endif /* _TRACE_SUBSYS_H */
-/* This part must be outside protection */
-#include <trace/define_trace.h>
+ /* This part must be outside protection */
+ #include <trace/define_trace.h>
-In subsys/file.c (where the tracing statement must be added) :
+In subsys/file.c (where the tracing statement must be added)::
-#include <trace/events/subsys.h>
+ #include <trace/events/subsys.h>
-#define CREATE_TRACE_POINTS
-DEFINE_TRACE(subsys_eventname);
+ #define CREATE_TRACE_POINTS
+ DEFINE_TRACE(subsys_eventname);
-void somefct(void)
-{
- ...
- trace_subsys_eventname(arg, task);
- ...
-}
+ void somefct(void)
+ {
+ ...
+ trace_subsys_eventname(arg, task);
+ ...
+ }
Where :
-- subsys_eventname is an identifier unique to your event
+ - subsys_eventname is an identifier unique to your event
+
- subsys is the name of your subsystem.
- eventname is the name of the event to trace.
-- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the
- function called by this tracepoint.
+ - `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the
+ function called by this tracepoint.
-- TP_ARGS(firstarg, p) are the parameters names, same as found in the
- prototype.
+ - `TP_ARGS(firstarg, p)` are the parameters names, same as found in the
+ prototype.
-- if you use the header in multiple source files, #define CREATE_TRACE_POINTS
- should appear only in one source file.
+ - if you use the header in multiple source files, `#define CREATE_TRACE_POINTS`
+ should appear only in one source file.
Connecting a function (probe) to a tracepoint is done by providing a
probe (function to call) for the specific tracepoint through
@@ -117,7 +120,7 @@ used to export the defined tracepoints.
If you need to do a bit of work for a tracepoint parameter, and
that work is only used for the tracepoint, that work can be encapsulated
-within an if statement with the following:
+within an if statement with the following::
if (trace_foo_bar_enabled()) {
int i;
@@ -139,7 +142,7 @@ The advantage of using the trace_<tracepoint>_enabled() is that it uses
the static_key of the tracepoint to allow the if statement to be implemented
with jump labels and avoid conditional branches.
-Note: The convenience macro TRACE_EVENT provides an alternative way to
+.. note:: The convenience macro TRACE_EVENT provides an alternative way to
define tracepoints. Check http://lwn.net/Articles/379903,
http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362
for a series of articles with more details.
--
2.7.4
next prev parent reply other threads:[~2018-02-17 5:49 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-02-17 5:39 [PATCH 00/17] Include linux trace docs to Sphinx TOC tree changbin.du
2018-02-17 5:39 ` [PATCH 01/17] Documentation: add Linux tracing " changbin.du
2018-02-17 5:39 ` [PATCH 02/17] trace doc: convert trace/ftrace-design.txt to rst format changbin.du
2018-02-17 5:39 ` [PATCH 03/17] trace doc: add ftrace-uses.rst to doc tree changbin.du
2018-02-17 5:39 ` [PATCH 04/17] trace doc: convert trace/tracepoint-analysis.txt to rst format changbin.du
2018-02-17 5:39 ` [PATCH 05/17] trace doc: convert trace/ftrace.txt " changbin.du
2018-02-20 7:28 ` Philippe Ombredanne
2018-02-20 13:27 ` Du, Changbin
2018-02-20 15:26 ` Steven Rostedt
2018-02-20 16:36 ` Jonathan Corbet
2018-02-17 5:39 ` [PATCH 06/17] trace doc: convert trace/kprobetrace.txt " changbin.du
2018-02-17 5:39 ` [PATCH 07/17] trace doc: convert trace/uprobetracer.txt " changbin.du
2018-02-17 5:39 ` changbin.du [this message]
2018-02-17 5:39 ` [PATCH 09/17] trace doc: convert trace/events.txt " changbin.du
2018-02-17 5:39 ` [PATCH 10/17] trace doc: convert trace/events-kmem.txt " changbin.du
2018-02-17 5:39 ` [PATCH 11/17] trace doc: convert trace/events-power.txt " changbin.du
2018-02-17 5:39 ` [PATCH 12/17] trace doc: convert trace/events-nmi.txt " changbin.du
2018-02-17 5:39 ` [PATCH 13/17] trace doc: convert trace/events-msr.txt " changbin.du
2018-02-17 5:39 ` [PATCH 14/17] trace doc: convert trace/mmiotrace.txt " changbin.du
2018-02-17 5:39 ` [PATCH 15/17] trace doc: convert trace/hwlat_detector.txt to rst fromat changbin.du
2018-02-17 5:39 ` [PATCH 16/17] trace doc: convert trace/intel_th.txt to rst format changbin.du
2018-02-17 5:39 ` [PATCH 17/17] trace doc: convert trace/stm.txt " changbin.du
2018-02-27 9:34 ` [PATCH 00/17] Include linux trace docs to Sphinx TOC tree Du, Changbin
2018-02-27 22:43 ` Steven Rostedt
2018-03-07 17:46 ` Jonathan Corbet
2018-03-08 2:42 ` Du, Changbin
2018-03-08 3:41 ` Steven Rostedt
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1518845990-20733-9-git-send-email-changbin.du@intel.com \
--to=changbin.du@intel.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mingo@kernel.org \
--cc=rostedt@goodmis.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).