Add stream header documentation
This commit is contained in:
parent
c83c8d2e56
commit
00872418a1
458
doc/fig/stream.svg
Normal file
458
doc/fig/stream.svg
Normal file
@ -0,0 +1,458 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||||
|
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||||
|
|
||||||
|
<svg
|
||||||
|
width="370"
|
||||||
|
height="180"
|
||||||
|
viewBox="0 0 97.895833 47.625002"
|
||||||
|
version="1.1"
|
||||||
|
id="svg5"
|
||||||
|
inkscape:version="1.2 (dc2aedaf03, 2022-05-15)"
|
||||||
|
sodipodi:docname="stream.svg"
|
||||||
|
inkscape:export-filename="event-payload.png"
|
||||||
|
inkscape:export-xdpi="300"
|
||||||
|
inkscape:export-ydpi="300"
|
||||||
|
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||||
|
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||||
|
xmlns="http://www.w3.org/2000/svg"
|
||||||
|
xmlns:svg="http://www.w3.org/2000/svg">
|
||||||
|
<sodipodi:namedview
|
||||||
|
id="namedview7"
|
||||||
|
pagecolor="#ffffff"
|
||||||
|
bordercolor="#666666"
|
||||||
|
borderopacity="1.0"
|
||||||
|
inkscape:showpageshadow="2"
|
||||||
|
inkscape:pageopacity="0.0"
|
||||||
|
inkscape:pagecheckerboard="0"
|
||||||
|
inkscape:deskcolor="#d1d1d1"
|
||||||
|
inkscape:document-units="mm"
|
||||||
|
showgrid="true"
|
||||||
|
inkscape:zoom="2.8289483"
|
||||||
|
inkscape:cx="200.42784"
|
||||||
|
inkscape:cy="124.78136"
|
||||||
|
inkscape:window-width="1914"
|
||||||
|
inkscape:window-height="1025"
|
||||||
|
inkscape:window-x="0"
|
||||||
|
inkscape:window-y="24"
|
||||||
|
inkscape:window-maximized="1"
|
||||||
|
inkscape:current-layer="layer1">
|
||||||
|
<inkscape:grid
|
||||||
|
type="xygrid"
|
||||||
|
id="grid126"
|
||||||
|
spacingx="2.6458333"
|
||||||
|
spacingy="2.6458333"
|
||||||
|
originx="-10.583333"
|
||||||
|
originy="-2.6458337"
|
||||||
|
empspacing="4" />
|
||||||
|
</sodipodi:namedview>
|
||||||
|
<defs
|
||||||
|
id="defs2" />
|
||||||
|
<g
|
||||||
|
inkscape:label="Layer 1"
|
||||||
|
inkscape:groupmode="layer"
|
||||||
|
id="layer1"
|
||||||
|
transform="translate(-10.583333,-2.6458333)">
|
||||||
|
<rect
|
||||||
|
style="fill:#ffffff;stroke:none;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.600001"
|
||||||
|
id="rect326"
|
||||||
|
width="97.895836"
|
||||||
|
height="47.625"
|
||||||
|
x="10.583333"
|
||||||
|
y="2.6458333" />
|
||||||
|
<rect
|
||||||
|
style="fill:#ffeeaa;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect6884"
|
||||||
|
width="84.666664"
|
||||||
|
height="10.583333"
|
||||||
|
x="21.166666"
|
||||||
|
y="21.166664" />
|
||||||
|
<rect
|
||||||
|
style="fill:#e6e6e6;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect2375"
|
||||||
|
width="84.666664"
|
||||||
|
height="5.2916665"
|
||||||
|
x="21.166666"
|
||||||
|
y="5.2916665" />
|
||||||
|
<rect
|
||||||
|
style="fill:#ffe6d5;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect2305"
|
||||||
|
width="84.666672"
|
||||||
|
height="5.2916632"
|
||||||
|
x="21.166662"
|
||||||
|
y="42.333336" />
|
||||||
|
<rect
|
||||||
|
style="fill:#c6e9af;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect1108"
|
||||||
|
width="84.666664"
|
||||||
|
height="10.583333"
|
||||||
|
x="21.166666"
|
||||||
|
y="31.75" />
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11667px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="59.082172"
|
||||||
|
y="41.534935"
|
||||||
|
id="text366"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan364"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11667px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="59.082172"
|
||||||
|
y="41.534935">version</tspan></text>
|
||||||
|
<rect
|
||||||
|
style="fill:#e6e6e6;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect2009"
|
||||||
|
width="21.166666"
|
||||||
|
height="7.937499"
|
||||||
|
x="21.166666"
|
||||||
|
y="10.583332" />
|
||||||
|
<rect
|
||||||
|
style="fill:#e6e6e6;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect2013"
|
||||||
|
width="21.166664"
|
||||||
|
height="7.937499"
|
||||||
|
x="42.33334"
|
||||||
|
y="10.583332" />
|
||||||
|
<rect
|
||||||
|
style="fill:#e6e6e6;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect2015"
|
||||||
|
width="21.166666"
|
||||||
|
height="7.937499"
|
||||||
|
x="63.5"
|
||||||
|
y="10.583332" />
|
||||||
|
<rect
|
||||||
|
style="fill:#e6e6e6;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none"
|
||||||
|
id="rect2017"
|
||||||
|
width="21.16666"
|
||||||
|
height="7.937499"
|
||||||
|
x="84.666672"
|
||||||
|
y="10.583332" />
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="30.794245"
|
||||||
|
y="14.384908"
|
||||||
|
id="text2087"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2085"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="30.794245"
|
||||||
|
y="14.384908">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="51.960915"
|
||||||
|
y="14.419789"
|
||||||
|
id="text2091"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2089"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="51.960915"
|
||||||
|
y="14.419789">1</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="73.127579"
|
||||||
|
y="14.419789"
|
||||||
|
id="text2095"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2093"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="73.127579"
|
||||||
|
y="14.419789">2</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="94.29425"
|
||||||
|
y="14.384908"
|
||||||
|
id="text2099"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2097"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="94.29425"
|
||||||
|
y="14.384908">3</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:2.82222px;line-height:1.25;font-family:cmr10;-inkscape-font-specification:cmr10;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="57.622673"
|
||||||
|
y="8.6726809"
|
||||||
|
id="text2155"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2153"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="57.622673"
|
||||||
|
y="8.6726809">4 Bytes</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="46.346531"
|
||||||
|
y="28.001389"
|
||||||
|
id="text2207"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2205"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="46.346531"
|
||||||
|
y="28.001389">7</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="56.908157"
|
||||||
|
y="28.0665"
|
||||||
|
id="text2211"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2209"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="56.908157"
|
||||||
|
y="28.0665">6</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="67.513191"
|
||||||
|
y="28.001389"
|
||||||
|
id="text2215"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2213"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="67.513191"
|
||||||
|
y="28.001389">6</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="78.100662"
|
||||||
|
y="27.999321"
|
||||||
|
id="text2219"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2217"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="78.100662"
|
||||||
|
y="27.999321">e</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="88.699493"
|
||||||
|
y="28.001389"
|
||||||
|
id="text2223"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2221"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="88.699493"
|
||||||
|
y="28.001389">6</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="99.267326"
|
||||||
|
y="27.999321"
|
||||||
|
id="text2227"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2225"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="99.267326"
|
||||||
|
y="27.999321">9</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="25.226366"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2231"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2229"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="25.226366"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="35.692909"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2235"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2233"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="35.692909"
|
||||||
|
y="38.582653">1</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="46.326889"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2239"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2237"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="46.326889"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="57.004272"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2243"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2241"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="57.004272"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="67.442909"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2247"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2245"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="67.442909"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="78.100662"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2251"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2249"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="78.100662"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="88.609589"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2255"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2253"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="88.609589"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="99.28904"
|
||||||
|
y="38.582653"
|
||||||
|
id="text2259"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2257"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="99.28904"
|
||||||
|
y="38.582653">0</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11667px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="60.563736"
|
||||||
|
y="45.73571"
|
||||||
|
id="text2303"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan2301"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11667px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="60.563736"
|
||||||
|
y="45.73571">Events...</tspan></text>
|
||||||
|
<rect
|
||||||
|
style="fill:#e6e6e6;fill-opacity:1;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:none;stroke-dashoffset:0"
|
||||||
|
id="rect2429"
|
||||||
|
width="5.291667"
|
||||||
|
height="21.166666"
|
||||||
|
x="13.229168"
|
||||||
|
y="21.166666" />
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:3.175px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="-37.530266"
|
||||||
|
y="17.058649"
|
||||||
|
id="text2433"
|
||||||
|
transform="rotate(-90)"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
style="font-size:3.175px;stroke-width:0.264583"
|
||||||
|
x="-37.530266"
|
||||||
|
y="17.058649"
|
||||||
|
id="tspan15238">Header</tspan></text>
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2161"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="21.166666"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2163"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="31.749998"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2165"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="42.33334"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2167"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="52.916668"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2169"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="63.5"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2171"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="74.083344"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2173"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="84.666672"
|
||||||
|
y="15.875" />
|
||||||
|
<rect
|
||||||
|
style="fill:none;stroke:#000000;stroke-width:0.2;stroke-linecap:round;stroke-dasharray:0.2, 0.6;stroke-dashoffset:0"
|
||||||
|
id="rect2175"
|
||||||
|
width="10.583333"
|
||||||
|
height="2.6458333"
|
||||||
|
x="95.249992"
|
||||||
|
y="15.875" />
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="25.199488"
|
||||||
|
y="28.001389"
|
||||||
|
id="text6878"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan6876"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="25.199488"
|
||||||
|
y="28.001389">6</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-size:4.23333px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="35.767326"
|
||||||
|
y="27.999321"
|
||||||
|
id="text6882"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan6880"
|
||||||
|
style="stroke-width:0.264583"
|
||||||
|
x="35.767326"
|
||||||
|
y="27.999321">f</tspan></text>
|
||||||
|
<text
|
||||||
|
xml:space="preserve"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11667px;line-height:1.25;font-family:monospace;-inkscape-font-specification:monospace;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
|
||||||
|
x="60.346699"
|
||||||
|
y="30.73921"
|
||||||
|
id="text6888"><tspan
|
||||||
|
sodipodi:role="line"
|
||||||
|
id="tspan6886"
|
||||||
|
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.11667px;font-family:monospace;-inkscape-font-specification:monospace;stroke-width:0.264583"
|
||||||
|
x="60.346699"
|
||||||
|
y="30.73921">magic</tspan></text>
|
||||||
|
</g>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 18 KiB |
@ -1,7 +1,7 @@
|
|||||||
# Trace specification version 1
|
# Trace specification version 1
|
||||||
|
|
||||||
The ovni instrumentation library produces a trace with the following
|
The ovni instrumentation library stores the information collected in a
|
||||||
specification.
|
trace following the specification of this document.
|
||||||
|
|
||||||
The complete trace is stored in a top-level directory named "ovni".
|
The complete trace is stored in a top-level directory named "ovni".
|
||||||
Inside this directory you will find the loom directories with the prefix
|
Inside this directory you will find the loom directories with the prefix
|
||||||
@ -15,7 +15,7 @@ specified in the `pid` argument to `ovni_proc_init()`.
|
|||||||
Each process directory contains:
|
Each process directory contains:
|
||||||
|
|
||||||
- The metadata file `metadata.json`.
|
- The metadata file `metadata.json`.
|
||||||
- The thread traces with prefix `thread.`.
|
- The thread streams with prefix `thread.`.
|
||||||
|
|
||||||
## Process metadata
|
## Process metadata
|
||||||
|
|
||||||
@ -27,6 +27,8 @@ The metadata is stored in the JSON file `metadata.json` inside each
|
|||||||
process directory and contains the following keys:
|
process directory and contains the following keys:
|
||||||
|
|
||||||
- `version`: a number specifying the version of the metadata format.
|
- `version`: a number specifying the version of the metadata format.
|
||||||
|
- `model_version`: a string with the version of each model supported by
|
||||||
|
the emulator.
|
||||||
- `app_id`: the application ID, used to distinguish between applications
|
- `app_id`: the application ID, used to distinguish between applications
|
||||||
running on the same loom.
|
running on the same loom.
|
||||||
- `rank`: the rank of the MPI process (optional).
|
- `rank`: the rank of the MPI process (optional).
|
||||||
@ -38,27 +40,66 @@ process directory and contains the following keys:
|
|||||||
- `phyid`: the number of the CPU as given by the operating system
|
- `phyid`: the number of the CPU as given by the operating system
|
||||||
(which can exceed $`N_c`$).
|
(which can exceed $`N_c`$).
|
||||||
|
|
||||||
## Thread trace
|
Here is an example of the `metadata.json` file:
|
||||||
|
|
||||||
The thread trace is a binary file composed of events joined one after
|
```
|
||||||
the other. Each event has a header with the following information:
|
{
|
||||||
|
"version": 1,
|
||||||
|
"model_version": "O1 V1 T1 M1 D1 K1",
|
||||||
|
"app_id": 1,
|
||||||
|
"rank": 0,
|
||||||
|
"nranks": 4,
|
||||||
|
"cpus": [
|
||||||
|
{
|
||||||
|
"index": 0,
|
||||||
|
"phyid": 0
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"index": 1,
|
||||||
|
"phyid": 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"index": 2,
|
||||||
|
"phyid": 2
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"index": 3,
|
||||||
|
"phyid": 3
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Thread streams
|
||||||
|
|
||||||
|
Streams are a binary files that contains a succession of events with
|
||||||
|
monotonically increasing clock values. Streams have a small header and
|
||||||
|
the variable size events just after the header.
|
||||||
|
|
||||||
|
The header contains the magic 4 bytes of "ovni" and a version number of
|
||||||
|
4 bytes too. Here is a figure of the data stored in disk:
|
||||||
|
|
||||||
|
<img src="fig/stream.svg" alt="Stream" width="400px"/>
|
||||||
|
|
||||||
|
Similarly, events have a fixed size header followed by an optional
|
||||||
|
payload of varying size. The header has the following information:
|
||||||
|
|
||||||
- Event flags
|
- Event flags
|
||||||
- Payload size in a special format
|
- Payload size in a special format
|
||||||
- Model, category and value codes
|
- Model, category and value codes
|
||||||
- Time in nanoseconds
|
- Time in nanoseconds
|
||||||
- Payload (optional)
|
|
||||||
|
|
||||||
The payload size is specified using 4 bits, with the value `0x0` for no
|
The event size can vary depending on the data stored in the payload. The
|
||||||
payload, or with value $`v`$ for $`v + 1`$ bytes of payload. This
|
payload size is specified using 4 bits, with the value `0x0` for no
|
||||||
allows us to use 16 bytes of payload with value `0xf` at the cost of
|
payload, or with value $`v`$ for $`v + 1`$ bytes of payload. This allows
|
||||||
|
us to use 16 bytes of payload with value `0xf` at the cost of
|
||||||
sacrificing payloads of one byte.
|
sacrificing payloads of one byte.
|
||||||
|
|
||||||
There are two types of events, depending of the size needed for the
|
There are two types of events, depending of the size needed for the
|
||||||
payload:
|
payload:
|
||||||
|
|
||||||
- Normal: with a payload up to 16 bytes
|
- Normal events: with a payload up to 16 bytes
|
||||||
- Jumbo: with a payload up to 2^32 bytes
|
- Jumbo events: with a payload up to 2^32 bytes
|
||||||
|
|
||||||
## Normal events
|
## Normal events
|
||||||
|
|
||||||
@ -74,8 +115,7 @@ Here is an example of a normal event without payload, a total of 12
|
|||||||
bytes:
|
bytes:
|
||||||
|
|
||||||
```
|
```
|
||||||
% dd if=thread.552943 skip=5258 bs=1 | hexdump -C
|
00 4f 48 65 01 c5 cf 1d 96 d0 12 00 |.OHe........|
|
||||||
00000000 00 4f 48 65 01 c5 cf 1d 96 d0 12 00 |.OHe........|
|
|
||||||
```
|
```
|
||||||
|
|
||||||
And in the following figure you can see every field annotated:
|
And in the following figure you can see every field annotated:
|
||||||
@ -83,12 +123,11 @@ And in the following figure you can see every field annotated:
|
|||||||
<img src="fig/event-normal.svg" alt="Normal event without payload" width="400px"/>
|
<img src="fig/event-normal.svg" alt="Normal event without payload" width="400px"/>
|
||||||
|
|
||||||
Another example of a normal event with 16 bytes of payload, a total of
|
Another example of a normal event with 16 bytes of payload, a total of
|
||||||
28 bytes as reported by hexdump:
|
28 bytes:
|
||||||
|
|
||||||
```
|
```
|
||||||
% dd if=thread.552943 bs=1 count=28 | hexdump -C
|
0f 4f 48 78 58 c1 b0 b5 95 43 11 00 00 00 00 00 |.OHxX....C......|
|
||||||
00000000 0f 4f 48 78 58 c1 b0 b5 95 43 11 00 00 00 00 00 |.OHxX....C......|
|
ff ff ff ff 00 00 00 00 00 00 00 00 |............|
|
||||||
00000010 ff ff ff ff 00 00 00 00 00 00 00 00 |............|
|
|
||||||
```
|
```
|
||||||
|
|
||||||
In the following figure you can see each field annotated:
|
In the following figure you can see each field annotated:
|
||||||
@ -112,8 +151,8 @@ Example of a jumbo event of 30 bytes in total, with 14 bytes of jumbo
|
|||||||
data:
|
data:
|
||||||
|
|
||||||
```
|
```
|
||||||
00000000 13 56 59 63 eb c1 4b 1a 96 d0 12 00 0e 00 00 00 |.VYc..K.........|
|
13 56 59 63 eb c1 4b 1a 96 d0 12 00 0e 00 00 00 |.VYc..K.........|
|
||||||
00000010 01 00 00 00 74 65 73 74 74 79 70 65 31 00 |....testtype1.|
|
01 00 00 00 74 65 73 74 74 79 70 65 31 00 |....testtype1.|
|
||||||
```
|
```
|
||||||
|
|
||||||
In the following figure you can see each field annotated:
|
In the following figure you can see each field annotated:
|
||||||
@ -122,38 +161,43 @@ In the following figure you can see each field annotated:
|
|||||||
|
|
||||||
## Design considerations
|
## Design considerations
|
||||||
|
|
||||||
The trace format has been designed to be very simple, so writing a
|
The stream format has been designed to be very simple, so writing a
|
||||||
parser library would take no more than 2 days.
|
parser library would take no more than 2 days for a single developer.
|
||||||
|
|
||||||
The common events don't use any payload, so the size per event is kept
|
The size of the events has been designed to be small, with 12 bytes per
|
||||||
at the minimum of 12 bytes.
|
event when no payload is used.
|
||||||
|
|
||||||
**Important:** The events are stored in disk following the endianness of
|
**Important:** The events are stored in disk following the endianness of
|
||||||
the machine where they are generated. So a trace generated with a little
|
the machine where they are generated. So a stream generated with a little
|
||||||
endian machine would be different than on a big endian machine. Using
|
endian machine would be different than on a big endian machine. We
|
||||||
the same endiannes avoids the cost of serialization when writting the
|
assume the same endiannes is used to write the trace at runtime and read
|
||||||
trace at runtime.
|
it after, at the emulation process.
|
||||||
|
|
||||||
The events are designed to be easily identified when looking at the
|
The events are designed to be easily identified when looking at the
|
||||||
raw trace in binary, as the MCV codes can be read as ASCII characters:
|
raw stream in binary, as the MCV codes can be read as ASCII characters:
|
||||||
|
|
||||||
```
|
```
|
||||||
00000000 0f 4f 48 78 58 c1 b0 b5 95 43 11 00 00 00 00 00 |.OHxX....C......|
|
00000000 6f 76 6e 69 01 00 00 00 0f 4f 48 78 08 ba 2e 5c |ovni.....OHx...\|
|
||||||
00000010 ff ff ff ff 00 00 00 00 00 00 00 00 00 36 53 72 |.............6Sr|
|
00000010 b5 b0 00 00 00 00 00 00 ff ff ff ff 00 00 00 00 |................|
|
||||||
00000020 ab cb b0 b5 95 43 11 00 00 36 53 73 78 c3 b9 b5 |.....C...6Ssx...|
|
00000020 00 00 00 00 13 56 59 63 3c c2 2e 5c b5 b0 00 00 |.....VYc<..\....|
|
||||||
00000030 95 43 11 00 00 36 53 40 87 a4 c2 b5 95 43 11 00 |.C...6S@.....C..|
|
00000030 0e 00 00 00 01 00 00 00 74 65 73 74 74 79 70 65 |........testtype|
|
||||||
00000040 00 36 53 68 9c 4b cb b5 95 43 11 00 00 36 53 66 |.6Sh.K...C...6Sf|
|
00000040 31 00 07 56 54 63 43 cc 2e 5c b5 b0 00 00 01 00 |1..VTcC..\......|
|
||||||
00000050 85 44 d4 b5 95 43 11 00 00 36 53 5b cb e7 dc b5 |.D...C...6S[....|
|
00000050 00 00 01 00 00 00 03 56 54 78 03 cd 2e 5c b5 b0 |.......VTx...\..|
|
||||||
00000060 95 43 11 00 00 36 53 5d cf ca e5 b5 95 43 11 00 |.C...6S].....C..|
|
00000060 00 00 01 00 00 00 03 56 54 70 2b 7d 37 5c b5 b0 |.......VTp+}7\..|
|
||||||
00000070 00 36 53 75 8c db ee b5 95 43 11 00 00 36 53 55 |.6Su.....C...6SU|
|
00000070 00 00 01 00 00 00 03 56 54 72 c3 4d 40 5c b5 b0 |.......VTr.M@\..|
|
||||||
00000080 5a 70 f8 b5 95 43 11 00 00 36 55 5b 1b ae 01 b6 |Zp...C...6U[....|
|
00000080 00 00 01 00 00 00 03 56 54 65 03 36 49 5c b5 b0 |.......VTe.6I\..|
|
||||||
00000090 95 43 11 00 00 36 55 5d aa 19 0b b6 95 43 11 00 |.C...6U].....C..|
|
00000090 00 00 01 00 00 00 00 4f 48 65 f5 36 49 5c b5 b0 |.......OHe.6I\..|
|
||||||
|
000000a0 00 00 |..|
|
||||||
```
|
```
|
||||||
|
|
||||||
This allows a human to detect signs of corruption by just visually
|
This allows a human to detect signs of corruption by visually inspecting
|
||||||
inspecting the trace.
|
the streams.
|
||||||
|
|
||||||
## Limitations
|
## Limitations
|
||||||
|
|
||||||
The traces are designed to be read only forward, as they only contain
|
The streams are designed to be read only forward, as they only contain
|
||||||
the size of each event in the header.
|
the size of each event in the header.
|
||||||
|
|
||||||
|
Currently, we only support using the threads as sources of events, using
|
||||||
|
one stream per thread. However, adding support for more streams from
|
||||||
|
multiple sources is planned for the future.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user