From: Antoine Busque Date: Wed, 27 Apr 2016 20:58:30 +0000 (-0400) Subject: Docs: update debuginfo doc X-Git-Tag: v1.4.0-rc1~41 X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=a85d5bcc49c8f339affbb764365245697a0f15b8 Docs: update debuginfo doc Update the output format in the examples and document the new --debug-info-target-prefix and --debug-info-full-path command line options. Signed-off-by: Antoine Busque Signed-off-by: Jérémie Galarneau --- diff --git a/doc/debuginfo.txt b/doc/debuginfo.txt index cae41349..98ab1f68 100644 --- a/doc/debuginfo.txt +++ b/doc/debuginfo.txt @@ -92,19 +92,20 @@ extra source location information if it can find it. A sample output may look like this: [...] - [19:53:41.648394410] (+0.000022616) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB4D4, debug_info = { func = "foo", source_loc = "/home/efficios/example/libhello.c:7" }, vpid = 25577 }, { my_string_field = "hello, tracer", my_integer_field = 42 } - [19:53:41.648423786] (+0.000029376) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB5A6, debug_info = { func = "bar", source_loc = "/home/efficios/example/libhello.c:13" }, vpid = 25577 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 } - [19:53:41.648435726] (+0.000011940) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB66B, debug_info = { func = "baz", source_loc = "/home/efficios/example/libhello.c:20" }, vpid = 25577 }, { some_field = 1729 } + [16:18:15.845829429] (+0.000011697) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D550E, debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9", src = "libhello.c:7" }, vpid = 28719 }, { my_string_field = "hello, tracer", my_integer_field = 42 } + [16:18:15.845841484] (+0.000012055) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D55E0, debug_info = { bin = "libhello.so+0x15e0", func = "bar+0xa9", src = "libhello.c:13" }, vpid = 28719 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 } + [16:18:15.845844852] (+0.000003368) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D56A5, debug_info = { bin = "libhello.so+0x16a5", func = "baz+0x9c", src = "libhello.c:20" }, vpid = 28719 }, { some_field = 1729 } [...] The interesting part is the debug_info section of the context: - debug_info = { func = "foo", source_loc = "/home/efficios/example/libhello.c:7" } + debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9", src = "libhello.c:7" } This is the expected output for events generated by an executable for -which DWARF information is available. It shows the name of the -function containing the tracepoint instance which generated the event -("foo"), and its source location ("libhello.c", line 7). +which DWARF information is available. It shows the name of the binary +and offset to the tracepoint, the name of the function containing the +tracepoint instance which generated the event ("foo") and the offset +within the function, and its source location ("libhello.c", line 7). The second event in the sample output is of the same type ("my_first_tracepoint"), but it was generated by a different @@ -116,15 +117,21 @@ The third event, of a different type, also shows debug information. If DWARF info is absent, but ELF symbols are not stripped, the output will instead look like this: - [...] - [19:53:41.648394410] (+0.000022616) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB4D4, debug_info = { func = "foo+0xa9" }, vpid = 25577 }, { my_string_field = "hello, tracer", my_integer_field = 42 } - [19:53:41.648423786] (+0.000029376) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB5A6, debug_info = { func = "bar+0xa9" }, vpid = 25577 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 } - [19:53:41.648435726] (+0.000011940) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB66B, debug_info = { func = "baz+0x9c" }, vpid = 25577 }, { some_field = 1729 } - [...] + [...] + [16:18:15.845829429] (+0.000011697) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D550E, debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9" }, vpid = 28719 }, { my_string_field = "hello, tracer", my_integer_field = 42 } + [16:18:15.845841484] (+0.000012055) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D55E0, debug_info = { bin = "libhello.so+0x15e0", func = "bar+0xa9" }, vpid = 28719 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 } + [16:18:15.845844852] (+0.000003368) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D56A5, debug_info = { bin = "libhello.so+0x16a5", func = "baz+0x9c" }, vpid = 28719 }, { some_field = 1729 } + [...] + +The debug information now provides both binary and function location +information, but no source location information, as this requires +DWARF. The function names are in fact resolved using ELF symbols, so +there may be a discrepancy with those provided by DWARF (e.g. in the +case of mangling). -The debug information now provides only the function name as given by -ELF symbols, plus an offset in bytes from the symbol to the actual -location of the tracepoint instance. +Paths to the binary and to the source location (if any) can be +expanded by using the command-line option +--debug-info-full-path. Otherwise, only the filename is shown. Debug Info and Dynamic Loading ------------------------------ @@ -164,17 +171,19 @@ ID method in the standard /usr/lib/debug/.build-id/ location, and finally in the various possible debug link locations. The first debug information file found is used. -Debug Info Directory --------------------- +The --debug-info-dir command-line option can be used to override the +default /usr/lib/debug/ directory used in build ID and debug link +lookups. Multiple debug info directories are currently not supported. -When performing debug info analysis, babeltrace uses an executable's -path from when it was traced to resolve debug information. If, -however, the trace was taken on a different machine, or the executable -was simply moved since the trace was taken, it is possible to override -the base path from which to look for the debug information. To do so, -the --debug-info-dir babeltrace command-line flag is available. - -If a --debug-info-dir value is given, it will replace the default -/usr/lib/debug path used in build ID and debug link lookups. +Target Prefix +------------- -Note that multiple debug directories are not currently supported. +The debug info analysis uses the paths to the executables as collected +during tracing as one mechanism to resolve DWARF or ELF +information. If the trace was taken on a separate machine, for +instance, it is possible to use --debug-info-target-prefix to specify +a prefix directory, representing the root of the target filesystem, +which will then be used for lookups. For example, if an executable was +located at /usr/bin/foo on the target system, it could be placed at +/home/efficios/target/usr/bin/foo on the system on which the analysis +is performed. In this case, the prefix is /home/efficios/target/.