diff --git a/doc/emulation/channels.md b/doc/emulation/channels.md index abdba51..b6a29f0 100644 --- a/doc/emulation/channels.md +++ b/doc/emulation/channels.md @@ -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) { diff --git a/doc/emulation/index.md b/doc/emulation/index.md index 3f2cd94..46d9c63 100644 --- a/doc/emulation/index.md +++ b/doc/emulation/index.md @@ -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. diff --git a/doc/emulation/ovni.md b/doc/emulation/ovni.md index 3f9ddbb..2412a83 100644 --- a/doc/emulation/ovni.md +++ b/doc/emulation/ovni.md @@ -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) diff --git a/doc/emulation/ovni-thread-model.png b/doc/emulation/ovni/thread-model.png similarity index 100% rename from doc/emulation/ovni-thread-model.png rename to doc/emulation/ovni/thread-model.png diff --git a/doc/extra.css b/doc/extra.css new file mode 100644 index 0000000..9799b33 --- /dev/null +++ b/doc/extra.css @@ -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; +} diff --git a/doc/index.md b/doc/index.md index 7595b89..ab01c4a 100644 --- a/doc/index.md +++ b/doc/index.md @@ -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/). diff --git a/doc/trace_spec.md b/doc/runtime/trace_spec.md similarity index 93% rename from doc/trace_spec.md rename to doc/runtime/trace_spec.md index 85390c1..0b01f39 100644 --- a/doc/trace_spec.md +++ b/doc/runtime/trace_spec.md @@ -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: -Stream +Stream 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: -Normal event without payload +Normal event without payload 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: -Normal event with payload content +Normal event with payload content ## Jumbo events @@ -157,7 +161,7 @@ data: In the following figure you can see each field annotated: -Jumbo event +Jumbo event ## Design considerations diff --git a/doc/fig/event-jumbo.svg b/doc/runtime/trace_spec/event-jumbo.svg similarity index 100% rename from doc/fig/event-jumbo.svg rename to doc/runtime/trace_spec/event-jumbo.svg diff --git a/doc/fig/event-normal-payload.svg b/doc/runtime/trace_spec/event-normal-payload.svg similarity index 100% rename from doc/fig/event-normal-payload.svg rename to doc/runtime/trace_spec/event-normal-payload.svg diff --git a/doc/fig/event-normal.svg b/doc/runtime/trace_spec/event-normal.svg similarity index 100% rename from doc/fig/event-normal.svg rename to doc/runtime/trace_spec/event-normal.svg diff --git a/doc/fig/stream.svg b/doc/runtime/trace_spec/stream.svg similarity index 100% rename from doc/fig/stream.svg rename to doc/runtime/trace_spec/stream.svg diff --git a/doc/runtime/tracing.md b/doc/runtime/tracing.md index 22c96f3..47d70a7 100644 --- a/doc/runtime/tracing.md +++ b/doc/runtime/tracing.md @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index 9e77840..2944875 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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