1TRACE-CMD.DAT.V(5)             libtracefs Manual            TRACE-CMD.DAT.V(5)
2
3
4

NAME

6       trace-cmd.dat.v6 - trace-cmd version 6 file format
7

SYNOPSIS

9       trace-cmd.dat ignore
10

DESCRIPTION

12       The trace-cmd(1) utility produces a "trace.dat" file. The file may also
13       be named anything depending if the user specifies a different output
14       name, but it must have a certain binary format. The file is used by
15       trace-cmd to save kernel traces into it and be able to extract the
16       trace from it at a later point (see trace-cmd-report(1)).
17

INITIAL FORMAT

19           The first three bytes contain the magic value:
20
21           0x17 0x08  0x44
22
23           The next 7 bytes contain the characters:
24
25           "tracing"
26
27           The next set of characters contain a null '\0' terminated string
28           that contains the version of the file:
29
30           "6\0"
31
32           The next 1 byte contains the flags for the file endianess:
33
34           0 = little endian
35           1 = big endian
36
37           The next byte contains the number of bytes per "long" value:
38
39           4 - 32-bit long values
40           8 - 64-bit long values
41
42           Note: This is the long size of the target's userspace. Not the
43           kernel space size.
44
45           [ Now all numbers are written in file defined endianess. ]
46
47           The next 4 bytes are a 32-bit word that defines what the traced
48           host machine page size was.
49

HEADER INFO FORMAT

51           Directly after the initial format comes information about the
52           trace headers recorded from the target box.
53
54           The next 12 bytes contain the string:
55
56           "header_page\0"
57
58           The next 8 bytes are a 64-bit word containing the size of the
59           page header information stored next.
60
61           The next set of data is of the size read from the previous 8 bytes,
62           and contains the data retrieved from debugfs/tracing/events/header_page.
63
64           Note: The size of the second field \fBcommit\fR contains the target
65           kernel long size. For example:
66
67           field: local_t commit;        offset:8;       \fBsize:8;\fR   signed:1;
68
69           shows the kernel has a 64-bit long.
70
71           The next 13 bytes contain the string:
72
73           "header_event\0"
74
75           The next 8 bytes are a 64-bit word containing the size of the
76           event header information stored next.
77
78           The next set of data is of the size read from the previous 8 bytes
79           and contains the data retrieved from debugfs/tracing/events/header_event.
80
81           This data allows the trace-cmd tool to know if the ring buffer format
82           of the kernel made any changes.
83

FTRACE EVENT FORMATS

85           Directly after the header information comes the information about
86           the Ftrace specific events. These are the events used by the Ftrace plugins
87           and are not enabled by the event tracing.
88
89           The next 4 bytes contain a 32-bit word of the number of Ftrace event
90           format files that are stored in the file.
91
92           For the number of times defined by the previous 4 bytes is the
93           following:
94
95           8 bytes for the size of the Ftrace event format file.
96
97           The Ftrace event format file copied from the target machine:
98           debugfs/tracing/events/ftrace/<event>/format
99

EVENT FORMATS

101           Directly after the Ftrace formats comes the information about
102           the event layout.
103
104           The next 4 bytes are a 32-bit word containing the number of
105           event systems that are stored in the file. These are the
106           directories in debugfs/tracing/events excluding the \fBftrace\fR
107           directory.
108
109           For the number of times defined by the previous 4 bytes is the
110           following:
111
112           A null-terminated string containing the system name.
113
114           4 bytes containing a 32-bit word containing the number
115           of events within the system.
116
117           For the number of times defined in the previous 4 bytes is the
118           following:
119
120           8 bytes for the size of the event format file.
121
122           The event format file copied from the target machine:
123           debugfs/tracing/events/<system>/<event>/format
124

KALLSYMS INFORMATION

126           Directly after the event formats comes the information of the mapping
127           of function addresses to the function names.
128
129           The next 4 bytes are a 32-bit word containing the size of the
130           data holding the function mappings.
131
132           The next set of data is of the size defined by the previous 4 bytes
133           and contains the information from the target machine's file:
134           /proc/kallsyms
135

TRACE_PRINTK INFORMATION

137           If a developer used trace_printk() within the kernel, it may
138           store the format string outside the ring buffer.
139           This information can be found in:
140           debugfs/tracing/printk_formats
141
142           The next 4 bytes are a 32-bit word containing the size of the
143           data holding the printk formats.
144
145           The next set of data is of the size defined by the previous 4 bytes
146           and contains the information from debugfs/tracing/printk_formats.
147

PROCESS INFORMATION

149           Directly after the trace_printk formats comes the information mapping
150           a PID to a process name.
151
152           The next 8 bytes contain a 64-bit word that holds the size of the
153           data mapping the PID to a process name.
154
155           The next set of data is of the size defined by the previous 8 bytes
156           and contains the information from debugfs/tracing/saved_cmdlines.
157

REST OF TRACE-CMD HEADER

159           Directly after the process information comes the last bit of the
160           trace.dat file header.
161
162           The next 4 bytes are a 32-bit word defining the number of CPUs that
163           were discovered on the target machine (and has matching trace data
164           for it).
165
166           The next 10 bytes are one of the following:
167
168           "options  \0"
169
170           "latency  \0"
171
172           "flyrecord\0"
173
174           If it is "options  \0" then:
175
176           The next 2 bytes are a 16-bit word defining the current option.
177           If the the value is zero then there are no more options.
178
179           Otherwise, the next 4 bytes contain a 32-bit word containing the
180           option size. If the reader does not know how to handle the option
181           it can simply skip it. Currently there are no options defined,
182           but this is here to extend the data.
183
184           The next option will be directly after the previous option, and
185           the options ends with a zero in the option type field.
186
187           The next 10 bytes after the options are one of the following:
188
189           "latency  \0"
190
191           "flyrecord\0"
192
193           which would follow the same as if options were not present.
194
195           If the value is "latency  \0", then the rest of the file is
196           simply ASCII text that was taken from the target's:
197           debugfs/tracing/trace
198
199           If the value is "flyrecord\0", the following is present:
200
201           For the number of CPUs that were read earlier, the
202           following is present:
203
204           8 bytes that are a 64-bit word containing the offset into the file
205           that holds the data for the CPU.
206
207           8 bytes that are a 64-bit word containing the size of the CPU
208           data at that offset.
209

CPU DATA

211           The CPU data is located in the part of the file that is specified
212           in the end of the header. Padding is placed between the header and
213           the CPU data, placing the CPU data at a page aligned (target page) position
214           in the file.
215
216           This data is copied directly from the Ftrace ring buffer and is of the
217           same format as the ring buffer specified by the event header files
218           loaded in the header format file.
219
220           The trace-cmd tool will try to \fBmmap(2)\fR the data page by page with the
221           target's page size if possible. If it fails to mmap, it will just read the
222           data instead.
223

SEE ALSO

225       trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1),
226       trace-cmd-start(1), trace-cmd-stop(1), trace-cmd-extract(1),
227       trace-cmd-reset(1), trace-cmd-split(1), trace-cmd-list(1),
228       trace-cmd-listen(1), trace-cmd.dat(5)
229

AUTHOR

231       Written by Steven Rostedt, <rostedt@goodmis.org[1]>
232

RESOURCES

234       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
235

COPYING

237       Copyright (C) 2010 Red Hat, Inc. Free use of this software is granted
238       under the terms of the GNU Public License (GPL).
239

NOTES

241        1. rostedt@goodmis.org
242           mailto:rostedt@goodmis.org
243
244
245
246libtracefs                        04/15/2022                TRACE-CMD.DAT.V(5)
Impressum