diff --git a/README.md b/README.md
index b99b01d2fb2b3893a24ca27a0ce55fb6df8d30ba..47f366cb384bc20ad16b65836957d4ce612f490f 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,73 @@
 # Cargo call-stack
-A cargo sub-commond for spanning the call stack for a `cortex-m` bare metal application.
+
+A cargo subcommand for spanning the call stack for a `cortex-m` bare metal application.
+
+## Requirements
+
+- A recent (Edition 2018) Rust toolchain.
+- LLVM `opt` tool, as distributed in the arch-linux LLVM package. As the tool uses `opt` to operate on the underlying `llvm-ir` we can give no compatibility guarantees if `opt` version differs to the `rustc` LLVM backend. The tool has been tested to work with LLVM `opt` 7.0, while the Rust toolchain has already moved to the LLVM 8.0 preview.
 
 ## Installing
-> cargo install --path <PATH_TO cargo-call-stack> -f
+
+> cargo install --path <PATH_TO cargo-call-stack> 
+
+If already installed, `-f` to force re-installation of the subcommand.
 
 ## Usage
-Assume we have have an existing `cortex-m` bare metal application, e.g., ...
+
+Assume we have have an existing `cortex-m` bare metal application:
+
+> cargo call-stack --release
+
+for analysing a crate, or
 
 > cargo call-stack --release --example hello1
 
+for analysing an example.
+
+- The `stdout` output gives the call-graph in `dot` format.
+- The `stderr` output gives additional information, mainly for debugging purposes.
+
+## Errors
+
+``` sh
+cargo call-stack --example hello2  --release > callgraph.dot
+
+...
+Out { hash: None, crate_name: None, out_dir: None }
+thread 'main' panicked at '--out-dir missing', libcore/option.rs:1008:5
+note: Run with `RUST_BACKTRACE=1` for a backtrace.
+```
+
+In this case, `rustc` did not recompile the crate (or example), and thus we cannot determine the output directory. This can be solved by forcing recompilation (e.g. by touching the respective source file.)
+
+``` sh
+cargo call-stack --examples  --release > callgraph.dot
+start sub command
+"cargo" "rustc" "--examples" "--release" "-v" "--color=always" "--" "-C" "lto" "--emit=llvm-bc,llvm-ir" "-Z" "emit-stack-sizes"
+error: extra arguments to `rustc` can only be passed to one target, consider filtering
+the package by passing e.g. `--lib` or `--bin NAME` to specify a single target
+thread 'main' panicked at 'assertion failed: status.success()', src/main.rs:228:13
+note: Run with `RUST_BACKTRACE=1` for a backtrace.
+```
+
+In this case `rustc` will abort, as extra arguments cannot be parsed to multiple targets. This problem is solved by giving a single target (see Usage above).
+
+``` sh
+cargo call-stack  > callgraph.dot
+...
+error: can't perform LTO when compiling incrementally
+```
+
+In this case `rustc` fails, as we require LTO optimization in order to achieve a single (monolithic) LLVM-IR for the call-graph analysis. This problem is solved by adding the `--release` flag (see Usage above).
+
+
+
 ## Tech notes
 
 ### Cargo sub-commands
 
-Cargo allows third party sub-commands to be installed, giving extended functionality to the build system. The crate name for a sub command should be pre-fixed with "cargo-X", X being the command name, in this case "cargo-call-stack". For further information see, ...
+Cargo allows third party sub-commands to be installed, giving extended functionality to the build system. The crate name for a subcommand should be pre-fixed with "cargo-X", X being the command name, in this case "cargo-call-stack". For further information see, ...
 
 ### Paths
 
@@ -37,4 +91,14 @@ the package by passing e.g. `--lib` or `--bin NAME` to specify a single target
 
 ```
 
-This is fine Since we are interested in analysing a single application. This error is reported directly by `rustc`  (not by the `call-stack` command). 
+This is fine Since we are interested in analysing a single application. This error is reported directly by `rustc`  (not by the `call-stack` command).
+
+## Todo
+
+### Usabililty improvements
+
+- forcing rebuild or find the current hash somehow (perhaps by date of generated files, if re-compilation is not done (can be checked))
+
+### Functionality improvements
+
+- handling of trait objects
\ No newline at end of file