6d20c5cb2c787bfbb2165b1bab81b49a5bed9ebc
[babeltrace.git] / tests / data / plugins / flt.lttng-utils.debug-info / README.md
1 debug-info-data
2 ==============
3
4 This directory contains pre-generated ELF and DWARF files used to test
5 the debug info analysis feature, including lookup of DWARF debugging
6 information via build ID and debug link methods, as well as the source
7 files used to generate them.
8
9 The generated files are:
10
11 * `ARCH/dwarf_full/libhello_so` (ELF and DWARF)
12 * `ARCH/elf_only/libhello_so` (ELF only)
13 * `ARCH/build_id/libhello_so` (ELF with separate DWARF via build ID)
14 * `ARCH/build_id/.build-id/cd/d98cdd87f7fe64c13b6daad553987eafd40cbb.debug` (DWARF for build ID)
15 * `ARCH/debug_link/libhello_so` (ELF with separate DWARF via debug link)
16 * `ARCH/debug_link/libhello_so.debug` (DWARF for debug link)
17
18 We use a suffix of "_so" instead of ".so" since some distributions
19 build systems will consider ".so" files as artifacts from a previous
20 build that were "left-over" and will remove them prior to the build.
21
22 All files are generated from the four (4) following source files:
23
24 * libhello.c
25 * libhello.h
26 * tp.c
27 * tp.h
28
29 The generated executables were built using a native GNU toolchain on either
30 Ubuntu 16.04 or 18.04 depending on the architecture.
31
32 To regenerate them, you can use the included Makefile or follow these steps:
33
34 ## Generate the object files
35
36 $ gcc -gdwarf -fdebug-prefix-map=$(pwd)=. -fPIC -c -I. tp.c libhello.c
37
38 ## Combined ELF and DWARF
39
40 $ build_id_prefix=cd
41 $ build_id_suffix=d98cdd87f7fe64c13b6daad553987eafd40cbb
42 $ build_id="$build_id_prefix$build_id_suffix"
43 $ mkdir dwarf_full
44 $ gcc -shared -g -llttng-ust -ldl -Wl,-soname,libhello.so -Wl,--build-id=0x$build_id -o dwarf_full/libhello_so tp.o libhello.o
45
46 ## ELF only
47
48 $ mkdir elf_only
49 $ objcopy -g dwarf_full/libhello_so elf_only/libhello_so
50 $ objcopy --remove-section=.note.gnu.build-id elf_only/libhello_so
51
52 ## ELF and DWARF with Build ID
53
54 $ mkdir -p build_id/.build-id/$build_id_prefix
55 $ objcopy --only-keep-debug dwarf_full/libhello_so build_id/.build-id/$build_id_prefix/$build_id_suffix.debug
56 $ objcopy -g dwarf_full/libhello_so build_id/libhello_so
57
58 ## ELF and DWARF with Debug Link
59
60 $ mkdir debug_link
61 $ objcopy --remove-section=.note.gnu.build-id dwarf_full/libhello_so debug_link/libhello_so
62 $ objcopy --only-keep-debug debug_link/libhello_so debug_link/libhello_so.debug
63 $ objcopy -g debug_link/libhello_so
64 $ cd debug_link && objcopy --add-gnu-debuglink=libhello_so.debug libhello_so && cd ..
65
66
67 Test program
68 ------------
69 The trace provided in `tests/data/ctf-traces/succeed/debug-info/` was generated
70 using lttng-ust in a LTTng session configured to contain only the bare minimum
71 to do the debug-info resolution. You can generate such trace by following these
72 steps:
73
74 1. Compile the example binary:
75 $ ln -s x86_64-linux-gnu/dwarf_full/libhello_so libhello.so
76 $ gcc -I. -o debug_info_app main.c -L. -lhello -llttng-ust -ldl -Wl,--rpath=.
77
78 2. In order to have paths to binary and shared objects that are not relative
79 to the file system they were built on, we used a simple trick of copying
80 the following files to the root directory ('/') like this:
81
82 $ sudo cp x86_64-linux-gnu/dwarf_full/libhello_so /libhello_so
83 $ sudo cp ./debug_info_app /
84
85 3. Create symbolic link to the `/libhello_so` file with the `/libhello.so` name.
86 $ sudo ln -s /libhello_so /libhello.so
87
88 4. Create the LTTng tracing session using the following commands:
89 $ cd /
90 $ sudo lttng create
91 $ sudo lttng add-context -u -t vpid -t ip
92 $ sudo lttng enable-event -u my_provider:my_first_tracepoint
93 $ sudo lttng enable-event -u lttng_ust_statedump:bin_info --filter='path=="/libhello_so"'
94 $ sudo lttng enable-event -u lttng_ust_statedump:bin_info --filter='path=="[linux-vdso.so.1]"'
95 $ sudo lttng start
96 $ sudo /debug_info_app
97 $ sudo lttng stop
98
99 5. Copy the resulting trace back into the Babeltrace repository.
100
101 When running babeltrace with the `--debug-info-target-prefix` option or
102 `target-prefix` component paramater set to the directory containing the right
103 `libhello_so` file. In the example used above, the `libhello_so` file is in the
104 `x86_64-linux-gnu/dwarf_full/` directory.
105 In the printed trace, the `my_provider:my_first_tracepoint` events should
106 contain information similar to this:
107
108 debug_info = { bin = "libhello_so+0x2349", func = "foo+0xd2", src = "libhello.c:35" }
This page took 0.03198 seconds and 3 git commands to generate.