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 parameter 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" }