Fix some documentation problems

This commit is contained in:
Rodrigo Arias 2022-08-29 17:10:38 +02:00
parent cf0ca35769
commit 135f3dc7aa
13 changed files with 66 additions and 23 deletions

View File

@ -105,14 +105,14 @@ state.
The channels can be updated in three ways:
1) A fixed state can be set to the channel using `chan_set()`, which
1. A fixed state can be set to the channel using `chan_set()`, which
overrides the previous state.
2) The new state can be stored in a stack with `chan_push()` and
2. The new state can be stored in a stack with `chan_push()` and
`chan_pop()`, to remember the history of the previous states. The
emitted event will be the one on the top.
3) Using a punctual event.
3. Using a punctual event.
Setting the channel state is commonly used to track quantities such as
the number of threads running per CPU. While the stack mode is commonly
@ -133,7 +133,7 @@ An example program may be instrumented like this:
instr("Xf]");
}
Then, in the emulator, when processing the events "Xf[" and "Xf]", we
Then, in the emulator, when processing the events `Xf[` and `Xf]`, we
could track of the state as follows:
int hook_pre_foo(struct ovni_chan *chan, int value) {

View File

@ -1,9 +1,9 @@
# Emulation overview
The emulator reads the events stored during runtime and reconstructs the
execution, restoring the state of each thread and CPU as time evolves. During
the emulation process, a detailed trace is generated with the state of the
execution in the Paraver PRV format.
The emulator `ovniemu` reads the events stored during runtime and
reconstructs the execution, restoring the state of each thread and CPU
as time evolves. During the emulation process, a detailed trace is
generated with the state of the execution in the Paraver PRV format.
The emulator has an execution model to represent the real execution that
happened on the hardware. It consists of CPUs which can execute multiple threads
@ -24,3 +24,18 @@ that use the same CPUs in a single node are grouped into looms.
The task model includes the information of MPI and tasks of the
programming model (OmpSs-2).
## Design considerations
The emulator tries to perform every posible check to detect if there is
any inconsistency in the received events from the runtime trace. When a
problem is found, the emulation is aborted, forcing the user to report
the problem. No effort is made to let the emulator recover from an
inconsistency.
The emulator critical path is kept as simple as possible, so the
processing of events can keep the disk writting as the bottleneck.
The linter mode enables more tests which are disabled from the default
mode to prevent costly operations running in the emulator by default.
The linter tests are enabled when running the ovni testsuite.

View File

@ -2,4 +2,4 @@
The ovni model tracks the state of threads and cpus.
![Thread states](ovni-thread-model.png)
![Thread states](thread-model.png)

View File

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 58 KiB

17
doc/extra.css Normal file
View File

@ -0,0 +1,17 @@
.rst-content code {
color: inherit;
font-size: 85%;
border: none;
padding: 0px;
background: #f8f8f8;
}
.rst-content pre code {
color: inherit;
font-size: 80%;
line-height: 1.5em;
}
p {
line-height: 1.5em;
}

View File

@ -9,6 +9,10 @@ Instrumentation project.
unless the grammar rules suggest otherwise, such as starting a
new sentence.
The ovni project implements a fast instrumentation library that records
small events (starting at 12 bytes) during the execution of programs to
later investigate how the execution happened.
The instrumentation process is split in two stages: [runtime](runtime)
tracing and [emulation](emulation/).

View File

@ -1,9 +1,13 @@
# Trace specification version 1
# Trace specification
!!! Note
Thie is the trace specification for the version 1
The ovni instrumentation library stores the information collected in a
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
`loom.`. The name of the loom is built from the `loom` parameter of
`ovni_proc_init()`, prefixing it with `loom.`.
@ -79,7 +83,7 @@ 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"/>
<img src="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:
@ -120,7 +124,7 @@ bytes:
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="event-normal.svg" alt="Normal event without payload" width="400px"/>
Another example of a normal event with 16 bytes of payload, a total of
28 bytes:
@ -132,7 +136,7 @@ ff ff ff ff 00 00 00 00 00 00 00 00 |............|
In the following figure you can see each field annotated:
<img src="fig/event-normal-payload.svg" alt="Normal event with payload content" width="400px"/>
<img src="event-normal-payload.svg" alt="Normal event with payload content" width="400px"/>
## Jumbo events
@ -157,7 +161,7 @@ data:
In the following figure you can see each field annotated:
<img src="fig/event-jumbo.svg" alt="Jumbo event" width="400px"/>
<img src="event-jumbo.svg" alt="Jumbo event" width="400px"/>
## Design considerations

View File

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

View File

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

View File

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

View File

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View File

@ -1,23 +1,24 @@
# Tracing a program with ovni
# Tracing a program
Read carefully this document before using libovni to generate a trace.
## Mark the start and end of processes and threads
## Trace processes and threads
Call `ovni_proc_init()` when a new program begins the execution.
- Call `ovni_proc_init()` when a new process begins the execution.
Call `ovni_thread_init()` when a new thread begins the execution
- Call `ovni_thread_init()` when a new thread begins the execution
(including the main process thread). Call `ovni_flush()` and
`ovni_thread_free()` when it finishes.
`ovni_thread_free()` when it finishes (in that order).
Call `ovni_proc_fini()` when the program ends, after all threads have
- Call `ovni_proc_fini()` when a process ends, after all threads have
finished.
You can use `ovni_ev_emit()` to record a new event. If you need more
than 16 bytes of payload, use `ovni_ev_jumbo_emit()`.
than 16 bytes of payload, use `ovni_ev_jumbo_emit()`. See the [trace
specification](../trace_spec) for more details.
Compile and link with libovni. When you run your program, a new
directory ovni will be created in the current directory ($PWD/ovni)
directory ovni will be created in the current directory `$PWD/ovni`
which contains the execution trace.
## Rules

View File

@ -1,6 +1,7 @@
site_name: ovni
theme: readthedocs
docs_dir: doc
extra_css: [extra.css]
markdown_extensions:
- admonition
- toc:
@ -11,6 +12,7 @@ nav:
- 'Runtime':
- runtime/tracing.md
- runtime/kernel.md
- runtime/trace_spec.md
- 'Emulation':
- emulation/index.md
- emulation/ovni.md