rarias/ovni
rarias/ovni
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

trace-v3 #7

Open
rarias wants to merge 36 commits from trace-v3 into master
pull from: trace-v3
merge into: rarias:master
Conversation 0 Commits 36 Files Changed 55 +765 -32
6 changed files with 765 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit bba46ac200 - Show all commits

31
doc/user/concepts.md
View File

@ -1,31 +0,0 @@
# Overview
The objective of the ovni project is to provide insight into what
happened at execution of a program.
![Instrumentation process](fig/instrumentation.svg)
The key pieces of software involved are instrumented so they emit events
during the execution which allow the reconstruction of the execution
later on.
During the execution phase, the information gathered in the events is
kept very short and simple, so the overhead is kept at minimum to avoid
disturbing the execution process. Here is an example of a single event
emitted during the execution phase, informing the current thread to
finish the execution:
00 4f 48 65 52 c0 27 b4 d3 ec 01 00
During the emulation phase, the events are read and processed in the
emulator, reconstructing the execution. State transitions are recorded
in a Paraver trace. Here is an example of the same thread ceasing the
execution:
2:0:1:1:1:50105669:1:0
Finally, loading the trace in the Paraver program, we can generate a
timeline visualization of the state change. Here is the example for the
same state transition of the thread stopping the execution:
![Visualization](fig/visualization.png)

62
doc/user/concepts/part-model.md Normal file
View File

@ -0,0 +1,62 @@
# Part model
Ovni has a model to represent the hardware components as well as the software
concepts like threads or processes. Each concept is considered to be a *part*.
Here is an example diagram depicting the part hierarchy:
![lalala](part-model.svg "foo bar")
Notice how a loom can restrict the CPUs of the node to its child processes.
## Software parts
These are not physical parts, but they abstract common concepts.
### Thread
A thread in ovni is directly mapped to a [POSIX
thread](https://en.wikipedia.org/wiki/Pthreads) and they are identified by a
`TID` which must be unique in a [node](#node). Threads in ovni have [a model with
an internal state](../emulation/ovni.md/#thread_model) that tries to tracks the
state of the real thread.
### Process
A process is directly mapped to a UNIX
[process](https://en.wikipedia.org/wiki/Process_(computing)) and they are
identified by a `PID` number which must be unique in a [node](#node).
### Loom
A loom has no direct mapping to a usual concept. It consists of a set of
[CPUs](#cpu) from the same node and a set of processes that can *only run in
those CPUs*. Each CPUs must belong to one and only one loom. It is often used
to group CPUs that belong to the same process when running workloads with
multiple processes (like with MPI).
Each loom has a virtual CPU which collects running threads that are not
exclusively assigned to a physical CPU, so we cannot determine on which CPU they
are running.
## Hardware parts
These parts have a physical object assigned.
### CPU
A CPU is a hardware thread that can execute at most one thread at a time. Each
CPU must have a physical ID that is unique in a node. In ovni there is also a
virtual CPU, which simply is used to collect threads that are not tied to an
specific physical CPU, so it cannot be easily determined where they are running.
### Node
A *node* refers to a compute node, often a physical machine with memory and
network which may contain one or more
[sockets](https://en.wikipedia.org/wiki/CPU_socket), where each socket has one
or more CPUs.
### System
A system represents the complete set of hardware parts and software parts that
are known to ovni in a given trace.

516
doc/user/concepts/part-model.svg Normal file
View File

@ -0,0 +1,516 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="306.91663mm"
height="127.00001mm"
viewBox="0 0 306.91663 127.00001"
version="1.1"
id="svg1"
inkscape:version="1.3.2 (091e20ef0f, 2023-11-25, custom)"
sodipodi:docname="part-model.svg"
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="namedview1"
pagecolor="#ffffff"
bordercolor="#999999"
borderopacity="1"
inkscape:showpageshadow="0"
inkscape:pageopacity="0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="mm"
showgrid="false"
inkscape:zoom="0.73049944"
inkscape:cx="629.70616"
inkscape:cy="280.62992"
inkscape:window-width="1920"
inkscape:window-height="1031"
inkscape:window-x="0"
inkscape:window-y="24"
inkscape:window-maximized="1"
inkscape:current-layer="layer1">
<inkscape:grid
id="grid1"
units="px"
originx="-74.083327"
originy="-89.958345"
spacingx="0.26458333"
spacingy="0.26458334"
empcolor="#7a7aff"
empopacity="0.25098039"
color="#6a6aff"
opacity="0.1254902"
empspacing="5"
dotted="false"
gridanglex="30"
gridanglez="30"
visible="false" />
</sodipodi:namedview>
<defs
id="defs1" />
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-74.083328,-89.958344)">
<rect
style="fill:none;stroke:none;stroke-width:0.264999;stroke-linecap:square;stroke-dasharray:none;stroke-dashoffset:0"
id="rect33"
width="306.91663"
height="127.00001"
x="74.083328"
y="89.958344" />
<rect
style="fill:#ffeeaa;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none;stroke-dashoffset:0"
id="rect32"
width="121.70832"
height="84.666679"
x="253.99998"
y="127.00001" />
<text
xml:space="preserve"
style="font-size:6.35px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="290.19363"
y="202.25124"
id="text32"><tspan
sodipodi:role="line"
id="tspan32"
style="font-size:6.35px;stroke-width:0.264583"
x="290.19363"
y="202.25124">Hardware parts</tspan></text>
<rect
style="fill:#eeffaa;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none;stroke-dashoffset:0"
id="rect31"
width="169.33333"
height="84.666679"
x="79.374992"
y="127.00001" />
<rect
style="fill:#fff6d5;stroke:#000000;stroke-width:0.3;stroke-linecap:square;stroke-dasharray:none;stroke-dashoffset:0"
id="rect27"
width="47.625004"
height="21.166676"
x="269.87497"
y="148.16667"
ry="2.645834" />
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect1"
width="21.166662"
height="10.583329"
x="84.566666"
y="174.52502"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="87.947342"
y="181.39488"
id="text1"><tspan
sodipodi:role="line"
id="tspan1"
style="stroke-width:0.264583"
x="87.947342"
y="181.39488">Thread</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect3"
width="21.166664"
height="10.583337"
x="111.12499"
y="153.45834"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="113.57446"
y="160.26309"
id="text3"><tspan
sodipodi:role="line"
id="tspan3"
style="stroke-width:0.264583"
x="113.57446"
y="160.26309">Process</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect4"
width="21.166664"
height="10.583333"
x="111.12499"
y="174.62502"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="114.50567"
y="181.49487"
id="text4"><tspan
sodipodi:role="line"
id="tspan4"
style="stroke-width:0.264583"
x="114.50567"
y="181.49487">Thread</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect5"
width="21.166658"
height="10.583333"
x="137.58333"
y="174.62502"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="140.964"
y="181.49487"
id="text5"><tspan
sodipodi:role="line"
id="tspan5"
style="stroke-width:0.264583"
x="140.964"
y="181.49487">Thread</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect6"
width="21.166672"
height="10.583333"
x="169.33331"
y="174.62502"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="172.71399"
y="181.49487"
id="text6"><tspan
sodipodi:role="line"
id="tspan6"
style="stroke-width:0.264583"
x="172.71399"
y="181.49487">Thread</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect7"
width="20.966642"
height="10.38336"
x="195.99167"
y="153.55833"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="198.24112"
y="160.16312"
id="text7"><tspan
sodipodi:role="line"
id="tspan7"
style="stroke-width:0.264583"
x="198.24112"
y="160.16312">Process</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect8"
width="21.16667"
height="10.583333"
x="195.79164"
y="174.62502"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="199.17232"
y="181.49487"
id="text8"><tspan
sodipodi:role="line"
id="tspan8"
style="stroke-width:0.264583"
x="199.17232"
y="181.49487">Thread</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect9"
width="21.166666"
height="10.583333"
x="222.24997"
y="174.62502"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="225.63065"
y="181.49487"
id="text9"><tspan
sodipodi:role="line"
id="tspan9"
style="stroke-width:0.264583"
x="225.63065"
y="181.49487">Thread</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect10"
width="21.166658"
height="10.583337"
x="153.45833"
y="132.29167"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="158.21979"
y="139.09644"
id="text10"><tspan
sodipodi:role="line"
id="tspan10"
style="stroke-width:0.264583"
x="158.21979"
y="139.09644">Loom</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect11"
width="21.166651"
height="10.58334"
x="306.91666"
y="132.29167"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="311.88068"
y="139.16154"
id="text11"><tspan
sodipodi:role="line"
id="tspan11"
style="stroke-width:0.264583"
x="311.88068"
y="139.16154">Node</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect12"
width="15.875001"
height="10.583341"
x="275.16666"
y="153.45834"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="278.86566"
y="160.291"
id="text12"><tspan
sodipodi:role="line"
id="tspan12"
style="stroke-width:0.264583"
x="278.86566"
y="160.291">CPU</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect13"
width="15.874983"
height="10.583341"
x="296.33334"
y="153.45834"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="300.03235"
y="160.291"
id="text13"><tspan
sodipodi:role="line"
id="tspan13"
style="stroke-width:0.264583"
x="300.03235"
y="160.291">CPU</tspan></text>
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 121.70832,164.04168 0,10.58334"
id="path15"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect3"
inkscape:connection-end="#rect4" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 206.45046,163.94169 -0.0505,10.68333"
id="path16"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect7"
inkscape:connection-end="#rect8" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 212.94006,163.94169 13.30366,10.68333"
id="path17"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-end="#rect9"
inkscape:connection-start="#rect7" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 199.96086,163.94169 -13.40463,10.68333"
id="path18"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect7"
inkscape:connection-end="#rect6" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 128.32291,164.04168 13.22917,10.58334"
id="path19"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect3"
inkscape:connection-end="#rect5" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 115.03723,164.04168 -13.21614,10.48334"
id="path20"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect3"
inkscape:connection-end="#rect1" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 153.45833,142.87501 -21.16667,10.58333"
id="path21"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect10"
inkscape:connection-end="#rect3" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 174.62499,142.86254 21.44212,10.69579"
id="path22"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect10"
inkscape:connection-end="#rect7" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 314.19269,142.87501 -6.61457,10.58333"
id="path24"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect11"
inkscape:connection-end="#rect13" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="M 308.90102,142.87501 291.04166,153.8654"
id="path25"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect11"
inkscape:connection-end="#rect12" />
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect25"
width="15.875013"
height="10.583337"
x="322.79163"
y="153.45834"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="326.49063"
y="160.291"
id="text25"><tspan
sodipodi:role="line"
id="tspan25"
style="stroke-width:0.264583"
x="326.49063"
y="160.291">CPU</tspan></text>
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect26"
width="15.874991"
height="10.583337"
x="343.95831"
y="153.45834"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="347.65732"
y="160.291"
id="text26"><tspan
sodipodi:role="line"
id="tspan26"
style="stroke-width:0.264583"
x="347.65732"
y="160.291">CPU</tspan></text>
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 320.80727,142.87501 6.61457,10.58333"
id="path26"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect11"
inkscape:connection-end="#rect25" />
<path
style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 326.09894,142.87501 17.85937,10.99039"
id="path27"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect11"
inkscape:connection-end="#rect26" />
<path
style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.265;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
d="m 174.62499,139.70001 95.24998,19.05"
id="path28"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect10" />
<rect
style="fill:#ffffff;stroke:#000000;stroke-width:0.2;stroke-linecap:square;stroke-dasharray:none"
id="rect29"
width="21.166666"
height="10.583335"
x="216.95831"
y="95.250008"
ry="0" />
<text
xml:space="preserve"
style="font-size:4.23333px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="219.6889"
y="101.67236"
id="text29"><tspan
sodipodi:role="line"
id="tspan29"
style="stroke-width:0.264583"
x="219.6889"
y="101.67236">System</tspan></text>
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 238.12498,104.89952 68.79168,28.32598"
id="path29"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect29"
inkscape:connection-end="#rect11" />
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 218.47022,105.83334 -45.35713,26.45833"
id="path30"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#rect29"
inkscape:connection-end="#rect10" />
<text
xml:space="preserve"
style="font-size:6.35px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583"
x="140.81671"
y="202.25124"
id="text31"><tspan
sodipodi:role="line"
id="tspan31"
style="font-size:6.35px;stroke-width:0.264583"
x="140.81671"
y="202.25124">Software parts</tspan></text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

72
doc/user/concepts/trace-model.md Normal file
View File

@ -0,0 +1,72 @@
# Trace model
An event model is composed by a group of runtime events
## Trace
The information generated by a program or later processed by other ovni tools is
known as a trace. A runtime trace stores the information as-is in disk from a
program execution. While a emulation trace is generated from the runtime trace
for visualization with Paraver.
All the information is always stored inside the same directory, by default
`ovni/`, which is known as the trace directory.
## Event
An event is a point in time that has some information associated. Events written
at runtime by libovni have at MCV, a clock and a optional payload. The list of
all events recognized by the emulator can be found [here](../emulation/events.md).
## State
A state is a discrete value that can change over time based on the events the
emulator receives. Usually a single event causes a single state change, which is
then written to the Paraver traces. An example is the thread state, which can
change over time based on the events `OH*` that indicate a state transition
of the current thread.
## MCV
The MCV acronym is short of Model-Class-Value, which is a three character (byte)
identification for events.
## Clock
A clock is a 64 bit counter, which counts the number of nanoseconds from an
arbitrary point in time in the past. Each event has the value of the clock
stored inside, to indicate when that event happened. In a given trace there can
be multiple clocks which don't refer to the same point in the past and must be
corrected so they all produce an ordered sequence of events. The ovnisync
program performs this correction by measuring the difference across clocks of
different nodes.
## Event model
An event model is composed of several components:
- A set of [events](#event) all with the same model identifier in the
[MCV](#mcv)
- The emulator code that processes those events.
- A human readable name, like `ovni` or `nanos6`.
## Payload
Events may have associated additional information which is stored in the stream.
## Binary stream
A binary stream is a file named `stream.obs` (.obs stands for Ovni Binary
Stream) composed of a header and a concatenated array of events without padding.
Notice that each event may have different length.
## Stream metadata
The stream metadata is a JSON file named `stream.json` which holds information
about the stream.
## Stream
A stream is a directory which contains a binary stream and the associated stream
metadata file. Each stream is associated with a given part of a system. As of
now, libovni can only generate streams associated to [threads](part-model.md#thread).

111
doc/user/runtime/index.md Normal file
View File

@ -0,0 +1,111 @@
# Introduction
To use *libovni* to instrument a program, follow the next instructions
carefully, or you may end up with an incomplete trace that is rejected at
emulation.
You can also generate a valid trace from your own software or hardware
directly, but be sure to follow the [trace specification](trace_spec.md).
## Initialization
To initialize libovni follow these steps in all threads:
1. **Check the version**. Call `ovni_version_check()` once before calling any
ovni function. It can be called multiple times from any thread, but only one
is required.
2. **Init the process**. Call `ovni_proc_init()` to initialize the process when
a new process begins the execution. It can only be called **once per
process** and it must be called before the thread is initialized.
3. **Init the thread**. Call `ovni_thread_init()` when a new thread begins the
execution (including the main process thread after the process is
initialized). Multiple attempts to initialize the thread are ignored with a
warning.
The `ovni_proc_init()` arguments are as follows:
```c
void ovni_proc_init(int app, const char *loom, int pid);
```
The `app` defines the "appid" of the program, which must be a number >0. This is
useful to run multiple processes some of which run the same "app", so you can
tell which one is which. The `loom` defines the
[loom](../concepts/part-model.md#loom) name and assignes the process to that
loom. It must be compose of the host name, a dot and a suffix. The PID is the
one obtained by `getpid(2)`.
The `ovni_thread_init()` function only accepts one argument, the TID as returned
by `gettid(2)`.
## Setup metadata
Once the process and thread are initialized, you can begin adding metadata to
the thread stream.
1. **Require models**. Call `ovni_thread_require()` with the required model
version before emitting events for a given model. Only required once from a
thread in a given trace.
2. **Emit loom CPUs**. Call `ovni_add_cpu()` to register each CPU in the loom. It can
be done from a single thread or multiple threads, in the latter the list of
CPUs is merged.
3. **Set the rank**. If you use MPI, call `ovni_proc_set_rank()` to register the
rank and number of ranks of the current execution. Only once per process.
## Start the execution
The current thread must switch to the "Running" state before any event can be
processed by the emulator. Do so by emitting a `OHx` event in the stream with
the appropriate payload:
```c
static void thread_execute(int32_t cpu, int32_t ctid, uint64_t tag)
{
struct ovni_ev ev = {0};
ovni_ev_set_clock(&ev, ovni_clock_now());
ovni_ev_set_mcv(&ev, "OHx");
ovni_payload_add(&ev, (uint8_t *) &cpu, sizeof(cpu));
ovni_payload_add(&ev, (uint8_t *) &ctid, sizeof(ctid));
ovni_payload_add(&ev, (uint8_t *) &tag, sizeof(tag));
ovni_ev_emit(&ev);
}
```
The `cpu` is the logical index (not the physical ID) of the loom CPU at which
this thread will begin the execution. Use -1 if it is not known. The `ctid` and
`tag` allow you to track the exact point at which a given thread was created and
by which thread but they are not relevant for the first thread, so they can be
set to -1.
## Emit events
After this point you can emit any other event from this thread. Use the
`ovni_ev_*` set of functions to create and emit events. Notice that all events
are refer to the current thread that emits them.
If you need to store metadata information, use the `ovni_attr_*` set of
functions. The metadata is stored in disk by `ovni_attr_fluch()` and when the
thread is freed by `ovni_thread_free()`.
Attempting to emit events or writing metadata without having a thread
initialized will cause your program to abort.
## Finishing the execution
To finalize the execution **every thread** must perform the following steps,
otherwise the trace **will be rejected**.
1. **End the current thread**. Emit a [`OHe` event](../emulation/events.md#OHe) to inform the current thread ends.
2. **Flush the buffer**. Call `ovni_flush()` to be sure all events are written
to disk.
3. **Free the thread**. Call `ovni_thread_free()` to complete the stream and
free the memory used by the buffer.
4. **Finish the process**. If this is the last thread, call `ovni_proc_fini()`
to set the process state to finished.
If a thread fails to perform these steps, the complete trace will be rejected by
the emulator as it cannot guarantee the trace to be consistent.

5
mkdocs.yml
View File

@ -23,9 +23,12 @@ markdown_extensions:
nav:
- index.md
- 'User guide':
- user/concepts.md
- user/installation.md
- 'Concepts':
- user/concepts/part-model.md
- user/concepts/trace-model.md
- 'Runtime':
- user/runtime/index.md
- user/runtime/tracing.md
- user/runtime/mark.md
- user/runtime/distributed.md