Fix some documentation problems

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) {

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.

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)

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;
+}

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/).
 

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:
 
-<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
 

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

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