| 1 | <!-- |
| 2 | SPDX-FileCopyrightText: 2016 Antoine Busque <abusque@efficios.com> |
| 3 | |
| 4 | SPDX-License-Identifier: CC-BY-4.0 |
| 5 | --> |
| 6 | |
| 7 | # lttng\_ust\_elf unit tests |
| 8 | |
| 9 | This is a series of unit tests for LTTng UST's ELF parser. The parser |
| 10 | is used to retrieve memory size, build ID, and debug link information |
| 11 | from ELF objects (standalone executable or shared object) for base |
| 12 | address statedump or dl events. |
| 13 | |
| 14 | The parser should technically be able to read ELF files from any 32- |
| 15 | or 64-bit architecture, little- or big- endian. |
| 16 | |
| 17 | However, to restrict the total amount of testing done, only 4 |
| 18 | architectures representing all combinations of bitness and endianness |
| 19 | are currently tested: |
| 20 | |
| 21 | * x86 |
| 22 | * x86\_64 |
| 23 | * armeb |
| 24 | * aarch64\_be |
| 25 | |
| 26 | For each architecture, there is a corresponding subdirectory under |
| 27 | `data`, and each of these directories contains exactly 2 files, |
| 28 | `main.elf` and `main.elf.debug`. |
| 29 | |
| 30 | The ELF files are generated from the trivial `main.c` program found in |
| 31 | `data/`, using GNU toolchains. The program contains a static array in |
| 32 | order to ensure the creation of a `.bss` section in the ELF file, |
| 33 | which is one of the multiple factors leading to different file and |
| 34 | in-memory size. |
| 35 | |
| 36 | The program is compiled with `gcc -g main.c -o main.elf`. On certain |
| 37 | architectures, it is necessary to explicitly specify the |
| 38 | `-Wl,--build-id=sha1` flags to include a build ID in the resulting |
| 39 | executable. |
| 40 | |
| 41 | The debug information bundled in `main.elf` is then copied into |
| 42 | `main.elf.debug` and stripped, and a debug link pointing to this file |
| 43 | is added to the executable. The commands used are as follow: |
| 44 | |
| 45 | ``` |
| 46 | $ objcopy --only-keep-debug main.elf main.elf.debug |
| 47 | $ strip -g main.elf |
| 48 | $ objcopy --add-gnu-debuglink=main.elf.debug main.elf |
| 49 | ``` |
| 50 | |
| 51 | There is also a series of tests used to check detection of |
| 52 | position-independent code (PIC). These tests use three pre-compiled |
| 53 | ELF files found under `data/pic/`, namely `hello.exec`, `hello.pie`, |
| 54 | and `hello.pic`. These can be re-generated using the files `hello.c` |
| 55 | and `libhello.c`, with the following commands: |
| 56 | |
| 57 | ``` |
| 58 | $ gcc hello.c -o hello.exec |
| 59 | $ gcc hello.c -fPIC -pie -o hello.pie |
| 60 | $ gcc -shared -o hello.pic -fPIC libhello.c |
| 61 | ``` |