tests/unit/ust-elf/README.md

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