From: Tzvetomir Stoyanov <tstoyanov@vmware.com>
To: rostedt@goodmis.org
Cc: linux-trace-devel@vger.kernel.org
Subject: [PATCH v6 25/26] tools/lib/traceevent: Man pages for APIs, used to extract common fields from a record
Date: Fri, 3 May 2019 12:11:18 +0300 [thread overview]
Message-ID: <20190503091119.23399-26-tstoyanov@vmware.com> (raw)
In-Reply-To: <20190503091119.23399-1-tstoyanov@vmware.com>
Create man pages for libtraceevent APIs:
tep_data_type(),
tep_data_pid(),
tep_data_preempt_count(),
tep_data_flags()
Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
.../libtraceevent-record_parse.txt | 137 ++++++++++++++++++
1 file changed, 137 insertions(+)
create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
new file mode 100644
index 000000000000..4b49d9bb8249
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
@@ -0,0 +1,137 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_data_type, tep_data_pid,tep_data_preempt_count, tep_data_flags -
+Extract common fields from a record.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *trace_flag_type* {
+ _TRACE_FLAG_IRQS_OFF_,
+ _TRACE_FLAG_IRQS_NOSUPPORT_,
+ _TRACE_FLAG_NEED_RESCHED_,
+ _TRACE_FLAG_HARDIRQ_,
+ _TRACE_FLAG_SOFTIRQ_,
+};
+
+int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
+--
+
+DESCRIPTION
+-----------
+This set of functions can be used to extract common fields from a record.
+
+The _tep_data_type()_ function gets the event id from the record _rec_.
+It reads the "common_type" field. The _tep_ argument is the trace event parser
+context.
+
+The _tep_data_pid()_ function gets the process id from the record _rec_.
+It reads the "common_pid" field. The _tep_ argument is the trace event parser
+context.
+
+The _tep_data_preempt_count()_ function gets the preemption count from the
+record _rec_. It reads the "common_preempt_count" field. The _tep_ argument is
+the trace event parser context.
+
+The _tep_data_flags()_ function gets the latency flags from the record _rec_.
+It reads the "common_flags" field. The _tep_ argument is the trace event parser
+context. Supported latency flags are:
+[verse]
+--
+ _TRACE_FLAG_IRQS_OFF_, Interrupts are disabled.
+ _TRACE_FLAG_IRQS_NOSUPPOR_, Reading IRQ flag is not supported by the architecture.
+ _TRACE_FLAG_NEED_RESCHED_, Task needs rescheduling.
+ _TRACE_FLAG_HARDIRQ_, Hard IRQ is running.
+ _TRACE_FLAG_SOFTIRQ_, Soft IRQ is running.
+--
+
+RETURN VALUE
+------------
+The _tep_data_type()_ function returns an integer, representing the event id.
+
+The _tep_data_pid()_ function returns an integer, representing the process id
+
+The _tep_data_preempt_count()_ function returns an integer, representing the
+preemption count.
+
+The _tep_data_flags()_ function returns an integer, representing the latency
+flags. Look at the _trace_flag_type_ enum for supported flags.
+
+All these functions in case of an error return a negative integer.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+void process_record(struct tep_record *record)
+{
+ int data;
+
+ data = tep_data_type(tep, record);
+ if (data >= 0) {
+ /* Got the ID of the event */
+ }
+
+ data = tep_data_pid(tep, record);
+ if (data >= 0) {
+ /* Got the process ID */
+ }
+
+ data = tep_data_preempt_count(tep, record);
+ if (data >= 0) {
+ /* Got the preemption count */
+ }
+
+ data = tep_data_flags(tep, record);
+ if (data >= 0) {
+ /* Got the latency flags */
+ }
+}
+...
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+ Header file to include in order to have access to the library APIs.
+*-ltraceevent*
+ Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_, _trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
--
2.20.1
next prev parent reply other threads:[~2019-05-03 9:11 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-03 9:10 [PATCH v6 00/26] Libtraceevent MAN pages Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 01/26] tools/lib/traceevent: Implement libtraceevent man pages Tzvetomir Stoyanov
2019-05-10 17:34 ` Steven Rostedt
2019-05-03 9:10 ` [PATCH v6 02/26] tools/lib/traceevent: Add support for man pages with multiple names Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 03/26] tools/lib/traceevent: libtraceevent man pages for tep_handler related APIs Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 04/26] tools/lib/traceevent: Man page for header_page APIs Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 05/26] tools/lib/traceevent: Man page for get/set cpus APIs Tzvetomir Stoyanov
2019-05-03 9:10 ` [PATCH v6 06/26] tools/lib/traceevent: Man page for file endian APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 07/26] tools/lib/traceevent: Man page for host " Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 08/26] tools/lib/traceevent: Man page for page size APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 09/26] tools/lib/traceevent: Man page for tep_strerror() Tzvetomir Stoyanov
2019-05-10 17:48 ` Steven Rostedt
2019-05-03 9:11 ` [PATCH v6 10/26] tools/lib/traceevent: Man pages for event handler APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 11/26] tools/lib/traceevent: Man pages for function related libtraceevent APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 12/26] tools/lib/traceevent: Man pages for registering print function Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 13/26] tools/lib/traceevent: Man page for tep_read_number() Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 14/26] tools/lib/traceevent: Man pages for event find APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 15/26] tools/lib/traceevent: Man page for list events APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 16/26] tools/lib/traceevent: Man pages for libtraceevent event get APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 17/26] tools/lib/traceevent: Man pages find field APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 18/26] tools/lib/traceevent: Man pages get field value APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 19/26] tools/lib/traceevent: Man pages for print field APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 20/26] tools/lib/traceevent: Man page for tep_read_number_field() Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 21/26] tools/lib/traceevent: Man pages for event fields APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 22/26] tools/lib/traceevent: Man pages for event filter APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 23/26] tools/lib/traceevent: Man pages for parse event APIs Tzvetomir Stoyanov
2019-05-03 9:11 ` [PATCH v6 24/26] tools/lib/traceevent: Man page for tep_parse_header_page() Tzvetomir Stoyanov
2019-05-03 9:11 ` Tzvetomir Stoyanov [this message]
2019-05-10 18:29 ` [PATCH v6 25/26] tools/lib/traceevent: Man pages for APIs, used to extract common fields from a record Steven Rostedt
2019-05-03 9:11 ` [PATCH v6 26/26] tools/lib/traceevent: Man pages for trace sequences APIs Tzvetomir Stoyanov
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=20190503091119.23399-26-tstoyanov@vmware.com \
--to=tstoyanov@vmware.com \
--cc=linux-trace-devel@vger.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).