From eea42459fd9d3fa42471432cd73005f50392f389 Mon Sep 17 00:00:00 2001
From: David Venhoff <david.venhoff@cs.tu-dortmund.de>
Date: Mon, 15 Sep 2025 15:59:23 +0200
Subject: [PATCH] Add some documentation

---
 README.md                  | 12 ++++++++++++
 client/build.rs            |  4 ++++
 pt-dump-decoder/src/lib.rs |  4 +++-
 src/benchmark.rs           |  1 +
 src/benchmark_baseline.rs  |  1 +
 src/benchmark_nyx_no_pt.rs |  1 +
 src/benchmark_nyx_pt.rs    |  1 +
 7 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..904a8e3
--- /dev/null
+++ b/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`
diff --git a/client/build.rs b/client/build.rs
index 28bc499..3362905 100644
--- a/client/build.rs
+++ b/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;
diff --git a/pt-dump-decoder/src/lib.rs b/pt-dump-decoder/src/lib.rs
index 156d1c4..a73bc2e 100644
--- a/pt-dump-decoder/src/lib.rs
+++ b/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()?;
diff --git a/src/benchmark.rs b/src/benchmark.rs
index 065d446..11b2b6a 100644
--- a/src/benchmark.rs
+++ b/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;
 
diff --git a/src/benchmark_baseline.rs b/src/benchmark_baseline.rs
index ccebc13..f45cf90 100644
--- a/src/benchmark_baseline.rs
+++ b/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<'_> {
diff --git a/src/benchmark_nyx_no_pt.rs b/src/benchmark_nyx_no_pt.rs
index 5d8e403..93207b9 100644
--- a/src/benchmark_nyx_no_pt.rs
+++ b/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 {
diff --git a/src/benchmark_nyx_pt.rs b/src/benchmark_nyx_pt.rs
index a3803ce..ce0112a 100644
--- a/src/benchmark_nyx_pt.rs
+++ b/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 {