From 58b08ce43830316e3f148e96ff0d83c75c93a645 Mon Sep 17 00:00:00 2001 From: Jonathan Rajotte Date: Fri, 17 Dec 2021 17:00:36 -0500 Subject: [PATCH] Deliverable item #1 - sow-2021-0006 Signed-off-by: Jonathan Rajotte --- .../bit-array-decoding-be.svg | 1 + .../bit-array-decoding-le.svg | 1 + .../bit-array-fields-be-le.svg | 1 + .../bit-array-fields-be.svg | 1 + .../bit-array-fields-le.svg | 1 + .../bit-array-fields-padding-be.svg | 1 + .../bit-array-fields-padding-le.svg | 1 + CTF2-SPECRC-3.0-images/ctf-trace-all.svg | 1 + CTF2-SPECRC-3.0-images/dl-array.svg | 1 + CTF2-SPECRC-3.0-images/sl-str.svg | 1 + CTF2-SPECRC-3.0-images/str.svg | 1 + CTF2-SPECRC-3.0-images/vl-ba.svg | 1 + CTF2-SPECRC-3.0.adoc | 6542 ++++++++++ CTF2-SPECRC-3.0.html | 10587 ++++++++++++++++ 14 files changed, 17141 insertions(+) create mode 100644 CTF2-SPECRC-3.0-images/bit-array-decoding-be.svg create mode 100644 CTF2-SPECRC-3.0-images/bit-array-decoding-le.svg create mode 100644 CTF2-SPECRC-3.0-images/bit-array-fields-be-le.svg create mode 100644 CTF2-SPECRC-3.0-images/bit-array-fields-be.svg create mode 100644 CTF2-SPECRC-3.0-images/bit-array-fields-le.svg create mode 100644 CTF2-SPECRC-3.0-images/bit-array-fields-padding-be.svg create mode 100644 CTF2-SPECRC-3.0-images/bit-array-fields-padding-le.svg create mode 100644 CTF2-SPECRC-3.0-images/ctf-trace-all.svg create mode 100644 CTF2-SPECRC-3.0-images/dl-array.svg create mode 100644 CTF2-SPECRC-3.0-images/sl-str.svg create mode 100644 CTF2-SPECRC-3.0-images/str.svg create mode 100644 CTF2-SPECRC-3.0-images/vl-ba.svg create mode 100644 CTF2-SPECRC-3.0.adoc create mode 100644 CTF2-SPECRC-3.0.html diff --git a/CTF2-SPECRC-3.0-images/bit-array-decoding-be.svg b/CTF2-SPECRC-3.0-images/bit-array-decoding-be.svg new file mode 100644 index 0000000..e0a3660 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-decoding-be.svg @@ -0,0 +1 @@ +bit-array-decoding-be \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/bit-array-decoding-le.svg b/CTF2-SPECRC-3.0-images/bit-array-decoding-le.svg new file mode 100644 index 0000000..a340a2a --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-decoding-le.svg @@ -0,0 +1 @@ +bit-array-decoding-le \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/bit-array-fields-be-le.svg b/CTF2-SPECRC-3.0-images/bit-array-fields-be-le.svg new file mode 100644 index 0000000..ced3143 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-fields-be-le.svg @@ -0,0 +1 @@ +bit-array-fields-be-le \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/bit-array-fields-be.svg b/CTF2-SPECRC-3.0-images/bit-array-fields-be.svg new file mode 100644 index 0000000..2e13d5c --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-fields-be.svg @@ -0,0 +1 @@ +bit-array-fields-be \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/bit-array-fields-le.svg b/CTF2-SPECRC-3.0-images/bit-array-fields-le.svg new file mode 100644 index 0000000..92ea549 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-fields-le.svg @@ -0,0 +1 @@ +bit-array-fields-le \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/bit-array-fields-padding-be.svg b/CTF2-SPECRC-3.0-images/bit-array-fields-padding-be.svg new file mode 100644 index 0000000..f4db208 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-fields-padding-be.svg @@ -0,0 +1 @@ +bit-array-fields-padding-be \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/bit-array-fields-padding-le.svg b/CTF2-SPECRC-3.0-images/bit-array-fields-padding-le.svg new file mode 100644 index 0000000..2aa8ae0 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/bit-array-fields-padding-le.svg @@ -0,0 +1 @@ +bit-array-fields-padding-le \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/ctf-trace-all.svg b/CTF2-SPECRC-3.0-images/ctf-trace-all.svg new file mode 100644 index 0000000..528519e --- /dev/null +++ b/CTF2-SPECRC-3.0-images/ctf-trace-all.svg @@ -0,0 +1 @@ +ctf-trace-all \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/dl-array.svg b/CTF2-SPECRC-3.0-images/dl-array.svg new file mode 100644 index 0000000..a08249d --- /dev/null +++ b/CTF2-SPECRC-3.0-images/dl-array.svg @@ -0,0 +1 @@ +dl-array \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/sl-str.svg b/CTF2-SPECRC-3.0-images/sl-str.svg new file mode 100644 index 0000000..1f612fd --- /dev/null +++ b/CTF2-SPECRC-3.0-images/sl-str.svg @@ -0,0 +1 @@ +sl-str \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/str.svg b/CTF2-SPECRC-3.0-images/str.svg new file mode 100644 index 0000000..ae2a041 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/str.svg @@ -0,0 +1 @@ +str \ No newline at end of file diff --git a/CTF2-SPECRC-3.0-images/vl-ba.svg b/CTF2-SPECRC-3.0-images/vl-ba.svg new file mode 100644 index 0000000..46ba146 --- /dev/null +++ b/CTF2-SPECRC-3.0-images/vl-ba.svg @@ -0,0 +1 @@ +vl-ba \ No newline at end of file diff --git a/CTF2-SPECRC-3.0.adoc b/CTF2-SPECRC-3.0.adoc new file mode 100644 index 0000000..36db867 --- /dev/null +++ b/CTF2-SPECRC-3.0.adoc @@ -0,0 +1,6542 @@ +// Please render with Asciidoctor +:doc-id: CTF2-SPECRC-3.0 + += **{doc-id}**: Common Trace Format version{nbsp}2 release candidate +Philippe Proulx +v3.0, 17 December 2021 +:attribute-missing: warn +:icons: font +:nofooter: +:sectnums: +:sectnumlevels: 5 +:toc: left +:toclevels: 3 +:nbh: ‑ +:minus: − +:times: × +:noteq: ≠+:ieee754: https://standards.ieee.org/standard/754-2008.html[IEEE 754-2008] binary interchange format +:ctf1-nl: CTF{nbsp}1 +:ctf1: https://diamon.org/ctf/v1.8.3/[{ctf1-nl}] +:ctf2: CTF{nbsp}2 +:fl-ba: fixed-length bit array +:c-fl-ba: Fixed-length bit array +:vl-ba: variable-length bit array +:c-vl-ba: Variable-length bit array +:fl-bool: fixed-length boolean +:c-fl-bool: Fixed-length boolean +:fl-int: fixed-length integer +:c-fl-int: Fixed-length integer +:fl-uint: fixed-length unsigned integer +:c-fl-uint: Fixed-length unsigned integer +:fl-sint: fixed-length signed integer +:c-fl-sint: Fixed-length signed integer +:vl-int: variable-length integer +:c-vl-int: Variable-length integer +:vl-uint: variable-length unsigned integer +:c-vl-uint: Variable-length unsigned integer +:vl-sint: variable-length signed integer +:c-vl-sint: Variable-length signed integer +:fl-enum: fixed-length enumeration +:c-fl-enum: Fixed-length enumeration +:fl-uenum: fixed-length unsigned enumeration +:c-fl-uenum: Fixed-length unsigned enumeration +:fl-senum: fixed-length signed enumeration +:c-fl-senum: Fixed-length signed enumeration +:vl-enum: variable-length enumeration +:c-vl-enum: Variable-length enumeration +:vl-uenum: variable-length unsigned enumeration +:c-vl-uenum: Variable-length unsigned enumeration +:vl-senum: variable-length signed enumeration +:c-vl-senum: Variable-length signed enumeration +:fl-fp: fixed-length floating point number +:c-fl-fp: Fixed-length floating point number +:str: null-terminated string +:c-str: Null-terminated string +:sl-array: static-length array +:c-sl-array: Static-length array +:sl-str: static-length string +:c-sl-str: Static-length string +:dl-array: dynamic-length array +:c-dl-array: Dynamic-length array +:dl-str: dynamic-length string +:c-dl-str: Dynamic-length string +:sl-blob: static-length BLOB +:c-sl-blob: Static-length BLOB +:dl-blob: dynamic-length BLOB +:c-dl-blob: Dynamic-length BLOB +:fl-ba-fc: <> +:c-fl-ba-fc: <> +:vl-ba-fc: <> +:c-vl-ba-fc: <> +:fl-bool-fc: <> +:c-fl-bool-fc: <> +:fl-int-fc: <> +:c-fl-int-fc: <> +:fl-uint-fc: <> +:c-fl-uint-fc: <> +:fl-sint-fc: <> +:c-fl-sint-fc: <> +:vl-int-fc: <> +:c-vl-int-fc: <> +:vl-uint-fc: <> +:c-vl-uint-fc: <> +:vl-sint-fc: <> +:c-vl-sint-fc: <> +:fl-enum-fc: <> +:c-fl-enum-fc: <> +:fl-uenum-fc: <> +:c-fl-uenum-fc: <> +:fl-senum-fc: <> +:c-fl-senum-fc: <> +:vl-enum-fc: <> +:c-vl-enum-fc: <> +:vl-uenum-fc: <> +:c-vl-uenum-fc: <> +:vl-senum-fc: <> +:c-vl-senum-fc: <> +:fl-fp-fc: <> +:c-fl-fp-fc: <> +:str-fc: <> +:c-str-fc: <> +:sl-array-fc: <> +:c-sl-array-fc: <> +:sl-str-fc: <> +:c-sl-str-fc: <> +:dl-array-fc: <> +:c-dl-array-fc: <> +:dl-str-fc: <> +:c-dl-str-fc: <> +:sl-blob-fc: <> +:c-sl-blob-fc: <> +:dl-blob-fc: <> +:c-dl-blob-fc: <> +:struct-fc: <> +:c-struct-fc: <> +:opt-fc: <> +:c-opt-fc: <> +:var-fc: <> +:c-var-fc: <> +:diamon: https://diamon.org/[DiaMon Workgroup] +:c-bo: https://en.wikipedia.org/wiki/Endianness[Byte order] +:rfc-7464: https://datatracker.ietf.org/doc/html/rfc7464[RFC 7464] +:must: pass:q[__MUST__] +:must-not: pass:q[__MUST NOT__] +:required: pass:q[__REQUIRED__] +:should: pass:q[__SHOULD__] +:should-not: pass:q[__SHOULD NOT__] +:may: pass:q[__MAY__] +:optional: pass:q[__OPTIONAL__] +:var-f: pass:q[__**F**__] +:var-o: pass:q[__**O**__] +:var-v: pass:q[__**V**__] +:var-p: pass:q[__**P**__] +:var-s: pass:q[__**S**__] +:var-dec-po: pass:q[__**PO**__] +:var-dec-o: pass:q[__**O**__] +:var-dec-o-minus-po: pass:q[__**O**__ Ã¢Ë†â€™ __**PO**__] + +This document is a release candidate of the Common Trace Format (CTF) +version{nbsp}2 specification (_**CTF2-SPEC-2.0**_). + +.RFC 2119 +IMPORTANT: The key words {must}, {must-not}, {required}, +{should}, {should-not}, {may}, and {optional} in this document, when +emphasized, are to be interpreted as described in +https://www.ietf.org/rfc/rfc2119.txt[RFC{nbsp}2119]. + +== Revision history + +.Revision history. +[%header%autowidth, cols="d,d,a"] +|=== +|Document |Publication date |Changes + +|_**{doc-id}**_ +|{revdate} +| +Add the optional `minimum-alignment` property to the +<>. + +Such a minimum alignment is needed when the <> of contained array field elements wouldn't be enough. For +example, a <> could write a single +32-bit-aligned, 32-bit little-endian integer value, but use the +following {sl-array-fc} for <>: + +[source,json] +---- +{ + "type": "static-length-array", + "length": 32, + "minimum-alignment": 32, + "element-field-class": { + "type": "fixed-length-boolean", + "length": 1, + "byte-order": "little-endian" + } +} +---- + +While the producer writes a single integer value, consumers decode said +datum as an array of 32{nbsp}individual flags (booleans). + +Update the <> section accordingly. + +|_**CTF2‑SPECRC‑2.0**_ +|9 December 2021 +| +* Describe how to use a <> with a procedure in + a new <> section to make constraints easier to + understand. + +* Rename the `members` property of a {struct-fc} to `member-classes` + as this JSON array contains + <>. + +* Make an <> require that _all_ its + possible selector fields be boolean fields, unsigned integer fields, + or signed integer fields. ++ +Correspondingly, make a <> require that _all_ its +possible selector fields be either unsigned integer fields or signed +integer fields. ++ +This constraint exists to accomodate some consumer implementations, in +particular the ones with limited integer types. + +* Add the "`nil`" <> so that + <> always generates a value. + +* Specify that an "`array`" decoding value contains a sequence of values, + whatever their types. ++ +Indeed, an <> {may} contain <>, making it possible for a resulting array value to contain +values having different types. + +|_**CTF2‑SPECRC‑1.0**_ +|25 November 2021 +|Initial {ctf2} specification release candidate. +|=== + +== What's {ctf2}? + +The _**Common Trace Format**_ version{nbsp}2 is a binary +https://en.wikipedia.org/wiki/Tracing_(software)[trace] format designed +to be very fast to write without compromising great flexibility. + +The intention of {ctf2} is that applications written in any programming +language, and running on any system (be it Linux or bare metal, for +example), can generate traces natively. + +A {ctf2} trace has all its <> described by a +<>. Given the rich set of +supported <>, this makes it possible for a {ctf2} +<> to append data structures as is to data +streams without further "`data massaging`". Indeed, the size, alignment, +and byte order of fixed-length fields are all configurable parameters +within the metadata stream. + +{ctf2} is transport agnostic: this document doesn't specify how to +transport or store {ctf2} streams. Other documents can specify such +conventions, and conform {ctf2} producers and <> +may or may not adhere to them. + +{ctf2} is a major revision of {ctf1}, bringing many improvements, such +as: + +* Using JSON text sequences for the metadata stream. + +* Adding <> (also JSON text sequences). + +* Simplifying the metadata stream. + +* Adding new <>. + +* Using <> instead of reserved structure member names to + identify "`special`" fields. + +and more, while remaining backward compatible at the data stream level. + +== Common definitions + +Common {ctf2} definitions: + +[[byte-def]] <>:: + A group of eight https://en.wikipedia.org/wiki/Bit[bits] operated on + as a unit. ++ +The bits are indexed such that, if the byte represents an 8-bit unsigned +integer, bit{nbsp}0 is the +https://en.wikipedia.org/wiki/Bit_numbering#Least_significant_bit[least +significant] and bit{nbsp}7 is the +https://en.wikipedia.org/wiki/Bit_numbering#Most_significant_bit[most +significant]. + +[[class-def]] <>:: + A set of values (instances) which share common properties. ++ +For example, a {fl-uint-fc} with an 8-bit length property is the set of +the all the {fl-uint} fields from binary `00000000` to `11111111` +(integers 0{nbsp}to{nbsp}255). ++ +This specification often states that some class _describes_ instances. +For example, an <> describes <>. + +[[consumer-def]] <>:: + A software or hardware system which consumes (reads) the streams of + a <>. ++ +A trace consumer is often a _trace viewer_ or a _trace analyzer_. + +[[ns-def]] <>:: + A string of which the purpose is to avoid naming conflicts. ++ +This document doesn't specify the format of a namespace. A producer +{should} use a URI, or at least include a domain name owned by the +organization defining the objects under a namespace. ++ +IMPORTANT: The `std` namespace is reserved for the {ctf2} specification. + +[[producer-def]] <>:: + A software or hardware system which produces (writes) the streams of + a <>. ++ +A trace producer is often a _tracer_. + +[[seq-def]] <>:: + A set of related items which follow each other in a particular + order. + +[[stream-def]] <>:: + A <> of <>. + +[[trace]] +== Trace composition + +A trace is: + +* One <>. +* One or more <>. +* Zero or more <>. + +As a reminder, this specification defines a <> as a +sequence of bytes. + +NOTE: This document doesn't specify how to transport or store {ctf2} +streams. A <> could serialize all streams as a +single file on the file system, or it could send the streams over the +network using TCP, to name a few examples. + +[[metadata-stream-overview]] +=== Metadata stream (overview) + +A metadata stream describes trace <> with JSON objects. + +A metadata stream describes things such as: + +* The <> of the data stream <>. +* The names of <>. +* The <> of event record fields. + +Multiple traces {may} share the same metadata stream: a given trace +{may} contain specific information in its own <>. + +See <> for the full metadata stream specification. + +[[ds]] +=== Data stream + +A _data stream_ is a <> of one or more data +<>: + +image::{doc-id}-images/ctf-trace-all.svg[] + +In the <>, a +<> describes data streams. + +A packet {must} contain one or more bytes of data. + +Although a packet {may} contain padding (garbage data) at the end +itself, from the point of view of a data stream, there's no padding +between packets. In other words, the byte following the last byte of a +packet is the first byte of the next packet. + +A data stream {may} have, conceptually: + +[[def-clk]] One default, monotonic clock:: + Described by a <> in the metadata stream. ++ +<> and <> {may} contain snapshots, named +_timestamps_, of the default clock of their data stream. + +[[disc-er-counter]] One counter of discarded event records:: + Indicates the number of event records which the + <> needed to discard for different reasons. ++ +For example, a tracer could discard an event record when it doesn't fit +some buffer and there's no other available buffer. ++ +A packet {may} contain a snapshot of this counter. + +See <> to learn how to decode a {ctf2} data stream. + +[[pkt]] +==== Packet + +A _packet_ is a segment of a <>. + +A packet contains a <> of data _fields_ or padding +(garbage data). In the metadata stream, <> describe +data fields. + +A packet {var-p}, contained in a data stream{nbsp}{var-s}, contains, +in this order: + +. [[pkt-header]] {optional}: A **header** <> field, + described at the <> level in the + <>, which contains, in this order: +.. {optional}: A packet magic number field (0xc1fc1fc1, or 3254525889). +.. In any order: +*** {optional}: A trace class UUID field. +*** {optional}: One or more fields which contain the numeric ID of the + <> of{nbsp}{var-s}. +*** {optional}: One or more fields which contain the numeric ID + of{nbsp}{var-s}. + +. [[pkt-ctx]] {optional}: A **context** <> field, + described at the <> level in the metadata + stream, which contains, in any order: +** {optional}: A field which contains the total size of{nbsp}{var-p}, + in bits (always a multiple of 8). +** {optional}: A field which contains the content size of{nbsp}{var-p}, + in bits. +** {optional}: A field which contains the beginning timestamp + of{nbsp}{var-p}. +** {optional}: A field which contains the end timestamp of{nbsp}{var-p}. +** {optional}: A field which contains a snapshot of the + <> of{nbsp}{var-s} at + the end of{nbsp}{var-p}. +** {optional}: A field which contains the sequence number + of{nbsp}{var-p} within{nbsp}{var-s}. +** {optional}: User fields. + +. Zero or more <>. + +A packet {must} contain one or more bytes of data. + +A packet {may} contain padding (garbage data) after its _last_ event +record. The size of this padding is the difference between its total +size and its content size (as found in its <>). + +Packets are independent of each other: if one removes a packet from a +data stream, a <> can still decode the whole data +stream. This is why: + +* Packets {may} contain _snapshots_ of the <> of their data stream. + +* Packets and event records {may} contain _timestamps_ which are + snapshots of the <> of their data stream. + +If the <> fields of the packets of a data stream +contain a <> field, a consumer +can recognize missing packets. + +See <> to learn how to decode a {ctf2} packet. + +[[er]] +==== Event record + +An _event record_ is the result of a <> writing a +record with {optional} user data when an event occurs during its +execution. + +A <> contains zero or more event records. + +An <> describes the specific parts of event +records. + +An event record _**E**_, contained in a <>{nbsp}{var-s}, +contains, in this order: + +. [[er-header]] {optional}: A **header** <> field, + described at the <> level in the metadata + stream, which contains, in any order: +** {optional}: One or more fields which contain the numeric ID of the + <> of{nbsp}__**E**__ which has the class + of{nbsp}{var-s} as its parent. +** {optional}: One or more fields which contain a timestamp or a partial + timestamp. + +. [[er-common-ctx]] {optional}: A **common context** + <> field, described at the data stream class + level in the metadata stream, which contains user fields. + +. [[er-spec-ctx]] {optional}: A **specific context** + <> field, described at the event record class + level in the metadata stream, which contains user fields. + +. [[er-payload]] {optional}: A **payload** <> field, + described at the event record class level in the metadata stream, + which contains user fields. + +An event record {must} contain one or more bits of data. + +The <> timestamp of an event record, that is, the +value of the default clock of its <> _after_ its +<>, if any, is encoded/decoded {must} be greater +than or equal to the default clock timestamp of the previous event +record, if any, within the _same_ data stream. + +See <> to learn how to decode a {ctf2} event record. + +[[aux-stream]] +=== Auxiliary stream + +An auxiliary stream is a JSON text sequence, as specified by {rfc-7464}, +which contains extra, structured information about the trace which +doesn't fit the <> model. + +Each element of an auxiliary stream is a JSON object which has a single +property: + +[horizontal] +Name:: + <> of the auxiliary stream. + +Value:: + A JSON value. + +.Auxiliary stream element with the `my.tracer` namespace. +==== +[source,json] +---- +{ + "my.tracer": { + "version": [1, 3, 2], + "session-name": "amqui" + } +} +---- +==== + +.Auxiliary stream element of which the value is just `42`. +==== +[source,json] +---- +{ + "328c7a2d-a959-4f60-bd22-cca74359326f": 42 +} +---- +==== + +[[env]] +==== Trace environment + +To remain backward compatible with {ctf1}, a trace {may} contain an +auxiliary stream having an element with the `std` namespace which +contains trace environment variables under the `environment` property. + +The trace environment variables are a single JSON object where each +property is: + +[horizontal] +Name:: + Trace environment variable name. + +Value:: + Trace environment variable value (any JSON value). + +This document doesn't specify trace environment variable names. + +.`std` auxiliary stream element with trace environment variables. +==== +[source,json] +---- +{ + "std": { + "environment": { + "hostname": "amqui", + "domain": "kernel", + "sysname": "Linux", + "kernel_release": "4.12.12-1-ARCH", + "kernel_version": "#1 SMP PREEMPT Sun Sep 10 09:41:14 CEST 2017", + "tracer_name": "lttng-modules", + "tracer_major": 2, + "tracer_minor": 10, + "tracer_patchlevel": 0 + } + } +} +---- +==== + +[[metadata-stream]] +== Metadata stream + +A metadata stream is a JSON text sequence, as specified by {rfc-7464}, +of _fragments_. + +Together, the fragments of a metadata stream contain all the information +about the <> of one or more <>. + +[[frag]] A _fragment_ is a JSON object; its allowed properties depend on +its `type` property. + +.Common properties of a fragment {var-f}. +[%header%autowidth,cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"preamble"`:: + {var-f} is a <>. + +`"trace-class"`:: + {var-f} is a <>. + +`"clock-class"`:: + {var-f} is a <>. + +`"data-stream-class"`:: + {var-f} is a <>. + +`"event-record-class"`:: + {var-f} is a <>. +|Yes +| + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +For any fragment except a <>, any +extension which exists under this property {must} also be declared in +the preamble fragment of the same metadata stream. +|No +|`+{}+` +|=== + +The metadata stream is a JSON text sequence of fragments instead of a +single JSON object containing nested objects to enable real-time, or +"`live`", tracing: a <> can always decode +<> having known <> +while a <> can always add new event record +classes to a <> by appending additional +fragments to the metadata stream. Once a producer appends a fragment to +a metadata stream, the fragment is considered "`frozen`", in that it +never needs to change. + +A metadata stream: + +* {must} start with a preamble fragment. +* {must} contain exactly one <>. +* {may} contain one <>. +* {must} contain one or more <> + which {must} follow the trace class fragment, if any. +* {may} contain one or more <> + which {must} follow their parent data stream class, if any. + +.Partial metadata stream. +==== +In the sample below, the string `` represents a single record +separator character (U+001E) and the string `[pass:[...]]` represents +continuation. +---- +{ + "type": "preamble", + "version": 2 +} +[...] +---- +==== + +[NOTE] +==== +This section doesn't specify how a metadata stream translates into +<> encoding and decoding rules; it only describes +objects and their properties. + +See <> to learn how to decode a data stream. +==== + +[[uuid]] +=== UUID + +Both a <> and a <> {may} have a +https://en.wikipedia.org/wiki/Universally_unique_identifier[_UUID_] +property. + +Within a metadata stream, a UUID is a JSON array of 16{nbsp}JSON +integers which are the numeric values of the 16{nbsp}bytes of the +UUID. + +.`e53e0ab8-50a1-4f0a-b710-b5f0bba9c4ac` UUID. +==== +[source,json] +---- +[229, 62, 10, 184, 80, 161, 79, 10, 183, 16, 181, 240, 187, 169, 196, 172] +---- +==== + +[[ext]] +=== Extensions + +A <> {may} add _extensions_ to many metadata +stream JSON objects. + +The purpose of an extension is to add core features to {ctf2} or to +modify existing core features, as specified by this document. In other +words, an extension {may} **alter** the format itself. + +This document doesn't specify what an extension exactly is. + +The <> of the metadata stream contains +_extension declarations_: + +* Any extension in metadata stream objects {must} be declared, by + namespace and name, in the preamble fragment. ++ +Declaring an extension is said to _enable_ it. + +* If a <> doesn't support _any_ declared + extension, it {must-not} consume the <> of the + <>. ++ +The consumer {should} report unsupported extensions as an error. + +Extensions are a single JSON object, where each property is: + +[horizontal] +Name:: + A <> + +Value:: + A <> + +[[ns-exts-obj]] A _namespaced extensions object_ is a JSON object, where +each property is: + +[horizontal] +Name:: + An extension name + +Value:: + A JSON value + +The metadata stream JSON objects which {may} contain extensions as their +`extensions` property are: + +* Any <>. ++ +An extension in the <> also makes it +_declared_/_enabled_. + +* Any <>. + +* A <>. + +* A <>. + +.Three extensions under two namespaces. +==== +[source,json] +---- +{ + "my.tracer": { + "piano": { + "keys": 88, + "temperament": "equal" + }, + "ramen": 23 + }, + "abc/xyz": { + "sax": { + "variant": "alto" + } + } +} +---- +==== + +[[user-attrs]] +=== User attributes + +A <> {may} add custom _user attributes_ to many +metadata stream JSON objects. + +This document doesn't specify what a user attribute exactly is. + +Unlike <>, a <> {must-not} +consider user attributes to decode <>. + +User attributes are a single JSON object, where each property is: + +[horizontal] +Name:: + A <> + +Value:: + A JSON value + +The metadata stream JSON objects which {may} contain user attributes +as their `user-attributes` property are: + +* Any <>. +* Any <>. +* A <>. +* A <>. + +.User attributes under two namespaces. +==== +[source,json] +---- +{ + "my.tracer": { + "max-count": 45, + "module": "sys" + }, + "abc/xyz": true +} +---- +==== + +[[fc]] +=== Field classes + +A _field class_ describes fields, that is, <> of bits +as found in a <>. + +A field class contains all the properties a <> +needs to <> a given field. + +A _field_ is a field class instance. + +This document specifies the following types of field classes: + +Abstract field classes:: + One cannot use the following field classes directly: they are bases + for other, concrete field classes: ++ +* <> +* <> +* <> +* <> + +Fixed/static-length field classes:: ++ +* {c-fl-ba-fc} +* {c-fl-bool-fc} +* {c-fl-int-fc} +* {c-fl-enum-fc} +* {c-fl-fp-fc} +* {c-sl-str-fc} +* {c-sl-blob-fc} + +Variable/dynamic-length field classes:: ++ +* {c-vl-ba-fc} +* {c-vl-int-fc} +* {c-vl-enum-fc} +* {c-str-fc} +* {c-dl-str-fc} +* {c-dl-blob-fc} + +Compound field classes:: + The following field classes contain one or more field classes. ++ +* {c-struct-fc} +* {c-sl-array-fc} +* {c-dl-array-fc} +* {c-opt-fc} +* {c-var-fc} + +A field class is a JSON object; its properties depend on its `type` +property. + +.Common properties of a field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"fixed-length-bit-array"`:: + {var-f} is a {fl-ba-fc}. + +`"fixed-length-boolean"`:: + {var-f} is a {fl-bool-fc}. + +`"fixed-length-unsigned-integer"`:: +`"fixed-length-signed-integer"`:: + {var-f} is a {fl-int-fc}. + +`"fixed-length-unsigned-enumeration"`:: +`"fixed-length-signed-enumeration"`:: + {var-f} is a {fl-enum-fc}. + +`"fixed-length-floating-point-number"`:: + {var-f} is a {fl-fp-fc}. + +`"variable-length-bit-array"`:: + {var-f} is a {vl-ba-fc}. + +`"variable-length-unsigned-integer"`:: +`"variable-length-signed-integer"`:: + {var-f} is a {vl-int-fc}. + +`"variable-length-unsigned-enumeration"`:: +`"variable-length-signed-enumeration"`:: + {var-f} is a {vl-enum-fc}. + +`"null-terminated-string"`:: + {var-f} is a {str-fc}. + +`"static-length-string"`:: + {var-f} is a {sl-str-fc}. + +`"static-length-blob"`:: + {var-f} is a {sl-blob-fc}. + +`"dynamic-length-string"`:: + {var-f} is a {dl-str-fc}. + +`"dynamic-length-blob"`:: + {var-f} is a {dl-blob-fc}. + +`"structure"`:: + {var-f} is a {struct-fc}. + +`"static-length-array"`:: + {var-f} is a {sl-array-fc}. + +`"dynamic-length-array"`:: + {var-f} is a {dl-array-fc}. + +`"optional"`:: + {var-f} is a {opt-fc}. + +`"variant"`:: + {var-f} is a {var-fc}. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +The following <> properties {must} have a {struct-fc} as +their value: + +<>:: + `packet-header-field-class` + +<>:: ++ +* `packet-context-field-class` +* `event-record-header-field-class` +* `event-record-common-context-field-class` + +<>:: ++ +* `specific-context-field-class` +* `payload-field-class` + +[[field-loc]] +==== Field location + +A _field location_ is a means for a <> to locate +a field which it needs to <> another, subsequent field. + +A consumer needs to locate another field to decode instances of the +following <>: + +{c-dl-array-fc}:: +{c-dl-str-fc}:: +{c-dl-blob-fc}:: + Needs a <> or + <> length field. + +{c-opt-fc}:: + Needs a <>, <>, or + <> selector field. + +{c-var-fc}:: + Needs a <> or <> selector + field. + +Let _**T**_ be an anteriorly decoded field which a consumer needs to +decode another field{nbsp}{var-s}. A field location is a JSON array +where, in this order: + +. The first element is the name (JSON string) of a root field from + where to start the lookup of{nbsp}__**T**__, amongst: ++ +-- +[horizontal] +`"packet-header"`:: + <> of the <> of{nbsp}{var-s}. +`"packet-context"`:: + <> of the packet of{nbsp}{var-s}. +`"event-record-header"`:: + <> of the <> of{nbsp}{var-s}. +`"event-record-common-context"`:: + <> of the event record of{nbsp}{var-s}. +`"event-record-specific-context"`:: + <> of the event record of{nbsp}{var-s}. +`"event-record-payload"`:: + <> of the event record of{nbsp}{var-s}. +-- ++ +In other words, __**T**__ {must} be in the same packet or event record +as{nbsp}{var-s}. + +. The following elements are <> field member names + (JSON strings) to follow to locate the target field. + +The length of a field location {must} be greater than or equal to two. + +See <> to learn how to locate a field with a field +location. + +[[int-range-set]] +==== Integer range set + +An _integer range set_ is a JSON array of integer ranges. + +An integer range set {must} contain one or more integer ranges. + +An _integer range_ is a JSON array of two elements: + +. The lower bound of the range (JSON integer, included). +. The upper bound of the range (JSON integer, included). + +An integer range represents all the integer values from the lower bound +of the range to its upper bound. + +The upper bound of an integer range {must} be greater than or equal to +its lower bound. + +If both the lower and upper bounds of an integer range are equal, then +the integer range represents a single integer value. + +.Integer ranges. +==== +[source,json] +---- +[3, 67] +---- + +[source,json] +---- +[-45, 101] +---- + +.Single integer value. +[source,json] +---- +[42, 42] +---- +==== + +.Integer range set containing three integer ranges. +==== +[source,json] +---- +[[3, 67], [-45, 1], [42, 42]] +---- +==== + +[[roles]] +==== Roles + +Some <> instances can have _roles_. + +A role is specific semantics attached to the fields (instances) of a +field class. For example, the `packet-magic-number` role of a +{fl-int-fc} indicates that the value of its instances {must} be the +<> magic number (0xc1fc1fc1). + +Roles are a JSON array of role names (JSON strings). + +See <> and <> which indicate accepted roles within +their root field classes. + +[[fl-ba-fc]] +==== {c-fl-ba} field class + +A _{fl-ba}_ field class describes _{fl-ba}_ fields. + +A {fl-ba} field is a simple array of contiguous bits, without any +attached integer type semantics. + +The length, or number of bits, of a {fl-ba} field is a property +(`length`) of its class. + +A {fl-ba} field class acts as a base of a {fl-bool-fc}, a {fl-int-fc}, +and a {fl-fp-fc}. + +.Common properties of a {fl-ba} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"fixed-length-bit-array"`. +|Yes +| + +|`length` +|JSON integer +|Number of bits of an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than zero. +|Yes +| + +|`byte-order` +|JSON string +|{c-bo} of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"big-endian"`:: + Big-endian. + +`"little-endian"`:: + Little-endian. +|Yes +| + +|`alignment` +|JSON integer +|Alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which +contains this instance. + +The value of this property {must} be a positive power of two. +|No +|`1` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {fl-ba} field class. +==== +[source,json] +---- +{ + "type": "fixed-length-bit-array", + "length": 16, + "byte-order": "little-endian" +} +---- +==== + +.{c-fl-ba} field class with instances aligned to 32{nbsp}bits. +==== +[source,json] +---- +{ + "type": "fixed-length-bit-array", + "length": 48, + "byte-order": "big-endian", + "alignment": 32 +} +---- +==== + +.{c-fl-ba} field class with <>. +==== +[source,json] +---- +{ + "type": "fixed-length-bit-array", + "length": 16, + "byte-order": "little-endian", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[fl-bool-fc]] +==== {c-fl-bool} field class + +A _{fl-bool}_ field class is a {fl-ba-fc} which describes _{fl-bool}_ +fields. + +A {fl-bool} field is a {fl-ba} field which has the following semantics: + +If all the bits of the bit array field are cleared (zero):: + The value of the {fl-bool} field is _false_. + +Otherwise:: + The value of the {fl-bool} field is _true_. + +.Properties of a {fl-bool} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"fixed-length-boolean"`. +|Yes +| + +|`length` +|JSON integer +|Number of bits of an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than zero. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`byte-order` +|JSON string +|{c-bo} of an instance +of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"big-endian"`:: + Big-endian. + +`"little-endian"`:: + Little-endian. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`alignment` +|JSON integer +|Alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which +contains this instance. + +The value of this property {must} be a positive power of two. + +Property inherited from the {fl-ba-fc}. +|No +|`1` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {fl-bool} field class. +==== +[source,json] +---- +{ + "type": "fixed-length-boolean", + "length": 16, + "byte-order": "little-endian" +} +---- +==== + +.{c-fl-bool} field class with instances aligned to 32{nbsp}bits. +==== +[source,json] +---- +{ + "type": "fixed-length-boolean", + "length": 48, + "byte-order": "big-endian", + "alignment": 32 +} +---- +==== + +.{c-fl-bool} field class with <>. +==== +[source,json] +---- +{ + "type": "fixed-length-boolean", + "length": 16, + "byte-order": "little-endian", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[int-fc]] +==== Abstract integer field class + +An _abstract integer_ field class is a base of a {fl-int-fc} and a +{vl-int-fc}. + +This field class is abstract in that it only exists to show the relation +between different integer field classes in this document: a +<> cannot contain an abstract integer field. + +.Common property of an integer field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`preferred-display-base` +|JSON integer +|Preferred base to display the value of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +[horizontal] +`2`:: + Binary base. + +`8`:: + Octal base. + +`10`:: + Decimal base. + +`16`:: + Hexadecimal base. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. +|No +|`10` +|=== + +[[fl-int-fc]] +==== {c-fl-int} field class + +A _{fl-int}_ field class is both an <> and a {fl-ba-fc} which describes _{fl-int}_ fields. + +A {fl-int} field is a {fl-ba} field which has integer semantics. + +If the value of the `type` property of a {fl-int} is +`"fixed-length-signed-integer"`, then its instances have the two's +complement format. + +A {fl-int} field class acts as a base of a {fl-enum-fc}. + +.Common properties of a {fl-int} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"fixed-length-unsigned-integer"`:: + The instances of{nbsp}{var-f} are {fl-uint} fields. + +`"fixed-length-signed-integer"`:: + The instances of{nbsp}{var-f} are {fl-sint} fields. +|Yes +| + +|`length` +|JSON integer +|Number of bits of an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than zero. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`byte-order` +|JSON string +|{c-bo} of an instance +of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"big-endian"`:: + Big-endian. + +`"little-endian"`:: + Little-endian. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`alignment` +|JSON integer +|Alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which +contains this instance. + +The value of this property {must} be a positive power of two. + +Property inherited from the {fl-ba-fc}. +|No +|`1` + +|`preferred-display-base` +|JSON integer +|Preferred base to display the value of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +[horizontal] +`2`:: + Binary base. + +`8`:: + Octal base. + +`10`:: + Decimal base. + +`16`:: + Hexadecimal base. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`10` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {fl-uint} field class. +==== +[source,json] +---- +{ + "type": "fixed-length-unsigned-integer", + "length": 16, + "byte-order": "little-endian" +} +---- +==== + +.{c-fl-sint} field class with instances aligned to 32{nbsp}bits. +==== +[source,json] +---- +{ + "type": "fixed-length-signed-integer", + "length": 48, + "byte-order": "big-endian", + "alignment": 32 +} +---- +==== + +.{c-fl-uint} field class with instances to be preferably displayed with a hexadecimal base. +==== +[source,json] +---- +{ + "type": "fixed-length-unsigned-integer", + "length": 48, + "byte-order": "big-endian", + "preferred-display-base": 16 +} +---- +==== + +.{c-fl-sint} field class with <>. +==== +[source,json] +---- +{ + "type": "fixed-length-signed-integer", + "length": 16, + "byte-order": "little-endian", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[enum-fc]] +==== Abstract enumeration field class + +An _abstract enumeration_ field class is a base of a {fl-enum-fc} and a +{vl-enum-fc}. + +This field class is abstract in that it only exists to show the relation +between different enumeration field classes in this document: a +<> cannot contain an abstract enumeration field. + +An abstract enumeration field class is an <>. + +An enumeration field is an integer field which {may} have one or more +associated names thanks to the `mappings` property of its class. + +.Common property of an enumeration field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`preferred-display-base` +|JSON integer +|Preferred base to display the value of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +[horizontal] +`2`:: + Binary base. + +`8`:: + Octal base. + +`10`:: + Decimal base. + +`16`:: + Hexadecimal base. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`10` + +|`mappings` +|<> +|Mappings of{nbsp}{var-f}. + +The value of this property {must} contain one or more properties. +|Yes +| +|=== + +[[enum-fc-mappings]] +===== Enumeration field class mappings + +_Enumeration field class mappings_ map names to +<>. + +Enumeration field class mappings are a JSON object, where each property +is: + +[horizontal] +Name:: + Mapping name. + +Value:: + Mapped ranges of integers (<>). + +The integer ranges of two given mappings {may} overlap. + +Enumeration field class mappings {must} contain one or more properties. + +.Enumeration field class mappings with three mappings. +==== +In this example, the `fortune` and `building` mappings overlap with the +values 4 and 5, and the `building` and `journal` mappings overlap with +the value 80. + +[source,json] +---- +{ + "fortune": [[3, 67], [-45, 1], [84, 84]], + "building": [[4, 5], [75, 82]], + "journal": [[100, 2305], [80, 80]] +} +---- +==== + +[[fl-enum-fc]] +==== {c-fl-enum} field class + +A _{fl-enum}_ field class is both an <> and a {fl-int-fc} which describes _{fl-enum}_ fields. + +A {fl-enum} field is a {fl-int} field which {may} have one or more +associated names thanks to the `mappings` property of its class. + +If the value of the `type` property of a {fl-enum} field class is +`"fixed-length-signed-enumeration"`, then its instances have the two's +complement format. + +.Properties of a {fl-enum} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"fixed-length-unsigned-enumeration"`:: + The instances of{nbsp}{var-f} are {fl-uenum} fields. + +`"fixed-length-signed-enumeration"`:: + The instances of{nbsp}{var-f} are {fl-senum} fields. +|Yes +| + +|`length` +|JSON integer +|Number of bits of an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than zero. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`byte-order` +|JSON string +|{c-bo} of an instance +of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"big-endian"`:: + Big-endian. + +`"little-endian"`:: + Little-endian. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`alignment` +|JSON integer +|Alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which +contains this instance. + +The value of this property {must} be a positive power of two. + +Property inherited from the {fl-ba-fc}. +|No +|`1` + +|`preferred-display-base` +|JSON integer +|Preferred base to display the value of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +[horizontal] +`2`:: + Binary base. + +`8`:: + Octal base. + +`10`:: + Decimal base. + +`16`:: + Hexadecimal base. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`10` + +|`mappings` +|<> +|Mappings of{nbsp}{var-f}. + +The value of this property {must} contain one or more properties. + +Property inherited from the <>. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {fl-uenum} field class. +==== +[source,json] +---- +{ + "type": "fixed-length-unsigned-enumeration", + "length": 16, + "byte-order": "little-endian", + "mappings": { + "apple": [[1, 19]] + } +} +---- +==== + +.{c-fl-senum} field class with instances aligned to 32{nbsp}bits. +==== +[source,json] +---- +{ + "type": "fixed-length-signed-enumeration", + "length": 48, + "byte-order": "big-endian", + "alignment": 32, + "mappings": { + "banana": [[-27399, -1882], [8, 199], [101, 101]], + "orange": [[67, 67], [43, 1534]] + } +} +---- +==== + +.{c-fl-uenum} field class with instances to be preferably displayed with a hexadecimal base. +==== +[source,json] +---- +{ + "type": "fixed-length-unsigned-enumeration", + "length": 8, + "byte-order": "big-endian", + "preferred-display-base": 16, + "mappings": { + "lime": [[3, 3]], + "kiwi": [[8, 8]], + "blueberry": [[11, 11]] + } +} +---- +==== + +.{c-fl-senum} field class with <>. +==== +[source,json] +---- +{ + "type": "fixed-length-signed-enumeration", + "length": 16, + "byte-order": "little-endian", + "mappings": { + "mango": [[23, 42]] + }, + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[fl-fp-fc]] +==== {c-fl-fp} field class + +A _{fl-fp}_ field class is a {fl-ba-fc} which describes _{fl-fp}_ +fields. + +A {fl-fp} field is a {fl-ba} field which has floating point number +semantics. + +.Properties of a {fl-fp} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be +`"fixed-length-floating-point-number"`. +|Yes +| + +|`length` +|JSON integer +|Number of bits of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`16`:: + The instances of{nbsp}{var-f} are binary16 floating point numbers, + as per the {ieee754}. + +`32`:: + The instances of{nbsp}{var-f} are binary32 floating point numbers. + +`64`:: + The instances of{nbsp}{var-f} are binary64 floating point numbers. + +`128`:: + The instances of{nbsp}{var-f} are binary128 floating point + numbers. + +_**K**_, where _**K**_ is greater than{nbsp}128 and a multiple of{nbsp}32:: + The instances of{nbsp}{var-f} are binary__**K**__ floating point + numbers. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`byte-order` +|JSON string +|{c-bo} of an instance +of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"big-endian"`:: + Big-endian. + +`"little-endian"`:: + Little-endian. + +Property inherited from the {fl-ba-fc}. +|Yes +| + +|`alignment` +|JSON integer +|Alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which +contains this instance. + +The value of this property {must} be a positive power of two. + +Property inherited from the {fl-ba-fc}. +|No +|`1` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal binary32 {fl-fp} field class. +==== +[source,json] +---- +{ + "type": "fixed-length-floating-point-number", + "length": 32, + "byte-order": "little-endian" +} +---- +==== + +.binary64 {fl-fp} field class with instances aligned to 32{nbsp}bits. +==== +[source,json] +---- +{ + "type": "fixed-length-floating-point-number", + "length": 64, + "byte-order": "big-endian", + "alignment": 32 +} +---- +==== + +.binary192 {fl-fp} field class with <>. +==== +[source,json] +---- +{ + "type": "fixed-length-floating-point-number", + "length": 192, + "byte-order": "little-endian", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[vl-ba-fc]] +==== {c-vl-ba} field class + +A _{vl-ba}_ field class describes _{vl-ba}_ fields. + +A {vl-ba} field is a <> of bytes with a variable +length which contains an array of bits of which the length is a multiple +of{nbsp}7. A {vl-ba} field is encoded as per +https://en.wikipedia.org/wiki/LEB128[LEB128]. + +A {vl-ba} field class acts as a base of a {vl-int-fc}. + +.Common properties of a {vl-ba} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"variable-length-bit-array"`. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {vl-ba} field class. +==== +[source,json] +---- +{ + "type": "variable-length-bit-array" +} +---- +==== + +.{c-vl-ba} field class with <>. +==== +[source,json] +---- +{ + "type": "variable-length-bit-array", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[vl-int-fc]] +==== {c-vl-int} field class + +A _{vl-int}_ field class is both an <> and a {vl-ba-fc} which describes _{vl-int}_ fields. + +A {vl-int} field is a {vl-ba} field which has integer semantics. + +If the value of the `type` property of a {vl-int} field class is +`"variable-length-signed-integer"`, then its instances have the two's +complement format. + +A {vl-int} field class acts as a base of a {vl-enum-fc}. + +.Common properties of a {vl-int} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"variable-length-unsigned-integer"`:: + The instances of{nbsp}{var-f} are {vl-uint} fields. + +`"variable-length-signed-integer"`:: + The instances of{nbsp}{var-f} are {vl-sint} fields. +|Yes +| + +|`preferred-display-base` +|JSON integer +|Preferred base to display the value of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +[horizontal] +`2`:: + Binary base. + +`8`:: + Octal base. + +`10`:: + Decimal base. + +`16`:: + Hexadecimal base. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`10` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {vl-uint} field class. +==== +[source,json] +---- +{ + "type": "variable-length-unsigned-integer" +} +---- +==== + +.{c-vl-sint} field class with instances to be preferably displayed with a hexadecimal base. +==== +[source,json] +---- +{ + "type": "variable-length-signed-integer", + "preferred-display-base": 16 +} +---- +==== + +.{c-vl-uint} field class with <>. +==== +[source,json] +---- +{ + "type": "variable-length-unsigned-integer", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[vl-enum-fc]] +==== {c-vl-enum} field class + +A _{vl-enum}_ field class is both an <> and a {vl-int-fc} which describes _{vl-enum}_ fields. + +A {vl-enum} field is a {vl-int} field which {may} have one or more +associated names thanks to the `mappings` property of its class. + +If the value of the `type` property of a {vl-enum} field class is +`"variable-length-signed-enumeration"`, then its instances have the +two's complement format. + +.Properties of a {vl-enum} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be one of: + +`"variable-length-unsigned-enumeration"`:: + The instances of{nbsp}{var-f} are {vl-uenum} fields. + +`"variable-length-signed-enumeration"`:: + The instances of{nbsp}{var-f} are {vl-senum} fields. +|Yes +| + +|`preferred-display-base` +|JSON integer +|Preferred base to display the value of an instance of{nbsp}{var-f}. + +The value of this property {must} be one of: + +[horizontal] +`2`:: + Binary base. + +`8`:: + Octal base. + +`10`:: + Decimal base. + +`16`:: + Hexadecimal base. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`10` + +|`mappings` +|<> +|Mappings of{nbsp}{var-f}. + +The value of this property {must} contain one or more properties. + +Property inherited from the <>. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {vl-uenum} field class. +==== +[source,json] +---- +{ + "type": "variable-length-unsigned-enumeration", + "mappings": { + "apple": [[1, 19]] + } +} +---- +==== + +.{c-vl-uenum} field class with instances to be preferably displayed with a hexadecimal base. +==== +[source,json] +---- +{ + "type": "variable-length-unsigned-enumeration", + "preferred-display-base": 16, + "mappings": { + "lime": [[3, 3]], + "kiwi": [[8, 8]], + "blueberry": [[11, 11]] + } +} +---- +==== + +.{c-vl-senum} field class with <>. +==== +[source,json] +---- +{ + "type": "variable-length-signed-enumeration", + "mappings": { + "banana": [[-27399, -1882], [8, 199], [101, 101]], + "orange": [[67, 67], [43, 1534]] + }, + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[str-fc]] +==== {c-str} field class + +A _{str}_ field class describes _{str}_ fields. + +A {str} field is, in this order: + +. Zero or more contiguous non-null (non-zero) bytes which form a + UTF-8-encoded string. + +. One null (zero) byte. + +.Properties of a {str} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"null-terminated-string"`. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Minimal {str} field class. +==== +[source,json] +---- +{ + "type": "null-terminated-string" +} +---- +==== + +.{c-str} field class with <>. +==== +[source,json] +---- +{ + "type": "null-terminated-string", + "user-attributes": { + "my.tracer": { + "is-nice": true + } + } +} +---- +==== + +[[sl-str-fc]] +==== {c-sl-str} field class + +A _{sl-str}_ field class describes _{sl-str}_ fields. + +A {sl-str} field is a <> of zero or more contiguous +bytes. All the bytes of a {sl-str} before the first null (zero) byte, if +any, form a UTF-8-encoded string. All the bytes after the first null +(zero) byte, if any, are padding (garbage data). + +The length, or number of bytes, of a {sl-str} field is a property +(`length`) of its class. + +.Properties of a {sl-str} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"static-length-string"`. +|Yes +| + +|`length` +|JSON integer +|Number of bytes contained in an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than or equal to zero. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Empty {sl-str} field class. +==== +[source,json] +---- +{ + "type": "static-length-string", + "length": 0 +} +---- +==== + +.{c-sl-str} field class with instances having 100{nbsp}bytes. +==== +[source,json] +---- +{ + "type": "static-length-string", + "length": 100 +} +---- +==== + +.{c-sl-str} field class with <>. +==== +[source,json] +---- +{ + "type": "static-length-string", + "length": 13, + "user-attributes": { + "my.tracer": null + } +} +---- +==== + +[[dl-str-fc]] +==== {c-dl-str} field class + +A _{dl-str}_ field class describes _{dl-str}_ fields. + +A {dl-str} field is a <> of zero or more contiguous +bytes. All the bytes of a {dl-str} before the first null (zero) byte, if +any, form a UTF-8-encoded string. All the bytes after the first null +(zero) byte, if any, are padding (garbage data). + +The length, or number of bytes, of a {dl-str} field is the value of +another, anterior (already encoded/decoded) _length_ field. A +<> can locate this length field thanks to the +`length-field-location` property of the {dl-str} field class. + +.Properties of a {dl-str} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"static-length-string"`. +|Yes +| + +|`length-field-location` +|<> +|Location of the field of which the value is the number of bytes +contained in an instance of{nbsp}{var-f}. + +The class of the length field {must} be one of: + +* {c-fl-uint-fc} +* {c-vl-uint-fc} +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.{c-dl-str} field class. +==== +[source,json] +---- +{ + "type": "dynamic-length-string", + "length-field-location": ["event-record-payload", "length"] +} +---- +==== + +.{c-dl-str} field class with <>. +==== +[source,json] +---- +{ + "type": "dynamic-length-string", + "length-field-location": ["event-record-common-context", "name-length"], + "user-attributes": { + "my.tracer": 177 + } +} +---- +==== + +[[blob-fc]] +==== Abstract BLOB field class + +An _abstract https://en.wikipedia.org/wiki/Binary_large_object[BLOB]_ +field class is a base of a {sl-blob-fc} and a {dl-blob-fc}. + +This field class is abstract in that it only exists to show the relation +between different BLOB field classes in this document: a <> +cannot contain an abstract BLOB field. + +.Common properties of a BLOB field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`media-type` +|JSON string +| +https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[IANA +media type] of an instance of{nbsp}{var-f}. +|No +|`"application/octet-stream"` +|=== + +[[sl-blob-fc]] +==== {c-sl-blob} field class + +A _{sl-blob}_ field class is an <> +which describes _{sl-blob}_ fields. + +A {sl-blob} field is a <> of zero or more contiguous +bytes with an associated IANA media type (given by the `media-type` +property of its class). + +The length, or number of bytes, of a {sl-blob} field is a property +(`length`) of its class. + +.Properties of a {sl-blob} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"static-length-blob"`. +|Yes +| + +|`length` +|JSON integer +|Number of bytes contained in an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than or equal to zero. +|Yes +| + +|`media-type` +|JSON string +| +https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[IANA +media type] of an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`"application/octet-stream"` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Empty {sl-blob} field class with instances having a default IANA media type. +==== +[source,json] +---- +{ + "type": "static-length-blob", + "length": 0 +} +---- +==== + +.Static-length TIFF BLOB field class with instances having 511,267{nbsp}bytes. +==== +[source,json] +---- +{ + "type": "static-length-blob", + "length": 511267, + "media-type": "image/tif" +} +---- +==== + +.Static-length CSV BLOB field class with <>. +==== +[source,json] +---- +{ + "type": "static-length-blob", + "length": 2400, + "media-type": "text/csv", + "user-attributes": { + "my.tracer": { + "csv-cols": 12 + } + } +} +---- +==== + +[[dl-blob-fc]] +==== {c-dl-blob} field class + +A _{dl-blob}_ field class is an <> +which describes _{dl-blob}_ fields. + +A {dl-blob} field is a <> of zero or more contiguous +bytes with an associated IANA media type. + +The length, or number of bytes, of a {dl-blob} field is the value of +another, anterior (already encoded/decoded) _length_ field. A +<> can locate this length field thanks to the +`length-field-location` property of the {dl-blob} field class. + +.Properties of a {dl-blob} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"dynamic-length-blob"`. +|Yes +| + +|`length-field-location` +|<> +|Location of the field of which the value is the number of bytes +contained in an instance of{nbsp}{var-f}. + +The class of the length field {must} be one of: + +* {c-fl-uint-fc} +* {c-vl-uint-fc} +|Yes +| + +|`media-type` +|JSON string +|https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types[IANA +media type] of an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|No +|`"application/octet-stream"` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.{c-dl-blob} field class with instances having a default IANA media type. +==== +[source,json] +---- +{ + "type": "dynamic-length-blob", + "length-field-location": ["event-record-payload", "length"] +} +---- +==== + +.Dynamic-length JPEG BLOB field class with <>. +==== +[source,json] +---- +{ + "type": "dynamic-length-blob", + "length-field-location": ["event-record-common-context", "length"], + "media-type": "image/jpeg", + "user-attributes": { + "my.tracer": { + "quality": 85 + } + } +} +---- +==== + +[[struct-fc]] +==== Structure field class + +A _structure field class_ describes _structure fields_. + +A structure field is a <> of zero or more structure +field _members_. A structure field member is a named field. + +.Properties of a structure field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"structure"`. +|Yes +| + +|`member-classes` +|JSON array of <> +|Classes of the members of an instance of{nbsp}{var-f}. + +The `name` property of each member class {must} be unique within the +member class names of{nbsp}{var-f}. +|No +|`+[]+` + +|`minimum-alignment` +|JSON integer +|Minimum alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which contains this +instance. + +The value of this property {must} be a positive power of two. + +The <> of the first bit of an instance +of{nbsp}{var-f} {may} be greater than the value of this property. +|No +|`1` + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Empty structure field class: instances have no members. +==== +[source,json] +---- +{ + "type": "structure" +} +---- +==== + +.Structure field class with three member classes. +==== +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "Villeray", + "field-class": { + "type": "null-terminated-string" + } + }, + { + "name": "Berri", + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 32, + "byte-order": "little-endian", + "preferred-display-base": 2 + }, + "user-attributes": { + "my.tracer": { + "is-mask": true + } + } + }, + { + "name": "Faillon", + "field-class": { + "type": "fixed-length-boolean", + "length": 8, + "byte-order": "little-endian" + } + } + ] +} +---- +==== + +.Structure field class with instances minimally aligned to 64{nbsp}bits. +==== +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "St-Denis", + "field-class": { + "type": "null-terminated-string" + } + }, + { + "name": "Lajeunesse", + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 32, + "byte-order": "big-endian", + "alignment": 32 + } + } + ], + "minimum-alignment": 64 +} +---- +==== + +.Structure field class with <>. +==== +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "Henri-Julien", + "field-class": { + "type": "fixed-length-signed-integer", + "length": 48, + "byte-order": "little-endian" + } + }, + { + "name": "Casgrain", + "field-class": { + "type": "static-length-string", + "length": 32 + } + } + ], + "user-attributes": { + "my.tracer": { + "version": 4 + } + } +} +---- +==== + +[[struct-member-cls]] +===== Structure field member class + +A _structure field member class_ describes _structure field members_. + +A structure field member class is a JSON object. + +.Properties of a structure field member class _**M**_. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`name` +|JSON string +|Name of{nbsp}__**M**__. +|Yes +| + +|`field-class` +|<> +|Field class of{nbsp}__**M**__. +|Yes +| + +|`user-attributes` +|<> +|User attributes of{nbsp}__**M**__. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}__**M**__. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.<> member class named `cat`. +==== +[source,json] +---- +{ + "name": "cat", + "field-class": { + "type": "null-terminated-string" + } +} +---- +==== + +.{c-vl-sint-fc} member class named `dog` with <>. +==== +[source,json] +---- +{ + "name": "dog", + "field-class": { + "type": "variable-length-signed-integer", + "preferred-display-base": 8 + }, + "user-attributes": { + "my.tracer": { + "uuid": [ + 243, 97, 0, 184, 236, 54, 72, 97, + 141, 107, 169, 214, 171, 137, 115, 201 + ], + "is-pid": true + } + } +} +---- +==== + +[[array-fc]] +==== Abstract array field class + +An _abstract array_ field class is a base of a {sl-array-fc} and a +{dl-array-fc}. + +This field class is abstract in that it only exists to show the relation +between different array field classes in this document: a <> +cannot contain an abstract array field. + +.Common properties of an array field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`element-field-class` +|<> +|Class of the element fields contained in an instance of{nbsp}{var-f}. +|Yes +| + +|`minimum-alignment` +|JSON integer +|Minimum alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which contains this +instance. + +The value of this property {must} be a positive power of two. + +The <> of the first bit of an instance +of{nbsp}{var-f} {may} be greater than the value of this property. +|No +|`1` +|=== + +[[sl-array-fc]] +==== {c-sl-array} field class + +A _{sl-array}_ field class is an <> +which describes _{sl-array}_ fields. + +A {sl-array} field is a sequence of zero or more element fields. + +The length, or number of element fields, of a {sl-array} field is a +property (`length`) of its class. + +.Properties of a {sl-array} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"static-length-array"`. +|Yes +| + +|`element-field-class` +|<> +|Class of the element fields contained in an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|Yes +| + +|`minimum-alignment` +|JSON integer +|Minimum alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which contains this +instance. + +The value of this property {must} be a positive power of two. + +The <> of the first bit of an instance +of{nbsp}{var-f} {may} be greater than the value of this property. + +Property inherited from the <>. +|No +|`1` + +|`length` +|JSON integer +|Number of element fields contained in an instance of{nbsp}{var-f}. + +The value of this property {must} be greater than or equal to zero. +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Empty {sl-array} field class. +==== +[source,json] +---- +{ + "type": "static-length-array", + "element-field-class": { + "type": "fixed-length-signed-integer", + "length": 16, + "byte-order": "little-endian", + "alignment": 16 + }, + "length": 0 +} +---- +==== + +.{c-sl-array} field class with instances having 100{nbsp}<> fields. +==== +[source,json] +---- +{ + "type": "static-length-array", + "element-field-class": { + "type": "null-terminated-string" + }, + "length": 100 +} +---- +==== + +.{c-sl-array} field class with <>. +==== +[source,json] +---- +{ + "type": "static-length-array", + "element-field-class": { + "type": "variable-length-unsigned-integer" + }, + "length": 13, + "user-attributes": { + "my.tracer": true + } +} +---- +==== + +.{c-sl-array} field class with instances minimally aligned to 32{nbsp}bits. +==== +With the following {sl-array} field class, a <> +can write a single 32-bit-aligned, 32-bit little-endian integer value, +and have <> <> it as +an array of 32{nbsp}flags (booleans). + +[source,json] +---- +{ + "type": "static-length-array", + "length": 32, + "minimum-alignment": 32, + "element-field-class": { + "type": "fixed-length-boolean", + "length": 1, + "byte-order": "little-endian" + } +} +---- +==== + +[[dl-array-fc]] +==== {c-dl-array} field class + +A _{dl-array}_ field class is an <> +which describes _{dl-array}_ fields. + +A {dl-array} field is a sequence of zero or more element fields. + +The length, or number of element fields, of a {dl-array} field is the +value of another, anterior (already encoded/decoded) _length_ field. A +<> can locate this length field thanks to the +`length-field-location` property of the {dl-array} field class. + +.Properties of a {dl-array} field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"dynamic-length-array"`. +|Yes +| + +|`element-field-class` +|<> +|Class of the element fields contained in an instance of{nbsp}{var-f}. + +Property inherited from the <>. +|Yes +| + +|`minimum-alignment` +|JSON integer +|Minimum alignment of the first bit of an instance of{nbsp}{var-f} +relative to the beginning of the <> which contains this +instance. + +The value of this property {must} be a positive power of two. + +The <> of the first bit of an instance +of{nbsp}{var-f} {may} be greater than the value of this property. + +Property inherited from the <>. +|No +|`1` + +|`length-field-location` +|<> +|Location of the field of which the value is the number of element +fields contained in an instance of{nbsp}{var-f}. + +The class of the length field {must} be one of: + +* {c-fl-uint-fc} +* {c-vl-uint-fc} +|Yes +| + +|`roles` +|<> +|Roles of an instance of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.{c-dl-array} field class. +==== +[source,json] +---- +{ + "type": "dynamic-length-array", + "element-field-class": { + "type": "fixed-length-unsigned-integer", + "length": 32, + "byte-order": "big-endian", + "alignment": 16 + }, + "length-field-location": ["event-record-payload", "length"] +} +---- +==== + +.{c-dl-array} field class with <>. +==== +[source,json] +---- +{ + "type": "dynamic-length-array", + "element-field-class": { + "type": "variable-length-unsigned-integer" + }, + "length-field-location": ["packet-context", "common-length"], + "user-attributes": { + "my.tracer": 177 + } +} +---- +==== + +[[opt-fc]] +==== Optional field class + +An _optional_ field class describes _optional_ fields. + +An optional field is, depending on the value of another, anterior +(already encoded/decoded) _selector_ field, one of: + +* An instance of a given field class (`field-class` property of the + optional field class). ++ +In this case, the optional field is said to be _enabled_. + +* A zero-bit field (no field). ++ +In this case, the optional field is said to be _disabled_. + +A <> can locate the selector field thanks to the +`selector-field-location` property of the optional field class. + +.Properties of an optional field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"optional"`. +|Yes +| + +|`field-class` +|<> +|Class of an instance of{nbsp}{var-f} when it's enabled. +|Yes +| + +|`selector-field-location` +|<> +|Location of the field of which the value indicates whether or not an +instance of{nbsp}{var-f} is enabled. + +A selector field{nbsp}__**S**__ {must} be an instance of one of: + +{c-fl-bool-fc}:: + An instance of{nbsp}{var-f} is enabled when{nbsp}__**S**__ is + true. + +{c-fl-int-fc}:: +{c-vl-int-fc}:: + An instance of{nbsp}{var-f} is enabled when the value + of{nbsp}__**S**__ is an element of any of the integer ranges of the + `selector-field-ranges` property of{nbsp}{var-f}. + +For a given instance of{nbsp}{var-f}, the `type` property of the +<> of _all_ the possible selector fields {must} be +one of: + +* <> +* Any of: +** <> +** <> +** <> +** <> + +* Any of: +** <> +** <> +** <> +** <> +|Yes +| + +|`selector-field-ranges` +|<> +|Ranges of integers which the value of a selector field {must} be an +element of to enable an instance of{nbsp}{var-f}. +|Yes, if the selector field is an instance of a {fl-int-fc} +or a {vl-int-fc}. +|None if the selector field is an instance of a {fl-bool-fc}. + +|`roles` +|<> +|Roles of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Optional {sl-array-fc} with a <> selector field class. +==== +[source,json] +---- +{ + "type": "optional", + "selector-field-location": ["event-record-payload", "has-ip"], + "field-class": { + "type": "static-length-array", + "element-field-class": { + "type": "fixed-length-unsigned-integer", + "length": 8, + "byte-order": "little-endian", + "alignment": 8 + }, + "length": 16 + } +} +---- +==== + +.Optional {str} with a <> selector field class. +==== +[source,json] +---- +{ + "type": "optional", + "selector-field-location": ["event-record-payload", "has-ip"], + "selector-field-ranges": [[-12, -12], [-5, 0], [15, 35]], + "field-class": { + "type": "null-terminated-string" + } +} +---- +==== + +[[var-fc]] +==== Variant field class + +A _variant_ field class describes _variant_ fields. + +A variant field is, depending on the value of another, anterior (already +encoded/decoded) _selector_ field, the instance of a specific, effective +field class amongst one or more _variant field class options_. + +A <> can locate the selector field thanks to the +`selector-field-location` property of the variant field class. + +.Properties of a variant field class {var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"variant"`. +|Yes +| + +|`options` +|JSON array of <> +|Options containing the possible effective classes of an instance +of{nbsp}{var-f}. + +This array {must} contain one or more elements. + +The `name` property of each option, if it's set, {must} be unique within +the option names of{nbsp}{var-f}. + +The integer ranges (`selector-field-ranges` property) of two given +options {must-not} intersect. +|Yes +| + +|`selector-field-location` +|<> +|Location of the field of which the value indicates which option +of{nbsp}{var-f} contains the effective class of an instance +of{nbsp}{var-f}. + +For a given instance of{nbsp}{var-f}, the `type` property of the +<> of _all_ the possible selector fields {must} be +one of: + +* Any of: +** <> +** <> +** <> +** <> + +* Any of: +** <> +** <> +** <> +** <> +|Yes +| + +|`roles` +|<> +|Roles of{nbsp}{var-f}. + +See <> and <> which indicate accepted within their +root field classes. +|No +|`+[]+` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Variant field class with two options. +==== +[source,json] +---- +{ + "type": "variant", + "selector-field-location": ["event-record-payload", "sel"], + "options": [ + { + "selector-field-ranges": [[5, 5]], + "field-class": { + "type": "null-terminated-string" + } + }, + { + "selector-field-ranges": [[8, 8]], + "field-class": { + "type": "fixed-length-signed-integer", + "length": 16, + "byte-order": "little-endian", + "preferred-display-base": 8 + } + } + ] +} +---- +==== + +.Variant field class within an {opt-fc} which share the same selector field location. +==== +This example shows that an optional field class and a contained variant +field class {may} share the same selector field location. + +In this example, depending on the value of the selector field: + +[horizontal] +0:: + The optional field is _not_ enabled. + +1:: + The optional field is enabled and is a variant field. ++ +The variant field is an instance of a {str-fc} (effective class). + +2:: + The optional field is enabled and is a variant field. ++ +The variant field is an instance of a {vl-sint-fc} (effective class). + +[source,json] +---- +{ + "type": "optional", + "selector-field-location": ["event-record-payload", "sel"], + "selector-field-ranges": [[1, 255]], + "field-class": { + "type": "variant", + "selector-field-location": ["event-record-payload", "sel"], + "options": [ + { + "selector-field-ranges": [[1, 1]], + "field-class": { + "type": "null-terminated-string" + } + }, + { + "selector-field-ranges": [[2, 2]], + "field-class": { + "type": "variable-length-signed-integer", + "preferred-display-base": 16 + } + } + ] + } +} +---- +==== + +.Variant field class with <>. +==== +[source,json] +---- +{ + "type": "variant", + "selector-field-location": ["event-record-specific-context", "sel"], + "options": [ + { + "selector-field-ranges": [[5, 5], [10, 10], [15, 15]], + "field-class": { + "type": "static-length-string", + "length": 20 + } + }, + { + "selector-field-ranges": [[0, 4], [6, 9], [11, 14], [16, 127]], + "field-class": { + "type": "fixed-length-floating-point-number", + "length": 32, + "byte-order": "big-endian" + } + } + ], + "user-attributes": { + "my.tracer": { + "owner": "Jimmy", + "id": 199990 + } + } +} +---- +==== + +[[var-fc-opt]] +===== Variant field class option + +A _variant field class option_ contains a possible effective class of a +variant field. + +A variant field class option{nbsp}__**O**__ also contains the ranges of +integer values (`selector-field-ranges` property) of which the value of +a selector field {must} be an element of for the effective class of a +variant field to be the field class of {var-o}. + +A variant field class option is a JSON object. + +.Properties of a variant field class option {var-o} contained in a variant field class{nbsp}{var-f}. +[%header%autowidth, cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`field-class` +|<> +|Field class of{nbsp}{var-o}. +|Yes +| + +|`selector-field-ranges` +|<> +|Ranges of integers which the value of a selector field {must} be an +element of for the effective class of an instance of{nbsp}{var-f} +to be the field class (`field-class` property) of{nbsp}{var-o}. +|Yes +| + +|`name` +|JSON string +|Name of{nbsp}{var-o}. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode an instance of{nbsp}{var-f}. +|No +|{var-o} is unnamed + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-o}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-o}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +.Unnamed {str-fc} option. +==== +[source,json] +---- +{ + "field-class": { + "type": "null-terminated-string" + }, + "selector-field-ranges": [[3, 9]] +} +---- +==== + +.{c-vl-sint-fc} option named `juice` with <>. +==== +[source,json] +---- +{ + "name": "juice", + "field-class": { + "type": "variable-length-signed-integer", + "preferred-display-base": 16 + }, + "selector-field-ranges": [[-4, 4], [9, 9], [100, 200]], + "user-attributes": { + "my.tracer": { + "uuid": [ + 243, 97, 0, 184, 236, 54, 72, 97, + 141, 107, 169, 214, 171, 137, 115, 201 + ], + "is-did": true + } + } +} +---- +==== + +[[preamble-frag]] +=== Preamble fragment + +A _preamble fragment_ indicates: + +* The {ctf2} major version (2). ++ +{ctf2} doesn't have a minor version: users can use +<> and <> to add +features to, or change features of, the format which this document +specifies. + +* <> declarations. ++ +An extension declaration is an initial extension of which the purpose is +to declare that it's _enabled_ within the <>. ++ +Because an extension {may} alter the {ctf2} format itself, and because a +preamble fragment is always the first metadata stream fragment, those +extension declarations make it possible for a <> +to gracefully decline the <> of the trace if it doesn't +support _any_ declared extension. + +The first fragment of a metadata stream {must} be a preamble fragment. + +.Properties of a preamble fragment {var-f}. +[%header%autowidth] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"preamble"`. +|Yes +| + +|`version` +|JSON integer +|{ctf2} major version. + +The value of this property {must} be `2`. +|Yes +| + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extension declarations of{nbsp}{var-f}. + +The name of each property is a <> and its value is a +<>. + +Within a <>, an extension +named{nbsp}__**N**__ is _declared_ when it exists as a property +named{nbsp}__**N**__, whatever the value of the property. +|No +|`+{}+` +|=== + +.Minimal preamble fragment. +==== +[source,json] +---- +{ + "type": "preamble", + "version": 2 +} +---- +==== + +.Preamble fragment with <> declarations. +==== +The following preamble fragment declares the `piano` and `ramen` +extensions under the `my.tracer` namespace. + +[source,json] +---- +{ + "type": "preamble", + "version": 2, + "extensions": { + "my.tracer": { + "piano": { + "keys": 88, + "temperament": "equal" + }, + "ramen": null + } + } +} +---- +==== + +[[tc-frag]] +=== Trace class fragment + +A _trace class_ describes <>. + +Within a metadata stream, a trace class fragment {must} occur, if any, +before any <>. + +.Properties of a trace class fragment {var-f}. +[%header%autowidth,cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"trace-class"`. +|Yes +| + +|`uuid` +|<> +|UUID of{nbsp}{var-f}. +|No +|{var-f}{nbsp}has no UUID + +|`packet-header-field-class` +|{c-struct-fc} +|Class of all the <> of an instance +of{nbsp}{var-f}. + +Any field class as the value of this property {must} satisfy _at least +one of_: + +* Have at least one valid <>. +* Be a {struct-fc}. +* Be an {opt-fc}. +* Be a {var-fc}. +* Be the class of a field which is the selector field of an optional + or variant field. +|No +|{var-f}{nbsp}has no packet header field class + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +==== Roles + +[[pkt-header-roles]] If the `packet-header-field-class` property of a +trace class fragment exists, then the <> of its +<> {may} have the following +<>: + +.Roles of field classes of the member classes of a packet header field class. +[%header%autowidth,cols="d,d,a,a"] +|=== +|Name |Description |Field class ({var-f}) constraints |Other constraints + +|`packet-magic-number` +|<> magic number. + +The purpose of a packet magic number field is to confirm the beginning +of a {ctf2} packet. +|{c-fl-uint-fc} with the following property value: + +[horizontal] +`length`:: + `32` +|An instance of{nbsp}{var-f} {must} be the _first_ member of the packet +header structure field. + +The value of an instance of{nbsp}{var-f} value {must} be 0xc1fc1fc1 +(3254525889). + +|`trace-class-uuid` +|Trace class UUID. + +The purpose of a trace class UUID field is to confirm the association +between a <> and a <>. +|{c-sl-blob-fc} with the following property value: + +[horizontal] +`length`:: + `16` +|The `uuid` property of the trace class {must} exist. + +The 16{nbsp}bytes of an instance of{nbsp}{var-f} {must} be equal to the +16{nbsp}JSON integers of the `uuid` property of the trace class. + +|`data-stream-class-id` +|Data stream class ID. + +The purpose of a data stream class ID field is to set the current ID of +the class of the data stream of the current packet. +|{c-fl-uint-fc} or {vl-uint-fc}. +| + +|`data-stream-id` +|Data stream ID. + +The purpose of a data stream ID field is to set the current ID of +the data stream of the current packet. + +Combined with the ID of its class, such a field makes it possible to +uniquely identify a data stream within a <>. +|{c-fl-uint-fc} or {vl-uint-fc}. +| +|=== + +.Trace class fragment. +==== +[source,json] +---- +{ + "type": "trace-class", + "uuid": [ + 30, 201, 100, 148, 228, 2, 69, 70, + 147, 219, 233, 34, 43, 238, 108, 199 + ], + "packet-header-field-class": { + "type": "structure", + "member-classes": [ + { + "name": "the magic!", + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 32, + "byte-order": "little-endian", + "preferred-display-base": 16, + "roles": ["packet-magic-number"] + } + }, + { + "name": "the UUID", + "field-class": { + "type": "static-length-blob", + "length": 16, + "roles": ["trace-class-uuid"] + } + }, + { + "name": "my data stream class ID", + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 8, + "byte-order": "little-endian", + "roles": ["data-stream-class-id"] + } + }, + { + "name": "my data stream ID", + "field-class": { + "type": "variable-length-unsigned-integer", + "roles": ["data-stream-id"] + } + } + ] + } +} +---- +==== + +[[cc-frag]] +=== Clock class fragment + +A _clock class_ describes _clocks_. + +A <> {may} have a <>. + +Within a metadata stream, a clock class fragment {must} occur before any +<> which refers to it by name with +its `default-clock-class-name` property. + +.Properties of a clock class fragment {var-f}. +[%header%autowidth,cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"clock-class"`. +|Yes +| + +|`frequency` +|JSON integer +|Frequency of an instance of{nbsp}{var-f} (Hz). + +The value of this property {must} be greater than zero. +|Yes +| + +|`name` +|JSON string +|Name of{nbsp}{var-f}. +|Yes +| + +|`description` +|JSON string +|Textual description of{nbsp}{var-f}. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode <>. +|No +|{var-f}{nbsp}has no textual description + +|`uuid` +|<> +|UUID of{nbsp}{var-f}. + +This property exists to remain backward compatible with {ctf1}: +it's not strictly needed to decode <>. +|No +|{var-f}{nbsp}has no UUID + +|`origin-is-unix-epoch` +|JSON boolean +|Whether or not the origin of an instance of{nbsp}{var-f} is +the https://en.wikipedia.org/wiki/Unix_time[Unix epoch]. + +If the value of this property is `false`, then the origin of +an instance of{nbsp}{var-f} is unknown. +|No +|`true` + +|`offset` +|<> +|Offset of an instance of{nbsp}{var-f} relative to its origin. + +Let: + +. _**H**_ be the value of the `frequency` property of{nbsp}{var-f}. +. {var-o} be the value of this property. +. {var-s} be the value of the `seconds` property of{nbsp}{var-o}. +. _**C**_ be the value of the `cycles` property of{nbsp}{var-o}. + +Then the effective offset of an instance of{nbsp}{var-f}, in clock +cycles, +is{nbsp}{var-s}{nbsp}{times}{nbsp}__**H**__{nbsp}pass:[+]{nbsp}__**C**__. +|No +|`{"seconds":{nbsp}0, "cycles":{nbsp}0}` + +|`precision` +|JSON integer +|Precision of an instance of{nbsp}{var-f} (clock cycles). + +The value of this property {must} be greater than or equal to zero. + +Let{nbsp}{var-p} be the value of this property and{nbsp}__**V**__ +the value of an instance of{nbsp}{var-f}: the range of possible +values of the instance +is{nbsp}[__**V**__{nbsp}{minus}{nbsp}{var-p},{nbsp}__**V**__{nbsp}pass:[+]{nbsp}{var-p}]. +|No +|`0` + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +Within a metadata stream, two given clock class fragments {must-not}: + +* Share the same `name` property value. +* Share the same `uuid` property value. + +.Minimal clock class fragment with 1-GHz instances. +==== +[source,json] +---- +{ + "type": "clock-class", + "name": "my clock class", + "frequency": 1000000000 +} +---- +==== + +.Clock class fragment with a UUID property. +==== +[source,json] +---- +{ + "type": "clock-class", + "name": "my clock class", + "frequency": 1000000000, + "uuid": [ + 116, 210, 0, 140, 239, 255, 77, 3, + 129, 99, 233, 226, 134, 106, 207, 32 + ] +} +---- +==== + +.Clock class fragment with instances having a specific offset. +==== +[source,json] +---- +{ + "type": "clock-class", + "name": "my clock class", + "frequency": 1000000000, + "offset": { + "seconds": 1605112699, + "cycles": 2878388 + } +} +---- +==== + +.Clock class fragment with instances having a specific precision. +==== +[source,json] +---- +{ + "type": "clock-class", + "name": "my clock class", + "frequency": 8000000, + "precision": 100 +} +---- +==== + +.Clock class fragment with instances having an origin which isn't the Unix epoch. +==== +[source,json] +---- +{ + "type": "clock-class", + "name": "my clock class", + "frequency": 1000000000, + "origin-is-unix-epoch": false +} +---- +==== + +.Clock class fragment with <>. +==== +[source,json] +---- +{ + "type": "clock-class", + "name": "my clock class", + "frequency": 16000000, + "user-attributes": { + "my.tracer": { + "sys-name": "SOC23", + "bus": { + "name": "LMB5", + "index": 5 + }, + "propagation-delay-ps": 177 + } + } +} +---- +==== + +[[clock-offset]] +==== Clock offset + +A _clock offset_ contains the offset of the instances of a +<> relative to their origin. + +A clock offset is a JSON object. + +.Properties of a clock offset contained in a clock class fragment {var-f}. +[%header%autowidth] +|=== +|Name |Type |Description |Required? |Default + +|`seconds` +|JSON integer +|Offset, in seconds, of an instance of{nbsp}{var-f} relative to its +origin. +|No +|`0` + +|`cycles` +|JSON integer +|Offset, in cycles, of an instance of{nbsp}{var-f} relative to its +origin. + +The value of this property {must} be greater than or equal to zero. + +The value of this property {must} be less than the value of the +`frequency` property of{nbsp}{var-f}. +|No +|`0` +|=== + +.Minimal clock offset. +==== +[source,json] +---- +{} +---- +==== + +.Clock offset with seconds and cycles. +==== +[source,json] +---- +{ + "seconds": 1605112699, + "cycles": 2878388 +} +---- +==== + +.Clock offset with seconds only. +==== +[source,json] +---- +{ + "seconds": 1605111293 +} +---- +==== + +.Negative clock offset. +==== +This example shows that a clock offset {may} be negative, that is, +_before_ the origin of the clock. + +[source,json] +---- +{ + "seconds": -18003, + "cycles": 11928547 +} +---- +==== + +[[dsc-frag]] +=== Data stream class fragment + +A _data stream class_ describes <>. + +Within a metadata stream, a data stream class fragment {var-f} {must} +occur before any <> of +which{nbsp}{var-f} is the parent. + +.Properties of a data stream class fragment {var-f}. +[%header%autowidth,cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"data-stream-class"`. +|Yes +| + +|`id` +|JSON integer +|Numeric ID of{nbsp}{var-f}. + +The value of this property {must} be greater than or equal to zero. +|No +|`0` + +|`name` +|JSON string +|Name of{nbsp}{var-f}. + +The purpose of this property, combined with the `namespace` property, is +to uniquely identify a data stream class amongst many +<>. +|No +|{var-f}{nbsp}is unnamed + +|`namespace` +|JSON string +|<> of{nbsp}{var-f}. + +The purpose of this property, combined with the `name` property, is to +uniquely identify a data stream class amongst many +<>. +|No +|{var-f}{nbsp}has no namespace + +|`default-clock-class-name` +|JSON string +|Name of the <> of the <> of an +instance of{nbsp}{var-f}. + +Within the metadata stream containing{nbsp}{var-f}, the <> which has the value of this property as its `name` +property {must} occur before{nbsp}{var-f}. +|No +|An instance of{nbsp}{var-f} has no default clock + +|`packet-context-field-class` +|{c-struct-fc} +|Class of all the <> of an instance +of{nbsp}{var-f}. +|No +|{var-f}{nbsp}has no packet context field class + +|`event-record-header-field-class` +|{c-struct-fc} +|Class of all the <> of an +instance of{nbsp}{var-f}. + +Any field class as the value of this property {must} satisfy _at least +one of_: + +* Have at least one valid <>. +* Be a {struct-fc}. +* Be an {opt-fc}. +* Be a {var-fc}. +* Be the class of a field which is the selector field of an optional or + variant field. +|No +|{var-f}{nbsp}has no event record header field class + +|`event-record-common-context-field-class` +|{c-struct-fc} +|Class of all the <> +of an instance of{nbsp}{var-f}. +|No +|{var-f}{nbsp}has no event record common context field class + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +Within a metadata stream, two given data stream class fragments +{must-not} share the same `id` property value. + +==== Roles + +[[pkt-ctx-roles]] If the `packet-context-field-class` property of a data +stream class fragment exists, then the <> of its +<> {may} have the following +<>: + +.Roles of field classes of the member classes of a packet context field class. +[%header%autowidth,cols="d,d,a,a"] +|=== +|Name |Description |Field class ({var-f}) constraints |Other constraints + +|`packet-total-size` +|Total size (bits) of the <>. + +This size includes any padding after the packet contents. +|{c-fl-uint-fc} or {vl-uint-fc}. + +|The value of an instance of{nbsp}{var-f} {must} be greater than or +equal to the value of an instance of a field class having the +`packet-content-size` role, if any, within the _same_ packet context +field. + +|`packet-content-size` +|Content size (bits) of the packet. +|{c-fl-uint-fc} or {vl-uint-fc}. +|The value of an instance of{nbsp}{var-f} {must} be less than or equal +to the value of an instance of a field class having the +`packet-total-size` role, if any, within the _same_ packet context +field. + +|`packet-beginning-default-clock-timestamp` +|Timestamp of the <> of the <> +when the packet begins. +|{c-fl-uint-fc} or {vl-uint-fc}. +|The timestamps of all the <> of the packet {must} be +greater than or equal to the value of an instance of{nbsp}{var-f}. + +The value of an instance of{nbsp}{var-f} {must} be less than or equal to +the value of an instance of a field class having the +`packet-end-default-clock-timestamp` role, if any, within the _same_ +packet context field. + +|`packet-end-default-clock-timestamp` +|Timestamp of the default clock of the data stream when the packet ends. +|{c-fl-uint-fc} or {vl-uint-fc}. +|The timestamps of all the <> of the packet {must} be +less than or equal to the value of an instance of{nbsp}{var-f}. + +The value of an instance of{nbsp}{var-f} {must} be greater than or equal +to the value of an instance of a field class having the +`packet-beginning-default-clock-timestamp` role, if any, within the +_same_ packet context field. + +|`discarded-event-record-counter-snapshot` +|Snapshot of the <> of +the data stream when the packet ends. +|{c-fl-uint-fc} or {vl-uint-fc}. +| + +|[[pkt-seq-num-role]] `packet-sequence-number` +|Sequence number of the packet within its data stream. +|{c-fl-uint-fc} or {vl-uint-fc}. +| +|=== + +[[er-header-roles]] If the `event-record-header-field-class` property of +a data stream class fragment exists, then the <> of +its <> {may} have the following +<>: + +.Roles of field classes of the member classes of an event record header field class. +[%header%autowidth,cols="d,d,a"] +|=== +|Name |Description |Field class ({var-f}) constraints + +|`event-record-class-id` +|Event record class ID. + +The purpose of an event record class ID field is to set the current ID +of the class of the event record within its parent <>. +|{c-fl-uint-fc} or {vl-uint-fc}. + +|`default-clock-timestamp` +|Current timestamp of the <> of the data stream +when the event record occurs. +|{c-fl-uint-fc} or {vl-uint-fc}. +|=== + +[[erc-frag]] +=== Event record class fragment + +An _event record class_ describes <>. + +The <> of which the value of the +`id` property matches the value of the `data-stream-class-id` property +of an event record class fragment{nbsp}{var-f} is considered the +_parent_ of{nbsp}{var-f}. + +.Properties of an event record class fragment{nbsp}{var-f} having the data stream class{nbsp}{var-p} as its parent. +[%header%autowidth,cols="d,d,a,d,d"] +|=== +|Name |Type |Description |Required? |Default + +|`type` +|JSON string +|Type of{nbsp}{var-f}. + +The value of this property {must} be `"event-record-class"`. +|Yes +| + +|`id` +|JSON integer +|Numeric ID of{nbsp}{var-f} within{nbsp}{var-p}. + +The value of this property {must} be greater than or equal to zero. +|No +|`0` + +|`data-stream-class-id` +|JSON integer +|Numeric ID of{nbsp}{var-p}. + +The value of this property {must} be greater than or equal to zero. + +Within the metadata stream,{nbsp}{var-p} {must} occur +before{nbsp}{var-f}. +|No +|`0` + +|`name` +|JSON string +|Name of{nbsp}{var-f}. + +The purpose of this property, combined with the `namespace` property, is +to uniquely identify an event record class amongst many +<>. +|No +|{var-f}{nbsp}is unnamed + +|`namespace` +|JSON string +|<> of{nbsp}{var-f}. + +The purpose of this property, combined with the `name` property, is to +uniquely identify an event record class amongst many +<>. +|No +|{var-f}{nbsp}has no namespace + +|`specific-context-field-class` +|{c-struct-fc} +|Class of the <> +of an instance of{nbsp}{var-f}. +|No +|{var-f}{nbsp}has no event record specific context field class + +|`payload-field-class` +|{c-struct-fc} +|Class of the <> of an +instance of{nbsp}{var-f}. +|No +|{var-f}{nbsp}has no event record payload field class + +|`user-attributes` +|<> +|User attributes of{nbsp}{var-f}. +|No +|`+{}+` + +|`extensions` +|<> +|Extensions of{nbsp}{var-f}. + +Any extension which exists under this property {must} also be declared +in the <> of the metadata stream. +|No +|`+{}+` +|=== + +Within a metadata stream, two given event record class fragments +{must-not} share the same `id` property value _and_ the same +`data-stream-class-id` property value. + +[[ds-dec]] +== Data stream decoding procedure + +This section shows how to, procedurally, _decode_ a {ctf2} <>. + +Decoding a data stream is the responsibility of a +<>. + +This document doesn't specify how to encode a data stream, as this +procedure implies much more freedom than decoding. One can deduce how to +encode a data stream from the decoding procedure. + +A consumer needs to keep a _data stream decoding state_ while decoding a +data stream. A data stream decoding state comprises the following +_variable_: + +.Variable needed to decode a data stream{nbsp}{var-s}. +[%header%autowidth] +|=== +|Name |Type |Description |Initial value + +|{var-dec-o} +|Unsigned integer +|Current decoding offset/position (bits) from the beginning +of{nbsp}{var-s}. +|0 +|=== + +To decode a data stream {var-s}: + +* While there's remaining data in {var-s}: +** <>. + +[[pkt-dec]] +=== Packet decoding procedure + +A <> needs to keep a _packet decoding state_ +while decoding a <>. A packet decoding state comprises the +following _variables_: + +.Variables needed to decode a packet{nbsp}{var-p} within a data stream{nbsp}{var-s}. +[%header%autowidth] +|=== +|Name |Type |Description |Initial value + +|_**DEF_CLK_VAL**_ +|Unsigned integer +|Current value (clock cycles) of the <> of{nbsp}{var-s}, if any. +|0 + +|_**DSC_ID**_ +|Unsigned integer +|Current ID of the <> of{nbsp}{var-s}. +|0 + +|_**DSC**_ +|Optional <> +|Current class of{nbsp}{var-s}. +|None + +|_**DS_ID**_ +|Optional unsigned integer +|Current ID of{nbsp}{var-s}. +|None + +|_**PKT_TOTAL_SZ**_ +|Unsigned integer +|Current total size (bits) of{nbsp}{var-p}. +|∞ + +|_**PKT_CONTENT_SZ**_ +|Unsigned integer +|Current content size (bits) of{nbsp}{var-p}. +|∞ + +|_**LAST_BO**_ +|Optional string +|Byte order of the last <>. +|None +|=== + +To decode a packet {var-p} within a data stream {var-s}: + +. Let {var-dec-po} be the current value of {var-dec-o}. ++ +While decoding the packet, {var-dec-o-minus-po} is the current decoding +offset/position (bits) from the beginning of{nbsp}{var-p}. + +. If the `packet-header-field-class` property of the <> of the metadata stream exists, then + <> the <> + of{nbsp}{var-p} using this property. ++ +During the packet header field decoding procedure, after having decoded +a field{nbsp}{var-f} having the class{nbsp}__**C**__ with a `roles` +property: ++ +** If _**C**_ has the role `packet-magic-number`, then validate that the + unsigned integer value of{nbsp}{var-f} is 0xc1fc1fc1 (3254525889). ++ +A <> {should} report an invalid packet magic +number as an error. + +** If _**C**_ has the role `trace-type-uuid`, then validate that the + value of{nbsp}{var-f} matches the `uuid` property of the trace + class fragment. ++ +A consumer {should} report a trace type UUID mismatch as an error. + +** If _**C**_ has the role `data-stream-class-id`, then + set{nbsp}__**DSC_ID**__ to the unsigned integer value + of{nbsp}{var-f}. + +** If _**C**_ has the role `data-stream-id`, then + set{nbsp}__**DS_ID**__ to the unsigned integer value + of{nbsp}{var-f}. + ++ +After having decoded the whole packet header field, +if{nbsp}__**DS_ID**__ is set, then it's the ID of{nbsp}{var-s} within +its <>. In other words, two data streams {may} have the +same ID if they are instances of different data stream classes. + +. Set _**DSC**_ to the <> + having{nbsp}__**DSC_ID**__ as the value of its `id` property. ++ +If no data stream class has the ID{nbsp}__**DSC_ID**__, then report an +error and abort the data stream decoding process. + +. If the `packet-context-field-class` property of{nbsp}__**DSC**__ + exists, then <> the <> + of{nbsp}{var-p} using this property. ++ +During the packet context field decoding procedure, after having decoded +a field{nbsp}{var-f} having the class{nbsp}__**C**__ with a `roles` +property: ++ +** If _**C**_ has the role `packet-total-size`, then + set{nbsp}__**PKT_TOTAL_SZ**__ to the unsigned integer value + of{nbsp}{var-f}. + +** If _**C**_ has the role `packet-content-size`, then + set{nbsp}__**PKT_CONTENT_SZ**__ to the unsigned integer value + of{nbsp}{var-f}. + +** If _**C**_ has the role `packet-beginning-default-clock-timestamp`, + then set{nbsp}__**DEF_CLK_VAL**__ to the unsigned integer value + of{nbsp}{var-f}. + +** If _**C**_ has the role `packet-end-default-clock-timestamp`, then + the unsigned integer value of{nbsp}{var-f} is the value of the + <> of{nbsp}{var-s} at the end of{nbsp}{var-p}. + +** If _**C**_ has the role `discarded-event-record-counter-snapshot`, + then the unsigned integer value of{nbsp}{var-f} is a snapshot of the + <> of{nbsp}{var-s} at + the end of{nbsp}{var-p}. + +** If _**C**_ has the role `packet-sequence-number`, then the unsigned + integer value of{nbsp}{var-f} is the sequence number of{nbsp}{var-p} + within{nbsp}{var-s}. + ++ +A <> {should} report a beginning default clock +timestamp greater than an end default clock timestamp as an error. + +. If __**PKT_TOTAL_SZ**__ is{nbsp}∞ and __**PKT_CONTENT_SZ**__ is + __not__{nbsp}∞, then set{nbsp}__**PKT_TOTAL_SZ**__ + to{nbsp}__**PKT_CONTENT_SZ**__. + +. If __**PKT_CONTENT_SZ**__ is{nbsp}∞ and __**PKT_TOTAL_SZ**__ is + __not__{nbsp}∞, then set{nbsp}__**PKT_CONTENT_SZ**__ + to{nbsp}__**PKT_TOTAL_SZ**__. + +. While {var-dec-o}{nbsp}<{nbsp}{var-dec-po}{nbsp}pass:[+]{nbsp}__**PKT_CONTENT_SZ**__ + and there's remaining data in{nbsp}{var-s}: + +** <>. + +. If __**PKT_TOTAL_SZ**__ and{nbsp}__**PKT_CONTENT_SZ**__ both are + __not__{nbsp}∞, then set{nbsp}{var-dec-o} to + {var-dec-po}{nbsp}pass:[+]{nbsp}__**PKT_TOTAL_SZ**__, effectively + skipping end-of-packet padding. + +[[er-dec]] +=== Event record decoding procedure + +A <> needs to keep an _event record decoding +state_ while decoding an <>. An event record decoding +state comprises the following _variables_: + +.Variables needed to decode an event record{nbsp}__**E**__ within a data stream{nbsp}{var-s}. +[%header%autowidth] +|=== +|Name |Type |Description |Initial value + +|_**ERC_ID**_ +|Unsigned integer +|Current ID of the <> of{nbsp}__**E**__ of which the +parent is the <> of{nbsp}{var-s}. +|0 + +|_**ERC**_ +|Optional <> +|Current class of{nbsp}__**E**__. +|None +|=== + +To decode an event record _**E**_ within a data stream {var-s}: + +. If the `event-record-header-field-class` property of{nbsp}__**DSC**__ + exists, then <> the <> of{nbsp}__**E**__ using this property. ++ +During the event record header field decoding procedure, after having +decoded a field{nbsp}{var-f} having the class{nbsp}__**C**__ with a +`roles` property: ++ +** If _**C**_ has the role `event-record-class-id`, then + set{nbsp}__**ERC_ID**__ to the unsigned integer value + of{nbsp}{var-f}. + +** If _**C**_ has the role `default-clock-timestamp`, then + <> from{nbsp}{var-f}. + + ++ +After having decoded the whole event record header field, +__**DEF_CLK_VAL**__ is the value of the <> +of{nbsp}{var-s} when{nbsp}__**E**__ occurs. + +. Set _**ERC**_ to the <> having: + +** __**DSC_ID**__ as the value of its `data-stream-class-id` property. +** __**ERC_ID**__ as the value of its `id` property. + ++ +If no event record class has the ID{nbsp}__**ERC_ID**__ within a data +stream class having the ID{nbsp}__**DSC_ID**__, then report an error and +abort the data stream decoding process. + +. If the `event-record-common-context-field-class` property + of{nbsp}__**DSC**__ exists, then <> the + <> of{nbsp}__**E**__ using this + property. + +. If the `specific-context-field-class` property of{nbsp}__**ERC**__ + exists, then <> the + <> of{nbsp}__**E**__ + using this property. + +. If the `payload-field-class` property of{nbsp}__**ERC**__ exists, then + <> the <> + of{nbsp}__**E**__ using this property. + +[[clk-val-update]] +==== Clock value update procedure + +To update __**DEF_CLK_VAL**__ from an unsigned integer +field{nbsp}{var-f} having the unsigned integer value{nbsp}__**V**__ and +the <>{nbsp}__**C**__: + +. Let __**L**__ be an unsigned integer initialized to, + depending on the `type` property of{nbsp}__**C**__: ++ +-- +<>:: +<>:: + The value of the `length` property of{nbsp}__**C**__. + +<>:: +<>:: + __**S**__{nbsp}{times}7, where{nbsp}__**S**__ is the number of + <> which{nbsp}{var-f} occupies + with the <>. +-- + +. Let _**MASK**_ be an unsigned integer initialized to + 2^__**L**__^{nbsp}{minus}{nbsp}1. + +. Let _**H**_ be an unsigned integer initialized to + __**DEF_CLK_VAL**__{nbsp}&{nbsp}pass:[~]__**MASK**__, + where "`&`" is the bitwise _AND_ operator and + "`pass:[~]`" is the bitwise _NOT_ operator. + +. Let _**CUR**_ be an unsigned integer initialized to + __**DEF_CLK_VAL**__{nbsp}&{nbsp}__**MASK**__, where "`&`" is the + bitwise _AND_ operator. + +. Set __**DEF_CLK_VAL**__ to: ++ +-- +If __**V**__{nbsp}≥{nbsp}__**CUR**__:: + __**H**__{nbsp}pass:[+]{nbsp}__**V**__ + +Else:: + __**H**__{nbsp}pass:[+]{nbsp}__**MASK**__{nbsp}pass:[+]{nbsp}1{nbsp}pass:[+]{nbsp}__**V**__ +-- + +[[field-dec]] +=== Field decoding procedure + +The <> of a field contains what's needed to decode it as a +_value_. + +While a field is an actual <> of bits within a +<>, a value is its conceptual interpretation with +attached semantics. + +[[dec-val-type]] The types of values are: + +[%header%autowidth,cols="a,a"] +|=== +|Value type |Possible values + +|Nil +|None. + +|Boolean +|_True_ or _false_. + +|Unsigned/signed integer +|Integral quantity. + +|Real +|Continuous quantity. + +|String +|<> of https://home.unicode.org/[Unicode] characters. + +|Array +|Sequence of values. + +|Structure +|Sequence of named values (members). +|=== + +To decode an instance of a field class{nbsp}{var-f}, depending on the +value of its `type` property: + +[%header%autowidth,cols="a,a"] +|=== +|Value of the `type` property of{nbsp}{var-f} |Decoding procedure of {var-f} + +|<> +|<>. + +|<> +|<>. + +| +* <> +* <> +|<>. + +| +* <> +* <> +|<>. + +|<> +|<>. + +|<> +|<>. + +| +* <> +* <> +|<>. + +| +* <> +* <> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. + +|<> +|<>. +|=== + +[[align-dec]] +==== Alignment procedure + +The decoding procedure of many fields require +{var-dec-o-minus-po} to have a specific _alignment_. + +The alignment _requirement_ of an instance of a <>{nbsp}{var-f} is, depending on the value of its `type` property: + +[%header,cols="a,a"] +|=== +|`type` property of {var-f} |Alignment requirement of {var-f} + +| +* <> +* <> +* <> +* <> +* <> +* <> +* <> +|The value of the `alignment` property of{nbsp}{var-f}. + +| +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +|8 + +|<> +|The _maximum_ value of: + +* The value of the `minimum-alignment` property of{nbsp}{var-f}. + +* The alignment requirements of the instances of the `field-class` + property of each <> of the + `member-classes` property of{nbsp}{var-f}. + +| +* <> +* <> +|The _maximum_ value of: + +* The value of the `minimum-alignment` property of{nbsp}{var-f}. + +* The alignment requirement of an instance of the + `element-field-class` property of{nbsp}{var-f}. + +| +* <> +* <> +|1 +|=== + +To align {var-dec-o-minus-po} to some alignment +requirement{nbsp}__**A**__ (bits): + +* Set {var-dec-o} to + {var-dec-po}{nbsp}pass:[+]{nbsp}(({var-dec-o-minus-po}{nbsp}pass:[+]{nbsp}__**A**__{nbsp}{minus}{nbsp}1){nbsp}&{nbsp}{minus}__**A**__), + where "`&`" is the bitwise _AND_ operator. + +[[field-loc-dec]] +==== Field location procedure + +To locate a previously decoded field using a +<>{nbsp}__**FL**__: + +. Let {var-v} be, depending on the first element of{nbsp}__**FL**__: ++ +-- +`"packet-header"`:: + The <> structure of{nbsp}__**P**__ + (<>). + +`"packet-context"`:: + The <> structure of{nbsp}__**P**__. + +`"event-record-header"`:: + The <> structure of{nbsp}__**E**__ + (<>). + +`"event-record-common-context"`:: + The <> structure of{nbsp}__**E**__. + +`"event-record-specific-context"`:: + The <> structure of{nbsp}__**E**__. + +`"event-record-payload"`:: + The <> structure of{nbsp}__**E**__. +-- ++ +If the consumer cannot set {var-v} because there's no such structure or +because it's not already decoded nor currently being decoded, then +report an error and abort the data stream decoding process. + +. For each element{nbsp}__**FLE**__ of{nbsp}__**FL**__, starting from + the second element: + +.. Let {var-v} be the value of the member named{nbsp}__**FLE**__ + within{nbsp}{var-v}. ++ +If no member is named{nbsp}__**FLE**__ within{nbsp}{var-v}, then +report an error and abort the data stream decoding process. ++ +If the member named{nbsp}__**FLE**__ within{nbsp}{var-v} is not already +decoded nor currently being decoded, then report an error and abort +the data stream decoding process. + +.. Depending on the <> of {var-v}: ++ +-- +Boolean:: +Signed integer:: +Unsigned integer:: + If{nbsp}__**FLE**__ is not the last element of{nbsp}__**FL**__, + then report an error and abort the data stream decoding process. + +Structure:: + Continue. + +Array:: + While {var-v} is an array: ++ +* If {var-v} is not currently being decoded, then report an error and + abort the data stream decoding process. ++ +Set {var-v} to the element of {var-v} currently being decoded. + +Other:: + Report an error and abort the data stream decoding process. +-- + +{var-v} is the located field. + +.<> field and its length field in the same root field. +==== +Assume the following JSON object is an event record payload {struct-fc}. + +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "corn", <3> + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 32, + "byte-order": "little-endian" + } + }, + { + "name": "inside", + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 16, + "byte-order": "little-endian" + } + }, + { + "name": "carbon", + "field-class": { + "type": "dynamic-length-array", <1> + "length-field-location": ["event-record-payload", "corn"], <2> + "element-field-class": { + "type": "null-terminated-string" + } + } + } + ] +} +---- +<1> {c-dl-array-fc}. +<2> Length field location of the {dl-array-fc}. +<3> Length member class. +==== + +.{c-dl-array} field and its length field in the same root field, within the same array field element. +==== +Assume the following JSON object is an event record payload {struct-fc}. + +Both the {dl-array} field and its length field exist within the same +element of the <> field named `nature`. + +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "norm", + "field-class": { + "type": "null-terminated-string" + } + }, + { + "name": "nature", + "field-class": { + "type": "static-length-array", + "length": 43, + "element-field-class": { + "type": "structure", + "member-classes": [ + { + "name": "laser", <3> + "field-class": { + "type": "variable-length-unsigned-integer" + } + }, + { + "name": "joystick", + "field-class": { + "type": "dynamic-length-array", <1> + "length-field-location": [ <2> + "event-record-payload", + "nature", + "laser" + ], + "element-field-class": { + "type": "null-terminated-string" + } + } + } + ] + } + } + } + ] +} +---- +<1> {c-dl-array-fc}. +<2> Length field location of the {dl-array-fc}. +<3> Length member class. +==== + +.{c-dl-array} and its length field in the same root field, within the same <> field. +==== +Assume the following JSON object is an event record payload {struct-fc}. + +Both the {dl-array} field and its length field exist within the same +option of the <> field named `clinic`. + +Moreover, the selector field of the `clinic` variant field is the +`lawyer` field. + +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "lawyer", <5> + "field-class": { + "type": "fixed-length-signed-integer", + "length": 16, + "byte-order": "little-endian" + } + }, + { + "name": "clinic", + "field-class": { + "type": "variant", + "selector-field-location": ["event-record-payload", "lawyer"], <4> + "options": [ + { + "selector-field-ranges": [[0, 0]], + "field-class": { + "type": "null-terminated-string" + } + }, + { + "selector-field-ranges": [[1, 4]], + "field-class": { + "type": "structure", + "member-classes": [ + { + "name": "lemon", <3> + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 8, + "byte-order": "big-endian" + } + }, + { + "name": "joystick", + "field-class": { + "type": "dynamic-length-array", <1> + "length-field-location": [ <2> + "event-record-payload", + "clinic", + "lemon" + ], + "element-field-class": { + "type": "null-terminated-string" + } + } + } + ] + } + }, + { + "selector-field-ranges": [[5, 5], [7, 7]], + "field-class": { + "type": "fixed-length-boolean", + "length": 8, + "byte-order": "little-endian" + } + } + ] + } + } + ] +} +---- +<1> {c-dl-array-fc}. +<2> Length field location of the {dl-array-fc}. +<3> Length member class. +<4> Selector field location of the variant field class. +<5> Selector member class. +==== + +.{c-dl-array} and its length field in the same root field; length field is a variant field. +==== +Assume the following JSON object is an event record payload {struct-fc}. + +The length field of the {dl-array} field is a variant field: it can be +an 8-bit, a 16-bit, or a 32-bit <> field, depending +on the selection of the variant field. + +Moreover, the selector field of the variant field is located in another +root field (event record specific context). + +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "glass", <3> + "field-class": { + "type": "variant", + "selector-field-location": ["event-record-specific-context", "sel"], + "options": [ + { + "selector-field-ranges": [[0, 0]], + "field-class": { + "type": "fixed-length-unsigned-integer", <4> + "length": 8, + "byte-order": "little-endian" + } + }, + { + "selector-field-ranges": [[1, 1]], + "field-class": { + "type": "fixed-length-unsigned-integer", <4> + "length": 16, + "byte-order": "little-endian" + } + }, + { + "selector-field-ranges": [[2, 2]], + "field-class": { + "type": "fixed-length-unsigned-integer", <4> + "length": 32, + "byte-order": "little-endian" + } + } + ] + } + }, + { + "name": "margin", + "field-class": { + "type": "dynamic-length-array", <1> + "length-field-location": ["event-record-payload", "glass"], <2> + "element-field-class": { + "type": "null-terminated-string" + } + } + } + ] +} +---- +<1> {c-dl-array-fc}. +<2> Length field location of the {dl-array-fc}. +<3> Length member class. +<4> Possible length field class. +==== + +.{c-dl-array} and its length field in the same root field; structure field containing length field is a variant field. +==== +Assume the following JSON object is an event record payload {struct-fc}. + +The length field of the {dl-array} field is within a structure field +which is a variant field. + +Moreover: + +* The selector field of the variant field is located in another root + field (event record common context). + +* The field class of the third option of the `glass` variant field class + contains a {dl-blob-fc} (`lock` member); the + length field of its instance is the previous member (`eagle`) within + the same structure field. + +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "glass", + "field-class": { + "type": "variant", + "selector-field-location": ["event-record-common-context", "sel"], + "options": [ + { + "selector-field-ranges": [[0, 0]], + "field-class": { + "type": "structure", + "member-classes": [ + { + "name": "eagle", + "field-class": { + "type": "fixed-length-unsigned-integer", <3> + "length": 16, + "byte-order": "little-endian" + } + }, + { + "name": "road", + "field-class": { + "type": "null-terminated-string" + } + } + ] + } + }, + { + "selector-field-ranges": [[32, 172]], + "field-class": { + "type": "structure", + "member-classes": [ + { + "name": "nuance", + "field-class": { + "type": "null-terminated-string" + } + }, + { + "name": "eagle", + "field-class": { + "type": "fixed-length-unsigned-integer", <3> + "length": 24, + "byte-order": "big-endian" + } + } + ] + } + }, + { + "selector-field-ranges": [[5, 5]], + "field-class": { + "type": "structure", + "member-classes": [ + { + "name": "eagle", <5> + "field-class": { + "type": "variable-length-unsigned-integer" <3> + } + }, + { + "name": "lock", + "field-class": { + "type": "dynamic-length-blob", + "length-field-location": [ <4> + "event-record-payload", + "glass", + "eagle" + ] + } + } + ] + } + } + ] + } + }, + { + "name": "margin", + "field-class": { + "type": "dynamic-length-array", <1> + "length-field-location": [ <2> + "event-record-payload", + "glass", + "eagle" + ], + "element-field-class": { + "type": "null-terminated-string" + } + } + } + ] +} +---- +<1> {c-dl-array-fc}. +<2> Length field location of the {dl-array-fc}. +<3> Possible length field class. +<4> Length field location of the {dl-blob-fc}. +<5> Length field class for the {dl-blob-fc}. + +Note that both the {dl-array} and {dl-blob} field classes have the same +length field location. +==== + +.{c-dl-array} and its length field in another root field. +==== +Assume the following JSON objects are the event record specific context +and payload <> of the same +<>. + +The length field of the {dl-array} field of the event record payload is +within the event record specific context. + +.Event record specific context field class. +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "cook", + "field-class": { + "type": "fixed-length-floating-point-number", + "length": 64, + "byte-order": "little-endian" + } + }, + { + "name": "vegetable", <1> + "field-class": { + "type": "variable-length-unsigned-integer" + } + } + ] +} +---- +<1> Length member class. + +.Event record payload field class. +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "avenue", + "field-class": { + "type": "dynamic-length-array", <1> + "length-field-location": [ <2> + "event-record-specific-context", + "vegetable" + ], + "element-field-class": { + "type": "null-terminated-string" + } + } + }, + { + "name": "railroad", + "field-class": { + "type": "null-terminated-string" + } + } + ] +} +---- +<1> {c-dl-array-fc}. +<2> Length field location of the {dl-array-fc}. +==== + +[[fl-ba-field-dec]] +==== {c-fl-ba} field decoding procedure + +For this whole section about decoding an instance of a +{fl-ba-fc}{nbsp}{var-f}, let _**BO**_ be the value of the `byte-order` +property of{nbsp}{var-f}. + +[[fl-ba-field-dec-bit]] To read a single data stream bit from an +instance of{nbsp}{var-f}: + +. Let: + +** _**BYTE_I**_ be ({var-dec-o-minus-po}){nbsp}/{nbsp}8 (integral + division; remainder discarded). + +** _**BIT_I**_ be: ++ +-- +[horizontal] +_**BO**_ is `"big-endian"`:: + 7{nbsp}{minus}{nbsp}(({var-dec-o-minus-po}){nbsp}mod{nbsp}8) + +_**BO**_ is `"little-endian"`:: + ({var-dec-o-minus-po}){nbsp}mod{nbsp}8 +-- + +. Depending on the value of the bit at the index{nbsp}__**BIT_I**__, + where{nbsp}0 is the index of the + https://en.wikipedia.org/wiki/Bit_numbering#Least_significant_bit[least significant bit], + within the byte at the index{nbsp}__**BYTE_I**__ from the beginning + of{nbsp}__**P**__ (the current packet being decoded): ++ +-- +[horizontal] +0:: + The bit value is _false_. + +1:: + The bit value is _true_. +-- + +To decode an instance of{nbsp}{var-f}: + +. Let: + +.. _**L**_ be the value of the `length` property of{nbsp}{var-f}. +.. {var-v} be an array of booleans of length{nbsp}__**L**__. +.. _**I**_ be an unsigned integer initialized to{nbsp}0. + +. <> according + to{nbsp}{var-f}. + +. [[fl-ba-field-dec-step-3]] If + (({var-dec-o-minus-po}){nbsp}mod{nbsp}8{nbsp}{noteq}{nbsp}0) and + __**LAST_BO**__{nbsp}{noteq}{nbsp}__**BO**__, then report an error + and abort the data stream decoding process. + +. While __**I**__{nbsp}<{nbsp}__**L**__: + +.. Let _**VI**_ be an unsigned integer initialized to: ++ +[horizontal] +_**BO**_ is `"big-endian"`:: + 0 + +_**BO**_ is `"little-endian"`:: + __**L**__{nbsp}{minus}{nbsp}__**I**__{nbsp}{minus}{nbsp}1 + +.. Set the element at the index{nbsp}__**VI**__ of{nbsp}{var-v} + to the current <>. + +.. Set __**I**__ to __**I**__{nbsp}+{nbsp}1. + +.. Set {var-dec-o} to {var-dec-o}{nbsp}+{nbsp}1. + +. Set _**LAST_BO**_ to{nbsp}__**BO**__. + +{var-v} is the decoded bit array value. + +To add to the decoding procedure above, note that the "`reading +direction`" within a byte depends on{nbsp}__**BO**__. Assuming +{var-dec-o-minus-po}{nbsp}={nbsp}0, the following diagrams show which +bit is selected by {var-dec-o-minus-po} within a 16-bit {fl-ba} field +depending on{nbsp}__**BO**__: + +`"big-endian"`:: {empty} ++ +image::{doc-id}-images/bit-array-decoding-be.svg[] + +`"little-endian"`:: {empty} ++ +image::{doc-id}-images/bit-array-decoding-le.svg[] + +.Contiguous {fl-ba} fields: big-endian versus little-endian. +==== +This example shows the binary layout of contiguous big-endian and +little-endian {fl-ba} fields. + +Assume that {var-dec-o-minus-po}{nbsp}={nbsp}16. All the {fl-ba} +fields of this example have an implicit 1-bit <>. + +Considering the following <> of some +{struct-fc}: + +[source,json] +---- +[ + { + "name": "green", + "field-class": { + "type": "fixed-length-bit-array", + "length": 3, + "byte-order": "big-endian" + } + }, + { + "name": "blue", + "field-class": { + "type": "fixed-length-bit-array", + "length": 9, + "byte-order": "big-endian" + } + }, + { + "name": "yellow", + "field-class": { + "type": "fixed-length-bit-array", + "length": 14, + "byte-order": "big-endian" + } + }, + { + "name": "red", + "field-class": { + "type": "fixed-length-bit-array", + "length": 4, + "byte-order": "big-endian" + } + } +] +---- + +The binary layout is as such: + +image::{doc-id}-images/bit-array-fields-be.svg[] + +Considering the following member classes of some structure field class, +the only difference with the previous sample being the values of the +`byte-order` property: + +[source,json] +---- +[ + { + "name": "green", + "field-class": { + "type": "fixed-length-bit-array", + "length": 3, + "byte-order": "little-endian" + } + }, + { + "name": "blue", + "field-class": { + "type": "fixed-length-bit-array", + "length": 9, + "byte-order": "little-endian" + } + }, + { + "name": "yellow", + "field-class": { + "type": "fixed-length-bit-array", + "length": 14, + "byte-order": "little-endian" + } + }, + { + "name": "red", + "field-class": { + "type": "fixed-length-bit-array", + "length": 4, + "byte-order": "little-endian" + } + } +] +---- + +The binary layout is as such: + +image::{doc-id}-images/bit-array-fields-le.svg[] +==== + +.Padding between {fl-ba} fields. +==== +This example shows how the <> of a +{fl-ba} field can translate into padding bits to skip during the +decoding process. + +Assume that {var-dec-o-minus-po}{nbsp}={nbsp}32. + +Considering the following <> of some +{struct-fc}: + +[source,json] +---- +[ + { + "name": "green", + "field-class": { + "type": "fixed-length-bit-array", + "length": 5, + "byte-order": "big-endian" + } + }, + { + "name": "blue", + "field-class": { + "type": "fixed-length-bit-array", + "length": 3, + "byte-order": "big-endian", + "alignment": 8 + } + }, + { + "name": "yellow", + "field-class": { + "type": "fixed-length-bit-array", + "length": 4, + "byte-order": "big-endian", + "alignment": 4 + } + } +] +---- + +The binary layout is as such: + +image::{doc-id}-images/bit-array-fields-padding-be.svg[] + +Considering the following member classes of some structure field class, +the only difference with the previous sample being the values of the +`byte-order` property: + +[source,json] +---- +[ + { + "name": "green", + "field-class": { + "type": "fixed-length-bit-array", + "length": 5, + "byte-order": "little-endian" + } + }, + { + "name": "blue", + "field-class": { + "type": "fixed-length-bit-array", + "length": 3, + "byte-order": "little-endian", + "alignment": 8 + } + }, + { + "name": "yellow", + "field-class": { + "type": "fixed-length-bit-array", + "length": 4, + "byte-order": "little-endian", + "alignment": 4 + } + } +] +---- + +The binary layout is as such: + +image::{doc-id}-images/bit-array-fields-padding-le.svg[] +==== + +.Contiguous {fl-ba} fields with different byte orders. +==== +<> of the decoding procedure above +requires that a <> stops the data stream decoding +process if the byte order between two contiguous {fl-ba} fields changes +when{nbsp}{var-dec-o-minus-po} is not a mutliple of{nbsp}8. + +In other words, a given data stream <> {must-not} contain +bits of two {fl-ba} fields having different byte orders. + +This example shows how contiguous {fl-ba} fields may have different byte +orders with correct <>. + +Assume that {var-dec-o-minus-po}{nbsp}={nbsp}16. + +Considering the following <> of some +{struct-fc}: + +[source,json] +---- +[ + { + "name": "green", + "field-class": { + "type": "fixed-length-bit-array", + "length": 3, + "byte-order": "big-endian" + } + }, + { + "name": "blue", + "field-class": { + "type": "fixed-length-bit-array", + "length": 5, + "byte-order": "big-endian" + } + }, + { + "name": "yellow", + "field-class": { + "type": "fixed-length-bit-array", + "length": 5, + "byte-order": "little-endian" + } + }, + { + "name": "orange", + "field-class": { + "type": "fixed-length-bit-array", + "length": 8, + "byte-order": "little-endian" + } + }, + { + "name": "red", + "field-class": { + "type": "fixed-length-bit-array", + "length": 6, + "byte-order": "big-endian", + "alignment": 8 + } + } +] +---- + +The binary layout is as such: + +image::{doc-id}-images/bit-array-fields-be-le.svg[] +==== + +[[fl-bool-field-dec]] +==== {c-fl-bool} field decoding procedure + +To decode an instance of a {fl-bool-fc}: + +. Let __**VB**__ be a boolean. +. <>. +. If all the elements of{nbsp}{var-v} are _false_, then set{nbsp}__**VB**__ + to _false_. ++ +Else, set __**VB**__ to _true_. + +_**VB**_ is the decoded boolean value. + +[[fl-uint-field-dec]] +==== {c-fl-uint} field decoding procedure + +To decode an instance of a {fl-uint-fc}: + +. Let __**VI**__ be an unsigned integer. +. <>. +. Set __**VI**__ as the unsigned integer interpretation +of{nbsp}{var-v}, where the first element of{nbsp}{var-v} is the most +significant bit. + +_**VI**_ is the decoded unsigned integer value. + +[[fl-sint-field-dec]] +==== {c-fl-sint} field decoding procedure + +To decode an instance of a {fl-sint-fc}: + +. Let __**VI**__ be a signed integer. +. <>. +. Set __**VI**__ as the signed integer interpretation, following the + two's complement format, of{nbsp}{var-v}, where the first element + of{nbsp}{var-v} is the most significant bit. + +_**VI**_ is the decoded signed integer value. + +[[fl-fp-field-dec]] +==== {c-fl-fp} field decoding procedure + +To decode an instance of a {fl-fp-fc}: + +. Let __**VR**__ be a real value. +. <>. +. Set __**VR**__ to the real number interpretation, following the + {ieee754}, of{nbsp}{var-v}, where the first element of{nbsp}{var-v} is + the most significant bit. + +_**VR**_ is the decoded real value. + +[[vl-ba-field-dec]] +==== {c-vl-ba} field decoding procedure + +To decode an instance of a {vl-ba-fc}{nbsp}{var-f}: + +. Let {var-v} be an empty array of booleans. + +. <> according + to{nbsp}{var-f}. + +. Read __**N**__{nbsp}bytes of data from{nbsp}{var-s} at the + offset{nbsp}{var-dec-o}, as many as needed following the unsigned + https://en.wikipedia.org/wiki/LEB128[LEB128] format, appending the + decoded bits to{nbsp}{var-v} as booleans from the most + significant to the least significant. + +. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}__**N**__{nbsp}{times}{nbsp}8. + +{var-v} is the decoded value. + +.3-byte {vl-ba} field decoding. +==== +Consider the following {vl-ba-fc}{nbsp}{var-f}: + +[source,json] +---- +{ + "type": "variable-length-bit-array" +} +---- + +The following diagram shows the three bytes of an instance +of{nbsp}{var-f} and the resulting bit array value. + +image::{doc-id}-images/vl-ba.svg[] + +Note that the data bits of the last byte (in red) become the first +elements of the resulting bit array value because LEB128 is a +little-endian encoding. +==== + +[[vl-uint-field-dec]] +==== {c-vl-uint} field decoding procedure + +To decode an instance of a {vl-uint-fc}: + +. Let __**VI**__ be an unsigned integer. +. <>. +. Set __**VI**__ as the unsigned integer interpretation of{nbsp}{var-v}, + where the first element of{nbsp}{var-v} is the most significant bit. + +_**VI**_ is the decoded unsigned integer value. + +[[vl-sint-field-dec]] +==== {c-vl-sint} field decoding procedure + +To decode an instance of a {vl-sint-fc}: + +. Let __**VI**__ be a signed integer. +. <>. +. Set __**VI**__ as the signed integer interpretation, following the + two's complement format, of{nbsp}{var-v}, where the first element + of{nbsp}{var-v} is the most significant bit. + +_**VI**_ is the decoded signed integer value. + +[[str-field-dec]] +==== {c-str} field decoding procedure + +To decode an instance of a {str-fc}{nbsp}{var-f}: + +. Let: +** _**B**_ be a byte. +** _**A**_ be an empty sequence of bytes. +** {var-v} be a string. + +. <> according + to{nbsp}{var-f}. + +. Read one byte of data from{nbsp}{var-s} at the offset{nbsp}{var-dec-o} + as{nbsp}__**B**__. + +. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}8. + +. While __**B**__{nbsp}{noteq}{nbsp}0: +.. Append __**B**__ to{nbsp}__**A**__. +.. Read one byte of data from{nbsp}{var-s} at the + offset{nbsp}{var-dec-o} as{nbsp}__**B**__. +.. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}8. + +. Decode _**A**_, following UTF-8, as {var-v}. + +{var-v} is the decoded string value. + +.22-byte {str} field decoding. +==== +Consider the following {str-fc}{nbsp}{var-f}: + +[source,json] +---- +{ + "type": "null-terminated-string" +} +---- + +The following diagram shows <> bytes including a 22-byte +instance of{nbsp}{var-f} (in blue) and its resulting string value. + +The offset of the {str} field, from the beginning of the packet, +is 0xfc23{nbsp}bytes, which means +{var-dec-o-minus-po}{nbsp}={nbsp}516,376. + +image::{doc-id}-images/str.svg[] + +The field contains 21{nbsp}UTF-8 bytes and a null terminating byte. + +The resulting string value contains 19{nbsp}Unicode characters. + +After the field is decoded, {var-dec-o-minus-po}{nbsp}={nbsp}516,552. +==== + +[[sl-str-field-dec]] +==== {c-sl-str} field decoding procedure + +To decode an instance of a {sl-str-fc}{nbsp}{var-f}: + +. Let: +** _**L**_ be the `length` property of{nbsp}{var-f}. +** _**I**_ be an unsigned integer initialized to 0. +** _**B**_ be a byte. +** _**R**_ be a boolean initialized to _true_. +** _**A**_ be an empty sequence of bytes. +** {var-v} be a string. + +. <> according + to{nbsp}{var-f}. + +. While __**I**__{nbsp}<{nbsp}__**L**__: + +.. Read one byte of data from{nbsp}{var-s} at the + offset{nbsp}{var-dec-o} as{nbsp}__**B**__. +.. If __**B**__{nbsp}={nbsp}0, then set _**R**_{nbsp}to _false_. ++ +Else, if _**R**_ is _true_, then append{nbsp}__**B**__ +to{nbsp}__**A**__. + +.. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}8. +.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1. + +. Decode _**A**_, following UTF-8, as {var-v}. + +{var-v} is the decoded string value. + +.18-byte {sl-str} field decoding. +==== +Consider the following {str-fc}{nbsp}{var-f}: + +[source,json] +---- +{ + "type": "static-length-string", + "length": 18 +} +---- + +The following diagram shows <> bytes including a 18-byte +instance of{nbsp}{var-f} (in green) and its resulting string value. + +The offset of the {sl-str} field, from the beginning of the packet, is +0x8c46{nbsp}bytes, which means {var-dec-o-minus-po}{nbsp}={nbsp}287,280. + +image::{doc-id}-images/sl-str.svg[] + +The field contains 14{nbsp}UTF-8 bytes, a null terminating byte, +and three garbage data bytes to ignore. + +The resulting string value contains seven Unicode characters. + +After the field is decoded, {var-dec-o-minus-po}{nbsp}={nbsp}287,424. +==== + +[[sl-blob-field-dec]] +==== {c-sl-blob} field decoding procedure + +To decode an instance of a {sl-blob-fc}{nbsp}{var-f}: + +. Let: +.. _**L**_ be the `length` property of{nbsp}{var-f}. +.. {var-v} be an array of bytes of length{nbsp}__**L**__. + +. <> according + to{nbsp}{var-f}. + +. Read _**L**_ bytes of data from{nbsp}{var-s} at the + offset{nbsp}{var-dec-o} as{nbsp}{var-v}. + +. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}__**L**__{nbsp}{times}{nbsp}8. + +{var-v} is the decoded BLOB value. + +[[dl-str-field-dec]] +==== {c-dl-str} field decoding procedure + +To decode an instance of a {dl-str-fc}{nbsp}{var-f}: + +. Let: +** _**L**_ be the value of the previously decoded unsigned integer + field of which the `length-field-location` property of{nbsp}{var-f} + indicates the <>. +** _**I**_ be an unsigned integer initialized to 0. +** _**B**_ be a byte. +** _**R**_ be a boolean initialized to _true_. +** _**A**_ be an empty sequence of bytes. +** {var-v} be a string. + +. <> according + to{nbsp}{var-f}. + +. While __**I**__{nbsp}<{nbsp}__**L**__: + +.. Read one byte of data from{nbsp}{var-s} at the + offset{nbsp}{var-dec-o} as{nbsp}__**B**__. +.. If __**B**__{nbsp}={nbsp}0, then set _**R**_{nbsp}to _false_. ++ +Else, if _**R**_ is _true_, then append{nbsp}__**B**__ +to{nbsp}__**A**__. + +.. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}8. +.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1. + +. Decode _**A**_, following UTF-8, as {var-v}. + +{var-v} is the decoded string value. + +[[dl-blob-field-dec]] +==== {c-dl-blob} field decoding procedure + +To decode an instance of a {dl-blob-fc}{nbsp}{var-f}: + +. Let: +.. _**L**_ be the value of the previously decoded unsigned integer + field of which the `length-field-location` property of{nbsp}{var-f} + indicates the <>. +.. {var-v} be an array of bytes of length{nbsp}__**L**__. + +. <> according + to{nbsp}{var-f}. + +. Read _**L**_ bytes of data from{nbsp}{var-s} at the + offset{nbsp}{var-dec-o} as{nbsp}{var-v}. + +. Set {var-dec-o} to {var-dec-o}{nbsp}pass:[+]{nbsp}__**L**__{nbsp}{times}{nbsp}8. + +{var-v} is the decoded BLOB value. + +[[struct-field-dec]] +==== Structure field decoding procedure + +To decode an instance of a {struct-fc}{nbsp}{var-f}: + +. Let: +** _**M**_ be the `member-classes` property of{nbsp}{var-f}. +** {var-v} be an empty structure. + +. <> according + to{nbsp}{var-f}. + +. For each member class{nbsp}__**MC**__ of{nbsp}__**M**__: +.. Let: +*** _**MF**_ be the `field-class` property of{nbsp}__**MC**__. +*** _**MN**_ be the `name` property of{nbsp}__**MC**__. +.. <> one instance of{nbsp}__**MF**__, appending the + resulting value as a member of{nbsp}{var-v} named{nbsp}__**MN**__. + +{var-v} is the decoded value. + +[[sl-array-field-dec]] +==== {c-sl-array} field decoding procedure + +To decode an instance of a {sl-array-fc}{nbsp}{var-f}: + +. Let: +.. _**L**_ be the `length` property of{nbsp}{var-f}. +.. _**EF**_ be the `element-field-class` property of{nbsp}{var-f}. +.. _**I**_ be an unsigned integer initialized to 0. +.. {var-v} be an array of values of length{nbsp}__**L**__. + +. <> according + to{nbsp}{var-f}. + +. While __**I**__{nbsp}<{nbsp}__**L**__: +.. <> one instance of{nbsp}__**EF**__ + as element{nbsp}__**I**__ of{nbsp}{var-v}. +.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1. + +{var-v} is the decoded value. + +[[dl-array-field-dec]] +==== {c-dl-array} field decoding procedure + +To decode an instance of a {dl-array-fc}{nbsp}{var-f}: + +. Let: +.. _**L**_ be the value of the previously decoded unsigned integer field + of which the `length-field-location` property of{nbsp}{var-f} + indicates the <>. +.. _**EF**_ be the `element-field-class` property of{nbsp}{var-f}. +.. _**I**_ be an unsigned integer initialized to 0. +.. {var-v} be an array of values of length{nbsp}__**L**__ + +. <> according + to{nbsp}{var-f}. + +. While __**I**__{nbsp}<{nbsp}__**L**__: +.. <> one instance of{nbsp}__**EF**__ + as element{nbsp}__**I**__ of{nbsp}{var-v}. +.. Set _**I**_ to __**I**__{nbsp}pass:[+]{nbsp}1. + +{var-v} is the decoded value. + +.5-element {dl-array} field decoding. +==== +Consider the following <> +{struct-fc}{nbsp}{var-f}: + +[source,json] +---- +{ + "type": "structure", + "member-classes": [ + { + "name": "len", + "field-class": { + "type": "fixed-length-unsigned-integer", + "length": 16, + "byte-order": "big-endian" + } + }, + { + "name": "id", + "field-class": { + "type": "null-terminated-string" + } + }, + { + "name": "vals", + "field-class": { + "type": + "type": "dynamic-length-array", + "length-field-location": ["event-record-payload", "len"], + "element-field-class": { + "type": "fixed-length-unsigned-integer", + "length": 32, + "byte-order": "little-endian", + "alignment": 32 + } + } + } + ] +} +---- + +The following diagram shows <> bytes including an instance +of{nbsp}{var-f} (starting in green and ending in blue) and the resulting +signed integer values of its `vals` member. + +The offset of the `len` {fl-uint} field, from the beginning of the packet, is +0x42c1{nbsp}bytes, which means {var-dec-o-minus-po}{nbsp}={nbsp}136,712. + +The offset of the `vals` {dl-array} field, from the beginning of the +packet, is 0x42c8{nbsp}bytes, which means +{var-dec-o-minus-po}{nbsp}={nbsp}136,768. + +image::{doc-id}-images/dl-array.svg[] + +The unsigned integer value of the `len` field is{nbsp}5, which means the +`vals` field contains five {fl-sint} fields. + +After the structure field is decoded, +{var-dec-o-minus-po}{nbsp}={nbsp}136,928. +==== + +[[opt-field-dec]] +==== Optional field decoding procedure + +To decode an instance of an {opt-fc}{nbsp}{var-f}: + +. Let: +** _**SEL**_ be the value of the previously decoded <> + or <> field of which the `selector-field-location` + property of{nbsp}{var-f} indicates the <>. +** _**OF**_ be the `field-class` property of {var-f}. +** {var-v} be a nil value. + +. If the class of{nbsp}__**SEL**__ is a {fl-bool-fc} + and _**SEL**_ is _true_, then: +** <> one instance of{nbsp}__**OF**__ + as{nbsp}{var-v}. + ++ +Else, if _**SEL**_ is an element of any <> +of the `selector-field-ranges` property of{nbsp}{var-f}, then: +** <> one instance of{nbsp}__**OF**__ + as{nbsp}{var-v}. + +{var-v} is the decoded value. + +[[var-field-dec]] +==== Variant field decoding procedure + +To decode an instance of an {var-fc}{nbsp}{var-f}: + +. Let: +.. _**SEL**_ be the value of the previously decoded <> + field of which the `selector-field-location` property of{nbsp}{var-f} + indicates the <>. +.. _**OPTS**_ be the `options` property of{nbsp}{var-f}. +.. _**OF**_ be the `field-class` property of the <>{nbsp}__**OPT**__ of{nbsp}__**OPTS**__ of + which{nbsp}__**SEL**__ is an element of any <> of the `selector-field-ranges` property of{nbsp}__**OPT**__. +.. {var-v} be a value. + +. <> one instance of{nbsp}__**OF**__ + as{nbsp}{var-v}. + +{var-v} is the decoded value. diff --git a/CTF2-SPECRC-3.0.html b/CTF2-SPECRC-3.0.html new file mode 100644 index 0000000..13e7b58 --- /dev/null +++ b/CTF2-SPECRC-3.0.html @@ -0,0 +1,10587 @@ + + + + + + + + +CTF2-SPECRC-3.0: Common Trace Format version 2 release candidate + + + + + + +
+
+
+
+

This document is a release candidate of the Common Trace Format (CTF) +version 2 specification (CTF2-SPEC-2.0).

+
+
+ + + + + +
+ + +
RFC 2119
+The key words MUST, MUST NOT, REQUIRED, +SHOULD, SHOULD NOT, MAY, and OPTIONAL in this document, when +emphasized, are to be interpreted as described in +RFC 2119. +
+
+
+
+
+

1. Revision history

+
+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Revision history.
DocumentPublication dateChanges

CTF2-SPECRC-3.0

17 December 2021

+

Add the optional minimum-alignment property to the +abstract array field class.

+
+
+

Such a minimum alignment is needed when the alignment +requirement of contained array field elements wouldn’t be enough. For +example, a producer could write a single +32-bit-aligned, 32-bit little-endian integer value, but use the +following static-length array field class for consumers:

+
+
+
+
{
+  "type": "static-length-array",
+  "length": 32,
+  "minimum-alignment": 32,
+  "element-field-class": {
+    "type": "fixed-length-boolean",
+    "length": 1,
+    "byte-order": "little-endian"
+  }
+}
+
+
+
+

While the producer writes a single integer value, consumers decode said +datum as an array of 32 individual flags (booleans).

+
+
+

Update the Alignment procedure section accordingly.

+

CTF2‑SPECRC‑2.0

9 December 2021

+
    +
  • +

    Describe how to use a field location with a procedure in +a new Field location procedure section to make constraints easier to +understand.

    +
    • +
  • +

    Rename the members property of a structure field class to member-classes +as this JSON array contains +structure field member classes.

    +
    • +
  • +

    Make an optional field require that all its +possible selector fields be boolean fields, unsigned integer fields, +or signed integer fields.

    +
    +

    Correspondingly, make a variant field require that all its +possible selector fields be either unsigned integer fields or signed +integer fields.

    +
    +
    +

    This constraint exists to accomodate some consumer implementations, in +particular the ones with limited integer types.

    +
    +
    • +
  • +

    Add the “nil” decoding value type so that +decoding an optional field always generates a value.

    +
    • +
  • +

    Specify that an “array” decoding value contains a sequence of values, +whatever their types.

    +
    +

    Indeed, an array field MAY contain variant +fields, making it possible for a resulting array value to contain +values having different types.

    +
    +
    • +
+

CTF2‑SPECRC‑1.0

25 November 2021

+

Initial CTF 2 specification release candidate.

+
+
+
+
+

2. What’s CTF 2?

+
+
+

The Common Trace Format version 2 is a binary +trace format designed +to be very fast to write without compromising great flexibility.

+
+
+

The intention of CTF 2 is that applications written in any programming +language, and running on any system (be it Linux or bare metal, for +example), can generate traces natively.

+
+
+

A CTF 2 trace has all its data streams described by a +metadata stream. Given the rich set of +supported data field types, this makes it possible for a CTF 2 +producer to append data structures as is to data +streams without further “data massaging”. Indeed, the size, alignment, +and byte order of fixed-length fields are all configurable parameters +within the metadata stream.

+
+
+

CTF 2 is transport agnostic: this document doesn’t specify how to +transport or store CTF 2 streams. Other documents can specify such +conventions, and conform CTF 2 producers and consumers +may or may not adhere to them.

+
+
+

CTF 2 is a major revision of CTF 1, bringing many improvements, such +as:

+
+
+
    +
  • +

    Using JSON text sequences for the metadata stream.

    +
    • +
  • +

    Adding auxiliary streams (also JSON text sequences).

    +
    • +
  • +

    Simplifying the metadata stream.

    +
    • +
  • +

    Adding new field classes.

    +
    • +
  • +

    Using roles instead of reserved structure member names to +identify “special” fields.

    +
    • +
+
+
+

and more, while remaining backward compatible at the data stream level.

+
+
+
+
+

3. Common definitions

+
+
+

Common CTF 2 definitions:

+
+
+
+
Byte
+
+

A group of eight bits operated on +as a unit.

+
+

The bits are indexed such that, if the byte represents an 8-bit unsigned +integer, bit 0 is the +least +significant and bit 7 is the +most +significant.

+
+
+
Class
+
+

A set of values (instances) which share common properties.

+
+

For example, a fixed-length unsigned integer field class with an 8-bit length property is the set of +the all the fixed-length unsigned integer fields from binary 00000000 to 11111111 +(integers 0 to 255).

+
+
+

This specification often states that some class describes instances. +For example, an event record class describes event +records.

+
+
+
Consumer
+
+

A software or hardware system which consumes (reads) the streams of +a trace.

+
+

A trace consumer is often a trace viewer or a trace analyzer.

+
+
+
Namespace
+
+

A string of which the purpose is to avoid naming conflicts.

+
+

This document doesn’t specify the format of a namespace. A producer +SHOULD use a URI, or at least include a domain name owned by the +organization defining the objects under a namespace.

+
+
+ + + + + +
+ + +The std namespace is reserved for the CTF 2 specification. +
+
+
+
Producer
+
+

A software or hardware system which produces (writes) the streams of +a trace.

+
+

A trace producer is often a tracer.

+
+
+
Sequence
+
+

A set of related items which follow each other in a particular +order.

+
+
Stream
+
+

A sequence of bytes.

+
+
+
+
+
+
+

4. Trace composition

+
+
+

A trace is:

+
+
+ +
+
+

As a reminder, this specification defines a stream as a +sequence of bytes.

+
+
+ + + + + +
+ + +This document doesn’t specify how to transport or store CTF 2 +streams. A producer could serialize all streams as a +single file on the file system, or it could send the streams over the +network using TCP, to name a few examples. +
+
+
+

4.1. Metadata stream (overview)

+
+

A metadata stream describes trace data streams with JSON objects.

+
+
+

A metadata stream describes things such as:

+
+
+ +
+
+

Multiple traces MAY share the same metadata stream: a given trace +MAY contain specific information in its own auxiliary +streams.

+
+
+

See Metadata stream for the full metadata stream specification.

+
+
+
+

4.2. Data stream

+
+

A data stream is a sequence of one or more data +packets:

+
+
+
+ctf trace all +
+
+
+

In the metadata stream, a +data stream class describes data streams.

+
+
+

A packet MUST contain one or more bytes of data.

+
+
+

Although a packet MAY contain padding (garbage data) at the end +itself, from the point of view of a data stream, there’s no padding +between packets. In other words, the byte following the last byte of a +packet is the first byte of the next packet.

+
+
+

A data stream MAY have, conceptually:

+
+
+
+
One default, monotonic clock
+
+

Described by a clock class in the metadata stream.

+
+

Packets and event records MAY contain snapshots, named +timestamps, of the default clock of their data stream.

+
+
+
One counter of discarded event records
+
+

Indicates the number of event records which the +producer needed to discard for different reasons.

+
+

For example, a tracer could discard an event record when it doesn’t fit +some buffer and there’s no other available buffer.

+
+
+

A packet MAY contain a snapshot of this counter.

+
+
+
+
+
+

See Data stream decoding procedure to learn how to decode a CTF 2 data stream.

+
+
+

4.2.1. Packet

+
+

A packet is a segment of a data stream.

+
+
+

A packet contains a sequence of data fields or padding +(garbage data). In the metadata stream, field classes describe +data fields.

+
+
+

A packet P, contained in a data stream S, contains, +in this order:

+
+
+
    +
  1. +

    OPTIONAL: A header structure field, +described at the trace class level in the +metadata stream, which contains, in this order:

    +
    +
      +
    1. +

      OPTIONAL: A packet magic number field (0xc1fc1fc1, or 3254525889).

      +
      2. +
    2. +

      In any order:

      +
      +
        +
      • +

        OPTIONAL: A trace class UUID field.

        +
        • +
      • +

        OPTIONAL: One or more fields which contain the numeric ID of the +class of S.

        +
        • +
      • +

        OPTIONAL: One or more fields which contain the numeric ID +of S.

        +
        • +
      +
      +
      3. +
    +
    +
    2. +
  2. +

    OPTIONAL: A context structure field, +described at the data stream class level in the metadata +stream, which contains, in any order:

    +
    +
      +
    • +

      OPTIONAL: A field which contains the total size of P, +in bits (always a multiple of 8).

      +
      • +
    • +

      OPTIONAL: A field which contains the content size of P, +in bits.

      +
      • +
    • +

      OPTIONAL: A field which contains the beginning timestamp +of P.

      +
      • +
    • +

      OPTIONAL: A field which contains the end timestamp of P.

      +
      • +
    • +

      OPTIONAL: A field which contains a snapshot of the +discarded event record counter of S at +the end of P.

      +
      • +
    • +

      OPTIONAL: A field which contains the sequence number +of P within S.

      +
      • +
    • +

      OPTIONAL: User fields.

      +
      • +
    +
    +
    3. +
  3. +

    Zero or more event records.

    +
    4. +
+
+
+

A packet MUST contain one or more bytes of data.

+
+
+

A packet MAY contain padding (garbage data) after its last event +record. The size of this padding is the difference between its total +size and its content size (as found in its context structure +field).

+
+
+

Packets are independent of each other: if one removes a packet from a +data stream, a consumer can still decode the whole data +stream. This is why:

+
+
+ +
+
+

If the packet context fields of the packets of a data stream +contain a packet sequence number field, a consumer +can recognize missing packets.

+
+
+

See Packet decoding procedure to learn how to decode a CTF 2 packet.

+
+
+
+

4.2.2. Event record

+
+

An event record is the result of a producer writing a +record with OPTIONAL user data when an event occurs during its +execution.

+
+
+

A packet contains zero or more event records.

+
+
+

An event record class describes the specific parts of event +records.

+
+
+

An event record E, contained in a data stream S, +contains, in this order:

+
+
+
    +
  1. +

    OPTIONAL: A header structure field, +described at the data stream class level in the metadata +stream, which contains, in any order:

    +
    +
      +
    • +

      OPTIONAL: One or more fields which contain the numeric ID of the +class of E which has the class +of S as its parent.

      +
      • +
    • +

      OPTIONAL: One or more fields which contain a timestamp or a partial +timestamp.

      +
      • +
    +
    +
    2. +
  2. +

    OPTIONAL: A common context +structure field, described at the data stream class +level in the metadata stream, which contains user fields.

    +
    3. +
  3. +

    OPTIONAL: A specific context +structure field, described at the event record class +level in the metadata stream, which contains user fields.

    +
    4. +
  4. +

    OPTIONAL: A payload structure field, +described at the event record class level in the metadata stream, +which contains user fields.

    +
    5. +
+
+
+

An event record MUST contain one or more bits of data.

+
+
+

The default clock timestamp of an event record, that is, the +value of the default clock of its data stream after its +header field, if any, is encoded/decoded MUST be greater +than or equal to the default clock timestamp of the previous event +record, if any, within the same data stream.

+
+
+

See Event record decoding procedure to learn how to decode a CTF 2 event record.

+
+
+
+
+

4.3. Auxiliary stream

+
+

An auxiliary stream is a JSON text sequence, as specified by RFC 7464, +which contains extra, structured information about the trace which +doesn’t fit the data stream model.

+
+
+

Each element of an auxiliary stream is a JSON object which has a single +property:

+
+
+ + + + + + + + + +
+Name + +

Namespace of the auxiliary stream.

+
+Value + +

A JSON value.

+
+
+
+
Example 1. Auxiliary stream element with the my.tracer namespace.
+
+
+
+
{
+  "my.tracer": {
+    "version": [1, 3, 2],
+    "session-name": "amqui"
+  }
+}
+
+
+
+
+
+
Example 2. Auxiliary stream element of which the value is just 42.
+
+
+
+
{
+  "328c7a2d-a959-4f60-bd22-cca74359326f": 42
+}
+
+
+
+
+
+

4.3.1. Trace environment

+
+

To remain backward compatible with CTF 1, a trace MAY contain an +auxiliary stream having an element with the std namespace which +contains trace environment variables under the environment property.

+
+
+

The trace environment variables are a single JSON object where each +property is:

+
+
+ + + + + + + + + +
+Name + +

Trace environment variable name.

+
+Value + +

Trace environment variable value (any JSON value).

+
+
+
+

This document doesn’t specify trace environment variable names.

+
+
+
Example 3. std auxiliary stream element with trace environment variables.
+
+
+
+
{
+  "std": {
+    "environment": {
+      "hostname": "amqui",
+      "domain": "kernel",
+      "sysname": "Linux",
+      "kernel_release": "4.12.12-1-ARCH",
+      "kernel_version": "#1 SMP PREEMPT Sun Sep 10 09:41:14 CEST 2017",
+      "tracer_name": "lttng-modules",
+      "tracer_major": 2,
+      "tracer_minor": 10,
+      "tracer_patchlevel": 0
+    }
+  }
+}
+
+
+
+
+
+
+
+
+
+

5. Metadata stream

+
+
+

A metadata stream is a JSON text sequence, as specified by RFC 7464, +of fragments.

+
+
+

Together, the fragments of a metadata stream contain all the information +about the data streams of one or more traces.

+
+
+

A fragment is a JSON object; its allowed properties depend on +its type property.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 2. Common properties of a fragment F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"preamble"
+
+

F is a preamble fragment.

+
+
"trace-class"
+
+

F is a trace class fragment.

+
+
"clock-class"
+
+

F is a clock class fragment.

+
+
"data-stream-class"
+
+

F is a data stream class fragment.

+
+
"event-record-class"
+
+

F is a event record class fragment.

+
+
+

Yes

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

For any fragment except a preamble fragment, any +extension which exists under this property MUST also be declared in +the preamble fragment of the same metadata stream.

+

No

{}

+
+

The metadata stream is a JSON text sequence of fragments instead of a +single JSON object containing nested objects to enable real-time, or +“live”, tracing: a consumer can always decode +event records having known event record classes +while a producer can always add new event record +classes to a data stream class by appending additional +fragments to the metadata stream. Once a producer appends a fragment to +a metadata stream, the fragment is considered “frozen”, in that it +never needs to change.

+
+
+

A metadata stream:

+
+
+ +
+
+
Example 4. Partial metadata stream.
+
+
+

In the sample below, the string <RS> represents a single record +separator character (U+001E) and the string [...] represents +continuation.

+
+
+
+
<RS>{
+  "type": "preamble",
+  "version": 2
+}
+<RS>[...]
+
+
+
+
+
+ + + + + +
+ + +
+

This section doesn’t specify how a metadata stream translates into +data stream encoding and decoding rules; it only describes +objects and their properties.

+
+
+

See Data stream decoding procedure to learn how to decode a data stream.

+
+
+
+
+

5.1. UUID

+
+

Both a trace class fragment and a clock class +fragment MAY have a +UUID +property.

+
+
+

Within a metadata stream, a UUID is a JSON array of 16 JSON +integers which are the numeric values of the 16 bytes of the +UUID.

+
+
+
Example 5. e53e0ab8-50a1-4f0a-b710-b5f0bba9c4ac UUID.
+
+
+
+
[229, 62, 10, 184, 80, 161, 79, 10, 183, 16, 181, 240, 187, 169, 196, 172]
+
+
+
+
+
+
+

5.2. Extensions

+
+

A producer MAY add extensions to many metadata +stream JSON objects.

+
+
+

The purpose of an extension is to add core features to CTF 2 or to +modify existing core features, as specified by this document. In other +words, an extension MAY alter the format itself.

+
+
+

This document doesn’t specify what an extension exactly is.

+
+
+

The preamble fragment of the metadata stream contains +extension declarations:

+
+
+
    +
  • +

    Any extension in metadata stream objects MUST be declared, by +namespace and name, in the preamble fragment.

    +
    +

    Declaring an extension is said to enable it.

    +
    +
    • +
  • +

    If a consumer doesn’t support any declared +extension, it MUST NOT consume the data streams of the +trace.

    +
    +

    The consumer SHOULD report unsupported extensions as an error.

    +
    +
    • +
+
+
+

Extensions are a single JSON object, where each property is:

+
+
+ + + + + + + + + +
+Name + +

A namespace

+
+Value + +

A namespaced extensions object

+
+
+
+

A namespaced extensions object is a JSON object, where +each property is:

+
+
+ + + + + + + + + +
+Name + +

An extension name

+
+Value + +

A JSON value

+
+
+
+

The metadata stream JSON objects which MAY contain extensions as their +extensions property are:

+
+
+ +
+
+
Example 6. Three extensions under two namespaces.
+
+
+
+
{
+  "my.tracer": {
+    "piano": {
+      "keys": 88,
+      "temperament": "equal"
+    },
+    "ramen": 23
+  },
+  "abc/xyz": {
+    "sax": {
+      "variant": "alto"
+    }
+  }
+}
+
+
+
+
+
+
+

5.3. User attributes

+
+

A producer MAY add custom user attributes to many +metadata stream JSON objects.

+
+
+

This document doesn’t specify what a user attribute exactly is.

+
+
+

Unlike extensions, a consumer MUST NOT +consider user attributes to decode data streams.

+
+
+

User attributes are a single JSON object, where each property is:

+
+
+ + + + + + + + + +
+Name + +

A namespace

+
+Value + +

A JSON value

+
+
+
+

The metadata stream JSON objects which MAY contain user attributes +as their user-attributes property are:

+
+
+ +
+
+
Example 7. User attributes under two namespaces.
+
+
+
+
{
+  "my.tracer": {
+    "max-count": 45,
+    "module": "sys"
+  },
+  "abc/xyz": true
+}
+
+
+
+
+
+
+

5.4. Field classes

+
+

A field class describes fields, that is, sequences of bits +as found in a data stream.

+
+
+

A field class contains all the properties a consumer +needs to decode a given field.

+
+
+

A field is a field class instance.

+
+
+

This document specifies the following types of field classes:

+
+
+
+
Abstract field classes
+
+

One cannot use the following field classes directly: they are bases +for other, concrete field classes:

+
+ +
+
+
Fixed/static-length field classes
+
+
+ +
+
+
Variable/dynamic-length field classes
+
+
+ +
+
+
Compound field classes
+
+

The following field classes contain one or more field classes.

+
+ +
+
+
+
+
+

A field class is a JSON object; its properties depend on its type +property.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3. Common properties of a field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"fixed-length-bit-array"
+
+

F is a fixed-length bit array field class.

+
+
"fixed-length-boolean"
+
+

F is a fixed-length boolean field class.

+
+
"fixed-length-unsigned-integer"
+
"fixed-length-signed-integer"
+
+

F is a fixed-length integer field class.

+
+
"fixed-length-unsigned-enumeration"
+
"fixed-length-signed-enumeration"
+
+

F is a fixed-length enumeration field class.

+
+
"fixed-length-floating-point-number"
+
+

F is a fixed-length floating point number field class.

+
+
"variable-length-bit-array"
+
+

F is a variable-length bit array field class.

+
+
"variable-length-unsigned-integer"
+
"variable-length-signed-integer"
+
+

F is a variable-length integer field class.

+
+
"variable-length-unsigned-enumeration"
+
"variable-length-signed-enumeration"
+
+

F is a variable-length enumeration field class.

+
+
"null-terminated-string"
+
+

F is a null-terminated string field class.

+
+
"static-length-string"
+
+

F is a static-length string field class.

+
+
"static-length-blob"
+
+

F is a static-length BLOB field class.

+
+
"dynamic-length-string"
+
+

F is a dynamic-length string field class.

+
+
"dynamic-length-blob"
+
+

F is a dynamic-length BLOB field class.

+
+
"structure"
+
+

F is a structure field class.

+
+
"static-length-array"
+
+

F is a static-length array field class.

+
+
"dynamic-length-array"
+
+

F is a dynamic-length array field class.

+
+
"optional"
+
+

F is a optional field class.

+
+
"variant"
+
+

F is a variant field class.

+
+
+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+

The following fragment properties MUST have a structure field class as +their value:

+
+
+
+
Trace class fragment
+
+

packet-header-field-class

+
+
Data stream class fragment
+
+
+
    +
  • +

    packet-context-field-class

    +
    • +
  • +

    event-record-header-field-class

    +
    • +
  • +

    event-record-common-context-field-class

    +
    • +
+
+
+
Event record class fragment
+
+
+
    +
  • +

    specific-context-field-class

    +
    • +
  • +

    payload-field-class

    +
    • +
+
+
+
+
+
+

5.4.1. Field location

+
+

A field location is a means for a consumer to locate +a field which it needs to decode another, subsequent field.

+
+
+

A consumer needs to locate another field to decode instances of the +following classes:

+
+
+
+
Dynamic-length array field class
+
Dynamic-length string field class
+
Dynamic-length BLOB field class
+
+

Needs a fixed-length unsigned integer or +variable-length unsigned integer length field.

+
+
Optional field class
+
+

Needs a fixed-length boolean, fixed-length integer, or +variable-length integer selector field.

+
+
Variant field class
+
+

Needs a fixed-length integer or variable-length integer selector +field.

+
+
+
+
+

Let T be an anteriorly decoded field which a consumer needs to +decode another field S. A field location is a JSON array +where, in this order:

+
+
+
    +
  1. +

    The first element is the name (JSON string) of a root field from +where to start the lookup of T, amongst:

    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    +"packet-header" + +

    Header of the packet of S.

    +
    +"packet-context" + +

    Context of the packet of S.

    +
    +"event-record-header" + +

    Header of the event record of S.

    +
    +"event-record-common-context" + +

    Common context of the event record of S.

    +
    +"event-record-specific-context" + +

    Specific context of the event record of S.

    +
    +"event-record-payload" + +

    Payload of the event record of S.

    +
    +
    +
    +
    +
    +

    In other words, T MUST be in the same packet or event record +as S.

    +
    +
    2. +
  2. +

    The following elements are structure field member names +(JSON strings) to follow to locate the target field.

    +
    3. +
+
+
+

The length of a field location MUST be greater than or equal to two.

+
+
+

See Field location procedure to learn how to locate a field with a field +location.

+
+
+
+

5.4.2. Integer range set

+
+

An integer range set is a JSON array of integer ranges.

+
+
+

An integer range set MUST contain one or more integer ranges.

+
+
+

An integer range is a JSON array of two elements:

+
+
+
    +
  1. +

    The lower bound of the range (JSON integer, included).

    +
    2. +
  2. +

    The upper bound of the range (JSON integer, included).

    +
    3. +
+
+
+

An integer range represents all the integer values from the lower bound +of the range to its upper bound.

+
+
+

The upper bound of an integer range MUST be greater than or equal to +its lower bound.

+
+
+

If both the lower and upper bounds of an integer range are equal, then +the integer range represents a single integer value.

+
+
+
Example 8. Integer ranges.
+
+
+
+
[3, 67]
+
+
+
+
+
[-45, 101]
+
+
+
+
Single integer value.
+
+
[42, 42]
+
+
+
+
+
+
Example 9. Integer range set containing three integer ranges.
+
+
+
+
[[3, 67], [-45, 1], [42, 42]]
+
+
+
+
+
+
+

5.4.3. Roles

+
+

Some field class instances can have roles.

+
+
+

A role is specific semantics attached to the fields (instances) of a +field class. For example, the packet-magic-number role of a +fixed-length integer field class indicates that the value of its instances MUST be the +packet magic number (0xc1fc1fc1).

+
+
+

Roles are a JSON array of role names (JSON strings).

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted roles within +their root field classes.

+
+
+
+

5.4.4. Fixed-length bit array field class

+
+

A fixed-length bit array field class describes fixed-length bit array fields.

+
+
+

A fixed-length bit array field is a simple array of contiguous bits, without any +attached integer type semantics.

+
+
+

The length, or number of bits, of a fixed-length bit array field is a property +(length) of its class.

+
+
+

A fixed-length bit array field class acts as a base of a fixed-length boolean field class, a fixed-length integer field class, +and a fixed-length floating point number field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4. Common properties of a fixed-length bit array field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "fixed-length-bit-array".

+

Yes

length

JSON integer

+

Number of bits of an instance of F.

+
+
+

The value of this property MUST be greater than zero.

+

Yes

byte-order

JSON string

+

Byte order of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"big-endian"
+
+

Big-endian.

+
+
"little-endian"
+
+

Little-endian.

+
+
+

Yes

alignment

JSON integer

+

Alignment of the first bit of an instance of F +relative to the beginning of the packet which +contains this instance.

+
+
+

The value of this property MUST be a positive power of two.

+

No

1

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 10. Minimal fixed-length bit array field class.
+
+
+
+
{
+  "type": "fixed-length-bit-array",
+  "length": 16,
+  "byte-order": "little-endian"
+}
+
+
+
+
+
+
Example 11. Fixed-length bit array field class with instances aligned to 32 bits.
+
+
+
+
{
+  "type": "fixed-length-bit-array",
+  "length": 48,
+  "byte-order": "big-endian",
+  "alignment": 32
+}
+
+
+
+
+
+
Example 12. Fixed-length bit array field class with user attributes.
+
+
+
+
{
+  "type": "fixed-length-bit-array",
+  "length": 16,
+  "byte-order": "little-endian",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.5. Fixed-length boolean field class

+
+

A fixed-length boolean field class is a fixed-length bit array field class which describes fixed-length boolean +fields.

+
+
+

A fixed-length boolean field is a fixed-length bit array field which has the following semantics:

+
+
+
+
If all the bits of the bit array field are cleared (zero)
+
+

The value of the fixed-length boolean field is false.

+
+
Otherwise
+
+

The value of the fixed-length boolean field is true.

+
+
+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5. Properties of a fixed-length boolean field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "fixed-length-boolean".

+

Yes

length

JSON integer

+

Number of bits of an instance of F.

+
+
+

The value of this property MUST be greater than zero.

+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

byte-order

JSON string

+

Byte order of an instance +of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"big-endian"
+
+

Big-endian.

+
+
"little-endian"
+
+

Little-endian.

+
+
+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

alignment

JSON integer

+

Alignment of the first bit of an instance of F +relative to the beginning of the packet which +contains this instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

Property inherited from the fixed-length bit array field class.

+

No

1

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 13. Minimal fixed-length boolean field class.
+
+
+
+
{
+  "type": "fixed-length-boolean",
+  "length": 16,
+  "byte-order": "little-endian"
+}
+
+
+
+
+
+
Example 14. Fixed-length boolean field class with instances aligned to 32 bits.
+
+
+
+
{
+  "type": "fixed-length-boolean",
+  "length": 48,
+  "byte-order": "big-endian",
+  "alignment": 32
+}
+
+
+
+
+
+
Example 15. Fixed-length boolean field class with user attributes.
+
+
+
+
{
+  "type": "fixed-length-boolean",
+  "length": 16,
+  "byte-order": "little-endian",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.6. Abstract integer field class

+
+

An abstract integer field class is a base of a fixed-length integer field class and a +variable-length integer field class.

+
+
+

This field class is abstract in that it only exists to show the relation +between different integer field classes in this document: a +packet cannot contain an abstract integer field.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + +
Table 6. Common property of an integer field class F.
NameTypeDescriptionRequired?Default

preferred-display-base

JSON integer

+

Preferred base to display the value of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+ + + + + + + + + + + + + + + + + +
+2 + +

Binary base.

+
+8 + +

Octal base.

+
+10 + +

Decimal base.

+
+16 + +

Hexadecimal base.

+
+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+

No

10

+
+
+

5.4.7. Fixed-length integer field class

+
+

A fixed-length integer field class is both an abstract integer field +class and a fixed-length bit array field class which describes fixed-length integer fields.

+
+
+

A fixed-length integer field is a fixed-length bit array field which has integer semantics.

+
+
+

If the value of the type property of a fixed-length integer is +"fixed-length-signed-integer", then its instances have the two’s +complement format.

+
+
+

A fixed-length integer field class acts as a base of a fixed-length enumeration field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 7. Common properties of a fixed-length integer field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"fixed-length-unsigned-integer"
+
+

The instances of F are fixed-length unsigned integer fields.

+
+
"fixed-length-signed-integer"
+
+

The instances of F are fixed-length signed integer fields.

+
+
+

Yes

length

JSON integer

+

Number of bits of an instance of F.

+
+
+

The value of this property MUST be greater than zero.

+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

byte-order

JSON string

+

Byte order of an instance +of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"big-endian"
+
+

Big-endian.

+
+
"little-endian"
+
+

Little-endian.

+
+
+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

alignment

JSON integer

+

Alignment of the first bit of an instance of F +relative to the beginning of the packet which +contains this instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

Property inherited from the fixed-length bit array field class.

+

No

1

preferred-display-base

JSON integer

+

Preferred base to display the value of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+ + + + + + + + + + + + + + + + + +
+2 + +

Binary base.

+
+8 + +

Octal base.

+
+10 + +

Decimal base.

+
+16 + +

Hexadecimal base.

+
+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+
+
+

Property inherited from the abstract integer field class.

+

No

10

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 16. Minimal fixed-length unsigned integer field class.
+
+
+
+
{
+  "type": "fixed-length-unsigned-integer",
+  "length": 16,
+  "byte-order": "little-endian"
+}
+
+
+
+
+
+
Example 17. Fixed-length signed integer field class with instances aligned to 32 bits.
+
+
+
+
{
+  "type": "fixed-length-signed-integer",
+  "length": 48,
+  "byte-order": "big-endian",
+  "alignment": 32
+}
+
+
+
+
+
+
Example 18. Fixed-length unsigned integer field class with instances to be preferably displayed with a hexadecimal base.
+
+
+
+
{
+  "type": "fixed-length-unsigned-integer",
+  "length": 48,
+  "byte-order": "big-endian",
+  "preferred-display-base": 16
+}
+
+
+
+
+
+
Example 19. Fixed-length signed integer field class with user attributes.
+
+
+
+
{
+  "type": "fixed-length-signed-integer",
+  "length": 16,
+  "byte-order": "little-endian",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.8. Abstract enumeration field class

+
+

An abstract enumeration field class is a base of a fixed-length enumeration field class and a +variable-length enumeration field class.

+
+
+

This field class is abstract in that it only exists to show the relation +between different enumeration field classes in this document: a +packet cannot contain an abstract enumeration field.

+
+
+

An abstract enumeration field class is an abstract integer +field class.

+
+
+

An enumeration field is an integer field which MAY have one or more +associated names thanks to the mappings property of its class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8. Common property of an enumeration field class F.
NameTypeDescriptionRequired?Default

preferred-display-base

JSON integer

+

Preferred base to display the value of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+ + + + + + + + + + + + + + + + + +
+2 + +

Binary base.

+
+8 + +

Octal base.

+
+10 + +

Decimal base.

+
+16 + +

Hexadecimal base.

+
+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+
+
+

Property inherited from the abstract integer field class.

+

No

10

mappings

Enumeration field class mappings

+

Mappings of F.

+
+
+

The value of this property MUST contain one or more properties.

+

Yes

+
+
5.4.8.1. Enumeration field class mappings
+
+

Enumeration field class mappings map names to +integer range sets.

+
+
+

Enumeration field class mappings are a JSON object, where each property +is:

+
+
+ + + + + + + + + +
+Name + +

Mapping name.

+
+Value + +

Mapped ranges of integers (integer range set).

+
+
+
+

The integer ranges of two given mappings MAY overlap.

+
+
+

Enumeration field class mappings MUST contain one or more properties.

+
+
+
Example 20. Enumeration field class mappings with three mappings.
+
+
+

In this example, the fortune and building mappings overlap with the +values 4 and 5, and the building and journal mappings overlap with +the value 80.

+
+
+
+
{
+  "fortune": [[3, 67], [-45, 1], [84, 84]],
+  "building": [[4, 5], [75, 82]],
+  "journal": [[100, 2305], [80, 80]]
+}
+
+
+
+
+
+
+
+

5.4.9. Fixed-length enumeration field class

+
+

A fixed-length enumeration field class is both an abstract enumeration +field class and a fixed-length integer field class which describes fixed-length enumeration fields.

+
+
+

A fixed-length enumeration field is a fixed-length integer field which MAY have one or more +associated names thanks to the mappings property of its class.

+
+
+

If the value of the type property of a fixed-length enumeration field class is +"fixed-length-signed-enumeration", then its instances have the two’s +complement format.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9. Properties of a fixed-length enumeration field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"fixed-length-unsigned-enumeration"
+
+

The instances of F are fixed-length unsigned enumeration fields.

+
+
"fixed-length-signed-enumeration"
+
+

The instances of F are fixed-length signed enumeration fields.

+
+
+

Yes

length

JSON integer

+

Number of bits of an instance of F.

+
+
+

The value of this property MUST be greater than zero.

+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

byte-order

JSON string

+

Byte order of an instance +of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"big-endian"
+
+

Big-endian.

+
+
"little-endian"
+
+

Little-endian.

+
+
+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

alignment

JSON integer

+

Alignment of the first bit of an instance of F +relative to the beginning of the packet which +contains this instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

Property inherited from the fixed-length bit array field class.

+

No

1

preferred-display-base

JSON integer

+

Preferred base to display the value of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+ + + + + + + + + + + + + + + + + +
+2 + +

Binary base.

+
+8 + +

Octal base.

+
+10 + +

Decimal base.

+
+16 + +

Hexadecimal base.

+
+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+
+
+

Property inherited from the abstract integer field class.

+

No

10

mappings

Enumeration field class mappings

+

Mappings of F.

+
+
+

The value of this property MUST contain one or more properties.

+
+
+

Property inherited from the abstract enumeration field class.

+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 21. Minimal fixed-length unsigned enumeration field class.
+
+
+
+
{
+  "type": "fixed-length-unsigned-enumeration",
+  "length": 16,
+  "byte-order": "little-endian",
+  "mappings": {
+    "apple": [[1, 19]]
+  }
+}
+
+
+
+
+
+
Example 22. Fixed-length signed enumeration field class with instances aligned to 32 bits.
+
+
+
+
{
+  "type": "fixed-length-signed-enumeration",
+  "length": 48,
+  "byte-order": "big-endian",
+  "alignment": 32,
+  "mappings": {
+    "banana": [[-27399, -1882], [8, 199], [101, 101]],
+    "orange": [[67, 67], [43, 1534]]
+  }
+}
+
+
+
+
+
+
Example 23. Fixed-length unsigned enumeration field class with instances to be preferably displayed with a hexadecimal base.
+
+
+
+
{
+  "type": "fixed-length-unsigned-enumeration",
+  "length": 8,
+  "byte-order": "big-endian",
+  "preferred-display-base": 16,
+  "mappings": {
+    "lime": [[3, 3]],
+    "kiwi": [[8, 8]],
+    "blueberry": [[11, 11]]
+  }
+}
+
+
+
+
+
+
Example 24. Fixed-length signed enumeration field class with user attributes.
+
+
+
+
{
+  "type": "fixed-length-signed-enumeration",
+  "length": 16,
+  "byte-order": "little-endian",
+  "mappings": {
+    "mango": [[23, 42]]
+  },
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.10. Fixed-length floating point number field class

+
+

A fixed-length floating point number field class is a fixed-length bit array field class which describes fixed-length floating point number +fields.

+
+
+

A fixed-length floating point number field is a fixed-length bit array field which has floating point number +semantics.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10. Properties of a fixed-length floating point number field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be +"fixed-length-floating-point-number".

+

Yes

length

JSON integer

+

Number of bits of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
16
+
+

The instances of F are binary16 floating point numbers, +as per the IEEE 754-2008 binary interchange format.

+
+
32
+
+

The instances of F are binary32 floating point numbers.

+
+
64
+
+

The instances of F are binary64 floating point numbers.

+
+
128
+
+

The instances of F are binary128 floating point +numbers.

+
+
K, where K is greater than 128 and a multiple of 32
+
+

The instances of F are binaryK floating point +numbers.

+
+
+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

byte-order

JSON string

+

Byte order of an instance +of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"big-endian"
+
+

Big-endian.

+
+
"little-endian"
+
+

Little-endian.

+
+
+
+
+

Property inherited from the fixed-length bit array field class.

+

Yes

alignment

JSON integer

+

Alignment of the first bit of an instance of F +relative to the beginning of the packet which +contains this instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

Property inherited from the fixed-length bit array field class.

+

No

1

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 25. Minimal binary32 fixed-length floating point number field class.
+
+
+
+
{
+  "type": "fixed-length-floating-point-number",
+  "length": 32,
+  "byte-order": "little-endian"
+}
+
+
+
+
+
+
Example 26. binary64 fixed-length floating point number field class with instances aligned to 32 bits.
+
+
+
+
{
+  "type": "fixed-length-floating-point-number",
+  "length": 64,
+  "byte-order": "big-endian",
+  "alignment": 32
+}
+
+
+
+
+
+
Example 27. binary192 fixed-length floating point number field class with user attributes.
+
+
+
+
{
+  "type": "fixed-length-floating-point-number",
+  "length": 192,
+  "byte-order": "little-endian",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.11. Variable-length bit array field class

+
+

A variable-length bit array field class describes variable-length bit array fields.

+
+
+

A variable-length bit array field is a sequence of bytes with a variable +length which contains an array of bits of which the length is a multiple +of 7. A variable-length bit array field is encoded as per +LEB128.

+
+
+

A variable-length bit array field class acts as a base of a variable-length integer field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 11. Common properties of a variable-length bit array field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "variable-length-bit-array".

+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 28. Minimal variable-length bit array field class.
+
+
+
+
{
+  "type": "variable-length-bit-array"
+}
+
+
+
+
+
+
Example 29. Variable-length bit array field class with user attributes.
+
+
+
+
{
+  "type": "variable-length-bit-array",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.12. Variable-length integer field class

+
+

A variable-length integer field class is both an abstract integer field +class and a variable-length bit array field class which describes variable-length integer fields.

+
+
+

A variable-length integer field is a variable-length bit array field which has integer semantics.

+
+
+

If the value of the type property of a variable-length integer field class is +"variable-length-signed-integer", then its instances have the two’s +complement format.

+
+
+

A variable-length integer field class acts as a base of a variable-length enumeration field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 12. Common properties of a variable-length integer field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"variable-length-unsigned-integer"
+
+

The instances of F are variable-length unsigned integer fields.

+
+
"variable-length-signed-integer"
+
+

The instances of F are variable-length signed integer fields.

+
+
+

Yes

preferred-display-base

JSON integer

+

Preferred base to display the value of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+ + + + + + + + + + + + + + + + + +
+2 + +

Binary base.

+
+8 + +

Octal base.

+
+10 + +

Decimal base.

+
+16 + +

Hexadecimal base.

+
+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+
+
+

Property inherited from the abstract integer field class.

+

No

10

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 30. Minimal variable-length unsigned integer field class.
+
+
+
+
{
+  "type": "variable-length-unsigned-integer"
+}
+
+
+
+
+
+
Example 31. Variable-length signed integer field class with instances to be preferably displayed with a hexadecimal base.
+
+
+
+
{
+  "type": "variable-length-signed-integer",
+  "preferred-display-base": 16
+}
+
+
+
+
+
+
Example 32. Variable-length unsigned integer field class with user attributes.
+
+
+
+
{
+  "type": "variable-length-unsigned-integer",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.13. Variable-length enumeration field class

+
+

A variable-length enumeration field class is both an abstract enumeration +field class and a variable-length integer field class which describes variable-length enumeration fields.

+
+
+

A variable-length enumeration field is a variable-length integer field which MAY have one or more +associated names thanks to the mappings property of its class.

+
+
+

If the value of the type property of a variable-length enumeration field class is +"variable-length-signed-enumeration", then its instances have the +two’s complement format.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 13. Properties of a variable-length enumeration field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be one of:

+
+
+
+
"variable-length-unsigned-enumeration"
+
+

The instances of F are variable-length unsigned enumeration fields.

+
+
"variable-length-signed-enumeration"
+
+

The instances of F are variable-length signed enumeration fields.

+
+
+

Yes

preferred-display-base

JSON integer

+

Preferred base to display the value of an instance of F.

+
+
+

The value of this property MUST be one of:

+
+
+ + + + + + + + + + + + + + + + + +
+2 + +

Binary base.

+
+8 + +

Octal base.

+
+10 + +

Decimal base.

+
+16 + +

Hexadecimal base.

+
+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+
+
+

Property inherited from the abstract integer field class.

+

No

10

mappings

Enumeration field class mappings

+

Mappings of F.

+
+
+

The value of this property MUST contain one or more properties.

+
+
+

Property inherited from the abstract enumeration field class.

+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 33. Minimal variable-length unsigned enumeration field class.
+
+
+
+
{
+  "type": "variable-length-unsigned-enumeration",
+  "mappings": {
+    "apple": [[1, 19]]
+  }
+}
+
+
+
+
+
+
Example 34. Variable-length unsigned enumeration field class with instances to be preferably displayed with a hexadecimal base.
+
+
+
+
{
+  "type": "variable-length-unsigned-enumeration",
+  "preferred-display-base": 16,
+  "mappings": {
+    "lime": [[3, 3]],
+    "kiwi": [[8, 8]],
+    "blueberry": [[11, 11]]
+  }
+}
+
+
+
+
+
+
Example 35. Variable-length signed enumeration field class with user attributes.
+
+
+
+
{
+  "type": "variable-length-signed-enumeration",
+  "mappings": {
+    "banana": [[-27399, -1882], [8, 199], [101, 101]],
+    "orange": [[67, 67], [43, 1534]]
+  },
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.14. Null-terminated string field class

+
+

A null-terminated string field class describes null-terminated string fields.

+
+
+

A null-terminated string field is, in this order:

+
+
+
    +
  1. +

    Zero or more contiguous non-null (non-zero) bytes which form a +UTF-8-encoded string.

    +
    2. +
  2. +

    One null (zero) byte.

    +
    3. +
+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 14. Properties of a null-terminated string field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "null-terminated-string".

+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 36. Minimal null-terminated string field class.
+
+
+
+
{
+  "type": "null-terminated-string"
+}
+
+
+
+
+
+
Example 37. Null-terminated string field class with user attributes.
+
+
+
+
{
+  "type": "null-terminated-string",
+  "user-attributes": {
+    "my.tracer": {
+      "is-nice": true
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.15. Static-length string field class

+
+

A static-length string field class describes static-length string fields.

+
+
+

A static-length string field is a sequence of zero or more contiguous +bytes. All the bytes of a static-length string before the first null (zero) byte, if +any, form a UTF-8-encoded string. All the bytes after the first null +(zero) byte, if any, are padding (garbage data).

+
+
+

The length, or number of bytes, of a static-length string field is a property +(length) of its class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 15. Properties of a static-length string field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "static-length-string".

+

Yes

length

JSON integer

+

Number of bytes contained in an instance of F.

+
+
+

The value of this property MUST be greater than or equal to zero.

+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 38. Empty static-length string field class.
+
+
+
+
{
+  "type": "static-length-string",
+  "length": 0
+}
+
+
+
+
+
+
Example 39. Static-length string field class with instances having 100 bytes.
+
+
+
+
{
+  "type": "static-length-string",
+  "length": 100
+}
+
+
+
+
+
+
Example 40. Static-length string field class with user attributes.
+
+
+
+
{
+  "type": "static-length-string",
+  "length": 13,
+  "user-attributes": {
+    "my.tracer": null
+  }
+}
+
+
+
+
+
+
+

5.4.16. Dynamic-length string field class

+
+

A dynamic-length string field class describes dynamic-length string fields.

+
+
+

A dynamic-length string field is a sequence of zero or more contiguous +bytes. All the bytes of a dynamic-length string before the first null (zero) byte, if +any, form a UTF-8-encoded string. All the bytes after the first null +(zero) byte, if any, are padding (garbage data).

+
+
+

The length, or number of bytes, of a dynamic-length string field is the value of +another, anterior (already encoded/decoded) length field. A +consumer can locate this length field thanks to the +length-field-location property of the dynamic-length string field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 16. Properties of a dynamic-length string field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "static-length-string".

+

Yes

length-field-location

Field location

+

Location of the field of which the value is the number of bytes +contained in an instance of F.

+
+
+

The class of the length field MUST be one of:

+
+
+ +

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 41. Dynamic-length string field class.
+
+
+
+
{
+  "type": "dynamic-length-string",
+  "length-field-location": ["event-record-payload", "length"]
+}
+
+
+
+
+
+
Example 42. Dynamic-length string field class with user attributes.
+
+
+
+
{
+  "type": "dynamic-length-string",
+  "length-field-location": ["event-record-common-context", "name-length"],
+  "user-attributes": {
+    "my.tracer": 177
+  }
+}
+
+
+
+
+
+
+

5.4.17. Abstract BLOB field class

+
+

An abstract BLOB +field class is a base of a static-length BLOB field class and a dynamic-length BLOB field class.

+
+
+

This field class is abstract in that it only exists to show the relation +between different BLOB field classes in this document: a packet +cannot contain an abstract BLOB field.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + +
Table 17. Common properties of a BLOB field class F.
NameTypeDescriptionRequired?Default

media-type

JSON string

+

IANA +media type of an instance of F.

+

No

"application/octet-stream"

+
+
+

5.4.18. Static-length BLOB field class

+
+

A static-length BLOB field class is an abstract BLOB field class +which describes static-length BLOB fields.

+
+
+

A static-length BLOB field is a sequence of zero or more contiguous +bytes with an associated IANA media type (given by the media-type +property of its class).

+
+
+

The length, or number of bytes, of a static-length BLOB field is a property +(length) of its class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 18. Properties of a static-length BLOB field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "static-length-blob".

+

Yes

length

JSON integer

+

Number of bytes contained in an instance of F.

+
+
+

The value of this property MUST be greater than or equal to zero.

+

Yes

media-type

JSON string

+

IANA +media type of an instance of F.

+
+
+

Property inherited from the abstract BLOB field class.

+

No

"application/octet-stream"

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 43. Empty static-length BLOB field class with instances having a default IANA media type.
+
+
+
+
{
+  "type": "static-length-blob",
+  "length": 0
+}
+
+
+
+
+
+
Example 44. Static-length TIFF BLOB field class with instances having 511,267 bytes.
+
+
+
+
{
+  "type": "static-length-blob",
+  "length": 511267,
+  "media-type": "image/tif"
+}
+
+
+
+
+
+
Example 45. Static-length CSV BLOB field class with user attributes.
+
+
+
+
{
+  "type": "static-length-blob",
+  "length": 2400,
+  "media-type": "text/csv",
+  "user-attributes": {
+    "my.tracer": {
+      "csv-cols": 12
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.19. Dynamic-length BLOB field class

+
+

A dynamic-length BLOB field class is an abstract BLOB field class +which describes dynamic-length BLOB fields.

+
+
+

A dynamic-length BLOB field is a sequence of zero or more contiguous +bytes with an associated IANA media type.

+
+
+

The length, or number of bytes, of a dynamic-length BLOB field is the value of +another, anterior (already encoded/decoded) length field. A +consumer can locate this length field thanks to the +length-field-location property of the dynamic-length BLOB field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 19. Properties of a dynamic-length BLOB field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "dynamic-length-blob".

+

Yes

length-field-location

Field location

+

Location of the field of which the value is the number of bytes +contained in an instance of F.

+
+
+

The class of the length field MUST be one of:

+
+
+ +

Yes

media-type

JSON string

+

IANA +media type of an instance of F.

+
+
+

Property inherited from the abstract BLOB field class.

+

No

"application/octet-stream"

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 46. Dynamic-length BLOB field class with instances having a default IANA media type.
+
+
+
+
{
+  "type": "dynamic-length-blob",
+  "length-field-location": ["event-record-payload", "length"]
+}
+
+
+
+
+
+
Example 47. Dynamic-length JPEG BLOB field class with user attributes.
+
+
+
+
{
+  "type": "dynamic-length-blob",
+  "length-field-location": ["event-record-common-context", "length"],
+  "media-type": "image/jpeg",
+  "user-attributes": {
+    "my.tracer": {
+      "quality": 85
+    }
+  }
+}
+
+
+
+
+
+
+

5.4.20. Structure field class

+
+

A structure field class describes structure fields.

+
+
+

A structure field is a sequence of zero or more structure +field members. A structure field member is a named field.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 20. Properties of a structure field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "structure".

+

Yes

member-classes

JSON array of structure field member classes

+

Classes of the members of an instance of F.

+
+
+

The name property of each member class MUST be unique within the +member class names of F.

+

No

[]

minimum-alignment

JSON integer

+

Minimum alignment of the first bit of an instance of F +relative to the beginning of the packet which contains this +instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

The effective alignment of the first bit of an instance +of F MAY be greater than the value of this property.

+

No

1

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 48. Empty structure field class: instances have no members.
+
+
+
+
{
+  "type": "structure"
+}
+
+
+
+
+
+
Example 49. Structure field class with three member classes.
+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "Villeray",
+      "field-class": {
+        "type": "null-terminated-string"
+      }
+    },
+    {
+      "name": "Berri",
+      "field-class": {
+        "type": "fixed-length-unsigned-integer",
+        "length": 32,
+        "byte-order": "little-endian",
+        "preferred-display-base": 2
+      },
+      "user-attributes": {
+        "my.tracer": {
+          "is-mask": true
+        }
+      }
+    },
+    {
+      "name": "Faillon",
+      "field-class": {
+        "type": "fixed-length-boolean",
+        "length": 8,
+        "byte-order": "little-endian"
+      }
+    }
+  ]
+}
+
+
+
+
+
+
Example 50. Structure field class with instances minimally aligned to 64 bits.
+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "St-Denis",
+      "field-class": {
+        "type": "null-terminated-string"
+      }
+    },
+    {
+      "name": "Lajeunesse",
+      "field-class": {
+        "type": "fixed-length-unsigned-integer",
+        "length": 32,
+        "byte-order": "big-endian",
+        "alignment": 32
+      }
+    }
+  ],
+  "minimum-alignment": 64
+}
+
+
+
+
+
+
Example 51. Structure field class with user attributes.
+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "Henri-Julien",
+      "field-class": {
+        "type": "fixed-length-signed-integer",
+        "length": 48,
+        "byte-order": "little-endian"
+      }
+    },
+    {
+      "name": "Casgrain",
+      "field-class": {
+        "type": "static-length-string",
+        "length": 32
+      }
+    }
+  ],
+  "user-attributes": {
+    "my.tracer": {
+      "version": 4
+    }
+  }
+}
+
+
+
+
+
+
5.4.20.1. Structure field member class
+
+

A structure field member class describes structure field members.

+
+
+

A structure field member class is a JSON object.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 21. Properties of a structure field member class M.
NameTypeDescriptionRequired?Default

name

JSON string

+

Name of M.

+

Yes

field-class

Field class

+

Field class of M.

+

Yes

user-attributes

User attributes

+

User attributes of M.

+

No

{}

extensions

Extensions

+

Extensions of M.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 52. Null-terminated string field class member class named cat.
+
+
+
+
{
+  "name": "cat",
+  "field-class": {
+    "type": "null-terminated-string"
+  }
+}
+
+
+
+
+
+
Example 53. Variable-length signed integer field class member class named dog with user attributes.
+
+
+
+
{
+  "name": "dog",
+  "field-class": {
+    "type": "variable-length-signed-integer",
+    "preferred-display-base": 8
+  },
+  "user-attributes": {
+    "my.tracer": {
+      "uuid": [
+        243, 97, 0, 184, 236, 54, 72, 97,
+        141, 107, 169, 214, 171, 137, 115, 201
+      ],
+      "is-pid": true
+    }
+  }
+}
+
+
+
+
+
+
+
+

5.4.21. Abstract array field class

+
+

An abstract array field class is a base of a static-length array field class and a +dynamic-length array field class.

+
+
+

This field class is abstract in that it only exists to show the relation +between different array field classes in this document: a packet +cannot contain an abstract array field.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 22. Common properties of an array field class F.
NameTypeDescriptionRequired?Default

element-field-class

Field class

+

Class of the element fields contained in an instance of F.

+

Yes

minimum-alignment

JSON integer

+

Minimum alignment of the first bit of an instance of F +relative to the beginning of the packet which contains this +instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

The effective alignment of the first bit of an instance +of F MAY be greater than the value of this property.

+

No

1

+
+
+

5.4.22. Static-length array field class

+
+

A static-length array field class is an abstract array field class +which describes static-length array fields.

+
+
+

A static-length array field is a sequence of zero or more element fields.

+
+
+

The length, or number of element fields, of a static-length array field is a +property (length) of its class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 23. Properties of a static-length array field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "static-length-array".

+

Yes

element-field-class

Field class

+

Class of the element fields contained in an instance of F.

+
+
+

Property inherited from the abstract array field class.

+

Yes

minimum-alignment

JSON integer

+

Minimum alignment of the first bit of an instance of F +relative to the beginning of the packet which contains this +instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

The effective alignment of the first bit of an instance +of F MAY be greater than the value of this property.

+
+
+

Property inherited from the abstract array field class.

+

No

1

length

JSON integer

+

Number of element fields contained in an instance of F.

+
+
+

The value of this property MUST be greater than or equal to zero.

+

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 54. Empty static-length array field class.
+
+
+
+
{
+  "type": "static-length-array",
+  "element-field-class": {
+    "type": "fixed-length-signed-integer",
+    "length": 16,
+    "byte-order": "little-endian",
+    "alignment": 16
+  },
+  "length": 0
+}
+
+
+
+
+
+
Example 55. Static-length array field class with instances having 100 null-terminated string fields.
+
+
+
+
{
+  "type": "static-length-array",
+  "element-field-class": {
+    "type": "null-terminated-string"
+  },
+  "length": 100
+}
+
+
+
+
+
+
Example 56. Static-length array field class with user attributes.
+
+
+
+
{
+  "type": "static-length-array",
+  "element-field-class": {
+    "type": "variable-length-unsigned-integer"
+  },
+  "length": 13,
+  "user-attributes": {
+    "my.tracer": true
+  }
+}
+
+
+
+
+
+
Example 57. Static-length array field class with instances minimally aligned to 32 bits.
+
+
+

With the following static-length array field class, a producer +can write a single 32-bit-aligned, 32-bit little-endian integer value, +and have consumers decode it as +an array of 32 flags (booleans).

+
+
+
+
{
+  "type": "static-length-array",
+  "length": 32,
+  "minimum-alignment": 32,
+  "element-field-class": {
+    "type": "fixed-length-boolean",
+    "length": 1,
+    "byte-order": "little-endian"
+  }
+}
+
+
+
+
+
+
+

5.4.23. Dynamic-length array field class

+
+

A dynamic-length array field class is an abstract array field class +which describes dynamic-length array fields.

+
+
+

A dynamic-length array field is a sequence of zero or more element fields.

+
+
+

The length, or number of element fields, of a dynamic-length array field is the +value of another, anterior (already encoded/decoded) length field. A +consumer can locate this length field thanks to the +length-field-location property of the dynamic-length array field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 24. Properties of a dynamic-length array field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "dynamic-length-array".

+

Yes

element-field-class

Field class

+

Class of the element fields contained in an instance of F.

+
+
+

Property inherited from the abstract array field class.

+

Yes

minimum-alignment

JSON integer

+

Minimum alignment of the first bit of an instance of F +relative to the beginning of the packet which contains this +instance.

+
+
+

The value of this property MUST be a positive power of two.

+
+
+

The effective alignment of the first bit of an instance +of F MAY be greater than the value of this property.

+
+
+

Property inherited from the abstract array field class.

+

No

1

length-field-location

Field location

+

Location of the field of which the value is the number of element +fields contained in an instance of F.

+
+
+

The class of the length field MUST be one of:

+
+
+ +

Yes

roles

Roles

+

Roles of an instance of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 58. Dynamic-length array field class.
+
+
+
+
{
+  "type": "dynamic-length-array",
+  "element-field-class": {
+    "type": "fixed-length-unsigned-integer",
+    "length": 32,
+    "byte-order": "big-endian",
+    "alignment": 16
+  },
+  "length-field-location": ["event-record-payload", "length"]
+}
+
+
+
+
+
+
Example 59. Dynamic-length array field class with user attributes.
+
+
+
+
{
+  "type": "dynamic-length-array",
+  "element-field-class": {
+    "type": "variable-length-unsigned-integer"
+  },
+  "length-field-location": ["packet-context", "common-length"],
+  "user-attributes": {
+    "my.tracer": 177
+  }
+}
+
+
+
+
+
+
+

5.4.24. Optional field class

+
+

An optional field class describes optional fields.

+
+
+

An optional field is, depending on the value of another, anterior +(already encoded/decoded) selector field, one of:

+
+
+
    +
  • +

    An instance of a given field class (field-class property of the +optional field class).

    +
    +

    In this case, the optional field is said to be enabled.

    +
    +
    • +
  • +

    A zero-bit field (no field).

    +
    +

    In this case, the optional field is said to be disabled.

    +
    +
    • +
+
+
+

A consumer can locate the selector field thanks to the +selector-field-location property of the optional field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 25. Properties of an optional field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "optional".

+

Yes

field-class

Field class

+

Class of an instance of F when it’s enabled.

+

Yes

selector-field-location

Field location

+

Location of the field of which the value indicates whether or not an +instance of F is enabled.

+
+
+

A selector field S MUST be an instance of one of:

+
+
+
+
Fixed-length boolean field class
+
+

An instance of F is enabled when S is +true.

+
+
Fixed-length integer field class
+
Variable-length integer field class
+
+

An instance of F is enabled when the value +of S is an element of any of the integer ranges of the +selector-field-ranges property of F.

+
+
+
+
+

For a given instance of F, the type property of the +classes of all the possible selector fields MUST be +one of:

+
+
+ +

Yes

selector-field-ranges

Integer range set

+

Ranges of integers which the value of a selector field MUST be an +element of to enable an instance of F.

+

Yes, if the selector field is an instance of a fixed-length integer field class +or a variable-length integer field class.

None if the selector field is an instance of a fixed-length boolean field class.

roles

Roles

+

Roles of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 60. Optional static-length array field class with a boolean selector field class.
+
+
+
+
{
+  "type": "optional",
+  "selector-field-location": ["event-record-payload", "has-ip"],
+  "field-class": {
+    "type": "static-length-array",
+    "element-field-class": {
+      "type": "fixed-length-unsigned-integer",
+      "length": 8,
+      "byte-order": "little-endian",
+      "alignment": 8
+    },
+    "length": 16
+  }
+}
+
+
+
+
+
+
Example 61. Optional null-terminated string with a fixed-length signed integer selector field class.
+
+
+
+
{
+  "type": "optional",
+  "selector-field-location": ["event-record-payload", "has-ip"],
+  "selector-field-ranges": [[-12, -12], [-5, 0], [15, 35]],
+  "field-class": {
+    "type": "null-terminated-string"
+  }
+}
+
+
+
+
+
+
+

5.4.25. Variant field class

+
+

A variant field class describes variant fields.

+
+
+

A variant field is, depending on the value of another, anterior (already +encoded/decoded) selector field, the instance of a specific, effective +field class amongst one or more variant field class options.

+
+
+

A consumer can locate the selector field thanks to the +selector-field-location property of the variant field class.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 26. Properties of a variant field class F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "variant".

+

Yes

options

JSON array of variant field class options

+

Options containing the possible effective classes of an instance +of F.

+
+
+

This array MUST contain one or more elements.

+
+
+

The name property of each option, if it’s set, MUST be unique within +the option names of F.

+
+
+

The integer ranges (selector-field-ranges property) of two given +options MUST NOT intersect.

+

Yes

selector-field-location

Field location

+

Location of the field of which the value indicates which option +of F contains the effective class of an instance +of F.

+
+
+

For a given instance of F, the type property of the +classes of all the possible selector fields MUST be +one of:

+
+
+ +

Yes

roles

Roles

+

Roles of F.

+
+
+

See Trace class fragment and Data stream class fragment which indicate accepted within their +root field classes.

+

No

[]

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 62. Variant field class with two options.
+
+
+
+
{
+  "type": "variant",
+  "selector-field-location": ["event-record-payload", "sel"],
+  "options": [
+    {
+      "selector-field-ranges": [[5, 5]],
+      "field-class": {
+        "type": "null-terminated-string"
+      }
+    },
+    {
+      "selector-field-ranges": [[8, 8]],
+      "field-class": {
+        "type": "fixed-length-signed-integer",
+        "length": 16,
+        "byte-order": "little-endian",
+        "preferred-display-base": 8
+      }
+    }
+  ]
+}
+
+
+
+
+
+
Example 63. Variant field class within an optional field class which share the same selector field location.
+
+
+

This example shows that an optional field class and a contained variant +field class MAY share the same selector field location.

+
+
+

In this example, depending on the value of the selector field:

+
+
+ + + + + + + + + + + + + +
+0 + +

The optional field is not enabled.

+
+1 + +

The optional field is enabled and is a variant field.

+
+

The variant field is an instance of a null-terminated string field class (effective class).

+
+
+2 + +

The optional field is enabled and is a variant field.

+
+

The variant field is an instance of a variable-length signed integer field class (effective class).

+
+
+
+
+
+
{
+  "type": "optional",
+  "selector-field-location": ["event-record-payload", "sel"],
+  "selector-field-ranges": [[1, 255]],
+  "field-class": {
+    "type": "variant",
+    "selector-field-location": ["event-record-payload", "sel"],
+    "options": [
+      {
+        "selector-field-ranges": [[1, 1]],
+        "field-class": {
+          "type": "null-terminated-string"
+        }
+      },
+      {
+        "selector-field-ranges": [[2, 2]],
+        "field-class": {
+          "type": "variable-length-signed-integer",
+          "preferred-display-base": 16
+        }
+      }
+    ]
+  }
+}
+
+
+
+
+
+
Example 64. Variant field class with user attributes.
+
+
+
+
{
+  "type": "variant",
+  "selector-field-location": ["event-record-specific-context", "sel"],
+  "options": [
+    {
+      "selector-field-ranges": [[5, 5], [10, 10], [15, 15]],
+      "field-class": {
+        "type": "static-length-string",
+        "length": 20
+      }
+    },
+    {
+      "selector-field-ranges": [[0, 4], [6, 9], [11, 14], [16, 127]],
+      "field-class": {
+        "type": "fixed-length-floating-point-number",
+        "length": 32,
+        "byte-order": "big-endian"
+      }
+    }
+  ],
+  "user-attributes": {
+    "my.tracer": {
+      "owner": "Jimmy",
+      "id": 199990
+    }
+  }
+}
+
+
+
+
+
+
5.4.25.1. Variant field class option
+
+

A variant field class option contains a possible effective class of a +variant field.

+
+
+

A variant field class option O also contains the ranges of +integer values (selector-field-ranges property) of which the value of +a selector field MUST be an element of for the effective class of a +variant field to be the field class of O.

+
+
+

A variant field class option is a JSON object.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 27. Properties of a variant field class option O contained in a variant field class F.
NameTypeDescriptionRequired?Default

field-class

Field class

+

Field class of O.

+

Yes

selector-field-ranges

Integer range set

+

Ranges of integers which the value of a selector field MUST be an +element of for the effective class of an instance of F +to be the field class (field-class property) of O.

+

Yes

name

JSON string

+

Name of O.

+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode an instance of F.

+

No

O is unnamed

user-attributes

User attributes

+

User attributes of O.

+

No

{}

extensions

Extensions

+

Extensions of O.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+
Example 65. Unnamed null-terminated string field class option.
+
+
+
+
{
+  "field-class": {
+    "type": "null-terminated-string"
+  },
+  "selector-field-ranges": [[3, 9]]
+}
+
+
+
+
+
+
Example 66. Variable-length signed integer field class option named juice with user attributes.
+
+
+
+
{
+  "name": "juice",
+  "field-class": {
+    "type": "variable-length-signed-integer",
+    "preferred-display-base": 16
+  },
+  "selector-field-ranges": [[-4, 4], [9, 9], [100, 200]],
+  "user-attributes": {
+    "my.tracer": {
+      "uuid": [
+        243, 97, 0, 184, 236, 54, 72, 97,
+        141, 107, 169, 214, 171, 137, 115, 201
+      ],
+      "is-did": true
+    }
+  }
+}
+
+
+
+
+
+
+
+
+

5.5. Preamble fragment

+
+

A preamble fragment indicates:

+
+
+
    +
  • +

    The CTF 2 major version (2).

    +
    +

    CTF 2 doesn’t have a minor version: users can use +user attributes and extensions to add +features to, or change features of, the format which this document +specifies.

    +
    +
    • +
  • +

    Extension declarations.

    +
    +

    An extension declaration is an initial extension of which the purpose is +to declare that it’s enabled within the metadata +stream.

    +
    +
    +

    Because an extension MAY alter the CTF 2 format itself, and because a +preamble fragment is always the first metadata stream fragment, those +extension declarations make it possible for a consumer +to gracefully decline the data streams of the trace if it doesn’t +support any declared extension.

    +
    +
    • +
+
+
+

The first fragment of a metadata stream MUST be a preamble fragment.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 28. Properties of a preamble fragment F.
NameTypeDescriptionRequired?Default

type

JSON string

Type of F.

+

The value of this property MUST be "preamble".

Yes

version

JSON integer

CTF 2 major version.

+

The value of this property MUST be 2.

Yes

user-attributes

User attributes

User attributes of F.

No

{}

extensions

Extensions

Extension declarations of F.

+

The name of each property is a namespace and its value is a +namespaced extensions object.

+

Within a namespaced extensions object, an extension +named N is declared when it exists as a property +named N, whatever the value of the property.

No

{}

+
+
Example 67. Minimal preamble fragment.
+
+
+
+
{
+  "type": "preamble",
+  "version": 2
+}
+
+
+
+
+
+
Example 68. Preamble fragment with extension declarations.
+
+
+

The following preamble fragment declares the piano and ramen +extensions under the my.tracer namespace.

+
+
+
+
{
+  "type": "preamble",
+  "version": 2,
+  "extensions": {
+    "my.tracer": {
+      "piano": {
+        "keys": 88,
+        "temperament": "equal"
+      },
+      "ramen": null
+    }
+  }
+}
+
+
+
+
+
+
+

5.6. Trace class fragment

+
+

A trace class describes traces.

+
+
+

Within a metadata stream, a trace class fragment MUST occur, if any, +before any data stream class fragment.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 29. Properties of a trace class fragment F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "trace-class".

+

Yes

uuid

UUID

+

UUID of F.

+

No

F has no UUID

packet-header-field-class

Structure field class

+

Class of all the packet header fields of an instance +of F.

+
+
+

Any field class as the value of this property MUST satisfy at least +one of:

+
+
+ +

No

F has no packet header field class

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+

5.6.1. Roles

+
+

If the packet-header-field-class property of a +trace class fragment exists, then the field classes of its +member classes MAY have the following +roles:

+
+ + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 30. Roles of field classes of the member classes of a packet header field class.
NameDescriptionField class (F) constraintsOther constraints

packet-magic-number

Packet magic number.

+

The purpose of a packet magic number field is to confirm the beginning +of a CTF 2 packet.

+

Fixed-length unsigned integer field class with the following property value:

+
+
+ + + + + +
+length + +

32

+
+
+

An instance of F MUST be the first member of the packet +header structure field.

+
+
+

The value of an instance of F value MUST be 0xc1fc1fc1 +(3254525889).

+

trace-class-uuid

Trace class UUID.

+

The purpose of a trace class UUID field is to confirm the association +between a data stream and a metadata +stream.

+

Static-length BLOB field class with the following property value:

+
+
+ + + + + +
+length + +

16

+
+
+

The uuid property of the trace class MUST exist.

+
+
+

The 16 bytes of an instance of F MUST be equal to the +16 JSON integers of the uuid property of the trace class.

+

data-stream-class-id

Data stream class ID.

+

The purpose of a data stream class ID field is to set the current ID of +the class of the data stream of the current packet.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+

data-stream-id

Data stream ID.

+

The purpose of a data stream ID field is to set the current ID of +the data stream of the current packet.

+

Combined with the ID of its class, such a field makes it possible to +uniquely identify a data stream within a trace.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+
+
Example 69. Trace class fragment.
+
+
+
+
{
+  "type": "trace-class",
+  "uuid": [
+    30, 201, 100, 148, 228, 2, 69, 70,
+    147, 219, 233, 34, 43, 238, 108, 199
+  ],
+  "packet-header-field-class": {
+    "type": "structure",
+    "member-classes": [
+      {
+        "name": "the magic!",
+        "field-class": {
+          "type": "fixed-length-unsigned-integer",
+          "length": 32,
+          "byte-order": "little-endian",
+          "preferred-display-base": 16,
+          "roles": ["packet-magic-number"]
+        }
+      },
+      {
+        "name": "the UUID",
+        "field-class": {
+          "type": "static-length-blob",
+          "length": 16,
+          "roles": ["trace-class-uuid"]
+        }
+      },
+      {
+        "name": "my data stream class ID",
+        "field-class": {
+          "type": "fixed-length-unsigned-integer",
+          "length": 8,
+          "byte-order": "little-endian",
+          "roles": ["data-stream-class-id"]
+        }
+      },
+      {
+        "name": "my data stream ID",
+        "field-class": {
+          "type": "variable-length-unsigned-integer",
+          "roles": ["data-stream-id"]
+        }
+      }
+    ]
+  }
+}
+
+
+
+
+
+
+
+

5.7. Clock class fragment

+
+

A clock class describes clocks.

+
+
+

A data stream MAY have a default clock.

+
+
+

Within a metadata stream, a clock class fragment MUST occur before any +data stream class fragment which refers to it by name with +its default-clock-class-name property.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 31. Properties of a clock class fragment F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "clock-class".

+

Yes

frequency

JSON integer

+

Frequency of an instance of F (Hz).

+
+
+

The value of this property MUST be greater than zero.

+

Yes

name

JSON string

+

Name of F.

+

Yes

description

JSON string

+

Textual description of F.

+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode data streams.

+

No

F has no textual description

uuid

UUID

+

UUID of F.

+
+
+

This property exists to remain backward compatible with CTF 1: +it’s not strictly needed to decode data streams.

+

No

F has no UUID

origin-is-unix-epoch

JSON boolean

+

Whether or not the origin of an instance of F is +the Unix epoch.

+
+
+

If the value of this property is false, then the origin of +an instance of F is unknown.

+

No

true

offset

Clock offset

+

Offset of an instance of F relative to its origin.

+
+
+

Let:

+
+
+
    +
  1. +

    H be the value of the frequency property of F.

    +
    2. +
  2. +

    O be the value of this property.

    +
    3. +
  3. +

    S be the value of the seconds property of O.

    +
    4. +
  4. +

    C be the value of the cycles property of O.

    +
    5. +
+
+
+

Then the effective offset of an instance of F, in clock +cycles, +is S Ãƒâ€” H + C.

+

No

{"seconds": 0, "cycles": 0}

precision

JSON integer

+

Precision of an instance of F (clock cycles).

+
+
+

The value of this property MUST be greater than or equal to zero.

+
+
+

Let P be the value of this property and V +the value of an instance of F: the range of possible +values of the instance +is [V Ã¢Ë†â€™ P, V + P].

+

No

0

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+

Within a metadata stream, two given clock class fragments MUST NOT:

+
+
+
    +
  • +

    Share the same name property value.

    +
    • +
  • +

    Share the same uuid property value.

    +
    • +
+
+
+
Example 70. Minimal clock class fragment with 1-GHz instances.
+
+
+
+
{
+  "type": "clock-class",
+  "name": "my clock class",
+  "frequency": 1000000000
+}
+
+
+
+
+
+
Example 71. Clock class fragment with a UUID property.
+
+
+
+
{
+  "type": "clock-class",
+  "name": "my clock class",
+  "frequency": 1000000000,
+  "uuid": [
+    116, 210, 0, 140, 239, 255, 77, 3,
+    129, 99, 233, 226, 134, 106, 207, 32
+  ]
+}
+
+
+
+
+
+
Example 72. Clock class fragment with instances having a specific offset.
+
+
+
+
{
+  "type": "clock-class",
+  "name": "my clock class",
+  "frequency": 1000000000,
+  "offset": {
+    "seconds": 1605112699,
+    "cycles": 2878388
+  }
+}
+
+
+
+
+
+
Example 73. Clock class fragment with instances having a specific precision.
+
+
+
+
{
+  "type": "clock-class",
+  "name": "my clock class",
+  "frequency": 8000000,
+  "precision": 100
+}
+
+
+
+
+
+
Example 74. Clock class fragment with instances having an origin which isn’t the Unix epoch.
+
+
+
+
{
+  "type": "clock-class",
+  "name": "my clock class",
+  "frequency": 1000000000,
+  "origin-is-unix-epoch": false
+}
+
+
+
+
+
+
Example 75. Clock class fragment with user attributes.
+
+
+
+
{
+  "type": "clock-class",
+  "name": "my clock class",
+  "frequency": 16000000,
+  "user-attributes": {
+    "my.tracer": {
+      "sys-name": "SOC23",
+      "bus": {
+        "name": "LMB5",
+        "index": 5
+      },
+      "propagation-delay-ps": 177
+    }
+  }
+}
+
+
+
+
+
+

5.7.1. Clock offset

+
+

A clock offset contains the offset of the instances of a +clock class relative to their origin.

+
+
+

A clock offset is a JSON object.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 32. Properties of a clock offset contained in a clock class fragment F.
NameTypeDescriptionRequired?Default

seconds

JSON integer

Offset, in seconds, of an instance of F relative to its +origin.

No

0

cycles

JSON integer

Offset, in cycles, of an instance of F relative to its +origin.

+

The value of this property MUST be greater than or equal to zero.

+

The value of this property MUST be less than the value of the +frequency property of F.

No

0

+
+
Example 76. Minimal clock offset.
+
+
+
+
{}
+
+
+
+
+
+
Example 77. Clock offset with seconds and cycles.
+
+
+
+
{
+  "seconds": 1605112699,
+  "cycles": 2878388
+}
+
+
+
+
+
+
Example 78. Clock offset with seconds only.
+
+
+
+
{
+  "seconds": 1605111293
+}
+
+
+
+
+
+
Example 79. Negative clock offset.
+
+
+

This example shows that a clock offset MAY be negative, that is, +before the origin of the clock.

+
+
+
+
{
+  "seconds": -18003,
+  "cycles": 11928547
+}
+
+
+
+
+
+
+
+

5.8. Data stream class fragment

+
+

A data stream class describes data streams.

+
+
+

Within a metadata stream, a data stream class fragment F MUST +occur before any event record class fragment of +which F is the parent.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 33. Properties of a data stream class fragment F.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "data-stream-class".

+

Yes

id

JSON integer

+

Numeric ID of F.

+
+
+

The value of this property MUST be greater than or equal to zero.

+

No

0

name

JSON string

+

Name of F.

+
+
+

The purpose of this property, combined with the namespace property, is +to uniquely identify a data stream class amongst many +producers.

+

No

F is unnamed

namespace

JSON string

+

Namespace of F.

+
+
+

The purpose of this property, combined with the name property, is to +uniquely identify a data stream class amongst many +producers.

+

No

F has no namespace

default-clock-class-name

JSON string

+

Name of the class of the default clock of an +instance of F.

+
+
+

Within the metadata stream containing F, the clock +class fragment which has the value of this property as its name +property MUST occur before F.

+

No

An instance of F has no default clock

packet-context-field-class

Structure field class

+

Class of all the packet context fields of an instance +of F.

+

No

F has no packet context field class

event-record-header-field-class

Structure field class

+

Class of all the event record header fields of an +instance of F.

+
+
+

Any field class as the value of this property MUST satisfy at least +one of:

+
+
+ +

No

F has no event record header field class

event-record-common-context-field-class

Structure field class

+

Class of all the event record common context fields +of an instance of F.

+

No

F has no event record common context field class

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+

Within a metadata stream, two given data stream class fragments +MUST NOT share the same id property value.

+
+
+

5.8.1. Roles

+
+

If the packet-context-field-class property of a data +stream class fragment exists, then the field classes of its +member classes MAY have the following +roles:

+
+ + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 34. Roles of field classes of the member classes of a packet context field class.
NameDescriptionField class (F) constraintsOther constraints

packet-total-size

Total size (bits) of the packet.

+

This size includes any padding after the packet contents.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+

The value of an instance of F MUST be greater than or +equal to the value of an instance of a field class having the +packet-content-size role, if any, within the same packet context +field.

+

packet-content-size

Content size (bits) of the packet.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+

The value of an instance of F MUST be less than or equal +to the value of an instance of a field class having the +packet-total-size role, if any, within the same packet context +field.

+

packet-beginning-default-clock-timestamp

Timestamp of the default clock of the data stream +when the packet begins.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+

The timestamps of all the event records of the packet MUST be +greater than or equal to the value of an instance of F.

+
+
+

The value of an instance of F MUST be less than or equal to +the value of an instance of a field class having the +packet-end-default-clock-timestamp role, if any, within the same +packet context field.

+

packet-end-default-clock-timestamp

Timestamp of the default clock of the data stream when the packet ends.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+

The timestamps of all the event records of the packet MUST be +less than or equal to the value of an instance of F.

+
+
+

The value of an instance of F MUST be greater than or equal +to the value of an instance of a field class having the +packet-beginning-default-clock-timestamp role, if any, within the +same packet context field.

+

discarded-event-record-counter-snapshot

Snapshot of the discarded event record counter of +the data stream when the packet ends.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+

packet-sequence-number

Sequence number of the packet within its data stream.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+
+

If the event-record-header-field-class property of +a data stream class fragment exists, then the field classes of +its member classes MAY have the following +roles:

+
+ + +++++ + + + + + + + + + + + + + + + + + + + +
Table 35. Roles of field classes of the member classes of an event record header field class.
NameDescriptionField class (F) constraints

event-record-class-id

Event record class ID.

+

The purpose of an event record class ID field is to set the current ID +of the class of the event record within its parent data +stream class.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+

default-clock-timestamp

Current timestamp of the default clock of the data stream +when the event record occurs.

+

Fixed-length unsigned integer field class or variable-length unsigned integer field class.

+
+
+
+
+

5.9. Event record class fragment

+
+

An event record class describes event records.

+
+
+

The data stream class fragment of which the value of the +id property matches the value of the data-stream-class-id property +of an event record class fragment F is considered the +parent of F.

+
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 36. Properties of an event record class fragment F having the data stream class P as its parent.
NameTypeDescriptionRequired?Default

type

JSON string

+

Type of F.

+
+
+

The value of this property MUST be "event-record-class".

+

Yes

id

JSON integer

+

Numeric ID of F within P.

+
+
+

The value of this property MUST be greater than or equal to zero.

+

No

0

data-stream-class-id

JSON integer

+

Numeric ID of P.

+
+
+

The value of this property MUST be greater than or equal to zero.

+
+
+

Within the metadata stream, P MUST occur +before F.

+

No

0

name

JSON string

+

Name of F.

+
+
+

The purpose of this property, combined with the namespace property, is +to uniquely identify an event record class amongst many +producers.

+

No

F is unnamed

namespace

JSON string

+

Namespace of F.

+
+
+

The purpose of this property, combined with the name property, is to +uniquely identify an event record class amongst many +producers.

+

No

F has no namespace

specific-context-field-class

Structure field class

+

Class of the event record specific context field +of an instance of F.

+

No

F has no event record specific context field class

payload-field-class

Structure field class

+

Class of the event record payload field of an +instance of F.

+

No

F has no event record payload field class

user-attributes

User attributes

+

User attributes of F.

+

No

{}

extensions

Extensions

+

Extensions of F.

+
+
+

Any extension which exists under this property MUST also be declared +in the preamble fragment of the metadata stream.

+

No

{}

+
+

Within a metadata stream, two given event record class fragments +MUST NOT share the same id property value and the same +data-stream-class-id property value.

+
+
+
+
+
+

6. Data stream decoding procedure

+
+
+

This section shows how to, procedurally, decode a CTF 2 data +stream.

+
+
+

Decoding a data stream is the responsibility of a +consumer.

+
+
+

This document doesn’t specify how to encode a data stream, as this +procedure implies much more freedom than decoding. One can deduce how to +encode a data stream from the decoding procedure.

+
+
+

A consumer needs to keep a data stream decoding state while decoding a +data stream. A data stream decoding state comprises the following +variable:

+
+ + ++++++ + + + + + + + + + + + + + + + + +
Table 37. Variable needed to decode a data stream S.
NameTypeDescriptionInitial value

O

Unsigned integer

Current decoding offset/position (bits) from the beginning +of S.

0

+
+

To decode a data stream S:

+
+
+ +
+
+

6.1. Packet decoding procedure

+
+

A consumer needs to keep a packet decoding state +while decoding a packet. A packet decoding state comprises the +following variables:

+
+ + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 38. Variables needed to decode a packet P within a data stream S.
NameTypeDescriptionInitial value

DEF_CLK_VAL

Unsigned integer

Current value (clock cycles) of the default +clock of S, if any.

0

DSC_ID

Unsigned integer

Current ID of the class of S.

0

DSC

Optional data stream class

Current class of S.

None

DS_ID

Optional unsigned integer

Current ID of S.

None

PKT_TOTAL_SZ

Unsigned integer

Current total size (bits) of P.

∞

PKT_CONTENT_SZ

Unsigned integer

Current content size (bits) of P.

∞

LAST_BO

Optional string

Byte order of the last decoded fixed-length bit array field.

None

+
+

To decode a packet P within a data stream S:

+
+
+
    +
  1. +

    Let PO be the current value of O.

    +
    +

    While decoding the packet, O Ã¢Ë†â€™ PO is the current decoding +offset/position (bits) from the beginning of P.

    +
    +
    2. +
  2. +

    If the packet-header-field-class property of the trace +class fragment of the metadata stream exists, then +decode the header field +of P using this property.

    +
    +

    During the packet header field decoding procedure, after having decoded +a field F having the class C with a roles +property:

    +
    +
    +
      +
    • +

      If C has the role packet-magic-number, then validate that the +unsigned integer value of F is 0xc1fc1fc1 (3254525889).

      +
      +

      A consumer SHOULD report an invalid packet magic +number as an error.

      +
      +
      • +
    • +

      If C has the role trace-type-uuid, then validate that the +value of F matches the uuid property of the trace +class fragment.

      +
      +

      A consumer SHOULD report a trace type UUID mismatch as an error.

      +
      +
      • +
    • +

      If C has the role data-stream-class-id, then +set DSC_ID to the unsigned integer value +of F.

      +
      • +
    • +

      If C has the role data-stream-id, then +set DS_ID to the unsigned integer value +of F.

      +
      • +
    +
    +
    +

    After having decoded the whole packet header field, +if DS_ID is set, then it’s the ID of S within +its class. In other words, two data streams MAY have the +same ID if they are instances of different data stream classes.

    +
    +
    3. +
  3. +

    Set DSC to the data stream class +having DSC_ID as the value of its id property.

    +
    +

    If no data stream class has the ID DSC_ID, then report an +error and abort the data stream decoding process.

    +
    +
    4. +
  4. +

    If the packet-context-field-class property of DSC +exists, then decode the context field +of P using this property.

    +
    +

    During the packet context field decoding procedure, after having decoded +a field F having the class C with a roles +property:

    +
    +
    +
      +
    • +

      If C has the role packet-total-size, then +set PKT_TOTAL_SZ to the unsigned integer value +of F.

      +
      • +
    • +

      If C has the role packet-content-size, then +set PKT_CONTENT_SZ to the unsigned integer value +of F.

      +
      • +
    • +

      If C has the role packet-beginning-default-clock-timestamp, +then set DEF_CLK_VAL to the unsigned integer value +of F.

      +
      • +
    • +

      If C has the role packet-end-default-clock-timestamp, then +the unsigned integer value of F is the value of the +default clock of S at the end of P.

      +
      • +
    • +

      If C has the role discarded-event-record-counter-snapshot, +then the unsigned integer value of F is a snapshot of the +discarded event record counter of S at +the end of P.

      +
      • +
    • +

      If C has the role packet-sequence-number, then the unsigned +integer value of F is the sequence number of P +within S.

      +
      • +
    +
    +
    +

    A consumer SHOULD report a beginning default clock +timestamp greater than an end default clock timestamp as an error.

    +
    +
    5. +
  5. +

    If PKT_TOTAL_SZ is Ã¢Ë†Å¾ and PKT_CONTENT_SZ is +not Ã¢Ë†Å¾, then set PKT_TOTAL_SZ +to PKT_CONTENT_SZ.

    +
    6. +
  6. +

    If PKT_CONTENT_SZ is Ã¢Ë†Å¾ and PKT_TOTAL_SZ is +not Ã¢Ë†Å¾, then set PKT_CONTENT_SZ +to PKT_TOTAL_SZ.

    +
    7. +
  7. +

    While O < PO + PKT_CONTENT_SZ +and there’s remaining data in S:

    +
    + +
    +
    8. +
  8. +

    If PKT_TOTAL_SZ and PKT_CONTENT_SZ both are +not Ã¢Ë†Å¾, then set O to +PO + PKT_TOTAL_SZ, effectively +skipping end-of-packet padding.

    +
    9. +
+
+
+
+

6.2. Event record decoding procedure

+
+

A consumer needs to keep an event record decoding +state while decoding an event record. An event record decoding +state comprises the following variables:

+
+ + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
Table 39. Variables needed to decode an event record E within a data stream S.
NameTypeDescriptionInitial value

ERC_ID

Unsigned integer

Current ID of the class of E of which the +parent is the class of S.

0

ERC

Optional event record class

Current class of E.

None

+
+

To decode an event record E within a data stream S:

+
+
+
    +
  1. +

    If the event-record-header-field-class property of DSC +exists, then decode the header +field of E using this property.

    +
    +

    During the event record header field decoding procedure, after having +decoded a field F having the class C with a +roles property:

    +
    +
    +
      +
    • +

      If C has the role event-record-class-id, then +set ERC_ID to the unsigned integer value +of F.

      +
      • +
    • +

      If C has the role default-clock-timestamp, then +update DEF_CLK_VAL from F.

      +
      • +
    +
    +
    +

    After having decoded the whole event record header field, +DEF_CLK_VAL is the value of the default clock +of S when E occurs.

    +
    +
    2. +
  2. +

    Set ERC to the event record class having:

    +
    +
      +
    • +

      DSC_ID as the value of its data-stream-class-id property.

      +
      • +
    • +

      ERC_ID as the value of its id property.

      +
      • +
    +
    +
    +

    If no event record class has the ID ERC_ID within a data +stream class having the ID DSC_ID, then report an error and +abort the data stream decoding process.

    +
    +
    3. +
  3. +

    If the event-record-common-context-field-class property +of DSC exists, then decode the +common context field of E using this +property.

    +
    4. +
  4. +

    If the specific-context-field-class property of ERC +exists, then decode the +specific context field of E +using this property.

    +
    5. +
  5. +

    If the payload-field-class property of ERC exists, then +decode the payload field +of E using this property.

    +
    6. +
+
+
+

6.2.1. Clock value update procedure

+
+

To update DEF_CLK_VAL from an unsigned integer +field F having the unsigned integer value V and +the class C:

+
+
+
    +
  1. +

    Let L be an unsigned integer initialized to, +depending on the type property of C:

    +
    +
    +
    +
    +
    "fixed-length-unsigned-integer"
    +
    "fixed-length-unsigned-enumeration"
    +
    +

    The value of the length property of C.

    +
    +
    "variable-length-unsigned-integer"
    +
    "variable-length-unsigned-enumeration"
    +
    +

    S Ãƒâ€”7, where S is the number of +bytes which F occupies +with the data stream.

    +
    +
    +
    +
    +
    +
    2. +
  2. +

    Let MASK be an unsigned integer initialized to +2L Ã¢Ë†â€™ 1.

    +
    3. +
  3. +

    Let H be an unsigned integer initialized to +DEF_CLK_VAL & ~MASK, +where “&” is the bitwise AND operator and +“~” is the bitwise NOT operator.

    +
    4. +
  4. +

    Let CUR be an unsigned integer initialized to +DEF_CLK_VAL & MASK, where “&” is the +bitwise AND operator.

    +
    5. +
  5. +

    Set DEF_CLK_VAL to:

    +
    +
    +
    +
    +
    If V Ã¢â€°Â¥ CUR
    +
    +

    H + V

    +
    +
    Else
    +
    +

    H + MASK + 1 + V

    +
    +
    +
    +
    +
    +
    6. +
+
+
+
+
+

6.3. Field decoding procedure

+
+

The class of a field contains what’s needed to decode it as a +value.

+
+
+

While a field is an actual sequence of bits within a +data stream, a value is its conceptual interpretation with +attached semantics.

+
+
+

The types of values are:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value typePossible values
+

Nil

+
+

None.

+
+

Boolean

+
+

True or false.

+
+

Unsigned/signed integer

+
+

Integral quantity.

+
+

Real

+
+

Continuous quantity.

+
+

String

+
+

Sequence of Unicode characters.

+
+

Array

+
+

Sequence of values.

+
+

Structure

+
+

Sequence of named values (members).

+
+
+

To decode an instance of a field class F, depending on the +value of its type property:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value of the type property of FDecoding procedure of F
+

"fixed-length-bit-array"

+
+

Decode a fixed-length bit array field.

+
+

"fixed-length-boolean"

+
+

Decode a fixed-length boolean field.

+
+ +
+

Decode a fixed-length unsigned integer field.

+
+ +
+

Decode a fixed-length signed integer field.

+
+

"fixed-length-floating-point-number"

+
+

Decode a fixed-length floating point number field.

+
+

"variable-length-bit-array"

+
+

Decode a variable-length bit array field.

+
+ +
+

Decode a variable-length unsigned integer field.

+
+ +
+

Decode a variable-length signed integer.

+
+

"null-terminated-string"

+
+

Decode a null-terminated string field.

+
+

"static-length-string"

+
+

Decode a static-length string field.

+
+

"static-length-blob"

+
+

Decode a static-length BLOB field.

+
+

"dynamic-length-string"

+
+

Decode a dynamic-length string field.

+
+

"dynamic-length-blob"

+
+

Decode a dynamic-length BLOB field.

+
+

"structure"

+
+

Decode a structure field.

+
+

"static-length-array"

+
+

Decode a static-length array field.

+
+

"dynamic-length-array"

+
+

Decode a dynamic-length array field.

+
+

"optional"

+
+

Decode an optional field.

+
+

"variant"

+
+

Decode a variant field.

+
+
+

6.3.1. Alignment procedure

+
+

The decoding procedure of many fields require +O Ã¢Ë†â€™ PO to have a specific alignment.

+
+
+

The alignment requirement of an instance of a field +class F is, depending on the value of its type property:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
type property of FAlignment requirement of F
+ +
+

The value of the alignment property of F.

+
+ +
+

8

+
+

"structure"

+
+

The maximum value of:

+
+
+
    +
  • +

    The value of the minimum-alignment property of F.

    +
    • +
  • +

    The alignment requirements of the instances of the field-class +property of each member class of the +member-classes property of F.

    +
    • +
+
+ +
+

The maximum value of:

+
+
+
    +
  • +

    The value of the minimum-alignment property of F.

    +
    • +
  • +

    The alignment requirement of an instance of the +element-field-class property of F.

    +
    • +
+
+ +
+

1

+
+
+

To align O Ã¢Ë†â€™ PO to some alignment +requirement A (bits):

+
+
+
    +
  • +

    Set O to +PO + ((O Ã¢Ë†â€™ PO + A Ã¢Ë†â€™ 1) & Ã¢Ë†â€™A), +where “&” is the bitwise AND operator.

    +
    • +
+
+
+
+

6.3.2. Field location procedure

+
+

To locate a previously decoded field using a +field location FL:

+
+
+
    +
  1. +

    Let V be, depending on the first element of FL:

    +
    +
    +
    +
    +
    "packet-header"
    +
    +

    The header structure of P +(current packet).

    +
    +
    "packet-context"
    +
    +

    The context structure of P.

    +
    +
    "event-record-header"
    +
    +

    The header structure of E +(current event record).

    +
    +
    "event-record-common-context"
    +
    +

    The common context structure of E.

    +
    +
    "event-record-specific-context"
    +
    +

    The specific context structure of E.

    +
    +
    "event-record-payload"
    +
    +

    The payload structure of E.

    +
    +
    +
    +
    +
    +
    +

    If the consumer cannot set V because there’s no such structure or +because it’s not already decoded nor currently being decoded, then +report an error and abort the data stream decoding process.

    +
    +
    2. +
  2. +

    For each element FLE of FL, starting from +the second element:

    +
    +
      +
    1. +

      Let V be the value of the member named FLE +within V.

      +
      +

      If no member is named FLE within V, then +report an error and abort the data stream decoding process.

      +
      +
      +

      If the member named FLE within V is not already +decoded nor currently being decoded, then report an error and abort +the data stream decoding process.

      +
      +
      2. +
    2. +

      Depending on the type of V:

      +
      +
      +
      +
      +
      Boolean
      +
      Signed integer
      +
      Unsigned integer
      +
      +

      If FLE is not the last element of FL, +then report an error and abort the data stream decoding process.

      +
      +
      Structure
      +
      +

      Continue.

      +
      +
      Array
      +
      +

      While V is an array:

      +
      +
        +
      • +

        If V is not currently being decoded, then report an error and +abort the data stream decoding process.

        +
        +

        Set V to the element of V currently being decoded.

        +
        +
        • +
      +
      +
      +
      Other
      +
      +

      Report an error and abort the data stream decoding process.

      +
      +
      +
      +
      +
      +
      3. +
    +
    +
    3. +
+
+
+

V is the located field.

+
+
+
Example 80. Dynamic-length array field and its length field in the same root field.
+
+
+

Assume the following JSON object is an event record payload structure field class.

+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "corn", (3)
+      "field-class": {
+        "type": "fixed-length-unsigned-integer",
+        "length": 32,
+        "byte-order": "little-endian"
+      }
+    },
+    {
+      "name": "inside",
+      "field-class": {
+        "type": "fixed-length-unsigned-integer",
+        "length": 16,
+        "byte-order": "little-endian"
+      }
+    },
+    {
+      "name": "carbon",
+      "field-class": {
+        "type": "dynamic-length-array", (1)
+        "length-field-location": ["event-record-payload", "corn"], (2)
+        "element-field-class": {
+          "type": "null-terminated-string"
+        }
+      }
+    }
+  ]
+}
+
+
+
+ + + + + + + + + + + + + +
1Dynamic-length array field class.
2Length field location of the dynamic-length array field class.
3Length member class.
+
+
+
+
+
Example 81. Dynamic-length array field and its length field in the same root field, within the same array field element.
+
+
+

Assume the following JSON object is an event record payload structure field class.

+
+
+

Both the dynamic-length array field and its length field exist within the same +element of the static-length array field named nature.

+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "norm",
+      "field-class": {
+        "type": "null-terminated-string"
+      }
+    },
+    {
+      "name": "nature",
+      "field-class": {
+        "type": "static-length-array",
+        "length": 43,
+        "element-field-class": {
+          "type": "structure",
+          "member-classes": [
+            {
+              "name": "laser", (3)
+              "field-class": {
+                "type": "variable-length-unsigned-integer"
+              }
+            },
+            {
+              "name": "joystick",
+              "field-class": {
+                "type": "dynamic-length-array", (1)
+                "length-field-location": [ (2)
+                  "event-record-payload",
+                  "nature",
+                  "laser"
+                ],
+                "element-field-class": {
+                  "type": "null-terminated-string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+
+
+
+ + + + + + + + + + + + + +
1Dynamic-length array field class.
2Length field location of the dynamic-length array field class.
3Length member class.
+
+
+
+
+
Example 82. Dynamic-length array and its length field in the same root field, within the same variant field.
+
+
+

Assume the following JSON object is an event record payload structure field class.

+
+
+

Both the dynamic-length array field and its length field exist within the same +option of the variant field named clinic.

+
+
+

Moreover, the selector field of the clinic variant field is the +lawyer field.

+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "lawyer", (5)
+      "field-class": {
+        "type": "fixed-length-signed-integer",
+        "length": 16,
+        "byte-order": "little-endian"
+      }
+    },
+    {
+      "name": "clinic",
+      "field-class": {
+        "type": "variant",
+        "selector-field-location": ["event-record-payload", "lawyer"], (4)
+        "options": [
+          {
+            "selector-field-ranges": [[0, 0]],
+            "field-class": {
+              "type": "null-terminated-string"
+            }
+          },
+          {
+            "selector-field-ranges": [[1, 4]],
+            "field-class": {
+              "type": "structure",
+              "member-classes": [
+                {
+                  "name": "lemon", (3)
+                  "field-class": {
+                    "type": "fixed-length-unsigned-integer",
+                    "length": 8,
+                    "byte-order": "big-endian"
+                  }
+                },
+                {
+                  "name": "joystick",
+                  "field-class": {
+                    "type": "dynamic-length-array", (1)
+                    "length-field-location": [ (2)
+                      "event-record-payload",
+                      "clinic",
+                      "lemon"
+                    ],
+                    "element-field-class": {
+                      "type": "null-terminated-string"
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          {
+            "selector-field-ranges": [[5, 5], [7, 7]],
+            "field-class": {
+              "type": "fixed-length-boolean",
+              "length": 8,
+              "byte-order": "little-endian"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+
+
+
+ + + + + + + + + + + + + + + + + + + + + +
1Dynamic-length array field class.
2Length field location of the dynamic-length array field class.
3Length member class.
4Selector field location of the variant field class.
5Selector member class.
+
+
+
+
+
Example 83. Dynamic-length array and its length field in the same root field; length field is a variant field.
+
+
+

Assume the following JSON object is an event record payload structure field class.

+
+
+

The length field of the dynamic-length array field is a variant field: it can be +an 8-bit, a 16-bit, or a 32-bit fixed-length integer field, depending +on the selection of the variant field.

+
+
+

Moreover, the selector field of the variant field is located in another +root field (event record specific context).

+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "glass", (3)
+      "field-class": {
+        "type": "variant",
+        "selector-field-location": ["event-record-specific-context", "sel"],
+        "options": [
+          {
+            "selector-field-ranges": [[0, 0]],
+            "field-class": {
+              "type": "fixed-length-unsigned-integer", (4)
+              "length": 8,
+              "byte-order": "little-endian"
+            }
+          },
+          {
+            "selector-field-ranges": [[1, 1]],
+            "field-class": {
+              "type": "fixed-length-unsigned-integer", (4)
+              "length": 16,
+              "byte-order": "little-endian"
+            }
+          },
+          {
+            "selector-field-ranges": [[2, 2]],
+            "field-class": {
+              "type": "fixed-length-unsigned-integer", (4)
+              "length": 32,
+              "byte-order": "little-endian"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "margin",
+      "field-class": {
+        "type": "dynamic-length-array", (1)
+        "length-field-location": ["event-record-payload", "glass"], (2)
+        "element-field-class": {
+          "type": "null-terminated-string"
+        }
+      }
+    }
+  ]
+}
+
+
+
+ + + + + + + + + + + + + + + + + +
1Dynamic-length array field class.
2Length field location of the dynamic-length array field class.
3Length member class.
4Possible length field class.
+
+
+
+
+
Example 84. Dynamic-length array and its length field in the same root field; structure field containing length field is a variant field.
+
+
+

Assume the following JSON object is an event record payload structure field class.

+
+
+

The length field of the dynamic-length array field is within a structure field +which is a variant field.

+
+
+

Moreover:

+
+
+
    +
  • +

    The selector field of the variant field is located in another root +field (event record common context).

    +
    • +
  • +

    The field class of the third option of the glass variant field class +contains a dynamic-length BLOB field class (lock member); the +length field of its instance is the previous member (eagle) within +the same structure field.

    +
    • +
+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "glass",
+      "field-class": {
+        "type": "variant",
+        "selector-field-location": ["event-record-common-context", "sel"],
+        "options": [
+          {
+            "selector-field-ranges": [[0, 0]],
+            "field-class": {
+              "type": "structure",
+              "member-classes": [
+                {
+                  "name": "eagle",
+                  "field-class": {
+                    "type": "fixed-length-unsigned-integer", (3)
+                    "length": 16,
+                    "byte-order": "little-endian"
+                  }
+                },
+                {
+                  "name": "road",
+                  "field-class": {
+                    "type": "null-terminated-string"
+                  }
+                }
+              ]
+            }
+          },
+          {
+            "selector-field-ranges": [[32, 172]],
+            "field-class": {
+              "type": "structure",
+              "member-classes": [
+                {
+                  "name": "nuance",
+                  "field-class": {
+                    "type": "null-terminated-string"
+                  }
+                },
+                {
+                  "name": "eagle",
+                  "field-class": {
+                    "type": "fixed-length-unsigned-integer", (3)
+                    "length": 24,
+                    "byte-order": "big-endian"
+                  }
+                }
+              ]
+            }
+          },
+          {
+            "selector-field-ranges": [[5, 5]],
+            "field-class": {
+              "type": "structure",
+              "member-classes": [
+                {
+                  "name": "eagle", (5)
+                  "field-class": {
+                    "type": "variable-length-unsigned-integer" (3)
+                  }
+                },
+                {
+                  "name": "lock",
+                  "field-class": {
+                    "type": "dynamic-length-blob",
+                    "length-field-location": [ (4)
+                      "event-record-payload",
+                      "glass",
+                      "eagle"
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "name": "margin",
+      "field-class": {
+        "type": "dynamic-length-array", (1)
+        "length-field-location": [ (2)
+          "event-record-payload",
+          "glass",
+          "eagle"
+        ],
+        "element-field-class": {
+          "type": "null-terminated-string"
+        }
+      }
+    }
+  ]
+}
+
+
+
+ + + + + + + + + + + + + + + + + + + + + +
1Dynamic-length array field class.
2Length field location of the dynamic-length array field class.
3Possible length field class.
4Length field location of the dynamic-length BLOB field class.
5Length field class for the dynamic-length BLOB field class.
+
+
+

Note that both the dynamic-length array and dynamic-length BLOB field classes have the same +length field location.

+
+
+
+
+
Example 85. Dynamic-length array and its length field in another root field.
+
+
+

Assume the following JSON objects are the event record specific context +and payload structure field classes of the same +event record class.

+
+
+

The length field of the dynamic-length array field of the event record payload is +within the event record specific context.

+
+
+
Event record specific context field class.
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "cook",
+      "field-class": {
+        "type": "fixed-length-floating-point-number",
+        "length": 64,
+        "byte-order": "little-endian"
+      }
+    },
+    {
+      "name": "vegetable", (1)
+      "field-class": {
+        "type": "variable-length-unsigned-integer"
+      }
+    }
+  ]
+}
+
+
+
+ + + + + +
1Length member class.
+
+
+
Event record payload field class.
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "avenue",
+      "field-class": {
+        "type": "dynamic-length-array", (1)
+        "length-field-location": [ (2)
+          "event-record-specific-context",
+          "vegetable"
+        ],
+        "element-field-class": {
+          "type": "null-terminated-string"
+        }
+      }
+    },
+    {
+      "name": "railroad",
+      "field-class": {
+        "type": "null-terminated-string"
+      }
+    }
+  ]
+}
+
+
+
+ + + + + + + + + +
1Dynamic-length array field class.
2Length field location of the dynamic-length array field class.
+
+
+
+
+
+

6.3.3. Fixed-length bit array field decoding procedure

+
+

For this whole section about decoding an instance of a +fixed-length bit array field class F, let BO be the value of the byte-order +property of F.

+
+
+

To read a single data stream bit from an +instance of F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    • +

      BYTE_I be (O Ã¢Ë†â€™ PO) / 8 (integral +division; remainder discarded).

      +
      • +
    • +

      BIT_I be:

      +
      +
      +
      + + + + + + + + + +
      +BO is "big-endian" + +

      7 Ã¢Ë†â€™ ((O Ã¢Ë†â€™ PO) mod 8)

      +
      +BO is "little-endian" + +

      (O Ã¢Ë†â€™ PO) mod 8

      +
      +
      +
      +
      +
      • +
    +
    +
    2. +
  2. +

    Depending on the value of the bit at the index BIT_I, +where 0 is the index of the +least significant bit, +within the byte at the index BYTE_I from the beginning +of P (the current packet being decoded):

    +
    +
    +
    + + + + + + + + + +
    +0 + +

    The bit value is false.

    +
    +1 + +

    The bit value is true.

    +
    +
    +
    +
    +
    3. +
+
+
+

To decode an instance of F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    1. +

      L be the value of the length property of F.

      +
      2. +
    2. +

      V be an array of booleans of length L.

      +
      3. +
    3. +

      I be an unsigned integer initialized to 0.

      +
      4. +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    If +((O Ã¢Ë†â€™ PO) mod 8 Ã¢â€° 0) and +LAST_BO Ã¢â€° BO, then report an error +and abort the data stream decoding process.

    +
    4. +
  4. +

    While I < L:

    +
    +
      +
    1. +

      Let VI be an unsigned integer initialized to:

      +
      + + + + + + + + + +
      +BO is "big-endian" + +

      0

      +
      +BO is "little-endian" + +

      L Ã¢Ë†â€™ I Ã¢Ë†â€™ 1

      +
      +
      +
      2. +
    2. +

      Set the element at the index VI of V +to the current single bit value.

      +
      3. +
    3. +

      Set I to I + 1.

      +
      4. +
    4. +

      Set O to O + 1.

      +
      5. +
    +
    +
    5. +
  5. +

    Set LAST_BO to BO.

    +
    6. +
+
+
+

V is the decoded bit array value.

+
+
+

To add to the decoding procedure above, note that the “reading +direction” within a byte depends on BO. Assuming +O Ã¢Ë†â€™ PO = 0, the following diagrams show which +bit is selected by O Ã¢Ë†â€™ PO within a 16-bit fixed-length bit array field +depending on BO:

+
+
+
+
"big-endian"
+
+

+
+
+bit array decoding be +
+
+
+
"little-endian"
+
+

+
+
+bit array decoding le +
+
+
+
+
+
+
Example 86. Contiguous fixed-length bit array fields: big-endian versus little-endian.
+
+
+

This example shows the binary layout of contiguous big-endian and +little-endian fixed-length bit array fields.

+
+
+

Assume that O Ã¢Ë†â€™ PO = 16. All the fixed-length bit array +fields of this example have an implicit 1-bit aligment +requirement.

+
+
+

Considering the following member classes of some +structure field class:

+
+
+
+
[
+  {
+    "name": "green",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 3,
+      "byte-order": "big-endian"
+    }
+  },
+  {
+    "name": "blue",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 9,
+      "byte-order": "big-endian"
+    }
+  },
+  {
+    "name": "yellow",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 14,
+      "byte-order": "big-endian"
+    }
+  },
+  {
+    "name": "red",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 4,
+      "byte-order": "big-endian"
+    }
+  }
+]
+
+
+
+

The binary layout is as such:

+
+
+
+bit array fields be +
+
+
+

Considering the following member classes of some structure field class, +the only difference with the previous sample being the values of the +byte-order property:

+
+
+
+
[
+  {
+    "name": "green",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 3,
+      "byte-order": "little-endian"
+    }
+  },
+  {
+    "name": "blue",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 9,
+      "byte-order": "little-endian"
+    }
+  },
+  {
+    "name": "yellow",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 14,
+      "byte-order": "little-endian"
+    }
+  },
+  {
+    "name": "red",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 4,
+      "byte-order": "little-endian"
+    }
+  }
+]
+
+
+
+

The binary layout is as such:

+
+
+
+bit array fields le +
+
+
+
+
+
Example 87. Padding between fixed-length bit array fields.
+
+
+

This example shows how the alignment requirement of a +fixed-length bit array field can translate into padding bits to skip during the +decoding process.

+
+
+

Assume that O Ã¢Ë†â€™ PO = 32.

+
+
+

Considering the following member classes of some +structure field class:

+
+
+
+
[
+  {
+    "name": "green",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 5,
+      "byte-order": "big-endian"
+    }
+  },
+  {
+    "name": "blue",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 3,
+      "byte-order": "big-endian",
+      "alignment": 8
+    }
+  },
+  {
+    "name": "yellow",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 4,
+      "byte-order": "big-endian",
+      "alignment": 4
+    }
+  }
+]
+
+
+
+

The binary layout is as such:

+
+
+
+bit array fields padding be +
+
+
+

Considering the following member classes of some structure field class, +the only difference with the previous sample being the values of the +byte-order property:

+
+
+
+
[
+  {
+    "name": "green",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 5,
+      "byte-order": "little-endian"
+    }
+  },
+  {
+    "name": "blue",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 3,
+      "byte-order": "little-endian",
+      "alignment": 8
+    }
+  },
+  {
+    "name": "yellow",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 4,
+      "byte-order": "little-endian",
+      "alignment": 4
+    }
+  }
+]
+
+
+
+

The binary layout is as such:

+
+
+
+bit array fields padding le +
+
+
+
+
+
Example 88. Contiguous fixed-length bit array fields with different byte orders.
+
+
+

Step 3 of the decoding procedure above +requires that a consumer stops the data stream decoding +process if the byte order between two contiguous fixed-length bit array fields changes +when O Ã¢Ë†â€™ PO is not a mutliple of 8.

+
+
+

In other words, a given data stream byte MUST NOT contain +bits of two fixed-length bit array fields having different byte orders.

+
+
+

This example shows how contiguous fixed-length bit array fields may have different byte +orders with correct alignment.

+
+
+

Assume that O Ã¢Ë†â€™ PO = 16.

+
+
+

Considering the following member classes of some +structure field class:

+
+
+
+
[
+  {
+    "name": "green",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 3,
+      "byte-order": "big-endian"
+    }
+  },
+  {
+    "name": "blue",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 5,
+      "byte-order": "big-endian"
+    }
+  },
+  {
+    "name": "yellow",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 5,
+      "byte-order": "little-endian"
+    }
+  },
+  {
+    "name": "orange",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 8,
+      "byte-order": "little-endian"
+    }
+  },
+  {
+    "name": "red",
+    "field-class": {
+      "type": "fixed-length-bit-array",
+      "length": 6,
+      "byte-order": "big-endian",
+      "alignment": 8
+    }
+  }
+]
+
+
+
+

The binary layout is as such:

+
+
+
+bit array fields be le +
+
+
+
+
+
+

6.3.4. Fixed-length boolean field decoding procedure

+
+

To decode an instance of a fixed-length boolean field class:

+
+
+
    +
  1. +

    Let VB be a boolean.

    +
    2. +
  2. +

    Decode the instance as a fixed-length bit array field.

    +
    3. +
  3. +

    If all the elements of V are false, then set VB +to false.

    +
    +

    Else, set VB to true.

    +
    +
    4. +
+
+
+

VB is the decoded boolean value.

+
+
+
+

6.3.5. Fixed-length unsigned integer field decoding procedure

+
+

To decode an instance of a fixed-length unsigned integer field class:

+
+
+
    +
  1. +

    Let VI be an unsigned integer.

    +
    2. +
  2. +

    Decode the instance as a fixed-length bit array field.

    +
    3. +
  3. +

    Set VI as the unsigned integer interpretation +of V, where the first element of V is the most +significant bit.

    +
    4. +
+
+
+

VI is the decoded unsigned integer value.

+
+
+
+

6.3.6. Fixed-length signed integer field decoding procedure

+
+

To decode an instance of a fixed-length signed integer field class:

+
+
+
    +
  1. +

    Let VI be a signed integer.

    +
    2. +
  2. +

    Decode the instance as a fixed-length bit array field.

    +
    3. +
  3. +

    Set VI as the signed integer interpretation, following the +two’s complement format, of V, where the first element +of V is the most significant bit.

    +
    4. +
+
+
+

VI is the decoded signed integer value.

+
+
+
+

6.3.7. Fixed-length floating point number field decoding procedure

+
+

To decode an instance of a fixed-length floating point number field class:

+
+
+
    +
  1. +

    Let VR be a real value.

    +
    2. +
  2. +

    Decode the instance as a fixed-length bit array field.

    +
    3. +
  3. +

    Set VR to the real number interpretation, following the +IEEE 754-2008 binary interchange format, of V, where the first element of V is +the most significant bit.

    +
    4. +
+
+
+

VR is the decoded real value.

+
+
+
+

6.3.8. Variable-length bit array field decoding procedure

+
+

To decode an instance of a variable-length bit array field class F:

+
+
+
    +
  1. +

    Let V be an empty array of booleans.

    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    Read N bytes of data from S at the +offset O, as many as needed following the unsigned +LEB128 format, appending the +decoded bits to V as booleans from the most +significant to the least significant.

    +
    4. +
  4. +

    Set O to O + N Ãƒâ€” 8.

    +
    5. +
+
+
+

V is the decoded value.

+
+
+
Example 89. 3-byte variable-length bit array field decoding.
+
+
+

Consider the following variable-length bit array field class F:

+
+
+
+
{
+  "type": "variable-length-bit-array"
+}
+
+
+
+

The following diagram shows the three bytes of an instance +of F and the resulting bit array value.

+
+
+
+vl ba +
+
+
+

Note that the data bits of the last byte (in red) become the first +elements of the resulting bit array value because LEB128 is a +little-endian encoding.

+
+
+
+
+
+

6.3.9. Variable-length unsigned integer field decoding procedure

+
+

To decode an instance of a variable-length unsigned integer field class:

+
+
+
    +
  1. +

    Let VI be an unsigned integer.

    +
    2. +
  2. +

    Decode the instance as a variable-length bit array field.

    +
    3. +
  3. +

    Set VI as the unsigned integer interpretation of V, +where the first element of V is the most significant bit.

    +
    4. +
+
+
+

VI is the decoded unsigned integer value.

+
+
+
+

6.3.10. Variable-length signed integer field decoding procedure

+
+

To decode an instance of a variable-length signed integer field class:

+
+
+
    +
  1. +

    Let VI be a signed integer.

    +
    2. +
  2. +

    Decode the instance as a variable-length bit array field.

    +
    3. +
  3. +

    Set VI as the signed integer interpretation, following the +two’s complement format, of V, where the first element +of V is the most significant bit.

    +
    4. +
+
+
+

VI is the decoded signed integer value.

+
+
+
+

6.3.11. Null-terminated string field decoding procedure

+
+

To decode an instance of a null-terminated string field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    • +

      B be a byte.

      +
      • +
    • +

      A be an empty sequence of bytes.

      +
      • +
    • +

      V be a string.

      +
      • +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    Read one byte of data from S at the offset O +as B.

    +
    4. +
  4. +

    Set O to O + 8.

    +
    5. +
  5. +

    While B Ã¢â€° 0:

    +
    +
      +
    1. +

      Append B to A.

      +
      2. +
    2. +

      Read one byte of data from S at the +offset O as B.

      +
      3. +
    3. +

      Set O to O + 8.

      +
      4. +
    +
    +
    6. +
  6. +

    Decode A, following UTF-8, as V.

    +
    7. +
+
+
+

V is the decoded string value.

+
+
+
Example 90. 22-byte null-terminated string field decoding.
+
+
+

Consider the following null-terminated string field class F:

+
+
+
+
{
+  "type": "null-terminated-string"
+}
+
+
+
+

The following diagram shows packet bytes including a 22-byte +instance of F (in blue) and its resulting string value.

+
+
+

The offset of the null-terminated string field, from the beginning of the packet, +is 0xfc23 bytes, which means +O Ã¢Ë†â€™ PO = 516,376.

+
+
+
+str +
+
+
+

The field contains 21 UTF-8 bytes and a null terminating byte.

+
+
+

The resulting string value contains 19 Unicode characters.

+
+
+

After the field is decoded, O Ã¢Ë†â€™ PO = 516,552.

+
+
+
+
+
+

6.3.12. Static-length string field decoding procedure

+
+

To decode an instance of a static-length string field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    • +

      L be the length property of F.

      +
      • +
    • +

      I be an unsigned integer initialized to 0.

      +
      • +
    • +

      B be a byte.

      +
      • +
    • +

      R be a boolean initialized to true.

      +
      • +
    • +

      A be an empty sequence of bytes.

      +
      • +
    • +

      V be a string.

      +
      • +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    While I < L:

    +
    +
      +
    1. +

      Read one byte of data from S at the +offset O as B.

      +
      2. +
    2. +

      If B = 0, then set R to false.

      +
      +

      Else, if R is true, then append B +to A.

      +
      +
      3. +
    3. +

      Set O to O + 8.

      +
      4. +
    4. +

      Set I to I + 1.

      +
      5. +
    +
    +
    4. +
  4. +

    Decode A, following UTF-8, as V.

    +
    5. +
+
+
+

V is the decoded string value.

+
+
+
Example 91. 18-byte static-length string field decoding.
+
+
+

Consider the following null-terminated string field class F:

+
+
+
+
{
+  "type": "static-length-string",
+  "length": 18
+}
+
+
+
+

The following diagram shows packet bytes including a 18-byte +instance of F (in green) and its resulting string value.

+
+
+

The offset of the static-length string field, from the beginning of the packet, is +0x8c46 bytes, which means O Ã¢Ë†â€™ PO = 287,280.

+
+
+
+sl str +
+
+
+

The field contains 14 UTF-8 bytes, a null terminating byte, +and three garbage data bytes to ignore.

+
+
+

The resulting string value contains seven Unicode characters.

+
+
+

After the field is decoded, O Ã¢Ë†â€™ PO = 287,424.

+
+
+
+
+
+

6.3.13. Static-length BLOB field decoding procedure

+
+

To decode an instance of a static-length BLOB field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    1. +

      L be the length property of F.

      +
      2. +
    2. +

      V be an array of bytes of length L.

      +
      3. +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    Read L bytes of data from S at the +offset O as V.

    +
    4. +
  4. +

    Set O to O + L Ãƒâ€” 8.

    +
    5. +
+
+
+

V is the decoded BLOB value.

+
+
+
+

6.3.14. Dynamic-length string field decoding procedure

+
+

To decode an instance of a dynamic-length string field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    • +

      L be the value of the previously decoded unsigned integer +field of which the length-field-location property of F +indicates the location.

      +
      • +
    • +

      I be an unsigned integer initialized to 0.

      +
      • +
    • +

      B be a byte.

      +
      • +
    • +

      R be a boolean initialized to true.

      +
      • +
    • +

      A be an empty sequence of bytes.

      +
      • +
    • +

      V be a string.

      +
      • +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    While I < L:

    +
    +
      +
    1. +

      Read one byte of data from S at the +offset O as B.

      +
      2. +
    2. +

      If B = 0, then set R to false.

      +
      +

      Else, if R is true, then append B +to A.

      +
      +
      3. +
    3. +

      Set O to O + 8.

      +
      4. +
    4. +

      Set I to I + 1.

      +
      5. +
    +
    +
    4. +
  4. +

    Decode A, following UTF-8, as V.

    +
    5. +
+
+
+

V is the decoded string value.

+
+
+
+

6.3.15. Dynamic-length BLOB field decoding procedure

+
+

To decode an instance of a dynamic-length BLOB field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    1. +

      L be the value of the previously decoded unsigned integer +field of which the length-field-location property of F +indicates the location.

      +
      2. +
    2. +

      V be an array of bytes of length L.

      +
      3. +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    Read L bytes of data from S at the +offset O as V.

    +
    4. +
  4. +

    Set O to O + L Ãƒâ€” 8.

    +
    5. +
+
+
+

V is the decoded BLOB value.

+
+
+
+

6.3.16. Structure field decoding procedure

+
+

To decode an instance of a structure field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    • +

      M be the member-classes property of F.

      +
      • +
    • +

      V be an empty structure.

      +
      • +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    For each member class MC of M:

    +
    +
      +
    1. +

      Let:

      +
      +
        +
      • +

        MF be the field-class property of MC.

        +
        • +
      • +

        MN be the name property of MC.

        +
        • +
      +
      +
      2. +
    2. +

      Decode one instance of MF, appending the +resulting value as a member of V named MN.

      +
      3. +
    +
    +
    4. +
+
+
+

V is the decoded value.

+
+
+
+

6.3.17. Static-length array field decoding procedure

+
+

To decode an instance of a static-length array field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    1. +

      L be the length property of F.

      +
      2. +
    2. +

      EF be the element-field-class property of F.

      +
      3. +
    3. +

      I be an unsigned integer initialized to 0.

      +
      4. +
    4. +

      V be an array of values of length L.

      +
      5. +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    While I < L:

    +
    +
      +
    1. +

      Decode one instance of EF +as element I of V.

      +
      2. +
    2. +

      Set I to I + 1.

      +
      3. +
    +
    +
    4. +
+
+
+

V is the decoded value.

+
+
+
+

6.3.18. Dynamic-length array field decoding procedure

+
+

To decode an instance of a dynamic-length array field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    1. +

      L be the value of the previously decoded unsigned integer field +of which the length-field-location property of F +indicates the location.

      +
      2. +
    2. +

      EF be the element-field-class property of F.

      +
      3. +
    3. +

      I be an unsigned integer initialized to 0.

      +
      4. +
    4. +

      V be an array of values of length L

      +
      5. +
    +
    +
    2. +
  2. +

    Align O Ã¢Ë†â€™ PO according +to F.

    +
    3. +
  3. +

    While I < L:

    +
    +
      +
    1. +

      Decode one instance of EF +as element I of V.

      +
      2. +
    2. +

      Set I to I + 1.

      +
      3. +
    +
    +
    4. +
+
+
+

V is the decoded value.

+
+
+
Example 92. 5-element dynamic-length array field decoding.
+
+
+

Consider the following event record payload +structure field class F:

+
+
+
+
{
+  "type": "structure",
+  "member-classes": [
+    {
+      "name": "len",
+      "field-class": {
+        "type": "fixed-length-unsigned-integer",
+        "length": 16,
+        "byte-order": "big-endian"
+      }
+    },
+    {
+      "name": "id",
+      "field-class": {
+        "type": "null-terminated-string"
+      }
+    },
+    {
+      "name": "vals",
+      "field-class": {
+        "type":
+        "type": "dynamic-length-array",
+        "length-field-location": ["event-record-payload", "len"],
+        "element-field-class": {
+          "type": "fixed-length-unsigned-integer",
+          "length": 32,
+          "byte-order": "little-endian",
+          "alignment": 32
+        }
+      }
+    }
+  ]
+}
+
+
+
+

The following diagram shows packet bytes including an instance +of F (starting in green and ending in blue) and the resulting +signed integer values of its vals member.

+
+
+

The offset of the len fixed-length unsigned integer field, from the beginning of the packet, is +0x42c1 bytes, which means O Ã¢Ë†â€™ PO = 136,712.

+
+
+

The offset of the vals dynamic-length array field, from the beginning of the +packet, is 0x42c8 bytes, which means +O Ã¢Ë†â€™ PO = 136,768.

+
+
+
+dl array +
+
+
+

The unsigned integer value of the len field is 5, which means the +vals field contains five fixed-length signed integer fields.

+
+
+

After the structure field is decoded, +O Ã¢Ë†â€™ PO = 136,928.

+
+
+
+
+
+

6.3.19. Optional field decoding procedure

+
+

To decode an instance of an optional field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    • +

      SEL be the value of the previously decoded boolean +or integer field of which the selector-field-location +property of F indicates the location.

      +
      • +
    • +

      OF be the field-class property of F.

      +
      • +
    • +

      V be a nil value.

      +
      • +
    +
    +
    2. +
  2. +

    If the class of SEL is a fixed-length boolean field class +and SEL is true, then:

    +
    +
      +
    • +

      Decode one instance of OF +as V.

      +
      • +
    +
    +
    +

    Else, if SEL is an element of any integer range +of the selector-field-ranges property of F, then:

    +
    +
    +
      +
    • +

      Decode one instance of OF +as V.

      +
      • +
    +
    +
    3. +
+
+
+

V is the decoded value.

+
+
+
+

6.3.20. Variant field decoding procedure

+
+

To decode an instance of an variant field class F:

+
+
+
    +
  1. +

    Let:

    +
    +
      +
    1. +

      SEL be the value of the previously decoded integer +field of which the selector-field-location property of F +indicates the location.

      +
      2. +
    2. +

      OPTS be the options property of F.

      +
      3. +
    3. +

      OF be the field-class property of the variant +field class option OPT of OPTS of +which SEL is an element of any integer +range of the selector-field-ranges property of OPT.

      +
      4. +
    4. +

      V be a value.

      +
      5. +
    +
    +
    2. +
  2. +

    Decode one instance of OF +as V.

    +
    3. +
+
+
+

V is the decoded value.

+
+
+
+
+
+
+ + \ No newline at end of file -- 2.34.1