[lttng-ust.git] / tests / unit / ust-elf / README.md

lttng_ust_elf unit tests
========================

This is a series of unit tests for LTTng UST's ELF parser. The parser
is used to retrieve memory size, build ID, and debug link information
from ELF objects (standalone executable or shared object) for base
address statedump or dl events.

The parser should technically be able to read ELF files from any 32-
or 64-bit architecture, little- or big- endian.

However, to restrict the total amount of testing done, only 4
architectures representing all combinations of bitness and endianness
are currently tested:

* x86
* x86_64
* armeb
* aarch64_be

For each architecture, there is a corresponding subdirectory under
`data`, and each of these directories contains exactly 2 files,
`main.elf` and `main.elf.debug`.

The ELF files are generated from the trivial `main.c` program found in
`data/`, using GNU toolchains. The program contains a static array in
order to ensure the creation of a `.bss` section in the ELF file,
which is one of the multiple factors leading to different file and
in-memory size.

The program is compiled with `gcc -g main.c -o main.elf`. On certain
architectures, it is necessary to explicitly specify the
`-Wl,--build-id=sha1` flags to include a build ID in the resulting
executable.

The debug information bundled in `main.elf` is then copied into
`main.elf.debug` and stripped, and a debug link pointing to this file
is added to the executable. The commands used are as follow:

    $ objcopy --only-keep-debug main.elf main.elf.debug
    $ strip -g main.elf
    $ objcopy --add-gnu-debuglink=main.elf.debug main.elf

There is also a series of tests used to check detection of
position-independent code (PIC). These tests use three pre-compiled
ELF files found under `data/pic/`, namely `hello.exec`, `hello.pie`,
and `hello.pic`. These can be re-generated using the files `hello.c`
and `libhello.c`, with the following commands:

    $ gcc hello.c -o hello.exec
    $ gcc hello.c -fPIC -pie -o hello.pie
    $ gcc -shared -o hello.pic -fPIC libhello.c
Commit	Line	Data
22609c7a AB	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
968f523d AB	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