[docs][llvm-symbolizer] Improve llvm-symbolizer documentation

[jhenderson]

Summary

As detailed in https://bugs.llvm.org/show_bug.cgi?id=42253, there were a number of issues in the llvm-symbolizer documentation. This patch fixes them by:

1. Adding [addresses...] to the synopsis.
2. Rewriting the description to fix grammar issues and mention other usage options.
3. Rewrite the examples to be easier to read.
4. Re-order the options into alphabetical order.
5. Improve the text of some of the option descriptions, and added some more examples.
6. Split the Mach-O options into a separate section of the document.
7. Standardized on double dashes for long options throughout the file.
8. Added a reference to the llvm-addr2line document.

[mtrent]

I wonder why the Mach-O specific commands are unlike that of other utilities ... In any case, these changes look fine.

[jhenderson]

In D63651#1555463, @mtrent wrote:

I wonder why the Mach-O specific commands are unlike that of other utilities ... In any case, these changes look fine.

Unlike in what way? Separated in the doc or something else?

[ikudrin]

docs/CommandGuide/llvm-symbolizer.rst

75

Some symbols are printed with parentheses, and some without them. I know that it is how demangling works, but it looks a bit confusing. Do you think it worth adding some explanation about that here?

[jhenderson]

Add extra notes to explain demangling differences a bit.

[ikudrin]

Thanks!

docs/CommandGuide/llvm-symbolizer.rst

 llvm-symbolizer - convert addresses into source code locations
 ==============================================================
 
 SYNOPSIS
 --------
 
-:program:`llvm-symbolizer` [options]
+:program:`llvm-symbolizer` [options] [addresses...]
 
 DESCRIPTION
 -----------
 
-:program:`llvm-symbolizer` reads object file names and addresses from standard
-input and prints corresponding source code locations to standard output.
-If object file is specified in command line, :program:`llvm-symbolizer` 
-processes only addresses from standard input, the rest is output verbatim.
-This program uses debug info sections and symbol table in the object files.
+:program:`llvm-symbolizer` reads object file names and addresses from the
+command-line and prints corresponding source code locations to standard output.
 
-EXAMPLE
+If no address is specified on the command-line, it reads the addresses from
+standard input. If no object file is specified on the command-line, but
+addresses are, or if at any time an input value is not recognized, the input is
+simply echoed to the output.
+
+A positional argument or standard input value can be preceded by "DATA" or
+"CODE" to indicate that the address should be symbolized as data or executable
+code respectively. If neither is specified, "CODE" is assumed. DATA is
+symbolized as address and symbol size rather than line number.
+
+Object files can be specified together with the addresses either on standard
+input or as positional arguments on the command-line, following any "DATA" or
+"CODE" prefix.
+
+EXAMPLES
 --------
 
+All of the following examples use the following two source files as input. They
+use a mixture of C-style and C++-style linkage to illustrate how these names are
+printed differently (see :option:`--demangle`).
+
+.. code-block:: c
+
+  // test.h
+  extern "C" inline int foz() {
+    return 1234;
+  }
+
+.. code-block:: c
+
+  // test.cpp
+  #include "test.h"
+  int bar=42;
+
+  int foo() {
+    return bar;
+  }
+
+  int baz() {
+    volatile int k = 42;
+    return foz() + k;
+  }
+
+  int main() {
+    return foo() + baz();
+  }
+
+These files are built as follows:
+
+.. code-block:: console
+
+  $ clang -g test.cpp -o test.elf
+  $ clang -g -O2 test.cpp -o inlined.elf
+
+Example 1 - addresses and object on command-line:
+
+.. code-block:: console
+
+  $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
+  foz
+  /tmp/test.h:1:0
+
+  baz()
+  /tmp/test.cpp:11:0
+
+Example 2 - addresses on standard input:
+
 .. code-block:: console
 
   $ cat addr.txt
-  a.out 0x4004f4
-  /tmp/b.out 0x400528
-  /tmp/c.so 0x710
-  /tmp/mach_universal_binary:i386 0x1f84
-  /tmp/mach_universal_binary:x86_64 0x100000f24
-  $ llvm-symbolizer < addr.txt
+  0x4004a0
+  0x400490
+  0x4004d0
+  $ llvm-symbolizer --obj=test.elf < addr.txt
   main
-  /tmp/a.cc:4
-  
-  f(int, int)
-  /tmp/b.cc:11
+  /tmp/test.cpp:15:0
+  baz()
+  /tmp/test.cpp:11:0
 
-  h_inlined_into_g
-  /tmp/header.h:2
-  g_inlined_into_f
-  /tmp/header.h:7
-  f_inlined_into_main
-  /tmp/source.cc:3
-  main
-  /tmp/source.cc:8
+  foz
+  /tmp/./test.h:1:0
 
-  _main
-  /tmp/source_i386.cc:8
+Example 3 - object specified with address:
+
+.. code-block:: console
+
+  $ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
+  baz()
+  /tmp/test.cpp:11:0
+
+  foo()
+  /tmp/test.cpp:8:10
 
-  _main
-  /tmp/source_x86_64.cc:8
   $ cat addr2.txt
-  0x4004f4
-  0x401000
-  $ llvm-symbolizer -obj=a.out < addr2.txt
+  test.elf 0x4004a0
+  inlined.elf 0x400480
+
+  $ llvm-symbolizer < addr2.txt
   main
-  /tmp/a.cc:4
+  /tmp/test.cpp:15:0
 
-  foo(int)
-  /tmp/a.cc:12
-  $cat addr.txt
-  0x40054d
-  $llvm-symbolizer -inlining -print-address -pretty-print -obj=addr.exe < addr.txt
-  0x40054d: inc at /tmp/x.c:3:3
-   (inlined by) main at /tmp/x.c:9:0
-  $llvm-symbolizer -inlining -pretty-print -obj=addr.exe < addr.txt
-  inc at /tmp/x.c:3:3
-   (inlined by) main at /tmp/x.c:9:0
+  foo()
+  /tmp/test.cpp:8:10
 
-OPTIONS
--------
+Example 4 - CODE and DATA prefixes:
 
-.. option:: -obj, -exe, -e
+.. code-block:: console
 
-  Path to object file to be symbolized.
+  $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
+  baz()
+  /tmp/test.cpp:11:0
+
+  bar
+  6295592 4
+
+  $ cat addr3.txt
+  CODE test.elf 0x4004a0
+  DATA inlined.elf 0x601028
 
-.. _llvm-symbolizer-opt-f:
+  $ llvm-symbolizer < addr3.txt
+  main
+  /tmp/test.cpp:15:0
+
+  bar
+  6295592 4
 
-.. option:: -functions [<none|short|linkage>], -f
+OPTIONS
+-------
 
-  Specify the way function names are printed (omit function name,
-  print short function name, or print full linkage name, respectively).
-  Defaults to ``linkage``.
+.. option:: --adjust-vma <offset>
 
-.. _llvm-symbolizer-opt-use-symbol-table:
+  Add the specified offset to object file addresses when performing lookups.
+  This can be used to perform lookups as if the object were relocated by the
+  offset.
 
-.. option:: -use-symbol-table
+.. option:: --basenames, -s
 
- Prefer function names stored in symbol table to function names
- in debug info sections. Defaults to true.
+  Strip directories when printing the file path.
 
 .. _llvm-symbolizer-opt-C:
 
-.. option:: -demangle, -C
+.. option:: --demangle, -C
 
- Print demangled function names. Defaults to true.
+  Print demangled function names, if the names are mangled (e.g. the mangled
+  name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
+  as is). Defaults to true.
 
-.. option:: -no-demangle
+.. option:: --dwp <path>
 
- Don't print demangled function names.
+  Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
+  debug data.
 
-.. _llvm-symbolizer-opt-i:
+.. option:: --fallback-debug-path <path>
 
-.. option:: -inlining, -inlines, -i
+  When a separate file contains debug data, and is referenced by a GNU debug
+  link section, use the specified path as a basis for locating the debug data if
+  it cannot be found relative to the object.
 
- If a source code location is in an inlined function, prints all the
- inlined frames. Defaults to true.
+.. _llvm-symbolizer-opt-f:
 
-.. option:: -default-arch
+.. option:: --functions [<none|short|linkage>], -f
 
- If a binary contains object files for multiple architectures (e.g. it is a
- Mach-O universal binary), symbolize the object file for a given architecture.
- You can also specify architecture by writing ``binary_name:arch_name`` in the
- input (see example above). If architecture is not specified in either way,
- address will not be symbolized. Defaults to empty string.
+  Specify the way function names are printed (omit function name, print short
+  function name, or print full linkage name, respectively). Defaults to
+  ``linkage``.
 
-.. option:: -dsym-hint <path/to/file.dSYM>
+.. option:: --help, -h
 
- (Darwin-only flag). If the debug info for a binary isn't present in the default
- location, look for the debug info at the .dSYM path provided via the
- ``-dsym-hint`` flag. This flag can be used multiple times.
+  Show help and usage for this command.
 
-.. option:: -print-address, -addresses, -a
+.. option:: --help-list
 
- Print address before the source code location. Defaults to false.
+  Show help and usage for this command without grouping the options into categories.
+
+.. _llvm-symbolizer-opt-i:
 
-.. option:: -pretty-print, -p
+.. option:: --inlining, --inlines, -i
 
- Print human readable output. If ``-inlining`` is specified, enclosing scope is
- prefixed by (inlined by). Refer to listed examples.
+  If a source code location is in an inlined function, prints all the inlined
+  frames. Defaults to true.
 
-.. option:: -basenames, -s
+.. option:: --no-demangle
 
- Strip directories when printing the file path.
+  Don't print demangled function names.
 
-.. option:: -adjust-vma <offset>
+.. option:: --obj <path>, --exe, -e
 
- Add the specified offset to object file addresses when performing lookups. This
- can be used to perform lookups as if the object were relocated by the offset.
+  Path to object file to be symbolized. If ``-`` is specified, read the object
+  directly from the standard input stream.
 
 .. _llvm-symbolizer-opt-output-style:
 
-.. option:: -output-style <LLVM|GNU>
+.. option:: --output-style <LLVM|GNU>
 
   Specify the preferred output style. Defaults to ``LLVM``. When the output
   style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
   The differences from the ``LLVM`` style are:
   
   * Does not print column of a source code location.
 
   * Does not add an empty line after the report for an address.
 
   * Does not replace the name of an inlined function with the name of the
-    topmost caller when inlined frames are not shown and ``-use-symbol-table``
+    topmost caller when inlined frames are not shown and :option:`--use-symbol-table`
     is on.
 
   .. code-block:: console
 
-    $ llvm-symbolizer -p -e=addr.exe 0x40054d 0x400568
-    inc at /tmp/x.c:3:3
-     (inlined by) main at /tmp/x.c:14:0
+    $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
+    baz() at /tmp/test.cpp:11:18
+     (inlined by) main at /tmp/test.cpp:15:0
 
-    main at /tmp/x.c:14:3
+    foo() at /tmp/test.cpp:6:3
 
-    $ llvm-symbolizer --output-style=LLVM -p -i=0 -e=addr.exe 0x40054d 0x400568
-    main at /tmp/x.c:3:3
+    $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
+    main at /tmp/test.cpp:11:18
 
-    main at /tmp/x.c:14:3
+    foo() at /tmp/test.cpp:6:3
 
-    $ llvm-symbolizer --output-style=GNU -p -i=0 -e=addr.exe 0x40054d 0x400568
-    inc at /tmp/x.c:3
-    main at /tmp/x.c:14
+    $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
+    baz() at /tmp/test.cpp:11
+    foo() at /tmp/test.cpp:6
+
+.. option:: --pretty-print, -p
+
+  Print human readable output. If :option:`--inlining` is specified, the
+  enclosing scope is prefixed by (inlined by).
+
+.. code-block:: console
+
+  $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
+  baz() at /tmp/test.cpp:11:18
+   (inlined by) main at /tmp/test.cpp:15:0
+
+.. option:: --print-address, --addresses, -a
+
+  Print address before the source code location. Defaults to false.
+
+.. code-block:: console
+
+  $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
+  0x4004be
+  baz()
+  /tmp/test.cpp:11:18
+  main
+  /tmp/test.cpp:15:0
+
+  $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
+  0x4004be: baz() at /tmp/test.cpp:11:18
+   (inlined by) main at /tmp/test.cpp:15:0
+
+.. option:: --print-source-context-lines <N>
+
+  Print ``N`` lines of source context for each symbolized address.
+
+.. code-block:: console
+
+  $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
+  baz()
+  /tmp/test.cpp:11:0
+  10  :   volatile int k = 42;
+  11 >:   return foz() + k;
+  12  : }
+
+.. _llvm-symbolizer-opt-use-symbol-table:
+
+.. option:: --use-symbol-table
+
+  Prefer function names stored in symbol table to function names in debug info
+  sections. Defaults to true.
+
+.. option:: --verbose
+
+  Print verbose line and column information.
+
+.. code-block:: console
+
+  $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
+  baz()
+    Filename: /tmp/test.cpp
+  Function start line: 9
+    Line: 11
+    Column: 18
+  main
+    Filename: /tmp/test.cpp
+  Function start line: 14
+    Line: 15
+    Column: 0
+
+.. option:: --version
+
+  Print version information for the tool.
 
 .. option:: @<FILE>
 
   Read command-line options from response file `<FILE>`.
 
+MACH-O SPECIFIC OPTIONS
+-----------------------
+
+.. option:: --default-arch <arch>
+
+  If a binary contains object files for multiple architectures (e.g. it is a
+  Mach-O universal binary), symbolize the object file for a given architecture.
+  You can also specify the architecture by writing ``binary_name:arch_name`` in
+  the input (see example below). If the architecture is not specified in either
+  way, the address will not be symbolized. Defaults to empty string.
+
+.. code-block:: console
+
+  $ cat addr.txt
+  /tmp/mach_universal_binary:i386 0x1f84
+  /tmp/mach_universal_binary:x86_64 0x100000f24
+
+  $ llvm-symbolizer < addr.txt
+  _main
+  /tmp/source_i386.cc:8
+
+  _main
+  /tmp/source_x86_64.cc:8
+
+.. option:: --dsym-hint <path/to/file.dSYM>
+
+  If the debug info for a binary isn't present in the default location, look for
+  the debug info at the .dSYM path provided via this option. This flag can be
+  used multiple times.
+
 EXIT STATUS
 -----------
 
 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 error.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-addr2line(1)`