<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style>
</head>
<body dir="ltr">
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<div style="box-sizing:border-box;font-family:"Segoe UI", system-ui, "Apple Color Emoji", "Segoe UI Emoji", sans-serif;font-size:14px;orphans:2;widows:2">
<div style="font-size:12pt">Hi Philippe,</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt">Great proposal, I have some _quick_ feedback.</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt">I tried the mental exercise of reading the example 8 and being a matthew-based-parser. It would have been much easier if you make a table, let's say 3.1 where the description column is the first column, or the key of table 3.</div>
<div style="font-size:12pt"><br>
</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt">Example:</div>
<div style="font-size:12pt">
<table class="copy-paste-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Required?</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>type</code></td>
<td>JSON string</td>
<td>Type of <em><strong>F</strong></em>.The value of this property <em>MUST</em> be one of:
<dl><dt><code>"fixed-length-bit-array"</code> </dt><dd><em><strong>F</strong></em> is a <a href="https://diamon.org/ctf/files/CTF2-PROP-2.0.html#fl-ba-fc" rel="noreferrer noopener" target="_blank" title="https://diamon.org/ctf/files/ctf2-prop-2.0.html#fl-ba-fc" tabindex="-1">
fixed-length bit array field class</a>. </dd><dt><code>"fixed-length-boolean"</code> </dt><dd><em><strong>F</strong></em> is a <a href="https://diamon.org/ctf/files/CTF2-PROP-2.0.html#fl-bool-fc" rel="noreferrer noopener" target="_blank" title="https://diamon.org/ctf/files/ctf2-prop-2.0.html#fl-bool-fc" tabindex="-1">
fixed-length boolean field class</a>. </dd></dl>
</td>
<td>Yes</td>
<td></td>
</tr>
</tbody>
</table>
</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt"><br>
</div>
<div style="font-size:12pt">Would make a new table (in CSV)</div>
<div style="font-size:12pt"><br>
</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt">Value, Type, Description</div>
<div style="font-size:12pt">fixes-length-bit-array, JSON string, A <em>fixed-length bit array</em> field class describes
<em>fixed-length bit array</em> fields.</div>
<div style="font-size:12pt">fixes-length-boolean-field, JSON string, <br>
<div>
<p>A <em>fixed-length boolean</em> field class is a <a href="https://diamon.org/ctf/files/CTF2-PROP-2.0.html#fl-ba-fc" rel="noreferrer noopener" target="_blank" title="https://diamon.org/ctf/files/ctf2-prop-2.0.html#fl-ba-fc" tabindex="-1">
fixed-length bit array field class</a> which describes <em>fixed-length boolean</em> fields.</p>
</div>
</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt"><br>
</div>
<div style="font-size:12pt">Potentially extremely out of scope</div>
<div style="font-size:12pt"></div>
<div style="font-size:12pt"><br>
</div>
<div style="font-size:12pt">Another general feedback would be that CTF is a data transport layer, it is information rich in the sense that it will tell you what the type of data is though. Would it be interesting to have a protocol ABOVE CTF to define a common
way to specify data and make visualizing it easier? If you look at the open tracing API or trace event (google), they have examples, but in the case of CTF, I suggest considering the following with the equivalent UI element:</div>
<div style="font-size:12pt">
<ul>
<li>stack entry-exit, (nested are guaranteed to be smaller) </li><li>request begin-end (nested may be any size) </li><li>lifespan create-destroy, (cannot nest) </li><li>message begin-end (link stacks or requests) </li><li>instant (add a tick) </li><li>frame start-frame end (contiguous global info, cannot have overlapping, think fps)
</li><li>stack (link to code) </li></ul>
<div>BR</div>
<div>Matthew</div>
</div>
</div>
<br>
</div>
<div id="appendonsend"></div>
<hr style="display:inline-block;width:98%" tabindex="-1">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" style="font-size:11pt" color="#000000"><b>From:</b> tracecompass-dev-bounces@eclipse.org <tracecompass-dev-bounces@eclipse.org> on behalf of tracecompass developer discussions <tracecompass-dev@eclipse.org><br>
<b>Sent:</b> Wednesday, November 18, 2020 3:30 PM<br>
<b>To:</b> diamon-discuss <diamon-discuss@lists.linuxfoundation.org><br>
<b>Cc:</b> lttng-dev <lttng-dev@lists.lttng.org>; tracecompass-dev <tracecompass-dev@eclipse.org><br>
<b>Subject:</b> [tracecompass-dev] CTF2-PROP-2.0: Proposal for a major revision of the Common Trace Format, version 1.8</font>
<div> </div>
</div>
<div class="BodyFragment"><font size="2"><span style="font-size:11pt;">
<div class="PlainText">Hello, people of the tracing world!<br>
<br>
This is a major revision of the proposal for a major revision of<br>
the Common Trace Format 1.8 (to CTF 2).<br>
<br>
This document, named CTF2-PROP-2.0, is available here:<br>
<br>
<<a href="https://protect2.fireeye.com/v1/url?k=89400b0d-d6db3148-89404b96-867b36d1634c-fa63be98dee74bde&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-2.0.html">https://protect2.fireeye.com/v1/url?k=89400b0d-d6db3148-89404b96-867b36d1634c-fa63be98dee74bde&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-2.0.html</a>><br>
<br>
It's a revision of CTF2-PROP-1.0 which I sent to this mailing list<br>
on October 25 2016:<br>
<br>
<<a href="https://protect2.fireeye.com/v1/url?k=86d7e626-d94cdc63-86d7a6bd-867b36d1634c-655d3ceeba08f19a&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html">https://protect2.fireeye.com/v1/url?k=86d7e626-d94cdc63-86d7a6bd-867b36d1634c-655d3ceeba08f19a&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html</a>><br>
<br>
I'm copying the AsciiDoc source here so that you can inline-comment it.<br>
If you do so, _please_ keep only a few lines of context (only what's<br>
necessary) above and below any comment, because the source has about<br>
6000 lines of text.<br>
<br>
Thank you for your comments!<br>
<br>
Philippe Proulx<br>
EfficiOS Inc.<br>
<a href="https://protect2.fireeye.com/v1/url?k=28b9d28c-7722e8c9-28b99217-867b36d1634c-2745ea8ed85463a9&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=http%3A%2F%2Fwww.efficios.com%2F">https://protect2.fireeye.com/v1/url?k=28b9d28c-7722e8c9-28b99217-867b36d1634c-2745ea8ed85463a9&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=http%3A%2F%2Fwww.efficios.com%2F</a><br>
<br>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<br>
<br>
// Please render with Asciidoctor<br>
<br>
= **CTF2-PROP-2.0**: Proposal for a major revision of the Common Trace<br>
Format, version 1.8<br>
Philippe Proulx <pproulx@efficios.com><br>
v2.0, 18 November 2020<br>
:attribute-missing: warn<br>
:icons: font<br>
:nofooter:<br>
:sectnums:<br>
:sectnumlevels: 5<br>
:toc: left<br>
:toclevels: 3<br>
:nbh: ‑<br>
:minus: −<br>
:times: ×<br>
:noteq: ≠<br>
:ieee754: <a href="https://standards.ieee.org/standard/754-2008.html[IEEE">https://standards.ieee.org/standard/754-2008.html[IEEE</a><br>
754-2008]'s binary interchange format<br>
:ctf1-nl: CTF{nbsp}1<br>
:ctf1: <a href="https://protect2.fireeye.com/v1/url?k=32b6763d-6d2d4c78-32b636a6-867b36d1634c-8fa7e342363b715f&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Fv1.8.3%2F%5B%257Bctf1-nl}">
https://protect2.fireeye.com/v1/url?k=32b6763d-6d2d4c78-32b636a6-867b36d1634c-8fa7e342363b715f&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Fv1.8.3%2F%5B%257Bctf1-nl}</a>]<br>
:ctf2: CTF{nbsp}2<br>
:fl-ba: fixed-length bit array<br>
:c-fl-ba: Fixed-length bit array<br>
:vl-ba: variable-length bit array<br>
:c-vl-ba: Variable-length bit array<br>
:fl-bool: fixed-length boolean<br>
:c-fl-bool: Fixed-length boolean<br>
:fl-int: fixed-length integer<br>
:c-fl-int: Fixed-length integer<br>
:fl-uint: fixed-length unsigned integer<br>
:c-fl-uint: Fixed-length unsigned integer<br>
:fl-sint: fixed-length signed integer<br>
:c-fl-sint: Fixed-length signed integer<br>
:vl-int: variable-length integer<br>
:c-vl-int: Variable-length integer<br>
:vl-uint: variable-length unsigned integer<br>
:c-vl-uint: Variable-length unsigned integer<br>
:vl-sint: variable-length signed integer<br>
:c-vl-sint: Variable-length signed integer<br>
:fl-enum: fixed-length enumeration<br>
:c-fl-enum: Fixed-length enumeration<br>
:fl-uenum: fixed-length unsigned enumeration<br>
:c-fl-uenum: Fixed-length unsigned enumeration<br>
:fl-senum: fixed-length signed enumeration<br>
:c-fl-senum: Fixed-length signed enumeration<br>
:vl-enum: variable-length enumeration<br>
:c-vl-enum: Variable-length enumeration<br>
:vl-uenum: variable-length unsigned enumeration<br>
:c-vl-uenum: Variable-length unsigned enumeration<br>
:vl-senum: variable-length signed enumeration<br>
:c-vl-senum: Variable-length signed enumeration<br>
:fl-fp: fixed-length floating point number<br>
:c-fl-fp: Fixed-length floating point number<br>
:str: null-terminated string<br>
:c-str: Null-terminated string<br>
:sl-array: static-length array<br>
:c-sl-array: Static-length array<br>
:sl-str: static-length string<br>
:c-sl-str: Static-length string<br>
:dl-array: dynamic-length array<br>
:c-dl-array: Dynamic-length array<br>
:dl-str: dynamic-length string<br>
:c-dl-str: Dynamic-length string<br>
:sl-blob: static-length BLOB<br>
:c-sl-blob: Static-length BLOB<br>
:dl-blob: dynamic-length BLOB<br>
:c-dl-blob: Dynamic-length BLOB<br>
:fl-ba-fc: <<fl-ba-fc,fixed-length bit array field class>><br>
:c-fl-ba-fc: <<fl-ba-fc,Fixed-length bit array field class>><br>
:vl-ba-fc: <<vl-ba-fc,variable-length bit array field class>><br>
:c-vl-ba-fc: <<vl-ba-fc,Variable-length bit array field class>><br>
:fl-bool-fc: <<fl-bool-fc,fixed-length boolean field class>><br>
:c-fl-bool-fc: <<fl-bool-fc,Fixed-length boolean field class>><br>
:fl-int-fc: <<fl-int-fc,fixed-length integer field class>><br>
:c-fl-int-fc: <<fl-int-fc,Fixed-length integer field class>><br>
:fl-uint-fc: <<fl-int-fc,fixed-length unsigned integer field class>><br>
:c-fl-uint-fc: <<fl-int-fc,Fixed-length unsigned integer field class>><br>
:fl-sint-fc: <<fl-int-fc,fixed-length signed integer field class>><br>
:c-fl-sint-fc: <<fl-int-fc,Fixed-length signed integer field class>><br>
:vl-int-fc: <<vl-int-fc,variable-length integer field class>><br>
:c-vl-int-fc: <<vl-int-fc,Variable-length integer field class>><br>
:vl-uint-fc: <<vl-int-fc,variable-length unsigned integer field class>><br>
:c-vl-uint-fc: <<vl-int-fc,Variable-length unsigned integer field class>><br>
:vl-sint-fc: <<vl-int-fc,variable-length signed integer field class>><br>
:c-vl-sint-fc: <<vl-int-fc,Variable-length signed integer field class>><br>
:fl-enum-fc: <<fl-enum-fc,fixed-length enumeration field class>><br>
:c-fl-enum-fc: <<fl-enum-fc,Fixed-length enumeration field class>><br>
:fl-uenum-fc: <<fl-enum-fc,fixed-length unsigned enumeration field class>><br>
:c-fl-uenum-fc: <<fl-enum-fc,Fixed-length unsigned enumeration field class>><br>
:fl-senum-fc: <<fl-enum-fc,fixed-length signed enumeration field class>><br>
:c-fl-senum-fc: <<fl-enum-fc,Fixed-length signed enumeration field class>><br>
:vl-enum-fc: <<vl-enum-fc,variable-length enumeration field class>><br>
:c-vl-enum-fc: <<vl-enum-fc,Variable-length enumeration field class>><br>
:vl-uenum-fc: <<vl-enum-fc,variable-length unsigned enumeration field class>><br>
:c-vl-uenum-fc: <<vl-enum-fc,Variable-length unsigned enumeration field class>><br>
:vl-senum-fc: <<vl-enum-fc,variable-length signed enumeration field class>><br>
:c-vl-senum-fc: <<vl-enum-fc,Variable-length signed enumeration field class>><br>
:fl-fp-fc: <<fl-fp-fc,fixed-length floating point number field class>><br>
:c-fl-fp-fc: <<fl-fp-fc,Fixed-length floating point number field class>><br>
:str-fc: <<str-fc,null-terminated string field class>><br>
:c-str-fc: <<str-fc,Null-terminated string field class>><br>
:sl-array-fc: <<sl-array-fc,static-length array field class>><br>
:c-sl-array-fc: <<sl-array-fc,Static-length array field class>><br>
:sl-str-fc: <<sl-str-fc,static-length string field class>><br>
:c-sl-str-fc: <<sl-str-fc,Static-length string field class>><br>
:dl-array-fc: <<dl-array-fc,dynamic-length array field class>><br>
:c-dl-array-fc: <<dl-array-fc,Dynamic-length array field class>><br>
:dl-str-fc: <<dl-str-fc,dynamic-length string field class>><br>
:c-dl-str-fc: <<dl-str-fc,Dynamic-length string field class>><br>
:sl-blob-fc: <<sl-blob-fc,static-length BLOB field class>><br>
:c-sl-blob-fc: <<sl-blob-fc,Static-length BLOB field class>><br>
:dl-blob-fc: <<dl-blob-fc,dynamic-length BLOB field class>><br>
:c-dl-blob-fc: <<dl-blob-fc,Dynamic-length BLOB field class>><br>
:struct-fc: <<struct-fc,structure field class>><br>
:c-struct-fc: <<struct-fc,Structure field class>><br>
:opt-fc: <<opt-fc,optional field class>><br>
:c-opt-fc: <<opt-fc,Optional field class>><br>
:var-fc: <<var-fc,variant field class>><br>
:c-var-fc: <<var-fc,Variant field class>><br>
:diamon: <a href="https://protect2.fireeye.com/v1/url?k=c6f67cca-996d468f-c6f63c51-867b36d1634c-ccf548966b1a6170&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2F%5BDiaMon">
https://protect2.fireeye.com/v1/url?k=c6f67cca-996d468f-c6f63c51-867b36d1634c-ccf548966b1a6170&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2F%5BDiaMon</a> Workgroup]<br>
:c-bo: <a href="https://en.wikipedia.org/wiki/Endianness[Byte">https://en.wikipedia.org/wiki/Endianness[Byte</a> order]<br>
:must: pass:q[__MUST__]<br>
:must-not: pass:q[__MUST NOT__]<br>
:required: pass:q[__REQUIRED__]<br>
:should: pass:q[__SHOULD__]<br>
:should-not: pass:q[__SHOULD NOT__]<br>
:may: pass:q[__MAY__]<br>
:optional: pass:q[__OPTIONAL__]<br>
:var-f: pass:q[__**F**__]<br>
:var-o: pass:q[__**O**__]<br>
:var-v: pass:q[__**V**__]<br>
:var-p: pass:q[__**P**__]<br>
:var-s: pass:q[__**S**__]<br>
:var-po: pass:q[__**PO**__]<br>
:var-o-minus-po: pass:q[__**O**__ − __**PO**__]<br>
:doc-id: pass:q[__**CTF2-PROP-2.0**__]<br>
<br>
This document is an informal proposal for the next major revision of the<br>
**Common Trace Format** (CTF) version{nbsp}2 (hereafter named _{ctf2}_).<br>
<br>
This is _not_ a formal reference. Some parts of this document, however,<br>
may be formal enough to be elligible for a specification document.<br>
<br>
.RFC 2119<br>
IMPORTANT: The key words {must}, {must-not}, {required},<br>
{should}, {should-not}, {may}, and {optional} in this document, when<br>
emphasized, are to be interpreted as described in<br>
<a href="https://www.ietf.org/rfc/rfc2119.txt[RFC{nbsp}2119">https://www.ietf.org/rfc/rfc2119.txt[RFC{nbsp}2119</a>].<br>
<br>
== Revision history<br>
<br>
Significant changes since<br>
<a href="https://protect2.fireeye.com/v1/url?k=98714279-c7ea783c-987102e2-867b36d1634c-8e327483f8f20aba&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html%5B_%2A%2ACTF2-PROP-1.0%2A%2A_]:">https://protect2.fireeye.com/v1/url?k=98714279-c7ea783c-987102e2-867b36d1634c-8e327483f8f20aba&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html%5B_%2A%2ACTF2-PROP-1.0%2A%2A_]:</a><br>
<br>
* Written in <a href="https://protect2.fireeye.com/v1/url?k=84af5bb3-db3461f6-84af1b28-867b36d1634c-fd327bcde7e315c5&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fasciidoctor.org%2F%5BAsciidoctor%5D%27s">
https://protect2.fireeye.com/v1/url?k=84af5bb3-db3461f6-84af1b28-867b36d1634c-fd327bcde7e315c5&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fasciidoctor.org%2F%5BAsciidoctor%5D%27s</a> AsciiDoc syntax.<br>
+<br>
The original AsciiDoc project is pretty much deprecated.<br>
+<br>
Asciidoctor is also what GitHub, GitLab, and more use to render<br>
AsciiDoc documents.<br>
<br>
* Terminology update.<br>
+<br>
See the <<term-update,{ctf2} terminology update>>.<br>
<br>
* Mostly written from the consumer's perspective, especially the<br>
<<ds-dec,data stream decoding procedure>>.<br>
<br>
* Metadata types are removed: the document uses JSON directly now.<br>
+<br>
This makes the specification easier to read, removing one nonessential<br>
abstraction layer.<br>
<br>
* Constant integer JSON object is removed: we can use plain JSON<br>
integers.<br>
<br>
* Splitting the specification into three layers is removed: the document<br>
specifies the whole format monolithically.<br>
+<br>
This makes the specification easier to read.<br>
<br>
* **Format simplifications**:<br>
<br>
** <<tc-frag,Trace class>>'s default/native byte order property is<br>
removed: a {fl-ba-fc} {must} have an explicit byte order property.<br>
<br>
** Not all <<fc,field classes>> have an alignment property: only a<br>
{fl-ba-fc}, and all the field classes which inherit it, need one.<br>
+<br>
To remain backward compatible with {ctf1}, a {struct-fc} still needs a<br>
_minimum_ alignment property.<br>
<br>
** Relative field location (field path in<br>
<a href="https://protect2.fireeye.com/v1/url?k=25738848-7ae8b20d-2573c8d3-867b36d1634c-956299cfe47af8a5&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html%5B_%2A%2ACTF2-PROP-1.0%2A%2A_">
https://protect2.fireeye.com/v1/url?k=25738848-7ae8b20d-2573c8d3-867b36d1634c-956299cfe47af8a5&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html%5B_%2A%2ACTF2-PROP-1.0%2A%2A_</a>])<br>
is removed.<br>
+<br>
You can always use absolute <<field-loc,field locations>>.<br>
<br>
** Field class aliases are removed.<br>
<br>
** "`Tags`" replaced with <<roles,roles>> attached to <<fc,field<br>
classes>>.<br>
+<br>
It makes sense for a field class to have a role now that each field<br>
class is unique (no field class aliases).<br>
<br>
** A <<ds,data stream>> {may} have a single <<def-clk,default clock>>.<br>
Therefore, a <<dsc-frag,data stream class>> {may} have a single,<br>
default <<cc-frag,clock class>>.<br>
+<br>
This is enough to satisfy the current use cases.<br>
<br>
** Null, variable-length boolean, and union field classes are removed:<br>
we don't have use cases for them.<br>
<br>
* {c-opt-fc} added.<br>
+<br>
This is why<br>
<a href="https://protect2.fireeye.com/v1/url?k=e8634e5c-b7f87419-e8630ec7-867b36d1634c-f650031c27b0f5b1&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html%5B_%2A%2ACTF2-PROP-1.0%2A%2A_">https://protect2.fireeye.com/v1/url?k=e8634e5c-b7f87419-e8630ec7-867b36d1634c-f650031c27b0f5b1&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fdiamon.org%2Fctf%2Ffiles%2FCTF2-PROP-1.0.html%5B_%2A%2ACTF2-PROP-1.0%2A%2A_</a>]<br>
introduced the null field class (removed in {doc-id}): in the<br>
end, a {var-fc} with a null field class option and another option really<br>
is an optional field class.<br>
<br>
* <<blob-fc,BLOB field classes>> added.<br>
+<br>
A BLOB field contains a<br>
<a href="https://en.wikipedia.org/wiki/Binary_large_object[BLOB">https://en.wikipedia.org/wiki/Binary_large_object[BLOB</a>].<br>
+<br>
Having dedicated static- and dynamic-length BLOB field classes instead<br>
of using static- and dynamic-length <<array-fc,array field classes>><br>
makes it possible for consumer APIs to provide the values of such fields<br>
as byte buffers.<br>
<br>
* An <<int-fc,integer field class>> {may} have a preferred display base,<br>
even if it's insignificant to <<field-dec,decode its fields>>, because<br>
this property exists in {ctf1} and makes the transition easier.<br>
<br>
* An <<ert-frag,event record class>> {may} have a name and other<br>
properties which exist in {ctf1-nl}, but which are insignificant to<br>
<<er-dec,decode its instances>>, because it makes the transition<br>
easier.<br>
<br>
* <<ext,Extension>> feature added.<br>
+<br>
This is how we plan to add core features and modify existing ones in the<br>
future without having to rely on a minor version.<br>
<br>
* <<aux-stream,Auxiliary stream>> feature added.<br>
<br>
== CTF publication authority<br>
<br>
The {diamon}, a <a href="https://www.linuxfoundation.org/[Linux">https://www.linuxfoundation.org/[Linux</a> Foundation]<br>
workgroup which creates de facto open standards and tools for tracing,<br>
monitoring, and diagnostics, oversees the Common Trace Format design and<br>
the publication of official CTF documents.<br>
<br>
The DiaMon Workgroup is also responsible for providing a platform for<br>
interested parties to comment on CTF-related proposals.<br>
<br>
== {ctf2} document identification<br>
<br>
We suggest that all official {ctf2} documents bear a unique **document<br>
identifier** (ID) having the following format:<br>
<br>
[verse]<br>
`CTF2-__SHORTNAME__-__MAJOR__.__MINOR__[r__REV__]`<br>
<br>
[%header%autowidth]<br>
.Descriptions and roles of {ctf2} document ID parts<br>
|===<br>
|Part |Description |Bump {may} introduce new concepts, procedures, and<br>
formats? |Bump {may} remove or change existing concepts, procedures,<br>
and formats?<br>
<br>
|`__SHORTNAME__`<br>
|The capitalized short name of the document, unique amongst all the<br>
official {ctf2} documents.<br>
|N/A<br>
|N/A<br>
<br>
|`__MAJOR__`<br>
|The major version number of the document.<br>
|Yes<br>
|Yes<br>
<br>
|`__MINOR__`<br>
|The minor version number of the document.<br>
|Yes<br>
|No<br>
<br>
|`__REV__`<br>
|The revision letter of the document (from `A` to `Z`, then `ZA` to<br>
`ZZ`, and so on).<br>
<br>
We'll use document revisions to add examples, clarify existing concepts,<br>
or fix grammar/content mistakes, for example.<br>
|No<br>
|No<br>
|===<br>
<br>
As an example, the short name of this document is _PROP_, for<br>
_proposal_, and its full document ID is {doc-id}. The next<br>
revision would be _**CTF2-PROP-2.0rA**_, and the following would be<br>
_**CTF2-PROP-2.0rB**_.<br>
<br>
A {ctf2} document {must} refer to another {ctf2} document using only its<br>
ID, for example:<br>
<br>
> This concept is further explained in _**CTF2-SOMEID-1.2**_.<br>
<br>
There's no need to refer to a specific revision: a reference always<br>
targets the latest document's revision.<br>
<br>
We suggest the following IDs for the initial documents:<br>
<br>
[%header,cols="d,d"]<br>
|===<br>
|{ctf2} document ID |Description<br>
<br>
|_**CTF2-DOCID-1.0**_<br>
|{ctf2} document identifier format.<br>
<br>
|_**CTF2-FS-2.0**_<br>
|Layout of a {ctf2} trace when stored on a file system.<br>
<br>
|_**CTF2-PMETA-2.0**_<br>
|{ctf2} metadata stream packet format.<br>
<br>
|_**CTF2-SPEC-2.0**_<br>
|Common Trace Format (CTF), version 2.<br>
<br>
We don't plan to ever bump this document's minor version as we can use<br>
the proposed <<ext,extension>> mechanism to add or modify core features.<br>
|===<br>
<br>
== Why {ctf2}?<br>
<br>
Why do we need a major version bump of the CTF specification?<br>
<br>
A major version bump is never an easy choice when it comes to revisiting<br>
a software library, a communication protocol, a file format, or anything<br>
else that serves as a contract between a producer and a consumer.<br>
<br>
When such a decision is taken, it must be justified by solid arguments,<br>
since it makes it impossible for old consumers to consume the product of<br>
new producers.<br>
<br>
In this proposal, for instance, {ctf2} traces are _not_ backward<br>
compatible with {ctf1} traces. Although the <<ds,data stream>> binary<br>
format is compatible, the <<metadata-stream-overview,metadata stream>><br>
is not: it's written in a different language (JSON instead of TSDL).<br>
<br>
{ctf1-nl} has been used and tested for over ten years now, by different<br>
producers and consumers. Over that time, we have noted a few gaps in the<br>
trace format, gaps that make it hard to extend {ctf1-nl} as much as we'd<br>
like, amongst other things.<br>
<br>
This specification proposition designs {ctf2} to overcome those gaps, to<br>
the best of our knowledge, and to be flexible enough to gracefully<br>
accept future additions while avoiding another major version bump in the<br>
upcoming years.<br>
<br>
[[design-goals]]<br>
=== Design goals<br>
<br>
The design goals of {ctf2} are as follows, in order, beginning with the<br>
most important:<br>
<br>
. **{ctf2} data streams {must} be backward compatible with {ctf1}<br>
<<ds,data streams>>.**<br>
+<br>
Many applications are already written to output valid {ctf1-nl}<br>
<<pkt,packets>>. Modifying the code of those applications to produce<br>
different binary packets can be cumbersome, and sometimes impossible if<br>
the application passed acceptance tests, for example.<br>
+<br>
Making sure that applications producing {ctf1-nl} traces can also<br>
produce {ctf2} traces only by changing the<br>
<<metadata-stream-overview,metadata stream>> is therefore a hard<br>
requirement.<br>
<br>
. **The {ctf2} data streams {must} be as efficient as possible to<br>
produce by a tracer.**<br>
+<br>
This design goal was also one of the major ones which drove the<br>
design of {ctf1-nl}.<br>
+<br>
In other words, a small embedded system {must} be able to produce {ctf2}<br>
data streams natively. Moreover, the tracer {must} be able to copy<br>
binary data to the packet buffer of a data stream without altering it.<br>
<br>
. **A {ctf2} metadata stream {must} be extensible by users (including<br>
the {diamon}) of the specification.**<br>
+<br>
{ctf1-nl}'s TSDL grammar is pretty restrictive when it comes to customizing<br>
existing blocks with user-defined attributes.<br>
+<br>
Many protocols and declarative languages support custom user data in<br>
their payload. For example, HTML5 allows any element to have user<br>
attributes with the `data-` prefix.<br>
+<br>
A {ctf2} producer {must} be able to add custom attributes to almost any<br>
specified metadata object. This makes it possible for standard consumers<br>
to read any {ctf2} trace and ignore unknown user attributes, providing a<br>
"`bland`", yet complete view of the trace fields, while you can write a<br>
special consumer (or extend an existing one) to interpret specific user<br>
attributes and use them to render a meaningful visualization.<br>
+<br>
This design goal also means that an "`old`" {ctf2} consumer {must} be<br>
able to either:<br>
+<br>
** Decode a "`new`" {ctf2} trace completely.<br>
** Indicate that it cannot decode a "`new`" {ctf2} trace completely.<br>
<br>
. **{ctf2}'s specification {must} focus on use cases known on its<br>
publication date.**<br>
+<br>
The previous design goal indicates that a {ctf2} metadata stream {must}<br>
be extensible by users. Knowing this, the {ctf2} specification itself<br>
{must} focus on _currently known_ use cases, leaving anything else to<br>
future extensions to be described in other {ctf2} documents.<br>
+<br>
As per design goal{nbsp}1, those known use cases include everything<br>
available in {ctf1-nl}.<br>
<br>
. **{ctf2}'s specification {must-not} specify how to transport or store<br>
a trace.**<br>
+<br>
In the {ctf2} specification, a {ctf2} trace {must} be defined as a set<br>
of streams, without specifying how you transport or store said streams.<br>
+<br>
Other official {ctf2} documents published by the {diamon} can define<br>
standard ways to transport and store {ctf2} streams for targeted use<br>
cases. Trace producers and consumers can choose to implement one or more<br>
transport/storage strategies following the other documents.<br>
<br>
. **A {ctf2} trace {should} be as easy as possible to consume.**<br>
+<br>
{ctf1-nl} focuses on being easy to produce, which is a good idea since<br>
producers are often tracers in this context, and as per design<br>
goal{nbsp}2, a minimal tracer {must} be able to produce a correct CTF<br>
trace with minimal code.<br>
+<br>
However, because a {ctf1-nl} <<metadata-stream-overview,metadata<br>
stream>> is written in TSDL, a custom, declarative, C-like DSL designed<br>
for CTF, writing a minimal consumer of {ctf1-nl} is not an easy task.<br>
TSDL is an intricate language, with many special cases and features,<br>
many of which are borrowed from the C language, which you can't ignore<br>
when writing a consumer supporting all its features. TSDL was developed<br>
to ease the _manual_ (human) production of metadata streams.<br>
+<br>
Over time, we realized that, while producing traces is important,<br>
consuming them to solve problems with <<er,event record>> analysis is<br>
just as important, if not more.<br>
+<br>
This is why {ctf2} {should} encourage the development of CTF consumers<br>
in any programming language by reducing the number of special cases, as<br>
well as by using a very simple, yet well-known descriptive language for<br>
the <<metadata-stream-overview,metadata stream>>.<br>
+<br>
{ctf1-nl} tries to accomodate other trace formats, which can be converted<br>
to CTF without changing the data streams by writing the matching<br>
metadata stream. This is also a source of special cases. {ctf2} {should}<br>
build on binary trace conversion (from another, non-CTF trace format to<br>
{ctf2}) rather than trying to accomodate other formats.<br>
<br>
. **{ctf2}'s model {should} be similar to {ctf1-nl}'s.**<br>
+<br>
Some APIs are already written to deal with {ctf1-nl} "`objects`", or<br>
concepts (<<erc-frag,event record classes>>, <<er,event records>>,<br>
<<fc,field classes>>, and <<cc-frag,clock classes>>, for example).<br>
+<br>
The model of {ctf2} {should} be, as much as possible, compatible with<br>
the model of {ctf1-nl}, so that those existing APIs can operate on<br>
{ctf2} objects too without requiring significant upgrades.<br>
<br>
== Changes since {ctf1-nl}<br>
<br>
Here is a brief summary of the changes, from {ctf1} to {ctf2},<br>
as introduced by this proposal.<br>
<br>
* The terminology of the specification and the binary layouts of the<br>
<<ds,data streams>> are _completely detached_ from the C language and<br>
from the behaviour of any C compiler.<br>
+<br>
{ctf2} is a programming language-agnostic trace format.<br>
<br>
* [[term-update]]**Terminology update**:<br>
+<br>
[%header%autowidth]<br>
|===<br>
|{ctf1-nl} term |Equivalent {ctf2} term<br>
<br>
|Absolute (clock class property) |Origin is Unix epoch<br>
|Array (field class) |{c-sl-array}<br>
|Base (integer field class property) |Preferred display base<br>
|Binary stream |Data stream<br>
|Clock (when it names a block of metadata which describes actual<br>
clocks) |Clock class<br>
|Content size |Packet's content size<br>
|Declaration |Field class<br>
|Enumeration (field class) |{c-fl-enum}<br>
|Event (when it names a block of metadata which describes event<br>
records) |Event record class<br>
|Event (when it names an actual recorded event contained in a packet)<br>
|Event record<br>
|Event context |Event record specific context<br>
|Event fields |Event record payload<br>
|Event ID |Event record class ID<br>
|Events discarded |Discarded event record counter<br>
|Field (structure field class) |Structure field member class<br>
|Field (structure field) |Structure field member<br>
|Floating point (field class) |{c-fl-fp}<br>
|Integer (field class) |{c-fl-int}<br>
|Packet size |Packet's total size<br>
|Sequence (field class) |{c-dl-array}<br>
|Size (integer field class property) |Length<br>
|Stream (when it names a block of metadata which describes data<br>
streams) |Data stream class<br>
|Stream event context |Event record common context<br>
|Stream event header |Event record header<br>
|Stream ID |Data stream class ID<br>
|Stream instance ID |Data stream ID<br>
|Stream packet context |Packet context<br>
|String (field class) |{c-str}<br>
|Tag (variant field class) |Selector<br>
|Trace (when it names a block of metadata which describes traces) |Trace class<br>
|Trace packet header |Packet header<br>
|===<br>
<br>
* The <<metadata-stream,metadata stream>> is written in JSON,<br>
as specified by<br>
<a href="https://protect2.fireeye.com/v1/url?k=3e8816cf-61132c8a-3e885654-867b36d1634c-bbf4be023e44dd4b&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Ffiles%2FECMA-ST%2FECMA-404.pdf%5BECMA-404">
https://protect2.fireeye.com/v1/url?k=3e8816cf-61132c8a-3e885654-867b36d1634c-bbf4be023e44dd4b&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Ffiles%2FECMA-ST%2FECMA-404.pdf%5BECMA-404</a>].<br>
<br>
* The {ctf2} specification doesn't specify a "`packetized`"<br>
metadata stream format.<br>
+<br>
This is a back-end-specific way of wrapping a<br>
<<metadata-stream-overview,metadata stream>> as defined in this<br>
document.<br>
+<br>
Another document specifies the packetized metadata stream format, which<br>
trace storage and transport documents can use if needed.<br>
<br>
* Most objects of a {ctf2} metadata stream {may} contain<br>
<<user-attrs,custom user attributes>>.<br>
<br>
* Field class aliases are removed.<br>
+<br>
This removes indirection, simplifying the format.<br>
<br>
* **New field classes**:<br>
<br>
** A __{fl-ba-fc}__ describes the most primitive<br>
fields ({fl-ba} fields) of a <<ds,data stream>> which actually have<br>
values.<br>
+<br>
A {fl-int-fc} is now specified as a {fl-ba}<br>
field class with an {optional} preferred display base property and<br>
integer type semantics.<br>
+<br>
A {fl-enum-fc} is now specified as a {fl-int-fc} with mappings.<br>
+<br>
A {fl-fp-fc} is now specified as a {fl-ba-fc}: its length property is<br>
enough to determine its encoding under {ieee754}.<br>
<br>
** A __{fl-bool-fc}__, which is a {fl-ba-fc} with a special meaning,<br>
describes {fl-bool} fields.<br>
+<br>
When all the bits of a {fl-bool} field are cleared (zero), the field's<br>
value is said to be _false_. Otherwise, the field's value is said to be<br>
_true_.<br>
<br>
** A __{vl-ba-fc}__ describes {vl-ba} fields.<br>
+<br>
Each byte of a {vl-ba} field has its most significant bit set if one<br>
more byte is part of the field.<br>
+<br>
The seven low-order bits of each byte are concatenated in a specific way<br>
to form a final, equivalent {fl-ba} field.<br>
<br>
** A __{vl-int-fc}__, which is to a {vl-ba-fc} what a {fl-int-fc}<br>
is to a {fl-ba-fc}, describes {vl-int} fields.<br>
<br>
** A __{vl-enum-fc}__, which is to a {vl-int-fc} what a {fl-enum-fc} is<br>
to a {fl-int-fc}, describes {vl-enum} fields.<br>
<br>
** A __{sl-str-fc}__ and a __{dl-str-fc}__ describe static- and<br>
dynamic-length string fields, which {may} not be null-terminated.<br>
+<br>
Such string fields hold _possibly_ null-terminated UTF-8 string values<br>
(they {may} also hold an exact number of UTF-8 bytes without a<br>
terminating null byte).<br>
<br>
** An __{opt-fc}__ describes an optional field.<br>
+<br>
It is similar to a variant field class with two options: the optional<br>
field class and an "`empty`" field class.<br>
<br>
** A __{sl-blob-fc}__ and a __{dl-blob-fc}__ describe static- and<br>
dynamic-length sequences of contiguous bytes to represent<br>
<a href="https://en.wikipedia.org/wiki/Binary_large_object[BLOBs">https://en.wikipedia.org/wiki/Binary_large_object[BLOBs</a>].<br>
<br>
* **Modified field classes**:<br>
<br>
** The default alignment property of a <<fl-ba-fc,{fl-ba}>> field<br>
(and therefore also of fixed-length <<fl-bool-fc,boolean>>,<br>
<<fl-int-fc,integer>>, <<fl-enum-fc,enumeration>>, and<br>
<<fl-fp-fc,floating point number>> fields) is{nbsp}1.<br>
+<br>
In {ctf1-nl}, it's{nbsp}8 if the field's class's size property is a<br>
multiple of{nbsp}8, and{nbsp}1 otherwise.<br>
<br>
** The _encoding_ property _is removed_ from the {fl-int-fc}.<br>
+<br>
The encoding property in {ctf1-nl} indicates that a byte is a UTF-8<br>
character, for example, but since there are UTF-8 characters which are<br>
encoded on more than one byte, this property actually makes no sense at<br>
the {fl-int-fc} level.<br>
+<br>
You can use the new {sl-str-fc} and {dl-str-fc} to achieve<br>
the same result.<br>
<br>
** The _exponent_ and _mantissa size_ properties _are removed_ from the<br>
{fl-fp-fc}.<br>
+<br>
A {fl-fp-fc} is now defined as a {fl-ba-fc}, which has a<br>
single length property to indicate its total, fixed length, in bits.<br>
+<br>
A {ctf2} consumer can<br>
<<fl-fp-field-dec,decode a {fl-fp} field>> encoded following {ieee754}<br>
knowing only this parameter--the storage width of the bit array--from<br>
which it can deduce other parameters according to the standard.<br>
+<br>
In other words, in {ctf1-nl}, only specific pairs of exponent and<br>
mantissa size properties are valid: 8 and 24, 11 and 53, 15 and 113, and<br>
so on.<br>
<br>
** The _encoding_ property _is removed_ from the {str-fc}.<br>
+<br>
{ctf2} {str} fields always contain a sequence of bytes which encode a<br>
{str} with UTF-8. If a {str} field is encoded with the ASCII encoding in<br>
a {ctf1-nl} data stream, it's still valid in {ctf2} since an ASCII<br>
string is a UTF-8 string.<br>
<br>
* _Relative_ field locations (variant field class's tag/selector and<br>
dynamic-length field class's length) are removed.<br>
+<br>
In {ctf2}, you can specify a location to any valid field with an<br>
absolute <<field-loc,field location>>.<br>
+<br>
This simplifies the format.<br>
<br>
* "`Special`" <<struct-member-cls,structure field member classes>>, such<br>
as the <<pkt,packet>> magic number member class, the <<dsc-frag,data<br>
stream class>> ID member class, and the packet's total size member<br>
class, _can have any name_: a <<fc,field class>> {may} have one or<br>
more <<roles,_roles_>> instead to indicate the purpose of its<br>
instances.<br>
+<br>
This means a {ctf2} consumer doesn't need to rely on reserved names like<br>
{ctf1-nl}'s `magic`, `stream_id`, and `packet_size`.<br>
+<br>
This new approach also makes it possible for a given field class to have<br>
multiple roles.<br>
<br>
* The _native byte order_ property _is removed_ from the<br>
<<tc-frag,trace class>>.<br>
+<br>
In {ctf2}, each {fl-ba-fc} {must} explicitly<br>
indicate the byte order of its instances.<br>
+<br>
This removes indirection, simplifying the format.<br>
<br>
* The _EMF URI_ property _is removed_ from the<br>
<<erc-frag,event record class>>.<br>
+<br>
This Eclipse Modeling Framework property is not common enough for the<br>
Common Trace Format.<br>
+<br>
A producer can still write such an URI as an event record class's<br>
<<user-attrs,user attribute>>.<br>
<br>
* The _log level_ property _is removed_ from the<br>
<<erc-frag,event record class>>.<br>
+<br>
Log level integral values are tracer-specific.<br>
+<br>
A producer can still write such a log level value as an event record<br>
class's <<user-attrs,user attribute>>.<br>
<br>
* A {ctf2} trace {may} have zero or more <<aux-stream,_auxiliary<br>
streams_>>.<br>
+<br>
An auxiliary stream contains structured information related to a<br>
specific trace which doesn't fit the <<ds,data stream>> model, whereas a<br>
{ctf2} metadata stream now describes a class of traces (multiple traces<br>
can share the same metadata stream).<br>
<br>
* The "`call site`" block feature is removed.<br>
+<br>
We don't know any producer using this.<br>
<br>
== Common definitions<br>
<br>
Common definitions for this specification:<br>
<br>
Byte::<br>
A group of eight bits operated on as a unit.<br>
<br>
Class::<br>
A set of values (instances) which share common properties.<br>
+<br>
For example, a {fl-uint-fc} with an 8-bit length<br>
is the set of the all the {fl-uint} fields from `00000000` to `11111111`<br>
(values 0{nbsp}to{nbsp}255).<br>
.<br>
+<br>
This document often states that some class _describes_ instances. For<br>
example, an <<erc-frag,event record class>> describes <<er,event<br>
records>>.<br>
<br>
Consumer::<br>
A software or hardware system which consumes (reads) the streams of<br>
a <<trace,trace>>.<br>
+<br>
A trace consumer is often a _trace viewer_ or a _trace analyzer_.<br>
<br>
[[ns-def]]Namespace::<br>
A string of which the purpose is to avoid naming conflicts.<br>
+<br>
This document doesn't specify the format of a namespace. It is<br>
_recommended_ to use a URI, or at least to include a domain name owned<br>
by the organization defining the objects under a namespace.<br>
+<br>
IMPORTANT: The `std` namespace is reserved for the {ctf2} specification.<br>
<br>
Producer::<br>
A software or hardware system which produces (writes) the streams of<br>
a <<trace,trace>>.<br>
+<br>
A trace producer is often a _tracer_.<br>
<br>
Sequence::<br>
A set of related items that follow each other in a particular order.<br>
<br>
Stream::<br>
A sequence of bytes.<br>
<br>
[[trace]]<br>
== Trace composition<br>
<br>
A trace is:<br>
<br>
* One <<metadata-stream-overview,metadata stream>>.<br>
* One or more <<data-stream,data streams>>.<br>
* Zero or more <<aux-stream,auxiliary streams>>.<br>
<br>
As a reminder, a stream is defined as a sequence of bytes.<br>
<br>
NOTE: This document doesn't specify how to transport or store<br>
{ctf2} streams. A producer could serialize all streams as a single file<br>
on the file system, or it could send the streams over the network using<br>
TCP, to name a few examples.<br>
<br>
[[metadata-stream-overview]]<br>
=== Metadata stream (overview)<br>
<br>
A metadata stream describes trace <<ds,data streams>> with JSON objects.<br>
<br>
A metadata stream describes things such as:<br>
<br>
* The <<cc-frag,class>> of the data stream <<def-clk,default clocks>>.<br>
* The names of <<erc-frag,event record classes>>.<br>
* The <<fc,classes>> of event record fields.<br>
<br>
Multiple traces {may} share the same metadata stream: a given trace<br>
{may} contain specific information in its own <<aux-stream,auxiliary<br>
streams>>.<br>
<br>
See <<metadata-stream>> for the full metadata stream specification.<br>
<br>
[[ds]]<br>
=== Data stream<br>
<br>
A _data stream_ is a sequence of one or more data <<pkt,packets>>:<br>
<br>
image::ctf-trace-all.svg[]<br>
<br>
In the <<metadata-stream,metadata stream>>, a<br>
<<dsc-frag,data stream class>> describes data streams.<br>
<br>
A packet {must} contain one or more bytes of data.<br>
<br>
Although a packet {may} contain padding at the end itself, from the data<br>
stream's point of view, there's no padding between packets. In other<br>
words, the byte following the last byte of a packet is the first byte of<br>
the next packet.<br>
<br>
A data stream {may} have, conceptually:<br>
<br>
[[def-clk]]One default, monotonic clock::<br>
Described by a <<cc-frag,clock class>> in the metadata stream.<br>
+<br>
<<pkt,Packets>> and <<er,event records>> {may} contain _snapshots_,<br>
named _timestamps_, of their data stream's default clock.<br>
<br>
[[disc-er-counter]]One counter of discarded event records::<br>
Indicates the number of event records which the producer<br>
needed to discard for different reasons.<br>
+<br>
For example, a tracer could discard an event record when it doesn't fit<br>
some buffer and there's no other available buffer.<br>
+<br>
A packet {may} contain a snapshot of this counter.<br>
<br>
See <<ds-dec>> to learn how to decode a {ctf2} data stream.<br>
<br>
[[pkt]]<br>
==== Packet<br>
<br>
A _packet_ is a part of a <<ds,data stream>>.<br>
<br>
A packet contains a sequence of data _fields_ or padding (garbage<br>
data). In the metadata stream, <<fc,field classes>> describe data<br>
fields.<br>
<br>
A packet {var-p}, contained in a data stream{nbsp}{var-s}, contains,<br>
in this order:<br>
<br>
. [[pkt-header]]{optional}: A **header** <<struct-fc,structure>> field,<br>
described at the <<tc-frag,trace class>> level in the<br>
<<metadata-stream,metadata stream>>, which contains:<br>
.. {optional}: A packet magic number field (0xc1fc1fc1, or 3254525889).<br>
.. Order _not_ significant:<br>
*** {optional}: A trace class UUID field.<br>
*** {optional}: One or more fields which contain the numeric ID of the<br>
<<dsc-frag,class>> of{nbsp}{var-s}.<br>
*** {optional}: One or more fields which contain the numeric ID<br>
of{nbsp}{var-s}.<br>
<br>
. [[pkt-ctx]]{optional}: A **context** <<struct-fc,structure>> field,<br>
described at the <<dsc-frag,data stream class>> level in the metadata<br>
stream, which contains (order _not_ significant):<br>
** {optional}: A field which contains the total size of{nbsp}{var-p},<br>
in bits (always a multiple of 8).<br>
** {optional}: A field which contains the content size<br>
of{nbsp}{var-p}, in bits.<br>
** {optional}: A field which contains the beginning timestamp<br>
of{nbsp}{var-p}.<br>
** {optional}: A field which contains the end timestamp<br>
of{nbsp}{var-p}.<br>
** {optional}: A field which contains a snapshot of the<br>
<<disc-er-counter,discarded event record counter>> of{nbsp}{var-s}<br>
at the end of{nbsp}{var-p}.<br>
** {optional}: A field which contains the sequence number<br>
of{nbsp}{var-p} within{nbsp}{var-s}.<br>
** {optional}: User fields.<br>
<br>
. Zero or more <<er,event records>>.<br>
<br>
A packet {must} contain one or more bytes of data.<br>
<br>
A packet {may} have padding (garbage data) after its _last_ event<br>
record. The size of this padding is the difference between its total<br>
size and its content size (as found in its <<pkt-ctx,context structure<br>
field>>).<br>
<br>
Packets are independent of each other: if you remove a packet<br>
from a data stream, a consumer can still decode the whole data stream.<br>
This is why:<br>
<br>
* Packets {may} contain _snapshots_ of their data stream's<br>
<<disc-er-counter,discarded event record counter>>.<br>
<br>
* Packets and event records {may} contain _timestamps_ which are<br>
snapshots of their data stream's <<def-clk,default clock>>.<br>
<br>
If the <<pkt-ctx,packet context>> fields of a data stream's packets<br>
contain a <<pkt-seq-num-role,packet sequence number>> field, a consumer<br>
can recognize missing packets.<br>
<br>
See <<pkt-dec>> to learn how to decode a {ctf2} packet.<br>
<br>
[[er]]<br>
==== Event record<br>
<br>
An _event record_ is the result of a producer writing a record with<br>
{optional} user data when an event occurs during its execution.<br>
<br>
A <<pkt,packet>> contains zero or more event records.<br>
<br>
An <<erc-frag,event record class>> describes the specific parts of<br>
event records.<br>
<br>
An event record _**E**_, contained in a <<ds,data<br>
stream>>{nbsp}{var-s}, contains, in this order:<br>
<br>
. [[er-header]]{optional}: A **header** <<struct-fc,structure>> field,<br>
described at the <<dsc-frag,data stream class>> level in the metadata<br>
stream, which contains (order _not_ significant):<br>
** {optional}: One or more fields which contain the numeric ID of the<br>
<<erc-frag,class>> of{nbsp}__**E**__ which has the class<br>
of{nbsp}{var-s} as its parent.<br>
** {optional}: One or more fields which contain a timestamp or a partial<br>
timestamp.<br>
<br>
. [[er-common-ctx]]{optional}: A **common context**<br>
<<struct-fc,structure>> field, described at the data stream class<br>
level in the metadata stream, which contains user fields.<br>
<br>
. [[er-spec-ctx]]{optional}: A **specific context**<br>
<<struct-fc,structure>> field, described at the event record class<br>
level in the metadata stream, which contains user fields.<br>
<br>
. [[er-payload]]{optional}: A **payload** <<struct-fc,structure>> field,<br>
described at the event record class level in the metadata stream,<br>
which contains user fields.<br>
<br>
An event record {must} contain one or more bits of data.<br>
<br>
The <<def-clk,default clock>> timestamp of an event record, that is, the<br>
value of its <<ds,data stream>>'s default clock _after_ its<br>
<<er-header,header field>>, if any, is encoded/decoded {must} be greater<br>
than or equal to the default clock timestamp of the previous event<br>
record, if any, within the _same_ data stream.<br>
<br>
See <<er-dec>> to learn how to decode a {ctf2} event record.<br>
<br>
[[aux-stream]]<br>
=== Auxiliary stream<br>
<br>
An auxiliary stream is a JSON object, as specified by<br>
<a href="https://protect2.fireeye.com/v1/url?k=af4f3d31-f0d40774-af4f7daa-867b36d1634c-fd4033714bb458fb&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Ffiles%2FECMA-ST%2FECMA-404.pdf%5BECMA-404">https://protect2.fireeye.com/v1/url?k=af4f3d31-f0d40774-af4f7daa-867b36d1634c-fd4033714bb458fb&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Ffiles%2FECMA-ST%2FECMA-404.pdf%5BECMA-404</a>],<br>
which contains extra, structured information about the trace which<br>
doesn't fit the <<ds,data stream>> model.<br>
<br>
An auxiliary stream has a single property:<br>
<br>
[horizontal]<br>
Name::<br>
Auxiliary stream's <<ns-def,namespace>>.<br>
<br>
Value::<br>
A JSON value.<br>
<br>
Two auxiliary streams of a given trace {must-not} have the same<br>
namespace.<br>
<br>
.Auxiliary stream with the `my.tracer` namespace.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"my.tracer": {<br>
"version": [1, 3, 2],<br>
"session-name": "hanon"<br>
}<br>
}<br>
----<br>
====<br>
<br>
.Auxiliary stream of which the value is just `42`.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"328c7a2d-a959-4f60-bd22-cca74359326f": 42<br>
}<br>
----<br>
====<br>
<br>
[[env]]<br>
==== Trace environment<br>
<br>
To remain backward compatible with {ctf1}, a trace {may} contain an<br>
auxiliary stream having the `std` namespace which contains trace<br>
environment variables under the `environment` property.<br>
<br>
The trace environment variables are a single JSON object where each<br>
property is:<br>
<br>
[horizontal]<br>
Name::<br>
Trace environment variable name.<br>
<br>
Value::<br>
Trace environment variable value (any JSON value).<br>
<br>
This document doesn't specify trace environment variable names.<br>
<br>
.`std` auxiliary stream with trace environment variables.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"std": {<br>
"environment": {<br>
"hostname": "hanon",<br>
"domain": "kernel",<br>
"sysname": "Linux",<br>
"kernel_release": "4.12.12-1-ARCH",<br>
"kernel_version": "#1 SMP PREEMPT Sun Sep 10 09:41:14 CEST 2017",<br>
"tracer_name": "lttng-modules",<br>
"tracer_major": 2,<br>
"tracer_minor": 10,<br>
"tracer_patchlevel": 0<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[metadata-stream]]<br>
== Metadata stream<br>
<br>
A metadata stream is a JSON array, as specified by<br>
<a href="https://protect2.fireeye.com/v1/url?k=92ff4d35-cd647770-92ff0dae-867b36d1634c-404c4d62482533d6&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Ffiles%2FECMA-ST%2FECMA-404.pdf%5BECMA-404">https://protect2.fireeye.com/v1/url?k=92ff4d35-cd647770-92ff0dae-867b36d1634c-404c4d62482533d6&q=1&e=698f127a-baf5-4d0a-8f64-50168d8d98c6&u=https%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Ffiles%2FECMA-ST%2FECMA-404.pdf%5BECMA-404</a>],<br>
of _fragments_.<br>
<br>
Together, the fragments of a metadata stream contain all the information<br>
about the <<ds,data streams>> of one or more <<trace,traces>>.<br>
<br>
[[frag]]A _fragment_ is a JSON object; its allowed properties depend on<br>
its `type` property.<br>
<br>
.Common properties of a fragment {var-f}.<br>
[%header%autowidth,cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"preamble"`::<br>
{var-f} is a <<preamble-frag,preamble fragment>>.<br>
<br>
`"trace-class"`::<br>
{var-f} is a <<tc-frag,trace class fragment>>.<br>
<br>
`"clock-class"`::<br>
{var-f} is a <<cc-frag,clock class fragment>>.<br>
<br>
`"data-stream-class"`::<br>
{var-f} is a <<dsc-frag,data stream class fragment>>.<br>
<br>
`"event-record-class"`::<br>
{var-f} is a <<erc-frag,event record class fragment>>.<br>
|Yes<br>
|<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
For any fragment except a <<preamble-frag,preamble fragment>>, any<br>
extension which exists under this property must also be declared in the<br>
metadata stream's preamble fragment.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
The metadata stream is designed as a flat JSON array of fragments<br>
instead of a single JSON object containing nested objects to enable<br>
real-time, or "`live`", tracing: a consumer can always decode <<er,event<br>
records>> having known <<erc-frag,event record classes>> while a<br>
producer can always add new event record classes to a <<dsc-frag,data<br>
stream class>> by appending additional fragments to the metadata stream.<br>
Once a producer appends a fragment to a metadata stream, the fragment<br>
is considered "`frozen`", in that it never needs to change.<br>
<br>
A metadata stream:<br>
<br>
* {must} start with a preamble fragment.<br>
* {must} contain exactly one <<preamble-frag,preamble fragment>>.<br>
* {may} contain one <<tc-frag,trace class fragment>>.<br>
* {must} contain one or more <<dsc-frag,data stream class fragments>><br>
which {must} follow the trace class fragment, if any.<br>
* {may} contain one or more <<er-frag,event record class fragments>><br>
which {must} follow their parent data stream class, if any.<br>
<br>
.Partial metadata stream.<br>
====<br>
[source,json]<br>
----<br>
[<br>
{<br>
"type": "preamble",<br>
"version": 2<br>
},<br>
…<br>
]<br>
----<br>
====<br>
<br>
[NOTE]<br>
====<br>
This section doesn't specify how a metadata stream translates into<br>
<<ds,data stream>> encoding and decoding rules; it only describes<br>
objects and their properties.<br>
<br>
See <<ds-dec>> to learn how to decode a data stream.<br>
====<br>
<br>
[[uuid]]<br>
=== UUID<br>
<br>
Both a <<tc-frag,trace class fragment>> and a <<cc-frag,clock class<br>
fragment>> {may} have a<br>
<a href="https://en.wikipedia.org/wiki/Universally_unique_identifier[_UUID_">https://en.wikipedia.org/wiki/Universally_unique_identifier[_UUID_</a>]<br>
property.<br>
<br>
Within a metadata stream, a UUID is a JSON string of which the value is<br>
the canonical textual representation of the UUID.<br>
<br>
.UUID.<br>
====<br>
[source,json]<br>
----<br>
"e53e0ab8-50a1-4f0a-b710-b5f0bba9c4ac"<br>
----<br>
====<br>
<br>
[[ext]]<br>
=== Extensions<br>
<br>
A producer {may} add _extensions_ to many metadata stream JSON objects.<br>
<br>
The purpose of an extension is to add core features to {ctf2} or to<br>
modify existing core features, as specified by this document. In other<br>
words, an extension {may} alter the format itself. This document doesn't<br>
specify what an extension exactly is.<br>
<br>
The metadata stream's <<preamble-frag,preamble fragment>> contains<br>
_extension declarations_:<br>
<br>
* Any extension in metadata stream objects {must} be declared, by<br>
namespace and name, in the preamble fragment.<br>
+<br>
Declaring an extension is said to _enable_ it.<br>
<br>
* If a consumer doesn't support _any_ declared extension, it {must-not}<br>
consume the <<trace,trace>>'s <<ds,data streams>>.<br>
+<br>
The consumer {should} report unsupported extensions as an error.<br>
<br>
Extensions are a single JSON object, where each property is:<br>
<br>
[horizontal]<br>
Name::<br>
A <<ns-def,namespace>><br>
<br>
Value::<br>
A <<ns-exts-obj,namespaced extensions object>><br>
<br>
[[ns-exts-obj]]A _namespaced extensions object_ is a JSON object, where<br>
each property is:<br>
<br>
[horizontal]<br>
Name::<br>
An extension name<br>
<br>
Value::<br>
A JSON value<br>
<br>
The metadata stream JSON objects which {may} contain extensions as their<br>
`extensions` property are:<br>
<br>
* Any <<frag,fragment>>.<br>
+<br>
An extension in the <<preamble-frag,preamble fragment>> also makes it<br>
_declared_.<br>
<br>
* Any <<fc,field class>>.<br>
<br>
* A <<struct-member-cls,structure field member class>>.<br>
<br>
* A <<var-fc-opt,variant field class option>>.<br>
<br>
.Three extensions under two namespaces.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"my.tracer": {<br>
"piano": {<br>
"keys": 88,<br>
"temperament": "equal"<br>
},<br>
"ramen": 23<br>
},<br>
"abc/xyz": {<br>
"sax": {<br>
"variant": "alto"<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[user-attrs]]<br>
=== User attributes<br>
<br>
A producer {may} add custom _user attributes_ to many metadata stream<br>
JSON objects.<br>
<br>
This document doesn't specify what a user attribute exactly is. Unlike<br>
<<ext,extensions>>, a consumer {must-not} consider user attributes to<br>
decode <<ds,data streams>>.<br>
<br>
User attributes are a single JSON object, where each property is:<br>
<br>
[horizontal]<br>
Name::<br>
A <<ns-def,namespace>><br>
<br>
Value::<br>
A JSON value<br>
<br>
The metadata stream JSON objects which {may} contain user attributes<br>
as their `user-attributes` property are:<br>
<br>
* Any <<frag,fragment>>.<br>
* Any <<fc,field class>>.<br>
* A <<struct-member-cls,structure field member class>>.<br>
* A <<var-fc-opt,variant field class option>>.<br>
<br>
.User attributes under two namespaces.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"my.tracer": {<br>
"max-count": 45,<br>
"module": "sys"<br>
},<br>
"abc/xyz": true<br>
}<br>
----<br>
====<br>
<br>
[[fc]]<br>
=== Field classes<br>
<br>
A _field class_ describes fields, that is, sequences of bits as found<br>
in a <<ds,data stream>>.<br>
<br>
A field class contains all the properties a consumer needs to<br>
<<ds-dec,decode>> a given field.<br>
<br>
A _field_ is a field class instance.<br>
<br>
This document specifies the following types of field classes:<br>
<br>
Abstract field classes::<br>
You cannot use the following field classes directly: they are bases<br>
for other, concrete field classes:<br>
+<br>
* <<int-fc,Abstract integer field class>><br>
* <<enum-fc,Abstract enumeration field class>><br>
* <<array-fc,Abstract array field class>><br>
* <<blob-fc,Abstract BLOB field class>><br>
<br>
Fixed/static-length field classes::<br>
+<br>
* {c-fl-ba-fc}<br>
* {c-fl-bool-fc}<br>
* {c-fl-int-fc}<br>
* {c-fl-enum-fc}<br>
* {c-fl-fp-fc}<br>
* {c-sl-str-fc}<br>
* {c-sl-blob-fc}<br>
<br>
Variable/dynamic-length field classes::<br>
+<br>
* {c-vl-ba-fc}<br>
* {c-vl-int-fc}<br>
* {c-vl-enum-fc}<br>
* {c-str-fc}<br>
* {c-dl-str-fc}<br>
* {c-dl-blob-fc}<br>
<br>
Compound field classes::<br>
The following field classes contain one or more field classes.<br>
+<br>
* {c-struct-fc}<br>
* {c-sl-array-fc}<br>
* {c-dl-array-fc}<br>
* {c-opt-fc}<br>
* {c-var-fc}<br>
<br>
A field class is a JSON object; its properties depend on its `type`<br>
property.<br>
<br>
.Common properties of a field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"fixed-length-bit-array"`::<br>
{var-f} is a {fl-ba-fc}.<br>
<br>
`"fixed-length-boolean"`::<br>
{var-f} is a {fl-bool-fc}.<br>
<br>
`"fixed-length-unsigned-integer"`::<br>
`"fixed-length-signed-integer"`::<br>
{var-f} is a {fl-int-fc}.<br>
<br>
`"fixed-length-unsigned-enumeration"`::<br>
`"fixed-length-signed-enumeration"`::<br>
{var-f} is a {fl-enum-fc}.<br>
<br>
`"fixed-length-floating-point-number"`::<br>
{var-f} is a {fl-fp-fc}.<br>
<br>
`"variable-length-bit-array"`::<br>
{var-f} is a {vl-ba-fc}.<br>
<br>
`"variable-length-unsigned-integer"`::<br>
`"variable-length-signed-integer"`::<br>
{var-f} is a {vl-int-fc}.<br>
<br>
`"variable-length-unsigned-enumeration"`::<br>
`"variable-length-signed-enumeration"`::<br>
{var-f} is a {vl-enum-fc}.<br>
<br>
`"null-terminated-string"`::<br>
{var-f} is a {str-fc}.<br>
<br>
`"static-length-string"`::<br>
{var-f} is a {sl-str-fc}.<br>
<br>
`"static-length-blob"`::<br>
{var-f} is a {sl-blob-fc}.<br>
<br>
`"dynamic-length-string"`::<br>
{var-f} is a {dl-str-fc}.<br>
<br>
`"dynamic-length-blob"`::<br>
{var-f} is a {dl-blob-fc}.<br>
<br>
`"structure"`::<br>
{var-f} is a {struct-fc}.<br>
<br>
`"static-length-array"`::<br>
{var-f} is a {sl-array-fc}.<br>
<br>
`"dynamic-length-array"`::<br>
{var-f} is a {dl-array-fc}.<br>
<br>
`"optional"`::<br>
{var-f} is a {opt-fc}.<br>
<br>
`"variant"`::<br>
{var-f} is a {var-fc}.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
The following <<frag,fragment>> properties require a<br>
{struct-fc} as their value:<br>
<br>
<<tc-frag,Trace class fragment>>::<br>
`packet-header-field-class`<br>
<br>
<<dsc-frag,Data stream class fragment>>::<br>
+<br>
* `packet-context-field-class`<br>
* `event-record-header-field-class`<br>
* `event-record-common-context-field-class`<br>
<br>
<<erc-frag,Event record class fragment>>::<br>
+<br>
* `specific-context-field-class`<br>
* `payload-field-class`<br>
<br>
[[field-loc]]<br>
==== Field location<br>
<br>
A _field location_ is a means for a consumer to find a field which it<br>
needs to decode another field.<br>
<br>
A consumer needs to find another field to decode instances of the<br>
following <<fc,classes>>:<br>
<br>
{c-dl-array-fc}::<br>
{c-dl-str-fc}::<br>
{c-dl-blob-fc}::<br>
Needs a <<fl-int-fc,{fl-uint}>> or<br>
<<vl-int-fc,{vl-uint}>> length field.<br>
<br>
{c-opt-fc}::<br>
Needs a <<fl-bool-fc,{fl-bool}>>, <<fl-int-fc,{fl-int}>>, or<br>
<<vl-int-fc,{vl-int}>> selector field.<br>
<br>
{c-var-fc}::<br>
Needs a <<fl-int-fc,{fl-int}>> or <<vl-int-fc,{vl-int}>> selector<br>
field.<br>
<br>
A field location is a JSON array, where, in this order:<br>
<br>
. The first element is the name (JSON string) of a root field from<br>
where to start the lookup, amongst:<br>
+<br>
[horizontal]<br>
`"packet-header"`:::<br>
Packet header<br>
`"packet-context"`:::<br>
Packet context<br>
`"event-record-header"`:::<br>
Event record header<br>
`"event-record-common-context"`:::<br>
Event record common context<br>
`"event-record-specific-context"`:::<br>
Event record specific context<br>
`"event-record-payload"`:::<br>
Event record payload<br>
<br>
. The following elements are <<struct-fc,structure>> field member names<br>
(JSON strings) to follow to find the target field.<br>
<br>
The length of a field location {must} be greater than or equal to two.<br>
<br>
Let _**T**_ be a field which a consumer needs to decode another<br>
field{nbsp}{var-s}:<br>
<br>
* If {var-s} is in a packet header, then{nbsp}__**T**__ {must} be in the<br>
_same_ packet header.<br>
<br>
* If {var-s} is in a packet context, then{nbsp}__**T**__ {must} be in<br>
one of:<br>
** The packet header the _same_ packet.<br>
** The _same_ packet context.<br>
<br>
* If {var-s} is in an event record header, then{nbsp}__**T**__ {must}<br>
be in one of:<br>
** The packet header of the _same_ packet.<br>
** The packet context of the _same_ packet.<br>
** The _same_ event record header.<br>
<br>
* If {var-s} is in an event record common context, then{nbsp}__**T**__<br>
{must} be in one of:<br>
** The packet header of the _same_ packet.<br>
** The packet context of the _same_ packet.<br>
** The event record header of the _same_ event record.<br>
** The _same_ event record common context.<br>
<br>
* If {var-s} is in an event record specific context, then{nbsp}__**T**__<br>
{must} be in one of:<br>
** The packet header of the _same_ packet.<br>
** The packet context of the _same_ packet.<br>
** The event record header of the _same_ event record.<br>
** The event record common context of the _same_ event record.<br>
** The _same_ event record specific context.<br>
<br>
* If {var-s} is in an event record payload, then{nbsp}__**T**__ {must}<br>
be in one of:<br>
** The packet header of the _same_ packet.<br>
** The packet context of the _same_ packet.<br>
** The event record header of the _same_ event record.<br>
** The event record common context of the _same_ event record.<br>
** The event record common specific of the _same_ event record.<br>
** The _same_ event record payload.<br>
<br>
* If {var-s} and _**T**_ are _not_ in the same root field,<br>
then{nbsp}__**T**__ {must-not} be in any <<array-fc,array>> or<br>
<<opt-fc,optional>> field.<br>
<br>
* If {var-s} and _**T**_ are in the same root field, then:<br>
** If {var-s} is in an array field, then{nbsp}__**T**__ must be in the<br>
_same_ array field element.<br>
** If {var-s} is in an optional field, then{nbsp}__**T**__ must be in the<br>
_same_ optional field.<br>
<br>
If any structure member name{nbsp}__**N**__ of a field<br>
location{nbsp}__**L**__ names a <<var-fc,variant field>>, then:<br>
<br>
If _**N**_ is _not_ the last element of{nbsp}__**L**__::<br>
The variant field {must} select a structure field, from which the<br>
lookup process can continue, recursively.<br>
<br>
If _**N**_ is the last element of{nbsp}__**L**__::<br>
The variant field {must} select the target field<br>
(<<fl-int-fc,{fl-int}>>, <<vl-int-fc,{vl-int}>>, or<br>
<<fl-bool-fc,{fl-bool}>>), recursively.<br>
<br>
In both cases, _all_ the options of the variant field class {must} make<br>
it possible for the lookup process to continue.<br>
<br>
.<<dl-array,{c-dl-array}>> field and its length field in the same root field.<br>
====<br>
The following JSON object is an event record payload<br>
{struct-fc}.<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "corn", <3><br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 32,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"name": "inside",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"name": "carbon",<br>
"field-class": {<br>
"type": "dynamic-length-array", <1><br>
"length-field-location": ["event-record-payload", "corn"], <2><br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> {c-dl-array-fc}.<br>
<2> {c-dl-array-fc}'s length field location.<br>
<3> Length member class.<br>
====<br>
<br>
.{c-dl-array} field and its length field in the same root field,<br>
within the same array field element.<br>
====<br>
The following JSON object is an event record payload<br>
{struct-fc}.<br>
<br>
Both the {dl-array} field and its length field exist within the same<br>
element of the <<sl-array-fc,{sl-array}>> field named `nature`.<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "norm",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
},<br>
{<br>
"name": "nature",<br>
"field-class": {<br>
"type": "static-length-array",<br>
"length": 43,<br>
"element-field-class": {<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "laser", <3><br>
"field-class": {<br>
"type": "variable-length-unsigned-integer"<br>
}<br>
},<br>
{<br>
"name": "joystick",<br>
"field-class": {<br>
"type": "dynamic-length-array", <1><br>
"length-field-location": [ <2><br>
"event-record-payload",<br>
"nature",<br>
"laser"<br>
],<br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
}<br>
]<br>
}<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> {c-dl-array-fc}.<br>
<2> {c-dl-array-fc}'s length field location.<br>
<3> Length member class.<br>
====<br>
<br>
.{c-dl-array} and its length field in the same root field, within the<br>
same <<var-fc,variant>> field.<br>
====<br>
The following JSON object is an event record payload<br>
{struct-fc}.<br>
<br>
Both the {dl-array} field and its length field exist within the same<br>
option of the <<var-fc,variant>> field named `clinic`.<br>
<br>
Moreover, the selector field of the `clinic` variant field is the<br>
`lawyer` field.<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "lawyer", <5><br>
"field-class": {<br>
"type": "fixed-length-signed-integer",<br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"name": "clinic",<br>
"field-class": {<br>
"type": "variant",<br>
"selector-field-location": ["event-record-payload", "lawyer"], <4><br>
"options": [<br>
{<br>
"selector-field-ranges": [[0, 0]],<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
},<br>
{<br>
"selector-field-ranges": [[1, 4]],<br>
"field-class": {<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "lemon", <3><br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 8,<br>
"byte-order": "big-endian"<br>
}<br>
},<br>
{<br>
"name": "joystick",<br>
"field-class": {<br>
"type": "dynamic-length-array", <1><br>
"length-field-location": [ <2><br>
"event-record-payload",<br>
"clinic",<br>
"lemon"<br>
],<br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
}<br>
]<br>
}<br>
},<br>
{<br>
"selector-field-ranges": [[5, 5], [7, 7]],<br>
"field-class": {<br>
"type": "fixed-length-boolean",<br>
"length": 8,<br>
"byte-order": "little-endian"<br>
}<br>
}<br>
]<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> {c-dl-array-fc}.<br>
<2> {c-dl-array-fc}'s length field location.<br>
<3> Length member class.<br>
<4> Variant field class's selector field location.<br>
<5> Selector member class.<br>
====<br>
<br>
.{c-dl-array} and its length field in the same root field; length<br>
field is a variant field.<br>
====<br>
The following JSON object is an event record payload<br>
{struct-fc}.<br>
<br>
The length field of the {dl-array} field is a variant field: it can be<br>
an 8-bit, a 16-bit, or a 32-bit <<fl-int-fc,{fl-int}>> field, depending<br>
on the variant field's selection.<br>
<br>
Moreover, the selector field of the variant field is located in another<br>
root field (event record specific context).<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "glass", <3><br>
"field-class": {<br>
"type": "variant",<br>
"selector-field-location": ["event-record-specific-context", "sel"],<br>
"options": [<br>
{<br>
"selector-field-ranges": [[0, 0]],<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer", <4><br>
"length": 8,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"selector-field-ranges": [[1, 1]],<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer", <4><br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"selector-field-ranges": [[2, 2]],<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer", <4><br>
"length": 32,<br>
"byte-order": "little-endian"<br>
}<br>
}<br>
]<br>
}<br>
},<br>
{<br>
"name": "margin",<br>
"field-class": {<br>
"type": "dynamic-length-array", <1><br>
"length-field-location": ["event-record-payload", "glass"], <2><br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> {c-dl-array-fc}.<br>
<2> {c-dl-array-fc}'s length field location.<br>
<3> Length member class.<br>
<4> Possible length field class.<br>
====<br>
<br>
.{c-dl-array} and its length field in the same root field; structure<br>
field containing length field is a variant field.<br>
====<br>
The following JSON object is an event record payload<br>
{struct-fc}.<br>
<br>
The length field of the {dl-array} field is within a structure field<br>
which is a variant field.<br>
<br>
Moreover:<br>
<br>
* The selector field of the variant field is located in another root<br>
field (event record common context).<br>
<br>
* The field class of the third option of the `glass` variant field class<br>
contains a {dl-blob-fc} (`lock` member); the<br>
length field of its instance is the previous member (`eagle`) within<br>
the same structure field.<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "glass",<br>
"field-class": {<br>
"type": "variant",<br>
"selector-field-location": ["event-record-common-context", "sel"],<br>
"options": [<br>
{<br>
"selector-field-ranges": [[0, 0]],<br>
"field-class": {<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "eagle",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer", <3><br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"name": "road",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
]<br>
}<br>
},<br>
{<br>
"selector-field-ranges": [[32, 172]],<br>
"field-class": {<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "nuance",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
},<br>
{<br>
"name": "eagle",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer", <3><br>
"length": 24,<br>
"byte-order": "big-endian"<br>
}<br>
}<br>
]<br>
}<br>
},<br>
{<br>
"selector-field-ranges": [[5, 5]],<br>
"field-class": {<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "eagle", <5><br>
"field-class": {<br>
"type": "variable-length-unsigned-integer" <3><br>
}<br>
},<br>
{<br>
"name": "lock",<br>
"field-class": {<br>
"type": "dynamic-length-blob",<br>
"length-field-location": [ <4><br>
"event-record-payload",<br>
"glass",<br>
"eagle"<br>
]<br>
}<br>
}<br>
]<br>
}<br>
}<br>
]<br>
}<br>
},<br>
{<br>
"name": "margin",<br>
"field-class": {<br>
"type": "dynamic-length-array", <1><br>
"length-field-location": [ <2><br>
"event-record-payload",<br>
"glass",<br>
"eagle"<br>
],<br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> {c-dl-array-fc}.<br>
<2> {c-dl-array-fc}'s length field location.<br>
<3> Possible length field class.<br>
<4> {c-dl-blob-fc}'s length field location.<br>
<5> Length field class for {dl-blob-fc}.<br>
<br>
Note that both the {dl-array} and {dl-blob} field classes have the same<br>
length field location.<br>
====<br>
<br>
.{c-dl-array} and its length field in another root field.<br>
====<br>
The following JSON objects are the event record specific context and<br>
payload <<struct-fc,structure field classes>> of the same<br>
<<erc-frag,event record class>>.<br>
<br>
The length field of the event record payload's {dl-array} field is<br>
within the event record specific context.<br>
<br>
.Event record specific context field class.<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "cook",<br>
"field-class": {<br>
"type": "fixed-length-floating-point-number",<br>
"length": 64,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"name": "vegetable", <1><br>
"field-class": {<br>
"type": "variable-length-unsigned-integer"<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> Length member class.<br>
<br>
.Event record payload field class.<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "avenue",<br>
"field-class": {<br>
"type": "dynamic-length-array", <1><br>
"length-field-location": [ <2><br>
"event-record-specific-context",<br>
"vegetable"<br>
],<br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
},<br>
{<br>
"name": "railroad",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
]<br>
}<br>
----<br>
<1> {c-dl-array-fc}.<br>
<2> {c-dl-array-fc}'s length field location.<br>
====<br>
<br>
[[int-range-set]]<br>
==== Integer range set<br>
<br>
An _integer range set_ is a JSON array of integer ranges.<br>
<br>
An integer range set {must} contain one or more integer ranges.<br>
<br>
An _integer range_ is a JSON array of two elements:<br>
<br>
. The range's lower bound (JSON integer, included).<br>
. The range's upper bound (JSON integer, included).<br>
<br>
An integer range represents all the integer values from the range's<br>
lower bound to its upper bound.<br>
<br>
An integer range's upper bound {must} be greater than or equal to its<br>
lower bound.<br>
<br>
If both the lower and upper bounds of an integer range are equal, then<br>
the integer range represents a single integer value.<br>
<br>
.Integer ranges.<br>
====<br>
[source,json]<br>
----<br>
[3, 67]<br>
----<br>
<br>
[source,json]<br>
----<br>
[-45, 101]<br>
----<br>
<br>
.Single integer value.<br>
[source,json]<br>
----<br>
[42, 42]<br>
----<br>
====<br>
<br>
.Integer range set containing three integer ranges.<br>
====<br>
[source,json]<br>
----<br>
[[3, 67], [-45, 1], [42, 42]]<br>
----<br>
====<br>
<br>
[[roles]]<br>
==== Roles<br>
<br>
Some <<fc,field class>> instances can have _roles_.<br>
<br>
A role is specific semantics attached to the fields (instances) of a<br>
field class. For example, the `packet-magic-number` role of a<br>
{fl-int-fc} indicates that<br>
the value of its instances {must} be the <<pkt,packet>> magic number<br>
(0xc1fc1fc1).<br>
<br>
Roles are a JSON array of role names (JSON strings).<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
<br>
[[fl-ba-fc]]<br>
==== {c-fl-ba} field class<br>
<br>
A _{fl-ba}_ field class describes _{fl-ba}_ fields.<br>
<br>
A {fl-ba} field is a simple array of contiguous bits, without any<br>
attached integer type semantics.<br>
<br>
The length, or number of bits, of a {fl-ba} field is a property<br>
(`length`) of its class.<br>
<br>
A {fl-ba} field class acts as a base of a {fl-bool-fc}, a {fl-int-fc},<br>
and a {fl-fp-fc}.<br>
<br>
.Common properties of a {fl-ba} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"fixed-length-bit-array"`.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bits of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than zero.<br>
|Yes<br>
|<br>
<br>
|`byte-order`<br>
|JSON string<br>
|{c-bo} of an instance<br>
of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"big-endian"`::<br>
Big-endian.<br>
<br>
`"little-endian"`::<br>
Little-endian.<br>
|Yes<br>
|<br>
<br>
|`alignment`<br>
|JSON integer<br>
|Alignment of the first bit of an instance of{nbsp}{var-f}<br>
relative to the beginning of the <<pkt,packet>> which<br>
contains this instance.<br>
<br>
The value of this property {must} be a positive power of two.<br>
|No<br>
|`1`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {fl-ba} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-bit-array",<br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-ba} field class with a 32-bit alignment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-bit-array",<br>
"length": 48,<br>
"byte-order": "big-endian",<br>
"alignment": 32<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-ba} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-bit-array",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[fl-bool-fc]]<br>
==== {c-fl-bool} field class<br>
<br>
A _{fl-bool}_ field class is a {fl-ba-fc} which describes<br>
_{fl-bool}_ fields.<br>
<br>
A {fl-bool} field is a {fl-ba} field which has the following<br>
semantics:<br>
<br>
If all the bit array field's bits are cleared (zero)::<br>
The {fl-bool} field's value is _false_.<br>
<br>
Otherwise::<br>
The {fl-bool} field's value is _true_.<br>
<br>
.Properties of a {fl-bool} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"fixed-length-boolean"`.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bits of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than zero.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`byte-order`<br>
|JSON string<br>
|{c-bo} of an instance<br>
of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"big-endian"`::<br>
Big-endian.<br>
<br>
`"little-endian"`::<br>
Little-endian.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`alignment`<br>
|JSON integer<br>
|Alignment of the first bit of an instance of{nbsp}{var-f}<br>
relative to the beginning of the <<pkt,packet>> which<br>
contains this instance.<br>
<br>
The value of this property {must} be a positive power of two.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|No<br>
|`1`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {fl-bool} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-boolean",<br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-bool} field class with a 32-bit alignment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-boolean",<br>
"length": 48,<br>
"byte-order": "big-endian",<br>
"alignment": 32<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-bool} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-boolean",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[int-fc]]<br>
==== Abstract integer field class<br>
<br>
An _abstract integer_ field class is a base of a {fl-int-fc} and a<br>
{vl-int-fc}.<br>
<br>
This field class is abstract in that it only exists to show the relation<br>
between different integer field classes in this document: a <<pkt,packet>><br>
cannot contain an abstract integer field.<br>
<br>
.Common property of an integer field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`preferred-display-base`<br>
|JSON integer<br>
|Preferred base to display the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`2`::<br>
Binary base.<br>
<br>
`8`::<br>
Octal base.<br>
<br>
`10`::<br>
Decimal base.<br>
<br>
`16`::<br>
Hexadecimal base.<br>
|No<br>
|`10`<br>
|===<br>
<br>
[[fl-int-fc]]<br>
==== {c-fl-int} field class<br>
<br>
A _{fl-int}_ field class is both an <<int-fc,abstract integer field<br>
class>> and a {fl-ba-fc} which describes<br>
_{fl-int}_ fields.<br>
<br>
A {fl-int} field is a {fl-ba} field which has integer semantics.<br>
<br>
If the value of a {fl-int} field class's `type` property is<br>
`"fixed-length-signed-integer"`, then its instances have the two's<br>
complement format.<br>
<br>
A {fl-int} field class acts as a base of a {fl-enum-fc}.<br>
<br>
.Common properties of a {fl-int} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"fixed-length-unsigned-integer"`::<br>
The instances of{nbsp}{var-f} are {fl-uint} fields.<br>
<br>
`"fixed-length-signed-integer"`::<br>
The instances of{nbsp}{var-f} are {fl-sint} fields.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bits of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than zero.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`byte-order`<br>
|JSON string<br>
|{c-bo} of an instance<br>
of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"big-endian"`::<br>
Big-endian.<br>
<br>
`"little-endian"`::<br>
Little-endian.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`alignment`<br>
|JSON integer<br>
|Alignment of the first bit of an instance of{nbsp}{var-f}<br>
relative to the beginning of the <<pkt,packet>> which<br>
contains this instance.<br>
<br>
The value of this property {must} be a positive power of two.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|No<br>
|`1`<br>
<br>
|`preferred-display-base`<br>
|JSON integer<br>
|Preferred base to display the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`2`::<br>
Binary base.<br>
<br>
`8`::<br>
Octal base.<br>
<br>
`10`::<br>
Decimal base.<br>
<br>
`16`::<br>
Hexadecimal base.<br>
<br>
Property inherited from the <<int-fc,abstract integer field class>>.<br>
|No<br>
|`10`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {fl-uint} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 16,<br>
"byte-order": "little-endian"<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-sint} field class with a 32-bit alignment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-signed-integer",<br>
"length": 48,<br>
"byte-order": "big-endian",<br>
"alignment": 32<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-uint} field class with a preferred hexadecimal display base.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 48,<br>
"byte-order": "big-endian",<br>
"preferred-display-base": 16<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-sint} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-signed-integer",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[enum-fc]]<br>
==== Abstract enumeration field class<br>
<br>
An _abstract enumeration_ field class is a base of a {fl-enum-fc} and a<br>
{vl-enum-fc}.<br>
<br>
This field class is abstract in that it only exists to show the relation<br>
between different enumeration field classes in this document: a<br>
<<pkt,packet>> cannot contain an abstract enumeration field.<br>
<br>
An abstract enumeration field class is an <<int-fc,abstract integer<br>
field class>>.<br>
<br>
An enumeration field is an integer field which {may} have one or more<br>
associated names thanks to its class's `mappings` property.<br>
<br>
.Common property of an enumeration field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`preferred-display-base`<br>
|JSON integer<br>
|Preferred base to display the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`2`::<br>
Binary base.<br>
<br>
`8`::<br>
Octal base.<br>
<br>
`10`::<br>
Decimal base.<br>
<br>
`16`::<br>
Hexadecimal base.<br>
<br>
Property inherited from the <<int-fc,abstract integer field class>>.<br>
|No<br>
|`10`<br>
<br>
|`mappings`<br>
|<<enum-fc-mappings,Enumeration field class mappings>><br>
|Mappings of{nbsp}{var-f}.<br>
<br>
The value of this property {must} contain one or more properties.<br>
|Yes<br>
|<br>
|===<br>
<br>
[[enum-fc-mappings]]<br>
===== Enumeration field class mappings<br>
<br>
_Enumeration field class mappings_ map names to<br>
<<int-range-set,integer range sets>>.<br>
<br>
Enumeration field class mappings are a JSON object, where each property<br>
is:<br>
<br>
[horizontal]<br>
Name::<br>
Mapping name.<br>
<br>
Value::<br>
Mapped ranges of integers (<<int-range-set,integer range set>>).<br>
<br>
The integer ranges of two given mappings {may} overlap.<br>
<br>
Enumeration field class mappings {must} contain one or more properties.<br>
<br>
.Enumeration field class mappings with three mappings.<br>
====<br>
In this example, the `fortune` and `building` mappings overlap with the<br>
values 4 and 5, and the `building` and `journal` mappings overlap with<br>
the value 80.<br>
<br>
[source,json]<br>
----<br>
{<br>
"fortune": [[3, 67], [-45, 1], [84, 84]],<br>
"building": [[4, 5], [75, 82]],<br>
"journal": [[100, 2305], [80, 80]]<br>
}<br>
----<br>
====<br>
<br>
[[fl-enum-fc]]<br>
==== {c-fl-enum} field class<br>
<br>
A _{fl-enum}_ field class is both an <<enum-fc,abstract enumeration<br>
field class>> and a {fl-int-fc} which describes<br>
_{fl-enum}_ fields.<br>
<br>
A {fl-enum} field is a {fl-int} field which {may} have one or more<br>
associated names thanks to its class's `mappings` property.<br>
<br>
If the value of a {fl-enum} field class's `type` property is<br>
`"fixed-length-signed-enumeration"`, then its instances have the two's<br>
complement format.<br>
<br>
.Properties of a {fl-enum} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"fixed-length-unsigned-enumeration"`::<br>
The instances of{nbsp}{var-f} are {fl-uenum} fields.<br>
<br>
`"fixed-length-signed-enumeration"`::<br>
The instances of{nbsp}{var-f} are {fl-senum} fields.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bits of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than zero.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`byte-order`<br>
|JSON string<br>
|{c-bo} of an instance<br>
of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"big-endian"`::<br>
Big-endian.<br>
<br>
`"little-endian"`::<br>
Little-endian.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`alignment`<br>
|JSON integer<br>
|Alignment of the first bit of an instance of{nbsp}{var-f}<br>
relative to the beginning of the <<pkt,packet>> which<br>
contains this instance.<br>
<br>
The value of this property {must} be a positive power of two.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|No<br>
|`1`<br>
<br>
|`preferred-display-base`<br>
|JSON integer<br>
|Preferred base to display the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`2`::<br>
Binary base.<br>
<br>
`8`::<br>
Octal base.<br>
<br>
`10`::<br>
Decimal base.<br>
<br>
`16`::<br>
Hexadecimal base.<br>
<br>
Property inherited from the <<int-fc,abstract integer field class>>.<br>
|No<br>
|`10`<br>
<br>
|`mappings`<br>
|<<enum-fc-mappings,Enumeration field class mappings>><br>
|Mappings of{nbsp}{var-f}.<br>
<br>
The value of this property {must} contain one or more properties.<br>
<br>
Property inherited from the <<enum-fc,abstract enumeration field class>>.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {fl-uenum} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-unsigned-enumeration",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"mappings": {<br>
"apple": [[1, 19]]<br>
}<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-senum} field class with a 32-bit alignment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-signed-enumeration",<br>
"length": 48,<br>
"byte-order": "big-endian",<br>
"alignment": 32,<br>
"mappings": {<br>
"banana": [[-27399, -1882], [8, 199], [101, 101]],<br>
"orange": [[67, 67], [43, 1534]]<br>
}<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-uenum} field class with a preferred hexadecimal display base.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-unsigned-enumeration",<br>
"length": 8,<br>
"byte-order": "big-endian",<br>
"preferred-display-base": 16,<br>
"mappings": {<br>
"lime": [[3, 3]],<br>
"kiwi": [[8, 8]],<br>
"blueberry": [[11, 11]]<br>
}<br>
}<br>
----<br>
====<br>
<br>
.{c-fl-senum} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-signed-enumeration",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"mappings": {<br>
"mango": [[23, 42]]<br>
},<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[fl-fp-fc]]<br>
==== {c-fl-fp} field class<br>
<br>
A _{fl-fp}_ field class is a {fl-ba-fc} which describes _{fl-fp}_<br>
fields.<br>
<br>
A {fl-fp} field is a {fl-ba} field which has floating point number<br>
semantics.<br>
<br>
.Properties of a {fl-fp} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"fixed-length-floating-point-number"`.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bits of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`16`::<br>
The instances of{nbsp}{var-f} are binary16 floating point numbers,<br>
as per {ieee754}.<br>
<br>
`32`::<br>
The instances of{nbsp}{var-f} are binary32 floating point numbers.<br>
<br>
`64`::<br>
The instances of{nbsp}{var-f} are binary64 floating point numbers.<br>
<br>
`128`::<br>
The instances of{nbsp}{var-f} are binary128 floating point<br>
numbers.<br>
<br>
_**K**_, where _**K**_ is greater than{nbsp}128 and a multiple of{nbsp}32::<br>
The instances of{nbsp}{var-f} are binary__**K**__ floating point<br>
numbers.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`byte-order`<br>
|JSON string<br>
|{c-bo} of an instance<br>
of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"big-endian"`::<br>
Big-endian.<br>
<br>
`"little-endian"`::<br>
Little-endian.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|Yes<br>
|<br>
<br>
|`alignment`<br>
|JSON integer<br>
|Alignment of the first bit of an instance of{nbsp}{var-f}<br>
relative to the beginning of the <<pkt,packet>> which<br>
contains this instance.<br>
<br>
The value of this property {must} be a positive power of two.<br>
<br>
Property inherited from the {fl-ba-fc}.<br>
|No<br>
|`1`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal binary32 {fl-fp} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-floating-point-number",<br>
"length": 32,<br>
"byte-order": "little-endian"<br>
}<br>
----<br>
====<br>
<br>
.binary64 {fl-fp} field class with a 32-bit alignment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-floating-point-number",<br>
"length": 64,<br>
"byte-order": "big-endian",<br>
"alignment": 32<br>
}<br>
----<br>
====<br>
<br>
.binary192 {fl-fp} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "fixed-length-floating-point-number",<br>
"length": 192,<br>
"byte-order": "little-endian",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[vl-ba-fc]]<br>
==== {c-vl-ba} field class<br>
<br>
A _{vl-ba}_ field class describes _{vl-ba}_ fields.<br>
<br>
A {vl-ba} field is a sequence of bytes with a variable length<br>
which contains an array of bits of which the length is a<br>
multiple of{nbsp}7. A {vl-ba} field is encoded as per<br>
<a href="https://en.wikipedia.org/wiki/LEB128[LEB128">https://en.wikipedia.org/wiki/LEB128[LEB128</a>].<br>
<br>
A {vl-ba} field class acts as a base of a {vl-int-fc}.<br>
<br>
.Common properties of a {vl-ba} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"variable-length-bit-array"`.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {vl-ba} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-bit-array"<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-ba} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-bit-array",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[vl-int-fc]]<br>
==== {c-vl-int} field class<br>
<br>
A _{vl-int}_ field class is both an <<int-fc,abstract integer field<br>
class>> and a {vl-ba-fc} which describes<br>
_{vl-int}_ fields.<br>
<br>
A {vl-int} field is a {vl-ba} field which has integer semantics.<br>
<br>
If the value of a {vl-int} field class's `type` property is<br>
`"variable-length-signed-integer"`, then its instances have the two's<br>
complement format.<br>
<br>
A {vl-int} field class acts as a base of a {vl-enum-fc}.<br>
<br>
.Common properties of a {vl-int} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"variable-length-unsigned-integer"`::<br>
The instances of{nbsp}{var-f} are {vl-uint} fields.<br>
<br>
`"variable-length-signed-integer"`::<br>
The instances of{nbsp}{var-f} are {vl-sint} fields.<br>
|Yes<br>
|<br>
<br>
|`preferred-display-base`<br>
|JSON integer<br>
|Preferred base to display the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`2`::<br>
Binary base.<br>
<br>
`8`::<br>
Octal base.<br>
<br>
`10`::<br>
Decimal base.<br>
<br>
`16`::<br>
Hexadecimal base.<br>
<br>
Property inherited from the <<int-fc,abstract integer field class>>.<br>
|No<br>
|`10`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {vl-uint} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-unsigned-integer"<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-sint} field class with a preferred hexadecimal display base.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-signed-integer",<br>
"preferred-display-base": 16<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-uint} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-unsigned-integer",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[vl-enum-fc]]<br>
==== {c-vl-enum} field class<br>
<br>
A _{vl-enum}_ field class is both an <<enum-fc,abstract enumeration<br>
field class>> and a {vl-int-fc} which describes<br>
_{vl-enum}_ fields.<br>
<br>
A {vl-enum} field is a {vl-int} field which {may} have one or more<br>
associated names thanks to its class's `mappings` property.<br>
<br>
If the value of a {vl-enum} field class's `type` property is<br>
`"variable-length-signed-enumeration"`, then its instances have the<br>
two's complement format.<br>
<br>
.Properties of a {vl-enum} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`"variable-length-unsigned-enumeration"`::<br>
The instances of{nbsp}{var-f} are {vl-uenum} fields.<br>
<br>
`"variable-length-signed-enumeration"`::<br>
The instances of{nbsp}{var-f} are {vl-senum} fields.<br>
|Yes<br>
|<br>
<br>
|`preferred-display-base`<br>
|JSON integer<br>
|Preferred base to display the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be one of:<br>
<br>
`2`::<br>
Binary base.<br>
<br>
`8`::<br>
Octal base.<br>
<br>
`10`::<br>
Decimal base.<br>
<br>
`16`::<br>
Hexadecimal base.<br>
<br>
Property inherited from the <<int-fc,abstract integer field class>>.<br>
|No<br>
|`10`<br>
<br>
|`mappings`<br>
|<<enum-fc-mappings,Enumeration field class mappings>><br>
|Mappings of{nbsp}{var-f}.<br>
<br>
The value of this property {must} contain one or more properties.<br>
<br>
Property inherited from the <<enum-fc,abstract enumeration field class>>.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {vl-uenum} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-unsigned-enumeration",<br>
"mappings": {<br>
"apple": [[1, 19]]<br>
}<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-uenum} field class with a preferred hexadecimal display base.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-unsigned-enumeration",<br>
"preferred-display-base": 16,<br>
"mappings": {<br>
"lime": [[3, 3]],<br>
"kiwi": [[8, 8]],<br>
"blueberry": [[11, 11]]<br>
}<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-senum} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variable-length-signed-enumeration",<br>
"mappings": {<br>
"banana": [[-27399, -1882], [8, 199], [101, 101]],<br>
"orange": [[67, 67], [43, 1534]]<br>
},<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[str-fc]]<br>
==== {c-str} field class<br>
<br>
A _{str}_ field class describes _{str}_ fields.<br>
<br>
A {str} field is, in this order:<br>
<br>
. Zero or more contiguous non-null (non-zero) bytes which form a<br>
UTF-8-encoded string.<br>
<br>
. One null (zero) byte.<br>
<br>
.Properties of a {str} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"null-terminated-string"`.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal {str} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "null-terminated-string"<br>
}<br>
----<br>
====<br>
<br>
.{c-str} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "null-terminated-string",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-nice": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[sl-str-fc]]<br>
==== {c-sl-str} field class<br>
<br>
A _{sl-str}_ field class describes _{sl-str}_ fields.<br>
<br>
A {sl-str} field is a sequence of zero or more contiguous bytes. All<br>
the bytes of a {sl-str} before the first null (zero) byte, if any,<br>
form a UTF-8-encoded string. All the bytes after the first null (zero)<br>
byte, if any, are garbage data.<br>
<br>
The length, or number of bytes, of a {sl-str} field is a property<br>
(`length`) of its class.<br>
<br>
.Properties of a {sl-str} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"static-length-string"`.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bytes contained in an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Empty {sl-str} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-string",<br>
"length": 0<br>
}<br>
----<br>
====<br>
<br>
.{c-sl-str} field class with instances having 100{nbsp}bytes.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-string",<br>
"length": 100<br>
}<br>
----<br>
====<br>
<br>
.{c-sl-str} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-string",<br>
"length": 13,<br>
"user-attributes": {<br>
"my.tracer": null<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[dl-str-fc]]<br>
==== {c-dl-str} field class<br>
<br>
A _{dl-str}_ field class describes _{dl-str}_ fields.<br>
<br>
A {dl-str} field is a sequence of zero or more contiguous bytes. All<br>
the bytes of a {dl-str} before the first null (zero) byte, if any,<br>
form a UTF-8-encoded string. All the bytes after the first null (zero)<br>
byte, if any, are garbage data.<br>
<br>
The length, or number of bytes, of a {dl-str} field is the value of<br>
another, anterior length field. A consumer can find this length field<br>
thanks to the {dl-str} field class's `length-field-location` property.<br>
<br>
.Properties of a {dl-str} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"static-length-string"`.<br>
|Yes<br>
|<br>
<br>
|`length-field-location`<br>
|<<field-loc,Field location>><br>
|Location of the field of which the value is the number of bytes<br>
contained in an instance of{nbsp}{var-f}.<br>
<br>
The class of the length field {must} be one of:<br>
<br>
* {c-fl-uint-fc}<br>
* {c-vl-uint-fc}<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.{c-dl-str} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "dynamic-length-string",<br>
"length-field-location": ["event-record-payload", "length"]<br>
}<br>
----<br>
====<br>
<br>
.{c-dl-str} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "dynamic-length-string",<br>
"length-field-location": ["event-record-common-context", "name-length"],<br>
"user-attributes": {<br>
"my.tracer": 177<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[blob-fc]]<br>
==== Abstract BLOB field class<br>
<br>
An _abstract <a href="https://en.wikipedia.org/wiki/Binary_large_object[BLOB]_">https://en.wikipedia.org/wiki/Binary_large_object[BLOB]_</a><br>
field class is a base of a {sl-blob-fc} and a {dl-blob-fc}.<br>
<br>
This field class is abstract in that it only exists to show the relation<br>
between different BLOB field classes in this document: a <<pkt,packet>><br>
cannot contain an abstract BLOB field.<br>
<br>
.Common properties of a BLOB field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`media-type`<br>
|JSON string<br>
|https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[IANA<br>
media type] of an instance of{nbsp}{var-f}.<br>
|No<br>
|`"application/octet-stream"`<br>
|===<br>
<br>
[[sl-blob-fc]]<br>
==== {c-sl-blob} field class<br>
<br>
A _{sl-blob}_ field class is an <<blob-fc,abstract BLOB field class>><br>
which describes _{sl-blob}_ fields.<br>
<br>
A {sl-blob} field is a sequence of zero or more contiguous bytes with an<br>
associated IANA media type (given by its class's `media-type` property).<br>
<br>
The length, or number of bytes, of a {sl-blob} field is a property<br>
(`length`) of its class.<br>
<br>
.Properties of a {sl-blob} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"static-length-blob"`.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of bytes contained in an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
|Yes<br>
|<br>
<br>
|`media-type`<br>
|JSON string<br>
|https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[IANA<br>
media type] of an instance of{nbsp}{var-f}.<br>
<br>
Property inherited from the <<blob-fc,abstract BLOB field class>>.<br>
|No<br>
|`"application/octet-stream"`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Empty {sl-blob} field class with a default IANA media type.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-blob",<br>
"length": 0<br>
}<br>
----<br>
====<br>
<br>
.Static-length TIFF BLOB field class with instances having 511,267{nbsp}bytes.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-blob",<br>
"length": 511267,<br>
"media-type": "image/tif"<br>
}<br>
----<br>
====<br>
<br>
.Static-length CSV BLOB field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-blob",<br>
"length": 2400,<br>
"media-type": "text/csv",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"csv-cols": 12<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[dl-blob-fc]]<br>
==== {c-dl-blob} field class<br>
<br>
A _{dl-blob}_ field class is an <<blob-fc,abstract BLOB field class>><br>
which describes _{dl-blob}_ fields.<br>
<br>
A {dl-blob} field is a sequence of zero or more contiguous bytes with an<br>
associated IANA media type.<br>
<br>
The length, or number of bytes, of a {dl-blob} field is the value of<br>
another, anterior length field. A consumer can find this length field<br>
thanks to the {dl-blob} field class's `length-field-location` property.<br>
<br>
.Properties of a {dl-blob} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"dynamic-length-blob"`.<br>
|Yes<br>
|<br>
<br>
|`length-field-location`<br>
|<<field-loc,Field location>><br>
|Location of the field of which the value is the number of bytes<br>
contained in an instance of{nbsp}{var-f}.<br>
<br>
The class of the length field {must} be one of:<br>
<br>
* {c-fl-uint-fc}<br>
* {c-vl-uint-fc}<br>
|Yes<br>
|<br>
<br>
|`media-type`<br>
|JSON string<br>
|https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[IANA<br>
media type] of an instance of{nbsp}{var-f}.<br>
<br>
Property inherited from the <<blob-fc,abstract BLOB field class>>.<br>
|No<br>
|`"application/octet-stream"`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.{c-dl-blob} field class with a default IANA media type.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "dynamic-length-blob",<br>
"length-field-location": ["event-record-payload", "length"]<br>
}<br>
----<br>
====<br>
<br>
.Dynamic-length JPEG BLOB field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "dynamic-length-blob",<br>
"length-field-location": ["event-record-common-context", "length"],<br>
"media-type": "image/jpeg",<br>
"user-attributes": {<br>
"my.tracer": {<br>
"quality": 85<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[struct-fc]]<br>
==== Structure field class<br>
<br>
A _structure field class_ describes _structure fields_.<br>
<br>
A structure field is a sequence of zero or more structure field<br>
_members_. A structure field member is a named field.<br>
<br>
.Properties of a structure field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"structure"`.<br>
|Yes<br>
|<br>
<br>
|`members`<br>
|JSON array of <<struct-member-cls,structure field member classes>><br>
|Classes of the members of an instance of{nbsp}{var-f}.<br>
<br>
Each member class's `name` property must be unique within this field<br>
class's member class names.<br>
|No<br>
|`+[]+`<br>
<br>
|`minimum-alignment`<br>
|JSON integer<br>
|Minimum alignment of the first bit of an instance of{nbsp}{var-f}<br>
relative to the beginning of the <<pkt,packet>> which contains this<br>
instance.<br>
<br>
The value of this property {must} be a positive power of two.<br>
<br>
The <<align-dec,_effective_ alignment>> of the first bit of an instance<br>
of{nbsp}{var-f} {may} be greater than the value of this property.<br>
|No<br>
|`1`<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Empty structure field class (no member classes).<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "structure"<br>
}<br>
----<br>
====<br>
<br>
.Structure field class with three member classes.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "Villeray",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
},<br>
{<br>
"name": "Berri",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 32,<br>
"byte-order": "little-endian",<br>
"preferred-display-base": 2<br>
},<br>
"user-attributes": {<br>
"my.tracer": {<br>
"is-mask": true<br>
}<br>
}<br>
},<br>
{<br>
"name": "Faillon",<br>
"field-class": {<br>
"type": "fixed-length-boolean",<br>
"length": 8,<br>
"byte-order": "little-endian"<br>
}<br>
}<br>
]<br>
}<br>
----<br>
====<br>
<br>
.Structure field class with a minimum alignment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "St-Denis",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
},<br>
{<br>
"name": "Lajeunesse",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 32,<br>
"byte-order": "big-endian",<br>
"alignment": 32<br>
}<br>
}<br>
],<br>
"minimum-alignment": 64<br>
}<br>
----<br>
====<br>
<br>
.Structure field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "Henri-Julien",<br>
"field-class": {<br>
"type": "fixed-length-signed-integer",<br>
"length": 48,<br>
"byte-order": "little-endian"<br>
}<br>
},<br>
{<br>
"name": "Casgrain",<br>
"field-class": {<br>
"type": "static-length-string",<br>
"length": 32<br>
}<br>
}<br>
],<br>
"user-attributes": {<br>
"my.tracer": {<br>
"version": 4<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[struct-member-cls]]<br>
===== Structure field member class<br>
<br>
A _structure field member class_ describes _structure field members_.<br>
<br>
A structure field member class is a JSON object.<br>
<br>
.Properties of a structure field member class _**M**_.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`name`<br>
|JSON string<br>
|Name of{nbsp}__**M**__.<br>
|Yes<br>
|<br>
<br>
|`field-class`<br>
|<<fc,Field class>><br>
|Field class of{nbsp}__**M**__.<br>
|Yes<br>
|<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}__**M**__.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}__**M**__.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.<<str-fc,{c-str} field class>> member class named `cat`.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"name": "cat",<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
}<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-sint-fc} member class named `dog` with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"name": "dog",<br>
"field-class": {<br>
"type": "variable-length-signed-integer",<br>
"preferred-display-base": 8<br>
},<br>
"user-attributes": {<br>
"my.tracer": {<br>
"uuid": "f36100b8-ec36-4861-8d6b-a9d6ab8973c9",<br>
"is-pid": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[array-fc]]<br>
==== Abstract array field class<br>
<br>
An _abstract array_ field class is a base of a {sl-array-fc}<br>
and a {dl-array-fc}.<br>
<br>
This field class is abstract in that it only exists to show the relation<br>
between different array field classes in this document: a <<pkt,packet>><br>
cannot contain an abstract array field.<br>
<br>
.Common properties of an array field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`element-field-class`<br>
|<<fc,Field class>><br>
|Class of the element fields contained in an instance of{nbsp}{var-f}.<br>
|Yes<br>
|<br>
|===<br>
<br>
[[sl-array-fc]]<br>
==== {c-sl-array} field class<br>
<br>
A _{sl-array}_ field class is an <<array-fc,abstract array field class>><br>
which describes _{sl-array}_ fields.<br>
<br>
A {sl-array} field is a sequence of zero or more element fields.<br>
<br>
The length, or number of element fields, of a {sl-array} field is a<br>
property (`length`) of its class.<br>
<br>
.Properties of a {sl-array} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"static-length-array"`.<br>
|Yes<br>
|<br>
<br>
|`element-field-class`<br>
|<<fc,Field class>><br>
|Class of the element fields contained in an instance of{nbsp}{var-f}.<br>
<br>
Property inherited from the <<array-fc,abstract array field class>>.<br>
|Yes<br>
|<br>
<br>
|`length`<br>
|JSON integer<br>
|Number of element fields contained in an instance of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Empty {sl-array} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-array",<br>
"element-field-class": {<br>
"type": "fixed-length-signed-integer",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"alignment": 16<br>
},<br>
"length": 0<br>
}<br>
----<br>
====<br>
<br>
.{c-sl-array} field class with instances having<br>
100{nbsp}<<str-fc,{str}>> fields.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-array",<br>
"element-field-class": {<br>
"type": "null-terminated-string"<br>
},<br>
"length": 100<br>
}<br>
----<br>
====<br>
<br>
.{c-sl-array} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "static-length-array",<br>
"element-field-class": {<br>
"type": "variable-length-unsigned-integer"<br>
},<br>
"length": 13,<br>
"user-attributes": {<br>
"my.tracer": true<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[dl-array-fc]]<br>
==== {c-dl-array} field class<br>
<br>
A _{dl-array}_ field class is an <<array-fc,abstract array field class>><br>
which describes _{dl-array}_ fields.<br>
<br>
A {dl-array} field is a sequence of zero or more element fields.<br>
<br>
The length, or number of element fields, of a {dl-array} field is the<br>
value of another, anterior length field. A consumer can find this length<br>
field thanks to the {dl-array} field class's `length-field-location`<br>
property.<br>
<br>
.Properties of a {dl-array} field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"dynamic-length-array"`.<br>
|Yes<br>
|<br>
<br>
|`element-field-class`<br>
|<<fc,Field class>><br>
|Class of the element fields contained in an instance of{nbsp}{var-f}.<br>
<br>
Property inherited from the <<array-fc,abstract array field class>>.<br>
|Yes<br>
|<br>
<br>
|`length-field-location`<br>
|<<field-loc,Field location>><br>
|Location of the field of which the value is the number of element<br>
fields contained in an instance of{nbsp}{var-f}.<br>
<br>
The class of the length field {must} be one of:<br>
<br>
* {c-fl-uint-fc}<br>
* {c-vl-uint-fc}<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of an instance of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.{c-dl-array} field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "dynamic-length-array",<br>
"element-field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 32,<br>
"byte-order": "big-endian",<br>
"alignment": 16<br>
},<br>
"length-field-location": ["event-record-payload", "length"]<br>
}<br>
----<br>
====<br>
<br>
.{c-dl-array} field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "dynamic-length-array",<br>
"element-field-class": {<br>
"type": "variable-length-unsigned-integer"<br>
},<br>
"length-field-location": ["packet-context", "common-length"],<br>
"user-attributes": {<br>
"my.tracer": 177<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[opt-fc]]<br>
==== Optional field class<br>
<br>
An _optional_ field class describes _optional_ fields.<br>
<br>
An optional field is, depending on the value of another, anterior<br>
selector field, one of:<br>
<br>
* An instance of a given field class (optional field class's<br>
`field-class` property).<br>
+<br>
In this case, the optional field is said to be _enabled_.<br>
<br>
* A zero-bit field (no field).<br>
+<br>
In this case, the optional field is said to be _disabled_.<br>
<br>
A consumer can find the selector field thanks to the optional field<br>
class's `selector-field-location` property.<br>
<br>
.Properties of an optional field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"optional"`.<br>
|Yes<br>
|<br>
<br>
|`field-class`<br>
|<<fc,Field class>><br>
|Class of an instance of{nbsp}{var-f} when it's enabled.<br>
|Yes<br>
|<br>
<br>
|`selector-field-location`<br>
|<<field-loc,Field location>><br>
|Location of the field of which the value indicates whether or not an<br>
instance of{nbsp}{var-f} is enabled.<br>
<br>
The selector field {must} be an instance of one of:<br>
<br>
{c-fl-bool-fc}::<br>
An instance of{nbsp}{var-f} is enabled when the selector field is<br>
true.<br>
<br>
{c-fl-int-fc}::<br>
{c-vl-int-fc}::<br>
An instance of{nbsp}{var-f} is enabled when the selector field's<br>
value is an element of any of the integer ranges of{nbsp}{var-f}'s<br>
`selector-field-ranges` property.<br>
|Yes<br>
|<br>
<br>
|`selector-field-ranges`<br>
|<<int-range-set,Integer range set>><br>
|Ranges of integers which the value of a selector field {must} be an<br>
element of to enable an instance of{nbsp}{var-f}.<br>
|Yes, if the selector field is an instance of a {fl-int-fc}<br>
or a {vl-int-fc}.<br>
|None if the selector field is an instance of a {fl-bool-fc}.<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
<br>
.Optional {sl-array-fc} with a <<bool-fc,boolean>> selector field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "optional",<br>
"selector-field-location": ["event-record-payload", "has-ip"],<br>
"field-class": {<br>
"type": "static-length-array",<br>
"element-field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 8,<br>
"byte-order": "little-endian",<br>
"alignment": 8<br>
},<br>
"length": 16<br>
}<br>
}<br>
----<br>
====<br>
<br>
.Optional {sl-array-fc} with a <<fl-int-fc,fixed-length signed<br>
integer>> selector field class.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "optional",<br>
"selector-field-location": ["event-record-payload", "has-ip"],<br>
"selector-field-ranges": [[-12, -12], [-5, 0], [15, 35]],<br>
"field-class": {<br>
"type": "static-length-array",<br>
"element-field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 8,<br>
"byte-order": "little-endian",<br>
"alignment": 8<br>
},<br>
"length": 16<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[var-fc]]<br>
==== Variant field class<br>
<br>
A _variant_ field class describes _variant_ fields.<br>
<br>
A variant field is, depending on the value of another, anterior selector<br>
field, the instance of a specific, effective field class amongst one or<br>
more _variant field class options_.<br>
<br>
A consumer can find the selector field thanks to the variant field<br>
class's `selector-field-location` property.<br>
<br>
.Properties of a variant field class {var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"variant"`.<br>
|Yes<br>
|<br>
<br>
|`options`<br>
|JSON array of <<var-fc-opt,variant field class options>><br>
|Options containing the possible effective classes of an instance<br>
of{nbsp}{var-f}.<br>
<br>
This array {must} contain one or more elements.<br>
<br>
Each option's `name` property, if it's set, must be unique within this<br>
field class's option names.<br>
<br>
The integer ranges (`selector-field-ranges` property) of two given<br>
options {must-not} intersect.<br>
|Yes<br>
|<br>
<br>
|`selector-field-location`<br>
|<<field-loc,Field location>><br>
|Location of the field of which the value indicates which option<br>
of{nbsp}{var-f} contains the effective class of an instance<br>
of{nbsp}{var-f}.<br>
<br>
The selector field {must} be an instance of one of:<br>
<br>
* {c-fl-int-fc}<br>
* {c-vl-int-fc}<br>
|Yes<br>
|<br>
<br>
|`roles`<br>
|<<roles,Roles>><br>
|Roles of{nbsp}{var-f}.<br>
<br>
See <<tc-frag>> and <<dsc-frag>> which indicate accepted<br>
roles for their root field classes.<br>
|No<br>
|`+[]+`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Variant field class with two options.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variant",<br>
"selector-field-location": ["event-record-payload", "sel"],<br>
"options": [<br>
{<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
},<br>
"selector-field-ranges": [[5, 5]]<br>
},<br>
{<br>
"field-class": {<br>
"type": "fixed-length-signed-integer",<br>
"length": 16,<br>
"byte-order": "little-endian",<br>
"preferred-display-base": 8<br>
},<br>
"selector-field-ranges": [[8, 8]]<br>
}<br>
]<br>
}<br>
----<br>
====<br>
<br>
.Variant field class within an {opt-fc} which share the same selector<br>
field location.<br>
====<br>
This example shows that an optional field class and a contained variant<br>
field class {may} share the same selector field location.<br>
<br>
In this example, depending on the selector field's value:<br>
<br>
[horizontal]<br>
0::<br>
Optional field is _not_ enabled.<br>
<br>
1::<br>
Optional field is enabled and is a variant field.<br>
+<br>
Variant field is an instance of a {str-fc} (effective class).<br>
<br>
2::<br>
Optional field is enabled and is a variant field.<br>
+<br>
Variant field is an instance of a {vl-sint-fc}<br>
(effective class).<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "optional",<br>
"selector-field-location": ["event-record-payload", "sel"],<br>
"selector-field-ranges": [[1, 255]],<br>
"field-class": {<br>
"type": "variant",<br>
"selector-field-location": ["event-record-payload", "sel"],<br>
"options": [<br>
{<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
},<br>
"selector-field-ranges": [[1, 1]]<br>
},<br>
{<br>
"field-class": {<br>
"type": "variable-length-signed-integer",<br>
"preferred-display-base": 16<br>
},<br>
"selector-field-ranges": [[2, 2]]<br>
}<br>
]<br>
}<br>
}<br>
----<br>
====<br>
<br>
.Variant field class with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "variant",<br>
"selector-field-location": ["event-record-specific-context", "sel"],<br>
"options": [<br>
{<br>
"field-class": {<br>
"type": "static-length-string",<br>
"length": 20<br>
},<br>
"selector-field-ranges": [[5, 5], [10, 10], [15, 15]]<br>
},<br>
{<br>
"field-class": {<br>
"type": "fixed-length-floating-point-number",<br>
"length": 32,<br>
"byte-order": "big-endian"<br>
},<br>
"selector-field-ranges": [[0, 4], [6, 9], [11, 14], [16, 127]]<br>
}<br>
],<br>
"user-attributes": {<br>
"my.tracer": {<br>
"owner": "Jimmy",<br>
"id": 199990<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[var-fc-opt]]<br>
===== Variant field class option<br>
<br>
A _variant field class option_ contains a possible effective class of a<br>
variant field.<br>
<br>
A variant field class option _**O**_ also contains the ranges of integer<br>
values (`selector-field-ranges` property) of which a selector field's<br>
value {must} be an element of for a variant field's effective class to<br>
be the field class of {var-o}.<br>
<br>
A variant field class option is a JSON object.<br>
<br>
.Properties of a variant field class option {var-o} contained in a<br>
variant field class{nbsp}{var-f}.<br>
[%header%autowidth, cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`field-class`<br>
|<<fc,Field class>><br>
|Field class of{nbsp}{var-o}.<br>
|Yes<br>
|<br>
<br>
|`selector-field-ranges`<br>
|<<int-range-set,Integer range set>><br>
|Ranges of integers which the value of a selector field {must} be an<br>
element of for the effective class of an instance of{nbsp}{var-f}<br>
to be the field class (`field-class` property) of{nbsp}{var-o}.<br>
|Yes<br>
|<br>
<br>
|`name`<br>
|JSON string<br>
|Name of{nbsp}{var-o}.<br>
<br>
This property exists to remain backward compatible with {ctf1}.<br>
|No<br>
|{var-o} is unnamed<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-o}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-o}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Unnamed {str-fc} option.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"field-class": {<br>
"type": "null-terminated-string"<br>
},<br>
"selector-field-ranges": [[3, 9]]<br>
}<br>
----<br>
====<br>
<br>
.{c-vl-sint-fc} option named `juice` with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"name": "juice",<br>
"field-class": {<br>
"type": "variable-length-signed-integer",<br>
"preferred-display-base": 16<br>
},<br>
"selector-field-ranges": [[-4, 4], [9, 9], [100, 200]],<br>
"user-attributes": {<br>
"my.tracer": {<br>
"uuid": "f36100b8-ec36-4861-8d6b-a9d6ab8973c9",<br>
"is-did": true<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[preamble-frag]]<br>
=== Preamble fragment<br>
<br>
A _preamble fragment_ indicates:<br>
<br>
* The {ctf2} major version (2).<br>
+<br>
{ctf2} doesn't have a minor version: all new changes are introduced as<br>
<<ext,extensions>>.<br>
<br>
* <<ext,Extension>> declarations.<br>
+<br>
An extension declaration is an initial extension of which the purpose is<br>
to declare that it's _enabled_ within the <<metadata-stream,metadata<br>
stream>>.<br>
+<br>
Because an extension {may} alter the {ctf2} format itself, and because a<br>
preamble fragment is always the first metadata stream fragment, those<br>
extension declarations make it possible for a consumer to decline the<br>
trace's <<ds,data streams>> gracefully if it doesn't support _any_<br>
declared extension.<br>
<br>
The first fragment of a metadata stream {must} be a preamble fragment.<br>
<br>
.Properties of a preamble fragment {var-f}.<br>
[%header%autowidth]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"preamble"`.<br>
|Yes<br>
|<br>
<br>
|`version`<br>
|JSON integer<br>
|{ctf2} major version.<br>
<br>
The value of this property {must} be `2`.<br>
|Yes<br>
|<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extension declarations of{nbsp}{var-f}.<br>
<br>
The name of each property is a <<ns-def,namespace>> and its value is a<br>
<<ns-exts-obj,namespaced extensions object>>.<br>
<br>
Within a <<ns-exts-obj,namespaced extensions object>>, an extension<br>
named{nbsp}__**N**__ is _declared_ when it exists as a property<br>
named{nbsp}__**N**__, whatever the property's value.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
.Minimal preamble fragment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "preamble",<br>
"version": 2<br>
}<br>
----<br>
====<br>
<br>
.Preamble fragment with <<ext,extension>> declarations.<br>
====<br>
The following preamble fragment declares the `piano` and `ramen`<br>
extensions under the `my.tracer` namespace.<br>
<br>
[source,json]<br>
----<br>
{<br>
"type": "preamble",<br>
"version": 2,<br>
"extensions": {<br>
"my.tracer": {<br>
"piano": {<br>
"keys": 88,<br>
"temperament": "equal"<br>
},<br>
"ramen": null<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[tc-frag]]<br>
=== Trace class fragment<br>
<br>
A _trace class_ describes <<trace,_traces_>>.<br>
<br>
Within a metadata stream, a trace class fragment {must} occur before<br>
any <<dsc-frag,data stream class fragment>>.<br>
<br>
.Properties of a trace class fragment {var-f}.<br>
[%header%autowidth,cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"trace-class"`.<br>
|Yes<br>
|<br>
<br>
|`uuid`<br>
|<<uuid,UUID>><br>
|UUID of{nbsp}{var-f}.<br>
|No<br>
|{var-f}{nbsp}has no UUID<br>
<br>
|`packet-header-field-class`<br>
|{c-struct-fc}<br>
|Class of all the <<pkt-header,packet header fields>> of an instance<br>
of{nbsp}{var-f}.<br>
<br>
Any <<fc,field class>> within this property's value {must} satisfy at<br>
least one of:<br>
<br>
* Have at least one valid <<pkt-header-roles,role>>.<br>
* Be a {struct-fc}.<br>
* Be an {opt-fc}.<br>
* Be a {var-fc}.<br>
* Be the class of a field which is the selector field of an optional<br>
or variant field.<br>
|No<br>
|{var-f}{nbsp}has no packet header field class<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
==== Roles<br>
<br>
[[pkt-header-roles]]If the `packet-header-field-class` property of a<br>
trace class fragment exists, then its inner <<fc,field classes>> {may}<br>
have the following <<roles,roles>>:<br>
<br>
.Roles of field classes within a packet header field class.<br>
[%header%autowidth,cols="d,d,a,a"]<br>
|===<br>
|Name |Description |Field class ({var-f}) constraints |Other constraints<br>
<br>
|`packet-magic-number`<br>
|<<pkt,Packet>> magic number.<br>
<br>
The purpose of a packet magic number field is to confirm the<br>
beginning of a {ctf2} packet.<br>
|{c-fl-uint-fc} with the following property value:<br>
<br>
[horizontal]<br>
`length`::<br>
`32`<br>
|An instance of{nbsp}{var-f} {must} be the packet header structure<br>
field's _first_ member.<br>
<br>
The value of an instance of{nbsp}{var-f} value {must} be 0xc1fc1fc1<br>
(3254525889).<br>
<br>
|`trace-class-uuid`<br>
|Trace class UUID.<br>
<br>
The purpose of a trace class UUID field is to confirm the association<br>
between a <<ds,data stream>> and a <<metadata-stream-overview,metadata<br>
stream>>.<br>
|{c-sl-blob-fc} with the following property value:<br>
<br>
[horizontal]<br>
`length`::<br>
`16`<br>
|The `uuid` property of the trace class must exist.<br>
<br>
The value of an instance of{nbsp}{var-f} {must} be the binary<br>
representation of the `uuid` property of the trace class.<br>
<br>
|`data-stream-class-id`<br>
|Data stream class ID.<br>
<br>
The purpose of a data stream class ID field is to set the current ID of<br>
the class of the packet's data stream.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|<br>
<br>
|`data-stream-id`<br>
|Data stream ID.<br>
<br>
The purpose of a data stream ID field is to set the current ID of<br>
the packet's data stream.<br>
<br>
Combined with the ID of its class, such a field makes it possible to<br>
uniquely identify a data stream within a <<trace,trace>>.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|<br>
|===<br>
<br>
.Trace class fragment.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "trace-class",<br>
"uuid": "1ec96494-e402-4546-93db-e9222bee6cc7",<br>
"packet-header-field-class": {<br>
"type": "structure",<br>
"members": [<br>
{<br>
"name": "the magic!",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 32,<br>
"byte-order": "little-endian",<br>
"preferred-display-base": 16,<br>
"roles": ["packet-magic-number"]<br>
}<br>
},<br>
{<br>
"name": "the UUID",<br>
"field-class": {<br>
"type": "static-length-blob",<br>
"length": 16,<br>
"roles": ["trace-class-uuid"]<br>
}<br>
},<br>
{<br>
"name": "my data stream class ID",<br>
"field-class": {<br>
"type": "fixed-length-unsigned-integer",<br>
"length": 8,<br>
"byte-order": "little-endian",<br>
"roles": ["data-stream-class-id"]<br>
}<br>
},<br>
{<br>
"name": "my data stream ID",<br>
"field-class": {<br>
"type": "variable-length-unsigned-integer",<br>
"roles": ["data-stream-id"]<br>
}<br>
}<br>
]<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[cc-frag]]<br>
=== Clock class fragment<br>
<br>
A _clock class_ describes _clocks_.<br>
<br>
A <<ds,data stream>> {may} have a <<def-clk,default clock>>.<br>
<br>
Within a metadata stream, a clock class fragment {must} occur before any<br>
<<dsc-frag,data stream class fragment>> which refers to it by name with<br>
its `default-clock-class-name` property.<br>
<br>
.Properties of a clock class fragment {var-f}.<br>
[%header%autowidth,cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"clock-class"`.<br>
|Yes<br>
|<br>
<br>
|`frequency`<br>
|JSON integer<br>
|Frequency of an instance of{nbsp}{var-f} (Hz).<br>
<br>
The value of this property {must} be greater than zero.<br>
|Yes<br>
|<br>
<br>
|`name`<br>
|JSON string<br>
|Name of{nbsp}{var-f}.<br>
|Yes<br>
|<br>
<br>
|`description`<br>
|JSON string<br>
|Textual description of{nbsp}{var-f}.<br>
<br>
This property exists to remain backward compatible with {ctf1}.<br>
|No<br>
|{var-f}{nbsp}has no textual description<br>
<br>
|`uuid`<br>
|<<uuid,UUID>><br>
|UUID of{nbsp}{var-f}.<br>
<br>
This property exists to remain backward compatible with {ctf1}.<br>
|No<br>
|{var-f}{nbsp}has no UUID<br>
<br>
|`origin-is-unix-epoch`<br>
|JSON boolean<br>
|Whether or not the origin of an instance of{nbsp}{var-f} is<br>
the <a href="https://en.wikipedia.org/wiki/Unix_time[Unix">https://en.wikipedia.org/wiki/Unix_time[Unix</a> epoch].<br>
<br>
If the value of this property is `false`, then the origin of<br>
an instance of{nbsp}{var-f} is unknown.<br>
|No<br>
|`true`<br>
<br>
|`offset`<br>
|<<cc-offset,Clock class offset>><br>
|Offset of an instance of{nbsp}{var-f} relative to its origin.<br>
<br>
Let:<br>
<br>
* _**H**_ be the value of {var-f}'s `frequency` property.<br>
* {var-o} be the value of this property.<br>
* {var-s} be the value of {var-o}'s `seconds` property.<br>
* _**C**_ be the value of {var-o}'s `cycles` property.<br>
<br>
Then the effective offset of an instance of {var-f}, in clock<br>
cycles,<br>
is{nbsp}{var-s}{nbsp}{times}{nbsp}__**H**__{nbsp}pass:[+]{nbsp}__**C**__.<br>
|No<br>
|`{"seconds":{nbsp}0, "cycles":{nbsp}0}`<br>
<br>
|`precision`<br>
|JSON integer<br>
|Precision of an instance of{nbsp}{var-f} (clock cycles).<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
<br>
Let{nbsp}{var-p} be the value of this property and{nbsp}__**V**__<br>
the value of an instance of{nbsp}{var-f}: the range of possible<br>
values of the instance<br>
is{nbsp}[__**V**__{nbsp}{minus}{nbsp}{var-p},{nbsp}__**V**__{nbsp}pass:[+]{nbsp}{var-p}].<br>
|No<br>
|`0`<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
Within a metadata stream, two given clock class fragments {must-not}:<br>
<br>
* Share the same `name` property value.<br>
* Share the same `uuid` property value.<br>
<br>
.Minimal clock class fragment (1{nbsp}GHz frequency).<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "clock-class",<br>
"name": "my clock class",<br>
"frequency": 1000000000<br>
}<br>
----<br>
====<br>
<br>
.Clock class fragment with a UUID.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "clock-class",<br>
"name": "my clock class",<br>
"frequency": 1000000000,<br>
"uuid": "74d2008c-efff-4d03-8163-e9e2866acf20"<br>
}<br>
----<br>
====<br>
<br>
.Clock class fragment with an offset.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "clock-class",<br>
"name": "my clock class",<br>
"frequency": 1000000000,<br>
"offset": {<br>
"seconds": 1605112699,<br>
"cycles": 2878388<br>
}<br>
}<br>
----<br>
====<br>
<br>
.Clock class fragment with a precision.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "clock-class",<br>
"name": "my clock class",<br>
"frequency": 8000000,<br>
"precision": 100<br>
}<br>
----<br>
====<br>
<br>
.Clock class fragment with an origin which is not the Unix epoch.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "clock-class",<br>
"name": "my clock class",<br>
"frequency": 1000000000,<br>
"origin-is-unix-epoch": false<br>
}<br>
----<br>
====<br>
<br>
.Clock class fragment with <<user-attrs,user attributes>>.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"type": "clock-class",<br>
"name": "my clock class",<br>
"frequency": 16000000,<br>
"user-attributes": {<br>
"my.tracer": {<br>
"sys-name": "SOC23",<br>
"bus": {<br>
"name": "LMB5",<br>
"index": 5<br>
},<br>
"propagation-delay-ps": 177<br>
}<br>
}<br>
}<br>
----<br>
====<br>
<br>
[[cc-offset]]<br>
==== Clock class offset<br>
<br>
A _clock class offset_ contains the offset of a <<cc-frag,clock<br>
class>>'s instances relative to their origin.<br>
<br>
A clock class offset is a JSON object.<br>
<br>
.Properties of a clock class offset contained in a clock class fragment {var-f}.<br>
[%header%autowidth]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`seconds`<br>
|JSON integer<br>
|Offset, in seconds, of an instance of{nbsp}{var-f} relative to its<br>
origin.<br>
|No<br>
|`0`<br>
<br>
|`cycles`<br>
|JSON integer<br>
|Offset, in cycles, of an instance of{nbsp}{var-f} relative to its<br>
origin.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
<br>
The value of this property {must} be less than the value<br>
of{nbsp}{var-f}'s `frequency` property.<br>
|No<br>
|`0`<br>
|===<br>
<br>
.Minimal clock class offset.<br>
====<br>
[source,json]<br>
----<br>
{}<br>
----<br>
====<br>
<br>
.Clock class offset with seconds and cycles.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"seconds": 1605112699,<br>
"cycles": 2878388<br>
}<br>
----<br>
====<br>
<br>
.Clock class offset with seconds only.<br>
====<br>
[source,json]<br>
----<br>
{<br>
"seconds": 1605111293<br>
}<br>
----<br>
====<br>
<br>
.Negative clock class offset.<br>
====<br>
This example shows that a clock class offset {may} be negative, that is,<br>
_before_ the origin of the clock class instances.<br>
<br>
[source,json]<br>
----<br>
{<br>
"seconds": -18003,<br>
"cycles": 11928547<br>
}<br>
----<br>
====<br>
<br>
[[dsc-frag]]<br>
=== Data stream class fragment<br>
<br>
A _data stream class_ describes <<ds,_data streams_>>.<br>
<br>
Within a metadata stream, a data stream class fragment {var-f} {must}<br>
occur before any <<erc-frag,event record class fragment>> of which<br>
{var-f} is the parent.<br>
<br>
.Properties of a data stream class fragment {var-f}.<br>
[%header%autowidth,cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"data-stream-class"`.<br>
|Yes<br>
|<br>
<br>
|`id`<br>
|JSON integer<br>
|Numeric ID of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
|No<br>
|`0`<br>
<br>
|`name`<br>
|JSON string<br>
|Name of{nbsp}{var-f}.<br>
<br>
The purpose of this property, combined with the `namespace` property, is<br>
to uniquely identify a data stream class amongst many producers.<br>
|No<br>
|{var-f}{nbsp}is unnamed<br>
<br>
|`namespace`<br>
|JSON string<br>
|<<ns-def,Namespace>> of{nbsp}{var-f}.<br>
<br>
The purpose of this property, combined with the `name` property, is to<br>
uniquely identify a data stream class amongst many producers.<br>
|No<br>
|{var-f}{nbsp}has no namespace<br>
<br>
|`default-clock-class-name`<br>
|JSON string<br>
|Name of the <<cc-frag,class>> of the <<def-clk,default clock>> of an<br>
instance of{nbsp}{var-f}.<br>
<br>
Within the metadata stream containing{nbsp}{var-f}, the <<cc-frag,clock<br>
class fragment>> which has this property's value as its `name` property<br>
must occur before{nbsp}{var-f}.<br>
|No<br>
|An instance of{nbsp}{var-f} has no default clock<br>
<br>
|`packet-context-field-class`<br>
|{c-struct-fc}<br>
|Class of all the <<pkt-ctx,packet context fields>> of an instance<br>
of{nbsp}{var-f}.<br>
|No<br>
|{var-f}{nbsp}has no packet context field class<br>
<br>
|`event-record-header-field-class`<br>
|{c-struct-fc}<br>
|Class of all the <<er-header,event record header fields>> of an<br>
instance of{nbsp}{var-f}.<br>
<br>
Any field class within this property's value {must} satisfy at least<br>
one of:<br>
<br>
* Have at least one valid <<er-header-roles,role>>.<br>
* Be a {struct-fc}.<br>
* Be an {opt-fc}.<br>
* Be a {var-fc}.<br>
* Be the class of a field which is the selector field of an optional<br>
or variant field.<br>
|No<br>
|{var-f}{nbsp}has no event record header field class<br>
<br>
|`event-record-common-context-field-class`<br>
|{c-struct-fc}<br>
|Class of all the <<er-common-ctx,event record common context fields>><br>
of an instance of{nbsp}{var-f}.<br>
|No<br>
|{var-f}{nbsp}has no event record common context field class<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
Within a metadata stream, two given data stream class fragments<br>
{must-not} share the same `id` property value.<br>
<br>
==== Roles<br>
<br>
[[pkt-ctx-roles]]If the `packet-context-field-class` property of a data<br>
stream class fragment exists, then its inner <<fc,field classes>> {may}<br>
have the following <<roles,roles>>:<br>
<br>
.Roles of field classes within a packet context field class.<br>
[%header%autowidth,cols="d,d,a,a"]<br>
|===<br>
|Name |Description |Field class ({var-f}) constraints |Other constraints<br>
<br>
|`packet-total-size`<br>
|Total size (bits) of the <<pkt,packet>>.<br>
<br>
This size includes any padding after the packet's content.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
<br>
|The value of an instance of{nbsp}{var-f} {must} be greater than or<br>
equal to the value of an instance of a field class having the<br>
`packet-content-size` role within the _same_ packet context field.<br>
<br>
|`packet-content-size`<br>
|Content size (bits) of the packet.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|The value of an instance of{nbsp}{var-f} {must} be less than or<br>
equal to the value of an instance of a field class having the<br>
`packet-total-size` role within the _same_ packet context field.<br>
<br>
|`packet-beginning-default-clock-timestamp`<br>
|Timestamp of the packet's <<ds,data stream>>'s <<def-clk,default clock>><br>
when the packet begins.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|The timestamps of all the packet's <<er,event records>> {must} be<br>
greater than or equal to the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of an instance of{nbsp}{var-f} {must} be less than or equal to<br>
the value of an instance of a field class having the<br>
`packet-end-default-clock-timestamp` role within the _same_ packet<br>
context field.<br>
<br>
|`packet-end-default-clock-timestamp`<br>
|Timestamp of the packet's data stream's <<def-clk,default clock>><br>
when the packet ends.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|The timestamps of all the packet's <<er,event records>> {must} be<br>
less than or equal to the value of an instance of{nbsp}{var-f}.<br>
<br>
The value of an instance of{nbsp}{var-f} {must} be greater than or equal<br>
to the value of an instance of a field class having the<br>
`packet-beginning-default-clock-timestamp` role within the _same_ packet<br>
context field.<br>
<br>
|`discarded-event-record-counter-snapshot`<br>
|Snapshot of the packet's data stream's<br>
<<disc-er-counter,discarded event record counter>> when the packet ends.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|<br>
<br>
|[[pkt-seq-num-role]]`packet-sequence-number`<br>
|Sequence number of the packet within its data stream.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|<br>
|===<br>
<br>
[[er-header-roles]]If the `event-record-header-field-class` property of<br>
a data stream class fragment exists, then its inner <<fc,field classes>><br>
{may} have the following <<roles,roles>>:<br>
<br>
.Roles of field classes within an event record header field class.<br>
[%header%autowidth,cols="d,d,a"]<br>
|===<br>
|Name |Description |Field class ({var-f}) constraints<br>
<br>
|`event-record-class-id`<br>
|Event record class ID.<br>
<br>
The purpose of an event record class ID field is to set the current ID<br>
of the class of the event record within its parent <<dsc-frag,data<br>
stream class>>.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
<br>
|`default-clock-timestamp`<br>
|Current timestamp of the event record's <<ds,data stream>>'s<br>
<<def-clk,default clock>> when the event record occurs.<br>
|{c-fl-uint-fc} or {vl-uint-fc}.<br>
|===<br>
<br>
[[erc-frag]]<br>
=== Event record class fragment<br>
<br>
An _event record class_ describes <<er,_event records_>>.<br>
<br>
The <<dsc-frag,data stream class fragment>> of which the `id` property's<br>
value matches the value of the `data-stream-class-id` property of an<br>
event record class fragment{nbsp}{var-f} is considered the _parent_<br>
of{nbsp}{var-f}.<br>
<br>
.Properties of an event record class fragment {var-f} having the data<br>
stream class{nbsp}{var-p} as its parent.<br>
[%header%autowidth,cols="d,d,a,d,d"]<br>
|===<br>
|Name |Type |Description |Required? |Default<br>
<br>
|`type`<br>
|JSON string<br>
|Type of{nbsp}{var-f}.<br>
<br>
The value of this property {must} be `"event-record-class"`.<br>
|Yes<br>
|<br>
<br>
|`id`<br>
|JSON integer<br>
|Numeric ID of{nbsp}{var-f} within{nbsp}{var-p}.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
|No<br>
|`0`<br>
<br>
|`data-stream-class-id`<br>
|JSON integer<br>
|Numeric ID of{nbsp}{var-p}.<br>
<br>
The value of this property {must} be greater than or equal to zero.<br>
<br>
Within the metadata stream,{nbsp}{var-p} {must} occur<br>
before{nbsp}{var-f}.<br>
|No<br>
|`0`<br>
<br>
|`name`<br>
|JSON string<br>
|Name of{nbsp}{var-f}.<br>
<br>
The purpose of this property, combined with the `namespace` property, is<br>
to uniquely identify an event record class amongst many producers.<br>
|No<br>
|{var-f}{nbsp}is unnamed<br>
<br>
|`namespace`<br>
|JSON string<br>
|<<ns-def,Namespace>> of{nbsp}{var-f}.<br>
<br>
The purpose of this property, combined with the `name` property, is to<br>
uniquely identify an event record class amongst many producers.<br>
|No<br>
|{var-f}{nbsp}has no namespace<br>
<br>
|`specific-context-field-class`<br>
|{c-struct-fc}<br>
|Class of the <<er-spec-ctx,event record specific context field>><br>
of an instance of{nbsp}{var-f}.<br>
|No<br>
|{var-f}{nbsp}has no event record specific context field class<br>
<br>
|`payload-field-class`<br>
|{c-struct-fc}<br>
|Class of the <<er-payload,event record payload field>> of an<br>
instance of{nbsp}{var-f}.<br>
|No<br>
|{var-f}{nbsp}has no event record payload field class<br>
<br>
|`user-attributes`<br>
|<<user-attrs,User attributes>><br>
|User attributes of{nbsp}{var-f}.<br>
|No<br>
|`+{}+`<br>
<br>
|`extensions`<br>
|<<ext,Extensions>><br>
|Extensions of{nbsp}{var-f}.<br>
<br>
Any extension which exists under this property must also be declared in<br>
the metadata stream's <<preamble-frag,preamble fragment>>.<br>
|No<br>
|`+{}+`<br>
|===<br>
<br>
Within a metadata stream, two given event record class fragments<br>
{must-not} share the same `id` property value _and_ the same<br>
`data-stream-class-id` property value.<br>
<br>
[[ds-dec]]<br>
== Data stream decoding procedure<br>
<br>
This section shows how to, procedurally, _decode_ a {ctf2} <<ds,data<br>
stream>>.<br>
<br>
Decoding a data stream is the responsibility of a consumer.<br>
<br>
This document doesn't specify how to encode a data stream, as this<br>
procedure implies much more freedom than decoding. You can deduce how to<br>
encode a data stream from the decoding procedure.<br>
<br>
A consumer needs to keep a _data stream decoding state_ while decoding a<br>
data stream. A data stream decoding state comprises the following<br>
_variable_:<br>
<br>
.Variable needed to decode a data stream{nbsp}{var-s}.<br>
[%header%autowidth]<br>
|===<br>
|Name |Type |Description |Initial value<br>
<br>
|{var-o}<br>
|Integer<br>
|Current decoding offset/position (bits) from the beginning<br>
of{nbsp}{var-s}.<br>
|0<br>
|===<br>
<br>
To decode a data stream {var-s}:<br>
<br>
* While there's remaining data in {var-s}:<br>
** <<pkt-dec,Decode one packet>>.<br>
<br>
[[pkt-dec]]<br>
=== Packet decoding procedure<br>
<br>
A consumer needs to keep a _packet decoding state_ while decoding a<br>
<<pkt,packet>>. A packet decoding state comprises the following<br>
_variables_:<br>
<br>
.Variables needed to decode a packet{nbsp}{var-p} within a data<br>
stream{nbsp}{var-s}.<br>
[%header%autowidth]<br>
|===<br>
|Name |Type |Description |Initial value<br>
<br>
|_**DEF_CLK_VAL**_<br>
|Integer<br>
|Current value (clock cycles) of the <<def-clk,default<br>
clock>> of{nbsp}{var-s}, if any.<br>
|0<br>
<br>
|_**DSC_ID**_<br>
|Integer<br>
|Current ID of the <<dsc-frag,class>> of{nbsp}{var-s}.<br>
|0<br>
<br>
|_**DSC**_<br>
|<<dsc-frag,Data stream class>><br>
|Current class of{nbsp}{var-s}.<br>
|None<br>
<br>
|_**DS_ID**_<br>
|Integer<br>
|Current ID of{nbsp}{var-s}.<br>
|None<br>
<br>
|_**PKT_TOTAL_SZ**_<br>
|Integer<br>
|Current total size (bits) of{nbsp}{var-p}.<br>
|∞<br>
<br>
|_**PKT_CONTENT_SZ**_<br>
|Integer<br>
|Current content size (bits) of{nbsp}{var-p}.<br>
|∞<br>
<br>
|_**LAST_BO**_<br>
|String<br>
|Byte order of the last <<fl-ba-field-dec,decoded {fl-ba} field>>.<br>
|None<br>
|===<br>
<br>
To decode a packet {var-p} within a data stream {var-s}:<br>
<br>
. Let {var-po} be the current value of {var-o}.<br>
<br>
. If the metadata stream's <<tc-frag,trace class fragment>>'s<br>
`packet-header-field-class` property exists, then<br>
<<struct-field-dec,decode>> the <<pkt-header,header field>><br>
of{nbsp}{var-p} using this property.<br>
+<br>
During the packet header field decoding procedure, after having decoded a<br>
field{nbsp}{var-f} having the class{nbsp}__**C**__ with a `roles`<br>
property:<br>
+<br>
** If _**C**_ has the role `packet-magic-number`, then validate that the<br>
integer value of{nbsp}{var-f} is 0xc1fc1fc1 (3254525889).<br>
** If _**C**_ has the role `trace-type-uuid`, then validate that the<br>
value of{nbsp}{var-f} matches the `uuid` property of the trace<br>
class fragment.<br>
** If _**C**_ has the role `data-stream-class-id`, then<br>
set{nbsp}__**DSC_ID**__ to the integer value of{nbsp}{var-f}.<br>
** If _**C**_ has the role `data-stream-id`, then<br>
set{nbsp}__**DS_ID**__ to the integer value of{nbsp}{var-f}.<br>
<br>
+<br>
After having decoded the whole packet header field, if __**DS_ID**__<br>
is set, it contains the ID of{nbsp}{var-s} within its<br>
<<dsc-frag,class>>. In other words, two data streams {may} have the same<br>
ID if they are instances of different data stream classes.<br>
<br>
. Set _**DSC**_ to the <<dsc-frag,data stream class>><br>
having{nbsp}__**DSC_ID**__ as the value of its `id` property.<br>
<br>
. If the `packet-context-field-class` property of{nbsp}__**DSC**__<br>
exists, then <<struct-field-dec,decode>> the <<pkt-ctx,context field>><br>
of{nbsp}{var-p} using this property.<br>
+<br>
During the packet context field decoding procedure, after having decoded a<br>
field{nbsp}{var-f} having the class{nbsp}__**C**__ with a `roles`<br>
property:<br>
+<br>
** If _**C**_ has the role `packet-total-size`, then<br>
set{nbsp}__**PKT_TOTAL_SZ**__ to the integer value<br>
of{nbsp}{var-f}.<br>
** If _**C**_ has the role `packet-content-size`, then<br>
set{nbsp}__**PKT_CONTENT_SZ**__ to the integer value<br>
of{nbsp}{var-f}.<br>
** If _**C**_ has the role `packet-beginning-default-clock-timestamp`, then<br>
set{nbsp}__**DEF_CLK_VAL**__ to the integer value<br>
of{nbsp}{var-f}.<br>
** If _**C**_ has the role `packet-end-default-clock-timestamp`, then<br>
the integer value of{nbsp}{var-f} is the value of the<br>
<<def-clk,default clock>> of{nbsp}{var-s} at the end<br>
of{nbsp}{var-p}.<br>
** If _**C**_ has the role `discarded-event-record-counter-snapshot`,<br>
then the integer value of{nbsp}{var-f} is a snapshot of the<br>
<<disc-er-counter,discarded event record counter>><br>
of{nbsp}{var-s} at the end of{nbsp}{var-p}.<br>
** If _**C**_ has the role `packet-sequence-number`, then<br>
the integer value of{nbsp}{var-f} is the sequence number<br>
of{nbsp}{var-p} within{nbsp}{var-s}.<br>
<br>
. If __**PKT_TOTAL_SZ**__ is{nbsp}∞ and<br>
__**PKT_CONTENT_SZ**__ is __not__{nbsp}∞,<br>
then set{nbsp}__**PKT_TOTAL_SZ**__<br>
to{nbsp}__**PKT_CONTENT_SZ**__.<br>
<br>
. If __**PKT_CONTENT_SZ**__ is{nbsp}∞ and<br>
__**PKT_TOTAL_SZ**__ is __not__{nbsp}∞,<br>
then set{nbsp}__**PKT_CONTENT_SZ**__<br>
to{nbsp}__**PKT_TOTAL_SZ**__.<br>
<br>
. While {var-o}{nbsp}<{nbsp}{var-po}{nbsp}pass:[+]{nbsp}__**PKT_CONTENT_SZ**__<br>
and there's remaining data in{nbsp}{var-s}:<br>
** <<er-dec,Decode an event record>>.<br>
<br>
. If __**PKT_TOTAL_SZ**__<br>
and{nbsp}__**PKT_CONTENT_SZ**__ both are __not__{nbsp}∞, then<br>
set {var-o} to {var-po}{nbsp}pass:[+]{nbsp}__**PKT_TOTAL_SZ**__,<br>
effectively skipping end-of-packet padding.<br>
<br>
[[er-dec]]<br>
=== Event record decoding procedure<br>
<br>
A consumer needs to keep an _event record decoding state_ while decoding<br>
an <<er,event record>>. An event record decoding state comprises the<br>
following _variables_:<br>
<br>
.Variables needed to decode an event record{nbsp}__**E**__ within a<br>
data stream{nbsp}{var-s}.<br>
[%header%autowidth]<br>
|===<br>
|Name |Type |Description |Initial value<br>
<br>
|_**ERC_ID**_<br>
|Integer<br>
|Current ID of the <<erc-frag,class>> of{nbsp}__**E**__ of which the<br>
parent is the <<dsc-frag,class>> of{nbsp}{var-s}.<br>
|0<br>
<br>
|_**ERC**_<br>
|<<erc-frag,Event record class>><br>
|Current class of{nbsp}__**E**__.<br>
|None<br>
|===<br>
<br>
To decode an event record _**E**_ within a data stream {var-s}:<br>
<br>
. If the `event-record-header-field-class` property of{nbsp}__**DSC**__<br>
exists, then <<struct-field-dec,decode>> the <<er-header,header<br>
field>> of{nbsp}__**E**__ using this property.<br>
+<br>
During the event record header field decoding procedure, after having<br>
decoded a field{nbsp}{var-f} having the class{nbsp}__**C**__ with a<br>
`roles` property:<br>
+<br>
** If _**C**_ has the role `event-record-class-id`, then<br>
set{nbsp}__**ERC_ID**__ to the integer value of{nbsp}{var-f}.<br>
** If _**C**_ has the role `default-clock-timestamp`, then<br>
update{nbsp}__**DEF_CLK_VAL**__ according to<br>
Common Trace Format{nbsp}1.8.3,{nbsp}§8.<br>
+<br>
NOTE: This proposal refers to {ctf1} to remain brief; the {ctf2}<br>
specification will show the complete clock value updating procedure.<br>
<br>
+<br>
After having decoded the whole event record header field,<br>
__**DEF_CLK_VAL**__ is the value of{nbsp}{var-s}'s<br>
<<def-clk,default clock>> when{nbsp}__**E**__ occurs.<br>
<br>
. Set _**ERC**_ to the <<erc-frag,event record class>><br>
having:<br>
** __**DSC_ID**__ as the value of its `data-stream-class-id`<br>
property.<br>
** __**ERC_ID**__ as the value of its `id` property.<br>
<br>
. If the `event-record-common-context-field-class` property<br>
of{nbsp}__**DSC**__ exists, then <<struct-field-dec,decode>> the<br>
<<er-common-ctx,common context field>> of{nbsp}__**E**__ using this<br>
property.<br>
<br>
. If the `specific-context-field-class` property of{nbsp}__**ERC**__<br>
exists, then <<struct-field-dec,decode>> the<br>
<<er-spec-ctx,specific context field>> of{nbsp}__**E**__<br>
using this property.<br>
<br>
. If the `payload-field-class` property of{nbsp}__**ERC**__ exists, then<br>
<<struct-field-dec,decode>> the <<er-payload,payload field>><br>
of{nbsp}__**E**__ using this property.<br>
<br>
[[field-dec]]<br>
=== Field decoding procedure<br>
<br>
The <<fc,class>> of a field contains what's needed to decode it<br>
as a _value_.<br>
<br>
While a field is an actual sequence of bits within a <<ds,data stream>>,<br>
a value is its conceptual interpretation with attached semantics.<br>
<br>
The types of values are:<br>
<br>
[%header%autowidth,cols="a,a"]<br>
|===<br>
|Value type |Possible values<br>
<br>
|Boolean<br>
|_True_ or _false_.<br>
<br>
|Integer<br>
|Integral quantity.<br>
<br>
|Real<br>
|Continuous quantity.<br>
<br>
|String<br>
|Sequence of <a href="https://home.unicode.org/[Unicode">https://home.unicode.org/[Unicode</a>] characters.<br>
<br>
|Array<br>
|Sequence of values having the same type.<br>
<br>
|Structure<br>
|Sequence of named values (members) which {may} have different types.<br>
|===<br>
<br>
To decode an instance of a field class{nbsp}{var-f}, depending on the<br>
value of its `type` property:<br>
<br>
[%header%autowidth,cols="a,a"]<br>
|===<br>
|Value of{nbsp}{var-f}'s `type` property |{var-f}'s decoding procedure<br>
<br>
|<<fl-ba-fc,`"fixed-length-bit-array"`>><br>
|<<fl-ba-field-dec,Decode a {fl-ba} field>>.<br>
<br>
|<<fl-bool-fc,`"fixed-length-boolean"`>><br>
|<<fl-bool-field-dec,Decode a {fl-bool} field>>.<br>
<br>
|<br>
* <<fl-int-fc,`"fixed-length-unsigned-integer"`>><br>
* <<fl-enum-fc,`"fixed-length-unsigned-enumeration"`>><br>
|<<fl-uint-field-dec,Decode a {fl-uint} field>>.<br>
<br>
|<br>
* <<fl-int-fc,`"fixed-length-signed-integer"`>><br>
* <<fl-enum-fc,`"fixed-length-signed-enumeration"`>><br>
|<<fl-sint-field-dec,Decode a {fl-sint} field>>.<br>
<br>
|<<fl-fp-fc,`"fixed-length-floating-point-number"`>><br>
|<<fl-fp-field-dec,Decode a {fl-fp} field>>.<br>
<br>
|<<vl-ba-fc,`"variable-length-bit-array"`>><br>
|<<vl-ba-field-dec,Decode a {vl-ba} field>>.<br>
<br>
|<br>
* <<vl-int-fc,`"variable-length-unsigned-integer"`>><br>
* <<vl-enum-fc,`"variable-length-unsigned-enumeration"`>><br>
|<<vl-uint-field-dec,Decode a {vl-uint} field>>.<br>
<br>
|<br>
* <<vl-int-fc,`"variable-length-signed-integer"`>><br>
* <<vl-enum-fc,`"variable-length-signed-enumeration"`>><br>
|<<vl-sint-field-dec,Decode a {vl-sint}>>.<br>
<br>
|<<str-fc,`"null-terminated-string"`>><br>
|<<str-field-dec,Decode a {str} field>>.<br>
<br>
|<<sl-str-fc,`"static-length-string"`>><br>
|<<sl-str-field-dec,Decode a {sl-str} field>>.<br>
<br>
|<<sl-blob-fc,`"static-length-blob"`>><br>
|<<sl-blob-field-dec,Decode a {sl-blob} field>>.<br>
<br>
|<<dl-str-fc,`"dynamic-length-string"`>><br>
|<<dl-str-field-dec,Decode a {dl-str} field>>.<br>
<br>
|<<dl-blob-fc,`"dynamic-length-blob"`>><br>
|<<dl-blob-field-dec,Decode a {dl-blob} field>>.<br>
<br>
|<<struct-fc,`"structure"`>><br>
|<<struct-field-dec,Decode a structure field>>.<br>
<br>
|<<sl-array-fc,`"static-length-array"`>><br>
|<<sl-array-field-dec,Decode a {sl-array} field>>.<br>
<br>
|<<dl-array-fc,`"dynamic-length-array"`>><br>
|<<dl-array-field-dec,Decode a {dl-array} field>>.<br>
<br>
|<<opt-fc,`"optional"`>><br>
|<<opt-field-dec,Decode an optional field>>.<br>
<br>
|<<var-fc,`"variant"`>><br>
|<<var-field-dec,Decode a variant field>>.<br>
|===<br>
<br>
[[align-dec]]<br>
==== Alignment procedure<br>
<br>
The decoding procedure of many fields require<br>
{var-o-minus-po} to have a specific _alignment_.<br>
<br>
The alignment requirement of an instance of a <<fc,field<br>
class>>{nbsp}{var-f} is, depending on the value of its `type` property:<br>
<br>
[%header,cols="a,a"]<br>
|===<br>
|{var-f}'s `type` property |{var-f}'s alignment requirement<br>
<br>
|<br>
* <<fl-ba-fc,`"fixed-length-bit-array"`>><br>
* <<fl-bool-fc,`"fixed-length-boolean"`>><br>
* <<fl-int-fc,`"fixed-length-unsigned-integer"`>><br>
* <<fl-int-fc,`"fixed-length-signed-integer"`>><br>
* <<fl-enum-fc,`"fixed-length-unsigned-enumeration"`>><br>
* <<fl-enum-fc,`"fixed-length-signed-enumeration"`>><br>
* <<fl-fp-fc,`"fixed-length-floating-point-number"`>><br>
|The value of {var-f}'s `alignment` property.<br>
<br>
|<br>
* <<vl-ba-fc,`"variable-length-bit-array"`>><br>
* <<vl-int-fc,`"variable-length-unsigned-integer"`>><br>
* <<vl-int-fc,`"variable-length-signed-integer"`>><br>
* <<vl-enum-fc,`"variable-length-unsigned-enumeration"`>><br>
* <<vl-enum-fc,`"variable-length-signed-enumeration"`>><br>
* <<str-fc,`"null-terminated-string"`>><br>
* <<sl-str-fc,`"static-length-string"`>><br>
* <<sl-blob-fc,`"static-length-blob"`>><br>
* <<dl-str-fc,`"dynamic-length-string"`>><br>
* <<dl-blob-fc,`"dynamic-length-blob"`>><br>
|8<br>
<br>
|<<struct-fc,`"structure"`>><br>
|The _maximum_ value of:<br>
<br>
* The value of{nbsp}{var-f}'s `minimum-alignment` property.<br>
<br>
* The alignment requirements of the instances of the `field-class`<br>
property of each <<struct-member-cls,member class>> of{nbsp}{var-f}'s<br>
`members` property.<br>
<br>
|<br>
* <<sl-array-fc,`"static-length-array"`>><br>
* <<dl-array-fc,`"dynamic-length-array"`>><br>
|The alignment requirement of an instance of{nbsp}{var-f}'s<br>
`element-field-class` property<br>
<br>
|<br>
* <<opt-fc,`"optional"`>><br>
* <<var-fc,`"variant"`>><br>
|1<br>
|===<br>
<br>
To align {var-o-minus-po} to some alignment<br>
requirement{nbsp}__**A**__ (bits):<br>
<br>
* Set {var-o} to<br>
{var-po}{nbsp}pass:[+]{nbsp}(({var-o-minus-po}{nbsp}pass:[+]{nbsp}__**A**__{nbsp}{minus}{nbsp}1){nbsp}&{nbsp}{minus}__**A**__),<br>
where __&__ is the bitwise _AND_ operator.<br>
<br>
[[fl-ba-field-dec]]<br>
==== {c-fl-ba} field decoding procedure<br>
<br>
To decode an instance of a {fl-ba-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**BO**_ be the value of {var-f}'s `byte-order` property.<br>
** _**L**_ be the value of {var-f}'s `length` property.<br>
** {var-v} be an array of booleans of length{nbsp}__**L**__.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. If (({var-o-minus-po}){nbsp}mod{nbsp}8{nbsp}{noteq}{nbsp}0)<br>
and __**LAST_BO**__{nbsp}{noteq}{nbsp}__**BO**__, then fail immediately.<br>
<br>
. Read __**L**__{nbsp}bits of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o} following Common Trace Format{nbsp}1.8.3,<br>
§4.1.5, as booleans within{nbsp}{var-v}.<br>
+<br>
NOTE: This proposal refers to {ctf1} to remain brief; the {ctf2}<br>
specification will show the complete decoding procedures for big-endian<br>
and little-endian {fl-ba} fields.<br>
<br>
. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}__**L**__.<br>
<br>
. Set _**LAST_BO**_ to{nbsp}__**BO**__.<br>
<br>
{var-v} is the decoded value.<br>
<br>
[[fl-bool-field-dec]]<br>
==== {c-fl-bool} field decoding procedure<br>
<br>
To decode an instance of a {fl-bool-fc}:<br>
<br>
. Let __**VB**__ be a boolean.<br>
. <<fl-ba-field-dec,Decode the instance as a {fl-ba} field>>.<br>
. If all the elements of{nbsp}{var-v} are _false_, then set{nbsp}__**VB**__<br>
to _false_.<br>
+<br>
Else, set __**VB**__ to _true_.<br>
<br>
_**VB**_ is the decoded boolean value.<br>
<br>
[[fl-uint-field-dec]]<br>
==== {c-fl-uint} field decoding procedure<br>
<br>
To decode an instance of a {fl-uint-fc}:<br>
<br>
. Let __**VI**__ be an integer.<br>
. <<fl-ba-field-dec,Decode the instance as a {fl-ba} field>>.<br>
. Set __**VI**__ as the unsigned integer interpretation<br>
of{nbsp}{var-v}.<br>
<br>
_**VI**_ is the decoded integer value.<br>
<br>
[[fl-sint-field-dec]]<br>
==== {c-fl-sint} field decoding procedure<br>
<br>
To decode an instance of a {fl-sint-fc}:<br>
<br>
. Let __**VI**__ be an integer.<br>
. <<fl-ba-field-dec,Decode the instance as a {fl-ba} field>>.<br>
. Set __**VI**__ as the signed integer interpretation, following the<br>
two's complement format, of{nbsp}{var-v}.<br>
<br>
_**VI**_ is the decoded integer value.<br>
<br>
[[fl-fp-field-dec]]<br>
==== {c-fl-fp} field decoding procedure<br>
<br>
To decode an instance of a {fl-fp-fc}:<br>
<br>
. Let __**VR**__ be a real value.<br>
. <<fl-ba-field-dec,Decode the instance as a {fl-ba} field>>.<br>
. Set __**VR**__ to the real number interpretation, following {ieee754},<br>
of{nbsp}{var-v}.<br>
<br>
_**VR**_ is the decoded real value.<br>
<br>
[[vl-ba-field-dec]]<br>
==== {c-vl-ba} field decoding procedure<br>
<br>
To decode an instance of a {vl-ba-fc}{nbsp}{var-f}:<br>
<br>
. Let {var-v} be an empty array of booleans.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. Read __**N**__{nbsp}bytes of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o}, as many as needed following the unsigned<br>
<a href="https://en.wikipedia.org/wiki/LEB128[LEB128">https://en.wikipedia.org/wiki/LEB128[LEB128</a>] format, appending the<br>
decoded bits to{nbsp}{var-v} as booleans.<br>
+<br>
NOTE: This proposal refers to LEB128 to remain brief; the {ctf2}<br>
specification will show the complete decoding procedure.<br>
<br>
. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}__**N**__{nbsp}{times}{nbsp}8.<br>
<br>
{var-v} is the decoded value.<br>
<br>
[[vl-uint-field-dec]]<br>
==== {c-vl-uint} field decoding procedure<br>
<br>
To decode an instance of a {vl-uint-fc}:<br>
<br>
. Let __**VI**__ be an integer.<br>
. <<vl-ba-field-dec,Decode the instance as a {vl-ba} field>>.<br>
. Set __**VI**__ as the unsigned integer interpretation<br>
of{nbsp}{var-v}.<br>
<br>
_**VI**_ is the decoded integer value.<br>
<br>
[[vl-sint-field-dec]]<br>
==== {c-vl-sint} field decoding procedure<br>
<br>
To decode an instance of a {vl-sint-fc}:<br>
<br>
. Let __**VI**__ be an integer.<br>
. <<vl-ba-field-dec,Decode the instance as a {vl-ba} field>>.<br>
. Set __**VI**__ as the signed integer interpretation, following the<br>
two's complement format, of{nbsp}{var-v}.<br>
<br>
_**VI**_ is the decoded integer value.<br>
<br>
[[str-field-dec]]<br>
==== {c-str} field decoding procedure<br>
<br>
To decode an instance of a {str-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**B**_ be a byte.<br>
** _**A**_ be an empty sequence of bytes.<br>
** {var-v} be a string.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. Read one byte of data from{nbsp}{var-s} at the offset{nbsp}{var-o}<br>
as{nbsp}__**B**__.<br>
<br>
. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}8.<br>
<br>
. While __**B**__{nbsp}{noteq}{nbsp}0:<br>
.. Append __**B**__ to{nbsp}__**A**__.<br>
.. Read one byte of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o} as{nbsp}__**B**__.<br>
.. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}8.<br>
<br>
. Decode _**A**_, following UTF-8, as {var-v}.<br>
<br>
{var-v} is the decoded string value.<br>
<br>
[[sl-str-field-dec]]<br>
==== {c-sl-str} field decoding procedure<br>
<br>
To decode an instance of a {sl-str-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**L**_ be {var-f}'s `length` property.<br>
** _**I**_ be an unsigned integer initialized to 0.<br>
** _**B**_ be a byte.<br>
** _**R**_ be a boolean initialized to _true_.<br>
** _**A**_ be an empty sequence of bytes.<br>
** {var-v} be a string.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. While __**I**__{nbsp}<{nbsp}__**L**__:<br>
<br>
.. Read one byte of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o} as{nbsp}__**B**__.<br>
.. If __**B**__{nbsp}={nbsp}0, then set _**R**_{nbsp}to _false_.<br>
+<br>
Else, if _**R**_ is _true_, then append{nbsp}__**B**__<br>
to{nbsp}__**A**__.<br>
<br>
.. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}8.<br>
.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1.<br>
<br>
. Decode _**A**_, following UTF-8, as {var-v}.<br>
<br>
{var-v} is the decoded string value.<br>
<br>
[[sl-blob-field-dec]]<br>
==== {c-sl-blob} field decoding procedure<br>
<br>
To decode an instance of a {sl-blob-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**L**_ be {var-f}'s `length` property.<br>
** {var-v} be an array of bytes of length{nbsp}__**L**__.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. Read _**L**_ bytes of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o} as{nbsp}{var-v}.<br>
<br>
. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}__**L**__{nbsp}{times}{nbsp}8.<br>
<br>
{var-v} is the decoded BLOB value.<br>
<br>
[[dl-str-field-dec]]<br>
==== {c-dl-str} field decoding procedure<br>
<br>
To decode an instance of a {dl-str-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**L**_ be the value of the previously decoded unsigned integer<br>
field of which{nbsp}{var-f}'s `length-field-location` indicates<br>
the location.<br>
** _**I**_ be an unsigned integer initialized to 0.<br>
** _**B**_ be a byte.<br>
** _**R**_ be a boolean initialized to _true_.<br>
** _**A**_ be an empty sequence of bytes.<br>
** {var-v} be a string.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. While __**I**__{nbsp}<{nbsp}__**L**__:<br>
<br>
.. Read one byte of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o} as{nbsp}__**B**__.<br>
.. If __**B**__{nbsp}={nbsp}0, then set _**R**_{nbsp}to _false_.<br>
+<br>
Else, if _**R**_ is _true_, then append{nbsp}__**B**__<br>
to{nbsp}__**A**__.<br>
<br>
.. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}8.<br>
.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1.<br>
<br>
. Decode _**A**_, following UTF-8, as {var-v}.<br>
<br>
{var-v} is the decoded string value.<br>
<br>
[[dl-blob-field-dec]]<br>
==== {c-dl-blob} field decoding procedure<br>
<br>
To decode an instance of a {dl-blob-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**L**_ be the value of the previously decoded unsigned integer<br>
field of which{nbsp}{var-f}'s `length-field-location` indicates<br>
the location.<br>
** {var-v} be an array of bytes of length{nbsp}__**L**__.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. Read _**L**_ bytes of data from{nbsp}{var-s} at the<br>
offset{nbsp}{var-o} as{nbsp}{var-v}.<br>
<br>
. Set {var-o} to {var-o}{nbsp}pass:[+]{nbsp}__**L**__{nbsp}{times}{nbsp}8.<br>
<br>
{var-v} is the decoded BLOB value.<br>
<br>
[[struct-field-dec]]<br>
==== Structure field decoding procedure<br>
<br>
To decode an instance of a {struct-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**M**_ be {var-f}'s `members` property.<br>
** {var-v} be an empty structure.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. For each member class{nbsp}__**MC**__ of{nbsp}__**M**__:<br>
.. Let:<br>
*** _**MF**_ be __**MC**__'s `field-class` property.<br>
*** _**MN**_ be __**MC**__'s `name` property.<br>
.. <<field-dec,Decode>> one instance of{nbsp}__**MF**__, appending the<br>
resulting value as a member of{nbsp}{var-v} named{nbsp}__**MN**__.<br>
<br>
{var-v} is the decoded value.<br>
<br>
[[sl-array-field-dec]]<br>
==== {c-sl-array} field decoding procedure<br>
<br>
To decode an instance of a {sl-array-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**L**_ be {var-f}'s `length` property.<br>
** _**EF**_ be {var-f}'s `element-field-class` property.<br>
** _**I**_ be an unsigned integer initialized to 0.<br>
** {var-v} be an array of values of length{nbsp}__**L**__.<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. While __**I**__{nbsp}<{nbsp}__**L**__:<br>
.. <<field-dec,Decode>> one instance of{nbsp}__**EF**__<br>
as element{nbsp}__**I**__ of{nbsp}{var-v}.<br>
.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1.<br>
<br>
{var-v} is the decoded value.<br>
<br>
[[dl-array-field-dec]]<br>
==== {c-dl-array} field decoding procedure<br>
<br>
To decode an instance of a {dl-array-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**L**_ be the value of the previously decoded unsigned integer<br>
field of which{nbsp}{var-f}'s `length-field-location` indicates<br>
the location.<br>
** _**EF**_ be {var-f}'s `element-field-class` property.<br>
** _**I**_ be an unsigned integer initialized to 0.<br>
** {var-v} be an array of values of length{nbsp}__**L**__<br>
<br>
. <<align-dec,Align {var-o-minus-po}>> according<br>
to{nbsp}{var-f}.<br>
<br>
. While __**I**__{nbsp}<{nbsp}__**L**__:<br>
.. <<field-dec,Decode>> one instance of{nbsp}__**EF**__<br>
as element{nbsp}__**I**__ of{nbsp}{var-v}.<br>
.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1.<br>
<br>
{var-v} is the decoded value.<br>
<br>
[[opt-field-dec]]<br>
==== Optional field decoding procedure<br>
<br>
To decode an instance of an {opt-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**SEL**_ be the value of the previously decoded <<bool-fc,boolean>><br>
or <<int-fc,integer>> field of which{nbsp}{var-f}'s<br>
`selector-field-location` indicates the location.<br>
** _**OF**_ be {var-f}'s `field-class` property.<br>
** {var-v} be an optional value, initially not set.<br>
<br>
. If the class of{nbsp}__**SEL**__ is a {fl-bool-fc}<br>
and _**SEL**_ is _true_, then:<br>
** <<field-dec,Decode>> one instance of{nbsp}__**OF**__<br>
as{nbsp}{var-v}.<br>
<br>
+<br>
Else, if _**SEL**_ is an element of any <<int-range-set,integer range>><br>
of{nbsp}{var-f}'s `selector-field-ranges` property, then:<br>
** <<field-dec,Decode>> one instance of{nbsp}__**OF**__<br>
as{nbsp}{var-v}.<br>
<br>
If {var-v} is set, then {var-v} is the decoded value. Otherwise, there's<br>
no decoded value.<br>
<br>
[[var-field-dec]]<br>
==== Variant field decoding procedure<br>
<br>
To decode an instance of an {var-fc}{nbsp}{var-f}:<br>
<br>
. Let:<br>
** _**SEL**_ be the value of the previously decoded <<int-fc,integer>><br>
field of which{nbsp}{var-f}'s `selector-field-location` indicates<br>
the location.<br>
** _**OPTS**_ be {var-f}'s `options` property.<br>
** _**OF**_ be the `field-class` property of the <<var-fc-opt,variant<br>
field class option>>{nbsp}__**OPT**__ of{nbsp}__**OPTS**__ of<br>
which{nbsp}__**SEL**__ is an element of any <<int-range-set,integer<br>
range>> of{nbsp}__**OPT**__'s `selector-field-ranges` property.<br>
** {var-v} be a value.<br>
<br>
. <<field-dec,Decode>> one instance of{nbsp}__**OF**__<br>
as{nbsp}{var-v}.<br>
<br>
{var-v} is the decoded value.<br>
_______________________________________________<br>
tracecompass-dev mailing list<br>
tracecompass-dev@eclipse.org<br>
To unsubscribe from this list, visit <a href="https://www.eclipse.org/mailman/listinfo/tracecompass-dev">
https://www.eclipse.org/mailman/listinfo/tracecompass-dev</a><br>
</div>
</span></font></div>
</body>
</html>