From fc21036aecbcd0375bfe38e19109ff01e67e77dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9ophile=20Bastian?= Date: Fri, 17 Aug 2018 19:55:37 +0200 Subject: [PATCH] Add README --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0054df7 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# General considerations about this internship + +The goal of this internship was to investigate and implement a compiler from +DWARF unwinding data to native assembly code. The various repositories listed +on [the git summary page](https://git.tobast.fr/m2-internship) are the various +components of the project, plus some off-topic (at various degrees) code I +wrote during the internship. + +Each repository includes a `README.md` file with detailed information about +what it does, how it is supposed to be used, etc. + +## List of repositories + +* `abstract`: this repository, provides a description/summary of the projects, + and gives insights of how they interact with each other. + +* `report`: the internship report repository, including `.tex` files, images, + source codes, etc. + +* `libunwind-eh_elf`: a fork of [libunwind](http://www.nongnu.org/libunwind/) + working with eh\_elfs, with only a slight interface change (an additional + parameter to an initialisation function). + +* `dwarf-assembly`: the compiler itself, along with benchmarking, stats and + various helper scripts. + +* `dwarf-semantics`: a subset of `report` that describes the semantics of the + compiled DWARF. **Outdated**. + +* `pkgbuilds`: contains `PKGBUILD` files for various uncommon libraries on + which `dwarf-assembly` depends. A `PKGBUILD` is a package building script + made for Archlinux. + +* `perf-eh_elf`: a fork of + [perf](https://perf.wiki.kernel.org/index.php/Main_Page) working with + `libunwind-eh_elf`. Since `perf` is originally developed within the Linux + kernel source tree, this repository was rerooted to only include + `tools/perf`. However, to be compiled, `perf` needs the other files from the + Linux source tree. See this repository's `README.md` for more details. + +* `dwarfinterpret`: a first project, providing features close to `libunwind`. + This was made as an exercise with DWARF, to better understand how it works, + at the beginning of the internship. + +* `frame-machine`: a fork of [Stephen Kell](https://www.cl.cam.ac.uk/~srk31/)'s + `frame-machine.c`. This was also made to better understand DWARF, and is a + C++ template-based unwinder. + +* `libdwarfpp-tests`: some more training codes regarding DWARF. These codes use + `libdwarfpp`, a library by [Stephen Kell](https://www.cl.cam.ac.uk/~srk31/) + that acts as a C++ wrapper for + [libdwarf](https://sourceforge.net/projects/libdwarf/). + +* `eh_frame_check_setup`: a collection of scripts to automate and ease the use + of + [`eh_frame_check`](https://github.com/francesco-zappa-nardelli/eh_frame_check), + a tool developed by + [Francesco Zappa-Nardelli](https://www.di.ens.fr/~zappa/), my advisor, to + check the consistency and correctness of the DWARF unwinding data of + arbitrary binaries. **Outdated**, as the up-to-date version can be found in + the above-mentioned Github repository. + +## Steps to setup the DWARF to assembly compiler + +* If you use Archlinux, install the three `PKGBUILD`s from `pkgbuilds`. If not, + install the three libraries `libsrk31cxx`, `libcxxfileno` and `libdwarfpp`, + all three by Stephen Kell. This can be tricky. + +* Clone the repository `dwarf-assembly` and run `make`. If the libraries from + the previous step are installed and available in standard directories, this + step should work without any particular problem. + +* From now on, you can compile `ELF`s to `eh_elf`. Follow the instructions from + `dwarf-assembly`'s `README.md`. + +* To use those `eh_elf`s, clone and build `libunwind-eh_elf`. Follow the + instructions from the `README.md`. + +* To also use `perf`, clone and build `perf-eh_elf` and follow the instructions + from the `README.md`.