From 209e66850556e877b4bff92d58b3568d5a1b9266 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophile=20Bastian?= <contact@tobast.fr>
Date: Tue, 15 May 2018 18:13:09 +0200
Subject: [PATCH] Add READMEs

---
 README.md     |  9 +++++++++
 src/README.md | 25 +++++++++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 src/README.md

diff --git a/README.md b/README.md
index e63c2bd..a0527cb 100644
--- a/README.md
+++ b/README.md
@@ -18,3 +18,12 @@ As of now, this project relies on the following libraries:
 
 These libraries are expected to be installed somewhere your compiler can find
 them.
+
+## Scripts and directories
+
+* `./generate_eh_elf.py`: generate `.eh_elf.so` files for a binary (and its
+  dependencies if required)
+* `./compare_sizes.py`: compare the sizes of the `.eh_frame` of a binary (and
+  its dependencies) with the sizes of the `.text` of the generated ELFs.
+* `./extract_pc.py`: extracts a list of valid program counters of an ELF and
+  produce a file as read by `dwarf-assembly`
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000..df1e81e
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,25 @@
+# Dwarf-assembly
+
+Generates C code from the DWARF embedded in an ELF file. This code can then be
+compiled into a .so, and used to unwind stack frames.
+
+## Options
+
+### Switch generation policy
+
+The code can either generate one big `switch` statement for every PC in the
+ELF, or one `switch` and a function per FDE, plus a lookup function.
+
+One of the two options must be passed:
+
+* `--switch-per-func`: one `switch` and function per FDE;
+* `--global-switch`: a single big `switch` for the whole ELF.
+
+### PC list
+
+Instead of generating interval switches (eg `case 0x42 ... 0x100`), it is
+possible to provide a binary file (generated by `../extract_pc.py`) containing
+a list of all PCs in the ELF. The file contains one 8-bytes chunk per PC,
+which is the PC in little endian.
+
+`--pc-list PC_LIST_FILE_PATH`