tests/ust-elf/README.md

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