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

<!--
SPDX-FileCopyrightText: 2016 Antoine Busque <abusque@efficios.com>

SPDX-License-Identifier: CC-BY-4.0
-->

# 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
e03d7c66 MJ	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
22609c7a AB	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
e03d7c66	22	* x86\_64
22609c7a	23	* armeb
e03d7c66	24	* aarch64\_be
22609c7a AB	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
e03d7c66 MJ	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	```
968f523d AB	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
e03d7c66 MJ	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	```