Explain some concepts in the documentation
This commit is contained in:
parent
5d4fa15eb9
commit
6285a47f72
@ -1,31 +0,0 @@
|
|||||||
# Overview
|
|
||||||
|
|
||||||
The objective of the ovni project is to provide insight into what
|
|
||||||
happened at execution of a program.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
|
|
||||||
62
doc/user/concepts/part-model.md
Normal file
62
doc/user/concepts/part-model.md
Normal 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:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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
516
doc/user/concepts/part-model.svg
Normal 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>
|
||||||
|
After Width: | Height: | Size: 18 KiB |
72
doc/user/concepts/trace-model.md
Normal file
72
doc/user/concepts/trace-model.md
Normal 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
111
doc/user/runtime/index.md
Normal 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.
|
||||||
@ -23,9 +23,12 @@ markdown_extensions:
|
|||||||
nav:
|
nav:
|
||||||
- index.md
|
- index.md
|
||||||
- 'User guide':
|
- 'User guide':
|
||||||
- user/concepts.md
|
|
||||||
- user/installation.md
|
- user/installation.md
|
||||||
|
- 'Concepts':
|
||||||
|
- user/concepts/part-model.md
|
||||||
|
- user/concepts/trace-model.md
|
||||||
- 'Runtime':
|
- 'Runtime':
|
||||||
|
- user/runtime/index.md
|
||||||
- user/runtime/tracing.md
|
- user/runtime/tracing.md
|
||||||
- user/runtime/mark.md
|
- user/runtime/mark.md
|
||||||
- user/runtime/distributed.md
|
- user/runtime/distributed.md
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user