Minimal usage example

README.md

@@ -4,7 +4,36 @@
 
 See [INTspect][https://gitlab.cs.fau.de/i4/intspect].
 
-## Sysfs Interface
+Here's a minimal example that demonstrates how you can benchmark softirqs from
+within a shell when INTsight has been injected into a kernel. INTspect
+essentially does exactly this, except that it gathers some additional
+information from `proc`.
+
+``` shell
+cd /sys/kernel/debug/intsight
+echo > init
+
+# Set the parameters
+echo softirq > bottom_handler
+echo 1000    > reps
+
+# Execute the benchmark
+echo > prepare_trigger
+echo > do_trigger
+echo > postprocess_trigger
+
+# Optional: Inspect the results
+head csv_results/pmccntr
+cat  reps # -> 1000
+
+# Save the results and paramerters
+cp -vrf . ~/my-insight
+```
+
+After this, `~/my-insight/csv_results` will contain the checkpoint names and
+timestamps recorded.
+
+## Sysfs Files
 
 When injected into a kernel, INTsight provides a `debugfs` interface accessible
 from user space, usually mounted in `/sys/kernel/debug/intsight`. INTspect uses
@@ -30,3 +59,13 @@ produced by INTspect.
 | csv_results/name | Read-only CSV | One line per measurement run, each line contains the checkpoint names in the encountered order for this run |
 | csv_results/* | Read-only CSVs | The recorded timestamps matching the checkpoint names in `csv_results/name` |
 | vmalloc_checkpoint_matrix | Read-only Boolean | Determine whether the checkpoint buffer was small enough to be allocated using `kmalloc()`, or whether `vmalloc()` was required |
+
+For each enabled timestamp, writing into `postprocess_trigger` creates a file in
+the `csv_results` folder. Like `csv_results/name`, this files contains one line
+per measurement run (the number of runs performed, was set before the benchmark
+by writing into `reps`).
+
+Each line in `csv_results/name` contains the checkpoint names in the encountered
+order for this run (at most `checkpoint_capacity` fields), the respective
+timestamps recorded during this checkpoint, can be found by opening the other
+files in `csv_results`, and looking in the same row/column.