Expand README with more useful information HEAD main

Signed-off-by: Mel <mel@rnrd.eu>

1 files changed, 52 insertions, 1 deletions

diff --git a/README.md b/README.md
index 658e099..83a609d 100644
--- a/README.md
+++ b/README.md
@@ -24,4 +24,55 @@ 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]`
+## building
+
+```bash
+make
+
+./vcpu_steal
+```
+
+requirements: any c compiler, make
+
+## supported platforms
+
+this utility only works on linux!
+we use `sched_setaffinity` and `cpu_set_t` for cpu pinning, both
+linux-specific, hence the linux requirement.
+
+both `x86_64` (uses `rdtscp`) and `aarch64` (uses `cntvct_el0`) are supported.
+
+## usage
+
+```bash
+./vcpu_steal [seconds] [cpu]
+```
+
+we run for **10 seconds**, on **cpu 0** by default if arguments not given.
+
+## output
+
+a 5-second run on vcpu 0 of a severely oversold vps:
+
+```
+ran at 2.795 GHz, for 117653562 iterations!
+
+kernel says:   3.108% stolen (wall=5000.04ms, cpu=4844.63ms, diff=155.41ms)
+we say:        24.093% stolen (gaps=11607, total=1204.67ms, max=78.164ms)
+
+histogram:
+    <10us     =   2369
+    10-50us   =   7572
+    50-100us  =    570
+    100-500us =    891
+    500us-1ms =     95
+    1-5ms     =     73
+    5-10ms    =     19
+    >=10ms    =     18
+```
+
+the kernel reports only **3% stolen** due to it not having access to the
+paravirtualized steal-time model-specific register.
+
+our detected value reports **24% stolen**, with one gap managing to last
+for a whole 78ms! pretty bad!