summaryrefslogtreecommitdiff
path: root/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
blob: e9a69116c78b7836c161faaf2fc178907a1fc290 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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_NOSUPPORT_,	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