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 <abusque@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/debuginfo.txt b/doc/debuginfo.txt
index cae41349728aee6faa2289d71745d139ac6f37ff..98ab1f68230654ad1e87e30e6596c8d7b77afaae 100644 (file)
--- 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/.