1 files changed, 27 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..658e099
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+# vcpu_steal
+
+measures actual vcpu steal time from a host that's running as a
+virtual guest inside of kvm, like a vps from most common providers.
+we do this by busy-looping a cycle counter on a singular pinned vcpu,
+trying to find gaps between any iteration that count as a preemption
+by the hypervisor.
+
+usually the actual steal time is not exposed on cheap vps providers,
+and even more expensive providers, and the value in `/proc/stat`
+which should represent it is often just empty.
+since we fully pin a single cpu and run a busy loop, the only events
+that can interrupt us are guest-kernel preemption (timer ticks, irqs)
+and the host stealing our vcpu. the guest-kernel events are short and
+usually sub-microsecond or just a little higher, so our 5us threshold
+for found gaps filters them out as noise, leaving the host preemption
+as the primary thing producing the longer gaps we measure.
+this results in an error of +1-2% at the absolute most.
+
+reports the cycle counter gap value, alongside the kernel wall vs.
+cpu time for comparison.
+note that the guest kernel doesn't really know what's going on and
+thinks that any time stolen from a task by the hypervisor belongs
+to the running task, thus this is only here to contrast the tested
+value we compute.
+
+usage: `./vcpu_steal [seconds] [cpu]`