Add some documentation

README.md

@@ -0,0 +1,12 @@
+# qemu-nyx-runner
+
+This repository contains the source code of `qemu-nyx-runner`,
+a tool which can be used to execute programs inside a `Nyx` hypervisor, trace them with `Intel PT`,
+and analyze the resulting trace files to estimate its execution without all this instrumentation.
+
+## Set Up
+
+To use this project, `KVM-Nyx-fork`s kernel modules have to be installed and loaded.
+use the `setup-kvm.sh` script for that.
+
+To run a program with `qemu-nyx-runner`, use `cargo r --release -- path/to/program`

client/build.rs

@@ -1,3 +1,7 @@
+//! Somewhat hacky build script for downloading and linking embench.
+//! Each benchmark is compiled individually, so that we can run them through rust
+//! and add some instrumentation around the benchmarks.
+
 use std::fmt::Write;
 use std::path::PathBuf;
 use std::process::Command;

pt-dump-decoder/src/lib.rs

@@ -30,10 +30,12 @@ pub fn analyze_dump(
     qemu_duration: Duration,
 ) -> Result<AnalyzeData, Box<dyn Error>> {
     let trace_file = File::open(path)?;
+    // Safety: We only read from the trace file, never write to it
+    // UB occurs when it is modified out-of-process, though
     let mmap = unsafe { Mmap::map(&trace_file)? };
 
     let builder = EncoderDecoderBuilder::<PacketDecoder<()>>::new();
-    // I hope this is safe if the buffer is never written to
+    // Safety: The mmap outlives the builder
     let builder = unsafe { builder.buffer_from_raw(mmap.as_ptr() as *mut _, mmap.len()) };
 
     let mut decoder = builder.build()?;

src/benchmark.rs

@@ -1,6 +1,7 @@
 use std::fmt::Debug;
 use std::io::Write;
 
+/// Used for benchmarking nyx + pt, nyx - pt, and the baseline
 pub trait Benchmark {
     const TITLE: &'static str;
 

src/benchmark_baseline.rs

@@ -5,6 +5,7 @@ use std::path::Path;
 use std::process::Command;
 use std::time::Duration;
 
+/// Executes the given program without any instrumentation
 pub struct Baseline<'a>(pub &'a Path);
 
 impl Benchmark for Baseline<'_> {

src/benchmark_nyx_no_pt.rs

@@ -3,6 +3,7 @@ use crate::nyx::{NyxRunner, TraceMode};
 use std::path::Path;
 use std::time::Duration;
 
+/// Executes the given program with nyx, but without tracing
 pub struct BenchmarkNyxNoPt(NyxRunner);
 
 impl BenchmarkNyxNoPt {

src/benchmark_nyx_pt.rs

@@ -5,6 +5,7 @@ use pt_dump_decoder::{AnalyzeData, analyze_dump};
 use std::io::Write;
 use std::path::Path;
 
+/// Executes the given program with nyx and tracing
 pub struct BenchmarkNyx(NyxRunner);
 
 impl BenchmarkNyx {