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:
 
     [...]
 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:
 
     [...]
 
 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
 
 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
 
 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:
 
 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
 ------------------------------
 
 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.
 
 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/.