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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>XRay Flight Data Recorder Trace Format — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="YAML I/O" href="YamlIO.html" />
<link rel="prev" title="Debugging with XRay" href="XRayExample.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="YamlIO.html" title="YAML I/O"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="XRayExample.html" title="Debugging with XRay"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="Reference.html" accesskey="U">Reference</a> »</li>
<li class="nav-item nav-item-this"><a href="">XRay Flight Data Recorder Trace Format</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/XRayFDRFormat.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="xray-flight-data-recorder-trace-format">
<h1>XRay Flight Data Recorder Trace Format<a class="headerlink" href="#xray-flight-data-recorder-trace-format" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Version</dt>
<dd class="field-odd"><p>1 as of 2017-07-20</p>
</dd>
</dl>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id1">Introduction</a></p></li>
<li><p><a class="reference internal" href="#general" id="id2">General</a></p></li>
<li><p><a class="reference internal" href="#header-section" id="id3">Header Section</a></p></li>
<li><p><a class="reference internal" href="#data-section" id="id4">Data Section</a></p>
<ul>
<li><p><a class="reference internal" href="#function-records" id="id5">Function Records</a></p></li>
<li><p><a class="reference internal" href="#metadata-records" id="id6">Metadata Records</a></p></li>
<li><p><a class="reference internal" href="#newbuffer-records" id="id7">NewBuffer Records</a></p></li>
<li><p><a class="reference internal" href="#wallclocktime-records" id="id8">WallClockTime Records</a></p></li>
<li><p><a class="reference internal" href="#newcpuid-records" id="id9">NewCpuId Records</a></p></li>
<li><p><a class="reference internal" href="#tscwrap-records" id="id10">TSCWrap Records</a></p></li>
<li><p><a class="reference internal" href="#callargument-records" id="id11">CallArgument Records</a></p></li>
<li><p><a class="reference internal" href="#customeventmarker-records" id="id12">CustomEventMarker Records</a></p></li>
<li><p><a class="reference internal" href="#endofbuffer-records" id="id13">EndOfBuffer Records</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#format-grammar-and-invariants" id="id14">Format Grammar and Invariants</a></p>
<ul>
<li><p><a class="reference internal" href="#function-record-order" id="id15">Function Record Order</a></p></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>When gathering XRay traces in Flight Data Recorder mode, each thread of an
application will claim buffers to fill with trace data, which at some point
is finalized and flushed.</p>
<p>A goal of the profiler is to minimize overhead, the flushed data directly
corresponds to the buffer.</p>
<p>This document describes the format of a trace file.</p>
</div>
<div class="section" id="general">
<h2><a class="toc-backref" href="#id2">General</a><a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
<p>Each trace file corresponds to a sequence of events in a particular thread.</p>
<p>The file has a header followed by a sequence of discriminated record types.</p>
<p>The endianness of byte fields matches the endianness of the platform which
produced the trace file.</p>
</div>
<div class="section" id="header-section">
<h2><a class="toc-backref" href="#id3">Header Section</a><a class="headerlink" href="#header-section" title="Permalink to this headline">¶</a></h2>
<p>A trace file begins with a 32 byte header.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 25%" />
<col style="width: 22%" />
<col style="width: 53%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>version</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
<td><p>Anticipates versioned readers. This
document describes the format when
version == 1</p></td>
</tr>
<tr class="row-odd"><td><p>type</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
<td><p>An enumeration encoding the type of
trace. Flight Data Recorder mode
traces have type == 1</p></td>
</tr>
<tr class="row-even"><td><p>bitfield</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">4</span></code></p></td>
<td><p>Holds parameters that are not aligned
to bytes. Further described below.</p></td>
</tr>
<tr class="row-odd"><td><p>cycle_frequency</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>The frequency in hertz of the CPU
oscillator used to measure duration of
events in ticks.</p></td>
</tr>
<tr class="row-even"><td><p>buffer_size</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>The size in bytes of the data portion
of the trace following the header.</p></td>
</tr>
<tr class="row-odd"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>Reserved for future use.</p></td>
</tr>
</tbody>
</table>
<p>The bitfield parameter of the file header is composed of the following fields.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 25%" />
<col style="width: 21%" />
<col style="width: 54%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bits)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>constant_tsc</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
<td><p>Whether the platform’s timestamp
counter used to record ticks between
events ticks at a constant frequency
despite CPU frequency changes.
0 == non-constant. 1 == constant.</p></td>
</tr>
<tr class="row-odd"><td><p>nonstop_tsc</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
<td><p>Whether the tsc continues to count
despite whether the CPU is in a low
power state. 0 == stop. 1 == non-stop.</p></td>
</tr>
<tr class="row-even"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">30</span></code></p></td>
<td><p>Not meaningful.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="data-section">
<h2><a class="toc-backref" href="#id4">Data Section</a><a class="headerlink" href="#data-section" title="Permalink to this headline">¶</a></h2>
<p>Following the header in a trace is a data section with size matching the
buffer_size field in the header.</p>
<p>The data section is a stream of elements of different types.</p>
<p>There are a few categories of data in the sequence.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">Function</span> <span class="pre">Records</span></code>: Function Records contain the timing of entry into and
exit from function execution. Function Records have 8 bytes each.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Metadata</span> <span class="pre">Records</span></code>: Metadata records serve many purposes. Mostly, they
capture information that may be too costly to record for each function, but
that is required to contextualize the fine-grained timings. They also are used
as markers for user-defined Event Data payloads. Metadata records have 16
bytes each.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Event</span> <span class="pre">Data</span></code>: Free form data may be associated with events that are traced
by the binary and encode data defined by a handler function. Event data is
always preceded with a marker record which indicates how large it is.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Function</span> <span class="pre">Arguments</span></code>: The arguments to some functions are included in the
trace. These are either pointer addresses or primitives that are read and
logged independently of their types in a high level language. To the tracer,
they are all numbers. Function Records that have attached arguments will
indicate their presence on the function entry record. We only support logging
contiguous function argument sequences starting with argument zero, which will
be the “this” pointer for member function invocations. For example, we don’t
support logging the first and third argument.</p></li>
</ul>
<p>A reader of the memory format must maintain a state machine. The format makes no
attempt to pad for alignment, and it is not seekable.</p>
<div class="section" id="function-records">
<h3><a class="toc-backref" href="#id5">Function Records</a><a class="headerlink" href="#function-records" title="Permalink to this headline">¶</a></h3>
<p>Function Records have an 8 byte layout. This layout encodes information to
reconstruct a call stack of instrumented function and their durations.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bits)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>discriminant</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
<td><p>Indicates whether a reader should read a
Function or Metadata record. Set to <code class="docutils literal notranslate"><span class="pre">0</span></code> for
Function records.</p></td>
</tr>
<tr class="row-odd"><td><p>action</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">3</span></code></p></td>
<td><p>Specifies whether the function is being
entered, exited, or is a non-standard entry
or exit produced by optimizations.</p></td>
</tr>
<tr class="row-even"><td><p>function_id</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">28</span></code></p></td>
<td><p>A numeric ID for the function. Resolved to a
name via the xray instrumentation map. The
instrumentation map is built by xray at
compile time into an object file and pairs
the function ids to addresses. It is used for
patching and as a lookup into the binary’s
symbols to obtain names.</p></td>
</tr>
<tr class="row-odd"><td><p>tsc_delta</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">32</span></code></p></td>
<td><p>The number of ticks of the timestamp counter
since a previous record recorded a delta or
other TSC resetting event.</p></td>
</tr>
</tbody>
</table>
<p>On little-endian machines, the bitfields are ordered from least significant bit
bit to most significant bit. A reader can read an 8 bit value and apply the mask
<code class="docutils literal notranslate"><span class="pre">0x01</span></code> for the discriminant. Similarly, they can read 32 bits and unsigned
shift right by <code class="docutils literal notranslate"><span class="pre">0x04</span></code> to obtain the function_id field.</p>
<p>On big-endian machine, the bitfields are written in order from most significant
bit to least significant bit. A reader would read an 8 bit value and unsigned
shift right by 7 bits for the discriminant. The function_id field could be
obtained by reading a 32 bit value and applying the mask <code class="docutils literal notranslate"><span class="pre">0x0FFFFFFF</span></code>.</p>
<p>Function action types are as follows.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Type</p></th>
<th class="head"><p>Number</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Entry</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>
<td><p>Typical function entry.</p></td>
</tr>
<tr class="row-odd"><td><p>Exit</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
<td><p>Typical function exit.</p></td>
</tr>
<tr class="row-even"><td><p>Tail_Exit</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
<td><p>An exit from a function due to tail call
optimization.</p></td>
</tr>
<tr class="row-odd"><td><p>Entry_Args</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">3</span></code></p></td>
<td><p>A function entry that records arguments.</p></td>
</tr>
</tbody>
</table>
<p>Entry_Args records do not contain the arguments themselves. Instead, metadata
records for each of the logged args follow the function record in the stream.</p>
</div>
<div class="section" id="metadata-records">
<h3><a class="toc-backref" href="#id6">Metadata Records</a><a class="headerlink" href="#metadata-records" title="Permalink to this headline">¶</a></h3>
<p>Interspersed throughout the buffer are 16 byte Metadata records. For typically
instrumented binaries, they will be sparser than Function records, and they
provide a fuller picture of the binary execution state.</p>
<p>Metadata record layout is partially record dependent, but they share a common
structure.</p>
<p>The same bit field rules described for function records apply to the first byte
of MetadataRecords. Within this byte, little endian machines use lsb to msb
ordering and big endian machines use msb to lsb ordering.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>discriminant</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre">bit</span></code></p></td>
<td><p>Indicates whether a reader should read a
Function or Metadata record. Set to <code class="docutils literal notranslate"><span class="pre">1</span></code> for
Metadata records.</p></td>
</tr>
<tr class="row-odd"><td><p>record_kind</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">7</span> <span class="pre">bits</span></code></p></td>
<td><p>The type of Metadata record.</p></td>
</tr>
<tr class="row-even"><td><p>data</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">15</span> <span class="pre">bytes</span></code></p></td>
<td><p>A data field used differently for each record
type.</p></td>
</tr>
</tbody>
</table>
<p>Here is a table of the enumerated record kinds.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 23%" />
<col style="width: 77%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Number</p></th>
<th class="head"><p>Type</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>0</p></td>
<td><p>NewBuffer</p></td>
</tr>
<tr class="row-odd"><td><p>1</p></td>
<td><p>EndOfBuffer</p></td>
</tr>
<tr class="row-even"><td><p>2</p></td>
<td><p>NewCPUId</p></td>
</tr>
<tr class="row-odd"><td><p>3</p></td>
<td><p>TSCWrap</p></td>
</tr>
<tr class="row-even"><td><p>4</p></td>
<td><p>WallTimeMarker</p></td>
</tr>
<tr class="row-odd"><td><p>5</p></td>
<td><p>CustomEventMarker</p></td>
</tr>
<tr class="row-even"><td><p>6</p></td>
<td><p>CallArgument</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="newbuffer-records">
<h3><a class="toc-backref" href="#id7">NewBuffer Records</a><a class="headerlink" href="#newbuffer-records" title="Permalink to this headline">¶</a></h3>
<p>Each buffer begins with a NewBuffer record immediately after the header.
It records the thread ID of the thread that the trace belongs to.</p>
<p>Its data segment is as follows.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>thread_Id</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
<td><p>Thread ID for buffer.</p></td>
</tr>
<tr class="row-odd"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">13</span></code></p></td>
<td><p>Unused.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="wallclocktime-records">
<h3><a class="toc-backref" href="#id8">WallClockTime Records</a><a class="headerlink" href="#wallclocktime-records" title="Permalink to this headline">¶</a></h3>
<p>Following the NewBuffer record, each buffer records an absolute time as a frame
of reference for the durations recorded by timestamp counter deltas.</p>
<p>Its data segment is as follows.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>seconds</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>Seconds on absolute timescale. The starting
point is unspecified and depends on the
implementation and platform configured by the
tracer.</p></td>
</tr>
<tr class="row-odd"><td><p>microseconds</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">4</span></code></p></td>
<td><p>The microsecond component of the time.</p></td>
</tr>
<tr class="row-even"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">3</span></code></p></td>
<td><p>Unused.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="newcpuid-records">
<h3><a class="toc-backref" href="#id9">NewCpuId Records</a><a class="headerlink" href="#newcpuid-records" title="Permalink to this headline">¶</a></h3>
<p>Each function entry invokes a routine to determine what CPU is executing.
Typically, this is done with readtscp, which reads the timestamp counter at the
same time.</p>
<p>If the tracing detects that the execution has switched CPUs or if this is the
first instrumented entry point, the tracer will output a NewCpuId record.</p>
<p>Its data segment is as follows.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>cpu_id</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
<td><p>CPU Id.</p></td>
</tr>
<tr class="row-odd"><td><p>absolute_tsc</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>The absolute value of the timestamp counter.</p></td>
</tr>
<tr class="row-even"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">5</span></code></p></td>
<td><p>Unused.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="tscwrap-records">
<h3><a class="toc-backref" href="#id10">TSCWrap Records</a><a class="headerlink" href="#tscwrap-records" title="Permalink to this headline">¶</a></h3>
<p>Since each function record uses a 32 bit value to represent the number of ticks
of the timestamp counter since the last reference, it is possible for this value
to overflow, particularly for sparsely instrumented binaries.</p>
<p>When this delta would not fit into a 32 bit representation, a reference absolute
timestamp counter record is written in the form of a TSCWrap record.</p>
<p>Its data segment is as follows.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>absolute_tsc</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>Timestamp counter value.</p></td>
</tr>
<tr class="row-odd"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">7</span></code></p></td>
<td><p>Unused.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="callargument-records">
<h3><a class="toc-backref" href="#id11">CallArgument Records</a><a class="headerlink" href="#callargument-records" title="Permalink to this headline">¶</a></h3>
<p>Immediately following an Entry_Args type function record, there may be one or
more CallArgument records that contain the traced function’s parameter values.</p>
<p>The order of the CallArgument Record sequency corresponds one to one with the
order of the function parameters.</p>
<p>CallArgument data segment:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>argument</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>Numeric argument (may be pointer address).</p></td>
</tr>
<tr class="row-odd"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">7</span></code></p></td>
<td><p>Unused.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="customeventmarker-records">
<h3><a class="toc-backref" href="#id12">CustomEventMarker Records</a><a class="headerlink" href="#customeventmarker-records" title="Permalink to this headline">¶</a></h3>
<p>XRay provides the feature of logging custom events. This may be leveraged to
record tracing info for RPCs or similarly trace data that is application
specific.</p>
<p>Custom Events themselves are an unstructured (application defined) segment of
memory with arbitrary size within the buffer. They are preceded by
CustomEventMarkers to indicate their presence and size.</p>
<p>CustomEventMarker data segment:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 20%" />
<col style="width: 18%" />
<col style="width: 62%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Size (bytes)</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>event_size</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">4</span></code></p></td>
<td><p>Size of preceded event.</p></td>
</tr>
<tr class="row-odd"><td><p>absolute_tsc</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">8</span></code></p></td>
<td><p>A timestamp counter of the event.</p></td>
</tr>
<tr class="row-even"><td><p>reserved</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">3</span></code></p></td>
<td><p>Unused.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="endofbuffer-records">
<h3><a class="toc-backref" href="#id13">EndOfBuffer Records</a><a class="headerlink" href="#endofbuffer-records" title="Permalink to this headline">¶</a></h3>
<p>An EndOfBuffer record type indicates that there is no more trace data in this
buffer. The reader is expected to seek past the remaining buffer_size expressed
before the start of buffer and look for either another header or EOF.</p>
</div>
</div>
<div class="section" id="format-grammar-and-invariants">
<h2><a class="toc-backref" href="#id14">Format Grammar and Invariants</a><a class="headerlink" href="#format-grammar-and-invariants" title="Permalink to this headline">¶</a></h2>
<p>Not all sequences of Metadata records and Function records are valid data. A
sequence should be parsed as a state machine. The expectations for a valid
format can be expressed as a context free grammar.</p>
<p>This is an attempt to explain the format with statements in EBNF format.</p>
<ul class="simple">
<li><p>Format := Header ThreadBuffer* EOF</p></li>
<li><p>ThreadBuffer := NewBuffer WallClockTime NewCPUId BodySequence* End</p></li>
<li><p>BodySequence := NewCPUId | TSCWrap | Function | CustomEvent</p></li>
<li><p>Function := (Function_Entry_Args CallArgument*) | Function_Other_Type</p></li>
<li><p>CustomEvent := CustomEventMarker CustomEventUnstructuredMemory</p></li>
<li><p>End := EndOfBuffer RemainingBufferSizeToSkip</p></li>
</ul>
<div class="section" id="function-record-order">
<h3><a class="toc-backref" href="#id15">Function Record Order</a><a class="headerlink" href="#function-record-order" title="Permalink to this headline">¶</a></h3>
<p>There are a few clarifications that may help understand what is expected of
Function records.</p>
<ul class="simple">
<li><p>Functions with an Exit are expected to have a corresponding Entry or
Entry_Args function record precede them in the trace.</p></li>
<li><p>Tail_Exit Function records record the Function ID of the function whose return
address the program counter will take. In other words, the final function that
would be popped off of the call stack if tail call optimization was not used.</p></li>
<li><p>Not all functions marked for instrumentation are necessarily in the trace. The
tracer uses heuristics to preserve the trace for non-trivial functions.</p></li>
<li><p>Not every entry must have a traced Exit or Tail Exit. The buffer may run out
of space or the program may request for the tracer to finalize toreturn the
buffer before an instrumented function exits.</p></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="YamlIO.html" title="YAML I/O"
>next</a> |</li>
<li class="right" >
<a href="XRayExample.html" title="Debugging with XRay"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="Reference.html" >Reference</a> »</li>
<li class="nav-item nav-item-this"><a href="">XRay Flight Data Recorder Trace Format</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
