CTF2-SPECRC-3.0.html

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta charset="UTF-8">
   5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
   7 <meta name="generator" content="Asciidoctor 2.0.10">
   8 <meta name="author" content="Philippe Proulx">
   9 <title>CTF2-SPECRC-3.0: Common Trace Format version&#160;2 release candidate</title>
  10 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
  11 <style>
  12 /* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
  13 /* Uncomment @import statement to use as custom stylesheet */
  14 /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
  15 article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}
  16 audio,video{display:inline-block}
  17 audio:not([controls]){display:none;height:0}
  18 html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
  19 a{background:none}
  20 a:focus{outline:thin dotted}
  21 a:active,a:hover{outline:0}
  22 h1{font-size:2em;margin:.67em 0}
  23 abbr[title]{border-bottom:1px dotted}
  24 b,strong{font-weight:bold}
  25 dfn{font-style:italic}
  26 hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
  27 mark{background:#ff0;color:#000}
  28 code,kbd,pre,samp{font-family:monospace;font-size:1em}
  29 pre{white-space:pre-wrap}
  30 q{quotes:"\201C" "\201D" "\2018" "\2019"}
  31 small{font-size:80%}
  32 sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
  33 sup{top:-.5em}
  34 sub{bottom:-.25em}
  35 img{border:0}
  36 svg:not(:root){overflow:hidden}
  37 figure{margin:0}
  38 fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
  39 legend{border:0;padding:0}
  40 button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
  41 button,input{line-height:normal}
  42 button,select{text-transform:none}
  43 button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
  44 button[disabled],html input[disabled]{cursor:default}
  45 input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
  46 button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
  47 textarea{overflow:auto;vertical-align:top}
  48 table{border-collapse:collapse;border-spacing:0}
  49 *,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
  50 html,body{font-size:100%}
  51 body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
  52 a:hover{cursor:pointer}
  53 img,object,embed{max-width:100%;height:auto}
  54 object,embed{height:100%}
  55 img{-ms-interpolation-mode:bicubic}
  56 .left{float:left!important}
  57 .right{float:right!important}
  58 .text-left{text-align:left!important}
  59 .text-right{text-align:right!important}
  60 .text-center{text-align:center!important}
  61 .text-justify{text-align:justify!important}
  62 .hide{display:none}
  63 img,object,svg{display:inline-block;vertical-align:middle}
  64 textarea{height:auto;min-height:50px}
  65 select{width:100%}
  66 .center{margin-left:auto;margin-right:auto}
  67 .stretch{width:100%}
  68 .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
  69 div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
  70 a{color:#2156a5;text-decoration:underline;line-height:inherit}
  71 a:hover,a:focus{color:#1d4b8f}
  72 a img{border:0}
  73 p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
  74 p aside{font-size:.875em;line-height:1.35;font-style:italic}
  75 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
  76 h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
  77 h1{font-size:2.125em}
  78 h2{font-size:1.6875em}
  79 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
  80 h4,h5{font-size:1.125em}
  81 h6{font-size:1em}
  82 hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
  83 em,i{font-style:italic;line-height:inherit}
  84 strong,b{font-weight:bold;line-height:inherit}
  85 small{font-size:60%;line-height:inherit}
  86 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
  87 ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
  88 ul,ol{margin-left:1.5em}
  89 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
  90 ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
  91 ul.square{list-style-type:square}
  92 ul.circle{list-style-type:circle}
  93 ul.disc{list-style-type:disc}
  94 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
  95 dl dt{margin-bottom:.3125em;font-weight:bold}
  96 dl dd{margin-bottom:1.25em}
  97 abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
  98 abbr{text-transform:none}
  99 blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
 100 blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
 101 blockquote cite::before{content:"\2014 \0020"}
 102 blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
 103 blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
 104 @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
 105 h1{font-size:2.75em}
 106 h2{font-size:2.3125em}
 107 h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
 108 h4{font-size:1.4375em}}
 109 table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
 110 table thead,table tfoot{background:#f7f8f7}
 111 table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
 112 table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
 113 table tr.even,table tr.alt{background:#f8f8f7}
 114 table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
 115 h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
 116 h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
 117 .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
 118 .clearfix::after,.float-group::after{clear:both}
 119 :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
 120 :not(pre)>code.nobreak{word-wrap:normal}
 121 :not(pre)>code.nowrap{white-space:nowrap}
 122 pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
 123 pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
 124 pre>code{display:block}
 125 pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
 126 em em{font-style:normal}
 127 strong strong{font-weight:400}
 128 .keyseq{color:rgba(51,51,51,.8)}
 129 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 130 .keyseq kbd:first-child{margin-left:0}
 131 .keyseq kbd:last-child{margin-right:0}
 132 .menuseq,.menuref{color:#000}
 133 .menuseq b:not(.caret),.menuref{font-weight:inherit}
 134 .menuseq{word-spacing:-.02em}
 135 .menuseq b.caret{font-size:1.25em;line-height:.8}
 136 .menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 137 b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
 138 b.button::before{content:"[";padding:0 3px 0 2px}
 139 b.button::after{content:"]";padding:0 2px 0 3px}
 140 p a>code:hover{color:rgba(0,0,0,.9)}
 141 #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
 142 #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
 143 #header::after,#content::after,#footnotes::after,#footer::after{clear:both}
 144 #content{margin-top:1.25em}
 145 #content::before{content:none}
 146 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 147 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
 148 #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 149 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
 150 #header .details span:first-child{margin-left:-.125em}
 151 #header .details span.email a{color:rgba(0,0,0,.85)}
 152 #header .details br{display:none}
 153 #header .details br+span::before{content:"\00a0\2013\00a0"}
 154 #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
 155 #header .details br+span#revremark::before{content:"\00a0|\00a0"}
 156 #header #revnumber{text-transform:capitalize}
 157 #header #revnumber::after{content:"\00a0"}
 158 #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
 159 #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
 160 #toc>ul{margin-left:.125em}
 161 #toc ul.sectlevel0>li>a{font-style:italic}
 162 #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
 163 #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
 164 #toc li{line-height:1.3334;margin-top:.3334em}
 165 #toc a{text-decoration:none}
 166 #toc a:active{text-decoration:underline}
 167 #toctitle{color:#7a2518;font-size:1.2em}
 168 @media screen and (min-width:768px){#toctitle{font-size:1.375em}
 169 body.toc2{padding-left:15em;padding-right:0}
 170 #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 171 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 172 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
 173 #toc.toc2 ul ul{margin-left:0;padding-left:1em}
 174 #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
 175 body.toc2.toc-right{padding-left:0;padding-right:15em}
 176 body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
 177 @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
 178 #toc.toc2{width:20em}
 179 #toc.toc2 #toctitle{font-size:1.375em}
 180 #toc.toc2>ul{font-size:.95em}
 181 #toc.toc2 ul ul{padding-left:1.25em}
 182 body.toc2.toc-right{padding-left:0;padding-right:20em}}
 183 #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
 184 #content #toc>:first-child{margin-top:0}
 185 #content #toc>:last-child{margin-bottom:0}
 186 #footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em}
 187 #footer-text{color:rgba(255,255,255,.8);line-height:1.44}
 188 #content{margin-bottom:.625em}
 189 .sect1{padding-bottom:.625em}
 190 @media screen and (min-width:768px){#content{margin-bottom:1.25em}
 191 .sect1{padding-bottom:1.25em}}
 192 .sect1:last-child{padding-bottom:0}
 193 .sect1+.sect1{border-top:1px solid #e7e7e9}
 194 #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
 195 #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
 196 #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
 197 #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
 198 #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
 199 details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
 200 details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em}
 201 .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
 202 table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
 203 .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
 204 table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
 205 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 206 .admonitionblock>table td.icon{text-align:center;width:80px}
 207 .admonitionblock>table td.icon img{max-width:none}
 208 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 209 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
 210 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
 211 .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
 212 .exampleblock>.content>:first-child{margin-top:0}
 213 .exampleblock>.content>:last-child{margin-bottom:0}
 214 .sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}
 215 .sidebarblock>:first-child{margin-top:0}
 216 .sidebarblock>:last-child{margin-bottom:0}
 217 .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
 218 .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
 219 .literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
 220 @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
 221 @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
 222 .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
 223 .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
 224 .listingblock>.content{position:relative}
 225 .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
 226 .listingblock:hover code[data-lang]::before{display:block}
 227 .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
 228 .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
 229 .listingblock pre.highlightjs{padding:0}
 230 .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
 231 .listingblock pre.prettyprint{border-width:0}
 232 .prettyprint{background:#f7f7f8}
 233 pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
 234 pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
 235 pre.prettyprint li code[data-lang]::before{opacity:1}
 236 pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
 237 table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
 238 table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
 239 table.linenotable td.code{padding-left:.75em}
 240 table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em}
 241 pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em}
 242 pre.pygments .lineno::before{content:"";margin-right:-.125em}
 243 .quoteblock{margin:0 1em 1.25em 1.5em;display:table}
 244 .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
 245 .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
 246 .quoteblock blockquote{margin:0;padding:0;border:0}
 247 .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
 248 .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
 249 .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
 250 .verseblock{margin:0 1em 1.25em}
 251 .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
 252 .verseblock pre strong{font-weight:400}
 253 .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
 254 .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
 255 .quoteblock .attribution br,.verseblock .attribution br{display:none}
 256 .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
 257 .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
 258 .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
 259 .quoteblock.abstract{margin:0 1em 1.25em;display:block}
 260 .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
 261 .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
 262 .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
 263 .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
 264 .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
 265 table.tableblock{max-width:100%;border-collapse:separate}
 266 p.tableblock:last-child{margin-bottom:0}
 267 td.tableblock>.content>:last-child{margin-bottom:-1.25em}
 268 td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0}
 269 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
 270 table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
 271 table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
 272 table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
 273 table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
 274 table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
 275 table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
 276 table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
 277 table.frame-all{border-width:1px}
 278 table.frame-sides{border-width:0 1px}
 279 table.frame-topbot,table.frame-ends{border-width:1px 0}
 280 table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7}
 281 th.halign-left,td.halign-left{text-align:left}
 282 th.halign-right,td.halign-right{text-align:right}
 283 th.halign-center,td.halign-center{text-align:center}
 284 th.valign-top,td.valign-top{vertical-align:top}
 285 th.valign-bottom,td.valign-bottom{vertical-align:bottom}
 286 th.valign-middle,td.valign-middle{vertical-align:middle}
 287 table thead th,table tfoot th{font-weight:bold}
 288 tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
 289 tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
 290 p.tableblock>code:only-child{background:none;padding:0}
 291 p.tableblock{font-size:1em}
 292 ol{margin-left:1.75em}
 293 ul li ol{margin-left:1.5em}
 294 dl dd{margin-left:1.125em}
 295 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 296 ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
 297 ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
 298 ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
 299 ul.unstyled,ol.unstyled{margin-left:0}
 300 ul.checklist{margin-left:.625em}
 301 ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
 302 ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
 303 ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
 304 ul.inline>li{margin-left:1.25em}
 305 .unstyled dl dt{font-weight:400;font-style:normal}
 306 ol.arabic{list-style-type:decimal}
 307 ol.decimal{list-style-type:decimal-leading-zero}
 308 ol.loweralpha{list-style-type:lower-alpha}
 309 ol.upperalpha{list-style-type:upper-alpha}
 310 ol.lowerroman{list-style-type:lower-roman}
 311 ol.upperroman{list-style-type:upper-roman}
 312 ol.lowergreek{list-style-type:lower-greek}
 313 .hdlist>table,.colist>table{border:0;background:none}
 314 .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
 315 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 316 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 317 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
 318 .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
 319 .colist td:not([class]):first-child img{max-width:none}
 320 .colist td:not([class]):last-child{padding:.25em 0}
 321 .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
 322 .imageblock.left{margin:.25em .625em 1.25em 0}
 323 .imageblock.right{margin:.25em 0 1.25em .625em}
 324 .imageblock>.title{margin-bottom:0}
 325 .imageblock.thumb,.imageblock.th{border-width:6px}
 326 .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
 327 .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
 328 .image.left{margin-right:.625em}
 329 .image.right{margin-left:.625em}
 330 a.image{text-decoration:none;display:inline-block}
 331 a.image object{pointer-events:none}
 332 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 333 sup.footnote a,sup.footnoteref a{text-decoration:none}
 334 sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 335 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 336 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 337 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
 338 #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
 339 #footnotes .footnote:last-of-type{margin-bottom:0}
 340 #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
 341 .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
 342 .gist .file-data>table td.line-data{width:99%}
 343 div.unbreakable{page-break-inside:avoid}
 344 .big{font-size:larger}
 345 .small{font-size:smaller}
 346 .underline{text-decoration:underline}
 347 .overline{text-decoration:overline}
 348 .line-through{text-decoration:line-through}
 349 .aqua{color:#00bfbf}
 350 .aqua-background{background:#00fafa}
 351 .black{color:#000}
 352 .black-background{background:#000}
 353 .blue{color:#0000bf}
 354 .blue-background{background:#0000fa}
 355 .fuchsia{color:#bf00bf}
 356 .fuchsia-background{background:#fa00fa}
 357 .gray{color:#606060}
 358 .gray-background{background:#7d7d7d}
 359 .green{color:#006000}
 360 .green-background{background:#007d00}
 361 .lime{color:#00bf00}
 362 .lime-background{background:#00fa00}
 363 .maroon{color:#600000}
 364 .maroon-background{background:#7d0000}
 365 .navy{color:#000060}
 366 .navy-background{background:#00007d}
 367 .olive{color:#606000}
 368 .olive-background{background:#7d7d00}
 369 .purple{color:#600060}
 370 .purple-background{background:#7d007d}
 371 .red{color:#bf0000}
 372 .red-background{background:#fa0000}
 373 .silver{color:#909090}
 374 .silver-background{background:#bcbcbc}
 375 .teal{color:#006060}
 376 .teal-background{background:#007d7d}
 377 .white{color:#bfbfbf}
 378 .white-background{background:#fafafa}
 379 .yellow{color:#bfbf00}
 380 .yellow-background{background:#fafa00}
 381 span.icon>.fa{cursor:default}
 382 a span.icon>.fa{cursor:inherit}
 383 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 384 .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
 385 .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
 386 .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
 387 .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
 388 .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
 389 .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
 390 .conum[data-value] *{color:#fff!important}
 391 .conum[data-value]+b{display:none}
 392 .conum[data-value]::after{content:attr(data-value)}
 393 pre .conum[data-value]{position:relative;top:-.125em}
 394 b.conum *{color:inherit!important}
 395 .conum:not([data-value]):empty{display:none}
 396 dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
 397 h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
 398 p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
 399 p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
 400 p{margin-bottom:1.25rem}
 401 .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
 402 .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
 403 .print-only{display:none!important}
 404 @page{margin:1.25cm .75cm}
 405 @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
 406 html{font-size:80%}
 407 a{color:inherit!important;text-decoration:underline!important}
 408 a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
 409 a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
 410 abbr[title]::after{content:" (" attr(title) ")"}
 411 pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
 412 thead{display:table-header-group}
 413 svg{max-width:100%}
 414 p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
 415 h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
 416 #toc,.sidebarblock,.exampleblock>.content{background:none!important}
 417 #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
 418 body.book #header{text-align:center}
 419 body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
 420 body.book #header .details{border:0!important;display:block;padding:0!important}
 421 body.book #header .details span:first-child{margin-left:0!important}
 422 body.book #header .details br{display:block}
 423 body.book #header .details br+span::before{content:none!important}
 424 body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
 425 body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
 426 .listingblock code[data-lang]::before{display:block}
 427 #footer{padding:0 .9375em}
 428 .hide-on-print{display:none!important}
 429 .print-only{display:block!important}
 430 .hide-for-print{display:none!important}
 431 .show-for-print{display:inherit!important}}
 432 @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
 433 .sect1{padding:0!important}
 434 .sect1+.sect1{border:0}
 435 #footer{background:none}
 436 #footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
 437 @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
 438 </style>
 439 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
 440 </head>
 441 <body class="article toc2 toc-left">
 442 <div id="header">
 443 <h1><strong>CTF2-SPECRC-3.0</strong>: Common Trace Format version&#160;2 release candidate</h1>
 444 <div class="details">
 445 <span id="author" class="author">Philippe Proulx</span><br>
 446 <span id="email" class="email"><a href="mailto:pproulx@efficios.com">pproulx@efficios.com</a></span><br>
 447 <span id="revnumber">version 3.0,</span>
 448 <span id="revdate">17 December 2021</span>
 449 </div>
 450 <div id="toc" class="toc2">
 451 <div id="toctitle">Table of Contents</div>
 452 <ul class="sectlevel1">
 453 <li><a href="#_revision_history">1. Revision history</a></li>
 454 <li><a href="#_whats_ctf2">2. What&#8217;s CTF&#160;2?</a></li>
 455 <li><a href="#_common_definitions">3. Common definitions</a></li>
 456 <li><a href="#trace">4. Trace composition</a>
 457 <ul class="sectlevel2">
 458 <li><a href="#metadata-stream-overview">4.1. Metadata stream (overview)</a></li>
 459 <li><a href="#ds">4.2. Data stream</a>
 460 <ul class="sectlevel3">
 461 <li><a href="#pkt">4.2.1. Packet</a></li>
 462 <li><a href="#er">4.2.2. Event record</a></li>
 463 </ul>
 464 </li>
 465 <li><a href="#aux-stream">4.3. Auxiliary stream</a>
 466 <ul class="sectlevel3">
 467 <li><a href="#env">4.3.1. Trace environment</a></li>
 468 </ul>
 469 </li>
 470 </ul>
 471 </li>
 472 <li><a href="#metadata-stream">5. Metadata stream</a>
 473 <ul class="sectlevel2">
 474 <li><a href="#uuid">5.1. UUID</a></li>
 475 <li><a href="#ext">5.2. Extensions</a></li>
 476 <li><a href="#user-attrs">5.3. User attributes</a></li>
 477 <li><a href="#fc">5.4. Field classes</a>
 478 <ul class="sectlevel3">
 479 <li><a href="#field-loc">5.4.1. Field location</a></li>
 480 <li><a href="#int-range-set">5.4.2. Integer range set</a></li>
 481 <li><a href="#roles">5.4.3. Roles</a></li>
 482 <li><a href="#fl-ba-fc">5.4.4. Fixed-length bit array field class</a></li>
 483 <li><a href="#fl-bool-fc">5.4.5. Fixed-length boolean field class</a></li>
 484 <li><a href="#int-fc">5.4.6. Abstract integer field class</a></li>
 485 <li><a href="#fl-int-fc">5.4.7. Fixed-length integer field class</a></li>
 486 <li><a href="#enum-fc">5.4.8. Abstract enumeration field class</a></li>
 487 <li><a href="#fl-enum-fc">5.4.9. Fixed-length enumeration field class</a></li>
 488 <li><a href="#fl-fp-fc">5.4.10. Fixed-length floating point number field class</a></li>
 489 <li><a href="#vl-ba-fc">5.4.11. Variable-length bit array field class</a></li>
 490 <li><a href="#vl-int-fc">5.4.12. Variable-length integer field class</a></li>
 491 <li><a href="#vl-enum-fc">5.4.13. Variable-length enumeration field class</a></li>
 492 <li><a href="#str-fc">5.4.14. Null-terminated string field class</a></li>
 493 <li><a href="#sl-str-fc">5.4.15. Static-length string field class</a></li>
 494 <li><a href="#dl-str-fc">5.4.16. Dynamic-length string field class</a></li>
 495 <li><a href="#blob-fc">5.4.17. Abstract BLOB field class</a></li>
 496 <li><a href="#sl-blob-fc">5.4.18. Static-length BLOB field class</a></li>
 497 <li><a href="#dl-blob-fc">5.4.19. Dynamic-length BLOB field class</a></li>
 498 <li><a href="#struct-fc">5.4.20. Structure field class</a></li>
 499 <li><a href="#array-fc">5.4.21. Abstract array field class</a></li>
 500 <li><a href="#sl-array-fc">5.4.22. Static-length array field class</a></li>
 501 <li><a href="#dl-array-fc">5.4.23. Dynamic-length array field class</a></li>
 502 <li><a href="#opt-fc">5.4.24. Optional field class</a></li>
 503 <li><a href="#var-fc">5.4.25. Variant field class</a></li>
 504 </ul>
 505 </li>
 506 <li><a href="#preamble-frag">5.5. Preamble fragment</a></li>
 507 <li><a href="#tc-frag">5.6. Trace class fragment</a>
 508 <ul class="sectlevel3">
 509 <li><a href="#_roles">5.6.1. Roles</a></li>
 510 </ul>
 511 </li>
 512 <li><a href="#cc-frag">5.7. Clock class fragment</a>
 513 <ul class="sectlevel3">
 514 <li><a href="#clock-offset">5.7.1. Clock offset</a></li>
 515 </ul>
 516 </li>
 517 <li><a href="#dsc-frag">5.8. Data stream class fragment</a>
 518 <ul class="sectlevel3">
 519 <li><a href="#_roles_2">5.8.1. Roles</a></li>
 520 </ul>
 521 </li>
 522 <li><a href="#erc-frag">5.9. Event record class fragment</a></li>
 523 </ul>
 524 </li>
 525 <li><a href="#ds-dec">6. Data stream decoding procedure</a>
 526 <ul class="sectlevel2">
 527 <li><a href="#pkt-dec">6.1. Packet decoding procedure</a></li>
 528 <li><a href="#er-dec">6.2. Event record decoding procedure</a>
 529 <ul class="sectlevel3">
 530 <li><a href="#clk-val-update">6.2.1. Clock value update procedure</a></li>
 531 </ul>
 532 </li>
 533 <li><a href="#field-dec">6.3. Field decoding procedure</a>
 534 <ul class="sectlevel3">
 535 <li><a href="#align-dec">6.3.1. Alignment procedure</a></li>
 536 <li><a href="#field-loc-dec">6.3.2. Field location procedure</a></li>
 537 <li><a href="#fl-ba-field-dec">6.3.3. Fixed-length bit array field decoding procedure</a></li>
 538 <li><a href="#fl-bool-field-dec">6.3.4. Fixed-length boolean field decoding procedure</a></li>
 539 <li><a href="#fl-uint-field-dec">6.3.5. Fixed-length unsigned integer field decoding procedure</a></li>
 540 <li><a href="#fl-sint-field-dec">6.3.6. Fixed-length signed integer field decoding procedure</a></li>
 541 <li><a href="#fl-fp-field-dec">6.3.7. Fixed-length floating point number field decoding procedure</a></li>
 542 <li><a href="#vl-ba-field-dec">6.3.8. Variable-length bit array field decoding procedure</a></li>
 543 <li><a href="#vl-uint-field-dec">6.3.9. Variable-length unsigned integer field decoding procedure</a></li>
 544 <li><a href="#vl-sint-field-dec">6.3.10. Variable-length signed integer field decoding procedure</a></li>
 545 <li><a href="#str-field-dec">6.3.11. Null-terminated string field decoding procedure</a></li>
 546 <li><a href="#sl-str-field-dec">6.3.12. Static-length string field decoding procedure</a></li>
 547 <li><a href="#sl-blob-field-dec">6.3.13. Static-length BLOB field decoding procedure</a></li>
 548 <li><a href="#dl-str-field-dec">6.3.14. Dynamic-length string field decoding procedure</a></li>
 549 <li><a href="#dl-blob-field-dec">6.3.15. Dynamic-length BLOB field decoding procedure</a></li>
 550 <li><a href="#struct-field-dec">6.3.16. Structure field decoding procedure</a></li>
 551 <li><a href="#sl-array-field-dec">6.3.17. Static-length array field decoding procedure</a></li>
 552 <li><a href="#dl-array-field-dec">6.3.18. Dynamic-length array field decoding procedure</a></li>
 553 <li><a href="#opt-field-dec">6.3.19. Optional field decoding procedure</a></li>
 554 <li><a href="#var-field-dec">6.3.20. Variant field decoding procedure</a></li>
 555 </ul>
 556 </li>
 557 </ul>
 558 </li>
 559 </ul>
 560 </div>
 561 </div>
 562 <div id="content">
 563 <div id="preamble">
 564 <div class="sectionbody">
 565 <div class="paragraph">
 566 <p>This document is a release candidate of the Common Trace Format (CTF)
 567 version&#160;2 specification (<em><strong>CTF2-SPEC-2.0</strong></em>).</p>
 568 </div>
 569 <div class="admonitionblock important">
 570 <table>
 571 <tr>
 572 <td class="icon">
 573 <i class="fa icon-important" title="Important"></i>
 574 </td>
 575 <td class="content">
 576 <div class="title">RFC 2119</div>
 577 The key words <em>MUST</em>, <em>MUST&#160;NOT</em>, <em>REQUIRED</em>,
 578 <em>SHOULD</em>, <em>SHOULD&#160;NOT</em>, <em>MAY</em>, and <em>OPTIONAL</em> in this document, when
 579 emphasized, are to be interpreted as described in
 580 <a href="https://www.ietf.org/rfc/rfc2119.txt">RFC&#160;2119</a>.
 581 </td>
 582 </tr>
 583 </table>
 584 </div>
 585 </div>
 586 </div>
 587 <div class="sect1">
 588 <h2 id="_revision_history">1. Revision history</h2>
 589 <div class="sectionbody">
 590 <table class="tableblock frame-all grid-all fit-content">
 591 <caption class="title">Table 1. Revision history.</caption>
 592 <colgroup>
 593 <col>
 594 <col>
 595 <col>
 596 </colgroup>
 597 <thead>
 598 <tr>
 599 <th class="tableblock halign-left valign-top">Document</th>
 600 <th class="tableblock halign-left valign-top">Publication date</th>
 601 <th class="tableblock halign-left valign-top">Changes</th>
 602 </tr>
 603 </thead>
 604 <tbody>
 605 <tr>
 606 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>CTF2-SPECRC-3.0</strong></em></p></td>
 607 <td class="tableblock halign-left valign-top"><p class="tableblock">17 December 2021</p></td>
 608 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
 609 <p>Add the optional <code>minimum-alignment</code> property to the
 610 <a href="#array-fc">abstract array field class</a>.</p>
 611 </div>
 612 <div class="paragraph">
 613 <p>Such a minimum alignment is needed when the <a href="#align-dec">alignment
 614 requirement</a> of contained array field elements wouldn&#8217;t be enough. For
 615 example, a <a href="#producer-def">producer</a> could write a single
 616 32-bit-aligned, 32-bit little-endian integer value, but use the
 617 following <a href="#sl-array-fc">static-length array field class</a> for <a href="#consumer-def">consumers</a>:</p>
 618 </div>
 619 <div class="listingblock">
 620 <div class="content">
 621 <pre class="highlight"><code class="language-json" data-lang="json">{
 622   "type": "static-length-array",
 623   "length": 32,
 624   "minimum-alignment": 32,
 625   "element-field-class": {
 626     "type": "fixed-length-boolean",
 627     "length": 1,
 628     "byte-order": "little-endian"
 629   }
 630 }</code></pre>
 631 </div>
 632 </div>
 633 <div class="paragraph">
 634 <p>While the producer writes a single integer value, consumers decode said
 635 datum as an array of 32&#160;individual flags (booleans).</p>
 636 </div>
 637 <div class="paragraph">
 638 <p>Update the <a href="#align-dec">Alignment procedure</a> section accordingly.</p>
 639 </div></div></td>
 640 </tr>
 641 <tr>
 642 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>CTF2&#8209;SPECRC&#8209;2.0</strong></em></p></td>
 643 <td class="tableblock halign-left valign-top"><p class="tableblock">9 December 2021</p></td>
 644 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
 645 <ul>
 646 <li>
 647 <p>Describe how to use a <a href="#field-loc">field location</a> with a procedure in
 648 a new <a href="#field-loc-dec">Field location procedure</a> section to make constraints easier to
 649 understand.</p>
 650 </li>
 651 <li>
 652 <p>Rename the <code>members</code> property of a <a href="#struct-fc">structure field class</a> to <code>member-classes</code>
 653 as this JSON array contains
 654 <a href="#struct-member-cls">structure field member classes</a>.</p>
 655 </li>
 656 <li>
 657 <p>Make an <a href="#opt-fc">optional field</a> require that <em>all</em> its
 658 possible selector fields be boolean fields, unsigned integer fields,
 659 or signed integer fields.</p>
 660 <div class="paragraph">
 661 <p>Correspondingly, make a <a href="#var-fc">variant field</a> require that <em>all</em> its
 662 possible selector fields be either unsigned integer fields or signed
 663 integer fields.</p>
 664 </div>
 665 <div class="paragraph">
 666 <p>This constraint exists to accomodate some consumer implementations, in
 667 particular the ones with limited integer types.</p>
 668 </div>
 669 </li>
 670 <li>
 671 <p>Add the &#8220;nil&#8221; <a href="#dec-val-type">decoding value type</a> so that
 672 <a href="#opt-field-dec">decoding an optional field</a> always generates a value.</p>
 673 </li>
 674 <li>
 675 <p>Specify that an &#8220;array&#8221; decoding value contains a sequence of values,
 676 whatever their types.</p>
 677 <div class="paragraph">
 678 <p>Indeed, an <a href="#array-fc">array field</a> <em>MAY</em> contain <a href="#var-fc">variant
 679 fields</a>, making it possible for a resulting array value to contain
 680 values having different types.</p>
 681 </div>
 682 </li>
 683 </ul>
 684 </div></div></td>
 685 </tr>
 686 <tr>
 687 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>CTF2&#8209;SPECRC&#8209;1.0</strong></em></p></td>
 688 <td class="tableblock halign-left valign-top"><p class="tableblock">25 November 2021</p></td>
 689 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
 690 <p>Initial CTF&#160;2 specification release candidate.</p>
 691 </div></div></td>
 692 </tr>
 693 </tbody>
 694 </table>
 695 </div>
 696 </div>
 697 <div class="sect1">
 698 <h2 id="_whats_ctf2">2. What&#8217;s CTF&#160;2?</h2>
 699 <div class="sectionbody">
 700 <div class="paragraph">
 701 <p>The <em><strong>Common Trace Format</strong></em> version&#160;2 is a binary
 702 <a href="https://en.wikipedia.org/wiki/Tracing_(software)">trace</a> format designed
 703 to be very fast to write without compromising great flexibility.</p>
 704 </div>
 705 <div class="paragraph">
 706 <p>The intention of CTF&#160;2 is that applications written in any programming
 707 language, and running on any system (be it Linux or bare metal, for
 708 example), can generate traces natively.</p>
 709 </div>
 710 <div class="paragraph">
 711 <p>A CTF&#160;2 trace has all its <a href="#ds">data streams</a> described by a
 712 <a href="#metadata-stream-overview">metadata stream</a>. Given the rich set of
 713 supported <a href="#fc">data field types</a>, this makes it possible for a CTF&#160;2
 714 <a href="#producer-def">producer</a> to append data structures as is to data
 715 streams without further &#8220;data massaging&#8221;. Indeed, the size, alignment,
 716 and byte order of fixed-length fields are all configurable parameters
 717 within the metadata stream.</p>
 718 </div>
 719 <div class="paragraph">
 720 <p>CTF&#160;2 is transport agnostic: this document doesn&#8217;t specify how to
 721 transport or store CTF&#160;2 streams. Other documents can specify such
 722 conventions, and conform CTF&#160;2 producers and <a href="#consumer-def">consumers</a>
 723 may or may not adhere to them.</p>
 724 </div>
 725 <div class="paragraph">
 726 <p>CTF&#160;2 is a major revision of <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>, bringing many improvements, such
 727 as:</p>
 728 </div>
 729 <div class="ulist">
 730 <ul>
 731 <li>
 732 <p>Using JSON text sequences for the metadata stream.</p>
 733 </li>
 734 <li>
 735 <p>Adding <a href="#aux-stream">auxiliary streams</a> (also JSON text sequences).</p>
 736 </li>
 737 <li>
 738 <p>Simplifying the metadata stream.</p>
 739 </li>
 740 <li>
 741 <p>Adding new <a href="#fc">field classes</a>.</p>
 742 </li>
 743 <li>
 744 <p>Using <a href="#roles">roles</a> instead of reserved structure member names to
 745 identify &#8220;special&#8221; fields.</p>
 746 </li>
 747 </ul>
 748 </div>
 749 <div class="paragraph">
 750 <p>and more, while remaining backward compatible at the data stream level.</p>
 751 </div>
 752 </div>
 753 </div>
 754 <div class="sect1">
 755 <h2 id="_common_definitions">3. Common definitions</h2>
 756 <div class="sectionbody">
 757 <div class="paragraph">
 758 <p>Common CTF&#160;2 definitions:</p>
 759 </div>
 760 <div class="dlist">
 761 <dl>
 762 <dt class="hdlist1"><a id="byte-def"></a> <a href="#byte-def">Byte</a></dt>
 763 <dd>
 764 <p>A group of eight <a href="https://en.wikipedia.org/wiki/Bit">bits</a> operated on
 765 as a unit.</p>
 766 <div class="paragraph">
 767 <p>The bits are indexed such that, if the byte represents an 8-bit unsigned
 768 integer, bit&#160;0 is the
 769 <a href="https://en.wikipedia.org/wiki/Bit_numbering#Least_significant_bit">least
 770 significant</a> and bit&#160;7 is the
 771 <a href="https://en.wikipedia.org/wiki/Bit_numbering#Most_significant_bit">most
 772 significant</a>.</p>
 773 </div>
 774 </dd>
 775 <dt class="hdlist1"><a id="class-def"></a> <a href="#class-def">Class</a></dt>
 776 <dd>
 777 <p>A set of values (instances) which share common properties.</p>
 778 <div class="paragraph">
 779 <p>For example, a <a href="#fl-int-fc">fixed-length unsigned integer field class</a> with an 8-bit length property is the set of
 780 the all the fixed-length unsigned integer fields from binary <code>00000000</code> to <code>11111111</code>
 781 (integers 0&#160;to&#160;255).</p>
 782 </div>
 783 <div class="paragraph">
 784 <p>This specification often states that some class <em>describes</em> instances.
 785 For example, an <a href="#erc-frag">event record class</a> describes <a href="#er">event
 786 records</a>.</p>
 787 </div>
 788 </dd>
 789 <dt class="hdlist1"><a id="consumer-def"></a> <a href="#consumer-def">Consumer</a></dt>
 790 <dd>
 791 <p>A software or hardware system which consumes (reads) the streams of
 792 a <a href="#trace">trace</a>.</p>
 793 <div class="paragraph">
 794 <p>A trace consumer is often a <em>trace viewer</em> or a <em>trace analyzer</em>.</p>
 795 </div>
 796 </dd>
 797 <dt class="hdlist1"><a id="ns-def"></a> <a href="#ns-def">Namespace</a></dt>
 798 <dd>
 799 <p>A string of which the purpose is to avoid naming conflicts.</p>
 800 <div class="paragraph">
 801 <p>This document doesn&#8217;t specify the format of a namespace. A producer
 802 <em>SHOULD</em> use a URI, or at least include a domain name owned by the
 803 organization defining the objects under a namespace.</p>
 804 </div>
 805 <div class="admonitionblock important">
 806 <table>
 807 <tr>
 808 <td class="icon">
 809 <i class="fa icon-important" title="Important"></i>
 810 </td>
 811 <td class="content">
 812 The <code>std</code> namespace is reserved for the CTF&#160;2 specification.
 813 </td>
 814 </tr>
 815 </table>
 816 </div>
 817 </dd>
 818 <dt class="hdlist1"><a id="producer-def"></a> <a href="#producer-def">Producer</a></dt>
 819 <dd>
 820 <p>A software or hardware system which produces (writes) the streams of
 821 a <a href="#trace">trace</a>.</p>
 822 <div class="paragraph">
 823 <p>A trace producer is often a <em>tracer</em>.</p>
 824 </div>
 825 </dd>
 826 <dt class="hdlist1"><a id="seq-def"></a> <a href="#seq-def">Sequence</a></dt>
 827 <dd>
 828 <p>A set of related items which follow each other in a particular
 829 order.</p>
 830 </dd>
 831 <dt class="hdlist1"><a id="stream-def"></a> <a href="#stream-def">Stream</a></dt>
 832 <dd>
 833 <p>A <a href="#seq-def">sequence</a> of <a href="#byte-def">bytes</a>.</p>
 834 </dd>
 835 </dl>
 836 </div>
 837 </div>
 838 </div>
 839 <div class="sect1">
 840 <h2 id="trace">4. Trace composition</h2>
 841 <div class="sectionbody">
 842 <div class="paragraph">
 843 <p>A trace is:</p>
 844 </div>
 845 <div class="ulist">
 846 <ul>
 847 <li>
 848 <p>One <a href="#metadata-stream-overview">metadata stream</a>.</p>
 849 </li>
 850 <li>
 851 <p>One or more <a href="#data-stream">data streams</a>.</p>
 852 </li>
 853 <li>
 854 <p>Zero or more <a href="#aux-stream">auxiliary streams</a>.</p>
 855 </li>
 856 </ul>
 857 </div>
 858 <div class="paragraph">
 859 <p>As a reminder, this specification defines a <a href="#stream-def">stream</a> as a
 860 sequence of bytes.</p>
 861 </div>
 862 <div class="admonitionblock note">
 863 <table>
 864 <tr>
 865 <td class="icon">
 866 <i class="fa icon-note" title="Note"></i>
 867 </td>
 868 <td class="content">
 869 This document doesn&#8217;t specify how to transport or store CTF&#160;2
 870 streams. A <a href="#producer-def">producer</a> could serialize all streams as a
 871 single file on the file system, or it could send the streams over the
 872 network using TCP, to name a few examples.
 873 </td>
 874 </tr>
 875 </table>
 876 </div>
 877 <div class="sect2">
 878 <h3 id="metadata-stream-overview">4.1. Metadata stream (overview)</h3>
 879 <div class="paragraph">
 880 <p>A metadata stream describes trace <a href="#ds">data streams</a> with JSON objects.</p>
 881 </div>
 882 <div class="paragraph">
 883 <p>A metadata stream describes things such as:</p>
 884 </div>
 885 <div class="ulist">
 886 <ul>
 887 <li>
 888 <p>The <a href="#cc-frag">class</a> of the data stream <a href="#def-clk">default clocks</a>.</p>
 889 </li>
 890 <li>
 891 <p>The names of <a href="#erc-frag">event record classes</a>.</p>
 892 </li>
 893 <li>
 894 <p>The <a href="#fc">classes</a> of event record fields.</p>
 895 </li>
 896 </ul>
 897 </div>
 898 <div class="paragraph">
 899 <p>Multiple traces <em>MAY</em> share the same metadata stream: a given trace
 900 <em>MAY</em> contain specific information in its own <a href="#aux-stream">auxiliary
 901 streams</a>.</p>
 902 </div>
 903 <div class="paragraph">
 904 <p>See <a href="#metadata-stream">Metadata stream</a> for the full metadata stream specification.</p>
 905 </div>
 906 </div>
 907 <div class="sect2">
 908 <h3 id="ds">4.2. Data stream</h3>
 909 <div class="paragraph">
 910 <p>A <em>data stream</em> is a <a href="#seq-def">sequence</a> of one or more data
 911 <a href="#pkt">packets</a>:</p>
 912 </div>
 913 <div class="imageblock">
 914 <div class="content">
 915 <img src="CTF2-SPECRC-3.0-images/ctf-trace-all.svg" alt="ctf trace all">
 916 </div>
 917 </div>
 918 <div class="paragraph">
 919 <p>In the <a href="#metadata-stream">metadata stream</a>, a
 920 <a href="#dsc-frag">data stream class</a> describes data streams.</p>
 921 </div>
 922 <div class="paragraph">
 923 <p>A packet <em>MUST</em> contain one or more bytes of data.</p>
 924 </div>
 925 <div class="paragraph">
 926 <p>Although a packet <em>MAY</em> contain padding (garbage data) at the end
 927 itself, from the point of view of a data stream, there&#8217;s no padding
 928 between packets. In other words, the byte following the last byte of a
 929 packet is the first byte of the next packet.</p>
 930 </div>
 931 <div class="paragraph">
 932 <p>A data stream <em>MAY</em> have, conceptually:</p>
 933 </div>
 934 <div class="dlist">
 935 <dl>
 936 <dt class="hdlist1"><a id="def-clk"></a> One default, monotonic clock</dt>
 937 <dd>
 938 <p>Described by a <a href="#cc-frag">clock class</a> in the metadata stream.</p>
 939 <div class="paragraph">
 940 <p><a href="#pkt">Packets</a> and <a href="#er">event records</a> <em>MAY</em> contain snapshots, named
 941 <em>timestamps</em>, of the default clock of their data stream.</p>
 942 </div>
 943 </dd>
 944 <dt class="hdlist1"><a id="disc-er-counter"></a> One counter of discarded event records</dt>
 945 <dd>
 946 <p>Indicates the number of event records which the
 947 <a href="#producer-def">producer</a> needed to discard for different reasons.</p>
 948 <div class="paragraph">
 949 <p>For example, a tracer could discard an event record when it doesn&#8217;t fit
 950 some buffer and there&#8217;s no other available buffer.</p>
 951 </div>
 952 <div class="paragraph">
 953 <p>A packet <em>MAY</em> contain a snapshot of this counter.</p>
 954 </div>
 955 </dd>
 956 </dl>
 957 </div>
 958 <div class="paragraph">
 959 <p>See <a href="#ds-dec">Data stream decoding procedure</a> to learn how to decode a CTF&#160;2 data stream.</p>
 960 </div>
 961 <div class="sect3">
 962 <h4 id="pkt">4.2.1. Packet</h4>
 963 <div class="paragraph">
 964 <p>A <em>packet</em> is a segment of a <a href="#ds">data stream</a>.</p>
 965 </div>
 966 <div class="paragraph">
 967 <p>A packet contains a <a href="#seq-def">sequence</a> of data <em>fields</em> or padding
 968 (garbage data). In the metadata stream, <a href="#fc">field classes</a> describe
 969 data fields.</p>
 970 </div>
 971 <div class="paragraph">
 972 <p>A packet <em><strong>P</strong></em>, contained in a data stream&#160;<em><strong>S</strong></em>, contains,
 973 in this order:</p>
 974 </div>
 975 <div class="olist arabic">
 976 <ol class="arabic">
 977 <li>
 978 <p><a id="pkt-header"></a> <em>OPTIONAL</em>: A <strong>header</strong> <a href="#struct-fc">structure</a> field,
 979 described at the <a href="#tc-frag">trace class</a> level in the
 980 <a href="#metadata-stream">metadata stream</a>, which contains, in this order:</p>
 981 <div class="olist loweralpha">
 982 <ol class="loweralpha" type="a">
 983 <li>
 984 <p><em>OPTIONAL</em>: A packet magic number field (0xc1fc1fc1, or 3254525889).</p>
 985 </li>
 986 <li>
 987 <p>In any order:</p>
 988 <div class="ulist">
 989 <ul>
 990 <li>
 991 <p><em>OPTIONAL</em>: A trace class UUID field.</p>
 992 </li>
 993 <li>
 994 <p><em>OPTIONAL</em>: One or more fields which contain the numeric ID of the
 995 <a href="#dsc-frag">class</a> of&#160;<em><strong>S</strong></em>.</p>
 996 </li>
 997 <li>
 998 <p><em>OPTIONAL</em>: One or more fields which contain the numeric ID
 999 of&#160;<em><strong>S</strong></em>.</p>
1000 </li>
1001 </ul>
1002 </div>
1003 </li>
1004 </ol>
1005 </div>
1006 </li>
1007 <li>
1008 <p><a id="pkt-ctx"></a> <em>OPTIONAL</em>: A <strong>context</strong> <a href="#struct-fc">structure</a> field,
1009 described at the <a href="#dsc-frag">data stream class</a> level in the metadata
1010 stream, which contains, in any order:</p>
1011 <div class="ulist">
1012 <ul>
1013 <li>
1014 <p><em>OPTIONAL</em>: A field which contains the total size of&#160;<em><strong>P</strong></em>,
1015 in bits (always a multiple of 8).</p>
1016 </li>
1017 <li>
1018 <p><em>OPTIONAL</em>: A field which contains the content size of&#160;<em><strong>P</strong></em>,
1019 in bits.</p>
1020 </li>
1021 <li>
1022 <p><em>OPTIONAL</em>: A field which contains the beginning timestamp
1023 of&#160;<em><strong>P</strong></em>.</p>
1024 </li>
1025 <li>
1026 <p><em>OPTIONAL</em>: A field which contains the end timestamp of&#160;<em><strong>P</strong></em>.</p>
1027 </li>
1028 <li>
1029 <p><em>OPTIONAL</em>: A field which contains a snapshot of the
1030 <a href="#disc-er-counter">discarded event record counter</a> of&#160;<em><strong>S</strong></em> at
1031 the end of&#160;<em><strong>P</strong></em>.</p>
1032 </li>
1033 <li>
1034 <p><em>OPTIONAL</em>: A field which contains the sequence number
1035 of&#160;<em><strong>P</strong></em> within&#160;<em><strong>S</strong></em>.</p>
1036 </li>
1037 <li>
1038 <p><em>OPTIONAL</em>: User fields.</p>
1039 </li>
1040 </ul>
1041 </div>
1042 </li>
1043 <li>
1044 <p>Zero or more <a href="#er">event records</a>.</p>
1045 </li>
1046 </ol>
1047 </div>
1048 <div class="paragraph">
1049 <p>A packet <em>MUST</em> contain one or more bytes of data.</p>
1050 </div>
1051 <div class="paragraph">
1052 <p>A packet <em>MAY</em> contain padding (garbage data) after its <em>last</em> event
1053 record. The size of this padding is the difference between its total
1054 size and its content size (as found in its <a href="#pkt-ctx">context structure
1055 field</a>).</p>
1056 </div>
1057 <div class="paragraph">
1058 <p>Packets are independent of each other: if one removes a packet from a
1059 data stream, a <a href="#consumer-def">consumer</a> can still decode the whole data
1060 stream. This is why:</p>
1061 </div>
1062 <div class="ulist">
1063 <ul>
1064 <li>
1065 <p>Packets <em>MAY</em> contain <em>snapshots</em> of the <a href="#disc-er-counter">discarded
1066 event record counter</a> of their data stream.</p>
1067 </li>
1068 <li>
1069 <p>Packets and event records <em>MAY</em> contain <em>timestamps</em> which are
1070 snapshots of the <a href="#def-clk">default clock</a> of their data stream.</p>
1071 </li>
1072 </ul>
1073 </div>
1074 <div class="paragraph">
1075 <p>If the <a href="#pkt-ctx">packet context</a> fields of the packets of a data stream
1076 contain a <a href="#pkt-seq-num-role">packet sequence number</a> field, a consumer
1077 can recognize missing packets.</p>
1078 </div>
1079 <div class="paragraph">
1080 <p>See <a href="#pkt-dec">Packet decoding procedure</a> to learn how to decode a CTF&#160;2 packet.</p>
1081 </div>
1082 </div>
1083 <div class="sect3">
1084 <h4 id="er">4.2.2. Event record</h4>
1085 <div class="paragraph">
1086 <p>An <em>event record</em> is the result of a <a href="#producer-def">producer</a> writing a
1087 record with <em>OPTIONAL</em> user data when an event occurs during its
1088 execution.</p>
1089 </div>
1090 <div class="paragraph">
1091 <p>A <a href="#pkt">packet</a> contains zero or more event records.</p>
1092 </div>
1093 <div class="paragraph">
1094 <p>An <a href="#erc-frag">event record class</a> describes the specific parts of event
1095 records.</p>
1096 </div>
1097 <div class="paragraph">
1098 <p>An event record <em><strong>E</strong></em>, contained in a <a href="#ds">data stream</a>&#160;<em><strong>S</strong></em>,
1099 contains, in this order:</p>
1100 </div>
1101 <div class="olist arabic">
1102 <ol class="arabic">
1103 <li>
1104 <p><a id="er-header"></a> <em>OPTIONAL</em>: A <strong>header</strong> <a href="#struct-fc">structure</a> field,
1105 described at the <a href="#dsc-frag">data stream class</a> level in the metadata
1106 stream, which contains, in any order:</p>
1107 <div class="ulist">
1108 <ul>
1109 <li>
1110 <p><em>OPTIONAL</em>: One or more fields which contain the numeric ID of the
1111 <a href="#erc-frag">class</a> of&#160;<em><strong>E</strong></em> which has the class
1112 of&#160;<em><strong>S</strong></em> as its parent.</p>
1113 </li>
1114 <li>
1115 <p><em>OPTIONAL</em>: One or more fields which contain a timestamp or a partial
1116 timestamp.</p>
1117 </li>
1118 </ul>
1119 </div>
1120 </li>
1121 <li>
1122 <p><a id="er-common-ctx"></a> <em>OPTIONAL</em>: A <strong>common context</strong>
1123 <a href="#struct-fc">structure</a> field, described at the data stream class
1124 level in the metadata stream, which contains user fields.</p>
1125 </li>
1126 <li>
1127 <p><a id="er-spec-ctx"></a> <em>OPTIONAL</em>: A <strong>specific context</strong>
1128 <a href="#struct-fc">structure</a> field, described at the event record class
1129 level in the metadata stream, which contains user fields.</p>
1130 </li>
1131 <li>
1132 <p><a id="er-payload"></a> <em>OPTIONAL</em>: A <strong>payload</strong> <a href="#struct-fc">structure</a> field,
1133 described at the event record class level in the metadata stream,
1134 which contains user fields.</p>
1135 </li>
1136 </ol>
1137 </div>
1138 <div class="paragraph">
1139 <p>An event record <em>MUST</em> contain one or more bits of data.</p>
1140 </div>
1141 <div class="paragraph">
1142 <p>The <a href="#def-clk">default clock</a> timestamp of an event record, that is, the
1143 value of the default clock of its <a href="#ds">data stream</a> <em>after</em> its
1144 <a href="#er-header">header field</a>, if any, is encoded/decoded <em>MUST</em> be greater
1145 than or equal to the default clock timestamp of the previous event
1146 record, if any, within the <em>same</em> data stream.</p>
1147 </div>
1148 <div class="paragraph">
1149 <p>See <a href="#er-dec">Event record decoding procedure</a> to learn how to decode a CTF&#160;2 event record.</p>
1150 </div>
1151 </div>
1152 </div>
1153 <div class="sect2">
1154 <h3 id="aux-stream">4.3. Auxiliary stream</h3>
1155 <div class="paragraph">
1156 <p>An auxiliary stream is a JSON text sequence, as specified by <a href="https://datatracker.ietf.org/doc/html/rfc7464">RFC&#160;7464</a>,
1157 which contains extra, structured information about the trace which
1158 doesn&#8217;t fit the <a href="#ds">data stream</a> model.</p>
1159 </div>
1160 <div class="paragraph">
1161 <p>Each element of an auxiliary stream is a JSON object which has a single
1162 property:</p>
1163 </div>
1164 <div class="hdlist">
1165 <table>
1166 <tr>
1167 <td class="hdlist1">
1168 Name
1169 </td>
1170 <td class="hdlist2">
1171 <p><a href="#ns-def">Namespace</a> of the auxiliary stream.</p>
1172 </td>
1173 </tr>
1174 <tr>
1175 <td class="hdlist1">
1176 Value
1177 </td>
1178 <td class="hdlist2">
1179 <p>A JSON value.</p>
1180 </td>
1181 </tr>
1182 </table>
1183 </div>
1184 <div class="exampleblock">
1185 <div class="title">Example 1. Auxiliary stream element with the <code>my.tracer</code> namespace.</div>
1186 <div class="content">
1187 <div class="listingblock">
1188 <div class="content">
1189 <pre class="highlight"><code class="language-json" data-lang="json">{
1190   "my.tracer": {
1191     "version": [1, 3, 2],
1192     "session-name": "amqui"
1193   }
1194 }</code></pre>
1195 </div>
1196 </div>
1197 </div>
1198 </div>
1199 <div class="exampleblock">
1200 <div class="title">Example 2. Auxiliary stream element of which the value is just <code>42</code>.</div>
1201 <div class="content">
1202 <div class="listingblock">
1203 <div class="content">
1204 <pre class="highlight"><code class="language-json" data-lang="json">{
1205   "328c7a2d-a959-4f60-bd22-cca74359326f": 42
1206 }</code></pre>
1207 </div>
1208 </div>
1209 </div>
1210 </div>
1211 <div class="sect3">
1212 <h4 id="env">4.3.1. Trace environment</h4>
1213 <div class="paragraph">
1214 <p>To remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>, a trace <em>MAY</em> contain an
1215 auxiliary stream having an element with the <code>std</code> namespace which
1216 contains trace environment variables under the <code>environment</code> property.</p>
1217 </div>
1218 <div class="paragraph">
1219 <p>The trace environment variables are a single JSON object where each
1220 property is:</p>
1221 </div>
1222 <div class="hdlist">
1223 <table>
1224 <tr>
1225 <td class="hdlist1">
1226 Name
1227 </td>
1228 <td class="hdlist2">
1229 <p>Trace environment variable name.</p>
1230 </td>
1231 </tr>
1232 <tr>
1233 <td class="hdlist1">
1234 Value
1235 </td>
1236 <td class="hdlist2">
1237 <p>Trace environment variable value (any JSON value).</p>
1238 </td>
1239 </tr>
1240 </table>
1241 </div>
1242 <div class="paragraph">
1243 <p>This document doesn&#8217;t specify trace environment variable names.</p>
1244 </div>
1245 <div class="exampleblock">
1246 <div class="title">Example 3. <code>std</code> auxiliary stream element with trace environment variables.</div>
1247 <div class="content">
1248 <div class="listingblock">
1249 <div class="content">
1250 <pre class="highlight"><code class="language-json" data-lang="json">{
1251   "std": {
1252     "environment": {
1253       "hostname": "amqui",
1254       "domain": "kernel",
1255       "sysname": "Linux",
1256       "kernel_release": "4.12.12-1-ARCH",
1257       "kernel_version": "#1 SMP PREEMPT Sun Sep 10 09:41:14 CEST 2017",
1258       "tracer_name": "lttng-modules",
1259       "tracer_major": 2,
1260       "tracer_minor": 10,
1261       "tracer_patchlevel": 0
1262     }
1263   }
1264 }</code></pre>
1265 </div>
1266 </div>
1267 </div>
1268 </div>
1269 </div>
1270 </div>
1271 </div>
1272 </div>
1273 <div class="sect1">
1274 <h2 id="metadata-stream">5. Metadata stream</h2>
1275 <div class="sectionbody">
1276 <div class="paragraph">
1277 <p>A metadata stream is a JSON text sequence, as specified by <a href="https://datatracker.ietf.org/doc/html/rfc7464">RFC&#160;7464</a>,
1278 of <em>fragments</em>.</p>
1279 </div>
1280 <div class="paragraph">
1281 <p>Together, the fragments of a metadata stream contain all the information
1282 about the <a href="#ds">data streams</a> of one or more <a href="#trace">traces</a>.</p>
1283 </div>
1284 <div class="paragraph">
1285 <p><a id="frag"></a> A <em>fragment</em> is a JSON object; its allowed properties depend on
1286 its <code>type</code> property.</p>
1287 </div>
1288 <table class="tableblock frame-all grid-all fit-content">
1289 <caption class="title">Table 2. Common properties of a fragment <em><strong>F</strong></em>.</caption>
1290 <colgroup>
1291 <col>
1292 <col>
1293 <col>
1294 <col>
1295 <col>
1296 </colgroup>
1297 <thead>
1298 <tr>
1299 <th class="tableblock halign-left valign-top">Name</th>
1300 <th class="tableblock halign-left valign-top">Type</th>
1301 <th class="tableblock halign-left valign-top">Description</th>
1302 <th class="tableblock halign-left valign-top">Required?</th>
1303 <th class="tableblock halign-left valign-top">Default</th>
1304 </tr>
1305 </thead>
1306 <tbody>
1307 <tr>
1308 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
1309 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
1310 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1311 <p>Type of&#160;<em><strong>F</strong></em>.</p>
1312 </div>
1313 <div class="paragraph">
1314 <p>The value of this property <em>MUST</em> be one of:</p>
1315 </div>
1316 <div class="dlist">
1317 <dl>
1318 <dt class="hdlist1"><code>"preamble"</code></dt>
1319 <dd>
1320 <p><em><strong>F</strong></em> is a <a href="#preamble-frag">preamble fragment</a>.</p>
1321 </dd>
1322 <dt class="hdlist1"><code>"trace-class"</code></dt>
1323 <dd>
1324 <p><em><strong>F</strong></em> is a <a href="#tc-frag">trace class fragment</a>.</p>
1325 </dd>
1326 <dt class="hdlist1"><code>"clock-class"</code></dt>
1327 <dd>
1328 <p><em><strong>F</strong></em> is a <a href="#cc-frag">clock class fragment</a>.</p>
1329 </dd>
1330 <dt class="hdlist1"><code>"data-stream-class"</code></dt>
1331 <dd>
1332 <p><em><strong>F</strong></em> is a <a href="#dsc-frag">data stream class fragment</a>.</p>
1333 </dd>
1334 <dt class="hdlist1"><code>"event-record-class"</code></dt>
1335 <dd>
1336 <p><em><strong>F</strong></em> is a <a href="#erc-frag">event record class fragment</a>.</p>
1337 </dd>
1338 </dl>
1339 </div></div></td>
1340 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
1341 <td class="tableblock halign-left valign-top"></td>
1342 </tr>
1343 <tr>
1344 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
1345 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
1346 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1347 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
1348 </div></div></td>
1349 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
1350 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
1351 </tr>
1352 <tr>
1353 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
1354 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
1355 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1356 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
1357 </div>
1358 <div class="paragraph">
1359 <p>For any fragment except a <a href="#preamble-frag">preamble fragment</a>, any
1360 extension which exists under this property <em>MUST</em> also be declared in
1361 the preamble fragment of the same metadata stream.</p>
1362 </div></div></td>
1363 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
1364 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
1365 </tr>
1366 </tbody>
1367 </table>
1368 <div class="paragraph">
1369 <p>The metadata stream is a JSON text sequence of fragments instead of a
1370 single JSON object containing nested objects to enable real-time, or
1371 &#8220;live&#8221;, tracing: a <a href="#consumer-def">consumer</a> can always decode
1372 <a href="#er">event records</a> having known <a href="#erc-frag">event record classes</a>
1373 while a <a href="#producer-def">producer</a> can always add new event record
1374 classes to a <a href="#dsc-frag">data stream class</a> by appending additional
1375 fragments to the metadata stream. Once a producer appends a fragment to
1376 a metadata stream, the fragment is considered &#8220;frozen&#8221;, in that it
1377 never needs to change.</p>
1378 </div>
1379 <div class="paragraph">
1380 <p>A metadata stream:</p>
1381 </div>
1382 <div class="ulist">
1383 <ul>
1384 <li>
1385 <p><em>MUST</em> start with a preamble fragment.</p>
1386 </li>
1387 <li>
1388 <p><em>MUST</em> contain exactly one <a href="#preamble-frag">preamble fragment</a>.</p>
1389 </li>
1390 <li>
1391 <p><em>MAY</em> contain one <a href="#tc-frag">trace class fragment</a>.</p>
1392 </li>
1393 <li>
1394 <p><em>MUST</em> contain one or more <a href="#dsc-frag">data stream class fragments</a>
1395 which <em>MUST</em> follow the trace class fragment, if any.</p>
1396 </li>
1397 <li>
1398 <p><em>MAY</em> contain one or more <a href="#er-frag">event record class fragments</a>
1399 which <em>MUST</em> follow their parent data stream class, if any.</p>
1400 </li>
1401 </ul>
1402 </div>
1403 <div class="exampleblock">
1404 <div class="title">Example 4. Partial metadata stream.</div>
1405 <div class="content">
1406 <div class="paragraph">
1407 <p>In the sample below, the string <code>&lt;RS&gt;</code> represents a single record
1408 separator character (U+001E) and the string <code>[...]</code> represents
1409 continuation.</p>
1410 </div>
1411 <div class="listingblock">
1412 <div class="content">
1413 <pre>&lt;RS&gt;{
1414   "type": "preamble",
1415   "version": 2
1416 }
1417 &lt;RS&gt;[...]</pre>
1418 </div>
1419 </div>
1420 </div>
1421 </div>
1422 <div class="admonitionblock note">
1423 <table>
1424 <tr>
1425 <td class="icon">
1426 <i class="fa icon-note" title="Note"></i>
1427 </td>
1428 <td class="content">
1429 <div class="paragraph">
1430 <p>This section doesn&#8217;t specify how a metadata stream translates into
1431 <a href="#ds">data stream</a> encoding and decoding rules; it only describes
1432 objects and their properties.</p>
1433 </div>
1434 <div class="paragraph">
1435 <p>See <a href="#ds-dec">Data stream decoding procedure</a> to learn how to decode a data stream.</p>
1436 </div>
1437 </td>
1438 </tr>
1439 </table>
1440 </div>
1441 <div class="sect2">
1442 <h3 id="uuid">5.1. UUID</h3>
1443 <div class="paragraph">
1444 <p>Both a <a href="#tc-frag">trace class fragment</a> and a <a href="#cc-frag">clock class
1445 fragment</a> <em>MAY</em> have a
1446 <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier"><em>UUID</em></a>
1447 property.</p>
1448 </div>
1449 <div class="paragraph">
1450 <p>Within a metadata stream, a UUID is a JSON array of 16&#160;JSON
1451 integers which are the numeric values of the 16&#160;bytes of the
1452 UUID.</p>
1453 </div>
1454 <div class="exampleblock">
1455 <div class="title">Example 5. <code>e53e0ab8-50a1-4f0a-b710-b5f0bba9c4ac</code> UUID.</div>
1456 <div class="content">
1457 <div class="listingblock">
1458 <div class="content">
1459 <pre class="highlight"><code class="language-json" data-lang="json">[229, 62, 10, 184, 80, 161, 79, 10, 183, 16, 181, 240, 187, 169, 196, 172]</code></pre>
1460 </div>
1461 </div>
1462 </div>
1463 </div>
1464 </div>
1465 <div class="sect2">
1466 <h3 id="ext">5.2. Extensions</h3>
1467 <div class="paragraph">
1468 <p>A <a href="#producer-def">producer</a> <em>MAY</em> add <em>extensions</em> to many metadata
1469 stream JSON objects.</p>
1470 </div>
1471 <div class="paragraph">
1472 <p>The purpose of an extension is to add core features to CTF&#160;2 or to
1473 modify existing core features, as specified by this document. In other
1474 words, an extension <em>MAY</em> <strong>alter</strong> the format itself.</p>
1475 </div>
1476 <div class="paragraph">
1477 <p>This document doesn&#8217;t specify what an extension exactly is.</p>
1478 </div>
1479 <div class="paragraph">
1480 <p>The <a href="#preamble-frag">preamble fragment</a> of the metadata stream contains
1481 <em>extension declarations</em>:</p>
1482 </div>
1483 <div class="ulist">
1484 <ul>
1485 <li>
1486 <p>Any extension in metadata stream objects <em>MUST</em> be declared, by
1487 namespace and name, in the preamble fragment.</p>
1488 <div class="paragraph">
1489 <p>Declaring an extension is said to <em>enable</em> it.</p>
1490 </div>
1491 </li>
1492 <li>
1493 <p>If a <a href="#consumer-def">consumer</a> doesn&#8217;t support <em>any</em> declared
1494 extension, it <em>MUST&#160;NOT</em> consume the <a href="#ds">data streams</a> of the
1495 <a href="#trace">trace</a>.</p>
1496 <div class="paragraph">
1497 <p>The consumer <em>SHOULD</em> report unsupported extensions as an error.</p>
1498 </div>
1499 </li>
1500 </ul>
1501 </div>
1502 <div class="paragraph">
1503 <p>Extensions are a single JSON object, where each property is:</p>
1504 </div>
1505 <div class="hdlist">
1506 <table>
1507 <tr>
1508 <td class="hdlist1">
1509 Name
1510 </td>
1511 <td class="hdlist2">
1512 <p>A <a href="#ns-def">namespace</a></p>
1513 </td>
1514 </tr>
1515 <tr>
1516 <td class="hdlist1">
1517 Value
1518 </td>
1519 <td class="hdlist2">
1520 <p>A <a href="#ns-exts-obj">namespaced extensions object</a></p>
1521 </td>
1522 </tr>
1523 </table>
1524 </div>
1525 <div class="paragraph">
1526 <p><a id="ns-exts-obj"></a> A <em>namespaced extensions object</em> is a JSON object, where
1527 each property is:</p>
1528 </div>
1529 <div class="hdlist">
1530 <table>
1531 <tr>
1532 <td class="hdlist1">
1533 Name
1534 </td>
1535 <td class="hdlist2">
1536 <p>An extension name</p>
1537 </td>
1538 </tr>
1539 <tr>
1540 <td class="hdlist1">
1541 Value
1542 </td>
1543 <td class="hdlist2">
1544 <p>A JSON value</p>
1545 </td>
1546 </tr>
1547 </table>
1548 </div>
1549 <div class="paragraph">
1550 <p>The metadata stream JSON objects which <em>MAY</em> contain extensions as their
1551 <code>extensions</code> property are:</p>
1552 </div>
1553 <div class="ulist">
1554 <ul>
1555 <li>
1556 <p>Any <a href="#frag">fragment</a>.</p>
1557 <div class="paragraph">
1558 <p>An extension in the <a href="#preamble-frag">preamble fragment</a> also makes it
1559 <em>declared</em>/<em>enabled</em>.</p>
1560 </div>
1561 </li>
1562 <li>
1563 <p>Any <a href="#fc">field class</a>.</p>
1564 </li>
1565 <li>
1566 <p>A <a href="#struct-member-cls">structure field member class</a>.</p>
1567 </li>
1568 <li>
1569 <p>A <a href="#var-fc-opt">variant field class option</a>.</p>
1570 </li>
1571 </ul>
1572 </div>
1573 <div class="exampleblock">
1574 <div class="title">Example 6. Three extensions under two namespaces.</div>
1575 <div class="content">
1576 <div class="listingblock">
1577 <div class="content">
1578 <pre class="highlight"><code class="language-json" data-lang="json">{
1579   "my.tracer": {
1580     "piano": {
1581       "keys": 88,
1582       "temperament": "equal"
1583     },
1584     "ramen": 23
1585   },
1586   "abc/xyz": {
1587     "sax": {
1588       "variant": "alto"
1589     }
1590   }
1591 }</code></pre>
1592 </div>
1593 </div>
1594 </div>
1595 </div>
1596 </div>
1597 <div class="sect2">
1598 <h3 id="user-attrs">5.3. User attributes</h3>
1599 <div class="paragraph">
1600 <p>A <a href="#producer-def">producer</a> <em>MAY</em> add custom <em>user attributes</em> to many
1601 metadata stream JSON objects.</p>
1602 </div>
1603 <div class="paragraph">
1604 <p>This document doesn&#8217;t specify what a user attribute exactly is.</p>
1605 </div>
1606 <div class="paragraph">
1607 <p>Unlike <a href="#ext">extensions</a>, a <a href="#consumer-def">consumer</a> <em>MUST&#160;NOT</em>
1608 consider user attributes to decode <a href="#ds">data streams</a>.</p>
1609 </div>
1610 <div class="paragraph">
1611 <p>User attributes are a single JSON object, where each property is:</p>
1612 </div>
1613 <div class="hdlist">
1614 <table>
1615 <tr>
1616 <td class="hdlist1">
1617 Name
1618 </td>
1619 <td class="hdlist2">
1620 <p>A <a href="#ns-def">namespace</a></p>
1621 </td>
1622 </tr>
1623 <tr>
1624 <td class="hdlist1">
1625 Value
1626 </td>
1627 <td class="hdlist2">
1628 <p>A JSON value</p>
1629 </td>
1630 </tr>
1631 </table>
1632 </div>
1633 <div class="paragraph">
1634 <p>The metadata stream JSON objects which <em>MAY</em> contain user attributes
1635 as their <code>user-attributes</code> property are:</p>
1636 </div>
1637 <div class="ulist">
1638 <ul>
1639 <li>
1640 <p>Any <a href="#frag">fragment</a>.</p>
1641 </li>
1642 <li>
1643 <p>Any <a href="#fc">field class</a>.</p>
1644 </li>
1645 <li>
1646 <p>A <a href="#struct-member-cls">structure field member class</a>.</p>
1647 </li>
1648 <li>
1649 <p>A <a href="#var-fc-opt">variant field class option</a>.</p>
1650 </li>
1651 </ul>
1652 </div>
1653 <div class="exampleblock">
1654 <div class="title">Example 7. User attributes under two namespaces.</div>
1655 <div class="content">
1656 <div class="listingblock">
1657 <div class="content">
1658 <pre class="highlight"><code class="language-json" data-lang="json">{
1659   "my.tracer": {
1660     "max-count": 45,
1661     "module": "sys"
1662   },
1663   "abc/xyz": true
1664 }</code></pre>
1665 </div>
1666 </div>
1667 </div>
1668 </div>
1669 </div>
1670 <div class="sect2">
1671 <h3 id="fc">5.4. Field classes</h3>
1672 <div class="paragraph">
1673 <p>A <em>field class</em> describes fields, that is, <a href="#seq-def">sequences</a> of bits
1674 as found in a <a href="#ds">data stream</a>.</p>
1675 </div>
1676 <div class="paragraph">
1677 <p>A field class contains all the properties a <a href="#consumer-def">consumer</a>
1678 needs to <a href="#ds-dec">decode</a> a given field.</p>
1679 </div>
1680 <div class="paragraph">
1681 <p>A <em>field</em> is a field class instance.</p>
1682 </div>
1683 <div class="paragraph">
1684 <p>This document specifies the following types of field classes:</p>
1685 </div>
1686 <div class="dlist">
1687 <dl>
1688 <dt class="hdlist1">Abstract field classes</dt>
1689 <dd>
1690 <p>One cannot use the following field classes directly: they are bases
1691 for other, concrete field classes:</p>
1692 <div class="ulist">
1693 <ul>
1694 <li>
1695 <p><a href="#int-fc">Abstract integer field class</a></p>
1696 </li>
1697 <li>
1698 <p><a href="#enum-fc">Abstract enumeration field class</a></p>
1699 </li>
1700 <li>
1701 <p><a href="#array-fc">Abstract array field class</a></p>
1702 </li>
1703 <li>
1704 <p><a href="#blob-fc">Abstract BLOB field class</a></p>
1705 </li>
1706 </ul>
1707 </div>
1708 </dd>
1709 <dt class="hdlist1">Fixed/static-length field classes</dt>
1710 <dd>
1711 <div class="ulist">
1712 <ul>
1713 <li>
1714 <p><a href="#fl-ba-fc">Fixed-length bit array field class</a></p>
1715 </li>
1716 <li>
1717 <p><a href="#fl-bool-fc">Fixed-length boolean field class</a></p>
1718 </li>
1719 <li>
1720 <p><a href="#fl-int-fc">Fixed-length integer field class</a></p>
1721 </li>
1722 <li>
1723 <p><a href="#fl-enum-fc">Fixed-length enumeration field class</a></p>
1724 </li>
1725 <li>
1726 <p><a href="#fl-fp-fc">Fixed-length floating point number field class</a></p>
1727 </li>
1728 <li>
1729 <p><a href="#sl-str-fc">Static-length string field class</a></p>
1730 </li>
1731 <li>
1732 <p><a href="#sl-blob-fc">Static-length BLOB field class</a></p>
1733 </li>
1734 </ul>
1735 </div>
1736 </dd>
1737 <dt class="hdlist1">Variable/dynamic-length field classes</dt>
1738 <dd>
1739 <div class="ulist">
1740 <ul>
1741 <li>
1742 <p><a href="#vl-ba-fc">Variable-length bit array field class</a></p>
1743 </li>
1744 <li>
1745 <p><a href="#vl-int-fc">Variable-length integer field class</a></p>
1746 </li>
1747 <li>
1748 <p><a href="#vl-enum-fc">Variable-length enumeration field class</a></p>
1749 </li>
1750 <li>
1751 <p><a href="#str-fc">Null-terminated string field class</a></p>
1752 </li>
1753 <li>
1754 <p><a href="#dl-str-fc">Dynamic-length string field class</a></p>
1755 </li>
1756 <li>
1757 <p><a href="#dl-blob-fc">Dynamic-length BLOB field class</a></p>
1758 </li>
1759 </ul>
1760 </div>
1761 </dd>
1762 <dt class="hdlist1">Compound field classes</dt>
1763 <dd>
1764 <p>The following field classes contain one or more field classes.</p>
1765 <div class="ulist">
1766 <ul>
1767 <li>
1768 <p><a href="#struct-fc">Structure field class</a></p>
1769 </li>
1770 <li>
1771 <p><a href="#sl-array-fc">Static-length array field class</a></p>
1772 </li>
1773 <li>
1774 <p><a href="#dl-array-fc">Dynamic-length array field class</a></p>
1775 </li>
1776 <li>
1777 <p><a href="#opt-fc">Optional field class</a></p>
1778 </li>
1779 <li>
1780 <p><a href="#var-fc">Variant field class</a></p>
1781 </li>
1782 </ul>
1783 </div>
1784 </dd>
1785 </dl>
1786 </div>
1787 <div class="paragraph">
1788 <p>A field class is a JSON object; its properties depend on its <code>type</code>
1789 property.</p>
1790 </div>
1791 <table class="tableblock frame-all grid-all fit-content">
1792 <caption class="title">Table 3. Common properties of a field class <em><strong>F</strong></em>.</caption>
1793 <colgroup>
1794 <col>
1795 <col>
1796 <col>
1797 <col>
1798 <col>
1799 </colgroup>
1800 <thead>
1801 <tr>
1802 <th class="tableblock halign-left valign-top">Name</th>
1803 <th class="tableblock halign-left valign-top">Type</th>
1804 <th class="tableblock halign-left valign-top">Description</th>
1805 <th class="tableblock halign-left valign-top">Required?</th>
1806 <th class="tableblock halign-left valign-top">Default</th>
1807 </tr>
1808 </thead>
1809 <tbody>
1810 <tr>
1811 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
1812 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
1813 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1814 <p>Type of&#160;<em><strong>F</strong></em>.</p>
1815 </div>
1816 <div class="paragraph">
1817 <p>The value of this property <em>MUST</em> be one of:</p>
1818 </div>
1819 <div class="dlist">
1820 <dl>
1821 <dt class="hdlist1"><code>"fixed-length-bit-array"</code></dt>
1822 <dd>
1823 <p><em><strong>F</strong></em> is a <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
1824 </dd>
1825 <dt class="hdlist1"><code>"fixed-length-boolean"</code></dt>
1826 <dd>
1827 <p><em><strong>F</strong></em> is a <a href="#fl-bool-fc">fixed-length boolean field class</a>.</p>
1828 </dd>
1829 <dt class="hdlist1"><code>"fixed-length-unsigned-integer"</code></dt>
1830 <dt class="hdlist1"><code>"fixed-length-signed-integer"</code></dt>
1831 <dd>
1832 <p><em><strong>F</strong></em> is a <a href="#fl-int-fc">fixed-length integer field class</a>.</p>
1833 </dd>
1834 <dt class="hdlist1"><code>"fixed-length-unsigned-enumeration"</code></dt>
1835 <dt class="hdlist1"><code>"fixed-length-signed-enumeration"</code></dt>
1836 <dd>
1837 <p><em><strong>F</strong></em> is a <a href="#fl-enum-fc">fixed-length enumeration field class</a>.</p>
1838 </dd>
1839 <dt class="hdlist1"><code>"fixed-length-floating-point-number"</code></dt>
1840 <dd>
1841 <p><em><strong>F</strong></em> is a <a href="#fl-fp-fc">fixed-length floating point number field class</a>.</p>
1842 </dd>
1843 <dt class="hdlist1"><code>"variable-length-bit-array"</code></dt>
1844 <dd>
1845 <p><em><strong>F</strong></em> is a <a href="#vl-ba-fc">variable-length bit array field class</a>.</p>
1846 </dd>
1847 <dt class="hdlist1"><code>"variable-length-unsigned-integer"</code></dt>
1848 <dt class="hdlist1"><code>"variable-length-signed-integer"</code></dt>
1849 <dd>
1850 <p><em><strong>F</strong></em> is a <a href="#vl-int-fc">variable-length integer field class</a>.</p>
1851 </dd>
1852 <dt class="hdlist1"><code>"variable-length-unsigned-enumeration"</code></dt>
1853 <dt class="hdlist1"><code>"variable-length-signed-enumeration"</code></dt>
1854 <dd>
1855 <p><em><strong>F</strong></em> is a <a href="#vl-enum-fc">variable-length enumeration field class</a>.</p>
1856 </dd>
1857 <dt class="hdlist1"><code>"null-terminated-string"</code></dt>
1858 <dd>
1859 <p><em><strong>F</strong></em> is a <a href="#str-fc">null-terminated string field class</a>.</p>
1860 </dd>
1861 <dt class="hdlist1"><code>"static-length-string"</code></dt>
1862 <dd>
1863 <p><em><strong>F</strong></em> is a <a href="#sl-str-fc">static-length string field class</a>.</p>
1864 </dd>
1865 <dt class="hdlist1"><code>"static-length-blob"</code></dt>
1866 <dd>
1867 <p><em><strong>F</strong></em> is a <a href="#sl-blob-fc">static-length BLOB field class</a>.</p>
1868 </dd>
1869 <dt class="hdlist1"><code>"dynamic-length-string"</code></dt>
1870 <dd>
1871 <p><em><strong>F</strong></em> is a <a href="#dl-str-fc">dynamic-length string field class</a>.</p>
1872 </dd>
1873 <dt class="hdlist1"><code>"dynamic-length-blob"</code></dt>
1874 <dd>
1875 <p><em><strong>F</strong></em> is a <a href="#dl-blob-fc">dynamic-length BLOB field class</a>.</p>
1876 </dd>
1877 <dt class="hdlist1"><code>"structure"</code></dt>
1878 <dd>
1879 <p><em><strong>F</strong></em> is a <a href="#struct-fc">structure field class</a>.</p>
1880 </dd>
1881 <dt class="hdlist1"><code>"static-length-array"</code></dt>
1882 <dd>
1883 <p><em><strong>F</strong></em> is a <a href="#sl-array-fc">static-length array field class</a>.</p>
1884 </dd>
1885 <dt class="hdlist1"><code>"dynamic-length-array"</code></dt>
1886 <dd>
1887 <p><em><strong>F</strong></em> is a <a href="#dl-array-fc">dynamic-length array field class</a>.</p>
1888 </dd>
1889 <dt class="hdlist1"><code>"optional"</code></dt>
1890 <dd>
1891 <p><em><strong>F</strong></em> is a <a href="#opt-fc">optional field class</a>.</p>
1892 </dd>
1893 <dt class="hdlist1"><code>"variant"</code></dt>
1894 <dd>
1895 <p><em><strong>F</strong></em> is a <a href="#var-fc">variant field class</a>.</p>
1896 </dd>
1897 </dl>
1898 </div></div></td>
1899 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
1900 <td class="tableblock halign-left valign-top"></td>
1901 </tr>
1902 <tr>
1903 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
1904 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
1905 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1906 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
1907 </div>
1908 <div class="paragraph">
1909 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
1910 root field classes.</p>
1911 </div></div></td>
1912 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
1913 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
1914 </tr>
1915 <tr>
1916 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
1917 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
1918 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1919 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
1920 </div></div></td>
1921 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
1922 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
1923 </tr>
1924 <tr>
1925 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
1926 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
1927 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1928 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
1929 </div>
1930 <div class="paragraph">
1931 <p>Any extension which exists under this property <em>MUST</em> also be declared
1932 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
1933 </div></div></td>
1934 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
1935 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
1936 </tr>
1937 </tbody>
1938 </table>
1939 <div class="paragraph">
1940 <p>The following <a href="#frag">fragment</a> properties <em>MUST</em> have a <a href="#struct-fc">structure field class</a> as
1941 their value:</p>
1942 </div>
1943 <div class="dlist">
1944 <dl>
1945 <dt class="hdlist1"><a href="#tc-frag">Trace class fragment</a></dt>
1946 <dd>
1947 <p><code>packet-header-field-class</code></p>
1948 </dd>
1949 <dt class="hdlist1"><a href="#dsc-frag">Data stream class fragment</a></dt>
1950 <dd>
1951 <div class="ulist">
1952 <ul>
1953 <li>
1954 <p><code>packet-context-field-class</code></p>
1955 </li>
1956 <li>
1957 <p><code>event-record-header-field-class</code></p>
1958 </li>
1959 <li>
1960 <p><code>event-record-common-context-field-class</code></p>
1961 </li>
1962 </ul>
1963 </div>
1964 </dd>
1965 <dt class="hdlist1"><a href="#erc-frag">Event record class fragment</a></dt>
1966 <dd>
1967 <div class="ulist">
1968 <ul>
1969 <li>
1970 <p><code>specific-context-field-class</code></p>
1971 </li>
1972 <li>
1973 <p><code>payload-field-class</code></p>
1974 </li>
1975 </ul>
1976 </div>
1977 </dd>
1978 </dl>
1979 </div>
1980 <div class="sect3">
1981 <h4 id="field-loc">5.4.1. Field location</h4>
1982 <div class="paragraph">
1983 <p>A <em>field location</em> is a means for a <a href="#consumer-def">consumer</a> to locate
1984 a field which it needs to <a href="#ds-dec">decode</a> another, subsequent field.</p>
1985 </div>
1986 <div class="paragraph">
1987 <p>A consumer needs to locate another field to decode instances of the
1988 following <a href="#fc">classes</a>:</p>
1989 </div>
1990 <div class="dlist">
1991 <dl>
1992 <dt class="hdlist1"><a href="#dl-array-fc">Dynamic-length array field class</a></dt>
1993 <dt class="hdlist1"><a href="#dl-str-fc">Dynamic-length string field class</a></dt>
1994 <dt class="hdlist1"><a href="#dl-blob-fc">Dynamic-length BLOB field class</a></dt>
1995 <dd>
1996 <p>Needs a <a href="#fl-int-fc">fixed-length unsigned integer</a> or
1997 <a href="#vl-int-fc">variable-length unsigned integer</a> length field.</p>
1998 </dd>
1999 <dt class="hdlist1"><a href="#opt-fc">Optional field class</a></dt>
2000 <dd>
2001 <p>Needs a <a href="#fl-bool-fc">fixed-length boolean</a>, <a href="#fl-int-fc">fixed-length integer</a>, or
2002 <a href="#vl-int-fc">variable-length integer</a> selector field.</p>
2003 </dd>
2004 <dt class="hdlist1"><a href="#var-fc">Variant field class</a></dt>
2005 <dd>
2006 <p>Needs a <a href="#fl-int-fc">fixed-length integer</a> or <a href="#vl-int-fc">variable-length integer</a> selector
2007 field.</p>
2008 </dd>
2009 </dl>
2010 </div>
2011 <div class="paragraph">
2012 <p>Let <em><strong>T</strong></em> be an anteriorly decoded field which a consumer needs to
2013 decode another field&#160;<em><strong>S</strong></em>. A field location is a JSON array
2014 where, in this order:</p>
2015 </div>
2016 <div class="olist arabic">
2017 <ol class="arabic">
2018 <li>
2019 <p>The first element is the name (JSON string) of a root field from
2020 where to start the lookup of&#160;<em><strong>T</strong></em>, amongst:</p>
2021 <div class="openblock">
2022 <div class="content">
2023 <div class="hdlist">
2024 <table>
2025 <tr>
2026 <td class="hdlist1">
2027 <code>"packet-header"</code>
2028 </td>
2029 <td class="hdlist2">
2030 <p><a href="#pkt-header">Header</a> of the <a href="#pkt">packet</a> of&#160;<em><strong>S</strong></em>.</p>
2031 </td>
2032 </tr>
2033 <tr>
2034 <td class="hdlist1">
2035 <code>"packet-context"</code>
2036 </td>
2037 <td class="hdlist2">
2038 <p><a href="#pkt-ctx">Context</a> of the packet of&#160;<em><strong>S</strong></em>.</p>
2039 </td>
2040 </tr>
2041 <tr>
2042 <td class="hdlist1">
2043 <code>"event-record-header"</code>
2044 </td>
2045 <td class="hdlist2">
2046 <p><a href="#er-header">Header</a> of the <a href="#er">event record</a> of&#160;<em><strong>S</strong></em>.</p>
2047 </td>
2048 </tr>
2049 <tr>
2050 <td class="hdlist1">
2051 <code>"event-record-common-context"</code>
2052 </td>
2053 <td class="hdlist2">
2054 <p><a href="#er-common-ctx">Common context</a> of the event record of&#160;<em><strong>S</strong></em>.</p>
2055 </td>
2056 </tr>
2057 <tr>
2058 <td class="hdlist1">
2059 <code>"event-record-specific-context"</code>
2060 </td>
2061 <td class="hdlist2">
2062 <p><a href="#er-spec-ctx">Specific context</a> of the event record of&#160;<em><strong>S</strong></em>.</p>
2063 </td>
2064 </tr>
2065 <tr>
2066 <td class="hdlist1">
2067 <code>"event-record-payload"</code>
2068 </td>
2069 <td class="hdlist2">
2070 <p><a href="#er-payload">Payload</a> of the event record of&#160;<em><strong>S</strong></em>.</p>
2071 </td>
2072 </tr>
2073 </table>
2074 </div>
2075 </div>
2076 </div>
2077 <div class="paragraph">
2078 <p>In other words, <em><strong>T</strong></em> <em>MUST</em> be in the same packet or event record
2079 as&#160;<em><strong>S</strong></em>.</p>
2080 </div>
2081 </li>
2082 <li>
2083 <p>The following elements are <a href="#struct-fc">structure</a> field member names
2084 (JSON strings) to follow to locate the target field.</p>
2085 </li>
2086 </ol>
2087 </div>
2088 <div class="paragraph">
2089 <p>The length of a field location <em>MUST</em> be greater than or equal to two.</p>
2090 </div>
2091 <div class="paragraph">
2092 <p>See <a href="#field-loc-dec">Field location procedure</a> to learn how to locate a field with a field
2093 location.</p>
2094 </div>
2095 </div>
2096 <div class="sect3">
2097 <h4 id="int-range-set">5.4.2. Integer range set</h4>
2098 <div class="paragraph">
2099 <p>An <em>integer range set</em> is a JSON array of integer ranges.</p>
2100 </div>
2101 <div class="paragraph">
2102 <p>An integer range set <em>MUST</em> contain one or more integer ranges.</p>
2103 </div>
2104 <div class="paragraph">
2105 <p>An <em>integer range</em> is a JSON array of two elements:</p>
2106 </div>
2107 <div class="olist arabic">
2108 <ol class="arabic">
2109 <li>
2110 <p>The lower bound of the range (JSON integer, included).</p>
2111 </li>
2112 <li>
2113 <p>The upper bound of the range (JSON integer, included).</p>
2114 </li>
2115 </ol>
2116 </div>
2117 <div class="paragraph">
2118 <p>An integer range represents all the integer values from the lower bound
2119 of the range to its upper bound.</p>
2120 </div>
2121 <div class="paragraph">
2122 <p>The upper bound of an integer range <em>MUST</em> be greater than or equal to
2123 its lower bound.</p>
2124 </div>
2125 <div class="paragraph">
2126 <p>If both the lower and upper bounds of an integer range are equal, then
2127 the integer range represents a single integer value.</p>
2128 </div>
2129 <div class="exampleblock">
2130 <div class="title">Example 8. Integer ranges.</div>
2131 <div class="content">
2132 <div class="listingblock">
2133 <div class="content">
2134 <pre class="highlight"><code class="language-json" data-lang="json">[3, 67]</code></pre>
2135 </div>
2136 </div>
2137 <div class="listingblock">
2138 <div class="content">
2139 <pre class="highlight"><code class="language-json" data-lang="json">[-45, 101]</code></pre>
2140 </div>
2141 </div>
2142 <div class="listingblock">
2143 <div class="title">Single integer value.</div>
2144 <div class="content">
2145 <pre class="highlight"><code class="language-json" data-lang="json">[42, 42]</code></pre>
2146 </div>
2147 </div>
2148 </div>
2149 </div>
2150 <div class="exampleblock">
2151 <div class="title">Example 9. Integer range set containing three integer ranges.</div>
2152 <div class="content">
2153 <div class="listingblock">
2154 <div class="content">
2155 <pre class="highlight"><code class="language-json" data-lang="json">[[3, 67], [-45, 1], [42, 42]]</code></pre>
2156 </div>
2157 </div>
2158 </div>
2159 </div>
2160 </div>
2161 <div class="sect3">
2162 <h4 id="roles">5.4.3. Roles</h4>
2163 <div class="paragraph">
2164 <p>Some <a href="#fc">field class</a> instances can have <em>roles</em>.</p>
2165 </div>
2166 <div class="paragraph">
2167 <p>A role is specific semantics attached to the fields (instances) of a
2168 field class. For example, the <code>packet-magic-number</code> role of a
2169 <a href="#fl-int-fc">fixed-length integer field class</a> indicates that the value of its instances <em>MUST</em> be the
2170 <a href="#pkt">packet</a> magic number (0xc1fc1fc1).</p>
2171 </div>
2172 <div class="paragraph">
2173 <p>Roles are a JSON array of role names (JSON strings).</p>
2174 </div>
2175 <div class="paragraph">
2176 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted roles within
2177 their root field classes.</p>
2178 </div>
2179 </div>
2180 <div class="sect3">
2181 <h4 id="fl-ba-fc">5.4.4. Fixed-length bit array field class</h4>
2182 <div class="paragraph">
2183 <p>A <em>fixed-length bit array</em> field class describes <em>fixed-length bit array</em> fields.</p>
2184 </div>
2185 <div class="paragraph">
2186 <p>A fixed-length bit array field is a simple array of contiguous bits, without any
2187 attached integer type semantics.</p>
2188 </div>
2189 <div class="paragraph">
2190 <p>The length, or number of bits, of a fixed-length bit array field is a property
2191 (<code>length</code>) of its class.</p>
2192 </div>
2193 <div class="paragraph">
2194 <p>A fixed-length bit array field class acts as a base of a <a href="#fl-bool-fc">fixed-length boolean field class</a>, a <a href="#fl-int-fc">fixed-length integer field class</a>,
2195 and a <a href="#fl-fp-fc">fixed-length floating point number field class</a>.</p>
2196 </div>
2197 <table class="tableblock frame-all grid-all fit-content">
2198 <caption class="title">Table 4. Common properties of a fixed-length bit array field class <em><strong>F</strong></em>.</caption>
2199 <colgroup>
2200 <col>
2201 <col>
2202 <col>
2203 <col>
2204 <col>
2205 </colgroup>
2206 <thead>
2207 <tr>
2208 <th class="tableblock halign-left valign-top">Name</th>
2209 <th class="tableblock halign-left valign-top">Type</th>
2210 <th class="tableblock halign-left valign-top">Description</th>
2211 <th class="tableblock halign-left valign-top">Required?</th>
2212 <th class="tableblock halign-left valign-top">Default</th>
2213 </tr>
2214 </thead>
2215 <tbody>
2216 <tr>
2217 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
2218 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
2219 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2220 <p>Type of&#160;<em><strong>F</strong></em>.</p>
2221 </div>
2222 <div class="paragraph">
2223 <p>The value of this property <em>MUST</em> be <code>"fixed-length-bit-array"</code>.</p>
2224 </div></div></td>
2225 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2226 <td class="tableblock halign-left valign-top"></td>
2227 </tr>
2228 <tr>
2229 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
2230 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2231 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2232 <p>Number of bits of an instance of&#160;<em><strong>F</strong></em>.</p>
2233 </div>
2234 <div class="paragraph">
2235 <p>The value of this property <em>MUST</em> be greater than zero.</p>
2236 </div></div></td>
2237 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2238 <td class="tableblock halign-left valign-top"></td>
2239 </tr>
2240 <tr>
2241 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>byte-order</code></p></td>
2242 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
2243 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2244 <p><a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a> of an instance of&#160;<em><strong>F</strong></em>.</p>
2245 </div>
2246 <div class="paragraph">
2247 <p>The value of this property <em>MUST</em> be one of:</p>
2248 </div>
2249 <div class="dlist">
2250 <dl>
2251 <dt class="hdlist1"><code>"big-endian"</code></dt>
2252 <dd>
2253 <p>Big-endian.</p>
2254 </dd>
2255 <dt class="hdlist1"><code>"little-endian"</code></dt>
2256 <dd>
2257 <p>Little-endian.</p>
2258 </dd>
2259 </dl>
2260 </div></div></td>
2261 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2262 <td class="tableblock halign-left valign-top"></td>
2263 </tr>
2264 <tr>
2265 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>alignment</code></p></td>
2266 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2267 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2268 <p>Alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
2269 relative to the beginning of the <a href="#pkt">packet</a> which
2270 contains this instance.</p>
2271 </div>
2272 <div class="paragraph">
2273 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
2274 </div></div></td>
2275 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2276 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
2277 </tr>
2278 <tr>
2279 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
2280 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
2281 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2282 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
2283 </div>
2284 <div class="paragraph">
2285 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
2286 root field classes.</p>
2287 </div></div></td>
2288 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2289 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
2290 </tr>
2291 <tr>
2292 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
2293 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
2294 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2295 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
2296 </div></div></td>
2297 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2298 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
2299 </tr>
2300 <tr>
2301 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
2302 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
2303 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2304 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
2305 </div>
2306 <div class="paragraph">
2307 <p>Any extension which exists under this property <em>MUST</em> also be declared
2308 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
2309 </div></div></td>
2310 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2311 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
2312 </tr>
2313 </tbody>
2314 </table>
2315 <div class="exampleblock">
2316 <div class="title">Example 10. Minimal fixed-length bit array field class.</div>
2317 <div class="content">
2318 <div class="listingblock">
2319 <div class="content">
2320 <pre class="highlight"><code class="language-json" data-lang="json">{
2321   "type": "fixed-length-bit-array",
2322   "length": 16,
2323   "byte-order": "little-endian"
2324 }</code></pre>
2325 </div>
2326 </div>
2327 </div>
2328 </div>
2329 <div class="exampleblock">
2330 <div class="title">Example 11. Fixed-length bit array field class with instances aligned to 32&#160;bits.</div>
2331 <div class="content">
2332 <div class="listingblock">
2333 <div class="content">
2334 <pre class="highlight"><code class="language-json" data-lang="json">{
2335   "type": "fixed-length-bit-array",
2336   "length": 48,
2337   "byte-order": "big-endian",
2338   "alignment": 32
2339 }</code></pre>
2340 </div>
2341 </div>
2342 </div>
2343 </div>
2344 <div class="exampleblock">
2345 <div class="title">Example 12. Fixed-length bit array field class with <a href="#user-attrs">user attributes</a>.</div>
2346 <div class="content">
2347 <div class="listingblock">
2348 <div class="content">
2349 <pre class="highlight"><code class="language-json" data-lang="json">{
2350   "type": "fixed-length-bit-array",
2351   "length": 16,
2352   "byte-order": "little-endian",
2353   "user-attributes": {
2354     "my.tracer": {
2355       "is-nice": true
2356     }
2357   }
2358 }</code></pre>
2359 </div>
2360 </div>
2361 </div>
2362 </div>
2363 </div>
2364 <div class="sect3">
2365 <h4 id="fl-bool-fc">5.4.5. Fixed-length boolean field class</h4>
2366 <div class="paragraph">
2367 <p>A <em>fixed-length boolean</em> field class is a <a href="#fl-ba-fc">fixed-length bit array field class</a> which describes <em>fixed-length boolean</em>
2368 fields.</p>
2369 </div>
2370 <div class="paragraph">
2371 <p>A fixed-length boolean field is a fixed-length bit array field which has the following semantics:</p>
2372 </div>
2373 <div class="dlist">
2374 <dl>
2375 <dt class="hdlist1">If all the bits of the bit array field are cleared (zero)</dt>
2376 <dd>
2377 <p>The value of the fixed-length boolean field is <em>false</em>.</p>
2378 </dd>
2379 <dt class="hdlist1">Otherwise</dt>
2380 <dd>
2381 <p>The value of the fixed-length boolean field is <em>true</em>.</p>
2382 </dd>
2383 </dl>
2384 </div>
2385 <table class="tableblock frame-all grid-all fit-content">
2386 <caption class="title">Table 5. Properties of a fixed-length boolean field class <em><strong>F</strong></em>.</caption>
2387 <colgroup>
2388 <col>
2389 <col>
2390 <col>
2391 <col>
2392 <col>
2393 </colgroup>
2394 <thead>
2395 <tr>
2396 <th class="tableblock halign-left valign-top">Name</th>
2397 <th class="tableblock halign-left valign-top">Type</th>
2398 <th class="tableblock halign-left valign-top">Description</th>
2399 <th class="tableblock halign-left valign-top">Required?</th>
2400 <th class="tableblock halign-left valign-top">Default</th>
2401 </tr>
2402 </thead>
2403 <tbody>
2404 <tr>
2405 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
2406 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
2407 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2408 <p>Type of&#160;<em><strong>F</strong></em>.</p>
2409 </div>
2410 <div class="paragraph">
2411 <p>The value of this property <em>MUST</em> be <code>"fixed-length-boolean"</code>.</p>
2412 </div></div></td>
2413 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2414 <td class="tableblock halign-left valign-top"></td>
2415 </tr>
2416 <tr>
2417 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
2418 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2419 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2420 <p>Number of bits of an instance of&#160;<em><strong>F</strong></em>.</p>
2421 </div>
2422 <div class="paragraph">
2423 <p>The value of this property <em>MUST</em> be greater than zero.</p>
2424 </div>
2425 <div class="paragraph">
2426 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
2427 </div></div></td>
2428 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2429 <td class="tableblock halign-left valign-top"></td>
2430 </tr>
2431 <tr>
2432 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>byte-order</code></p></td>
2433 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
2434 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2435 <p><a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a> of an instance
2436 of&#160;<em><strong>F</strong></em>.</p>
2437 </div>
2438 <div class="paragraph">
2439 <p>The value of this property <em>MUST</em> be one of:</p>
2440 </div>
2441 <div class="dlist">
2442 <dl>
2443 <dt class="hdlist1"><code>"big-endian"</code></dt>
2444 <dd>
2445 <p>Big-endian.</p>
2446 </dd>
2447 <dt class="hdlist1"><code>"little-endian"</code></dt>
2448 <dd>
2449 <p>Little-endian.</p>
2450 </dd>
2451 </dl>
2452 </div>
2453 <div class="paragraph">
2454 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
2455 </div></div></td>
2456 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2457 <td class="tableblock halign-left valign-top"></td>
2458 </tr>
2459 <tr>
2460 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>alignment</code></p></td>
2461 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2462 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2463 <p>Alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
2464 relative to the beginning of the <a href="#pkt">packet</a> which
2465 contains this instance.</p>
2466 </div>
2467 <div class="paragraph">
2468 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
2469 </div>
2470 <div class="paragraph">
2471 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
2472 </div></div></td>
2473 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2474 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
2475 </tr>
2476 <tr>
2477 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
2478 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
2479 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2480 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
2481 </div>
2482 <div class="paragraph">
2483 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
2484 root field classes.</p>
2485 </div></div></td>
2486 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2487 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
2488 </tr>
2489 <tr>
2490 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
2491 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
2492 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2493 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
2494 </div></div></td>
2495 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2496 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
2497 </tr>
2498 <tr>
2499 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
2500 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
2501 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2502 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
2503 </div>
2504 <div class="paragraph">
2505 <p>Any extension which exists under this property <em>MUST</em> also be declared
2506 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
2507 </div></div></td>
2508 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2509 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
2510 </tr>
2511 </tbody>
2512 </table>
2513 <div class="exampleblock">
2514 <div class="title">Example 13. Minimal fixed-length boolean field class.</div>
2515 <div class="content">
2516 <div class="listingblock">
2517 <div class="content">
2518 <pre class="highlight"><code class="language-json" data-lang="json">{
2519   "type": "fixed-length-boolean",
2520   "length": 16,
2521   "byte-order": "little-endian"
2522 }</code></pre>
2523 </div>
2524 </div>
2525 </div>
2526 </div>
2527 <div class="exampleblock">
2528 <div class="title">Example 14. Fixed-length boolean field class with instances aligned to 32&#160;bits.</div>
2529 <div class="content">
2530 <div class="listingblock">
2531 <div class="content">
2532 <pre class="highlight"><code class="language-json" data-lang="json">{
2533   "type": "fixed-length-boolean",
2534   "length": 48,
2535   "byte-order": "big-endian",
2536   "alignment": 32
2537 }</code></pre>
2538 </div>
2539 </div>
2540 </div>
2541 </div>
2542 <div class="exampleblock">
2543 <div class="title">Example 15. Fixed-length boolean field class with <a href="#user-attrs">user attributes</a>.</div>
2544 <div class="content">
2545 <div class="listingblock">
2546 <div class="content">
2547 <pre class="highlight"><code class="language-json" data-lang="json">{
2548   "type": "fixed-length-boolean",
2549   "length": 16,
2550   "byte-order": "little-endian",
2551   "user-attributes": {
2552     "my.tracer": {
2553       "is-nice": true
2554     }
2555   }
2556 }</code></pre>
2557 </div>
2558 </div>
2559 </div>
2560 </div>
2561 </div>
2562 <div class="sect3">
2563 <h4 id="int-fc">5.4.6. Abstract integer field class</h4>
2564 <div class="paragraph">
2565 <p>An <em>abstract integer</em> field class is a base of a <a href="#fl-int-fc">fixed-length integer field class</a> and a
2566 <a href="#vl-int-fc">variable-length integer field class</a>.</p>
2567 </div>
2568 <div class="paragraph">
2569 <p>This field class is abstract in that it only exists to show the relation
2570 between different integer field classes in this document: a
2571 <a href="#pkt">packet</a> cannot contain an abstract integer field.</p>
2572 </div>
2573 <table class="tableblock frame-all grid-all fit-content">
2574 <caption class="title">Table 6. Common property of an integer field class <em><strong>F</strong></em>.</caption>
2575 <colgroup>
2576 <col>
2577 <col>
2578 <col>
2579 <col>
2580 <col>
2581 </colgroup>
2582 <thead>
2583 <tr>
2584 <th class="tableblock halign-left valign-top">Name</th>
2585 <th class="tableblock halign-left valign-top">Type</th>
2586 <th class="tableblock halign-left valign-top">Description</th>
2587 <th class="tableblock halign-left valign-top">Required?</th>
2588 <th class="tableblock halign-left valign-top">Default</th>
2589 </tr>
2590 </thead>
2591 <tbody>
2592 <tr>
2593 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>preferred-display-base</code></p></td>
2594 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2595 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2596 <p>Preferred base to display the value of an instance of&#160;<em><strong>F</strong></em>.</p>
2597 </div>
2598 <div class="paragraph">
2599 <p>The value of this property <em>MUST</em> be one of:</p>
2600 </div>
2601 <div class="hdlist">
2602 <table>
2603 <tr>
2604 <td class="hdlist1">
2605 <code>2</code>
2606 </td>
2607 <td class="hdlist2">
2608 <p>Binary base.</p>
2609 </td>
2610 </tr>
2611 <tr>
2612 <td class="hdlist1">
2613 <code>8</code>
2614 </td>
2615 <td class="hdlist2">
2616 <p>Octal base.</p>
2617 </td>
2618 </tr>
2619 <tr>
2620 <td class="hdlist1">
2621 <code>10</code>
2622 </td>
2623 <td class="hdlist2">
2624 <p>Decimal base.</p>
2625 </td>
2626 </tr>
2627 <tr>
2628 <td class="hdlist1">
2629 <code>16</code>
2630 </td>
2631 <td class="hdlist2">
2632 <p>Hexadecimal base.</p>
2633 </td>
2634 </tr>
2635 </table>
2636 </div>
2637 <div class="paragraph">
2638 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
2639 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
2640 </div></div></td>
2641 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2642 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
2643 </tr>
2644 </tbody>
2645 </table>
2646 </div>
2647 <div class="sect3">
2648 <h4 id="fl-int-fc">5.4.7. Fixed-length integer field class</h4>
2649 <div class="paragraph">
2650 <p>A <em>fixed-length integer</em> field class is both an <a href="#int-fc">abstract integer field
2651 class</a> and a <a href="#fl-ba-fc">fixed-length bit array field class</a> which describes <em>fixed-length integer</em> fields.</p>
2652 </div>
2653 <div class="paragraph">
2654 <p>A fixed-length integer field is a fixed-length bit array field which has integer semantics.</p>
2655 </div>
2656 <div class="paragraph">
2657 <p>If the value of the <code>type</code> property of a fixed-length integer is
2658 <code>"fixed-length-signed-integer"</code>, then its instances have the two&#8217;s
2659 complement format.</p>
2660 </div>
2661 <div class="paragraph">
2662 <p>A fixed-length integer field class acts as a base of a <a href="#fl-enum-fc">fixed-length enumeration field class</a>.</p>
2663 </div>
2664 <table class="tableblock frame-all grid-all fit-content">
2665 <caption class="title">Table 7. Common properties of a fixed-length integer field class <em><strong>F</strong></em>.</caption>
2666 <colgroup>
2667 <col>
2668 <col>
2669 <col>
2670 <col>
2671 <col>
2672 </colgroup>
2673 <thead>
2674 <tr>
2675 <th class="tableblock halign-left valign-top">Name</th>
2676 <th class="tableblock halign-left valign-top">Type</th>
2677 <th class="tableblock halign-left valign-top">Description</th>
2678 <th class="tableblock halign-left valign-top">Required?</th>
2679 <th class="tableblock halign-left valign-top">Default</th>
2680 </tr>
2681 </thead>
2682 <tbody>
2683 <tr>
2684 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
2685 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
2686 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2687 <p>Type of&#160;<em><strong>F</strong></em>.</p>
2688 </div>
2689 <div class="paragraph">
2690 <p>The value of this property <em>MUST</em> be one of:</p>
2691 </div>
2692 <div class="dlist">
2693 <dl>
2694 <dt class="hdlist1"><code>"fixed-length-unsigned-integer"</code></dt>
2695 <dd>
2696 <p>The instances of&#160;<em><strong>F</strong></em> are fixed-length unsigned integer fields.</p>
2697 </dd>
2698 <dt class="hdlist1"><code>"fixed-length-signed-integer"</code></dt>
2699 <dd>
2700 <p>The instances of&#160;<em><strong>F</strong></em> are fixed-length signed integer fields.</p>
2701 </dd>
2702 </dl>
2703 </div></div></td>
2704 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2705 <td class="tableblock halign-left valign-top"></td>
2706 </tr>
2707 <tr>
2708 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
2709 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2710 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2711 <p>Number of bits of an instance of&#160;<em><strong>F</strong></em>.</p>
2712 </div>
2713 <div class="paragraph">
2714 <p>The value of this property <em>MUST</em> be greater than zero.</p>
2715 </div>
2716 <div class="paragraph">
2717 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
2718 </div></div></td>
2719 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2720 <td class="tableblock halign-left valign-top"></td>
2721 </tr>
2722 <tr>
2723 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>byte-order</code></p></td>
2724 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
2725 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2726 <p><a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a> of an instance
2727 of&#160;<em><strong>F</strong></em>.</p>
2728 </div>
2729 <div class="paragraph">
2730 <p>The value of this property <em>MUST</em> be one of:</p>
2731 </div>
2732 <div class="dlist">
2733 <dl>
2734 <dt class="hdlist1"><code>"big-endian"</code></dt>
2735 <dd>
2736 <p>Big-endian.</p>
2737 </dd>
2738 <dt class="hdlist1"><code>"little-endian"</code></dt>
2739 <dd>
2740 <p>Little-endian.</p>
2741 </dd>
2742 </dl>
2743 </div>
2744 <div class="paragraph">
2745 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
2746 </div></div></td>
2747 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
2748 <td class="tableblock halign-left valign-top"></td>
2749 </tr>
2750 <tr>
2751 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>alignment</code></p></td>
2752 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2753 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2754 <p>Alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
2755 relative to the beginning of the <a href="#pkt">packet</a> which
2756 contains this instance.</p>
2757 </div>
2758 <div class="paragraph">
2759 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
2760 </div>
2761 <div class="paragraph">
2762 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
2763 </div></div></td>
2764 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2765 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
2766 </tr>
2767 <tr>
2768 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>preferred-display-base</code></p></td>
2769 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2770 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2771 <p>Preferred base to display the value of an instance of&#160;<em><strong>F</strong></em>.</p>
2772 </div>
2773 <div class="paragraph">
2774 <p>The value of this property <em>MUST</em> be one of:</p>
2775 </div>
2776 <div class="hdlist">
2777 <table>
2778 <tr>
2779 <td class="hdlist1">
2780 <code>2</code>
2781 </td>
2782 <td class="hdlist2">
2783 <p>Binary base.</p>
2784 </td>
2785 </tr>
2786 <tr>
2787 <td class="hdlist1">
2788 <code>8</code>
2789 </td>
2790 <td class="hdlist2">
2791 <p>Octal base.</p>
2792 </td>
2793 </tr>
2794 <tr>
2795 <td class="hdlist1">
2796 <code>10</code>
2797 </td>
2798 <td class="hdlist2">
2799 <p>Decimal base.</p>
2800 </td>
2801 </tr>
2802 <tr>
2803 <td class="hdlist1">
2804 <code>16</code>
2805 </td>
2806 <td class="hdlist2">
2807 <p>Hexadecimal base.</p>
2808 </td>
2809 </tr>
2810 </table>
2811 </div>
2812 <div class="paragraph">
2813 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
2814 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
2815 </div>
2816 <div class="paragraph">
2817 <p>Property inherited from the <a href="#int-fc">abstract integer field class</a>.</p>
2818 </div></div></td>
2819 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2820 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
2821 </tr>
2822 <tr>
2823 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
2824 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
2825 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2826 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
2827 </div>
2828 <div class="paragraph">
2829 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
2830 root field classes.</p>
2831 </div></div></td>
2832 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2833 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
2834 </tr>
2835 <tr>
2836 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
2837 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
2838 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2839 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
2840 </div></div></td>
2841 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2842 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
2843 </tr>
2844 <tr>
2845 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
2846 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
2847 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2848 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
2849 </div>
2850 <div class="paragraph">
2851 <p>Any extension which exists under this property <em>MUST</em> also be declared
2852 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
2853 </div></div></td>
2854 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
2855 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
2856 </tr>
2857 </tbody>
2858 </table>
2859 <div class="exampleblock">
2860 <div class="title">Example 16. Minimal fixed-length unsigned integer field class.</div>
2861 <div class="content">
2862 <div class="listingblock">
2863 <div class="content">
2864 <pre class="highlight"><code class="language-json" data-lang="json">{
2865   "type": "fixed-length-unsigned-integer",
2866   "length": 16,
2867   "byte-order": "little-endian"
2868 }</code></pre>
2869 </div>
2870 </div>
2871 </div>
2872 </div>
2873 <div class="exampleblock">
2874 <div class="title">Example 17. Fixed-length signed integer field class with instances aligned to 32&#160;bits.</div>
2875 <div class="content">
2876 <div class="listingblock">
2877 <div class="content">
2878 <pre class="highlight"><code class="language-json" data-lang="json">{
2879   "type": "fixed-length-signed-integer",
2880   "length": 48,
2881   "byte-order": "big-endian",
2882   "alignment": 32
2883 }</code></pre>
2884 </div>
2885 </div>
2886 </div>
2887 </div>
2888 <div class="exampleblock">
2889 <div class="title">Example 18. Fixed-length unsigned integer field class with instances to be preferably displayed with a hexadecimal base.</div>
2890 <div class="content">
2891 <div class="listingblock">
2892 <div class="content">
2893 <pre class="highlight"><code class="language-json" data-lang="json">{
2894   "type": "fixed-length-unsigned-integer",
2895   "length": 48,
2896   "byte-order": "big-endian",
2897   "preferred-display-base": 16
2898 }</code></pre>
2899 </div>
2900 </div>
2901 </div>
2902 </div>
2903 <div class="exampleblock">
2904 <div class="title">Example 19. Fixed-length signed integer field class with <a href="#user-attrs">user attributes</a>.</div>
2905 <div class="content">
2906 <div class="listingblock">
2907 <div class="content">
2908 <pre class="highlight"><code class="language-json" data-lang="json">{
2909   "type": "fixed-length-signed-integer",
2910   "length": 16,
2911   "byte-order": "little-endian",
2912   "user-attributes": {
2913     "my.tracer": {
2914       "is-nice": true
2915     }
2916   }
2917 }</code></pre>
2918 </div>
2919 </div>
2920 </div>
2921 </div>
2922 </div>
2923 <div class="sect3">
2924 <h4 id="enum-fc">5.4.8. Abstract enumeration field class</h4>
2925 <div class="paragraph">
2926 <p>An <em>abstract enumeration</em> field class is a base of a <a href="#fl-enum-fc">fixed-length enumeration field class</a> and a
2927 <a href="#vl-enum-fc">variable-length enumeration field class</a>.</p>
2928 </div>
2929 <div class="paragraph">
2930 <p>This field class is abstract in that it only exists to show the relation
2931 between different enumeration field classes in this document: a
2932 <a href="#pkt">packet</a> cannot contain an abstract enumeration field.</p>
2933 </div>
2934 <div class="paragraph">
2935 <p>An abstract enumeration field class is an <a href="#int-fc">abstract integer
2936 field class</a>.</p>
2937 </div>
2938 <div class="paragraph">
2939 <p>An enumeration field is an integer field which <em>MAY</em> have one or more
2940 associated names thanks to the <code>mappings</code> property of its class.</p>
2941 </div>
2942 <table class="tableblock frame-all grid-all fit-content">
2943 <caption class="title">Table 8. Common property of an enumeration field class <em><strong>F</strong></em>.</caption>
2944 <colgroup>
2945 <col>
2946 <col>
2947 <col>
2948 <col>
2949 <col>
2950 </colgroup>
2951 <thead>
2952 <tr>
2953 <th class="tableblock halign-left valign-top">Name</th>
2954 <th class="tableblock halign-left valign-top">Type</th>
2955 <th class="tableblock halign-left valign-top">Description</th>
2956 <th class="tableblock halign-left valign-top">Required?</th>
2957 <th class="tableblock halign-left valign-top">Default</th>
2958 </tr>
2959 </thead>
2960 <tbody>
2961 <tr>
2962 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>preferred-display-base</code></p></td>
2963 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
2964 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
2965 <p>Preferred base to display the value of an instance of&#160;<em><strong>F</strong></em>.</p>
2966 </div>
2967 <div class="paragraph">
2968 <p>The value of this property <em>MUST</em> be one of:</p>
2969 </div>
2970 <div class="hdlist">
2971 <table>
2972 <tr>
2973 <td class="hdlist1">
2974 <code>2</code>
2975 </td>
2976 <td class="hdlist2">
2977 <p>Binary base.</p>
2978 </td>
2979 </tr>
2980 <tr>
2981 <td class="hdlist1">
2982 <code>8</code>
2983 </td>
2984 <td class="hdlist2">
2985 <p>Octal base.</p>
2986 </td>
2987 </tr>
2988 <tr>
2989 <td class="hdlist1">
2990 <code>10</code>
2991 </td>
2992 <td class="hdlist2">
2993 <p>Decimal base.</p>
2994 </td>
2995 </tr>
2996 <tr>
2997 <td class="hdlist1">
2998 <code>16</code>
2999 </td>
3000 <td class="hdlist2">
3001 <p>Hexadecimal base.</p>
3002 </td>
3003 </tr>
3004 </table>
3005 </div>
3006 <div class="paragraph">
3007 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
3008 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
3009 </div>
3010 <div class="paragraph">
3011 <p>Property inherited from the <a href="#int-fc">abstract integer field class</a>.</p>
3012 </div></div></td>
3013 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3014 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
3015 </tr>
3016 <tr>
3017 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mappings</code></p></td>
3018 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#enum-fc-mappings">Enumeration field class mappings</a></p></td>
3019 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3020 <p>Mappings of&#160;<em><strong>F</strong></em>.</p>
3021 </div>
3022 <div class="paragraph">
3023 <p>The value of this property <em>MUST</em> contain one or more properties.</p>
3024 </div></div></td>
3025 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3026 <td class="tableblock halign-left valign-top"></td>
3027 </tr>
3028 </tbody>
3029 </table>
3030 <div class="sect4">
3031 <h5 id="enum-fc-mappings">5.4.8.1. Enumeration field class mappings</h5>
3032 <div class="paragraph">
3033 <p><em>Enumeration field class mappings</em> map names to
3034 <a href="#int-range-set">integer range sets</a>.</p>
3035 </div>
3036 <div class="paragraph">
3037 <p>Enumeration field class mappings are a JSON object, where each property
3038 is:</p>
3039 </div>
3040 <div class="hdlist">
3041 <table>
3042 <tr>
3043 <td class="hdlist1">
3044 Name
3045 </td>
3046 <td class="hdlist2">
3047 <p>Mapping name.</p>
3048 </td>
3049 </tr>
3050 <tr>
3051 <td class="hdlist1">
3052 Value
3053 </td>
3054 <td class="hdlist2">
3055 <p>Mapped ranges of integers (<a href="#int-range-set">integer range set</a>).</p>
3056 </td>
3057 </tr>
3058 </table>
3059 </div>
3060 <div class="paragraph">
3061 <p>The integer ranges of two given mappings <em>MAY</em> overlap.</p>
3062 </div>
3063 <div class="paragraph">
3064 <p>Enumeration field class mappings <em>MUST</em> contain one or more properties.</p>
3065 </div>
3066 <div class="exampleblock">
3067 <div class="title">Example 20. Enumeration field class mappings with three mappings.</div>
3068 <div class="content">
3069 <div class="paragraph">
3070 <p>In this example, the <code>fortune</code> and <code>building</code> mappings overlap with the
3071 values 4 and 5, and the <code>building</code> and <code>journal</code> mappings overlap with
3072 the value 80.</p>
3073 </div>
3074 <div class="listingblock">
3075 <div class="content">
3076 <pre class="highlight"><code class="language-json" data-lang="json">{
3077   "fortune": [[3, 67], [-45, 1], [84, 84]],
3078   "building": [[4, 5], [75, 82]],
3079   "journal": [[100, 2305], [80, 80]]
3080 }</code></pre>
3081 </div>
3082 </div>
3083 </div>
3084 </div>
3085 </div>
3086 </div>
3087 <div class="sect3">
3088 <h4 id="fl-enum-fc">5.4.9. Fixed-length enumeration field class</h4>
3089 <div class="paragraph">
3090 <p>A <em>fixed-length enumeration</em> field class is both an <a href="#enum-fc">abstract enumeration
3091 field class</a> and a <a href="#fl-int-fc">fixed-length integer field class</a> which describes <em>fixed-length enumeration</em> fields.</p>
3092 </div>
3093 <div class="paragraph">
3094 <p>A fixed-length enumeration field is a fixed-length integer field which <em>MAY</em> have one or more
3095 associated names thanks to the <code>mappings</code> property of its class.</p>
3096 </div>
3097 <div class="paragraph">
3098 <p>If the value of the <code>type</code> property of a fixed-length enumeration field class is
3099 <code>"fixed-length-signed-enumeration"</code>, then its instances have the two&#8217;s
3100 complement format.</p>
3101 </div>
3102 <table class="tableblock frame-all grid-all fit-content">
3103 <caption class="title">Table 9. Properties of a fixed-length enumeration field class <em><strong>F</strong></em>.</caption>
3104 <colgroup>
3105 <col>
3106 <col>
3107 <col>
3108 <col>
3109 <col>
3110 </colgroup>
3111 <thead>
3112 <tr>
3113 <th class="tableblock halign-left valign-top">Name</th>
3114 <th class="tableblock halign-left valign-top">Type</th>
3115 <th class="tableblock halign-left valign-top">Description</th>
3116 <th class="tableblock halign-left valign-top">Required?</th>
3117 <th class="tableblock halign-left valign-top">Default</th>
3118 </tr>
3119 </thead>
3120 <tbody>
3121 <tr>
3122 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
3123 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3124 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3125 <p>Type of&#160;<em><strong>F</strong></em>.</p>
3126 </div>
3127 <div class="paragraph">
3128 <p>The value of this property <em>MUST</em> be one of:</p>
3129 </div>
3130 <div class="dlist">
3131 <dl>
3132 <dt class="hdlist1"><code>"fixed-length-unsigned-enumeration"</code></dt>
3133 <dd>
3134 <p>The instances of&#160;<em><strong>F</strong></em> are fixed-length unsigned enumeration fields.</p>
3135 </dd>
3136 <dt class="hdlist1"><code>"fixed-length-signed-enumeration"</code></dt>
3137 <dd>
3138 <p>The instances of&#160;<em><strong>F</strong></em> are fixed-length signed enumeration fields.</p>
3139 </dd>
3140 </dl>
3141 </div></div></td>
3142 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3143 <td class="tableblock halign-left valign-top"></td>
3144 </tr>
3145 <tr>
3146 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
3147 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3148 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3149 <p>Number of bits of an instance of&#160;<em><strong>F</strong></em>.</p>
3150 </div>
3151 <div class="paragraph">
3152 <p>The value of this property <em>MUST</em> be greater than zero.</p>
3153 </div>
3154 <div class="paragraph">
3155 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
3156 </div></div></td>
3157 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3158 <td class="tableblock halign-left valign-top"></td>
3159 </tr>
3160 <tr>
3161 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>byte-order</code></p></td>
3162 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3163 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3164 <p><a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a> of an instance
3165 of&#160;<em><strong>F</strong></em>.</p>
3166 </div>
3167 <div class="paragraph">
3168 <p>The value of this property <em>MUST</em> be one of:</p>
3169 </div>
3170 <div class="dlist">
3171 <dl>
3172 <dt class="hdlist1"><code>"big-endian"</code></dt>
3173 <dd>
3174 <p>Big-endian.</p>
3175 </dd>
3176 <dt class="hdlist1"><code>"little-endian"</code></dt>
3177 <dd>
3178 <p>Little-endian.</p>
3179 </dd>
3180 </dl>
3181 </div>
3182 <div class="paragraph">
3183 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
3184 </div></div></td>
3185 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3186 <td class="tableblock halign-left valign-top"></td>
3187 </tr>
3188 <tr>
3189 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>alignment</code></p></td>
3190 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3191 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3192 <p>Alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
3193 relative to the beginning of the <a href="#pkt">packet</a> which
3194 contains this instance.</p>
3195 </div>
3196 <div class="paragraph">
3197 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
3198 </div>
3199 <div class="paragraph">
3200 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
3201 </div></div></td>
3202 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3203 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
3204 </tr>
3205 <tr>
3206 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>preferred-display-base</code></p></td>
3207 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3208 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3209 <p>Preferred base to display the value of an instance of&#160;<em><strong>F</strong></em>.</p>
3210 </div>
3211 <div class="paragraph">
3212 <p>The value of this property <em>MUST</em> be one of:</p>
3213 </div>
3214 <div class="hdlist">
3215 <table>
3216 <tr>
3217 <td class="hdlist1">
3218 <code>2</code>
3219 </td>
3220 <td class="hdlist2">
3221 <p>Binary base.</p>
3222 </td>
3223 </tr>
3224 <tr>
3225 <td class="hdlist1">
3226 <code>8</code>
3227 </td>
3228 <td class="hdlist2">
3229 <p>Octal base.</p>
3230 </td>
3231 </tr>
3232 <tr>
3233 <td class="hdlist1">
3234 <code>10</code>
3235 </td>
3236 <td class="hdlist2">
3237 <p>Decimal base.</p>
3238 </td>
3239 </tr>
3240 <tr>
3241 <td class="hdlist1">
3242 <code>16</code>
3243 </td>
3244 <td class="hdlist2">
3245 <p>Hexadecimal base.</p>
3246 </td>
3247 </tr>
3248 </table>
3249 </div>
3250 <div class="paragraph">
3251 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
3252 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
3253 </div>
3254 <div class="paragraph">
3255 <p>Property inherited from the <a href="#int-fc">abstract integer field class</a>.</p>
3256 </div></div></td>
3257 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3258 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
3259 </tr>
3260 <tr>
3261 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mappings</code></p></td>
3262 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#enum-fc-mappings">Enumeration field class mappings</a></p></td>
3263 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3264 <p>Mappings of&#160;<em><strong>F</strong></em>.</p>
3265 </div>
3266 <div class="paragraph">
3267 <p>The value of this property <em>MUST</em> contain one or more properties.</p>
3268 </div>
3269 <div class="paragraph">
3270 <p>Property inherited from the <a href="#enum-fc">abstract enumeration field class</a>.</p>
3271 </div></div></td>
3272 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3273 <td class="tableblock halign-left valign-top"></td>
3274 </tr>
3275 <tr>
3276 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
3277 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
3278 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3279 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
3280 </div>
3281 <div class="paragraph">
3282 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
3283 root field classes.</p>
3284 </div></div></td>
3285 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3286 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
3287 </tr>
3288 <tr>
3289 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
3290 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
3291 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3292 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
3293 </div></div></td>
3294 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3295 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3296 </tr>
3297 <tr>
3298 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
3299 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
3300 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3301 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
3302 </div>
3303 <div class="paragraph">
3304 <p>Any extension which exists under this property <em>MUST</em> also be declared
3305 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
3306 </div></div></td>
3307 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3308 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3309 </tr>
3310 </tbody>
3311 </table>
3312 <div class="exampleblock">
3313 <div class="title">Example 21. Minimal fixed-length unsigned enumeration field class.</div>
3314 <div class="content">
3315 <div class="listingblock">
3316 <div class="content">
3317 <pre class="highlight"><code class="language-json" data-lang="json">{
3318   "type": "fixed-length-unsigned-enumeration",
3319   "length": 16,
3320   "byte-order": "little-endian",
3321   "mappings": {
3322     "apple": [[1, 19]]
3323   }
3324 }</code></pre>
3325 </div>
3326 </div>
3327 </div>
3328 </div>
3329 <div class="exampleblock">
3330 <div class="title">Example 22. Fixed-length signed enumeration field class with instances aligned to 32&#160;bits.</div>
3331 <div class="content">
3332 <div class="listingblock">
3333 <div class="content">
3334 <pre class="highlight"><code class="language-json" data-lang="json">{
3335   "type": "fixed-length-signed-enumeration",
3336   "length": 48,
3337   "byte-order": "big-endian",
3338   "alignment": 32,
3339   "mappings": {
3340     "banana": [[-27399, -1882], [8, 199], [101, 101]],
3341     "orange": [[67, 67], [43, 1534]]
3342   }
3343 }</code></pre>
3344 </div>
3345 </div>
3346 </div>
3347 </div>
3348 <div class="exampleblock">
3349 <div class="title">Example 23. Fixed-length unsigned enumeration field class with instances to be preferably displayed with a hexadecimal base.</div>
3350 <div class="content">
3351 <div class="listingblock">
3352 <div class="content">
3353 <pre class="highlight"><code class="language-json" data-lang="json">{
3354   "type": "fixed-length-unsigned-enumeration",
3355   "length": 8,
3356   "byte-order": "big-endian",
3357   "preferred-display-base": 16,
3358   "mappings": {
3359     "lime": [[3, 3]],
3360     "kiwi": [[8, 8]],
3361     "blueberry": [[11, 11]]
3362   }
3363 }</code></pre>
3364 </div>
3365 </div>
3366 </div>
3367 </div>
3368 <div class="exampleblock">
3369 <div class="title">Example 24. Fixed-length signed enumeration field class with <a href="#user-attrs">user attributes</a>.</div>
3370 <div class="content">
3371 <div class="listingblock">
3372 <div class="content">
3373 <pre class="highlight"><code class="language-json" data-lang="json">{
3374   "type": "fixed-length-signed-enumeration",
3375   "length": 16,
3376   "byte-order": "little-endian",
3377   "mappings": {
3378     "mango": [[23, 42]]
3379   },
3380   "user-attributes": {
3381     "my.tracer": {
3382       "is-nice": true
3383     }
3384   }
3385 }</code></pre>
3386 </div>
3387 </div>
3388 </div>
3389 </div>
3390 </div>
3391 <div class="sect3">
3392 <h4 id="fl-fp-fc">5.4.10. Fixed-length floating point number field class</h4>
3393 <div class="paragraph">
3394 <p>A <em>fixed-length floating point number</em> field class is a <a href="#fl-ba-fc">fixed-length bit array field class</a> which describes <em>fixed-length floating point number</em>
3395 fields.</p>
3396 </div>
3397 <div class="paragraph">
3398 <p>A fixed-length floating point number field is a fixed-length bit array field which has floating point number
3399 semantics.</p>
3400 </div>
3401 <table class="tableblock frame-all grid-all fit-content">
3402 <caption class="title">Table 10. Properties of a fixed-length floating point number field class <em><strong>F</strong></em>.</caption>
3403 <colgroup>
3404 <col>
3405 <col>
3406 <col>
3407 <col>
3408 <col>
3409 </colgroup>
3410 <thead>
3411 <tr>
3412 <th class="tableblock halign-left valign-top">Name</th>
3413 <th class="tableblock halign-left valign-top">Type</th>
3414 <th class="tableblock halign-left valign-top">Description</th>
3415 <th class="tableblock halign-left valign-top">Required?</th>
3416 <th class="tableblock halign-left valign-top">Default</th>
3417 </tr>
3418 </thead>
3419 <tbody>
3420 <tr>
3421 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
3422 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3423 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3424 <p>Type of&#160;<em><strong>F</strong></em>.</p>
3425 </div>
3426 <div class="paragraph">
3427 <p>The value of this property <em>MUST</em> be
3428 <code>"fixed-length-floating-point-number"</code>.</p>
3429 </div></div></td>
3430 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3431 <td class="tableblock halign-left valign-top"></td>
3432 </tr>
3433 <tr>
3434 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
3435 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3436 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3437 <p>Number of bits of an instance of&#160;<em><strong>F</strong></em>.</p>
3438 </div>
3439 <div class="paragraph">
3440 <p>The value of this property <em>MUST</em> be one of:</p>
3441 </div>
3442 <div class="dlist">
3443 <dl>
3444 <dt class="hdlist1"><code>16</code></dt>
3445 <dd>
3446 <p>The instances of&#160;<em><strong>F</strong></em> are binary16 floating point numbers,
3447 as per the <a href="https://standards.ieee.org/standard/754-2008.html">IEEE 754-2008</a> binary interchange format.</p>
3448 </dd>
3449 <dt class="hdlist1"><code>32</code></dt>
3450 <dd>
3451 <p>The instances of&#160;<em><strong>F</strong></em> are binary32 floating point numbers.</p>
3452 </dd>
3453 <dt class="hdlist1"><code>64</code></dt>
3454 <dd>
3455 <p>The instances of&#160;<em><strong>F</strong></em> are binary64 floating point numbers.</p>
3456 </dd>
3457 <dt class="hdlist1"><code>128</code></dt>
3458 <dd>
3459 <p>The instances of&#160;<em><strong>F</strong></em> are binary128 floating point
3460 numbers.</p>
3461 </dd>
3462 <dt class="hdlist1"><em><strong>K</strong></em>, where <em><strong>K</strong></em> is greater than&#160;128 and a multiple of&#160;32</dt>
3463 <dd>
3464 <p>The instances of&#160;<em><strong>F</strong></em> are binary<em><strong>K</strong></em> floating point
3465 numbers.</p>
3466 </dd>
3467 </dl>
3468 </div>
3469 <div class="paragraph">
3470 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
3471 </div></div></td>
3472 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3473 <td class="tableblock halign-left valign-top"></td>
3474 </tr>
3475 <tr>
3476 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>byte-order</code></p></td>
3477 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3478 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3479 <p><a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a> of an instance
3480 of&#160;<em><strong>F</strong></em>.</p>
3481 </div>
3482 <div class="paragraph">
3483 <p>The value of this property <em>MUST</em> be one of:</p>
3484 </div>
3485 <div class="dlist">
3486 <dl>
3487 <dt class="hdlist1"><code>"big-endian"</code></dt>
3488 <dd>
3489 <p>Big-endian.</p>
3490 </dd>
3491 <dt class="hdlist1"><code>"little-endian"</code></dt>
3492 <dd>
3493 <p>Little-endian.</p>
3494 </dd>
3495 </dl>
3496 </div>
3497 <div class="paragraph">
3498 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
3499 </div></div></td>
3500 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3501 <td class="tableblock halign-left valign-top"></td>
3502 </tr>
3503 <tr>
3504 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>alignment</code></p></td>
3505 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3506 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3507 <p>Alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
3508 relative to the beginning of the <a href="#pkt">packet</a> which
3509 contains this instance.</p>
3510 </div>
3511 <div class="paragraph">
3512 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
3513 </div>
3514 <div class="paragraph">
3515 <p>Property inherited from the <a href="#fl-ba-fc">fixed-length bit array field class</a>.</p>
3516 </div></div></td>
3517 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3518 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
3519 </tr>
3520 <tr>
3521 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
3522 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
3523 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3524 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
3525 </div>
3526 <div class="paragraph">
3527 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
3528 root field classes.</p>
3529 </div></div></td>
3530 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3531 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
3532 </tr>
3533 <tr>
3534 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
3535 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
3536 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3537 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
3538 </div></div></td>
3539 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3540 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3541 </tr>
3542 <tr>
3543 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
3544 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
3545 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3546 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
3547 </div>
3548 <div class="paragraph">
3549 <p>Any extension which exists under this property <em>MUST</em> also be declared
3550 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
3551 </div></div></td>
3552 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3553 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3554 </tr>
3555 </tbody>
3556 </table>
3557 <div class="exampleblock">
3558 <div class="title">Example 25. Minimal binary32 fixed-length floating point number field class.</div>
3559 <div class="content">
3560 <div class="listingblock">
3561 <div class="content">
3562 <pre class="highlight"><code class="language-json" data-lang="json">{
3563   "type": "fixed-length-floating-point-number",
3564   "length": 32,
3565   "byte-order": "little-endian"
3566 }</code></pre>
3567 </div>
3568 </div>
3569 </div>
3570 </div>
3571 <div class="exampleblock">
3572 <div class="title">Example 26. binary64 fixed-length floating point number field class with instances aligned to 32&#160;bits.</div>
3573 <div class="content">
3574 <div class="listingblock">
3575 <div class="content">
3576 <pre class="highlight"><code class="language-json" data-lang="json">{
3577   "type": "fixed-length-floating-point-number",
3578   "length": 64,
3579   "byte-order": "big-endian",
3580   "alignment": 32
3581 }</code></pre>
3582 </div>
3583 </div>
3584 </div>
3585 </div>
3586 <div class="exampleblock">
3587 <div class="title">Example 27. binary192 fixed-length floating point number field class with <a href="#user-attrs">user attributes</a>.</div>
3588 <div class="content">
3589 <div class="listingblock">
3590 <div class="content">
3591 <pre class="highlight"><code class="language-json" data-lang="json">{
3592   "type": "fixed-length-floating-point-number",
3593   "length": 192,
3594   "byte-order": "little-endian",
3595   "user-attributes": {
3596     "my.tracer": {
3597       "is-nice": true
3598     }
3599   }
3600 }</code></pre>
3601 </div>
3602 </div>
3603 </div>
3604 </div>
3605 </div>
3606 <div class="sect3">
3607 <h4 id="vl-ba-fc">5.4.11. Variable-length bit array field class</h4>
3608 <div class="paragraph">
3609 <p>A <em>variable-length bit array</em> field class describes <em>variable-length bit array</em> fields.</p>
3610 </div>
3611 <div class="paragraph">
3612 <p>A variable-length bit array field is a <a href="#seq-def">sequence</a> of bytes with a variable
3613 length which contains an array of bits of which the length is a multiple
3614 of&#160;7. A variable-length bit array field is encoded as per
3615 <a href="https://en.wikipedia.org/wiki/LEB128">LEB128</a>.</p>
3616 </div>
3617 <div class="paragraph">
3618 <p>A variable-length bit array field class acts as a base of a <a href="#vl-int-fc">variable-length integer field class</a>.</p>
3619 </div>
3620 <table class="tableblock frame-all grid-all fit-content">
3621 <caption class="title">Table 11. Common properties of a variable-length bit array field class <em><strong>F</strong></em>.</caption>
3622 <colgroup>
3623 <col>
3624 <col>
3625 <col>
3626 <col>
3627 <col>
3628 </colgroup>
3629 <thead>
3630 <tr>
3631 <th class="tableblock halign-left valign-top">Name</th>
3632 <th class="tableblock halign-left valign-top">Type</th>
3633 <th class="tableblock halign-left valign-top">Description</th>
3634 <th class="tableblock halign-left valign-top">Required?</th>
3635 <th class="tableblock halign-left valign-top">Default</th>
3636 </tr>
3637 </thead>
3638 <tbody>
3639 <tr>
3640 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
3641 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3642 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3643 <p>Type of&#160;<em><strong>F</strong></em>.</p>
3644 </div>
3645 <div class="paragraph">
3646 <p>The value of this property <em>MUST</em> be <code>"variable-length-bit-array"</code>.</p>
3647 </div></div></td>
3648 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3649 <td class="tableblock halign-left valign-top"></td>
3650 </tr>
3651 <tr>
3652 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
3653 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
3654 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3655 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
3656 </div>
3657 <div class="paragraph">
3658 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
3659 root field classes.</p>
3660 </div></div></td>
3661 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3662 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
3663 </tr>
3664 <tr>
3665 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
3666 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
3667 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3668 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
3669 </div></div></td>
3670 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3671 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3672 </tr>
3673 <tr>
3674 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
3675 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
3676 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3677 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
3678 </div>
3679 <div class="paragraph">
3680 <p>Any extension which exists under this property <em>MUST</em> also be declared
3681 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
3682 </div></div></td>
3683 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3684 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3685 </tr>
3686 </tbody>
3687 </table>
3688 <div class="exampleblock">
3689 <div class="title">Example 28. Minimal variable-length bit array field class.</div>
3690 <div class="content">
3691 <div class="listingblock">
3692 <div class="content">
3693 <pre class="highlight"><code class="language-json" data-lang="json">{
3694   "type": "variable-length-bit-array"
3695 }</code></pre>
3696 </div>
3697 </div>
3698 </div>
3699 </div>
3700 <div class="exampleblock">
3701 <div class="title">Example 29. Variable-length bit array field class with <a href="#user-attrs">user attributes</a>.</div>
3702 <div class="content">
3703 <div class="listingblock">
3704 <div class="content">
3705 <pre class="highlight"><code class="language-json" data-lang="json">{
3706   "type": "variable-length-bit-array",
3707   "user-attributes": {
3708     "my.tracer": {
3709       "is-nice": true
3710     }
3711   }
3712 }</code></pre>
3713 </div>
3714 </div>
3715 </div>
3716 </div>
3717 </div>
3718 <div class="sect3">
3719 <h4 id="vl-int-fc">5.4.12. Variable-length integer field class</h4>
3720 <div class="paragraph">
3721 <p>A <em>variable-length integer</em> field class is both an <a href="#int-fc">abstract integer field
3722 class</a> and a <a href="#vl-ba-fc">variable-length bit array field class</a> which describes <em>variable-length integer</em> fields.</p>
3723 </div>
3724 <div class="paragraph">
3725 <p>A variable-length integer field is a variable-length bit array field which has integer semantics.</p>
3726 </div>
3727 <div class="paragraph">
3728 <p>If the value of the <code>type</code> property of a variable-length integer field class is
3729 <code>"variable-length-signed-integer"</code>, then its instances have the two&#8217;s
3730 complement format.</p>
3731 </div>
3732 <div class="paragraph">
3733 <p>A variable-length integer field class acts as a base of a <a href="#vl-enum-fc">variable-length enumeration field class</a>.</p>
3734 </div>
3735 <table class="tableblock frame-all grid-all fit-content">
3736 <caption class="title">Table 12. Common properties of a variable-length integer field class <em><strong>F</strong></em>.</caption>
3737 <colgroup>
3738 <col>
3739 <col>
3740 <col>
3741 <col>
3742 <col>
3743 </colgroup>
3744 <thead>
3745 <tr>
3746 <th class="tableblock halign-left valign-top">Name</th>
3747 <th class="tableblock halign-left valign-top">Type</th>
3748 <th class="tableblock halign-left valign-top">Description</th>
3749 <th class="tableblock halign-left valign-top">Required?</th>
3750 <th class="tableblock halign-left valign-top">Default</th>
3751 </tr>
3752 </thead>
3753 <tbody>
3754 <tr>
3755 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
3756 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3757 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3758 <p>Type of&#160;<em><strong>F</strong></em>.</p>
3759 </div>
3760 <div class="paragraph">
3761 <p>The value of this property <em>MUST</em> be one of:</p>
3762 </div>
3763 <div class="dlist">
3764 <dl>
3765 <dt class="hdlist1"><code>"variable-length-unsigned-integer"</code></dt>
3766 <dd>
3767 <p>The instances of&#160;<em><strong>F</strong></em> are variable-length unsigned integer fields.</p>
3768 </dd>
3769 <dt class="hdlist1"><code>"variable-length-signed-integer"</code></dt>
3770 <dd>
3771 <p>The instances of&#160;<em><strong>F</strong></em> are variable-length signed integer fields.</p>
3772 </dd>
3773 </dl>
3774 </div></div></td>
3775 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3776 <td class="tableblock halign-left valign-top"></td>
3777 </tr>
3778 <tr>
3779 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>preferred-display-base</code></p></td>
3780 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3781 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3782 <p>Preferred base to display the value of an instance of&#160;<em><strong>F</strong></em>.</p>
3783 </div>
3784 <div class="paragraph">
3785 <p>The value of this property <em>MUST</em> be one of:</p>
3786 </div>
3787 <div class="hdlist">
3788 <table>
3789 <tr>
3790 <td class="hdlist1">
3791 <code>2</code>
3792 </td>
3793 <td class="hdlist2">
3794 <p>Binary base.</p>
3795 </td>
3796 </tr>
3797 <tr>
3798 <td class="hdlist1">
3799 <code>8</code>
3800 </td>
3801 <td class="hdlist2">
3802 <p>Octal base.</p>
3803 </td>
3804 </tr>
3805 <tr>
3806 <td class="hdlist1">
3807 <code>10</code>
3808 </td>
3809 <td class="hdlist2">
3810 <p>Decimal base.</p>
3811 </td>
3812 </tr>
3813 <tr>
3814 <td class="hdlist1">
3815 <code>16</code>
3816 </td>
3817 <td class="hdlist2">
3818 <p>Hexadecimal base.</p>
3819 </td>
3820 </tr>
3821 </table>
3822 </div>
3823 <div class="paragraph">
3824 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
3825 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
3826 </div>
3827 <div class="paragraph">
3828 <p>Property inherited from the <a href="#int-fc">abstract integer field class</a>.</p>
3829 </div></div></td>
3830 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3831 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
3832 </tr>
3833 <tr>
3834 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
3835 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
3836 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3837 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
3838 </div>
3839 <div class="paragraph">
3840 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
3841 root field classes.</p>
3842 </div></div></td>
3843 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3844 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
3845 </tr>
3846 <tr>
3847 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
3848 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
3849 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3850 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
3851 </div></div></td>
3852 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3853 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3854 </tr>
3855 <tr>
3856 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
3857 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
3858 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3859 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
3860 </div>
3861 <div class="paragraph">
3862 <p>Any extension which exists under this property <em>MUST</em> also be declared
3863 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
3864 </div></div></td>
3865 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
3866 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
3867 </tr>
3868 </tbody>
3869 </table>
3870 <div class="exampleblock">
3871 <div class="title">Example 30. Minimal variable-length unsigned integer field class.</div>
3872 <div class="content">
3873 <div class="listingblock">
3874 <div class="content">
3875 <pre class="highlight"><code class="language-json" data-lang="json">{
3876   "type": "variable-length-unsigned-integer"
3877 }</code></pre>
3878 </div>
3879 </div>
3880 </div>
3881 </div>
3882 <div class="exampleblock">
3883 <div class="title">Example 31. Variable-length signed integer field class with instances to be preferably displayed with a hexadecimal base.</div>
3884 <div class="content">
3885 <div class="listingblock">
3886 <div class="content">
3887 <pre class="highlight"><code class="language-json" data-lang="json">{
3888   "type": "variable-length-signed-integer",
3889   "preferred-display-base": 16
3890 }</code></pre>
3891 </div>
3892 </div>
3893 </div>
3894 </div>
3895 <div class="exampleblock">
3896 <div class="title">Example 32. Variable-length unsigned integer field class with <a href="#user-attrs">user attributes</a>.</div>
3897 <div class="content">
3898 <div class="listingblock">
3899 <div class="content">
3900 <pre class="highlight"><code class="language-json" data-lang="json">{
3901   "type": "variable-length-unsigned-integer",
3902   "user-attributes": {
3903     "my.tracer": {
3904       "is-nice": true
3905     }
3906   }
3907 }</code></pre>
3908 </div>
3909 </div>
3910 </div>
3911 </div>
3912 </div>
3913 <div class="sect3">
3914 <h4 id="vl-enum-fc">5.4.13. Variable-length enumeration field class</h4>
3915 <div class="paragraph">
3916 <p>A <em>variable-length enumeration</em> field class is both an <a href="#enum-fc">abstract enumeration
3917 field class</a> and a <a href="#vl-int-fc">variable-length integer field class</a> which describes <em>variable-length enumeration</em> fields.</p>
3918 </div>
3919 <div class="paragraph">
3920 <p>A variable-length enumeration field is a variable-length integer field which <em>MAY</em> have one or more
3921 associated names thanks to the <code>mappings</code> property of its class.</p>
3922 </div>
3923 <div class="paragraph">
3924 <p>If the value of the <code>type</code> property of a variable-length enumeration field class is
3925 <code>"variable-length-signed-enumeration"</code>, then its instances have the
3926 two&#8217;s complement format.</p>
3927 </div>
3928 <table class="tableblock frame-all grid-all fit-content">
3929 <caption class="title">Table 13. Properties of a variable-length enumeration field class <em><strong>F</strong></em>.</caption>
3930 <colgroup>
3931 <col>
3932 <col>
3933 <col>
3934 <col>
3935 <col>
3936 </colgroup>
3937 <thead>
3938 <tr>
3939 <th class="tableblock halign-left valign-top">Name</th>
3940 <th class="tableblock halign-left valign-top">Type</th>
3941 <th class="tableblock halign-left valign-top">Description</th>
3942 <th class="tableblock halign-left valign-top">Required?</th>
3943 <th class="tableblock halign-left valign-top">Default</th>
3944 </tr>
3945 </thead>
3946 <tbody>
3947 <tr>
3948 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
3949 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
3950 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3951 <p>Type of&#160;<em><strong>F</strong></em>.</p>
3952 </div>
3953 <div class="paragraph">
3954 <p>The value of this property <em>MUST</em> be one of:</p>
3955 </div>
3956 <div class="dlist">
3957 <dl>
3958 <dt class="hdlist1"><code>"variable-length-unsigned-enumeration"</code></dt>
3959 <dd>
3960 <p>The instances of&#160;<em><strong>F</strong></em> are variable-length unsigned enumeration fields.</p>
3961 </dd>
3962 <dt class="hdlist1"><code>"variable-length-signed-enumeration"</code></dt>
3963 <dd>
3964 <p>The instances of&#160;<em><strong>F</strong></em> are variable-length signed enumeration fields.</p>
3965 </dd>
3966 </dl>
3967 </div></div></td>
3968 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
3969 <td class="tableblock halign-left valign-top"></td>
3970 </tr>
3971 <tr>
3972 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>preferred-display-base</code></p></td>
3973 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
3974 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
3975 <p>Preferred base to display the value of an instance of&#160;<em><strong>F</strong></em>.</p>
3976 </div>
3977 <div class="paragraph">
3978 <p>The value of this property <em>MUST</em> be one of:</p>
3979 </div>
3980 <div class="hdlist">
3981 <table>
3982 <tr>
3983 <td class="hdlist1">
3984 <code>2</code>
3985 </td>
3986 <td class="hdlist2">
3987 <p>Binary base.</p>
3988 </td>
3989 </tr>
3990 <tr>
3991 <td class="hdlist1">
3992 <code>8</code>
3993 </td>
3994 <td class="hdlist2">
3995 <p>Octal base.</p>
3996 </td>
3997 </tr>
3998 <tr>
3999 <td class="hdlist1">
4000 <code>10</code>
4001 </td>
4002 <td class="hdlist2">
4003 <p>Decimal base.</p>
4004 </td>
4005 </tr>
4006 <tr>
4007 <td class="hdlist1">
4008 <code>16</code>
4009 </td>
4010 <td class="hdlist2">
4011 <p>Hexadecimal base.</p>
4012 </td>
4013 </tr>
4014 </table>
4015 </div>
4016 <div class="paragraph">
4017 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
4018 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
4019 </div>
4020 <div class="paragraph">
4021 <p>Property inherited from the <a href="#int-fc">abstract integer field class</a>.</p>
4022 </div></div></td>
4023 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4024 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
4025 </tr>
4026 <tr>
4027 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mappings</code></p></td>
4028 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#enum-fc-mappings">Enumeration field class mappings</a></p></td>
4029 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4030 <p>Mappings of&#160;<em><strong>F</strong></em>.</p>
4031 </div>
4032 <div class="paragraph">
4033 <p>The value of this property <em>MUST</em> contain one or more properties.</p>
4034 </div>
4035 <div class="paragraph">
4036 <p>Property inherited from the <a href="#enum-fc">abstract enumeration field class</a>.</p>
4037 </div></div></td>
4038 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4039 <td class="tableblock halign-left valign-top"></td>
4040 </tr>
4041 <tr>
4042 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4043 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4044 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4045 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4046 </div>
4047 <div class="paragraph">
4048 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4049 root field classes.</p>
4050 </div></div></td>
4051 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4052 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4053 </tr>
4054 <tr>
4055 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4056 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4057 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4058 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4059 </div></div></td>
4060 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4061 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4062 </tr>
4063 <tr>
4064 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4065 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4066 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4067 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4068 </div>
4069 <div class="paragraph">
4070 <p>Any extension which exists under this property <em>MUST</em> also be declared
4071 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4072 </div></div></td>
4073 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4074 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4075 </tr>
4076 </tbody>
4077 </table>
4078 <div class="exampleblock">
4079 <div class="title">Example 33. Minimal variable-length unsigned enumeration field class.</div>
4080 <div class="content">
4081 <div class="listingblock">
4082 <div class="content">
4083 <pre class="highlight"><code class="language-json" data-lang="json">{
4084   "type": "variable-length-unsigned-enumeration",
4085   "mappings": {
4086     "apple": [[1, 19]]
4087   }
4088 }</code></pre>
4089 </div>
4090 </div>
4091 </div>
4092 </div>
4093 <div class="exampleblock">
4094 <div class="title">Example 34. Variable-length unsigned enumeration field class with instances to be preferably displayed with a hexadecimal base.</div>
4095 <div class="content">
4096 <div class="listingblock">
4097 <div class="content">
4098 <pre class="highlight"><code class="language-json" data-lang="json">{
4099   "type": "variable-length-unsigned-enumeration",
4100   "preferred-display-base": 16,
4101   "mappings": {
4102     "lime": [[3, 3]],
4103     "kiwi": [[8, 8]],
4104     "blueberry": [[11, 11]]
4105   }
4106 }</code></pre>
4107 </div>
4108 </div>
4109 </div>
4110 </div>
4111 <div class="exampleblock">
4112 <div class="title">Example 35. Variable-length signed enumeration field class with <a href="#user-attrs">user attributes</a>.</div>
4113 <div class="content">
4114 <div class="listingblock">
4115 <div class="content">
4116 <pre class="highlight"><code class="language-json" data-lang="json">{
4117   "type": "variable-length-signed-enumeration",
4118   "mappings": {
4119     "banana": [[-27399, -1882], [8, 199], [101, 101]],
4120     "orange": [[67, 67], [43, 1534]]
4121   },
4122   "user-attributes": {
4123     "my.tracer": {
4124       "is-nice": true
4125     }
4126   }
4127 }</code></pre>
4128 </div>
4129 </div>
4130 </div>
4131 </div>
4132 </div>
4133 <div class="sect3">
4134 <h4 id="str-fc">5.4.14. Null-terminated string field class</h4>
4135 <div class="paragraph">
4136 <p>A <em>null-terminated string</em> field class describes <em>null-terminated string</em> fields.</p>
4137 </div>
4138 <div class="paragraph">
4139 <p>A null-terminated string field is, in this order:</p>
4140 </div>
4141 <div class="olist arabic">
4142 <ol class="arabic">
4143 <li>
4144 <p>Zero or more contiguous non-null (non-zero) bytes which form a
4145 UTF-8-encoded string.</p>
4146 </li>
4147 <li>
4148 <p>One null (zero) byte.</p>
4149 </li>
4150 </ol>
4151 </div>
4152 <table class="tableblock frame-all grid-all fit-content">
4153 <caption class="title">Table 14. Properties of a null-terminated string field class <em><strong>F</strong></em>.</caption>
4154 <colgroup>
4155 <col>
4156 <col>
4157 <col>
4158 <col>
4159 <col>
4160 </colgroup>
4161 <thead>
4162 <tr>
4163 <th class="tableblock halign-left valign-top">Name</th>
4164 <th class="tableblock halign-left valign-top">Type</th>
4165 <th class="tableblock halign-left valign-top">Description</th>
4166 <th class="tableblock halign-left valign-top">Required?</th>
4167 <th class="tableblock halign-left valign-top">Default</th>
4168 </tr>
4169 </thead>
4170 <tbody>
4171 <tr>
4172 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
4173 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4174 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4175 <p>Type of&#160;<em><strong>F</strong></em>.</p>
4176 </div>
4177 <div class="paragraph">
4178 <p>The value of this property <em>MUST</em> be <code>"null-terminated-string"</code>.</p>
4179 </div></div></td>
4180 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4181 <td class="tableblock halign-left valign-top"></td>
4182 </tr>
4183 <tr>
4184 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4185 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4186 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4187 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4188 </div>
4189 <div class="paragraph">
4190 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4191 root field classes.</p>
4192 </div></div></td>
4193 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4194 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4195 </tr>
4196 <tr>
4197 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4198 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4199 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4200 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4201 </div></div></td>
4202 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4203 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4204 </tr>
4205 <tr>
4206 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4207 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4208 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4209 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4210 </div>
4211 <div class="paragraph">
4212 <p>Any extension which exists under this property <em>MUST</em> also be declared
4213 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4214 </div></div></td>
4215 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4216 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4217 </tr>
4218 </tbody>
4219 </table>
4220 <div class="exampleblock">
4221 <div class="title">Example 36. Minimal null-terminated string field class.</div>
4222 <div class="content">
4223 <div class="listingblock">
4224 <div class="content">
4225 <pre class="highlight"><code class="language-json" data-lang="json">{
4226   "type": "null-terminated-string"
4227 }</code></pre>
4228 </div>
4229 </div>
4230 </div>
4231 </div>
4232 <div class="exampleblock">
4233 <div class="title">Example 37. Null-terminated string field class with <a href="#user-attrs">user attributes</a>.</div>
4234 <div class="content">
4235 <div class="listingblock">
4236 <div class="content">
4237 <pre class="highlight"><code class="language-json" data-lang="json">{
4238   "type": "null-terminated-string",
4239   "user-attributes": {
4240     "my.tracer": {
4241       "is-nice": true
4242     }
4243   }
4244 }</code></pre>
4245 </div>
4246 </div>
4247 </div>
4248 </div>
4249 </div>
4250 <div class="sect3">
4251 <h4 id="sl-str-fc">5.4.15. Static-length string field class</h4>
4252 <div class="paragraph">
4253 <p>A <em>static-length string</em> field class describes <em>static-length string</em> fields.</p>
4254 </div>
4255 <div class="paragraph">
4256 <p>A static-length string field is a <a href="#seq-def">sequence</a> of zero or more contiguous
4257 bytes. All the bytes of a static-length string before the first null (zero) byte, if
4258 any, form a UTF-8-encoded string. All the bytes after the first null
4259 (zero) byte, if any, are padding (garbage data).</p>
4260 </div>
4261 <div class="paragraph">
4262 <p>The length, or number of bytes, of a static-length string field is a property
4263 (<code>length</code>) of its class.</p>
4264 </div>
4265 <table class="tableblock frame-all grid-all fit-content">
4266 <caption class="title">Table 15. Properties of a static-length string field class <em><strong>F</strong></em>.</caption>
4267 <colgroup>
4268 <col>
4269 <col>
4270 <col>
4271 <col>
4272 <col>
4273 </colgroup>
4274 <thead>
4275 <tr>
4276 <th class="tableblock halign-left valign-top">Name</th>
4277 <th class="tableblock halign-left valign-top">Type</th>
4278 <th class="tableblock halign-left valign-top">Description</th>
4279 <th class="tableblock halign-left valign-top">Required?</th>
4280 <th class="tableblock halign-left valign-top">Default</th>
4281 </tr>
4282 </thead>
4283 <tbody>
4284 <tr>
4285 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
4286 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4287 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4288 <p>Type of&#160;<em><strong>F</strong></em>.</p>
4289 </div>
4290 <div class="paragraph">
4291 <p>The value of this property <em>MUST</em> be <code>"static-length-string"</code>.</p>
4292 </div></div></td>
4293 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4294 <td class="tableblock halign-left valign-top"></td>
4295 </tr>
4296 <tr>
4297 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
4298 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
4299 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4300 <p>Number of bytes contained in an instance of&#160;<em><strong>F</strong></em>.</p>
4301 </div>
4302 <div class="paragraph">
4303 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
4304 </div></div></td>
4305 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4306 <td class="tableblock halign-left valign-top"></td>
4307 </tr>
4308 <tr>
4309 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4310 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4311 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4312 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4313 </div>
4314 <div class="paragraph">
4315 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4316 root field classes.</p>
4317 </div></div></td>
4318 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4319 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4320 </tr>
4321 <tr>
4322 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4323 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4324 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4325 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4326 </div></div></td>
4327 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4328 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4329 </tr>
4330 <tr>
4331 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4332 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4333 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4334 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4335 </div>
4336 <div class="paragraph">
4337 <p>Any extension which exists under this property <em>MUST</em> also be declared
4338 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4339 </div></div></td>
4340 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4341 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4342 </tr>
4343 </tbody>
4344 </table>
4345 <div class="exampleblock">
4346 <div class="title">Example 38. Empty static-length string field class.</div>
4347 <div class="content">
4348 <div class="listingblock">
4349 <div class="content">
4350 <pre class="highlight"><code class="language-json" data-lang="json">{
4351   "type": "static-length-string",
4352   "length": 0
4353 }</code></pre>
4354 </div>
4355 </div>
4356 </div>
4357 </div>
4358 <div class="exampleblock">
4359 <div class="title">Example 39. Static-length string field class with instances having 100&#160;bytes.</div>
4360 <div class="content">
4361 <div class="listingblock">
4362 <div class="content">
4363 <pre class="highlight"><code class="language-json" data-lang="json">{
4364   "type": "static-length-string",
4365   "length": 100
4366 }</code></pre>
4367 </div>
4368 </div>
4369 </div>
4370 </div>
4371 <div class="exampleblock">
4372 <div class="title">Example 40. Static-length string field class with <a href="#user-attrs">user attributes</a>.</div>
4373 <div class="content">
4374 <div class="listingblock">
4375 <div class="content">
4376 <pre class="highlight"><code class="language-json" data-lang="json">{
4377   "type": "static-length-string",
4378   "length": 13,
4379   "user-attributes": {
4380     "my.tracer": null
4381   }
4382 }</code></pre>
4383 </div>
4384 </div>
4385 </div>
4386 </div>
4387 </div>
4388 <div class="sect3">
4389 <h4 id="dl-str-fc">5.4.16. Dynamic-length string field class</h4>
4390 <div class="paragraph">
4391 <p>A <em>dynamic-length string</em> field class describes <em>dynamic-length string</em> fields.</p>
4392 </div>
4393 <div class="paragraph">
4394 <p>A dynamic-length string field is a <a href="#seq-def">sequence</a> of zero or more contiguous
4395 bytes. All the bytes of a dynamic-length string before the first null (zero) byte, if
4396 any, form a UTF-8-encoded string. All the bytes after the first null
4397 (zero) byte, if any, are padding (garbage data).</p>
4398 </div>
4399 <div class="paragraph">
4400 <p>The length, or number of bytes, of a dynamic-length string field is the value of
4401 another, anterior (already encoded/decoded) <em>length</em> field. A
4402 <a href="#consumer-def">consumer</a> can locate this length field thanks to the
4403 <code>length-field-location</code> property of the dynamic-length string field class.</p>
4404 </div>
4405 <table class="tableblock frame-all grid-all fit-content">
4406 <caption class="title">Table 16. Properties of a dynamic-length string field class <em><strong>F</strong></em>.</caption>
4407 <colgroup>
4408 <col>
4409 <col>
4410 <col>
4411 <col>
4412 <col>
4413 </colgroup>
4414 <thead>
4415 <tr>
4416 <th class="tableblock halign-left valign-top">Name</th>
4417 <th class="tableblock halign-left valign-top">Type</th>
4418 <th class="tableblock halign-left valign-top">Description</th>
4419 <th class="tableblock halign-left valign-top">Required?</th>
4420 <th class="tableblock halign-left valign-top">Default</th>
4421 </tr>
4422 </thead>
4423 <tbody>
4424 <tr>
4425 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
4426 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4427 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4428 <p>Type of&#160;<em><strong>F</strong></em>.</p>
4429 </div>
4430 <div class="paragraph">
4431 <p>The value of this property <em>MUST</em> be <code>"static-length-string"</code>.</p>
4432 </div></div></td>
4433 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4434 <td class="tableblock halign-left valign-top"></td>
4435 </tr>
4436 <tr>
4437 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length-field-location</code></p></td>
4438 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#field-loc">Field location</a></p></td>
4439 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4440 <p>Location of the field of which the value is the number of bytes
4441 contained in an instance of&#160;<em><strong>F</strong></em>.</p>
4442 </div>
4443 <div class="paragraph">
4444 <p>The class of the length field <em>MUST</em> be one of:</p>
4445 </div>
4446 <div class="ulist">
4447 <ul>
4448 <li>
4449 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a></p>
4450 </li>
4451 <li>
4452 <p><a href="#vl-int-fc">Variable-length unsigned integer field class</a></p>
4453 </li>
4454 </ul>
4455 </div></div></td>
4456 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4457 <td class="tableblock halign-left valign-top"></td>
4458 </tr>
4459 <tr>
4460 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4461 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4462 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4463 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4464 </div>
4465 <div class="paragraph">
4466 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4467 root field classes.</p>
4468 </div></div></td>
4469 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4470 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4471 </tr>
4472 <tr>
4473 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4474 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4475 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4476 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4477 </div></div></td>
4478 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4479 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4480 </tr>
4481 <tr>
4482 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4483 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4484 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4485 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4486 </div>
4487 <div class="paragraph">
4488 <p>Any extension which exists under this property <em>MUST</em> also be declared
4489 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4490 </div></div></td>
4491 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4492 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4493 </tr>
4494 </tbody>
4495 </table>
4496 <div class="exampleblock">
4497 <div class="title">Example 41. Dynamic-length string field class.</div>
4498 <div class="content">
4499 <div class="listingblock">
4500 <div class="content">
4501 <pre class="highlight"><code class="language-json" data-lang="json">{
4502   "type": "dynamic-length-string",
4503   "length-field-location": ["event-record-payload", "length"]
4504 }</code></pre>
4505 </div>
4506 </div>
4507 </div>
4508 </div>
4509 <div class="exampleblock">
4510 <div class="title">Example 42. Dynamic-length string field class with <a href="#user-attrs">user attributes</a>.</div>
4511 <div class="content">
4512 <div class="listingblock">
4513 <div class="content">
4514 <pre class="highlight"><code class="language-json" data-lang="json">{
4515   "type": "dynamic-length-string",
4516   "length-field-location": ["event-record-common-context", "name-length"],
4517   "user-attributes": {
4518     "my.tracer": 177
4519   }
4520 }</code></pre>
4521 </div>
4522 </div>
4523 </div>
4524 </div>
4525 </div>
4526 <div class="sect3">
4527 <h4 id="blob-fc">5.4.17. Abstract BLOB field class</h4>
4528 <div class="paragraph">
4529 <p>An <em>abstract <a href="https://en.wikipedia.org/wiki/Binary_large_object">BLOB</a></em>
4530 field class is a base of a <a href="#sl-blob-fc">static-length BLOB field class</a> and a <a href="#dl-blob-fc">dynamic-length BLOB field class</a>.</p>
4531 </div>
4532 <div class="paragraph">
4533 <p>This field class is abstract in that it only exists to show the relation
4534 between different BLOB field classes in this document: a <a href="#pkt">packet</a>
4535 cannot contain an abstract BLOB field.</p>
4536 </div>
4537 <table class="tableblock frame-all grid-all fit-content">
4538 <caption class="title">Table 17. Common properties of a BLOB field class <em><strong>F</strong></em>.</caption>
4539 <colgroup>
4540 <col>
4541 <col>
4542 <col>
4543 <col>
4544 <col>
4545 </colgroup>
4546 <thead>
4547 <tr>
4548 <th class="tableblock halign-left valign-top">Name</th>
4549 <th class="tableblock halign-left valign-top">Type</th>
4550 <th class="tableblock halign-left valign-top">Description</th>
4551 <th class="tableblock halign-left valign-top">Required?</th>
4552 <th class="tableblock halign-left valign-top">Default</th>
4553 </tr>
4554 </thead>
4555 <tbody>
4556 <tr>
4557 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>media-type</code></p></td>
4558 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4559 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4560 <p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">IANA
4561 media type</a> of an instance of&#160;<em><strong>F</strong></em>.</p>
4562 </div></div></td>
4563 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4564 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>"application/octet-stream"</code></p></td>
4565 </tr>
4566 </tbody>
4567 </table>
4568 </div>
4569 <div class="sect3">
4570 <h4 id="sl-blob-fc">5.4.18. Static-length BLOB field class</h4>
4571 <div class="paragraph">
4572 <p>A <em>static-length BLOB</em> field class is an <a href="#blob-fc">abstract BLOB field class</a>
4573 which describes <em>static-length BLOB</em> fields.</p>
4574 </div>
4575 <div class="paragraph">
4576 <p>A static-length BLOB field is a <a href="#seq-def">sequence</a> of zero or more contiguous
4577 bytes with an associated IANA media type (given by the <code>media-type</code>
4578 property of its class).</p>
4579 </div>
4580 <div class="paragraph">
4581 <p>The length, or number of bytes, of a static-length BLOB field is a property
4582 (<code>length</code>) of its class.</p>
4583 </div>
4584 <table class="tableblock frame-all grid-all fit-content">
4585 <caption class="title">Table 18. Properties of a static-length BLOB field class <em><strong>F</strong></em>.</caption>
4586 <colgroup>
4587 <col>
4588 <col>
4589 <col>
4590 <col>
4591 <col>
4592 </colgroup>
4593 <thead>
4594 <tr>
4595 <th class="tableblock halign-left valign-top">Name</th>
4596 <th class="tableblock halign-left valign-top">Type</th>
4597 <th class="tableblock halign-left valign-top">Description</th>
4598 <th class="tableblock halign-left valign-top">Required?</th>
4599 <th class="tableblock halign-left valign-top">Default</th>
4600 </tr>
4601 </thead>
4602 <tbody>
4603 <tr>
4604 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
4605 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4606 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4607 <p>Type of&#160;<em><strong>F</strong></em>.</p>
4608 </div>
4609 <div class="paragraph">
4610 <p>The value of this property <em>MUST</em> be <code>"static-length-blob"</code>.</p>
4611 </div></div></td>
4612 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4613 <td class="tableblock halign-left valign-top"></td>
4614 </tr>
4615 <tr>
4616 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
4617 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
4618 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4619 <p>Number of bytes contained in an instance of&#160;<em><strong>F</strong></em>.</p>
4620 </div>
4621 <div class="paragraph">
4622 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
4623 </div></div></td>
4624 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4625 <td class="tableblock halign-left valign-top"></td>
4626 </tr>
4627 <tr>
4628 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>media-type</code></p></td>
4629 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4630 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4631 <p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">IANA
4632 media type</a> of an instance of&#160;<em><strong>F</strong></em>.</p>
4633 </div>
4634 <div class="paragraph">
4635 <p>Property inherited from the <a href="#blob-fc">abstract BLOB field class</a>.</p>
4636 </div></div></td>
4637 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4638 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>"application/octet-stream"</code></p></td>
4639 </tr>
4640 <tr>
4641 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4642 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4643 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4644 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4645 </div>
4646 <div class="paragraph">
4647 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4648 root field classes.</p>
4649 </div></div></td>
4650 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4651 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4652 </tr>
4653 <tr>
4654 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4655 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4656 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4657 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4658 </div></div></td>
4659 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4660 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4661 </tr>
4662 <tr>
4663 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4664 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4665 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4666 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4667 </div>
4668 <div class="paragraph">
4669 <p>Any extension which exists under this property <em>MUST</em> also be declared
4670 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4671 </div></div></td>
4672 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4673 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4674 </tr>
4675 </tbody>
4676 </table>
4677 <div class="exampleblock">
4678 <div class="title">Example 43. Empty static-length BLOB field class with instances having a default IANA media type.</div>
4679 <div class="content">
4680 <div class="listingblock">
4681 <div class="content">
4682 <pre class="highlight"><code class="language-json" data-lang="json">{
4683   "type": "static-length-blob",
4684   "length": 0
4685 }</code></pre>
4686 </div>
4687 </div>
4688 </div>
4689 </div>
4690 <div class="exampleblock">
4691 <div class="title">Example 44. Static-length TIFF BLOB field class with instances having 511,267&#160;bytes.</div>
4692 <div class="content">
4693 <div class="listingblock">
4694 <div class="content">
4695 <pre class="highlight"><code class="language-json" data-lang="json">{
4696   "type": "static-length-blob",
4697   "length": 511267,
4698   "media-type": "image/tif"
4699 }</code></pre>
4700 </div>
4701 </div>
4702 </div>
4703 </div>
4704 <div class="exampleblock">
4705 <div class="title">Example 45. Static-length CSV BLOB field class with <a href="#user-attrs">user attributes</a>.</div>
4706 <div class="content">
4707 <div class="listingblock">
4708 <div class="content">
4709 <pre class="highlight"><code class="language-json" data-lang="json">{
4710   "type": "static-length-blob",
4711   "length": 2400,
4712   "media-type": "text/csv",
4713   "user-attributes": {
4714     "my.tracer": {
4715       "csv-cols": 12
4716     }
4717   }
4718 }</code></pre>
4719 </div>
4720 </div>
4721 </div>
4722 </div>
4723 </div>
4724 <div class="sect3">
4725 <h4 id="dl-blob-fc">5.4.19. Dynamic-length BLOB field class</h4>
4726 <div class="paragraph">
4727 <p>A <em>dynamic-length BLOB</em> field class is an <a href="#blob-fc">abstract BLOB field class</a>
4728 which describes <em>dynamic-length BLOB</em> fields.</p>
4729 </div>
4730 <div class="paragraph">
4731 <p>A dynamic-length BLOB field is a <a href="#seq-def">sequence</a> of zero or more contiguous
4732 bytes with an associated IANA media type.</p>
4733 </div>
4734 <div class="paragraph">
4735 <p>The length, or number of bytes, of a dynamic-length BLOB field is the value of
4736 another, anterior (already encoded/decoded) <em>length</em> field. A
4737 <a href="#consumer-def">consumer</a> can locate this length field thanks to the
4738 <code>length-field-location</code> property of the dynamic-length BLOB field class.</p>
4739 </div>
4740 <table class="tableblock frame-all grid-all fit-content">
4741 <caption class="title">Table 19. Properties of a dynamic-length BLOB field class <em><strong>F</strong></em>.</caption>
4742 <colgroup>
4743 <col>
4744 <col>
4745 <col>
4746 <col>
4747 <col>
4748 </colgroup>
4749 <thead>
4750 <tr>
4751 <th class="tableblock halign-left valign-top">Name</th>
4752 <th class="tableblock halign-left valign-top">Type</th>
4753 <th class="tableblock halign-left valign-top">Description</th>
4754 <th class="tableblock halign-left valign-top">Required?</th>
4755 <th class="tableblock halign-left valign-top">Default</th>
4756 </tr>
4757 </thead>
4758 <tbody>
4759 <tr>
4760 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
4761 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4762 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4763 <p>Type of&#160;<em><strong>F</strong></em>.</p>
4764 </div>
4765 <div class="paragraph">
4766 <p>The value of this property <em>MUST</em> be <code>"dynamic-length-blob"</code>.</p>
4767 </div></div></td>
4768 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4769 <td class="tableblock halign-left valign-top"></td>
4770 </tr>
4771 <tr>
4772 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length-field-location</code></p></td>
4773 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#field-loc">Field location</a></p></td>
4774 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4775 <p>Location of the field of which the value is the number of bytes
4776 contained in an instance of&#160;<em><strong>F</strong></em>.</p>
4777 </div>
4778 <div class="paragraph">
4779 <p>The class of the length field <em>MUST</em> be one of:</p>
4780 </div>
4781 <div class="ulist">
4782 <ul>
4783 <li>
4784 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a></p>
4785 </li>
4786 <li>
4787 <p><a href="#vl-int-fc">Variable-length unsigned integer field class</a></p>
4788 </li>
4789 </ul>
4790 </div></div></td>
4791 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4792 <td class="tableblock halign-left valign-top"></td>
4793 </tr>
4794 <tr>
4795 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>media-type</code></p></td>
4796 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4797 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4798 <p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">IANA
4799 media type</a> of an instance of&#160;<em><strong>F</strong></em>.</p>
4800 </div>
4801 <div class="paragraph">
4802 <p>Property inherited from the <a href="#blob-fc">abstract BLOB field class</a>.</p>
4803 </div></div></td>
4804 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4805 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>"application/octet-stream"</code></p></td>
4806 </tr>
4807 <tr>
4808 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4809 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4810 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4811 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4812 </div>
4813 <div class="paragraph">
4814 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4815 root field classes.</p>
4816 </div></div></td>
4817 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4818 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4819 </tr>
4820 <tr>
4821 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4822 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4823 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4824 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4825 </div></div></td>
4826 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4827 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4828 </tr>
4829 <tr>
4830 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4831 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4832 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4833 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4834 </div>
4835 <div class="paragraph">
4836 <p>Any extension which exists under this property <em>MUST</em> also be declared
4837 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4838 </div></div></td>
4839 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4840 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4841 </tr>
4842 </tbody>
4843 </table>
4844 <div class="exampleblock">
4845 <div class="title">Example 46. Dynamic-length BLOB field class with instances having a default IANA media type.</div>
4846 <div class="content">
4847 <div class="listingblock">
4848 <div class="content">
4849 <pre class="highlight"><code class="language-json" data-lang="json">{
4850   "type": "dynamic-length-blob",
4851   "length-field-location": ["event-record-payload", "length"]
4852 }</code></pre>
4853 </div>
4854 </div>
4855 </div>
4856 </div>
4857 <div class="exampleblock">
4858 <div class="title">Example 47. Dynamic-length JPEG BLOB field class with <a href="#user-attrs">user attributes</a>.</div>
4859 <div class="content">
4860 <div class="listingblock">
4861 <div class="content">
4862 <pre class="highlight"><code class="language-json" data-lang="json">{
4863   "type": "dynamic-length-blob",
4864   "length-field-location": ["event-record-common-context", "length"],
4865   "media-type": "image/jpeg",
4866   "user-attributes": {
4867     "my.tracer": {
4868       "quality": 85
4869     }
4870   }
4871 }</code></pre>
4872 </div>
4873 </div>
4874 </div>
4875 </div>
4876 </div>
4877 <div class="sect3">
4878 <h4 id="struct-fc">5.4.20. Structure field class</h4>
4879 <div class="paragraph">
4880 <p>A <em>structure field class</em> describes <em>structure fields</em>.</p>
4881 </div>
4882 <div class="paragraph">
4883 <p>A structure field is a <a href="#seq-def">sequence</a> of zero or more structure
4884 field <em>members</em>. A structure field member is a named field.</p>
4885 </div>
4886 <table class="tableblock frame-all grid-all fit-content">
4887 <caption class="title">Table 20. Properties of a structure field class <em><strong>F</strong></em>.</caption>
4888 <colgroup>
4889 <col>
4890 <col>
4891 <col>
4892 <col>
4893 <col>
4894 </colgroup>
4895 <thead>
4896 <tr>
4897 <th class="tableblock halign-left valign-top">Name</th>
4898 <th class="tableblock halign-left valign-top">Type</th>
4899 <th class="tableblock halign-left valign-top">Description</th>
4900 <th class="tableblock halign-left valign-top">Required?</th>
4901 <th class="tableblock halign-left valign-top">Default</th>
4902 </tr>
4903 </thead>
4904 <tbody>
4905 <tr>
4906 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
4907 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
4908 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4909 <p>Type of&#160;<em><strong>F</strong></em>.</p>
4910 </div>
4911 <div class="paragraph">
4912 <p>The value of this property <em>MUST</em> be <code>"structure"</code>.</p>
4913 </div></div></td>
4914 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
4915 <td class="tableblock halign-left valign-top"></td>
4916 </tr>
4917 <tr>
4918 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>member-classes</code></p></td>
4919 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON array of <a href="#struct-member-cls">structure field member classes</a></p></td>
4920 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4921 <p>Classes of the members of an instance of&#160;<em><strong>F</strong></em>.</p>
4922 </div>
4923 <div class="paragraph">
4924 <p>The <code>name</code> property of each member class <em>MUST</em> be unique within the
4925 member class names of&#160;<em><strong>F</strong></em>.</p>
4926 </div></div></td>
4927 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4928 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4929 </tr>
4930 <tr>
4931 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>minimum-alignment</code></p></td>
4932 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
4933 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4934 <p>Minimum alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
4935 relative to the beginning of the <a href="#pkt">packet</a> which contains this
4936 instance.</p>
4937 </div>
4938 <div class="paragraph">
4939 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
4940 </div>
4941 <div class="paragraph">
4942 <p>The <a href="#align-dec"><em>effective</em> alignment</a> of the first bit of an instance
4943 of&#160;<em><strong>F</strong></em> <em>MAY</em> be greater than the value of this property.</p>
4944 </div></div></td>
4945 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4946 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
4947 </tr>
4948 <tr>
4949 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
4950 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
4951 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4952 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
4953 </div>
4954 <div class="paragraph">
4955 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
4956 root field classes.</p>
4957 </div></div></td>
4958 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4959 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
4960 </tr>
4961 <tr>
4962 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
4963 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
4964 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4965 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
4966 </div></div></td>
4967 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4968 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4969 </tr>
4970 <tr>
4971 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
4972 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
4973 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
4974 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
4975 </div>
4976 <div class="paragraph">
4977 <p>Any extension which exists under this property <em>MUST</em> also be declared
4978 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
4979 </div></div></td>
4980 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
4981 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
4982 </tr>
4983 </tbody>
4984 </table>
4985 <div class="exampleblock">
4986 <div class="title">Example 48. Empty structure field class: instances have no members.</div>
4987 <div class="content">
4988 <div class="listingblock">
4989 <div class="content">
4990 <pre class="highlight"><code class="language-json" data-lang="json">{
4991   "type": "structure"
4992 }</code></pre>
4993 </div>
4994 </div>
4995 </div>
4996 </div>
4997 <div class="exampleblock">
4998 <div class="title">Example 49. Structure field class with three member classes.</div>
4999 <div class="content">
5000 <div class="listingblock">
5001 <div class="content">
5002 <pre class="highlight"><code class="language-json" data-lang="json">{
5003   "type": "structure",
5004   "member-classes": [
5005     {
5006       "name": "Villeray",
5007       "field-class": {
5008         "type": "null-terminated-string"
5009       }
5010     },
5011     {
5012       "name": "Berri",
5013       "field-class": {
5014         "type": "fixed-length-unsigned-integer",
5015         "length": 32,
5016         "byte-order": "little-endian",
5017         "preferred-display-base": 2
5018       },
5019       "user-attributes": {
5020         "my.tracer": {
5021           "is-mask": true
5022         }
5023       }
5024     },
5025     {
5026       "name": "Faillon",
5027       "field-class": {
5028         "type": "fixed-length-boolean",
5029         "length": 8,
5030         "byte-order": "little-endian"
5031       }
5032     }
5033   ]
5034 }</code></pre>
5035 </div>
5036 </div>
5037 </div>
5038 </div>
5039 <div class="exampleblock">
5040 <div class="title">Example 50. Structure field class with instances minimally aligned to 64&#160;bits.</div>
5041 <div class="content">
5042 <div class="listingblock">
5043 <div class="content">
5044 <pre class="highlight"><code class="language-json" data-lang="json">{
5045   "type": "structure",
5046   "member-classes": [
5047     {
5048       "name": "St-Denis",
5049       "field-class": {
5050         "type": "null-terminated-string"
5051       }
5052     },
5053     {
5054       "name": "Lajeunesse",
5055       "field-class": {
5056         "type": "fixed-length-unsigned-integer",
5057         "length": 32,
5058         "byte-order": "big-endian",
5059         "alignment": 32
5060       }
5061     }
5062   ],
5063   "minimum-alignment": 64
5064 }</code></pre>
5065 </div>
5066 </div>
5067 </div>
5068 </div>
5069 <div class="exampleblock">
5070 <div class="title">Example 51. Structure field class with <a href="#user-attrs">user attributes</a>.</div>
5071 <div class="content">
5072 <div class="listingblock">
5073 <div class="content">
5074 <pre class="highlight"><code class="language-json" data-lang="json">{
5075   "type": "structure",
5076   "member-classes": [
5077     {
5078       "name": "Henri-Julien",
5079       "field-class": {
5080         "type": "fixed-length-signed-integer",
5081         "length": 48,
5082         "byte-order": "little-endian"
5083       }
5084     },
5085     {
5086       "name": "Casgrain",
5087       "field-class": {
5088         "type": "static-length-string",
5089         "length": 32
5090       }
5091     }
5092   ],
5093   "user-attributes": {
5094     "my.tracer": {
5095       "version": 4
5096     }
5097   }
5098 }</code></pre>
5099 </div>
5100 </div>
5101 </div>
5102 </div>
5103 <div class="sect4">
5104 <h5 id="struct-member-cls">5.4.20.1. Structure field member class</h5>
5105 <div class="paragraph">
5106 <p>A <em>structure field member class</em> describes <em>structure field members</em>.</p>
5107 </div>
5108 <div class="paragraph">
5109 <p>A structure field member class is a JSON object.</p>
5110 </div>
5111 <table class="tableblock frame-all grid-all fit-content">
5112 <caption class="title">Table 21. Properties of a structure field member class <em><strong>M</strong></em>.</caption>
5113 <colgroup>
5114 <col>
5115 <col>
5116 <col>
5117 <col>
5118 <col>
5119 </colgroup>
5120 <thead>
5121 <tr>
5122 <th class="tableblock halign-left valign-top">Name</th>
5123 <th class="tableblock halign-left valign-top">Type</th>
5124 <th class="tableblock halign-left valign-top">Description</th>
5125 <th class="tableblock halign-left valign-top">Required?</th>
5126 <th class="tableblock halign-left valign-top">Default</th>
5127 </tr>
5128 </thead>
5129 <tbody>
5130 <tr>
5131 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td>
5132 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
5133 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5134 <p>Name of&#160;<em><strong>M</strong></em>.</p>
5135 </div></div></td>
5136 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5137 <td class="tableblock halign-left valign-top"></td>
5138 </tr>
5139 <tr>
5140 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>field-class</code></p></td>
5141 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#fc">Field class</a></p></td>
5142 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5143 <p>Field class of&#160;<em><strong>M</strong></em>.</p>
5144 </div></div></td>
5145 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5146 <td class="tableblock halign-left valign-top"></td>
5147 </tr>
5148 <tr>
5149 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
5150 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
5151 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5152 <p>User attributes of&#160;<em><strong>M</strong></em>.</p>
5153 </div></div></td>
5154 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5155 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5156 </tr>
5157 <tr>
5158 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
5159 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
5160 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5161 <p>Extensions of&#160;<em><strong>M</strong></em>.</p>
5162 </div>
5163 <div class="paragraph">
5164 <p>Any extension which exists under this property <em>MUST</em> also be declared
5165 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
5166 </div></div></td>
5167 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5168 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5169 </tr>
5170 </tbody>
5171 </table>
5172 <div class="exampleblock">
5173 <div class="title">Example 52. <a href="#str-fc">Null-terminated string field class</a> member class named <code>cat</code>.</div>
5174 <div class="content">
5175 <div class="listingblock">
5176 <div class="content">
5177 <pre class="highlight"><code class="language-json" data-lang="json">{
5178   "name": "cat",
5179   "field-class": {
5180     "type": "null-terminated-string"
5181   }
5182 }</code></pre>
5183 </div>
5184 </div>
5185 </div>
5186 </div>
5187 <div class="exampleblock">
5188 <div class="title">Example 53. <a href="#vl-int-fc">Variable-length signed integer field class</a> member class named <code>dog</code> with <a href="#user-attrs">user attributes</a>.</div>
5189 <div class="content">
5190 <div class="listingblock">
5191 <div class="content">
5192 <pre class="highlight"><code class="language-json" data-lang="json">{
5193   "name": "dog",
5194   "field-class": {
5195     "type": "variable-length-signed-integer",
5196     "preferred-display-base": 8
5197   },
5198   "user-attributes": {
5199     "my.tracer": {
5200       "uuid": [
5201         243, 97, 0, 184, 236, 54, 72, 97,
5202         141, 107, 169, 214, 171, 137, 115, 201
5203       ],
5204       "is-pid": true
5205     }
5206   }
5207 }</code></pre>
5208 </div>
5209 </div>
5210 </div>
5211 </div>
5212 </div>
5213 </div>
5214 <div class="sect3">
5215 <h4 id="array-fc">5.4.21. Abstract array field class</h4>
5216 <div class="paragraph">
5217 <p>An <em>abstract array</em> field class is a base of a <a href="#sl-array-fc">static-length array field class</a> and a
5218 <a href="#dl-array-fc">dynamic-length array field class</a>.</p>
5219 </div>
5220 <div class="paragraph">
5221 <p>This field class is abstract in that it only exists to show the relation
5222 between different array field classes in this document: a <a href="#pkt">packet</a>
5223 cannot contain an abstract array field.</p>
5224 </div>
5225 <table class="tableblock frame-all grid-all fit-content">
5226 <caption class="title">Table 22. Common properties of an array field class <em><strong>F</strong></em>.</caption>
5227 <colgroup>
5228 <col>
5229 <col>
5230 <col>
5231 <col>
5232 <col>
5233 </colgroup>
5234 <thead>
5235 <tr>
5236 <th class="tableblock halign-left valign-top">Name</th>
5237 <th class="tableblock halign-left valign-top">Type</th>
5238 <th class="tableblock halign-left valign-top">Description</th>
5239 <th class="tableblock halign-left valign-top">Required?</th>
5240 <th class="tableblock halign-left valign-top">Default</th>
5241 </tr>
5242 </thead>
5243 <tbody>
5244 <tr>
5245 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>element-field-class</code></p></td>
5246 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#fc">Field class</a></p></td>
5247 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5248 <p>Class of the element fields contained in an instance of&#160;<em><strong>F</strong></em>.</p>
5249 </div></div></td>
5250 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5251 <td class="tableblock halign-left valign-top"></td>
5252 </tr>
5253 <tr>
5254 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>minimum-alignment</code></p></td>
5255 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
5256 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5257 <p>Minimum alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
5258 relative to the beginning of the <a href="#pkt">packet</a> which contains this
5259 instance.</p>
5260 </div>
5261 <div class="paragraph">
5262 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
5263 </div>
5264 <div class="paragraph">
5265 <p>The <a href="#align-dec"><em>effective</em> alignment</a> of the first bit of an instance
5266 of&#160;<em><strong>F</strong></em> <em>MAY</em> be greater than the value of this property.</p>
5267 </div></div></td>
5268 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5269 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
5270 </tr>
5271 </tbody>
5272 </table>
5273 </div>
5274 <div class="sect3">
5275 <h4 id="sl-array-fc">5.4.22. Static-length array field class</h4>
5276 <div class="paragraph">
5277 <p>A <em>static-length array</em> field class is an <a href="#array-fc">abstract array field class</a>
5278 which describes <em>static-length array</em> fields.</p>
5279 </div>
5280 <div class="paragraph">
5281 <p>A static-length array field is a sequence of zero or more element fields.</p>
5282 </div>
5283 <div class="paragraph">
5284 <p>The length, or number of element fields, of a static-length array field is a
5285 property (<code>length</code>) of its class.</p>
5286 </div>
5287 <table class="tableblock frame-all grid-all fit-content">
5288 <caption class="title">Table 23. Properties of a static-length array field class <em><strong>F</strong></em>.</caption>
5289 <colgroup>
5290 <col>
5291 <col>
5292 <col>
5293 <col>
5294 <col>
5295 </colgroup>
5296 <thead>
5297 <tr>
5298 <th class="tableblock halign-left valign-top">Name</th>
5299 <th class="tableblock halign-left valign-top">Type</th>
5300 <th class="tableblock halign-left valign-top">Description</th>
5301 <th class="tableblock halign-left valign-top">Required?</th>
5302 <th class="tableblock halign-left valign-top">Default</th>
5303 </tr>
5304 </thead>
5305 <tbody>
5306 <tr>
5307 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
5308 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
5309 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5310 <p>Type of&#160;<em><strong>F</strong></em>.</p>
5311 </div>
5312 <div class="paragraph">
5313 <p>The value of this property <em>MUST</em> be <code>"static-length-array"</code>.</p>
5314 </div></div></td>
5315 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5316 <td class="tableblock halign-left valign-top"></td>
5317 </tr>
5318 <tr>
5319 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>element-field-class</code></p></td>
5320 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#fc">Field class</a></p></td>
5321 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5322 <p>Class of the element fields contained in an instance of&#160;<em><strong>F</strong></em>.</p>
5323 </div>
5324 <div class="paragraph">
5325 <p>Property inherited from the <a href="#array-fc">abstract array field class</a>.</p>
5326 </div></div></td>
5327 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5328 <td class="tableblock halign-left valign-top"></td>
5329 </tr>
5330 <tr>
5331 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>minimum-alignment</code></p></td>
5332 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
5333 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5334 <p>Minimum alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
5335 relative to the beginning of the <a href="#pkt">packet</a> which contains this
5336 instance.</p>
5337 </div>
5338 <div class="paragraph">
5339 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
5340 </div>
5341 <div class="paragraph">
5342 <p>The <a href="#align-dec"><em>effective</em> alignment</a> of the first bit of an instance
5343 of&#160;<em><strong>F</strong></em> <em>MAY</em> be greater than the value of this property.</p>
5344 </div>
5345 <div class="paragraph">
5346 <p>Property inherited from the <a href="#array-fc">abstract array field class</a>.</p>
5347 </div></div></td>
5348 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5349 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
5350 </tr>
5351 <tr>
5352 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length</code></p></td>
5353 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
5354 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5355 <p>Number of element fields contained in an instance of&#160;<em><strong>F</strong></em>.</p>
5356 </div>
5357 <div class="paragraph">
5358 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
5359 </div></div></td>
5360 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5361 <td class="tableblock halign-left valign-top"></td>
5362 </tr>
5363 <tr>
5364 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
5365 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
5366 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5367 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
5368 </div>
5369 <div class="paragraph">
5370 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
5371 root field classes.</p>
5372 </div></div></td>
5373 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5374 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
5375 </tr>
5376 <tr>
5377 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
5378 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
5379 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5380 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
5381 </div></div></td>
5382 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5383 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5384 </tr>
5385 <tr>
5386 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
5387 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
5388 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5389 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
5390 </div>
5391 <div class="paragraph">
5392 <p>Any extension which exists under this property <em>MUST</em> also be declared
5393 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
5394 </div></div></td>
5395 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5396 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5397 </tr>
5398 </tbody>
5399 </table>
5400 <div class="exampleblock">
5401 <div class="title">Example 54. Empty static-length array field class.</div>
5402 <div class="content">
5403 <div class="listingblock">
5404 <div class="content">
5405 <pre class="highlight"><code class="language-json" data-lang="json">{
5406   "type": "static-length-array",
5407   "element-field-class": {
5408     "type": "fixed-length-signed-integer",
5409     "length": 16,
5410     "byte-order": "little-endian",
5411     "alignment": 16
5412   },
5413   "length": 0
5414 }</code></pre>
5415 </div>
5416 </div>
5417 </div>
5418 </div>
5419 <div class="exampleblock">
5420 <div class="title">Example 55. Static-length array field class with instances having 100&#160;<a href="#str-fc">null-terminated string</a> fields.</div>
5421 <div class="content">
5422 <div class="listingblock">
5423 <div class="content">
5424 <pre class="highlight"><code class="language-json" data-lang="json">{
5425   "type": "static-length-array",
5426   "element-field-class": {
5427     "type": "null-terminated-string"
5428   },
5429   "length": 100
5430 }</code></pre>
5431 </div>
5432 </div>
5433 </div>
5434 </div>
5435 <div class="exampleblock">
5436 <div class="title">Example 56. Static-length array field class with <a href="#user-attrs">user attributes</a>.</div>
5437 <div class="content">
5438 <div class="listingblock">
5439 <div class="content">
5440 <pre class="highlight"><code class="language-json" data-lang="json">{
5441   "type": "static-length-array",
5442   "element-field-class": {
5443     "type": "variable-length-unsigned-integer"
5444   },
5445   "length": 13,
5446   "user-attributes": {
5447     "my.tracer": true
5448   }
5449 }</code></pre>
5450 </div>
5451 </div>
5452 </div>
5453 </div>
5454 <div class="exampleblock">
5455 <div class="title">Example 57. Static-length array field class with instances minimally aligned to 32&#160;bits.</div>
5456 <div class="content">
5457 <div class="paragraph">
5458 <p>With the following static-length array field class, a <a href="#producer-def">producer</a>
5459 can write a single 32-bit-aligned, 32-bit little-endian integer value,
5460 and have <a href="#consumer-def">consumers</a> <a href="#sl-array-field-dec">decode</a> it as
5461 an array of 32&#160;flags (booleans).</p>
5462 </div>
5463 <div class="listingblock">
5464 <div class="content">
5465 <pre class="highlight"><code class="language-json" data-lang="json">{
5466   "type": "static-length-array",
5467   "length": 32,
5468   "minimum-alignment": 32,
5469   "element-field-class": {
5470     "type": "fixed-length-boolean",
5471     "length": 1,
5472     "byte-order": "little-endian"
5473   }
5474 }</code></pre>
5475 </div>
5476 </div>
5477 </div>
5478 </div>
5479 </div>
5480 <div class="sect3">
5481 <h4 id="dl-array-fc">5.4.23. Dynamic-length array field class</h4>
5482 <div class="paragraph">
5483 <p>A <em>dynamic-length array</em> field class is an <a href="#array-fc">abstract array field class</a>
5484 which describes <em>dynamic-length array</em> fields.</p>
5485 </div>
5486 <div class="paragraph">
5487 <p>A dynamic-length array field is a sequence of zero or more element fields.</p>
5488 </div>
5489 <div class="paragraph">
5490 <p>The length, or number of element fields, of a dynamic-length array field is the
5491 value of another, anterior (already encoded/decoded) <em>length</em> field. A
5492 <a href="#consumer-def">consumer</a> can locate this length field thanks to the
5493 <code>length-field-location</code> property of the dynamic-length array field class.</p>
5494 </div>
5495 <table class="tableblock frame-all grid-all fit-content">
5496 <caption class="title">Table 24. Properties of a dynamic-length array field class <em><strong>F</strong></em>.</caption>
5497 <colgroup>
5498 <col>
5499 <col>
5500 <col>
5501 <col>
5502 <col>
5503 </colgroup>
5504 <thead>
5505 <tr>
5506 <th class="tableblock halign-left valign-top">Name</th>
5507 <th class="tableblock halign-left valign-top">Type</th>
5508 <th class="tableblock halign-left valign-top">Description</th>
5509 <th class="tableblock halign-left valign-top">Required?</th>
5510 <th class="tableblock halign-left valign-top">Default</th>
5511 </tr>
5512 </thead>
5513 <tbody>
5514 <tr>
5515 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
5516 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
5517 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5518 <p>Type of&#160;<em><strong>F</strong></em>.</p>
5519 </div>
5520 <div class="paragraph">
5521 <p>The value of this property <em>MUST</em> be <code>"dynamic-length-array"</code>.</p>
5522 </div></div></td>
5523 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5524 <td class="tableblock halign-left valign-top"></td>
5525 </tr>
5526 <tr>
5527 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>element-field-class</code></p></td>
5528 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#fc">Field class</a></p></td>
5529 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5530 <p>Class of the element fields contained in an instance of&#160;<em><strong>F</strong></em>.</p>
5531 </div>
5532 <div class="paragraph">
5533 <p>Property inherited from the <a href="#array-fc">abstract array field class</a>.</p>
5534 </div></div></td>
5535 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5536 <td class="tableblock halign-left valign-top"></td>
5537 </tr>
5538 <tr>
5539 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>minimum-alignment</code></p></td>
5540 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
5541 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5542 <p>Minimum alignment of the first bit of an instance of&#160;<em><strong>F</strong></em>
5543 relative to the beginning of the <a href="#pkt">packet</a> which contains this
5544 instance.</p>
5545 </div>
5546 <div class="paragraph">
5547 <p>The value of this property <em>MUST</em> be a positive power of two.</p>
5548 </div>
5549 <div class="paragraph">
5550 <p>The <a href="#align-dec"><em>effective</em> alignment</a> of the first bit of an instance
5551 of&#160;<em><strong>F</strong></em> <em>MAY</em> be greater than the value of this property.</p>
5552 </div>
5553 <div class="paragraph">
5554 <p>Property inherited from the <a href="#array-fc">abstract array field class</a>.</p>
5555 </div></div></td>
5556 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5557 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>1</code></p></td>
5558 </tr>
5559 <tr>
5560 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>length-field-location</code></p></td>
5561 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#field-loc">Field location</a></p></td>
5562 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5563 <p>Location of the field of which the value is the number of element
5564 fields contained in an instance of&#160;<em><strong>F</strong></em>.</p>
5565 </div>
5566 <div class="paragraph">
5567 <p>The class of the length field <em>MUST</em> be one of:</p>
5568 </div>
5569 <div class="ulist">
5570 <ul>
5571 <li>
5572 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a></p>
5573 </li>
5574 <li>
5575 <p><a href="#vl-int-fc">Variable-length unsigned integer field class</a></p>
5576 </li>
5577 </ul>
5578 </div></div></td>
5579 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5580 <td class="tableblock halign-left valign-top"></td>
5581 </tr>
5582 <tr>
5583 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
5584 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
5585 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5586 <p>Roles of an instance of&#160;<em><strong>F</strong></em>.</p>
5587 </div>
5588 <div class="paragraph">
5589 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
5590 root field classes.</p>
5591 </div></div></td>
5592 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5593 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
5594 </tr>
5595 <tr>
5596 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
5597 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
5598 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5599 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
5600 </div></div></td>
5601 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5602 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5603 </tr>
5604 <tr>
5605 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
5606 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
5607 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5608 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
5609 </div>
5610 <div class="paragraph">
5611 <p>Any extension which exists under this property <em>MUST</em> also be declared
5612 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
5613 </div></div></td>
5614 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5615 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5616 </tr>
5617 </tbody>
5618 </table>
5619 <div class="exampleblock">
5620 <div class="title">Example 58. Dynamic-length array field class.</div>
5621 <div class="content">
5622 <div class="listingblock">
5623 <div class="content">
5624 <pre class="highlight"><code class="language-json" data-lang="json">{
5625   "type": "dynamic-length-array",
5626   "element-field-class": {
5627     "type": "fixed-length-unsigned-integer",
5628     "length": 32,
5629     "byte-order": "big-endian",
5630     "alignment": 16
5631   },
5632   "length-field-location": ["event-record-payload", "length"]
5633 }</code></pre>
5634 </div>
5635 </div>
5636 </div>
5637 </div>
5638 <div class="exampleblock">
5639 <div class="title">Example 59. Dynamic-length array field class with <a href="#user-attrs">user attributes</a>.</div>
5640 <div class="content">
5641 <div class="listingblock">
5642 <div class="content">
5643 <pre class="highlight"><code class="language-json" data-lang="json">{
5644   "type": "dynamic-length-array",
5645   "element-field-class": {
5646     "type": "variable-length-unsigned-integer"
5647   },
5648   "length-field-location": ["packet-context", "common-length"],
5649   "user-attributes": {
5650     "my.tracer": 177
5651   }
5652 }</code></pre>
5653 </div>
5654 </div>
5655 </div>
5656 </div>
5657 </div>
5658 <div class="sect3">
5659 <h4 id="opt-fc">5.4.24. Optional field class</h4>
5660 <div class="paragraph">
5661 <p>An <em>optional</em> field class describes <em>optional</em> fields.</p>
5662 </div>
5663 <div class="paragraph">
5664 <p>An optional field is, depending on the value of another, anterior
5665 (already encoded/decoded) <em>selector</em> field, one of:</p>
5666 </div>
5667 <div class="ulist">
5668 <ul>
5669 <li>
5670 <p>An instance of a given field class (<code>field-class</code> property of the
5671 optional field class).</p>
5672 <div class="paragraph">
5673 <p>In this case, the optional field is said to be <em>enabled</em>.</p>
5674 </div>
5675 </li>
5676 <li>
5677 <p>A zero-bit field (no field).</p>
5678 <div class="paragraph">
5679 <p>In this case, the optional field is said to be <em>disabled</em>.</p>
5680 </div>
5681 </li>
5682 </ul>
5683 </div>
5684 <div class="paragraph">
5685 <p>A <a href="#consumer-def">consumer</a> can locate the selector field thanks to the
5686 <code>selector-field-location</code> property of the optional field class.</p>
5687 </div>
5688 <table class="tableblock frame-all grid-all fit-content">
5689 <caption class="title">Table 25. Properties of an optional field class <em><strong>F</strong></em>.</caption>
5690 <colgroup>
5691 <col>
5692 <col>
5693 <col>
5694 <col>
5695 <col>
5696 </colgroup>
5697 <thead>
5698 <tr>
5699 <th class="tableblock halign-left valign-top">Name</th>
5700 <th class="tableblock halign-left valign-top">Type</th>
5701 <th class="tableblock halign-left valign-top">Description</th>
5702 <th class="tableblock halign-left valign-top">Required?</th>
5703 <th class="tableblock halign-left valign-top">Default</th>
5704 </tr>
5705 </thead>
5706 <tbody>
5707 <tr>
5708 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
5709 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
5710 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5711 <p>Type of&#160;<em><strong>F</strong></em>.</p>
5712 </div>
5713 <div class="paragraph">
5714 <p>The value of this property <em>MUST</em> be <code>"optional"</code>.</p>
5715 </div></div></td>
5716 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5717 <td class="tableblock halign-left valign-top"></td>
5718 </tr>
5719 <tr>
5720 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>field-class</code></p></td>
5721 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#fc">Field class</a></p></td>
5722 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5723 <p>Class of an instance of&#160;<em><strong>F</strong></em> when it&#8217;s enabled.</p>
5724 </div></div></td>
5725 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5726 <td class="tableblock halign-left valign-top"></td>
5727 </tr>
5728 <tr>
5729 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>selector-field-location</code></p></td>
5730 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#field-loc">Field location</a></p></td>
5731 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5732 <p>Location of the field of which the value indicates whether or not an
5733 instance of&#160;<em><strong>F</strong></em> is enabled.</p>
5734 </div>
5735 <div class="paragraph">
5736 <p>A selector field&#160;<em><strong>S</strong></em> <em>MUST</em> be an instance of one of:</p>
5737 </div>
5738 <div class="dlist">
5739 <dl>
5740 <dt class="hdlist1"><a href="#fl-bool-fc">Fixed-length boolean field class</a></dt>
5741 <dd>
5742 <p>An instance of&#160;<em><strong>F</strong></em> is enabled when&#160;<em><strong>S</strong></em> is
5743 true.</p>
5744 </dd>
5745 <dt class="hdlist1"><a href="#fl-int-fc">Fixed-length integer field class</a></dt>
5746 <dt class="hdlist1"><a href="#vl-int-fc">Variable-length integer field class</a></dt>
5747 <dd>
5748 <p>An instance of&#160;<em><strong>F</strong></em> is enabled when the value
5749 of&#160;<em><strong>S</strong></em> is an element of any of the integer ranges of the
5750 <code>selector-field-ranges</code> property of&#160;<em><strong>F</strong></em>.</p>
5751 </dd>
5752 </dl>
5753 </div>
5754 <div class="paragraph">
5755 <p>For a given instance of&#160;<em><strong>F</strong></em>, the <code>type</code> property of the
5756 <a href="#fc">classes</a> of <em>all</em> the possible selector fields <em>MUST</em> be
5757 one of:</p>
5758 </div>
5759 <div class="ulist">
5760 <ul>
5761 <li>
5762 <p><a href="#fl-bool-fc"><code>"fixed-length-boolean"</code></a></p>
5763 </li>
5764 <li>
5765 <p>Any of:</p>
5766 <div class="ulist">
5767 <ul>
5768 <li>
5769 <p><a href="#fl-int-fc"><code>"fixed-length-unsigned-integer"</code></a></p>
5770 </li>
5771 <li>
5772 <p><a href="#fl-enum-fc"><code>"fixed-length-unsigned-enumeration"</code></a></p>
5773 </li>
5774 <li>
5775 <p><a href="#vl-int-fc"><code>"variable-length-unsigned-integer"</code></a></p>
5776 </li>
5777 <li>
5778 <p><a href="#vl-enum-fc"><code>"variable-length-unsigned-enumeration"</code></a></p>
5779 </li>
5780 </ul>
5781 </div>
5782 </li>
5783 <li>
5784 <p>Any of:</p>
5785 <div class="ulist">
5786 <ul>
5787 <li>
5788 <p><a href="#fl-int-fc"><code>"fixed-length-signed-integer"</code></a></p>
5789 </li>
5790 <li>
5791 <p><a href="#fl-enum-fc"><code>"fixed-length-signed-enumeration"</code></a></p>
5792 </li>
5793 <li>
5794 <p><a href="#vl-int-fc"><code>"variable-length-signed-integer"</code></a></p>
5795 </li>
5796 <li>
5797 <p><a href="#vl-enum-fc"><code>"variable-length-signed-enumeration"</code></a></p>
5798 </li>
5799 </ul>
5800 </div>
5801 </li>
5802 </ul>
5803 </div></div></td>
5804 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5805 <td class="tableblock halign-left valign-top"></td>
5806 </tr>
5807 <tr>
5808 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>selector-field-ranges</code></p></td>
5809 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#int-range-set">Integer range set</a></p></td>
5810 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5811 <p>Ranges of integers which the value of a selector field <em>MUST</em> be an
5812 element of to enable an instance of&#160;<em><strong>F</strong></em>.</p>
5813 </div></div></td>
5814 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes, if the selector field is an instance of a <a href="#fl-int-fc">fixed-length integer field class</a>
5815 or a <a href="#vl-int-fc">variable-length integer field class</a>.</p></td>
5816 <td class="tableblock halign-left valign-top"><p class="tableblock">None if the selector field is an instance of a <a href="#fl-bool-fc">fixed-length boolean field class</a>.</p></td>
5817 </tr>
5818 <tr>
5819 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
5820 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
5821 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5822 <p>Roles of&#160;<em><strong>F</strong></em>.</p>
5823 </div>
5824 <div class="paragraph">
5825 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
5826 root field classes.</p>
5827 </div></div></td>
5828 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5829 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
5830 </tr>
5831 <tr>
5832 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
5833 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
5834 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5835 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
5836 </div></div></td>
5837 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5838 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5839 </tr>
5840 <tr>
5841 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
5842 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
5843 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5844 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
5845 </div>
5846 <div class="paragraph">
5847 <p>Any extension which exists under this property <em>MUST</em> also be declared
5848 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
5849 </div></div></td>
5850 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
5851 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
5852 </tr>
5853 </tbody>
5854 </table>
5855 <div class="exampleblock">
5856 <div class="title">Example 60. Optional <a href="#sl-array-fc">static-length array field class</a> with a <a href="#bool-fc">boolean</a> selector field class.</div>
5857 <div class="content">
5858 <div class="listingblock">
5859 <div class="content">
5860 <pre class="highlight"><code class="language-json" data-lang="json">{
5861   "type": "optional",
5862   "selector-field-location": ["event-record-payload", "has-ip"],
5863   "field-class": {
5864     "type": "static-length-array",
5865     "element-field-class": {
5866       "type": "fixed-length-unsigned-integer",
5867       "length": 8,
5868       "byte-order": "little-endian",
5869       "alignment": 8
5870     },
5871     "length": 16
5872   }
5873 }</code></pre>
5874 </div>
5875 </div>
5876 </div>
5877 </div>
5878 <div class="exampleblock">
5879 <div class="title">Example 61. Optional null-terminated string with a <a href="#fl-int-fc">fixed-length signed integer</a> selector field class.</div>
5880 <div class="content">
5881 <div class="listingblock">
5882 <div class="content">
5883 <pre class="highlight"><code class="language-json" data-lang="json">{
5884   "type": "optional",
5885   "selector-field-location": ["event-record-payload", "has-ip"],
5886   "selector-field-ranges": [[-12, -12], [-5, 0], [15, 35]],
5887   "field-class": {
5888     "type": "null-terminated-string"
5889   }
5890 }</code></pre>
5891 </div>
5892 </div>
5893 </div>
5894 </div>
5895 </div>
5896 <div class="sect3">
5897 <h4 id="var-fc">5.4.25. Variant field class</h4>
5898 <div class="paragraph">
5899 <p>A <em>variant</em> field class describes <em>variant</em> fields.</p>
5900 </div>
5901 <div class="paragraph">
5902 <p>A variant field is, depending on the value of another, anterior (already
5903 encoded/decoded) <em>selector</em> field, the instance of a specific, effective
5904 field class amongst one or more <em>variant field class options</em>.</p>
5905 </div>
5906 <div class="paragraph">
5907 <p>A <a href="#consumer-def">consumer</a> can locate the selector field thanks to the
5908 <code>selector-field-location</code> property of the variant field class.</p>
5909 </div>
5910 <table class="tableblock frame-all grid-all fit-content">
5911 <caption class="title">Table 26. Properties of a variant field class <em><strong>F</strong></em>.</caption>
5912 <colgroup>
5913 <col>
5914 <col>
5915 <col>
5916 <col>
5917 <col>
5918 </colgroup>
5919 <thead>
5920 <tr>
5921 <th class="tableblock halign-left valign-top">Name</th>
5922 <th class="tableblock halign-left valign-top">Type</th>
5923 <th class="tableblock halign-left valign-top">Description</th>
5924 <th class="tableblock halign-left valign-top">Required?</th>
5925 <th class="tableblock halign-left valign-top">Default</th>
5926 </tr>
5927 </thead>
5928 <tbody>
5929 <tr>
5930 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
5931 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
5932 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5933 <p>Type of&#160;<em><strong>F</strong></em>.</p>
5934 </div>
5935 <div class="paragraph">
5936 <p>The value of this property <em>MUST</em> be <code>"variant"</code>.</p>
5937 </div></div></td>
5938 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5939 <td class="tableblock halign-left valign-top"></td>
5940 </tr>
5941 <tr>
5942 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>options</code></p></td>
5943 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON array of <a href="#var-fc-opt">variant field class options</a></p></td>
5944 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5945 <p>Options containing the possible effective classes of an instance
5946 of&#160;<em><strong>F</strong></em>.</p>
5947 </div>
5948 <div class="paragraph">
5949 <p>This array <em>MUST</em> contain one or more elements.</p>
5950 </div>
5951 <div class="paragraph">
5952 <p>The <code>name</code> property of each option, if it&#8217;s set, <em>MUST</em> be unique within
5953 the option names of&#160;<em><strong>F</strong></em>.</p>
5954 </div>
5955 <div class="paragraph">
5956 <p>The integer ranges (<code>selector-field-ranges</code> property) of two given
5957 options <em>MUST&#160;NOT</em> intersect.</p>
5958 </div></div></td>
5959 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
5960 <td class="tableblock halign-left valign-top"></td>
5961 </tr>
5962 <tr>
5963 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>selector-field-location</code></p></td>
5964 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#field-loc">Field location</a></p></td>
5965 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5966 <p>Location of the field of which the value indicates which option
5967 of&#160;<em><strong>F</strong></em> contains the effective class of an instance
5968 of&#160;<em><strong>F</strong></em>.</p>
5969 </div>
5970 <div class="paragraph">
5971 <p>For a given instance of&#160;<em><strong>F</strong></em>, the <code>type</code> property of the
5972 <a href="#fc">classes</a> of <em>all</em> the possible selector fields <em>MUST</em> be
5973 one of:</p>
5974 </div>
5975 <div class="ulist">
5976 <ul>
5977 <li>
5978 <p>Any of:</p>
5979 <div class="ulist">
5980 <ul>
5981 <li>
5982 <p><a href="#fl-int-fc"><code>"fixed-length-unsigned-integer"</code></a></p>
5983 </li>
5984 <li>
5985 <p><a href="#fl-enum-fc"><code>"fixed-length-unsigned-enumeration"</code></a></p>
5986 </li>
5987 <li>
5988 <p><a href="#vl-int-fc"><code>"variable-length-unsigned-integer"</code></a></p>
5989 </li>
5990 <li>
5991 <p><a href="#vl-enum-fc"><code>"variable-length-unsigned-enumeration"</code></a></p>
5992 </li>
5993 </ul>
5994 </div>
5995 </li>
5996 <li>
5997 <p>Any of:</p>
5998 <div class="ulist">
5999 <ul>
6000 <li>
6001 <p><a href="#fl-int-fc"><code>"fixed-length-signed-integer"</code></a></p>
6002 </li>
6003 <li>
6004 <p><a href="#fl-enum-fc"><code>"fixed-length-signed-enumeration"</code></a></p>
6005 </li>
6006 <li>
6007 <p><a href="#vl-int-fc"><code>"variable-length-signed-integer"</code></a></p>
6008 </li>
6009 <li>
6010 <p><a href="#vl-enum-fc"><code>"variable-length-signed-enumeration"</code></a></p>
6011 </li>
6012 </ul>
6013 </div>
6014 </li>
6015 </ul>
6016 </div></div></td>
6017 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6018 <td class="tableblock halign-left valign-top"></td>
6019 </tr>
6020 <tr>
6021 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>roles</code></p></td>
6022 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#roles">Roles</a></p></td>
6023 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6024 <p>Roles of&#160;<em><strong>F</strong></em>.</p>
6025 </div>
6026 <div class="paragraph">
6027 <p>See <a href="#tc-frag">Trace class fragment</a> and <a href="#dsc-frag">Data stream class fragment</a> which indicate accepted within their
6028 root field classes.</p>
6029 </div></div></td>
6030 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6031 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[]</code></p></td>
6032 </tr>
6033 <tr>
6034 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
6035 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
6036 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6037 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
6038 </div></div></td>
6039 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6040 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6041 </tr>
6042 <tr>
6043 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
6044 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
6045 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6046 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
6047 </div>
6048 <div class="paragraph">
6049 <p>Any extension which exists under this property <em>MUST</em> also be declared
6050 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
6051 </div></div></td>
6052 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6053 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6054 </tr>
6055 </tbody>
6056 </table>
6057 <div class="exampleblock">
6058 <div class="title">Example 62. Variant field class with two options.</div>
6059 <div class="content">
6060 <div class="listingblock">
6061 <div class="content">
6062 <pre class="highlight"><code class="language-json" data-lang="json">{
6063   "type": "variant",
6064   "selector-field-location": ["event-record-payload", "sel"],
6065   "options": [
6066     {
6067       "selector-field-ranges": [[5, 5]],
6068       "field-class": {
6069         "type": "null-terminated-string"
6070       }
6071     },
6072     {
6073       "selector-field-ranges": [[8, 8]],
6074       "field-class": {
6075         "type": "fixed-length-signed-integer",
6076         "length": 16,
6077         "byte-order": "little-endian",
6078         "preferred-display-base": 8
6079       }
6080     }
6081   ]
6082 }</code></pre>
6083 </div>
6084 </div>
6085 </div>
6086 </div>
6087 <div class="exampleblock">
6088 <div class="title">Example 63. Variant field class within an <a href="#opt-fc">optional field class</a> which share the same selector field location.</div>
6089 <div class="content">
6090 <div class="paragraph">
6091 <p>This example shows that an optional field class and a contained variant
6092 field class <em>MAY</em> share the same selector field location.</p>
6093 </div>
6094 <div class="paragraph">
6095 <p>In this example, depending on the value of the selector field:</p>
6096 </div>
6097 <div class="hdlist">
6098 <table>
6099 <tr>
6100 <td class="hdlist1">
6101 0
6102 </td>
6103 <td class="hdlist2">
6104 <p>The optional field is <em>not</em> enabled.</p>
6105 </td>
6106 </tr>
6107 <tr>
6108 <td class="hdlist1">
6109 1
6110 </td>
6111 <td class="hdlist2">
6112 <p>The optional field is enabled and is a variant field.</p>
6113 <div class="paragraph">
6114 <p>The variant field is an instance of a <a href="#str-fc">null-terminated string field class</a> (effective class).</p>
6115 </div>
6116 </td>
6117 </tr>
6118 <tr>
6119 <td class="hdlist1">
6120 2
6121 </td>
6122 <td class="hdlist2">
6123 <p>The optional field is enabled and is a variant field.</p>
6124 <div class="paragraph">
6125 <p>The variant field is an instance of a <a href="#vl-int-fc">variable-length signed integer field class</a> (effective class).</p>
6126 </div>
6127 </td>
6128 </tr>
6129 </table>
6130 </div>
6131 <div class="listingblock">
6132 <div class="content">
6133 <pre class="highlight"><code class="language-json" data-lang="json">{
6134   "type": "optional",
6135   "selector-field-location": ["event-record-payload", "sel"],
6136   "selector-field-ranges": [[1, 255]],
6137   "field-class": {
6138     "type": "variant",
6139     "selector-field-location": ["event-record-payload", "sel"],
6140     "options": [
6141       {
6142         "selector-field-ranges": [[1, 1]],
6143         "field-class": {
6144           "type": "null-terminated-string"
6145         }
6146       },
6147       {
6148         "selector-field-ranges": [[2, 2]],
6149         "field-class": {
6150           "type": "variable-length-signed-integer",
6151           "preferred-display-base": 16
6152         }
6153       }
6154     ]
6155   }
6156 }</code></pre>
6157 </div>
6158 </div>
6159 </div>
6160 </div>
6161 <div class="exampleblock">
6162 <div class="title">Example 64. Variant field class with <a href="#user-attrs">user attributes</a>.</div>
6163 <div class="content">
6164 <div class="listingblock">
6165 <div class="content">
6166 <pre class="highlight"><code class="language-json" data-lang="json">{
6167   "type": "variant",
6168   "selector-field-location": ["event-record-specific-context", "sel"],
6169   "options": [
6170     {
6171       "selector-field-ranges": [[5, 5], [10, 10], [15, 15]],
6172       "field-class": {
6173         "type": "static-length-string",
6174         "length": 20
6175       }
6176     },
6177     {
6178       "selector-field-ranges": [[0, 4], [6, 9], [11, 14], [16, 127]],
6179       "field-class": {
6180         "type": "fixed-length-floating-point-number",
6181         "length": 32,
6182         "byte-order": "big-endian"
6183       }
6184     }
6185   ],
6186   "user-attributes": {
6187     "my.tracer": {
6188       "owner": "Jimmy",
6189       "id": 199990
6190     }
6191   }
6192 }</code></pre>
6193 </div>
6194 </div>
6195 </div>
6196 </div>
6197 <div class="sect4">
6198 <h5 id="var-fc-opt">5.4.25.1. Variant field class option</h5>
6199 <div class="paragraph">
6200 <p>A <em>variant field class option</em> contains a possible effective class of a
6201 variant field.</p>
6202 </div>
6203 <div class="paragraph">
6204 <p>A variant field class option&#160;<em><strong>O</strong></em> also contains the ranges of
6205 integer values (<code>selector-field-ranges</code> property) of which the value of
6206 a selector field <em>MUST</em> be an element of for the effective class of a
6207 variant field to be the field class of <em><strong>O</strong></em>.</p>
6208 </div>
6209 <div class="paragraph">
6210 <p>A variant field class option is a JSON object.</p>
6211 </div>
6212 <table class="tableblock frame-all grid-all fit-content">
6213 <caption class="title">Table 27. Properties of a variant field class option <em><strong>O</strong></em> contained in a variant field class&#160;<em><strong>F</strong></em>.</caption>
6214 <colgroup>
6215 <col>
6216 <col>
6217 <col>
6218 <col>
6219 <col>
6220 </colgroup>
6221 <thead>
6222 <tr>
6223 <th class="tableblock halign-left valign-top">Name</th>
6224 <th class="tableblock halign-left valign-top">Type</th>
6225 <th class="tableblock halign-left valign-top">Description</th>
6226 <th class="tableblock halign-left valign-top">Required?</th>
6227 <th class="tableblock halign-left valign-top">Default</th>
6228 </tr>
6229 </thead>
6230 <tbody>
6231 <tr>
6232 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>field-class</code></p></td>
6233 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#fc">Field class</a></p></td>
6234 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6235 <p>Field class of&#160;<em><strong>O</strong></em>.</p>
6236 </div></div></td>
6237 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6238 <td class="tableblock halign-left valign-top"></td>
6239 </tr>
6240 <tr>
6241 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>selector-field-ranges</code></p></td>
6242 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#int-range-set">Integer range set</a></p></td>
6243 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6244 <p>Ranges of integers which the value of a selector field <em>MUST</em> be an
6245 element of for the effective class of an instance of&#160;<em><strong>F</strong></em>
6246 to be the field class (<code>field-class</code> property) of&#160;<em><strong>O</strong></em>.</p>
6247 </div></div></td>
6248 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6249 <td class="tableblock halign-left valign-top"></td>
6250 </tr>
6251 <tr>
6252 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td>
6253 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
6254 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6255 <p>Name of&#160;<em><strong>O</strong></em>.</p>
6256 </div>
6257 <div class="paragraph">
6258 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
6259 it&#8217;s not strictly needed to decode an instance of&#160;<em><strong>F</strong></em>.</p>
6260 </div></div></td>
6261 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6262 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>O</strong></em> is unnamed</p></td>
6263 </tr>
6264 <tr>
6265 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
6266 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
6267 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6268 <p>User attributes of&#160;<em><strong>O</strong></em>.</p>
6269 </div></div></td>
6270 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6271 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6272 </tr>
6273 <tr>
6274 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
6275 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
6276 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6277 <p>Extensions of&#160;<em><strong>O</strong></em>.</p>
6278 </div>
6279 <div class="paragraph">
6280 <p>Any extension which exists under this property <em>MUST</em> also be declared
6281 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
6282 </div></div></td>
6283 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6284 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6285 </tr>
6286 </tbody>
6287 </table>
6288 <div class="exampleblock">
6289 <div class="title">Example 65. Unnamed <a href="#str-fc">null-terminated string field class</a> option.</div>
6290 <div class="content">
6291 <div class="listingblock">
6292 <div class="content">
6293 <pre class="highlight"><code class="language-json" data-lang="json">{
6294   "field-class": {
6295     "type": "null-terminated-string"
6296   },
6297   "selector-field-ranges": [[3, 9]]
6298 }</code></pre>
6299 </div>
6300 </div>
6301 </div>
6302 </div>
6303 <div class="exampleblock">
6304 <div class="title">Example 66. <a href="#vl-int-fc">Variable-length signed integer field class</a> option named <code>juice</code> with <a href="#user-attrs">user attributes</a>.</div>
6305 <div class="content">
6306 <div class="listingblock">
6307 <div class="content">
6308 <pre class="highlight"><code class="language-json" data-lang="json">{
6309   "name": "juice",
6310   "field-class": {
6311     "type": "variable-length-signed-integer",
6312     "preferred-display-base": 16
6313   },
6314   "selector-field-ranges": [[-4, 4], [9, 9], [100, 200]],
6315   "user-attributes": {
6316     "my.tracer": {
6317       "uuid": [
6318         243, 97, 0, 184, 236, 54, 72, 97,
6319         141, 107, 169, 214, 171, 137, 115, 201
6320       ],
6321       "is-did": true
6322     }
6323   }
6324 }</code></pre>
6325 </div>
6326 </div>
6327 </div>
6328 </div>
6329 </div>
6330 </div>
6331 </div>
6332 <div class="sect2">
6333 <h3 id="preamble-frag">5.5. Preamble fragment</h3>
6334 <div class="paragraph">
6335 <p>A <em>preamble fragment</em> indicates:</p>
6336 </div>
6337 <div class="ulist">
6338 <ul>
6339 <li>
6340 <p>The CTF&#160;2 major version (2).</p>
6341 <div class="paragraph">
6342 <p>CTF&#160;2 doesn&#8217;t have a minor version: users can use
6343 <a href="#user-attributes">user attributes</a> and <a href="#ext">extensions</a> to add
6344 features to, or change features of, the format which this document
6345 specifies.</p>
6346 </div>
6347 </li>
6348 <li>
6349 <p><a href="#ext">Extension</a> declarations.</p>
6350 <div class="paragraph">
6351 <p>An extension declaration is an initial extension of which the purpose is
6352 to declare that it&#8217;s <em>enabled</em> within the <a href="#metadata-stream">metadata
6353 stream</a>.</p>
6354 </div>
6355 <div class="paragraph">
6356 <p>Because an extension <em>MAY</em> alter the CTF&#160;2 format itself, and because a
6357 preamble fragment is always the first metadata stream fragment, those
6358 extension declarations make it possible for a <a href="#consumer-def">consumer</a>
6359 to gracefully decline the <a href="#ds">data streams</a> of the trace if it doesn&#8217;t
6360 support <em>any</em> declared extension.</p>
6361 </div>
6362 </li>
6363 </ul>
6364 </div>
6365 <div class="paragraph">
6366 <p>The first fragment of a metadata stream <em>MUST</em> be a preamble fragment.</p>
6367 </div>
6368 <table class="tableblock frame-all grid-all fit-content">
6369 <caption class="title">Table 28. Properties of a preamble fragment <em><strong>F</strong></em>.</caption>
6370 <colgroup>
6371 <col>
6372 <col>
6373 <col>
6374 <col>
6375 <col>
6376 </colgroup>
6377 <thead>
6378 <tr>
6379 <th class="tableblock halign-left valign-top">Name</th>
6380 <th class="tableblock halign-left valign-top">Type</th>
6381 <th class="tableblock halign-left valign-top">Description</th>
6382 <th class="tableblock halign-left valign-top">Required?</th>
6383 <th class="tableblock halign-left valign-top">Default</th>
6384 </tr>
6385 </thead>
6386 <tbody>
6387 <tr>
6388 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
6389 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
6390 <td class="tableblock halign-left valign-top"><p class="tableblock">Type of&#160;<em><strong>F</strong></em>.</p>
6391 <p class="tableblock">The value of this property <em>MUST</em> be <code>"preamble"</code>.</p></td>
6392 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6393 <td class="tableblock halign-left valign-top"></td>
6394 </tr>
6395 <tr>
6396 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>version</code></p></td>
6397 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
6398 <td class="tableblock halign-left valign-top"><p class="tableblock">CTF&#160;2 major version.</p>
6399 <p class="tableblock">The value of this property <em>MUST</em> be <code>2</code>.</p></td>
6400 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6401 <td class="tableblock halign-left valign-top"></td>
6402 </tr>
6403 <tr>
6404 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
6405 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
6406 <td class="tableblock halign-left valign-top"><p class="tableblock">User attributes of&#160;<em><strong>F</strong></em>.</p></td>
6407 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6408 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6409 </tr>
6410 <tr>
6411 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
6412 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
6413 <td class="tableblock halign-left valign-top"><p class="tableblock">Extension declarations of&#160;<em><strong>F</strong></em>.</p>
6414 <p class="tableblock">The name of each property is a <a href="#ns-def">namespace</a> and its value is a
6415 <a href="#ns-exts-obj">namespaced extensions object</a>.</p>
6416 <p class="tableblock">Within a <a href="#ns-exts-obj">namespaced extensions object</a>, an extension
6417 named&#160;<em><strong>N</strong></em> is <em>declared</em> when it exists as a property
6418 named&#160;<em><strong>N</strong></em>, whatever the value of the property.</p></td>
6419 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6420 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6421 </tr>
6422 </tbody>
6423 </table>
6424 <div class="exampleblock">
6425 <div class="title">Example 67. Minimal preamble fragment.</div>
6426 <div class="content">
6427 <div class="listingblock">
6428 <div class="content">
6429 <pre class="highlight"><code class="language-json" data-lang="json">{
6430   "type": "preamble",
6431   "version": 2
6432 }</code></pre>
6433 </div>
6434 </div>
6435 </div>
6436 </div>
6437 <div class="exampleblock">
6438 <div class="title">Example 68. Preamble fragment with <a href="#ext">extension</a> declarations.</div>
6439 <div class="content">
6440 <div class="paragraph">
6441 <p>The following preamble fragment declares the <code>piano</code> and <code>ramen</code>
6442 extensions under the <code>my.tracer</code> namespace.</p>
6443 </div>
6444 <div class="listingblock">
6445 <div class="content">
6446 <pre class="highlight"><code class="language-json" data-lang="json">{
6447   "type": "preamble",
6448   "version": 2,
6449   "extensions": {
6450     "my.tracer": {
6451       "piano": {
6452         "keys": 88,
6453         "temperament": "equal"
6454       },
6455       "ramen": null
6456     }
6457   }
6458 }</code></pre>
6459 </div>
6460 </div>
6461 </div>
6462 </div>
6463 </div>
6464 <div class="sect2">
6465 <h3 id="tc-frag">5.6. Trace class fragment</h3>
6466 <div class="paragraph">
6467 <p>A <em>trace class</em> describes <a href="#trace"><em>traces</em></a>.</p>
6468 </div>
6469 <div class="paragraph">
6470 <p>Within a metadata stream, a trace class fragment <em>MUST</em> occur, if any,
6471 before any <a href="#dsc-frag">data stream class fragment</a>.</p>
6472 </div>
6473 <table class="tableblock frame-all grid-all fit-content">
6474 <caption class="title">Table 29. Properties of a trace class fragment <em><strong>F</strong></em>.</caption>
6475 <colgroup>
6476 <col>
6477 <col>
6478 <col>
6479 <col>
6480 <col>
6481 </colgroup>
6482 <thead>
6483 <tr>
6484 <th class="tableblock halign-left valign-top">Name</th>
6485 <th class="tableblock halign-left valign-top">Type</th>
6486 <th class="tableblock halign-left valign-top">Description</th>
6487 <th class="tableblock halign-left valign-top">Required?</th>
6488 <th class="tableblock halign-left valign-top">Default</th>
6489 </tr>
6490 </thead>
6491 <tbody>
6492 <tr>
6493 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
6494 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
6495 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6496 <p>Type of&#160;<em><strong>F</strong></em>.</p>
6497 </div>
6498 <div class="paragraph">
6499 <p>The value of this property <em>MUST</em> be <code>"trace-class"</code>.</p>
6500 </div></div></td>
6501 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6502 <td class="tableblock halign-left valign-top"></td>
6503 </tr>
6504 <tr>
6505 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uuid</code></p></td>
6506 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#uuid">UUID</a></p></td>
6507 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6508 <p>UUID of&#160;<em><strong>F</strong></em>.</p>
6509 </div></div></td>
6510 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6511 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no UUID</p></td>
6512 </tr>
6513 <tr>
6514 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-header-field-class</code></p></td>
6515 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#struct-fc">Structure field class</a></p></td>
6516 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6517 <p>Class of all the <a href="#pkt-header">packet header fields</a> of an instance
6518 of&#160;<em><strong>F</strong></em>.</p>
6519 </div>
6520 <div class="paragraph">
6521 <p>Any field class as the value of this property <em>MUST</em> satisfy <em>at least
6522 one of</em>:</p>
6523 </div>
6524 <div class="ulist">
6525 <ul>
6526 <li>
6527 <p>Have at least one valid <a href="#pkt-header-roles">role</a>.</p>
6528 </li>
6529 <li>
6530 <p>Be a <a href="#struct-fc">structure field class</a>.</p>
6531 </li>
6532 <li>
6533 <p>Be an <a href="#opt-fc">optional field class</a>.</p>
6534 </li>
6535 <li>
6536 <p>Be a <a href="#var-fc">variant field class</a>.</p>
6537 </li>
6538 <li>
6539 <p>Be the class of a field which is the selector field of an optional
6540 or variant field.</p>
6541 </li>
6542 </ul>
6543 </div></div></td>
6544 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6545 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no packet header field class</p></td>
6546 </tr>
6547 <tr>
6548 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
6549 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
6550 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6551 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
6552 </div></div></td>
6553 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6554 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6555 </tr>
6556 <tr>
6557 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
6558 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
6559 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6560 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
6561 </div>
6562 <div class="paragraph">
6563 <p>Any extension which exists under this property <em>MUST</em> also be declared
6564 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
6565 </div></div></td>
6566 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6567 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6568 </tr>
6569 </tbody>
6570 </table>
6571 <div class="sect3">
6572 <h4 id="_roles">5.6.1. Roles</h4>
6573 <div class="paragraph">
6574 <p><a id="pkt-header-roles"></a> If the <code>packet-header-field-class</code> property of a
6575 trace class fragment exists, then the <a href="#fc">field classes</a> of its
6576 <a href="#struct-member-cls">member classes</a> <em>MAY</em> have the following
6577 <a href="#roles">roles</a>:</p>
6578 </div>
6579 <table class="tableblock frame-all grid-all fit-content">
6580 <caption class="title">Table 30. Roles of field classes of the member classes of a packet header field class.</caption>
6581 <colgroup>
6582 <col>
6583 <col>
6584 <col>
6585 <col>
6586 </colgroup>
6587 <thead>
6588 <tr>
6589 <th class="tableblock halign-left valign-top">Name</th>
6590 <th class="tableblock halign-left valign-top">Description</th>
6591 <th class="tableblock halign-left valign-top">Field class (<em><strong>F</strong></em>) constraints</th>
6592 <th class="tableblock halign-left valign-top">Other constraints</th>
6593 </tr>
6594 </thead>
6595 <tbody>
6596 <tr>
6597 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-magic-number</code></p></td>
6598 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#pkt">Packet</a> magic number.</p>
6599 <p class="tableblock">The purpose of a packet magic number field is to confirm the beginning
6600 of a CTF&#160;2 packet.</p></td>
6601 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6602 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> with the following property value:</p>
6603 </div>
6604 <div class="hdlist">
6605 <table>
6606 <tr>
6607 <td class="hdlist1">
6608 <code>length</code>
6609 </td>
6610 <td class="hdlist2">
6611 <p><code>32</code></p>
6612 </td>
6613 </tr>
6614 </table>
6615 </div></div></td>
6616 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6617 <p>An instance of&#160;<em><strong>F</strong></em> <em>MUST</em> be the <em>first</em> member of the packet
6618 header structure field.</p>
6619 </div>
6620 <div class="paragraph">
6621 <p>The value of an instance of&#160;<em><strong>F</strong></em> value <em>MUST</em> be 0xc1fc1fc1
6622 (3254525889).</p>
6623 </div></div></td>
6624 </tr>
6625 <tr>
6626 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>trace-class-uuid</code></p></td>
6627 <td class="tableblock halign-left valign-top"><p class="tableblock">Trace class UUID.</p>
6628 <p class="tableblock">The purpose of a trace class UUID field is to confirm the association
6629 between a <a href="#ds">data stream</a> and a <a href="#metadata-stream-overview">metadata
6630 stream</a>.</p></td>
6631 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6632 <p><a href="#sl-blob-fc">Static-length BLOB field class</a> with the following property value:</p>
6633 </div>
6634 <div class="hdlist">
6635 <table>
6636 <tr>
6637 <td class="hdlist1">
6638 <code>length</code>
6639 </td>
6640 <td class="hdlist2">
6641 <p><code>16</code></p>
6642 </td>
6643 </tr>
6644 </table>
6645 </div></div></td>
6646 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6647 <p>The <code>uuid</code> property of the trace class <em>MUST</em> exist.</p>
6648 </div>
6649 <div class="paragraph">
6650 <p>The 16&#160;bytes of an instance of&#160;<em><strong>F</strong></em> <em>MUST</em> be equal to the
6651 16&#160;JSON integers of the <code>uuid</code> property of the trace class.</p>
6652 </div></div></td>
6653 </tr>
6654 <tr>
6655 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>data-stream-class-id</code></p></td>
6656 <td class="tableblock halign-left valign-top"><p class="tableblock">Data stream class ID.</p>
6657 <p class="tableblock">The purpose of a data stream class ID field is to set the current ID of
6658 the class of the data stream of the current packet.</p></td>
6659 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6660 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
6661 </div></div></td>
6662 <td class="tableblock halign-left valign-top"><div class="content"></div></td>
6663 </tr>
6664 <tr>
6665 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>data-stream-id</code></p></td>
6666 <td class="tableblock halign-left valign-top"><p class="tableblock">Data stream ID.</p>
6667 <p class="tableblock">The purpose of a data stream ID field is to set the current ID of
6668 the data stream of the current packet.</p>
6669 <p class="tableblock">Combined with the ID of its class, such a field makes it possible to
6670 uniquely identify a data stream within a <a href="#trace">trace</a>.</p></td>
6671 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6672 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
6673 </div></div></td>
6674 <td class="tableblock halign-left valign-top"><div class="content"></div></td>
6675 </tr>
6676 </tbody>
6677 </table>
6678 <div class="exampleblock">
6679 <div class="title">Example 69. Trace class fragment.</div>
6680 <div class="content">
6681 <div class="listingblock">
6682 <div class="content">
6683 <pre class="highlight"><code class="language-json" data-lang="json">{
6684   "type": "trace-class",
6685   "uuid": [
6686     30, 201, 100, 148, 228, 2, 69, 70,
6687     147, 219, 233, 34, 43, 238, 108, 199
6688   ],
6689   "packet-header-field-class": {
6690     "type": "structure",
6691     "member-classes": [
6692       {
6693         "name": "the magic!",
6694         "field-class": {
6695           "type": "fixed-length-unsigned-integer",
6696           "length": 32,
6697           "byte-order": "little-endian",
6698           "preferred-display-base": 16,
6699           "roles": ["packet-magic-number"]
6700         }
6701       },
6702       {
6703         "name": "the UUID",
6704         "field-class": {
6705           "type": "static-length-blob",
6706           "length": 16,
6707           "roles": ["trace-class-uuid"]
6708         }
6709       },
6710       {
6711         "name": "my data stream class ID",
6712         "field-class": {
6713           "type": "fixed-length-unsigned-integer",
6714           "length": 8,
6715           "byte-order": "little-endian",
6716           "roles": ["data-stream-class-id"]
6717         }
6718       },
6719       {
6720         "name": "my data stream ID",
6721         "field-class": {
6722           "type": "variable-length-unsigned-integer",
6723           "roles": ["data-stream-id"]
6724         }
6725       }
6726     ]
6727   }
6728 }</code></pre>
6729 </div>
6730 </div>
6731 </div>
6732 </div>
6733 </div>
6734 </div>
6735 <div class="sect2">
6736 <h3 id="cc-frag">5.7. Clock class fragment</h3>
6737 <div class="paragraph">
6738 <p>A <em>clock class</em> describes <em>clocks</em>.</p>
6739 </div>
6740 <div class="paragraph">
6741 <p>A <a href="#ds">data stream</a> <em>MAY</em> have a <a href="#def-clk">default clock</a>.</p>
6742 </div>
6743 <div class="paragraph">
6744 <p>Within a metadata stream, a clock class fragment <em>MUST</em> occur before any
6745 <a href="#dsc-frag">data stream class fragment</a> which refers to it by name with
6746 its <code>default-clock-class-name</code> property.</p>
6747 </div>
6748 <table class="tableblock frame-all grid-all fit-content">
6749 <caption class="title">Table 31. Properties of a clock class fragment <em><strong>F</strong></em>.</caption>
6750 <colgroup>
6751 <col>
6752 <col>
6753 <col>
6754 <col>
6755 <col>
6756 </colgroup>
6757 <thead>
6758 <tr>
6759 <th class="tableblock halign-left valign-top">Name</th>
6760 <th class="tableblock halign-left valign-top">Type</th>
6761 <th class="tableblock halign-left valign-top">Description</th>
6762 <th class="tableblock halign-left valign-top">Required?</th>
6763 <th class="tableblock halign-left valign-top">Default</th>
6764 </tr>
6765 </thead>
6766 <tbody>
6767 <tr>
6768 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
6769 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
6770 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6771 <p>Type of&#160;<em><strong>F</strong></em>.</p>
6772 </div>
6773 <div class="paragraph">
6774 <p>The value of this property <em>MUST</em> be <code>"clock-class"</code>.</p>
6775 </div></div></td>
6776 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6777 <td class="tableblock halign-left valign-top"></td>
6778 </tr>
6779 <tr>
6780 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>frequency</code></p></td>
6781 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
6782 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6783 <p>Frequency of an instance of&#160;<em><strong>F</strong></em> (Hz).</p>
6784 </div>
6785 <div class="paragraph">
6786 <p>The value of this property <em>MUST</em> be greater than zero.</p>
6787 </div></div></td>
6788 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6789 <td class="tableblock halign-left valign-top"></td>
6790 </tr>
6791 <tr>
6792 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td>
6793 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
6794 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6795 <p>Name of&#160;<em><strong>F</strong></em>.</p>
6796 </div></div></td>
6797 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
6798 <td class="tableblock halign-left valign-top"></td>
6799 </tr>
6800 <tr>
6801 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>description</code></p></td>
6802 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
6803 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6804 <p>Textual description of&#160;<em><strong>F</strong></em>.</p>
6805 </div>
6806 <div class="paragraph">
6807 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
6808 it&#8217;s not strictly needed to decode <a href="#ds">data streams</a>.</p>
6809 </div></div></td>
6810 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6811 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no textual description</p></td>
6812 </tr>
6813 <tr>
6814 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uuid</code></p></td>
6815 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#uuid">UUID</a></p></td>
6816 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6817 <p>UUID of&#160;<em><strong>F</strong></em>.</p>
6818 </div>
6819 <div class="paragraph">
6820 <p>This property exists to remain backward compatible with <a href="https://diamon.org/ctf/v1.8.3/">CTF&#160;1</a>:
6821 it&#8217;s not strictly needed to decode <a href="#ds">data streams</a>.</p>
6822 </div></div></td>
6823 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6824 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no UUID</p></td>
6825 </tr>
6826 <tr>
6827 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>origin-is-unix-epoch</code></p></td>
6828 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON boolean</p></td>
6829 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6830 <p>Whether or not the origin of an instance of&#160;<em><strong>F</strong></em> is
6831 the <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.</p>
6832 </div>
6833 <div class="paragraph">
6834 <p>If the value of this property is <code>false</code>, then the origin of
6835 an instance of&#160;<em><strong>F</strong></em> is unknown.</p>
6836 </div></div></td>
6837 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6838 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td>
6839 </tr>
6840 <tr>
6841 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>offset</code></p></td>
6842 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#clock-offset">Clock offset</a></p></td>
6843 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6844 <p>Offset of an instance of&#160;<em><strong>F</strong></em> relative to its origin.</p>
6845 </div>
6846 <div class="paragraph">
6847 <p>Let:</p>
6848 </div>
6849 <div class="olist arabic">
6850 <ol class="arabic">
6851 <li>
6852 <p><em><strong>H</strong></em> be the value of the <code>frequency</code> property of&#160;<em><strong>F</strong></em>.</p>
6853 </li>
6854 <li>
6855 <p><em><strong>O</strong></em> be the value of this property.</p>
6856 </li>
6857 <li>
6858 <p><em><strong>S</strong></em> be the value of the <code>seconds</code> property of&#160;<em><strong>O</strong></em>.</p>
6859 </li>
6860 <li>
6861 <p><em><strong>C</strong></em> be the value of the <code>cycles</code> property of&#160;<em><strong>O</strong></em>.</p>
6862 </li>
6863 </ol>
6864 </div>
6865 <div class="paragraph">
6866 <p>Then the effective offset of an instance of&#160;<em><strong>F</strong></em>, in clock
6867 cycles,
6868 is&#160;<em><strong>S</strong></em>&#160;Ã—&#160;<em><strong>H</strong></em>&#160;+&#160;<em><strong>C</strong></em>.</p>
6869 </div></div></td>
6870 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6871 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{"seconds":&#160;0, "cycles":&#160;0}</code></p></td>
6872 </tr>
6873 <tr>
6874 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>precision</code></p></td>
6875 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
6876 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6877 <p>Precision of an instance of&#160;<em><strong>F</strong></em> (clock cycles).</p>
6878 </div>
6879 <div class="paragraph">
6880 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
6881 </div>
6882 <div class="paragraph">
6883 <p>Let&#160;<em><strong>P</strong></em> be the value of this property and&#160;<em><strong>V</strong></em>
6884 the value of an instance of&#160;<em><strong>F</strong></em>: the range of possible
6885 values of the instance
6886 is&#160;[<em><strong>V</strong></em>&#160;âˆ’&#160;<em><strong>P</strong></em>,&#160;<em><strong>V</strong></em>&#160;+&#160;<em><strong>P</strong></em>].</p>
6887 </div></div></td>
6888 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6889 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td>
6890 </tr>
6891 <tr>
6892 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
6893 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
6894 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6895 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
6896 </div></div></td>
6897 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6898 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6899 </tr>
6900 <tr>
6901 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
6902 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
6903 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
6904 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
6905 </div>
6906 <div class="paragraph">
6907 <p>Any extension which exists under this property <em>MUST</em> also be declared
6908 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
6909 </div></div></td>
6910 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
6911 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
6912 </tr>
6913 </tbody>
6914 </table>
6915 <div class="paragraph">
6916 <p>Within a metadata stream, two given clock class fragments <em>MUST&#160;NOT</em>:</p>
6917 </div>
6918 <div class="ulist">
6919 <ul>
6920 <li>
6921 <p>Share the same <code>name</code> property value.</p>
6922 </li>
6923 <li>
6924 <p>Share the same <code>uuid</code> property value.</p>
6925 </li>
6926 </ul>
6927 </div>
6928 <div class="exampleblock">
6929 <div class="title">Example 70. Minimal clock class fragment with 1-GHz instances.</div>
6930 <div class="content">
6931 <div class="listingblock">
6932 <div class="content">
6933 <pre class="highlight"><code class="language-json" data-lang="json">{
6934   "type": "clock-class",
6935   "name": "my clock class",
6936   "frequency": 1000000000
6937 }</code></pre>
6938 </div>
6939 </div>
6940 </div>
6941 </div>
6942 <div class="exampleblock">
6943 <div class="title">Example 71. Clock class fragment with a UUID property.</div>
6944 <div class="content">
6945 <div class="listingblock">
6946 <div class="content">
6947 <pre class="highlight"><code class="language-json" data-lang="json">{
6948   "type": "clock-class",
6949   "name": "my clock class",
6950   "frequency": 1000000000,
6951   "uuid": [
6952     116, 210, 0, 140, 239, 255, 77, 3,
6953     129, 99, 233, 226, 134, 106, 207, 32
6954   ]
6955 }</code></pre>
6956 </div>
6957 </div>
6958 </div>
6959 </div>
6960 <div class="exampleblock">
6961 <div class="title">Example 72. Clock class fragment with instances having a specific offset.</div>
6962 <div class="content">
6963 <div class="listingblock">
6964 <div class="content">
6965 <pre class="highlight"><code class="language-json" data-lang="json">{
6966   "type": "clock-class",
6967   "name": "my clock class",
6968   "frequency": 1000000000,
6969   "offset": {
6970     "seconds": 1605112699,
6971     "cycles": 2878388
6972   }
6973 }</code></pre>
6974 </div>
6975 </div>
6976 </div>
6977 </div>
6978 <div class="exampleblock">
6979 <div class="title">Example 73. Clock class fragment with instances having a specific precision.</div>
6980 <div class="content">
6981 <div class="listingblock">
6982 <div class="content">
6983 <pre class="highlight"><code class="language-json" data-lang="json">{
6984   "type": "clock-class",
6985   "name": "my clock class",
6986   "frequency": 8000000,
6987   "precision": 100
6988 }</code></pre>
6989 </div>
6990 </div>
6991 </div>
6992 </div>
6993 <div class="exampleblock">
6994 <div class="title">Example 74. Clock class fragment with instances having an origin which isn&#8217;t the Unix epoch.</div>
6995 <div class="content">
6996 <div class="listingblock">
6997 <div class="content">
6998 <pre class="highlight"><code class="language-json" data-lang="json">{
6999   "type": "clock-class",
7000   "name": "my clock class",
7001   "frequency": 1000000000,
7002   "origin-is-unix-epoch": false
7003 }</code></pre>
7004 </div>
7005 </div>
7006 </div>
7007 </div>
7008 <div class="exampleblock">
7009 <div class="title">Example 75. Clock class fragment with <a href="#user-attrs">user attributes</a>.</div>
7010 <div class="content">
7011 <div class="listingblock">
7012 <div class="content">
7013 <pre class="highlight"><code class="language-json" data-lang="json">{
7014   "type": "clock-class",
7015   "name": "my clock class",
7016   "frequency": 16000000,
7017   "user-attributes": {
7018     "my.tracer": {
7019       "sys-name": "SOC23",
7020       "bus": {
7021         "name": "LMB5",
7022         "index": 5
7023       },
7024       "propagation-delay-ps": 177
7025     }
7026   }
7027 }</code></pre>
7028 </div>
7029 </div>
7030 </div>
7031 </div>
7032 <div class="sect3">
7033 <h4 id="clock-offset">5.7.1. Clock offset</h4>
7034 <div class="paragraph">
7035 <p>A <em>clock offset</em> contains the offset of the instances of a
7036 <a href="#cc-frag">clock class</a> relative to their origin.</p>
7037 </div>
7038 <div class="paragraph">
7039 <p>A clock offset is a JSON object.</p>
7040 </div>
7041 <table class="tableblock frame-all grid-all fit-content">
7042 <caption class="title">Table 32. Properties of a clock offset contained in a clock class fragment <em><strong>F</strong></em>.</caption>
7043 <colgroup>
7044 <col>
7045 <col>
7046 <col>
7047 <col>
7048 <col>
7049 </colgroup>
7050 <thead>
7051 <tr>
7052 <th class="tableblock halign-left valign-top">Name</th>
7053 <th class="tableblock halign-left valign-top">Type</th>
7054 <th class="tableblock halign-left valign-top">Description</th>
7055 <th class="tableblock halign-left valign-top">Required?</th>
7056 <th class="tableblock halign-left valign-top">Default</th>
7057 </tr>
7058 </thead>
7059 <tbody>
7060 <tr>
7061 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>seconds</code></p></td>
7062 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
7063 <td class="tableblock halign-left valign-top"><p class="tableblock">Offset, in seconds, of an instance of&#160;<em><strong>F</strong></em> relative to its
7064 origin.</p></td>
7065 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7066 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td>
7067 </tr>
7068 <tr>
7069 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>cycles</code></p></td>
7070 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
7071 <td class="tableblock halign-left valign-top"><p class="tableblock">Offset, in cycles, of an instance of&#160;<em><strong>F</strong></em> relative to its
7072 origin.</p>
7073 <p class="tableblock">The value of this property <em>MUST</em> be greater than or equal to zero.</p>
7074 <p class="tableblock">The value of this property <em>MUST</em> be less than the value of the
7075 <code>frequency</code> property of&#160;<em><strong>F</strong></em>.</p></td>
7076 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7077 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td>
7078 </tr>
7079 </tbody>
7080 </table>
7081 <div class="exampleblock">
7082 <div class="title">Example 76. Minimal clock offset.</div>
7083 <div class="content">
7084 <div class="listingblock">
7085 <div class="content">
7086 <pre class="highlight"><code class="language-json" data-lang="json">{}</code></pre>
7087 </div>
7088 </div>
7089 </div>
7090 </div>
7091 <div class="exampleblock">
7092 <div class="title">Example 77. Clock offset with seconds and cycles.</div>
7093 <div class="content">
7094 <div class="listingblock">
7095 <div class="content">
7096 <pre class="highlight"><code class="language-json" data-lang="json">{
7097   "seconds": 1605112699,
7098   "cycles": 2878388
7099 }</code></pre>
7100 </div>
7101 </div>
7102 </div>
7103 </div>
7104 <div class="exampleblock">
7105 <div class="title">Example 78. Clock offset with seconds only.</div>
7106 <div class="content">
7107 <div class="listingblock">
7108 <div class="content">
7109 <pre class="highlight"><code class="language-json" data-lang="json">{
7110   "seconds": 1605111293
7111 }</code></pre>
7112 </div>
7113 </div>
7114 </div>
7115 </div>
7116 <div class="exampleblock">
7117 <div class="title">Example 79. Negative clock offset.</div>
7118 <div class="content">
7119 <div class="paragraph">
7120 <p>This example shows that a clock offset <em>MAY</em> be negative, that is,
7121 <em>before</em> the origin of the clock.</p>
7122 </div>
7123 <div class="listingblock">
7124 <div class="content">
7125 <pre class="highlight"><code class="language-json" data-lang="json">{
7126   "seconds": -18003,
7127   "cycles": 11928547
7128 }</code></pre>
7129 </div>
7130 </div>
7131 </div>
7132 </div>
7133 </div>
7134 </div>
7135 <div class="sect2">
7136 <h3 id="dsc-frag">5.8. Data stream class fragment</h3>
7137 <div class="paragraph">
7138 <p>A <em>data stream class</em> describes <a href="#ds"><em>data streams</em></a>.</p>
7139 </div>
7140 <div class="paragraph">
7141 <p>Within a metadata stream, a data stream class fragment <em><strong>F</strong></em> <em>MUST</em>
7142 occur before any <a href="#erc-frag">event record class fragment</a> of
7143 which&#160;<em><strong>F</strong></em> is the parent.</p>
7144 </div>
7145 <table class="tableblock frame-all grid-all fit-content">
7146 <caption class="title">Table 33. Properties of a data stream class fragment <em><strong>F</strong></em>.</caption>
7147 <colgroup>
7148 <col>
7149 <col>
7150 <col>
7151 <col>
7152 <col>
7153 </colgroup>
7154 <thead>
7155 <tr>
7156 <th class="tableblock halign-left valign-top">Name</th>
7157 <th class="tableblock halign-left valign-top">Type</th>
7158 <th class="tableblock halign-left valign-top">Description</th>
7159 <th class="tableblock halign-left valign-top">Required?</th>
7160 <th class="tableblock halign-left valign-top">Default</th>
7161 </tr>
7162 </thead>
7163 <tbody>
7164 <tr>
7165 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
7166 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7167 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7168 <p>Type of&#160;<em><strong>F</strong></em>.</p>
7169 </div>
7170 <div class="paragraph">
7171 <p>The value of this property <em>MUST</em> be <code>"data-stream-class"</code>.</p>
7172 </div></div></td>
7173 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
7174 <td class="tableblock halign-left valign-top"></td>
7175 </tr>
7176 <tr>
7177 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>id</code></p></td>
7178 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
7179 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7180 <p>Numeric ID of&#160;<em><strong>F</strong></em>.</p>
7181 </div>
7182 <div class="paragraph">
7183 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
7184 </div></div></td>
7185 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7186 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td>
7187 </tr>
7188 <tr>
7189 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td>
7190 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7191 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7192 <p>Name of&#160;<em><strong>F</strong></em>.</p>
7193 </div>
7194 <div class="paragraph">
7195 <p>The purpose of this property, combined with the <code>namespace</code> property, is
7196 to uniquely identify a data stream class amongst many
7197 <a href="#producer-def">producers</a>.</p>
7198 </div></div></td>
7199 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7200 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;is unnamed</p></td>
7201 </tr>
7202 <tr>
7203 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>namespace</code></p></td>
7204 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7205 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7206 <p><a href="#ns-def">Namespace</a> of&#160;<em><strong>F</strong></em>.</p>
7207 </div>
7208 <div class="paragraph">
7209 <p>The purpose of this property, combined with the <code>name</code> property, is to
7210 uniquely identify a data stream class amongst many
7211 <a href="#producer-def">producers</a>.</p>
7212 </div></div></td>
7213 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7214 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no namespace</p></td>
7215 </tr>
7216 <tr>
7217 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>default-clock-class-name</code></p></td>
7218 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7219 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7220 <p>Name of the <a href="#cc-frag">class</a> of the <a href="#def-clk">default clock</a> of an
7221 instance of&#160;<em><strong>F</strong></em>.</p>
7222 </div>
7223 <div class="paragraph">
7224 <p>Within the metadata stream containing&#160;<em><strong>F</strong></em>, the <a href="#cc-frag">clock
7225 class fragment</a> which has the value of this property as its <code>name</code>
7226 property <em>MUST</em> occur before&#160;<em><strong>F</strong></em>.</p>
7227 </div></div></td>
7228 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7229 <td class="tableblock halign-left valign-top"><p class="tableblock">An instance of&#160;<em><strong>F</strong></em> has no default clock</p></td>
7230 </tr>
7231 <tr>
7232 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-context-field-class</code></p></td>
7233 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#struct-fc">Structure field class</a></p></td>
7234 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7235 <p>Class of all the <a href="#pkt-ctx">packet context fields</a> of an instance
7236 of&#160;<em><strong>F</strong></em>.</p>
7237 </div></div></td>
7238 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7239 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no packet context field class</p></td>
7240 </tr>
7241 <tr>
7242 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>event-record-header-field-class</code></p></td>
7243 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#struct-fc">Structure field class</a></p></td>
7244 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7245 <p>Class of all the <a href="#er-header">event record header fields</a> of an
7246 instance of&#160;<em><strong>F</strong></em>.</p>
7247 </div>
7248 <div class="paragraph">
7249 <p>Any field class as the value of this property <em>MUST</em> satisfy <em>at least
7250 one of</em>:</p>
7251 </div>
7252 <div class="ulist">
7253 <ul>
7254 <li>
7255 <p>Have at least one valid <a href="#er-header-roles">role</a>.</p>
7256 </li>
7257 <li>
7258 <p>Be a <a href="#struct-fc">structure field class</a>.</p>
7259 </li>
7260 <li>
7261 <p>Be an <a href="#opt-fc">optional field class</a>.</p>
7262 </li>
7263 <li>
7264 <p>Be a <a href="#var-fc">variant field class</a>.</p>
7265 </li>
7266 <li>
7267 <p>Be the class of a field which is the selector field of an optional or
7268 variant field.</p>
7269 </li>
7270 </ul>
7271 </div></div></td>
7272 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7273 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no event record header field class</p></td>
7274 </tr>
7275 <tr>
7276 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>event-record-common-context-field-class</code></p></td>
7277 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#struct-fc">Structure field class</a></p></td>
7278 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7279 <p>Class of all the <a href="#er-common-ctx">event record common context fields</a>
7280 of an instance of&#160;<em><strong>F</strong></em>.</p>
7281 </div></div></td>
7282 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7283 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no event record common context field class</p></td>
7284 </tr>
7285 <tr>
7286 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
7287 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
7288 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7289 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
7290 </div></div></td>
7291 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7292 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
7293 </tr>
7294 <tr>
7295 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
7296 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
7297 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7298 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
7299 </div>
7300 <div class="paragraph">
7301 <p>Any extension which exists under this property <em>MUST</em> also be declared
7302 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
7303 </div></div></td>
7304 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7305 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
7306 </tr>
7307 </tbody>
7308 </table>
7309 <div class="paragraph">
7310 <p>Within a metadata stream, two given data stream class fragments
7311 <em>MUST&#160;NOT</em> share the same <code>id</code> property value.</p>
7312 </div>
7313 <div class="sect3">
7314 <h4 id="_roles_2">5.8.1. Roles</h4>
7315 <div class="paragraph">
7316 <p><a id="pkt-ctx-roles"></a> If the <code>packet-context-field-class</code> property of a data
7317 stream class fragment exists, then the <a href="#fc">field classes</a> of its
7318 <a href="#struct-member-cls">member classes</a> <em>MAY</em> have the following
7319 <a href="#roles">roles</a>:</p>
7320 </div>
7321 <table class="tableblock frame-all grid-all fit-content">
7322 <caption class="title">Table 34. Roles of field classes of the member classes of a packet context field class.</caption>
7323 <colgroup>
7324 <col>
7325 <col>
7326 <col>
7327 <col>
7328 </colgroup>
7329 <thead>
7330 <tr>
7331 <th class="tableblock halign-left valign-top">Name</th>
7332 <th class="tableblock halign-left valign-top">Description</th>
7333 <th class="tableblock halign-left valign-top">Field class (<em><strong>F</strong></em>) constraints</th>
7334 <th class="tableblock halign-left valign-top">Other constraints</th>
7335 </tr>
7336 </thead>
7337 <tbody>
7338 <tr>
7339 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-total-size</code></p></td>
7340 <td class="tableblock halign-left valign-top"><p class="tableblock">Total size (bits) of the <a href="#pkt">packet</a>.</p>
7341 <p class="tableblock">This size includes any padding after the packet contents.</p></td>
7342 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7343 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7344 </div></div></td>
7345 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7346 <p>The value of an instance of&#160;<em><strong>F</strong></em> <em>MUST</em> be greater than or
7347 equal to the value of an instance of a field class having the
7348 <code>packet-content-size</code> role, if any, within the <em>same</em> packet context
7349 field.</p>
7350 </div></div></td>
7351 </tr>
7352 <tr>
7353 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-content-size</code></p></td>
7354 <td class="tableblock halign-left valign-top"><p class="tableblock">Content size (bits) of the packet.</p></td>
7355 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7356 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7357 </div></div></td>
7358 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7359 <p>The value of an instance of&#160;<em><strong>F</strong></em> <em>MUST</em> be less than or equal
7360 to the value of an instance of a field class having the
7361 <code>packet-total-size</code> role, if any, within the <em>same</em> packet context
7362 field.</p>
7363 </div></div></td>
7364 </tr>
7365 <tr>
7366 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-beginning-default-clock-timestamp</code></p></td>
7367 <td class="tableblock halign-left valign-top"><p class="tableblock">Timestamp of the <a href="#def-clk">default clock</a> of the <a href="#ds">data stream</a>
7368 when the packet begins.</p></td>
7369 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7370 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7371 </div></div></td>
7372 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7373 <p>The timestamps of all the <a href="#er">event records</a> of the packet <em>MUST</em> be
7374 greater than or equal to the value of an instance of&#160;<em><strong>F</strong></em>.</p>
7375 </div>
7376 <div class="paragraph">
7377 <p>The value of an instance of&#160;<em><strong>F</strong></em> <em>MUST</em> be less than or equal to
7378 the value of an instance of a field class having the
7379 <code>packet-end-default-clock-timestamp</code> role, if any, within the <em>same</em>
7380 packet context field.</p>
7381 </div></div></td>
7382 </tr>
7383 <tr>
7384 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>packet-end-default-clock-timestamp</code></p></td>
7385 <td class="tableblock halign-left valign-top"><p class="tableblock">Timestamp of the default clock of the data stream when the packet ends.</p></td>
7386 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7387 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7388 </div></div></td>
7389 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7390 <p>The timestamps of all the <a href="#er">event records</a> of the packet <em>MUST</em> be
7391 less than or equal to the value of an instance of&#160;<em><strong>F</strong></em>.</p>
7392 </div>
7393 <div class="paragraph">
7394 <p>The value of an instance of&#160;<em><strong>F</strong></em> <em>MUST</em> be greater than or equal
7395 to the value of an instance of a field class having the
7396 <code>packet-beginning-default-clock-timestamp</code> role, if any, within the
7397 <em>same</em> packet context field.</p>
7398 </div></div></td>
7399 </tr>
7400 <tr>
7401 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>discarded-event-record-counter-snapshot</code></p></td>
7402 <td class="tableblock halign-left valign-top"><p class="tableblock">Snapshot of the <a href="#disc-er-counter">discarded event record counter</a> of
7403 the data stream when the packet ends.</p></td>
7404 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7405 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7406 </div></div></td>
7407 <td class="tableblock halign-left valign-top"><div class="content"></div></td>
7408 </tr>
7409 <tr>
7410 <td class="tableblock halign-left valign-top"><p class="tableblock"><a id="pkt-seq-num-role"></a> <code>packet-sequence-number</code></p></td>
7411 <td class="tableblock halign-left valign-top"><p class="tableblock">Sequence number of the packet within its data stream.</p></td>
7412 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7413 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7414 </div></div></td>
7415 <td class="tableblock halign-left valign-top"><div class="content"></div></td>
7416 </tr>
7417 </tbody>
7418 </table>
7419 <div class="paragraph">
7420 <p><a id="er-header-roles"></a> If the <code>event-record-header-field-class</code> property of
7421 a data stream class fragment exists, then the <a href="#fc">field classes</a> of
7422 its <a href="#struct-member-cls">member classes</a> <em>MAY</em> have the following
7423 <a href="#roles">roles</a>:</p>
7424 </div>
7425 <table class="tableblock frame-all grid-all fit-content">
7426 <caption class="title">Table 35. Roles of field classes of the member classes of an event record header field class.</caption>
7427 <colgroup>
7428 <col>
7429 <col>
7430 <col>
7431 </colgroup>
7432 <thead>
7433 <tr>
7434 <th class="tableblock halign-left valign-top">Name</th>
7435 <th class="tableblock halign-left valign-top">Description</th>
7436 <th class="tableblock halign-left valign-top">Field class (<em><strong>F</strong></em>) constraints</th>
7437 </tr>
7438 </thead>
7439 <tbody>
7440 <tr>
7441 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>event-record-class-id</code></p></td>
7442 <td class="tableblock halign-left valign-top"><p class="tableblock">Event record class ID.</p>
7443 <p class="tableblock">The purpose of an event record class ID field is to set the current ID
7444 of the class of the event record within its parent <a href="#dsc-frag">data
7445 stream class</a>.</p></td>
7446 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7447 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7448 </div></div></td>
7449 </tr>
7450 <tr>
7451 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>default-clock-timestamp</code></p></td>
7452 <td class="tableblock halign-left valign-top"><p class="tableblock">Current timestamp of the <a href="#def-clk">default clock</a> of the data stream
7453 when the event record occurs.</p></td>
7454 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7455 <p><a href="#fl-int-fc">Fixed-length unsigned integer field class</a> or <a href="#vl-int-fc">variable-length unsigned integer field class</a>.</p>
7456 </div></div></td>
7457 </tr>
7458 </tbody>
7459 </table>
7460 </div>
7461 </div>
7462 <div class="sect2">
7463 <h3 id="erc-frag">5.9. Event record class fragment</h3>
7464 <div class="paragraph">
7465 <p>An <em>event record class</em> describes <a href="#er"><em>event records</em></a>.</p>
7466 </div>
7467 <div class="paragraph">
7468 <p>The <a href="#dsc-frag">data stream class fragment</a> of which the value of the
7469 <code>id</code> property matches the value of the <code>data-stream-class-id</code> property
7470 of an event record class fragment&#160;<em><strong>F</strong></em> is considered the
7471 <em>parent</em> of&#160;<em><strong>F</strong></em>.</p>
7472 </div>
7473 <table class="tableblock frame-all grid-all fit-content">
7474 <caption class="title">Table 36. Properties of an event record class fragment&#160;<em><strong>F</strong></em> having the data stream class&#160;<em><strong>P</strong></em> as its parent.</caption>
7475 <colgroup>
7476 <col>
7477 <col>
7478 <col>
7479 <col>
7480 <col>
7481 </colgroup>
7482 <thead>
7483 <tr>
7484 <th class="tableblock halign-left valign-top">Name</th>
7485 <th class="tableblock halign-left valign-top">Type</th>
7486 <th class="tableblock halign-left valign-top">Description</th>
7487 <th class="tableblock halign-left valign-top">Required?</th>
7488 <th class="tableblock halign-left valign-top">Default</th>
7489 </tr>
7490 </thead>
7491 <tbody>
7492 <tr>
7493 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>type</code></p></td>
7494 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7495 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7496 <p>Type of&#160;<em><strong>F</strong></em>.</p>
7497 </div>
7498 <div class="paragraph">
7499 <p>The value of this property <em>MUST</em> be <code>"event-record-class"</code>.</p>
7500 </div></div></td>
7501 <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td>
7502 <td class="tableblock halign-left valign-top"></td>
7503 </tr>
7504 <tr>
7505 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>id</code></p></td>
7506 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
7507 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7508 <p>Numeric ID of&#160;<em><strong>F</strong></em> within&#160;<em><strong>P</strong></em>.</p>
7509 </div>
7510 <div class="paragraph">
7511 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
7512 </div></div></td>
7513 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7514 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td>
7515 </tr>
7516 <tr>
7517 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>data-stream-class-id</code></p></td>
7518 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON integer</p></td>
7519 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7520 <p>Numeric ID of&#160;<em><strong>P</strong></em>.</p>
7521 </div>
7522 <div class="paragraph">
7523 <p>The value of this property <em>MUST</em> be greater than or equal to zero.</p>
7524 </div>
7525 <div class="paragraph">
7526 <p>Within the metadata stream,&#160;<em><strong>P</strong></em> <em>MUST</em> occur
7527 before&#160;<em><strong>F</strong></em>.</p>
7528 </div></div></td>
7529 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7530 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0</code></p></td>
7531 </tr>
7532 <tr>
7533 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name</code></p></td>
7534 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7535 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7536 <p>Name of&#160;<em><strong>F</strong></em>.</p>
7537 </div>
7538 <div class="paragraph">
7539 <p>The purpose of this property, combined with the <code>namespace</code> property, is
7540 to uniquely identify an event record class amongst many
7541 <a href="#producer-def">producers</a>.</p>
7542 </div></div></td>
7543 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7544 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;is unnamed</p></td>
7545 </tr>
7546 <tr>
7547 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>namespace</code></p></td>
7548 <td class="tableblock halign-left valign-top"><p class="tableblock">JSON string</p></td>
7549 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7550 <p><a href="#ns-def">Namespace</a> of&#160;<em><strong>F</strong></em>.</p>
7551 </div>
7552 <div class="paragraph">
7553 <p>The purpose of this property, combined with the <code>name</code> property, is to
7554 uniquely identify an event record class amongst many
7555 <a href="#producer-def">producers</a>.</p>
7556 </div></div></td>
7557 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7558 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no namespace</p></td>
7559 </tr>
7560 <tr>
7561 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>specific-context-field-class</code></p></td>
7562 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#struct-fc">Structure field class</a></p></td>
7563 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7564 <p>Class of the <a href="#er-spec-ctx">event record specific context field</a>
7565 of an instance of&#160;<em><strong>F</strong></em>.</p>
7566 </div></div></td>
7567 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7568 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no event record specific context field class</p></td>
7569 </tr>
7570 <tr>
7571 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>payload-field-class</code></p></td>
7572 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#struct-fc">Structure field class</a></p></td>
7573 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7574 <p>Class of the <a href="#er-payload">event record payload field</a> of an
7575 instance of&#160;<em><strong>F</strong></em>.</p>
7576 </div></div></td>
7577 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7578 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>F</strong></em>&#160;has no event record payload field class</p></td>
7579 </tr>
7580 <tr>
7581 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>user-attributes</code></p></td>
7582 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#user-attrs">User attributes</a></p></td>
7583 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7584 <p>User attributes of&#160;<em><strong>F</strong></em>.</p>
7585 </div></div></td>
7586 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7587 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
7588 </tr>
7589 <tr>
7590 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>extensions</code></p></td>
7591 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#ext">Extensions</a></p></td>
7592 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
7593 <p>Extensions of&#160;<em><strong>F</strong></em>.</p>
7594 </div>
7595 <div class="paragraph">
7596 <p>Any extension which exists under this property <em>MUST</em> also be declared
7597 in the <a href="#preamble-frag">preamble fragment</a> of the metadata stream.</p>
7598 </div></div></td>
7599 <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
7600 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{}</code></p></td>
7601 </tr>
7602 </tbody>
7603 </table>
7604 <div class="paragraph">
7605 <p>Within a metadata stream, two given event record class fragments
7606 <em>MUST&#160;NOT</em> share the same <code>id</code> property value <em>and</em> the same
7607 <code>data-stream-class-id</code> property value.</p>
7608 </div>
7609 </div>
7610 </div>
7611 </div>
7612 <div class="sect1">
7613 <h2 id="ds-dec">6. Data stream decoding procedure</h2>
7614 <div class="sectionbody">
7615 <div class="paragraph">
7616 <p>This section shows how to, procedurally, <em>decode</em> a CTF&#160;2 <a href="#ds">data
7617 stream</a>.</p>
7618 </div>
7619 <div class="paragraph">
7620 <p>Decoding a data stream is the responsibility of a
7621 <a href="#consumer-def">consumer</a>.</p>
7622 </div>
7623 <div class="paragraph">
7624 <p>This document doesn&#8217;t specify how to encode a data stream, as this
7625 procedure implies much more freedom than decoding. One can deduce how to
7626 encode a data stream from the decoding procedure.</p>
7627 </div>
7628 <div class="paragraph">
7629 <p>A consumer needs to keep a <em>data stream decoding state</em> while decoding a
7630 data stream. A data stream decoding state comprises the following
7631 <em>variable</em>:</p>
7632 </div>
7633 <table class="tableblock frame-all grid-all fit-content">
7634 <caption class="title">Table 37. Variable needed to decode a data stream&#160;<em><strong>S</strong></em>.</caption>
7635 <colgroup>
7636 <col>
7637 <col>
7638 <col>
7639 <col>
7640 </colgroup>
7641 <thead>
7642 <tr>
7643 <th class="tableblock halign-left valign-top">Name</th>
7644 <th class="tableblock halign-left valign-top">Type</th>
7645 <th class="tableblock halign-left valign-top">Description</th>
7646 <th class="tableblock halign-left valign-top">Initial value</th>
7647 </tr>
7648 </thead>
7649 <tbody>
7650 <tr>
7651 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>O</strong></em></p></td>
7652 <td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned integer</p></td>
7653 <td class="tableblock halign-left valign-top"><p class="tableblock">Current decoding offset/position (bits) from the beginning
7654 of&#160;<em><strong>S</strong></em>.</p></td>
7655 <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
7656 </tr>
7657 </tbody>
7658 </table>
7659 <div class="paragraph">
7660 <p>To decode a data stream <em><strong>S</strong></em>:</p>
7661 </div>
7662 <div class="ulist">
7663 <ul>
7664 <li>
7665 <p>While there&#8217;s remaining data in <em><strong>S</strong></em>:</p>
7666 <div class="ulist">
7667 <ul>
7668 <li>
7669 <p><a href="#pkt-dec">Decode one packet</a>.</p>
7670 </li>
7671 </ul>
7672 </div>
7673 </li>
7674 </ul>
7675 </div>
7676 <div class="sect2">
7677 <h3 id="pkt-dec">6.1. Packet decoding procedure</h3>
7678 <div class="paragraph">
7679 <p>A <a href="#consumer-def">consumer</a> needs to keep a <em>packet decoding state</em>
7680 while decoding a <a href="#pkt">packet</a>. A packet decoding state comprises the
7681 following <em>variables</em>:</p>
7682 </div>
7683 <table class="tableblock frame-all grid-all fit-content">
7684 <caption class="title">Table 38. Variables needed to decode a packet&#160;<em><strong>P</strong></em> within a data stream&#160;<em><strong>S</strong></em>.</caption>
7685 <colgroup>
7686 <col>
7687 <col>
7688 <col>
7689 <col>
7690 </colgroup>
7691 <thead>
7692 <tr>
7693 <th class="tableblock halign-left valign-top">Name</th>
7694 <th class="tableblock halign-left valign-top">Type</th>
7695 <th class="tableblock halign-left valign-top">Description</th>
7696 <th class="tableblock halign-left valign-top">Initial value</th>
7697 </tr>
7698 </thead>
7699 <tbody>
7700 <tr>
7701 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>DEF_CLK_VAL</strong></em></p></td>
7702 <td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned integer</p></td>
7703 <td class="tableblock halign-left valign-top"><p class="tableblock">Current value (clock cycles) of the <a href="#def-clk">default
7704 clock</a> of&#160;<em><strong>S</strong></em>, if any.</p></td>
7705 <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
7706 </tr>
7707 <tr>
7708 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>DSC_ID</strong></em></p></td>
7709 <td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned integer</p></td>
7710 <td class="tableblock halign-left valign-top"><p class="tableblock">Current ID of the <a href="#dsc-frag">class</a> of&#160;<em><strong>S</strong></em>.</p></td>
7711 <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
7712 </tr>
7713 <tr>
7714 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>DSC</strong></em></p></td>
7715 <td class="tableblock halign-left valign-top"><p class="tableblock">Optional <a href="#dsc-frag">data stream class</a></p></td>
7716 <td class="tableblock halign-left valign-top"><p class="tableblock">Current class of&#160;<em><strong>S</strong></em>.</p></td>
7717 <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
7718 </tr>
7719 <tr>
7720 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>DS_ID</strong></em></p></td>
7721 <td class="tableblock halign-left valign-top"><p class="tableblock">Optional unsigned integer</p></td>
7722 <td class="tableblock halign-left valign-top"><p class="tableblock">Current ID of&#160;<em><strong>S</strong></em>.</p></td>
7723 <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
7724 </tr>
7725 <tr>
7726 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>PKT_TOTAL_SZ</strong></em></p></td>
7727 <td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned integer</p></td>
7728 <td class="tableblock halign-left valign-top"><p class="tableblock">Current total size (bits) of&#160;<em><strong>P</strong></em>.</p></td>
7729 <td class="tableblock halign-left valign-top"><p class="tableblock">âˆž</p></td>
7730 </tr>
7731 <tr>
7732 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>PKT_CONTENT_SZ</strong></em></p></td>
7733 <td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned integer</p></td>
7734 <td class="tableblock halign-left valign-top"><p class="tableblock">Current content size (bits) of&#160;<em><strong>P</strong></em>.</p></td>
7735 <td class="tableblock halign-left valign-top"><p class="tableblock">âˆž</p></td>
7736 </tr>
7737 <tr>
7738 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>LAST_BO</strong></em></p></td>
7739 <td class="tableblock halign-left valign-top"><p class="tableblock">Optional string</p></td>
7740 <td class="tableblock halign-left valign-top"><p class="tableblock">Byte order of the last <a href="#fl-ba-field-dec">decoded fixed-length bit array field</a>.</p></td>
7741 <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
7742 </tr>
7743 </tbody>
7744 </table>
7745 <div class="paragraph">
7746 <p>To decode a packet <em><strong>P</strong></em> within a data stream <em><strong>S</strong></em>:</p>
7747 </div>
7748 <div class="olist arabic">
7749 <ol class="arabic">
7750 <li>
7751 <p>Let <em><strong>PO</strong></em> be the current value of <em><strong>O</strong></em>.</p>
7752 <div class="paragraph">
7753 <p>While decoding the packet, <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em> is the current decoding
7754 offset/position (bits) from the beginning of&#160;<em><strong>P</strong></em>.</p>
7755 </div>
7756 </li>
7757 <li>
7758 <p>If the <code>packet-header-field-class</code> property of the <a href="#tc-frag">trace
7759 class fragment</a> of the metadata stream exists, then
7760 <a href="#struct-field-dec">decode</a> the <a href="#pkt-header">header field</a>
7761 of&#160;<em><strong>P</strong></em> using this property.</p>
7762 <div class="paragraph">
7763 <p>During the packet header field decoding procedure, after having decoded
7764 a field&#160;<em><strong>F</strong></em> having the class&#160;<em><strong>C</strong></em> with a <code>roles</code>
7765 property:</p>
7766 </div>
7767 <div class="ulist">
7768 <ul>
7769 <li>
7770 <p>If <em><strong>C</strong></em> has the role <code>packet-magic-number</code>, then validate that the
7771 unsigned integer value of&#160;<em><strong>F</strong></em> is 0xc1fc1fc1 (3254525889).</p>
7772 <div class="paragraph">
7773 <p>A <a href="#consumer-def">consumer</a> <em>SHOULD</em> report an invalid packet magic
7774 number as an error.</p>
7775 </div>
7776 </li>
7777 <li>
7778 <p>If <em><strong>C</strong></em> has the role <code>trace-type-uuid</code>, then validate that the
7779 value of&#160;<em><strong>F</strong></em> matches the <code>uuid</code> property of the trace
7780 class fragment.</p>
7781 <div class="paragraph">
7782 <p>A consumer <em>SHOULD</em> report a trace type UUID mismatch as an error.</p>
7783 </div>
7784 </li>
7785 <li>
7786 <p>If <em><strong>C</strong></em> has the role <code>data-stream-class-id</code>, then
7787 set&#160;<em><strong>DSC_ID</strong></em> to the unsigned integer value
7788 of&#160;<em><strong>F</strong></em>.</p>
7789 </li>
7790 <li>
7791 <p>If <em><strong>C</strong></em> has the role <code>data-stream-id</code>, then
7792 set&#160;<em><strong>DS_ID</strong></em> to the unsigned integer value
7793 of&#160;<em><strong>F</strong></em>.</p>
7794 </li>
7795 </ul>
7796 </div>
7797 <div class="paragraph">
7798 <p>After having decoded the whole packet header field,
7799 if&#160;<em><strong>DS_ID</strong></em> is set, then it&#8217;s the ID of&#160;<em><strong>S</strong></em> within
7800 its <a href="#dsc-frag">class</a>. In other words, two data streams <em>MAY</em> have the
7801 same ID if they are instances of different data stream classes.</p>
7802 </div>
7803 </li>
7804 <li>
7805 <p>Set <em><strong>DSC</strong></em> to the <a href="#dsc-frag">data stream class</a>
7806 having&#160;<em><strong>DSC_ID</strong></em> as the value of its <code>id</code> property.</p>
7807 <div class="paragraph">
7808 <p>If no data stream class has the ID&#160;<em><strong>DSC_ID</strong></em>, then report an
7809 error and abort the data stream decoding process.</p>
7810 </div>
7811 </li>
7812 <li>
7813 <p>If the <code>packet-context-field-class</code> property of&#160;<em><strong>DSC</strong></em>
7814 exists, then <a href="#struct-field-dec">decode</a> the <a href="#pkt-ctx">context field</a>
7815 of&#160;<em><strong>P</strong></em> using this property.</p>
7816 <div class="paragraph">
7817 <p>During the packet context field decoding procedure, after having decoded
7818 a field&#160;<em><strong>F</strong></em> having the class&#160;<em><strong>C</strong></em> with a <code>roles</code>
7819 property:</p>
7820 </div>
7821 <div class="ulist">
7822 <ul>
7823 <li>
7824 <p>If <em><strong>C</strong></em> has the role <code>packet-total-size</code>, then
7825 set&#160;<em><strong>PKT_TOTAL_SZ</strong></em> to the unsigned integer value
7826 of&#160;<em><strong>F</strong></em>.</p>
7827 </li>
7828 <li>
7829 <p>If <em><strong>C</strong></em> has the role <code>packet-content-size</code>, then
7830 set&#160;<em><strong>PKT_CONTENT_SZ</strong></em> to the unsigned integer value
7831 of&#160;<em><strong>F</strong></em>.</p>
7832 </li>
7833 <li>
7834 <p>If <em><strong>C</strong></em> has the role <code>packet-beginning-default-clock-timestamp</code>,
7835 then set&#160;<em><strong>DEF_CLK_VAL</strong></em> to the unsigned integer value
7836 of&#160;<em><strong>F</strong></em>.</p>
7837 </li>
7838 <li>
7839 <p>If <em><strong>C</strong></em> has the role <code>packet-end-default-clock-timestamp</code>, then
7840 the unsigned integer value of&#160;<em><strong>F</strong></em> is the value of the
7841 <a href="#def-clk">default clock</a> of&#160;<em><strong>S</strong></em> at the end of&#160;<em><strong>P</strong></em>.</p>
7842 </li>
7843 <li>
7844 <p>If <em><strong>C</strong></em> has the role <code>discarded-event-record-counter-snapshot</code>,
7845 then the unsigned integer value of&#160;<em><strong>F</strong></em> is a snapshot of the
7846 <a href="#disc-er-counter">discarded event record counter</a> of&#160;<em><strong>S</strong></em> at
7847 the end of&#160;<em><strong>P</strong></em>.</p>
7848 </li>
7849 <li>
7850 <p>If <em><strong>C</strong></em> has the role <code>packet-sequence-number</code>, then the unsigned
7851 integer value of&#160;<em><strong>F</strong></em> is the sequence number of&#160;<em><strong>P</strong></em>
7852 within&#160;<em><strong>S</strong></em>.</p>
7853 </li>
7854 </ul>
7855 </div>
7856 <div class="paragraph">
7857 <p>A <a href="#consumer-def">consumer</a> <em>SHOULD</em> report a beginning default clock
7858 timestamp greater than an end default clock timestamp as an error.</p>
7859 </div>
7860 </li>
7861 <li>
7862 <p>If <em><strong>PKT_TOTAL_SZ</strong></em> is&#160;âˆž and <em><strong>PKT_CONTENT_SZ</strong></em> is
7863 <em>not</em>&#160;âˆž, then set&#160;<em><strong>PKT_TOTAL_SZ</strong></em>
7864 to&#160;<em><strong>PKT_CONTENT_SZ</strong></em>.</p>
7865 </li>
7866 <li>
7867 <p>If <em><strong>PKT_CONTENT_SZ</strong></em> is&#160;âˆž and <em><strong>PKT_TOTAL_SZ</strong></em> is
7868 <em>not</em>&#160;âˆž, then set&#160;<em><strong>PKT_CONTENT_SZ</strong></em>
7869 to&#160;<em><strong>PKT_TOTAL_SZ</strong></em>.</p>
7870 </li>
7871 <li>
7872 <p>While <em><strong>O</strong></em>&#160;&lt;&#160;<em><strong>PO</strong></em>&#160;+&#160;<em><strong>PKT_CONTENT_SZ</strong></em>
7873 and there&#8217;s remaining data in&#160;<em><strong>S</strong></em>:</p>
7874 <div class="ulist">
7875 <ul>
7876 <li>
7877 <p><a href="#er-dec">Decode an event record</a>.</p>
7878 </li>
7879 </ul>
7880 </div>
7881 </li>
7882 <li>
7883 <p>If <em><strong>PKT_TOTAL_SZ</strong></em> and&#160;<em><strong>PKT_CONTENT_SZ</strong></em> both are
7884 <em>not</em>&#160;âˆž, then set&#160;<em><strong>O</strong></em> to
7885 <em><strong>PO</strong></em>&#160;+&#160;<em><strong>PKT_TOTAL_SZ</strong></em>, effectively
7886 skipping end-of-packet padding.</p>
7887 </li>
7888 </ol>
7889 </div>
7890 </div>
7891 <div class="sect2">
7892 <h3 id="er-dec">6.2. Event record decoding procedure</h3>
7893 <div class="paragraph">
7894 <p>A <a href="#consumer-def">consumer</a> needs to keep an <em>event record decoding
7895 state</em> while decoding an <a href="#er">event record</a>. An event record decoding
7896 state comprises the following <em>variables</em>:</p>
7897 </div>
7898 <table class="tableblock frame-all grid-all fit-content">
7899 <caption class="title">Table 39. Variables needed to decode an event record&#160;<em><strong>E</strong></em> within a data stream&#160;<em><strong>S</strong></em>.</caption>
7900 <colgroup>
7901 <col>
7902 <col>
7903 <col>
7904 <col>
7905 </colgroup>
7906 <thead>
7907 <tr>
7908 <th class="tableblock halign-left valign-top">Name</th>
7909 <th class="tableblock halign-left valign-top">Type</th>
7910 <th class="tableblock halign-left valign-top">Description</th>
7911 <th class="tableblock halign-left valign-top">Initial value</th>
7912 </tr>
7913 </thead>
7914 <tbody>
7915 <tr>
7916 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>ERC_ID</strong></em></p></td>
7917 <td class="tableblock halign-left valign-top"><p class="tableblock">Unsigned integer</p></td>
7918 <td class="tableblock halign-left valign-top"><p class="tableblock">Current ID of the <a href="#erc-frag">class</a> of&#160;<em><strong>E</strong></em> of which the
7919 parent is the <a href="#dsc-frag">class</a> of&#160;<em><strong>S</strong></em>.</p></td>
7920 <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
7921 </tr>
7922 <tr>
7923 <td class="tableblock halign-left valign-top"><p class="tableblock"><em><strong>ERC</strong></em></p></td>
7924 <td class="tableblock halign-left valign-top"><p class="tableblock">Optional <a href="#erc-frag">event record class</a></p></td>
7925 <td class="tableblock halign-left valign-top"><p class="tableblock">Current class of&#160;<em><strong>E</strong></em>.</p></td>
7926 <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td>
7927 </tr>
7928 </tbody>
7929 </table>
7930 <div class="paragraph">
7931 <p>To decode an event record <em><strong>E</strong></em> within a data stream <em><strong>S</strong></em>:</p>
7932 </div>
7933 <div class="olist arabic">
7934 <ol class="arabic">
7935 <li>
7936 <p>If the <code>event-record-header-field-class</code> property of&#160;<em><strong>DSC</strong></em>
7937 exists, then <a href="#struct-field-dec">decode</a> the <a href="#er-header">header
7938 field</a> of&#160;<em><strong>E</strong></em> using this property.</p>
7939 <div class="paragraph">
7940 <p>During the event record header field decoding procedure, after having
7941 decoded a field&#160;<em><strong>F</strong></em> having the class&#160;<em><strong>C</strong></em> with a
7942 <code>roles</code> property:</p>
7943 </div>
7944 <div class="ulist">
7945 <ul>
7946 <li>
7947 <p>If <em><strong>C</strong></em> has the role <code>event-record-class-id</code>, then
7948 set&#160;<em><strong>ERC_ID</strong></em> to the unsigned integer value
7949 of&#160;<em><strong>F</strong></em>.</p>
7950 </li>
7951 <li>
7952 <p>If <em><strong>C</strong></em> has the role <code>default-clock-timestamp</code>, then
7953 <a href="#clk-val-update">update&#160;<em><strong>DEF_CLK_VAL</strong></em></a> from&#160;<em><strong>F</strong></em>.</p>
7954 </li>
7955 </ul>
7956 </div>
7957 <div class="paragraph">
7958 <p>After having decoded the whole event record header field,
7959 <em><strong>DEF_CLK_VAL</strong></em> is the value of the <a href="#def-clk">default clock</a>
7960 of&#160;<em><strong>S</strong></em> when&#160;<em><strong>E</strong></em> occurs.</p>
7961 </div>
7962 </li>
7963 <li>
7964 <p>Set <em><strong>ERC</strong></em> to the <a href="#erc-frag">event record class</a> having:</p>
7965 <div class="ulist">
7966 <ul>
7967 <li>
7968 <p><em><strong>DSC_ID</strong></em> as the value of its <code>data-stream-class-id</code> property.</p>
7969 </li>
7970 <li>
7971 <p><em><strong>ERC_ID</strong></em> as the value of its <code>id</code> property.</p>
7972 </li>
7973 </ul>
7974 </div>
7975 <div class="paragraph">
7976 <p>If no event record class has the ID&#160;<em><strong>ERC_ID</strong></em> within a data
7977 stream class having the ID&#160;<em><strong>DSC_ID</strong></em>, then report an error and
7978 abort the data stream decoding process.</p>
7979 </div>
7980 </li>
7981 <li>
7982 <p>If the <code>event-record-common-context-field-class</code> property
7983 of&#160;<em><strong>DSC</strong></em> exists, then <a href="#struct-field-dec">decode</a> the
7984 <a href="#er-common-ctx">common context field</a> of&#160;<em><strong>E</strong></em> using this
7985 property.</p>
7986 </li>
7987 <li>
7988 <p>If the <code>specific-context-field-class</code> property of&#160;<em><strong>ERC</strong></em>
7989 exists, then <a href="#struct-field-dec">decode</a> the
7990 <a href="#er-spec-ctx">specific context field</a> of&#160;<em><strong>E</strong></em>
7991 using this property.</p>
7992 </li>
7993 <li>
7994 <p>If the <code>payload-field-class</code> property of&#160;<em><strong>ERC</strong></em> exists, then
7995 <a href="#struct-field-dec">decode</a> the <a href="#er-payload">payload field</a>
7996 of&#160;<em><strong>E</strong></em> using this property.</p>
7997 </li>
7998 </ol>
7999 </div>
8000 <div class="sect3">
8001 <h4 id="clk-val-update">6.2.1. Clock value update procedure</h4>
8002 <div class="paragraph">
8003 <p>To update <em><strong>DEF_CLK_VAL</strong></em> from an unsigned integer
8004 field&#160;<em><strong>F</strong></em> having the unsigned integer value&#160;<em><strong>V</strong></em> and
8005 the <a href="#fc">class</a>&#160;<em><strong>C</strong></em>:</p>
8006 </div>
8007 <div class="olist arabic">
8008 <ol class="arabic">
8009 <li>
8010 <p>Let <em><strong>L</strong></em> be an unsigned integer initialized to,
8011 depending on the <code>type</code> property of&#160;<em><strong>C</strong></em>:</p>
8012 <div class="openblock">
8013 <div class="content">
8014 <div class="dlist">
8015 <dl>
8016 <dt class="hdlist1"><a href="#fl-int-fc"><code>"fixed-length-unsigned-integer"</code></a></dt>
8017 <dt class="hdlist1"><a href="#fl-enum-fc"><code>"fixed-length-unsigned-enumeration"</code></a></dt>
8018 <dd>
8019 <p>The value of the <code>length</code> property of&#160;<em><strong>C</strong></em>.</p>
8020 </dd>
8021 <dt class="hdlist1"><a href="#vl-int-fc"><code>"variable-length-unsigned-integer"</code></a></dt>
8022 <dt class="hdlist1"><a href="#vl-enum-fc"><code>"variable-length-unsigned-enumeration"</code></a></dt>
8023 <dd>
8024 <p><em><strong>S</strong></em>&#160;Ã—7, where&#160;<em><strong>S</strong></em> is the number of
8025 <a href="#byte-def">bytes</a> which&#160;<em><strong>F</strong></em> occupies
8026 with the <a href="#ds">data stream</a>.</p>
8027 </dd>
8028 </dl>
8029 </div>
8030 </div>
8031 </div>
8032 </li>
8033 <li>
8034 <p>Let <em><strong>MASK</strong></em> be an unsigned integer initialized to
8035 2<sup><em><strong>L</strong></em></sup>&#160;âˆ’&#160;1.</p>
8036 </li>
8037 <li>
8038 <p>Let <em><strong>H</strong></em> be an unsigned integer initialized to
8039 <em><strong>DEF_CLK_VAL</strong></em>&#160;&amp;&#160;~<em><strong>MASK</strong></em>,
8040 where &#8220;&amp;&#8221; is the bitwise <em>AND</em> operator and
8041 &#8220;~&#8221; is the bitwise <em>NOT</em> operator.</p>
8042 </li>
8043 <li>
8044 <p>Let <em><strong>CUR</strong></em> be an unsigned integer initialized to
8045 <em><strong>DEF_CLK_VAL</strong></em>&#160;&amp;&#160;<em><strong>MASK</strong></em>, where &#8220;&amp;&#8221; is the
8046 bitwise <em>AND</em> operator.</p>
8047 </li>
8048 <li>
8049 <p>Set <em><strong>DEF_CLK_VAL</strong></em> to:</p>
8050 <div class="openblock">
8051 <div class="content">
8052 <div class="dlist">
8053 <dl>
8054 <dt class="hdlist1">If <em><strong>V</strong></em>&#160;â‰¥&#160;<em><strong>CUR</strong></em></dt>
8055 <dd>
8056 <p><em><strong>H</strong></em>&#160;+&#160;<em><strong>V</strong></em></p>
8057 </dd>
8058 <dt class="hdlist1">Else</dt>
8059 <dd>
8060 <p><em><strong>H</strong></em>&#160;+&#160;<em><strong>MASK</strong></em>&#160;+&#160;1&#160;+&#160;<em><strong>V</strong></em></p>
8061 </dd>
8062 </dl>
8063 </div>
8064 </div>
8065 </div>
8066 </li>
8067 </ol>
8068 </div>
8069 </div>
8070 </div>
8071 <div class="sect2">
8072 <h3 id="field-dec">6.3. Field decoding procedure</h3>
8073 <div class="paragraph">
8074 <p>The <a href="#fc">class</a> of a field contains what&#8217;s needed to decode it as a
8075 <em>value</em>.</p>
8076 </div>
8077 <div class="paragraph">
8078 <p>While a field is an actual <a href="#seq-def">sequence</a> of bits within a
8079 <a href="#ds">data stream</a>, a value is its conceptual interpretation with
8080 attached semantics.</p>
8081 </div>
8082 <div class="paragraph">
8083 <p><a id="dec-val-type"></a> The types of values are:</p>
8084 </div>
8085 <table class="tableblock frame-all grid-all fit-content">
8086 <colgroup>
8087 <col>
8088 <col>
8089 </colgroup>
8090 <thead>
8091 <tr>
8092 <th class="tableblock halign-left valign-top">Value type</th>
8093 <th class="tableblock halign-left valign-top">Possible values</th>
8094 </tr>
8095 </thead>
8096 <tbody>
8097 <tr>
8098 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8099 <p>Nil</p>
8100 </div></div></td>
8101 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8102 <p>None.</p>
8103 </div></div></td>
8104 </tr>
8105 <tr>
8106 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8107 <p>Boolean</p>
8108 </div></div></td>
8109 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8110 <p><em>True</em> or <em>false</em>.</p>
8111 </div></div></td>
8112 </tr>
8113 <tr>
8114 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8115 <p>Unsigned/signed integer</p>
8116 </div></div></td>
8117 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8118 <p>Integral quantity.</p>
8119 </div></div></td>
8120 </tr>
8121 <tr>
8122 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8123 <p>Real</p>
8124 </div></div></td>
8125 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8126 <p>Continuous quantity.</p>
8127 </div></div></td>
8128 </tr>
8129 <tr>
8130 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8131 <p>String</p>
8132 </div></div></td>
8133 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8134 <p><a href="#seq-def">Sequence</a> of <a href="https://home.unicode.org/">Unicode</a> characters.</p>
8135 </div></div></td>
8136 </tr>
8137 <tr>
8138 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8139 <p>Array</p>
8140 </div></div></td>
8141 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8142 <p>Sequence of values.</p>
8143 </div></div></td>
8144 </tr>
8145 <tr>
8146 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8147 <p>Structure</p>
8148 </div></div></td>
8149 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8150 <p>Sequence of named values (members).</p>
8151 </div></div></td>
8152 </tr>
8153 </tbody>
8154 </table>
8155 <div class="paragraph">
8156 <p>To decode an instance of a field class&#160;<em><strong>F</strong></em>, depending on the
8157 value of its <code>type</code> property:</p>
8158 </div>
8159 <table class="tableblock frame-all grid-all fit-content">
8160 <colgroup>
8161 <col>
8162 <col>
8163 </colgroup>
8164 <thead>
8165 <tr>
8166 <th class="tableblock halign-left valign-top">Value of the <code>type</code> property of&#160;<em><strong>F</strong></em></th>
8167 <th class="tableblock halign-left valign-top">Decoding procedure of <em><strong>F</strong></em></th>
8168 </tr>
8169 </thead>
8170 <tbody>
8171 <tr>
8172 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8173 <p><a href="#fl-ba-fc"><code>"fixed-length-bit-array"</code></a></p>
8174 </div></div></td>
8175 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8176 <p><a href="#fl-ba-field-dec">Decode a fixed-length bit array field</a>.</p>
8177 </div></div></td>
8178 </tr>
8179 <tr>
8180 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8181 <p><a href="#fl-bool-fc"><code>"fixed-length-boolean"</code></a></p>
8182 </div></div></td>
8183 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8184 <p><a href="#fl-bool-field-dec">Decode a fixed-length boolean field</a>.</p>
8185 </div></div></td>
8186 </tr>
8187 <tr>
8188 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8189 <ul>
8190 <li>
8191 <p><a href="#fl-int-fc"><code>"fixed-length-unsigned-integer"</code></a></p>
8192 </li>
8193 <li>
8194 <p><a href="#fl-enum-fc"><code>"fixed-length-unsigned-enumeration"</code></a></p>
8195 </li>
8196 </ul>
8197 </div></div></td>
8198 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8199 <p><a href="#fl-uint-field-dec">Decode a fixed-length unsigned integer field</a>.</p>
8200 </div></div></td>
8201 </tr>
8202 <tr>
8203 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8204 <ul>
8205 <li>
8206 <p><a href="#fl-int-fc"><code>"fixed-length-signed-integer"</code></a></p>
8207 </li>
8208 <li>
8209 <p><a href="#fl-enum-fc"><code>"fixed-length-signed-enumeration"</code></a></p>
8210 </li>
8211 </ul>
8212 </div></div></td>
8213 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8214 <p><a href="#fl-sint-field-dec">Decode a fixed-length signed integer field</a>.</p>
8215 </div></div></td>
8216 </tr>
8217 <tr>
8218 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8219 <p><a href="#fl-fp-fc"><code>"fixed-length-floating-point-number"</code></a></p>
8220 </div></div></td>
8221 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8222 <p><a href="#fl-fp-field-dec">Decode a fixed-length floating point number field</a>.</p>
8223 </div></div></td>
8224 </tr>
8225 <tr>
8226 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8227 <p><a href="#vl-ba-fc"><code>"variable-length-bit-array"</code></a></p>
8228 </div></div></td>
8229 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8230 <p><a href="#vl-ba-field-dec">Decode a variable-length bit array field</a>.</p>
8231 </div></div></td>
8232 </tr>
8233 <tr>
8234 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8235 <ul>
8236 <li>
8237 <p><a href="#vl-int-fc"><code>"variable-length-unsigned-integer"</code></a></p>
8238 </li>
8239 <li>
8240 <p><a href="#vl-enum-fc"><code>"variable-length-unsigned-enumeration"</code></a></p>
8241 </li>
8242 </ul>
8243 </div></div></td>
8244 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8245 <p><a href="#vl-uint-field-dec">Decode a variable-length unsigned integer field</a>.</p>
8246 </div></div></td>
8247 </tr>
8248 <tr>
8249 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8250 <ul>
8251 <li>
8252 <p><a href="#vl-int-fc"><code>"variable-length-signed-integer"</code></a></p>
8253 </li>
8254 <li>
8255 <p><a href="#vl-enum-fc"><code>"variable-length-signed-enumeration"</code></a></p>
8256 </li>
8257 </ul>
8258 </div></div></td>
8259 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8260 <p><a href="#vl-sint-field-dec">Decode a variable-length signed integer</a>.</p>
8261 </div></div></td>
8262 </tr>
8263 <tr>
8264 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8265 <p><a href="#str-fc"><code>"null-terminated-string"</code></a></p>
8266 </div></div></td>
8267 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8268 <p><a href="#str-field-dec">Decode a null-terminated string field</a>.</p>
8269 </div></div></td>
8270 </tr>
8271 <tr>
8272 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8273 <p><a href="#sl-str-fc"><code>"static-length-string"</code></a></p>
8274 </div></div></td>
8275 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8276 <p><a href="#sl-str-field-dec">Decode a static-length string field</a>.</p>
8277 </div></div></td>
8278 </tr>
8279 <tr>
8280 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8281 <p><a href="#sl-blob-fc"><code>"static-length-blob"</code></a></p>
8282 </div></div></td>
8283 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8284 <p><a href="#sl-blob-field-dec">Decode a static-length BLOB field</a>.</p>
8285 </div></div></td>
8286 </tr>
8287 <tr>
8288 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8289 <p><a href="#dl-str-fc"><code>"dynamic-length-string"</code></a></p>
8290 </div></div></td>
8291 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8292 <p><a href="#dl-str-field-dec">Decode a dynamic-length string field</a>.</p>
8293 </div></div></td>
8294 </tr>
8295 <tr>
8296 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8297 <p><a href="#dl-blob-fc"><code>"dynamic-length-blob"</code></a></p>
8298 </div></div></td>
8299 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8300 <p><a href="#dl-blob-field-dec">Decode a dynamic-length BLOB field</a>.</p>
8301 </div></div></td>
8302 </tr>
8303 <tr>
8304 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8305 <p><a href="#struct-fc"><code>"structure"</code></a></p>
8306 </div></div></td>
8307 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8308 <p><a href="#struct-field-dec">Decode a structure field</a>.</p>
8309 </div></div></td>
8310 </tr>
8311 <tr>
8312 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8313 <p><a href="#sl-array-fc"><code>"static-length-array"</code></a></p>
8314 </div></div></td>
8315 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8316 <p><a href="#sl-array-field-dec">Decode a static-length array field</a>.</p>
8317 </div></div></td>
8318 </tr>
8319 <tr>
8320 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8321 <p><a href="#dl-array-fc"><code>"dynamic-length-array"</code></a></p>
8322 </div></div></td>
8323 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8324 <p><a href="#dl-array-field-dec">Decode a dynamic-length array field</a>.</p>
8325 </div></div></td>
8326 </tr>
8327 <tr>
8328 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8329 <p><a href="#opt-fc"><code>"optional"</code></a></p>
8330 </div></div></td>
8331 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8332 <p><a href="#opt-field-dec">Decode an optional field</a>.</p>
8333 </div></div></td>
8334 </tr>
8335 <tr>
8336 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8337 <p><a href="#var-fc"><code>"variant"</code></a></p>
8338 </div></div></td>
8339 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8340 <p><a href="#var-field-dec">Decode a variant field</a>.</p>
8341 </div></div></td>
8342 </tr>
8343 </tbody>
8344 </table>
8345 <div class="sect3">
8346 <h4 id="align-dec">6.3.1. Alignment procedure</h4>
8347 <div class="paragraph">
8348 <p>The decoding procedure of many fields require
8349 <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em> to have a specific <em>alignment</em>.</p>
8350 </div>
8351 <div class="paragraph">
8352 <p>The alignment <em>requirement</em> of an instance of a <a href="#fc">field
8353 class</a>&#160;<em><strong>F</strong></em> is, depending on the value of its <code>type</code> property:</p>
8354 </div>
8355 <table class="tableblock frame-all grid-all stretch">
8356 <colgroup>
8357 <col style="width: 50%;">
8358 <col style="width: 50%;">
8359 </colgroup>
8360 <thead>
8361 <tr>
8362 <th class="tableblock halign-left valign-top"><code>type</code> property of <em><strong>F</strong></em></th>
8363 <th class="tableblock halign-left valign-top">Alignment requirement of <em><strong>F</strong></em></th>
8364 </tr>
8365 </thead>
8366 <tbody>
8367 <tr>
8368 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8369 <ul>
8370 <li>
8371 <p><a href="#fl-ba-fc"><code>"fixed-length-bit-array"</code></a></p>
8372 </li>
8373 <li>
8374 <p><a href="#fl-bool-fc"><code>"fixed-length-boolean"</code></a></p>
8375 </li>
8376 <li>
8377 <p><a href="#fl-int-fc"><code>"fixed-length-unsigned-integer"</code></a></p>
8378 </li>
8379 <li>
8380 <p><a href="#fl-int-fc"><code>"fixed-length-signed-integer"</code></a></p>
8381 </li>
8382 <li>
8383 <p><a href="#fl-enum-fc"><code>"fixed-length-unsigned-enumeration"</code></a></p>
8384 </li>
8385 <li>
8386 <p><a href="#fl-enum-fc"><code>"fixed-length-signed-enumeration"</code></a></p>
8387 </li>
8388 <li>
8389 <p><a href="#fl-fp-fc"><code>"fixed-length-floating-point-number"</code></a></p>
8390 </li>
8391 </ul>
8392 </div></div></td>
8393 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8394 <p>The value of the <code>alignment</code> property of&#160;<em><strong>F</strong></em>.</p>
8395 </div></div></td>
8396 </tr>
8397 <tr>
8398 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8399 <ul>
8400 <li>
8401 <p><a href="#vl-ba-fc"><code>"variable-length-bit-array"</code></a></p>
8402 </li>
8403 <li>
8404 <p><a href="#vl-int-fc"><code>"variable-length-unsigned-integer"</code></a></p>
8405 </li>
8406 <li>
8407 <p><a href="#vl-int-fc"><code>"variable-length-signed-integer"</code></a></p>
8408 </li>
8409 <li>
8410 <p><a href="#vl-enum-fc"><code>"variable-length-unsigned-enumeration"</code></a></p>
8411 </li>
8412 <li>
8413 <p><a href="#vl-enum-fc"><code>"variable-length-signed-enumeration"</code></a></p>
8414 </li>
8415 <li>
8416 <p><a href="#str-fc"><code>"null-terminated-string"</code></a></p>
8417 </li>
8418 <li>
8419 <p><a href="#sl-str-fc"><code>"static-length-string"</code></a></p>
8420 </li>
8421 <li>
8422 <p><a href="#sl-blob-fc"><code>"static-length-blob"</code></a></p>
8423 </li>
8424 <li>
8425 <p><a href="#dl-str-fc"><code>"dynamic-length-string"</code></a></p>
8426 </li>
8427 <li>
8428 <p><a href="#dl-blob-fc"><code>"dynamic-length-blob"</code></a></p>
8429 </li>
8430 </ul>
8431 </div></div></td>
8432 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8433 <p>8</p>
8434 </div></div></td>
8435 </tr>
8436 <tr>
8437 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8438 <p><a href="#struct-fc"><code>"structure"</code></a></p>
8439 </div></div></td>
8440 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8441 <p>The <em>maximum</em> value of:</p>
8442 </div>
8443 <div class="ulist">
8444 <ul>
8445 <li>
8446 <p>The value of the <code>minimum-alignment</code> property of&#160;<em><strong>F</strong></em>.</p>
8447 </li>
8448 <li>
8449 <p>The alignment requirements of the instances of the <code>field-class</code>
8450 property of each <a href="#struct-member-cls">member class</a> of the
8451 <code>member-classes</code> property of&#160;<em><strong>F</strong></em>.</p>
8452 </li>
8453 </ul>
8454 </div></div></td>
8455 </tr>
8456 <tr>
8457 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8458 <ul>
8459 <li>
8460 <p><a href="#sl-array-fc"><code>"static-length-array"</code></a></p>
8461 </li>
8462 <li>
8463 <p><a href="#dl-array-fc"><code>"dynamic-length-array"</code></a></p>
8464 </li>
8465 </ul>
8466 </div></div></td>
8467 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8468 <p>The <em>maximum</em> value of:</p>
8469 </div>
8470 <div class="ulist">
8471 <ul>
8472 <li>
8473 <p>The value of the <code>minimum-alignment</code> property of&#160;<em><strong>F</strong></em>.</p>
8474 </li>
8475 <li>
8476 <p>The alignment requirement of an instance of the
8477 <code>element-field-class</code> property of&#160;<em><strong>F</strong></em>.</p>
8478 </li>
8479 </ul>
8480 </div></div></td>
8481 </tr>
8482 <tr>
8483 <td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
8484 <ul>
8485 <li>
8486 <p><a href="#opt-fc"><code>"optional"</code></a></p>
8487 </li>
8488 <li>
8489 <p><a href="#var-fc"><code>"variant"</code></a></p>
8490 </li>
8491 </ul>
8492 </div></div></td>
8493 <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
8494 <p>1</p>
8495 </div></div></td>
8496 </tr>
8497 </tbody>
8498 </table>
8499 <div class="paragraph">
8500 <p>To align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em> to some alignment
8501 requirement&#160;<em><strong>A</strong></em> (bits):</p>
8502 </div>
8503 <div class="ulist">
8504 <ul>
8505 <li>
8506 <p>Set <em><strong>O</strong></em> to
8507 <em><strong>PO</strong></em>&#160;+&#160;((<em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;+&#160;<em><strong>A</strong></em>&#160;âˆ’&#160;1)&#160;&amp;&#160;âˆ’<em><strong>A</strong></em>),
8508 where &#8220;&amp;&#8221; is the bitwise <em>AND</em> operator.</p>
8509 </li>
8510 </ul>
8511 </div>
8512 </div>
8513 <div class="sect3">
8514 <h4 id="field-loc-dec">6.3.2. Field location procedure</h4>
8515 <div class="paragraph">
8516 <p>To locate a previously decoded field using a
8517 <a href="#field-loc">field location</a>&#160;<em><strong>FL</strong></em>:</p>
8518 </div>
8519 <div class="olist arabic">
8520 <ol class="arabic">
8521 <li>
8522 <p>Let <em><strong>V</strong></em> be, depending on the first element of&#160;<em><strong>FL</strong></em>:</p>
8523 <div class="openblock">
8524 <div class="content">
8525 <div class="dlist">
8526 <dl>
8527 <dt class="hdlist1"><code>"packet-header"</code></dt>
8528 <dd>
8529 <p>The <a href="#pkt-header">header</a> structure of&#160;<em><strong>P</strong></em>
8530 (<a href="#pkt-dec">current packet</a>).</p>
8531 </dd>
8532 <dt class="hdlist1"><code>"packet-context"</code></dt>
8533 <dd>
8534 <p>The <a href="#pkt-ctx">context</a> structure of&#160;<em><strong>P</strong></em>.</p>
8535 </dd>
8536 <dt class="hdlist1"><code>"event-record-header"</code></dt>
8537 <dd>
8538 <p>The <a href="#er-header">header</a> structure of&#160;<em><strong>E</strong></em>
8539 (<a href="#er-dec">current event record</a>).</p>
8540 </dd>
8541 <dt class="hdlist1"><code>"event-record-common-context"</code></dt>
8542 <dd>
8543 <p>The <a href="#er-common-ctx">common context</a> structure of&#160;<em><strong>E</strong></em>.</p>
8544 </dd>
8545 <dt class="hdlist1"><code>"event-record-specific-context"</code></dt>
8546 <dd>
8547 <p>The <a href="#er-spec-ctx">specific context</a> structure of&#160;<em><strong>E</strong></em>.</p>
8548 </dd>
8549 <dt class="hdlist1"><code>"event-record-payload"</code></dt>
8550 <dd>
8551 <p>The <a href="#er-payload">payload</a> structure of&#160;<em><strong>E</strong></em>.</p>
8552 </dd>
8553 </dl>
8554 </div>
8555 </div>
8556 </div>
8557 <div class="paragraph">
8558 <p>If the consumer cannot set <em><strong>V</strong></em> because there&#8217;s no such structure or
8559 because it&#8217;s not already decoded nor currently being decoded, then
8560 report an error and abort the data stream decoding process.</p>
8561 </div>
8562 </li>
8563 <li>
8564 <p>For each element&#160;<em><strong>FLE</strong></em> of&#160;<em><strong>FL</strong></em>, starting from
8565 the second element:</p>
8566 <div class="olist loweralpha">
8567 <ol class="loweralpha" type="a">
8568 <li>
8569 <p>Let <em><strong>V</strong></em> be the value of the member named&#160;<em><strong>FLE</strong></em>
8570 within&#160;<em><strong>V</strong></em>.</p>
8571 <div class="paragraph">
8572 <p>If no member is named&#160;<em><strong>FLE</strong></em> within&#160;<em><strong>V</strong></em>, then
8573 report an error and abort the data stream decoding process.</p>
8574 </div>
8575 <div class="paragraph">
8576 <p>If the member named&#160;<em><strong>FLE</strong></em> within&#160;<em><strong>V</strong></em> is not already
8577 decoded nor currently being decoded, then report an error and abort
8578 the data stream decoding process.</p>
8579 </div>
8580 </li>
8581 <li>
8582 <p>Depending on the <a href="#dec-val-type">type</a> of <em><strong>V</strong></em>:</p>
8583 <div class="openblock">
8584 <div class="content">
8585 <div class="dlist">
8586 <dl>
8587 <dt class="hdlist1">Boolean</dt>
8588 <dt class="hdlist1">Signed integer</dt>
8589 <dt class="hdlist1">Unsigned integer</dt>
8590 <dd>
8591 <p>If&#160;<em><strong>FLE</strong></em> is not the last element of&#160;<em><strong>FL</strong></em>,
8592 then report an error and abort the data stream decoding process.</p>
8593 </dd>
8594 <dt class="hdlist1">Structure</dt>
8595 <dd>
8596 <p>Continue.</p>
8597 </dd>
8598 <dt class="hdlist1">Array</dt>
8599 <dd>
8600 <p>While <em><strong>V</strong></em> is an array:</p>
8601 <div class="ulist">
8602 <ul>
8603 <li>
8604 <p>If <em><strong>V</strong></em> is not currently being decoded, then report an error and
8605 abort the data stream decoding process.</p>
8606 <div class="paragraph">
8607 <p>Set <em><strong>V</strong></em> to the element of <em><strong>V</strong></em> currently being decoded.</p>
8608 </div>
8609 </li>
8610 </ul>
8611 </div>
8612 </dd>
8613 <dt class="hdlist1">Other</dt>
8614 <dd>
8615 <p>Report an error and abort the data stream decoding process.</p>
8616 </dd>
8617 </dl>
8618 </div>
8619 </div>
8620 </div>
8621 </li>
8622 </ol>
8623 </div>
8624 </li>
8625 </ol>
8626 </div>
8627 <div class="paragraph">
8628 <p><em><strong>V</strong></em> is the located field.</p>
8629 </div>
8630 <div class="exampleblock">
8631 <div class="title">Example 80. <a href="#dl-array">Dynamic-length array</a> field and its length field in the same root field.</div>
8632 <div class="content">
8633 <div class="paragraph">
8634 <p>Assume the following JSON object is an event record payload <a href="#struct-fc">structure field class</a>.</p>
8635 </div>
8636 <div class="listingblock">
8637 <div class="content">
8638 <pre class="highlight"><code class="language-json" data-lang="json">{
8639   "type": "structure",
8640   "member-classes": [
8641     {
8642       "name": "corn", <i class="conum" data-value="3"></i><b>(3)</b>
8643       "field-class": {
8644         "type": "fixed-length-unsigned-integer",
8645         "length": 32,
8646         "byte-order": "little-endian"
8647       }
8648     },
8649     {
8650       "name": "inside",
8651       "field-class": {
8652         "type": "fixed-length-unsigned-integer",
8653         "length": 16,
8654         "byte-order": "little-endian"
8655       }
8656     },
8657     {
8658       "name": "carbon",
8659       "field-class": {
8660         "type": "dynamic-length-array", <i class="conum" data-value="1"></i><b>(1)</b>
8661         "length-field-location": ["event-record-payload", "corn"], <i class="conum" data-value="2"></i><b>(2)</b>
8662         "element-field-class": {
8663           "type": "null-terminated-string"
8664         }
8665       }
8666     }
8667   ]
8668 }</code></pre>
8669 </div>
8670 </div>
8671 <div class="colist arabic">
8672 <table>
8673 <tr>
8674 <td><i class="conum" data-value="1"></i><b>1</b></td>
8675 <td><a href="#dl-array-fc">Dynamic-length array field class</a>.</td>
8676 </tr>
8677 <tr>
8678 <td><i class="conum" data-value="2"></i><b>2</b></td>
8679 <td>Length field location of the <a href="#dl-array-fc">dynamic-length array field class</a>.</td>
8680 </tr>
8681 <tr>
8682 <td><i class="conum" data-value="3"></i><b>3</b></td>
8683 <td>Length member class.</td>
8684 </tr>
8685 </table>
8686 </div>
8687 </div>
8688 </div>
8689 <div class="exampleblock">
8690 <div class="title">Example 81. Dynamic-length array field and its length field in the same root field, within the same array field element.</div>
8691 <div class="content">
8692 <div class="paragraph">
8693 <p>Assume the following JSON object is an event record payload <a href="#struct-fc">structure field class</a>.</p>
8694 </div>
8695 <div class="paragraph">
8696 <p>Both the dynamic-length array field and its length field exist within the same
8697 element of the <a href="#sl-array-fc">static-length array</a> field named <code>nature</code>.</p>
8698 </div>
8699 <div class="listingblock">
8700 <div class="content">
8701 <pre class="highlight"><code class="language-json" data-lang="json">{
8702   "type": "structure",
8703   "member-classes": [
8704     {
8705       "name": "norm",
8706       "field-class": {
8707         "type": "null-terminated-string"
8708       }
8709     },
8710     {
8711       "name": "nature",
8712       "field-class": {
8713         "type": "static-length-array",
8714         "length": 43,
8715         "element-field-class": {
8716           "type": "structure",
8717           "member-classes": [
8718             {
8719               "name": "laser", <i class="conum" data-value="3"></i><b>(3)</b>
8720               "field-class": {
8721                 "type": "variable-length-unsigned-integer"
8722               }
8723             },
8724             {
8725               "name": "joystick",
8726               "field-class": {
8727                 "type": "dynamic-length-array", <i class="conum" data-value="1"></i><b>(1)</b>
8728                 "length-field-location": [ <i class="conum" data-value="2"></i><b>(2)</b>
8729                   "event-record-payload",
8730                   "nature",
8731                   "laser"
8732                 ],
8733                 "element-field-class": {
8734                   "type": "null-terminated-string"
8735                 }
8736               }
8737             }
8738           ]
8739         }
8740       }
8741     }
8742   ]
8743 }</code></pre>
8744 </div>
8745 </div>
8746 <div class="colist arabic">
8747 <table>
8748 <tr>
8749 <td><i class="conum" data-value="1"></i><b>1</b></td>
8750 <td><a href="#dl-array-fc">Dynamic-length array field class</a>.</td>
8751 </tr>
8752 <tr>
8753 <td><i class="conum" data-value="2"></i><b>2</b></td>
8754 <td>Length field location of the <a href="#dl-array-fc">dynamic-length array field class</a>.</td>
8755 </tr>
8756 <tr>
8757 <td><i class="conum" data-value="3"></i><b>3</b></td>
8758 <td>Length member class.</td>
8759 </tr>
8760 </table>
8761 </div>
8762 </div>
8763 </div>
8764 <div class="exampleblock">
8765 <div class="title">Example 82. Dynamic-length array and its length field in the same root field, within the same <a href="#var-fc">variant</a> field.</div>
8766 <div class="content">
8767 <div class="paragraph">
8768 <p>Assume the following JSON object is an event record payload <a href="#struct-fc">structure field class</a>.</p>
8769 </div>
8770 <div class="paragraph">
8771 <p>Both the dynamic-length array field and its length field exist within the same
8772 option of the <a href="#var-fc">variant</a> field named <code>clinic</code>.</p>
8773 </div>
8774 <div class="paragraph">
8775 <p>Moreover, the selector field of the <code>clinic</code> variant field is the
8776 <code>lawyer</code> field.</p>
8777 </div>
8778 <div class="listingblock">
8779 <div class="content">
8780 <pre class="highlight"><code class="language-json" data-lang="json">{
8781   "type": "structure",
8782   "member-classes": [
8783     {
8784       "name": "lawyer", <i class="conum" data-value="5"></i><b>(5)</b>
8785       "field-class": {
8786         "type": "fixed-length-signed-integer",
8787         "length": 16,
8788         "byte-order": "little-endian"
8789       }
8790     },
8791     {
8792       "name": "clinic",
8793       "field-class": {
8794         "type": "variant",
8795         "selector-field-location": ["event-record-payload", "lawyer"], <i class="conum" data-value="4"></i><b>(4)</b>
8796         "options": [
8797           {
8798             "selector-field-ranges": [[0, 0]],
8799             "field-class": {
8800               "type": "null-terminated-string"
8801             }
8802           },
8803           {
8804             "selector-field-ranges": [[1, 4]],
8805             "field-class": {
8806               "type": "structure",
8807               "member-classes": [
8808                 {
8809                   "name": "lemon", <i class="conum" data-value="3"></i><b>(3)</b>
8810                   "field-class": {
8811                     "type": "fixed-length-unsigned-integer",
8812                     "length": 8,
8813                     "byte-order": "big-endian"
8814                   }
8815                 },
8816                 {
8817                   "name": "joystick",
8818                   "field-class": {
8819                     "type": "dynamic-length-array", <i class="conum" data-value="1"></i><b>(1)</b>
8820                     "length-field-location": [ <i class="conum" data-value="2"></i><b>(2)</b>
8821                       "event-record-payload",
8822                       "clinic",
8823                       "lemon"
8824                     ],
8825                     "element-field-class": {
8826                       "type": "null-terminated-string"
8827                     }
8828                   }
8829                 }
8830               ]
8831             }
8832           },
8833           {
8834             "selector-field-ranges": [[5, 5], [7, 7]],
8835             "field-class": {
8836               "type": "fixed-length-boolean",
8837               "length": 8,
8838               "byte-order": "little-endian"
8839             }
8840           }
8841         ]
8842       }
8843     }
8844   ]
8845 }</code></pre>
8846 </div>
8847 </div>
8848 <div class="colist arabic">
8849 <table>
8850 <tr>
8851 <td><i class="conum" data-value="1"></i><b>1</b></td>
8852 <td><a href="#dl-array-fc">Dynamic-length array field class</a>.</td>
8853 </tr>
8854 <tr>
8855 <td><i class="conum" data-value="2"></i><b>2</b></td>
8856 <td>Length field location of the <a href="#dl-array-fc">dynamic-length array field class</a>.</td>
8857 </tr>
8858 <tr>
8859 <td><i class="conum" data-value="3"></i><b>3</b></td>
8860 <td>Length member class.</td>
8861 </tr>
8862 <tr>
8863 <td><i class="conum" data-value="4"></i><b>4</b></td>
8864 <td>Selector field location of the variant field class.</td>
8865 </tr>
8866 <tr>
8867 <td><i class="conum" data-value="5"></i><b>5</b></td>
8868 <td>Selector member class.</td>
8869 </tr>
8870 </table>
8871 </div>
8872 </div>
8873 </div>
8874 <div class="exampleblock">
8875 <div class="title">Example 83. Dynamic-length array and its length field in the same root field; length field is a variant field.</div>
8876 <div class="content">
8877 <div class="paragraph">
8878 <p>Assume the following JSON object is an event record payload <a href="#struct-fc">structure field class</a>.</p>
8879 </div>
8880 <div class="paragraph">
8881 <p>The length field of the dynamic-length array field is a variant field: it can be
8882 an 8-bit, a 16-bit, or a 32-bit <a href="#fl-int-fc">fixed-length integer</a> field, depending
8883 on the selection of the variant field.</p>
8884 </div>
8885 <div class="paragraph">
8886 <p>Moreover, the selector field of the variant field is located in another
8887 root field (event record specific context).</p>
8888 </div>
8889 <div class="listingblock">
8890 <div class="content">
8891 <pre class="highlight"><code class="language-json" data-lang="json">{
8892   "type": "structure",
8893   "member-classes": [
8894     {
8895       "name": "glass", <i class="conum" data-value="3"></i><b>(3)</b>
8896       "field-class": {
8897         "type": "variant",
8898         "selector-field-location": ["event-record-specific-context", "sel"],
8899         "options": [
8900           {
8901             "selector-field-ranges": [[0, 0]],
8902             "field-class": {
8903               "type": "fixed-length-unsigned-integer", <i class="conum" data-value="4"></i><b>(4)</b>
8904               "length": 8,
8905               "byte-order": "little-endian"
8906             }
8907           },
8908           {
8909             "selector-field-ranges": [[1, 1]],
8910             "field-class": {
8911               "type": "fixed-length-unsigned-integer", <i class="conum" data-value="4"></i><b>(4)</b>
8912               "length": 16,
8913               "byte-order": "little-endian"
8914             }
8915           },
8916           {
8917             "selector-field-ranges": [[2, 2]],
8918             "field-class": {
8919               "type": "fixed-length-unsigned-integer", <i class="conum" data-value="4"></i><b>(4)</b>
8920               "length": 32,
8921               "byte-order": "little-endian"
8922             }
8923           }
8924         ]
8925       }
8926     },
8927     {
8928       "name": "margin",
8929       "field-class": {
8930         "type": "dynamic-length-array", <i class="conum" data-value="1"></i><b>(1)</b>
8931         "length-field-location": ["event-record-payload", "glass"], <i class="conum" data-value="2"></i><b>(2)</b>
8932         "element-field-class": {
8933           "type": "null-terminated-string"
8934         }
8935       }
8936     }
8937   ]
8938 }</code></pre>
8939 </div>
8940 </div>
8941 <div class="colist arabic">
8942 <table>
8943 <tr>
8944 <td><i class="conum" data-value="1"></i><b>1</b></td>
8945 <td><a href="#dl-array-fc">Dynamic-length array field class</a>.</td>
8946 </tr>
8947 <tr>
8948 <td><i class="conum" data-value="2"></i><b>2</b></td>
8949 <td>Length field location of the <a href="#dl-array-fc">dynamic-length array field class</a>.</td>
8950 </tr>
8951 <tr>
8952 <td><i class="conum" data-value="3"></i><b>3</b></td>
8953 <td>Length member class.</td>
8954 </tr>
8955 <tr>
8956 <td><i class="conum" data-value="4"></i><b>4</b></td>
8957 <td>Possible length field class.</td>
8958 </tr>
8959 </table>
8960 </div>
8961 </div>
8962 </div>
8963 <div class="exampleblock">
8964 <div class="title">Example 84. Dynamic-length array and its length field in the same root field; structure field containing length field is a variant field.</div>
8965 <div class="content">
8966 <div class="paragraph">
8967 <p>Assume the following JSON object is an event record payload <a href="#struct-fc">structure field class</a>.</p>
8968 </div>
8969 <div class="paragraph">
8970 <p>The length field of the dynamic-length array field is within a structure field
8971 which is a variant field.</p>
8972 </div>
8973 <div class="paragraph">
8974 <p>Moreover:</p>
8975 </div>
8976 <div class="ulist">
8977 <ul>
8978 <li>
8979 <p>The selector field of the variant field is located in another root
8980 field (event record common context).</p>
8981 </li>
8982 <li>
8983 <p>The field class of the third option of the <code>glass</code> variant field class
8984 contains a <a href="#dl-blob-fc">dynamic-length BLOB field class</a> (<code>lock</code> member); the
8985 length field of its instance is the previous member (<code>eagle</code>) within
8986 the same structure field.</p>
8987 </li>
8988 </ul>
8989 </div>
8990 <div class="listingblock">
8991 <div class="content">
8992 <pre class="highlight"><code class="language-json" data-lang="json">{
8993   "type": "structure",
8994   "member-classes": [
8995     {
8996       "name": "glass",
8997       "field-class": {
8998         "type": "variant",
8999         "selector-field-location": ["event-record-common-context", "sel"],
9000         "options": [
9001           {
9002             "selector-field-ranges": [[0, 0]],
9003             "field-class": {
9004               "type": "structure",
9005               "member-classes": [
9006                 {
9007                   "name": "eagle",
9008                   "field-class": {
9009                     "type": "fixed-length-unsigned-integer", <i class="conum" data-value="3"></i><b>(3)</b>
9010                     "length": 16,
9011                     "byte-order": "little-endian"
9012                   }
9013                 },
9014                 {
9015                   "name": "road",
9016                   "field-class": {
9017                     "type": "null-terminated-string"
9018                   }
9019                 }
9020               ]
9021             }
9022           },
9023           {
9024             "selector-field-ranges": [[32, 172]],
9025             "field-class": {
9026               "type": "structure",
9027               "member-classes": [
9028                 {
9029                   "name": "nuance",
9030                   "field-class": {
9031                     "type": "null-terminated-string"
9032                   }
9033                 },
9034                 {
9035                   "name": "eagle",
9036                   "field-class": {
9037                     "type": "fixed-length-unsigned-integer", <i class="conum" data-value="3"></i><b>(3)</b>
9038                     "length": 24,
9039                     "byte-order": "big-endian"
9040                   }
9041                 }
9042               ]
9043             }
9044           },
9045           {
9046             "selector-field-ranges": [[5, 5]],
9047             "field-class": {
9048               "type": "structure",
9049               "member-classes": [
9050                 {
9051                   "name": "eagle", <i class="conum" data-value="5"></i><b>(5)</b>
9052                   "field-class": {
9053                     "type": "variable-length-unsigned-integer" <i class="conum" data-value="3"></i><b>(3)</b>
9054                   }
9055                 },
9056                 {
9057                   "name": "lock",
9058                   "field-class": {
9059                     "type": "dynamic-length-blob",
9060                     "length-field-location": [ <i class="conum" data-value="4"></i><b>(4)</b>
9061                       "event-record-payload",
9062                       "glass",
9063                       "eagle"
9064                     ]
9065                   }
9066                 }
9067               ]
9068             }
9069           }
9070         ]
9071       }
9072     },
9073     {
9074       "name": "margin",
9075       "field-class": {
9076         "type": "dynamic-length-array", <i class="conum" data-value="1"></i><b>(1)</b>
9077         "length-field-location": [ <i class="conum" data-value="2"></i><b>(2)</b>
9078           "event-record-payload",
9079           "glass",
9080           "eagle"
9081         ],
9082         "element-field-class": {
9083           "type": "null-terminated-string"
9084         }
9085       }
9086     }
9087   ]
9088 }</code></pre>
9089 </div>
9090 </div>
9091 <div class="colist arabic">
9092 <table>
9093 <tr>
9094 <td><i class="conum" data-value="1"></i><b>1</b></td>
9095 <td><a href="#dl-array-fc">Dynamic-length array field class</a>.</td>
9096 </tr>
9097 <tr>
9098 <td><i class="conum" data-value="2"></i><b>2</b></td>
9099 <td>Length field location of the <a href="#dl-array-fc">dynamic-length array field class</a>.</td>
9100 </tr>
9101 <tr>
9102 <td><i class="conum" data-value="3"></i><b>3</b></td>
9103 <td>Possible length field class.</td>
9104 </tr>
9105 <tr>
9106 <td><i class="conum" data-value="4"></i><b>4</b></td>
9107 <td>Length field location of the <a href="#dl-blob-fc">dynamic-length BLOB field class</a>.</td>
9108 </tr>
9109 <tr>
9110 <td><i class="conum" data-value="5"></i><b>5</b></td>
9111 <td>Length field class for the <a href="#dl-blob-fc">dynamic-length BLOB field class</a>.</td>
9112 </tr>
9113 </table>
9114 </div>
9115 <div class="paragraph">
9116 <p>Note that both the dynamic-length array and dynamic-length BLOB field classes have the same
9117 length field location.</p>
9118 </div>
9119 </div>
9120 </div>
9121 <div class="exampleblock">
9122 <div class="title">Example 85. Dynamic-length array and its length field in another root field.</div>
9123 <div class="content">
9124 <div class="paragraph">
9125 <p>Assume the following JSON objects are the event record specific context
9126 and payload <a href="#struct-fc">structure field classes</a> of the same
9127 <a href="#erc-frag">event record class</a>.</p>
9128 </div>
9129 <div class="paragraph">
9130 <p>The length field of the dynamic-length array field of the event record payload is
9131 within the event record specific context.</p>
9132 </div>
9133 <div class="listingblock">
9134 <div class="title">Event record specific context field class.</div>
9135 <div class="content">
9136 <pre class="highlight"><code class="language-json" data-lang="json">{
9137   "type": "structure",
9138   "member-classes": [
9139     {
9140       "name": "cook",
9141       "field-class": {
9142         "type": "fixed-length-floating-point-number",
9143         "length": 64,
9144         "byte-order": "little-endian"
9145       }
9146     },
9147     {
9148       "name": "vegetable", <i class="conum" data-value="1"></i><b>(1)</b>
9149       "field-class": {
9150         "type": "variable-length-unsigned-integer"
9151       }
9152     }
9153   ]
9154 }</code></pre>
9155 </div>
9156 </div>
9157 <div class="colist arabic">
9158 <table>
9159 <tr>
9160 <td><i class="conum" data-value="1"></i><b>1</b></td>
9161 <td>Length member class.</td>
9162 </tr>
9163 </table>
9164 </div>
9165 <div class="listingblock">
9166 <div class="title">Event record payload field class.</div>
9167 <div class="content">
9168 <pre class="highlight"><code class="language-json" data-lang="json">{
9169   "type": "structure",
9170   "member-classes": [
9171     {
9172       "name": "avenue",
9173       "field-class": {
9174         "type": "dynamic-length-array", <i class="conum" data-value="1"></i><b>(1)</b>
9175         "length-field-location": [ <i class="conum" data-value="2"></i><b>(2)</b>
9176           "event-record-specific-context",
9177           "vegetable"
9178         ],
9179         "element-field-class": {
9180           "type": "null-terminated-string"
9181         }
9182       }
9183     },
9184     {
9185       "name": "railroad",
9186       "field-class": {
9187         "type": "null-terminated-string"
9188       }
9189     }
9190   ]
9191 }</code></pre>
9192 </div>
9193 </div>
9194 <div class="colist arabic">
9195 <table>
9196 <tr>
9197 <td><i class="conum" data-value="1"></i><b>1</b></td>
9198 <td><a href="#dl-array-fc">Dynamic-length array field class</a>.</td>
9199 </tr>
9200 <tr>
9201 <td><i class="conum" data-value="2"></i><b>2</b></td>
9202 <td>Length field location of the <a href="#dl-array-fc">dynamic-length array field class</a>.</td>
9203 </tr>
9204 </table>
9205 </div>
9206 </div>
9207 </div>
9208 </div>
9209 <div class="sect3">
9210 <h4 id="fl-ba-field-dec">6.3.3. Fixed-length bit array field decoding procedure</h4>
9211 <div class="paragraph">
9212 <p>For this whole section about decoding an instance of a
9213 <a href="#fl-ba-fc">fixed-length bit array field class</a>&#160;<em><strong>F</strong></em>, let <em><strong>BO</strong></em> be the value of the <code>byte-order</code>
9214 property of&#160;<em><strong>F</strong></em>.</p>
9215 </div>
9216 <div class="paragraph">
9217 <p><a id="fl-ba-field-dec-bit"></a> To read a single data stream bit from an
9218 instance of&#160;<em><strong>F</strong></em>:</p>
9219 </div>
9220 <div class="olist arabic">
9221 <ol class="arabic">
9222 <li>
9223 <p>Let:</p>
9224 <div class="ulist">
9225 <ul>
9226 <li>
9227 <p><em><strong>BYTE_I</strong></em> be (<em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>)&#160;/&#160;8 (integral
9228 division; remainder discarded).</p>
9229 </li>
9230 <li>
9231 <p><em><strong>BIT_I</strong></em> be:</p>
9232 <div class="openblock">
9233 <div class="content">
9234 <div class="hdlist">
9235 <table>
9236 <tr>
9237 <td class="hdlist1">
9238 <em><strong>BO</strong></em> is <code>"big-endian"</code>
9239 </td>
9240 <td class="hdlist2">
9241 <p>7&#160;âˆ’&#160;((<em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>)&#160;mod&#160;8)</p>
9242 </td>
9243 </tr>
9244 <tr>
9245 <td class="hdlist1">
9246 <em><strong>BO</strong></em> is <code>"little-endian"</code>
9247 </td>
9248 <td class="hdlist2">
9249 <p>(<em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>)&#160;mod&#160;8</p>
9250 </td>
9251 </tr>
9252 </table>
9253 </div>
9254 </div>
9255 </div>
9256 </li>
9257 </ul>
9258 </div>
9259 </li>
9260 <li>
9261 <p>Depending on the value of the bit at the index&#160;<em><strong>BIT_I</strong></em>,
9262 where&#160;0 is the index of the
9263 <a href="https://en.wikipedia.org/wiki/Bit_numbering#Least_significant_bit">least significant bit</a>,
9264 within the byte at the index&#160;<em><strong>BYTE_I</strong></em> from the beginning
9265 of&#160;<em><strong>P</strong></em> (the current packet being decoded):</p>
9266 <div class="openblock">
9267 <div class="content">
9268 <div class="hdlist">
9269 <table>
9270 <tr>
9271 <td class="hdlist1">
9272 0
9273 </td>
9274 <td class="hdlist2">
9275 <p>The bit value is <em>false</em>.</p>
9276 </td>
9277 </tr>
9278 <tr>
9279 <td class="hdlist1">
9280 1
9281 </td>
9282 <td class="hdlist2">
9283 <p>The bit value is <em>true</em>.</p>
9284 </td>
9285 </tr>
9286 </table>
9287 </div>
9288 </div>
9289 </div>
9290 </li>
9291 </ol>
9292 </div>
9293 <div class="paragraph">
9294 <p>To decode an instance of&#160;<em><strong>F</strong></em>:</p>
9295 </div>
9296 <div class="olist arabic">
9297 <ol class="arabic">
9298 <li>
9299 <p>Let:</p>
9300 <div class="olist loweralpha">
9301 <ol class="loweralpha" type="a">
9302 <li>
9303 <p><em><strong>L</strong></em> be the value of the <code>length</code> property of&#160;<em><strong>F</strong></em>.</p>
9304 </li>
9305 <li>
9306 <p><em><strong>V</strong></em> be an array of booleans of length&#160;<em><strong>L</strong></em>.</p>
9307 </li>
9308 <li>
9309 <p><em><strong>I</strong></em> be an unsigned integer initialized to&#160;0.</p>
9310 </li>
9311 </ol>
9312 </div>
9313 </li>
9314 <li>
9315 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
9316 to&#160;<em><strong>F</strong></em>.</p>
9317 </li>
9318 <li>
9319 <p><a id="fl-ba-field-dec-step-3"></a> If
9320 ((<em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>)&#160;mod&#160;8&#160;â‰&#160;0) and
9321 <em><strong>LAST_BO</strong></em>&#160;â‰&#160;<em><strong>BO</strong></em>, then report an error
9322 and abort the data stream decoding process.</p>
9323 </li>
9324 <li>
9325 <p>While <em><strong>I</strong></em>&#160;&lt;&#160;<em><strong>L</strong></em>:</p>
9326 <div class="olist loweralpha">
9327 <ol class="loweralpha" type="a">
9328 <li>
9329 <p>Let <em><strong>VI</strong></em> be an unsigned integer initialized to:</p>
9330 <div class="hdlist">
9331 <table>
9332 <tr>
9333 <td class="hdlist1">
9334 <em><strong>BO</strong></em> is <code>"big-endian"</code>
9335 </td>
9336 <td class="hdlist2">
9337 <p>0</p>
9338 </td>
9339 </tr>
9340 <tr>
9341 <td class="hdlist1">
9342 <em><strong>BO</strong></em> is <code>"little-endian"</code>
9343 </td>
9344 <td class="hdlist2">
9345 <p><em><strong>L</strong></em>&#160;âˆ’&#160;<em><strong>I</strong></em>&#160;âˆ’&#160;1</p>
9346 </td>
9347 </tr>
9348 </table>
9349 </div>
9350 </li>
9351 <li>
9352 <p>Set the element at the index&#160;<em><strong>VI</strong></em> of&#160;<em><strong>V</strong></em>
9353 to the current <a href="#fl-ba-field-dec-bit">single bit value</a>.</p>
9354 </li>
9355 <li>
9356 <p>Set <em><strong>I</strong></em> to <em><strong>I</strong></em>&#160;+&#160;1.</p>
9357 </li>
9358 <li>
9359 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;1.</p>
9360 </li>
9361 </ol>
9362 </div>
9363 </li>
9364 <li>
9365 <p>Set <em><strong>LAST_BO</strong></em> to&#160;<em><strong>BO</strong></em>.</p>
9366 </li>
9367 </ol>
9368 </div>
9369 <div class="paragraph">
9370 <p><em><strong>V</strong></em> is the decoded bit array value.</p>
9371 </div>
9372 <div class="paragraph">
9373 <p>To add to the decoding procedure above, note that the &#8220;reading
9374 direction&#8221; within a byte depends on&#160;<em><strong>BO</strong></em>. Assuming
9375 <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;0, the following diagrams show which
9376 bit is selected by <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em> within a 16-bit fixed-length bit array field
9377 depending on&#160;<em><strong>BO</strong></em>:</p>
9378 </div>
9379 <div class="dlist">
9380 <dl>
9381 <dt class="hdlist1"><code>"big-endian"</code></dt>
9382 <dd>
9383 <p></p>
9384 <div class="imageblock">
9385 <div class="content">
9386 <img src="CTF2-SPECRC-3.0-images/bit-array-decoding-be.svg" alt="bit array decoding be">
9387 </div>
9388 </div>
9389 </dd>
9390 <dt class="hdlist1"><code>"little-endian"</code></dt>
9391 <dd>
9392 <p></p>
9393 <div class="imageblock">
9394 <div class="content">
9395 <img src="CTF2-SPECRC-3.0-images/bit-array-decoding-le.svg" alt="bit array decoding le">
9396 </div>
9397 </div>
9398 </dd>
9399 </dl>
9400 </div>
9401 <div class="exampleblock">
9402 <div class="title">Example 86. Contiguous fixed-length bit array fields: big-endian versus little-endian.</div>
9403 <div class="content">
9404 <div class="paragraph">
9405 <p>This example shows the binary layout of contiguous big-endian and
9406 little-endian fixed-length bit array fields.</p>
9407 </div>
9408 <div class="paragraph">
9409 <p>Assume that <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;16. All the fixed-length bit array
9410 fields of this example have an implicit 1-bit <a href="#align-dec">aligment
9411 requirement</a>.</p>
9412 </div>
9413 <div class="paragraph">
9414 <p>Considering the following <a href="#struct-member-cls">member classes</a> of some
9415 <a href="#struct-fc">structure field class</a>:</p>
9416 </div>
9417 <div class="listingblock">
9418 <div class="content">
9419 <pre class="highlight"><code class="language-json" data-lang="json">[
9420   {
9421     "name": "green",
9422     "field-class": {
9423       "type": "fixed-length-bit-array",
9424       "length": 3,
9425       "byte-order": "big-endian"
9426     }
9427   },
9428   {
9429     "name": "blue",
9430     "field-class": {
9431       "type": "fixed-length-bit-array",
9432       "length": 9,
9433       "byte-order": "big-endian"
9434     }
9435   },
9436   {
9437     "name": "yellow",
9438     "field-class": {
9439       "type": "fixed-length-bit-array",
9440       "length": 14,
9441       "byte-order": "big-endian"
9442     }
9443   },
9444   {
9445     "name": "red",
9446     "field-class": {
9447       "type": "fixed-length-bit-array",
9448       "length": 4,
9449       "byte-order": "big-endian"
9450     }
9451   }
9452 ]</code></pre>
9453 </div>
9454 </div>
9455 <div class="paragraph">
9456 <p>The binary layout is as such:</p>
9457 </div>
9458 <div class="imageblock">
9459 <div class="content">
9460 <img src="CTF2-SPECRC-3.0-images/bit-array-fields-be.svg" alt="bit array fields be">
9461 </div>
9462 </div>
9463 <div class="paragraph">
9464 <p>Considering the following member classes of some structure field class,
9465 the only difference with the previous sample being the values of the
9466 <code>byte-order</code> property:</p>
9467 </div>
9468 <div class="listingblock">
9469 <div class="content">
9470 <pre class="highlight"><code class="language-json" data-lang="json">[
9471   {
9472     "name": "green",
9473     "field-class": {
9474       "type": "fixed-length-bit-array",
9475       "length": 3,
9476       "byte-order": "little-endian"
9477     }
9478   },
9479   {
9480     "name": "blue",
9481     "field-class": {
9482       "type": "fixed-length-bit-array",
9483       "length": 9,
9484       "byte-order": "little-endian"
9485     }
9486   },
9487   {
9488     "name": "yellow",
9489     "field-class": {
9490       "type": "fixed-length-bit-array",
9491       "length": 14,
9492       "byte-order": "little-endian"
9493     }
9494   },
9495   {
9496     "name": "red",
9497     "field-class": {
9498       "type": "fixed-length-bit-array",
9499       "length": 4,
9500       "byte-order": "little-endian"
9501     }
9502   }
9503 ]</code></pre>
9504 </div>
9505 </div>
9506 <div class="paragraph">
9507 <p>The binary layout is as such:</p>
9508 </div>
9509 <div class="imageblock">
9510 <div class="content">
9511 <img src="CTF2-SPECRC-3.0-images/bit-array-fields-le.svg" alt="bit array fields le">
9512 </div>
9513 </div>
9514 </div>
9515 </div>
9516 <div class="exampleblock">
9517 <div class="title">Example 87. Padding between fixed-length bit array fields.</div>
9518 <div class="content">
9519 <div class="paragraph">
9520 <p>This example shows how the <a href="#align-dec">alignment requirement</a> of a
9521 fixed-length bit array field can translate into padding bits to skip during the
9522 decoding process.</p>
9523 </div>
9524 <div class="paragraph">
9525 <p>Assume that <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;32.</p>
9526 </div>
9527 <div class="paragraph">
9528 <p>Considering the following <a href="#struct-member-cls">member classes</a> of some
9529 <a href="#struct-fc">structure field class</a>:</p>
9530 </div>
9531 <div class="listingblock">
9532 <div class="content">
9533 <pre class="highlight"><code class="language-json" data-lang="json">[
9534   {
9535     "name": "green",
9536     "field-class": {
9537       "type": "fixed-length-bit-array",
9538       "length": 5,
9539       "byte-order": "big-endian"
9540     }
9541   },
9542   {
9543     "name": "blue",
9544     "field-class": {
9545       "type": "fixed-length-bit-array",
9546       "length": 3,
9547       "byte-order": "big-endian",
9548       "alignment": 8
9549     }
9550   },
9551   {
9552     "name": "yellow",
9553     "field-class": {
9554       "type": "fixed-length-bit-array",
9555       "length": 4,
9556       "byte-order": "big-endian",
9557       "alignment": 4
9558     }
9559   }
9560 ]</code></pre>
9561 </div>
9562 </div>
9563 <div class="paragraph">
9564 <p>The binary layout is as such:</p>
9565 </div>
9566 <div class="imageblock">
9567 <div class="content">
9568 <img src="CTF2-SPECRC-3.0-images/bit-array-fields-padding-be.svg" alt="bit array fields padding be">
9569 </div>
9570 </div>
9571 <div class="paragraph">
9572 <p>Considering the following member classes of some structure field class,
9573 the only difference with the previous sample being the values of the
9574 <code>byte-order</code> property:</p>
9575 </div>
9576 <div class="listingblock">
9577 <div class="content">
9578 <pre class="highlight"><code class="language-json" data-lang="json">[
9579   {
9580     "name": "green",
9581     "field-class": {
9582       "type": "fixed-length-bit-array",
9583       "length": 5,
9584       "byte-order": "little-endian"
9585     }
9586   },
9587   {
9588     "name": "blue",
9589     "field-class": {
9590       "type": "fixed-length-bit-array",
9591       "length": 3,
9592       "byte-order": "little-endian",
9593       "alignment": 8
9594     }
9595   },
9596   {
9597     "name": "yellow",
9598     "field-class": {
9599       "type": "fixed-length-bit-array",
9600       "length": 4,
9601       "byte-order": "little-endian",
9602       "alignment": 4
9603     }
9604   }
9605 ]</code></pre>
9606 </div>
9607 </div>
9608 <div class="paragraph">
9609 <p>The binary layout is as such:</p>
9610 </div>
9611 <div class="imageblock">
9612 <div class="content">
9613 <img src="CTF2-SPECRC-3.0-images/bit-array-fields-padding-le.svg" alt="bit array fields padding le">
9614 </div>
9615 </div>
9616 </div>
9617 </div>
9618 <div class="exampleblock">
9619 <div class="title">Example 88. Contiguous fixed-length bit array fields with different byte orders.</div>
9620 <div class="content">
9621 <div class="paragraph">
9622 <p><a href="#fl-ba-field-dec-step-3">Step&#160;3</a> of the decoding procedure above
9623 requires that a <a href="#consumer-def">consumer</a> stops the data stream decoding
9624 process if the byte order between two contiguous fixed-length bit array fields changes
9625 when&#160;<em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em> is not a mutliple of&#160;8.</p>
9626 </div>
9627 <div class="paragraph">
9628 <p>In other words, a given data stream <a href="#byte-def">byte</a> <em>MUST&#160;NOT</em> contain
9629 bits of two fixed-length bit array fields having different byte orders.</p>
9630 </div>
9631 <div class="paragraph">
9632 <p>This example shows how contiguous fixed-length bit array fields may have different byte
9633 orders with correct <a href="#align-dec">alignment</a>.</p>
9634 </div>
9635 <div class="paragraph">
9636 <p>Assume that <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;16.</p>
9637 </div>
9638 <div class="paragraph">
9639 <p>Considering the following <a href="#struct-member-cls">member classes</a> of some
9640 <a href="#struct-fc">structure field class</a>:</p>
9641 </div>
9642 <div class="listingblock">
9643 <div class="content">
9644 <pre class="highlight"><code class="language-json" data-lang="json">[
9645   {
9646     "name": "green",
9647     "field-class": {
9648       "type": "fixed-length-bit-array",
9649       "length": 3,
9650       "byte-order": "big-endian"
9651     }
9652   },
9653   {
9654     "name": "blue",
9655     "field-class": {
9656       "type": "fixed-length-bit-array",
9657       "length": 5,
9658       "byte-order": "big-endian"
9659     }
9660   },
9661   {
9662     "name": "yellow",
9663     "field-class": {
9664       "type": "fixed-length-bit-array",
9665       "length": 5,
9666       "byte-order": "little-endian"
9667     }
9668   },
9669   {
9670     "name": "orange",
9671     "field-class": {
9672       "type": "fixed-length-bit-array",
9673       "length": 8,
9674       "byte-order": "little-endian"
9675     }
9676   },
9677   {
9678     "name": "red",
9679     "field-class": {
9680       "type": "fixed-length-bit-array",
9681       "length": 6,
9682       "byte-order": "big-endian",
9683       "alignment": 8
9684     }
9685   }
9686 ]</code></pre>
9687 </div>
9688 </div>
9689 <div class="paragraph">
9690 <p>The binary layout is as such:</p>
9691 </div>
9692 <div class="imageblock">
9693 <div class="content">
9694 <img src="CTF2-SPECRC-3.0-images/bit-array-fields-be-le.svg" alt="bit array fields be le">
9695 </div>
9696 </div>
9697 </div>
9698 </div>
9699 </div>
9700 <div class="sect3">
9701 <h4 id="fl-bool-field-dec">6.3.4. Fixed-length boolean field decoding procedure</h4>
9702 <div class="paragraph">
9703 <p>To decode an instance of a <a href="#fl-bool-fc">fixed-length boolean field class</a>:</p>
9704 </div>
9705 <div class="olist arabic">
9706 <ol class="arabic">
9707 <li>
9708 <p>Let <em><strong>VB</strong></em> be a boolean.</p>
9709 </li>
9710 <li>
9711 <p><a href="#fl-ba-field-dec">Decode the instance as a fixed-length bit array field</a>.</p>
9712 </li>
9713 <li>
9714 <p>If all the elements of&#160;<em><strong>V</strong></em> are <em>false</em>, then set&#160;<em><strong>VB</strong></em>
9715 to <em>false</em>.</p>
9716 <div class="paragraph">
9717 <p>Else, set <em><strong>VB</strong></em> to <em>true</em>.</p>
9718 </div>
9719 </li>
9720 </ol>
9721 </div>
9722 <div class="paragraph">
9723 <p><em><strong>VB</strong></em> is the decoded boolean value.</p>
9724 </div>
9725 </div>
9726 <div class="sect3">
9727 <h4 id="fl-uint-field-dec">6.3.5. Fixed-length unsigned integer field decoding procedure</h4>
9728 <div class="paragraph">
9729 <p>To decode an instance of a <a href="#fl-int-fc">fixed-length unsigned integer field class</a>:</p>
9730 </div>
9731 <div class="olist arabic">
9732 <ol class="arabic">
9733 <li>
9734 <p>Let <em><strong>VI</strong></em> be an unsigned integer.</p>
9735 </li>
9736 <li>
9737 <p><a href="#fl-ba-field-dec">Decode the instance as a fixed-length bit array field</a>.</p>
9738 </li>
9739 <li>
9740 <p>Set <em><strong>VI</strong></em> as the unsigned integer interpretation
9741 of&#160;<em><strong>V</strong></em>, where the first element of&#160;<em><strong>V</strong></em> is the most
9742 significant bit.</p>
9743 </li>
9744 </ol>
9745 </div>
9746 <div class="paragraph">
9747 <p><em><strong>VI</strong></em> is the decoded unsigned integer value.</p>
9748 </div>
9749 </div>
9750 <div class="sect3">
9751 <h4 id="fl-sint-field-dec">6.3.6. Fixed-length signed integer field decoding procedure</h4>
9752 <div class="paragraph">
9753 <p>To decode an instance of a <a href="#fl-int-fc">fixed-length signed integer field class</a>:</p>
9754 </div>
9755 <div class="olist arabic">
9756 <ol class="arabic">
9757 <li>
9758 <p>Let <em><strong>VI</strong></em> be a signed integer.</p>
9759 </li>
9760 <li>
9761 <p><a href="#fl-ba-field-dec">Decode the instance as a fixed-length bit array field</a>.</p>
9762 </li>
9763 <li>
9764 <p>Set <em><strong>VI</strong></em> as the signed integer interpretation, following the
9765 two&#8217;s complement format, of&#160;<em><strong>V</strong></em>, where the first element
9766 of&#160;<em><strong>V</strong></em> is the most significant bit.</p>
9767 </li>
9768 </ol>
9769 </div>
9770 <div class="paragraph">
9771 <p><em><strong>VI</strong></em> is the decoded signed integer value.</p>
9772 </div>
9773 </div>
9774 <div class="sect3">
9775 <h4 id="fl-fp-field-dec">6.3.7. Fixed-length floating point number field decoding procedure</h4>
9776 <div class="paragraph">
9777 <p>To decode an instance of a <a href="#fl-fp-fc">fixed-length floating point number field class</a>:</p>
9778 </div>
9779 <div class="olist arabic">
9780 <ol class="arabic">
9781 <li>
9782 <p>Let <em><strong>VR</strong></em> be a real value.</p>
9783 </li>
9784 <li>
9785 <p><a href="#fl-ba-field-dec">Decode the instance as a fixed-length bit array field</a>.</p>
9786 </li>
9787 <li>
9788 <p>Set <em><strong>VR</strong></em> to the real number interpretation, following the
9789 <a href="https://standards.ieee.org/standard/754-2008.html">IEEE 754-2008</a> binary interchange format, of&#160;<em><strong>V</strong></em>, where the first element of&#160;<em><strong>V</strong></em> is
9790 the most significant bit.</p>
9791 </li>
9792 </ol>
9793 </div>
9794 <div class="paragraph">
9795 <p><em><strong>VR</strong></em> is the decoded real value.</p>
9796 </div>
9797 </div>
9798 <div class="sect3">
9799 <h4 id="vl-ba-field-dec">6.3.8. Variable-length bit array field decoding procedure</h4>
9800 <div class="paragraph">
9801 <p>To decode an instance of a <a href="#vl-ba-fc">variable-length bit array field class</a>&#160;<em><strong>F</strong></em>:</p>
9802 </div>
9803 <div class="olist arabic">
9804 <ol class="arabic">
9805 <li>
9806 <p>Let <em><strong>V</strong></em> be an empty array of booleans.</p>
9807 </li>
9808 <li>
9809 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
9810 to&#160;<em><strong>F</strong></em>.</p>
9811 </li>
9812 <li>
9813 <p>Read <em><strong>N</strong></em>&#160;bytes of data from&#160;<em><strong>S</strong></em> at the
9814 offset&#160;<em><strong>O</strong></em>, as many as needed following the unsigned
9815 <a href="https://en.wikipedia.org/wiki/LEB128">LEB128</a> format, appending the
9816 decoded bits to&#160;<em><strong>V</strong></em> as booleans from the most
9817 significant to the least significant.</p>
9818 </li>
9819 <li>
9820 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;<em><strong>N</strong></em>&#160;Ã—&#160;8.</p>
9821 </li>
9822 </ol>
9823 </div>
9824 <div class="paragraph">
9825 <p><em><strong>V</strong></em> is the decoded value.</p>
9826 </div>
9827 <div class="exampleblock">
9828 <div class="title">Example 89. 3-byte variable-length bit array field decoding.</div>
9829 <div class="content">
9830 <div class="paragraph">
9831 <p>Consider the following <a href="#vl-ba-fc">variable-length bit array field class</a>&#160;<em><strong>F</strong></em>:</p>
9832 </div>
9833 <div class="listingblock">
9834 <div class="content">
9835 <pre class="highlight"><code class="language-json" data-lang="json">{
9836   "type": "variable-length-bit-array"
9837 }</code></pre>
9838 </div>
9839 </div>
9840 <div class="paragraph">
9841 <p>The following diagram shows the three bytes of an instance
9842 of&#160;<em><strong>F</strong></em> and the resulting bit array value.</p>
9843 </div>
9844 <div class="imageblock">
9845 <div class="content">
9846 <img src="CTF2-SPECRC-3.0-images/vl-ba.svg" alt="vl ba">
9847 </div>
9848 </div>
9849 <div class="paragraph">
9850 <p>Note that the data bits of the last byte (in red) become the first
9851 elements of the resulting bit array value because LEB128 is a
9852 little-endian encoding.</p>
9853 </div>
9854 </div>
9855 </div>
9856 </div>
9857 <div class="sect3">
9858 <h4 id="vl-uint-field-dec">6.3.9. Variable-length unsigned integer field decoding procedure</h4>
9859 <div class="paragraph">
9860 <p>To decode an instance of a <a href="#vl-int-fc">variable-length unsigned integer field class</a>:</p>
9861 </div>
9862 <div class="olist arabic">
9863 <ol class="arabic">
9864 <li>
9865 <p>Let <em><strong>VI</strong></em> be an unsigned integer.</p>
9866 </li>
9867 <li>
9868 <p><a href="#vl-ba-field-dec">Decode the instance as a variable-length bit array field</a>.</p>
9869 </li>
9870 <li>
9871 <p>Set <em><strong>VI</strong></em> as the unsigned integer interpretation of&#160;<em><strong>V</strong></em>,
9872 where the first element of&#160;<em><strong>V</strong></em> is the most significant bit.</p>
9873 </li>
9874 </ol>
9875 </div>
9876 <div class="paragraph">
9877 <p><em><strong>VI</strong></em> is the decoded unsigned integer value.</p>
9878 </div>
9879 </div>
9880 <div class="sect3">
9881 <h4 id="vl-sint-field-dec">6.3.10. Variable-length signed integer field decoding procedure</h4>
9882 <div class="paragraph">
9883 <p>To decode an instance of a <a href="#vl-int-fc">variable-length signed integer field class</a>:</p>
9884 </div>
9885 <div class="olist arabic">
9886 <ol class="arabic">
9887 <li>
9888 <p>Let <em><strong>VI</strong></em> be a signed integer.</p>
9889 </li>
9890 <li>
9891 <p><a href="#vl-ba-field-dec">Decode the instance as a variable-length bit array field</a>.</p>
9892 </li>
9893 <li>
9894 <p>Set <em><strong>VI</strong></em> as the signed integer interpretation, following the
9895 two&#8217;s complement format, of&#160;<em><strong>V</strong></em>, where the first element
9896 of&#160;<em><strong>V</strong></em> is the most significant bit.</p>
9897 </li>
9898 </ol>
9899 </div>
9900 <div class="paragraph">
9901 <p><em><strong>VI</strong></em> is the decoded signed integer value.</p>
9902 </div>
9903 </div>
9904 <div class="sect3">
9905 <h4 id="str-field-dec">6.3.11. Null-terminated string field decoding procedure</h4>
9906 <div class="paragraph">
9907 <p>To decode an instance of a <a href="#str-fc">null-terminated string field class</a>&#160;<em><strong>F</strong></em>:</p>
9908 </div>
9909 <div class="olist arabic">
9910 <ol class="arabic">
9911 <li>
9912 <p>Let:</p>
9913 <div class="ulist">
9914 <ul>
9915 <li>
9916 <p><em><strong>B</strong></em> be a byte.</p>
9917 </li>
9918 <li>
9919 <p><em><strong>A</strong></em> be an empty sequence of bytes.</p>
9920 </li>
9921 <li>
9922 <p><em><strong>V</strong></em> be a string.</p>
9923 </li>
9924 </ul>
9925 </div>
9926 </li>
9927 <li>
9928 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
9929 to&#160;<em><strong>F</strong></em>.</p>
9930 </li>
9931 <li>
9932 <p>Read one byte of data from&#160;<em><strong>S</strong></em> at the offset&#160;<em><strong>O</strong></em>
9933 as&#160;<em><strong>B</strong></em>.</p>
9934 </li>
9935 <li>
9936 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;8.</p>
9937 </li>
9938 <li>
9939 <p>While <em><strong>B</strong></em>&#160;â‰&#160;0:</p>
9940 <div class="olist loweralpha">
9941 <ol class="loweralpha" type="a">
9942 <li>
9943 <p>Append <em><strong>B</strong></em> to&#160;<em><strong>A</strong></em>.</p>
9944 </li>
9945 <li>
9946 <p>Read one byte of data from&#160;<em><strong>S</strong></em> at the
9947 offset&#160;<em><strong>O</strong></em> as&#160;<em><strong>B</strong></em>.</p>
9948 </li>
9949 <li>
9950 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;8.</p>
9951 </li>
9952 </ol>
9953 </div>
9954 </li>
9955 <li>
9956 <p>Decode <em><strong>A</strong></em>, following UTF-8, as <em><strong>V</strong></em>.</p>
9957 </li>
9958 </ol>
9959 </div>
9960 <div class="paragraph">
9961 <p><em><strong>V</strong></em> is the decoded string value.</p>
9962 </div>
9963 <div class="exampleblock">
9964 <div class="title">Example 90. 22-byte null-terminated string field decoding.</div>
9965 <div class="content">
9966 <div class="paragraph">
9967 <p>Consider the following <a href="#str-fc">null-terminated string field class</a>&#160;<em><strong>F</strong></em>:</p>
9968 </div>
9969 <div class="listingblock">
9970 <div class="content">
9971 <pre class="highlight"><code class="language-json" data-lang="json">{
9972   "type": "null-terminated-string"
9973 }</code></pre>
9974 </div>
9975 </div>
9976 <div class="paragraph">
9977 <p>The following diagram shows <a href="#pkt">packet</a> bytes including a 22-byte
9978 instance of&#160;<em><strong>F</strong></em> (in blue) and its resulting string value.</p>
9979 </div>
9980 <div class="paragraph">
9981 <p>The offset of the null-terminated string field, from the beginning of the packet,
9982 is 0xfc23&#160;bytes, which means
9983 <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;516,376.</p>
9984 </div>
9985 <div class="imageblock">
9986 <div class="content">
9987 <img src="CTF2-SPECRC-3.0-images/str.svg" alt="str">
9988 </div>
9989 </div>
9990 <div class="paragraph">
9991 <p>The field contains 21&#160;UTF-8 bytes and a null terminating byte.</p>
9992 </div>
9993 <div class="paragraph">
9994 <p>The resulting string value contains 19&#160;Unicode characters.</p>
9995 </div>
9996 <div class="paragraph">
9997 <p>After the field is decoded, <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;516,552.</p>
9998 </div>
9999 </div>
10000 </div>
10001 </div>
10002 <div class="sect3">
10003 <h4 id="sl-str-field-dec">6.3.12. Static-length string field decoding procedure</h4>
10004 <div class="paragraph">
10005 <p>To decode an instance of a <a href="#sl-str-fc">static-length string field class</a>&#160;<em><strong>F</strong></em>:</p>
10006 </div>
10007 <div class="olist arabic">
10008 <ol class="arabic">
10009 <li>
10010 <p>Let:</p>
10011 <div class="ulist">
10012 <ul>
10013 <li>
10014 <p><em><strong>L</strong></em> be the <code>length</code> property of&#160;<em><strong>F</strong></em>.</p>
10015 </li>
10016 <li>
10017 <p><em><strong>I</strong></em> be an unsigned integer initialized to 0.</p>
10018 </li>
10019 <li>
10020 <p><em><strong>B</strong></em> be a byte.</p>
10021 </li>
10022 <li>
10023 <p><em><strong>R</strong></em> be a boolean initialized to <em>true</em>.</p>
10024 </li>
10025 <li>
10026 <p><em><strong>A</strong></em> be an empty sequence of bytes.</p>
10027 </li>
10028 <li>
10029 <p><em><strong>V</strong></em> be a string.</p>
10030 </li>
10031 </ul>
10032 </div>
10033 </li>
10034 <li>
10035 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10036 to&#160;<em><strong>F</strong></em>.</p>
10037 </li>
10038 <li>
10039 <p>While <em><strong>I</strong></em>&#160;&lt;&#160;<em><strong>L</strong></em>:</p>
10040 <div class="olist loweralpha">
10041 <ol class="loweralpha" type="a">
10042 <li>
10043 <p>Read one byte of data from&#160;<em><strong>S</strong></em> at the
10044 offset&#160;<em><strong>O</strong></em> as&#160;<em><strong>B</strong></em>.</p>
10045 </li>
10046 <li>
10047 <p>If <em><strong>B</strong></em>&#160;=&#160;0, then set <em><strong>R</strong></em>&#160;to <em>false</em>.</p>
10048 <div class="paragraph">
10049 <p>Else, if <em><strong>R</strong></em> is <em>true</em>, then append&#160;<em><strong>B</strong></em>
10050 to&#160;<em><strong>A</strong></em>.</p>
10051 </div>
10052 </li>
10053 <li>
10054 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;8.</p>
10055 </li>
10056 <li>
10057 <p>Set <em><strong>I</strong></em> to <em><strong>I</strong></em>&#160;+&#160;1.</p>
10058 </li>
10059 </ol>
10060 </div>
10061 </li>
10062 <li>
10063 <p>Decode <em><strong>A</strong></em>, following UTF-8, as <em><strong>V</strong></em>.</p>
10064 </li>
10065 </ol>
10066 </div>
10067 <div class="paragraph">
10068 <p><em><strong>V</strong></em> is the decoded string value.</p>
10069 </div>
10070 <div class="exampleblock">
10071 <div class="title">Example 91. 18-byte static-length string field decoding.</div>
10072 <div class="content">
10073 <div class="paragraph">
10074 <p>Consider the following <a href="#str-fc">null-terminated string field class</a>&#160;<em><strong>F</strong></em>:</p>
10075 </div>
10076 <div class="listingblock">
10077 <div class="content">
10078 <pre class="highlight"><code class="language-json" data-lang="json">{
10079   "type": "static-length-string",
10080   "length": 18
10081 }</code></pre>
10082 </div>
10083 </div>
10084 <div class="paragraph">
10085 <p>The following diagram shows <a href="#pkt">packet</a> bytes including a 18-byte
10086 instance of&#160;<em><strong>F</strong></em> (in green) and its resulting string value.</p>
10087 </div>
10088 <div class="paragraph">
10089 <p>The offset of the static-length string field, from the beginning of the packet, is
10090 0x8c46&#160;bytes, which means <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;287,280.</p>
10091 </div>
10092 <div class="imageblock">
10093 <div class="content">
10094 <img src="CTF2-SPECRC-3.0-images/sl-str.svg" alt="sl str">
10095 </div>
10096 </div>
10097 <div class="paragraph">
10098 <p>The field contains 14&#160;UTF-8 bytes, a null terminating byte,
10099 and three garbage data bytes to ignore.</p>
10100 </div>
10101 <div class="paragraph">
10102 <p>The resulting string value contains seven Unicode characters.</p>
10103 </div>
10104 <div class="paragraph">
10105 <p>After the field is decoded, <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;287,424.</p>
10106 </div>
10107 </div>
10108 </div>
10109 </div>
10110 <div class="sect3">
10111 <h4 id="sl-blob-field-dec">6.3.13. Static-length BLOB field decoding procedure</h4>
10112 <div class="paragraph">
10113 <p>To decode an instance of a <a href="#sl-blob-fc">static-length BLOB field class</a>&#160;<em><strong>F</strong></em>:</p>
10114 </div>
10115 <div class="olist arabic">
10116 <ol class="arabic">
10117 <li>
10118 <p>Let:</p>
10119 <div class="olist loweralpha">
10120 <ol class="loweralpha" type="a">
10121 <li>
10122 <p><em><strong>L</strong></em> be the <code>length</code> property of&#160;<em><strong>F</strong></em>.</p>
10123 </li>
10124 <li>
10125 <p><em><strong>V</strong></em> be an array of bytes of length&#160;<em><strong>L</strong></em>.</p>
10126 </li>
10127 </ol>
10128 </div>
10129 </li>
10130 <li>
10131 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10132 to&#160;<em><strong>F</strong></em>.</p>
10133 </li>
10134 <li>
10135 <p>Read <em><strong>L</strong></em> bytes of data from&#160;<em><strong>S</strong></em> at the
10136 offset&#160;<em><strong>O</strong></em> as&#160;<em><strong>V</strong></em>.</p>
10137 </li>
10138 <li>
10139 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;<em><strong>L</strong></em>&#160;Ã—&#160;8.</p>
10140 </li>
10141 </ol>
10142 </div>
10143 <div class="paragraph">
10144 <p><em><strong>V</strong></em> is the decoded BLOB value.</p>
10145 </div>
10146 </div>
10147 <div class="sect3">
10148 <h4 id="dl-str-field-dec">6.3.14. Dynamic-length string field decoding procedure</h4>
10149 <div class="paragraph">
10150 <p>To decode an instance of a <a href="#dl-str-fc">dynamic-length string field class</a>&#160;<em><strong>F</strong></em>:</p>
10151 </div>
10152 <div class="olist arabic">
10153 <ol class="arabic">
10154 <li>
10155 <p>Let:</p>
10156 <div class="ulist">
10157 <ul>
10158 <li>
10159 <p><em><strong>L</strong></em> be the value of the previously decoded unsigned integer
10160 field of which the <code>length-field-location</code> property of&#160;<em><strong>F</strong></em>
10161 indicates the <a href="#field-loc-dec">location</a>.</p>
10162 </li>
10163 <li>
10164 <p><em><strong>I</strong></em> be an unsigned integer initialized to 0.</p>
10165 </li>
10166 <li>
10167 <p><em><strong>B</strong></em> be a byte.</p>
10168 </li>
10169 <li>
10170 <p><em><strong>R</strong></em> be a boolean initialized to <em>true</em>.</p>
10171 </li>
10172 <li>
10173 <p><em><strong>A</strong></em> be an empty sequence of bytes.</p>
10174 </li>
10175 <li>
10176 <p><em><strong>V</strong></em> be a string.</p>
10177 </li>
10178 </ul>
10179 </div>
10180 </li>
10181 <li>
10182 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10183 to&#160;<em><strong>F</strong></em>.</p>
10184 </li>
10185 <li>
10186 <p>While <em><strong>I</strong></em>&#160;&lt;&#160;<em><strong>L</strong></em>:</p>
10187 <div class="olist loweralpha">
10188 <ol class="loweralpha" type="a">
10189 <li>
10190 <p>Read one byte of data from&#160;<em><strong>S</strong></em> at the
10191 offset&#160;<em><strong>O</strong></em> as&#160;<em><strong>B</strong></em>.</p>
10192 </li>
10193 <li>
10194 <p>If <em><strong>B</strong></em>&#160;=&#160;0, then set <em><strong>R</strong></em>&#160;to <em>false</em>.</p>
10195 <div class="paragraph">
10196 <p>Else, if <em><strong>R</strong></em> is <em>true</em>, then append&#160;<em><strong>B</strong></em>
10197 to&#160;<em><strong>A</strong></em>.</p>
10198 </div>
10199 </li>
10200 <li>
10201 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;8.</p>
10202 </li>
10203 <li>
10204 <p>Set <em><strong>I</strong></em> to <em><strong>I</strong></em>&#160;+&#160;1.</p>
10205 </li>
10206 </ol>
10207 </div>
10208 </li>
10209 <li>
10210 <p>Decode <em><strong>A</strong></em>, following UTF-8, as <em><strong>V</strong></em>.</p>
10211 </li>
10212 </ol>
10213 </div>
10214 <div class="paragraph">
10215 <p><em><strong>V</strong></em> is the decoded string value.</p>
10216 </div>
10217 </div>
10218 <div class="sect3">
10219 <h4 id="dl-blob-field-dec">6.3.15. Dynamic-length BLOB field decoding procedure</h4>
10220 <div class="paragraph">
10221 <p>To decode an instance of a <a href="#dl-blob-fc">dynamic-length BLOB field class</a>&#160;<em><strong>F</strong></em>:</p>
10222 </div>
10223 <div class="olist arabic">
10224 <ol class="arabic">
10225 <li>
10226 <p>Let:</p>
10227 <div class="olist loweralpha">
10228 <ol class="loweralpha" type="a">
10229 <li>
10230 <p><em><strong>L</strong></em> be the value of the previously decoded unsigned integer
10231 field of which the <code>length-field-location</code> property of&#160;<em><strong>F</strong></em>
10232 indicates the <a href="#field-loc-dec">location</a>.</p>
10233 </li>
10234 <li>
10235 <p><em><strong>V</strong></em> be an array of bytes of length&#160;<em><strong>L</strong></em>.</p>
10236 </li>
10237 </ol>
10238 </div>
10239 </li>
10240 <li>
10241 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10242 to&#160;<em><strong>F</strong></em>.</p>
10243 </li>
10244 <li>
10245 <p>Read <em><strong>L</strong></em> bytes of data from&#160;<em><strong>S</strong></em> at the
10246 offset&#160;<em><strong>O</strong></em> as&#160;<em><strong>V</strong></em>.</p>
10247 </li>
10248 <li>
10249 <p>Set <em><strong>O</strong></em> to <em><strong>O</strong></em>&#160;+&#160;<em><strong>L</strong></em>&#160;Ã—&#160;8.</p>
10250 </li>
10251 </ol>
10252 </div>
10253 <div class="paragraph">
10254 <p><em><strong>V</strong></em> is the decoded BLOB value.</p>
10255 </div>
10256 </div>
10257 <div class="sect3">
10258 <h4 id="struct-field-dec">6.3.16. Structure field decoding procedure</h4>
10259 <div class="paragraph">
10260 <p>To decode an instance of a <a href="#struct-fc">structure field class</a>&#160;<em><strong>F</strong></em>:</p>
10261 </div>
10262 <div class="olist arabic">
10263 <ol class="arabic">
10264 <li>
10265 <p>Let:</p>
10266 <div class="ulist">
10267 <ul>
10268 <li>
10269 <p><em><strong>M</strong></em> be the <code>member-classes</code> property of&#160;<em><strong>F</strong></em>.</p>
10270 </li>
10271 <li>
10272 <p><em><strong>V</strong></em> be an empty structure.</p>
10273 </li>
10274 </ul>
10275 </div>
10276 </li>
10277 <li>
10278 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10279 to&#160;<em><strong>F</strong></em>.</p>
10280 </li>
10281 <li>
10282 <p>For each member class&#160;<em><strong>MC</strong></em> of&#160;<em><strong>M</strong></em>:</p>
10283 <div class="olist loweralpha">
10284 <ol class="loweralpha" type="a">
10285 <li>
10286 <p>Let:</p>
10287 <div class="ulist">
10288 <ul>
10289 <li>
10290 <p><em><strong>MF</strong></em> be the <code>field-class</code> property of&#160;<em><strong>MC</strong></em>.</p>
10291 </li>
10292 <li>
10293 <p><em><strong>MN</strong></em> be the <code>name</code> property of&#160;<em><strong>MC</strong></em>.</p>
10294 </li>
10295 </ul>
10296 </div>
10297 </li>
10298 <li>
10299 <p><a href="#field-dec">Decode</a> one instance of&#160;<em><strong>MF</strong></em>, appending the
10300 resulting value as a member of&#160;<em><strong>V</strong></em> named&#160;<em><strong>MN</strong></em>.</p>
10301 </li>
10302 </ol>
10303 </div>
10304 </li>
10305 </ol>
10306 </div>
10307 <div class="paragraph">
10308 <p><em><strong>V</strong></em> is the decoded value.</p>
10309 </div>
10310 </div>
10311 <div class="sect3">
10312 <h4 id="sl-array-field-dec">6.3.17. Static-length array field decoding procedure</h4>
10313 <div class="paragraph">
10314 <p>To decode an instance of a <a href="#sl-array-fc">static-length array field class</a>&#160;<em><strong>F</strong></em>:</p>
10315 </div>
10316 <div class="olist arabic">
10317 <ol class="arabic">
10318 <li>
10319 <p>Let:</p>
10320 <div class="olist loweralpha">
10321 <ol class="loweralpha" type="a">
10322 <li>
10323 <p><em><strong>L</strong></em> be the <code>length</code> property of&#160;<em><strong>F</strong></em>.</p>
10324 </li>
10325 <li>
10326 <p><em><strong>EF</strong></em> be the <code>element-field-class</code> property of&#160;<em><strong>F</strong></em>.</p>
10327 </li>
10328 <li>
10329 <p><em><strong>I</strong></em> be an unsigned integer initialized to 0.</p>
10330 </li>
10331 <li>
10332 <p><em><strong>V</strong></em> be an array of values of length&#160;<em><strong>L</strong></em>.</p>
10333 </li>
10334 </ol>
10335 </div>
10336 </li>
10337 <li>
10338 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10339 to&#160;<em><strong>F</strong></em>.</p>
10340 </li>
10341 <li>
10342 <p>While <em><strong>I</strong></em>&#160;&lt;&#160;<em><strong>L</strong></em>:</p>
10343 <div class="olist loweralpha">
10344 <ol class="loweralpha" type="a">
10345 <li>
10346 <p><a href="#field-dec">Decode</a> one instance of&#160;<em><strong>EF</strong></em>
10347 as element&#160;<em><strong>I</strong></em> of&#160;<em><strong>V</strong></em>.</p>
10348 </li>
10349 <li>
10350 <p>Set <em><strong>I</strong></em> to <em><strong>I</strong></em>&#160;+&#160;1.</p>
10351 </li>
10352 </ol>
10353 </div>
10354 </li>
10355 </ol>
10356 </div>
10357 <div class="paragraph">
10358 <p><em><strong>V</strong></em> is the decoded value.</p>
10359 </div>
10360 </div>
10361 <div class="sect3">
10362 <h4 id="dl-array-field-dec">6.3.18. Dynamic-length array field decoding procedure</h4>
10363 <div class="paragraph">
10364 <p>To decode an instance of a <a href="#dl-array-fc">dynamic-length array field class</a>&#160;<em><strong>F</strong></em>:</p>
10365 </div>
10366 <div class="olist arabic">
10367 <ol class="arabic">
10368 <li>
10369 <p>Let:</p>
10370 <div class="olist loweralpha">
10371 <ol class="loweralpha" type="a">
10372 <li>
10373 <p><em><strong>L</strong></em> be the value of the previously decoded unsigned integer field
10374 of which the <code>length-field-location</code> property of&#160;<em><strong>F</strong></em>
10375 indicates the <a href="#field-loc-dec">location</a>.</p>
10376 </li>
10377 <li>
10378 <p><em><strong>EF</strong></em> be the <code>element-field-class</code> property of&#160;<em><strong>F</strong></em>.</p>
10379 </li>
10380 <li>
10381 <p><em><strong>I</strong></em> be an unsigned integer initialized to 0.</p>
10382 </li>
10383 <li>
10384 <p><em><strong>V</strong></em> be an array of values of length&#160;<em><strong>L</strong></em></p>
10385 </li>
10386 </ol>
10387 </div>
10388 </li>
10389 <li>
10390 <p><a href="#align-dec">Align <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em></a> according
10391 to&#160;<em><strong>F</strong></em>.</p>
10392 </li>
10393 <li>
10394 <p>While <em><strong>I</strong></em>&#160;&lt;&#160;<em><strong>L</strong></em>:</p>
10395 <div class="olist loweralpha">
10396 <ol class="loweralpha" type="a">
10397 <li>
10398 <p><a href="#field-dec">Decode</a> one instance of&#160;<em><strong>EF</strong></em>
10399 as element&#160;<em><strong>I</strong></em> of&#160;<em><strong>V</strong></em>.</p>
10400 </li>
10401 <li>
10402 <p>Set <em><strong>I</strong></em> to <em><strong>I</strong></em>&#160;+&#160;1.</p>
10403 </li>
10404 </ol>
10405 </div>
10406 </li>
10407 </ol>
10408 </div>
10409 <div class="paragraph">
10410 <p><em><strong>V</strong></em> is the decoded value.</p>
10411 </div>
10412 <div class="exampleblock">
10413 <div class="title">Example 92. 5-element dynamic-length array field decoding.</div>
10414 <div class="content">
10415 <div class="paragraph">
10416 <p>Consider the following <a href="#er-payload">event record payload</a>
10417 <a href="#struct-fc">structure field class</a>&#160;<em><strong>F</strong></em>:</p>
10418 </div>
10419 <div class="listingblock">
10420 <div class="content">
10421 <pre class="highlight"><code class="language-json" data-lang="json">{
10422   "type": "structure",
10423   "member-classes": [
10424     {
10425       "name": "len",
10426       "field-class": {
10427         "type": "fixed-length-unsigned-integer",
10428         "length": 16,
10429         "byte-order": "big-endian"
10430       }
10431     },
10432     {
10433       "name": "id",
10434       "field-class": {
10435         "type": "null-terminated-string"
10436       }
10437     },
10438     {
10439       "name": "vals",
10440       "field-class": {
10441         "type":
10442         "type": "dynamic-length-array",
10443         "length-field-location": ["event-record-payload", "len"],
10444         "element-field-class": {
10445           "type": "fixed-length-unsigned-integer",
10446           "length": 32,
10447           "byte-order": "little-endian",
10448           "alignment": 32
10449         }
10450       }
10451     }
10452   ]
10453 }</code></pre>
10454 </div>
10455 </div>
10456 <div class="paragraph">
10457 <p>The following diagram shows <a href="#pkt">packet</a> bytes including an instance
10458 of&#160;<em><strong>F</strong></em> (starting in green and ending in blue) and the resulting
10459 signed integer values of its <code>vals</code> member.</p>
10460 </div>
10461 <div class="paragraph">
10462 <p>The offset of the <code>len</code> fixed-length unsigned integer field, from the beginning of the packet, is
10463 0x42c1&#160;bytes, which means <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;136,712.</p>
10464 </div>
10465 <div class="paragraph">
10466 <p>The offset of the <code>vals</code> dynamic-length array field, from the beginning of the
10467 packet, is 0x42c8&#160;bytes, which means
10468 <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;136,768.</p>
10469 </div>
10470 <div class="imageblock">
10471 <div class="content">
10472 <img src="CTF2-SPECRC-3.0-images/dl-array.svg" alt="dl array">
10473 </div>
10474 </div>
10475 <div class="paragraph">
10476 <p>The unsigned integer value of the <code>len</code> field is&#160;5, which means the
10477 <code>vals</code> field contains five fixed-length signed integer fields.</p>
10478 </div>
10479 <div class="paragraph">
10480 <p>After the structure field is decoded,
10481 <em><strong>O</strong></em>&#160;âˆ’&#160;<em><strong>PO</strong></em>&#160;=&#160;136,928.</p>
10482 </div>
10483 </div>
10484 </div>
10485 </div>
10486 <div class="sect3">
10487 <h4 id="opt-field-dec">6.3.19. Optional field decoding procedure</h4>
10488 <div class="paragraph">
10489 <p>To decode an instance of an <a href="#opt-fc">optional field class</a>&#160;<em><strong>F</strong></em>:</p>
10490 </div>
10491 <div class="olist arabic">
10492 <ol class="arabic">
10493 <li>
10494 <p>Let:</p>
10495 <div class="ulist">
10496 <ul>
10497 <li>
10498 <p><em><strong>SEL</strong></em> be the value of the previously decoded <a href="#bool-fc">boolean</a>
10499 or <a href="#int-fc">integer</a> field of which the <code>selector-field-location</code>
10500 property of&#160;<em><strong>F</strong></em> indicates the <a href="#field-loc-dec">location</a>.</p>
10501 </li>
10502 <li>
10503 <p><em><strong>OF</strong></em> be the <code>field-class</code> property of <em><strong>F</strong></em>.</p>
10504 </li>
10505 <li>
10506 <p><em><strong>V</strong></em> be a nil value.</p>
10507 </li>
10508 </ul>
10509 </div>
10510 </li>
10511 <li>
10512 <p>If the class of&#160;<em><strong>SEL</strong></em> is a <a href="#fl-bool-fc">fixed-length boolean field class</a>
10513 and <em><strong>SEL</strong></em> is <em>true</em>, then:</p>
10514 <div class="ulist">
10515 <ul>
10516 <li>
10517 <p><a href="#field-dec">Decode</a> one instance of&#160;<em><strong>OF</strong></em>
10518 as&#160;<em><strong>V</strong></em>.</p>
10519 </li>
10520 </ul>
10521 </div>
10522 <div class="paragraph">
10523 <p>Else, if <em><strong>SEL</strong></em> is an element of any <a href="#int-range-set">integer range</a>
10524 of the <code>selector-field-ranges</code> property of&#160;<em><strong>F</strong></em>, then:</p>
10525 </div>
10526 <div class="ulist">
10527 <ul>
10528 <li>
10529 <p><a href="#field-dec">Decode</a> one instance of&#160;<em><strong>OF</strong></em>
10530 as&#160;<em><strong>V</strong></em>.</p>
10531 </li>
10532 </ul>
10533 </div>
10534 </li>
10535 </ol>
10536 </div>
10537 <div class="paragraph">
10538 <p><em><strong>V</strong></em> is the decoded value.</p>
10539 </div>
10540 </div>
10541 <div class="sect3">
10542 <h4 id="var-field-dec">6.3.20. Variant field decoding procedure</h4>
10543 <div class="paragraph">
10544 <p>To decode an instance of an <a href="#var-fc">variant field class</a>&#160;<em><strong>F</strong></em>:</p>
10545 </div>
10546 <div class="olist arabic">
10547 <ol class="arabic">
10548 <li>
10549 <p>Let:</p>
10550 <div class="olist loweralpha">
10551 <ol class="loweralpha" type="a">
10552 <li>
10553 <p><em><strong>SEL</strong></em> be the value of the previously decoded <a href="#int-fc">integer</a>
10554 field of which the <code>selector-field-location</code> property of&#160;<em><strong>F</strong></em>
10555 indicates the <a href="#field-loc-dec">location</a>.</p>
10556 </li>
10557 <li>
10558 <p><em><strong>OPTS</strong></em> be the <code>options</code> property of&#160;<em><strong>F</strong></em>.</p>
10559 </li>
10560 <li>
10561 <p><em><strong>OF</strong></em> be the <code>field-class</code> property of the <a href="#var-fc-opt">variant
10562 field class option</a>&#160;<em><strong>OPT</strong></em> of&#160;<em><strong>OPTS</strong></em> of
10563 which&#160;<em><strong>SEL</strong></em> is an element of any <a href="#int-range-set">integer
10564 range</a> of the <code>selector-field-ranges</code> property of&#160;<em><strong>OPT</strong></em>.</p>
10565 </li>
10566 <li>
10567 <p><em><strong>V</strong></em> be a value.</p>
10568 </li>
10569 </ol>
10570 </div>
10571 </li>
10572 <li>
10573 <p><a href="#field-dec">Decode</a> one instance of&#160;<em><strong>OF</strong></em>
10574 as&#160;<em><strong>V</strong></em>.</p>
10575 </li>
10576 </ol>
10577 </div>
10578 <div class="paragraph">
10579 <p><em><strong>V</strong></em> is the decoded value.</p>
10580 </div>
10581 </div>
10582 </div>
10583 </div>
10584 </div>
10585 </div>
10586 </body>
10587 </html>