# 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.

## Dependency graph

![Dependency graph - see the corresponding directory](https://git.tobast.fr/m2-internship/abstract/raw/master/dependency_graph/deps.png)

## 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`.