From d315110364ec0ff9fe50b4d05268e6b7660209c9 Mon Sep 17 00:00:00 2001
From: Florian Fischer <florian.fl.fischer@fau.de>
Date: Sun, 10 Feb 2019 17:53:43 +0100
Subject: Update Readme.md

---
 Readme.md | 46 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

(limited to 'Readme.md')

diff --git a/Readme.md b/Readme.md
index 50dd5b0..420055d 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,22 +1,30 @@
-# allocbench - benchmark tool for memory allocators
+# allocbench - benchmark tool for POSIX memory allocators
 
-to download allocbench just run
+To download allocbench run
 
 ```shell
 git clone https://muhq.space/software/allocbench.git
 ```
 
+## Requirements
+
+* python3
+* perf (`perf stat -d` is the default command to measure benchmark results)
+* util-linux (`whereis` is used to find system installed allocators)
+* (git to clone allocators in `allocators/{no_falsesharing, BA_allocators}.py`)
+
+
 ## Usage
 
 	usage: bench.py [-h] [-s] [-l LOAD] [-a ALLOCATORS] [-r RUNS] [-v]
-	                [-b BENCHMARKS [BENCHMARKS ...]] [-ns] [-sd RESULTDIR]
+	                [-b BENCHMARKS [BENCHMARKS ...]] [-ns] [-rd RESULTDIR]
 	                [--license]
 
 	benchmark memory allocators
 
 	optional arguments:
 	  -h, --help            show this help message and exit
-	  -s, --save            save benchmark results to disk
+	  -s, --save            save benchmark results in RESULTDIR
 	  -l LOAD, --load LOAD  load benchmark results from directory
 	  -a ALLOCATORS, --allocators ALLOCATORS
 	                        load allocator definitions from file
@@ -25,10 +33,38 @@ git clone https://muhq.space/software/allocbench.git
 	  -b BENCHMARKS [BENCHMARKS ...], --benchmarks BENCHMARKS [BENCHMARKS ...]
 	                        benchmarks to run
 	  -ns, --nosum          don't produce plots
-	  -sd RESULTDIR, --resultdir RESULTDIR
+	  -rd RESULTDIR, --resultdir RESULTDIR
 	                        directory where all results go
 	  --license             print license info and exit
 
+### Examples
+
+	./bench.py -b loop
+
+runs only the loop benchmark for some installed allocators and will put its
+results in `$PWD/results/$HOSTNAME/<time>/loop`
+
+	./bench.py -a allocators/BA_allocators.py
+
+builds all allocators used in my [BA thesis](muhq.space/ba.html) and runs all
+default benchmarks
+
+	./bench.py -r 0 -l <path/to/saved/results>
+
+doesn't run any benchmark just summarizes the loaded results
+
+## Benchmarks
+
+You want to compare allocators with your own software or add a new benchmark,
+have a look at [doc/Benchmarks.md]().
+
+## Allocators
+
+By default tcmalloc, jemalloc, Hoard and your libc's allocator will be used
+if found and the `-a` option is not used.
+
+For more control about used allocators have a look at [doc/Allocators.md]().
+
 ## License
 
 This program is released under GPLv3. You can find a copy of the license
-- 
cgit v1.2.3