df063cbf11
Patch 1 of 3 to add to llvm-dwarfdump the ability to measure DWARF coverage of local variables in terms of source lines, as discussed in [this RFC](https://discourse.llvm.org/t/rfc-debug-info-coverage-tool-v2/83266). This patch adds the basic variable coverage implementation. By default, inlined instances are shown separately (displaying the full inlining chain). Alternatively, a combined view that averages across all inlined instances can be returned using `--combine-instances`. In this patch, we simply print a count of source lines over which each variable is covered. Later patches in the series will add the comparison against a baseline. Example output: ``` $ llvm-dwarfdump --show-variable-coverage somefile Variable coverage statistics: Function InlChain Variable Decl LinesCovered foo bar path/to/somefile.h:54 3 foo path/to/someotherfile.c:32 bar path/to/somefile.h:54 2 foo baz main.c:76 9 ``` ``` $ llvm-dwarfdump --show-variable-coverage somefile --combine-instances Variable coverage statistics: Function InstanceCount Variable Decl LinesCovered foo 2 bar path/to/somefile.h:54 2.5 foo 1 baz main.c:76 9 ``` This reapplies #169646, fixing some ambiguous overloads that caused several bots to fail.
295 lines
10 KiB
ReStructuredText
295 lines
10 KiB
ReStructuredText
llvm-dwarfdump - dump and verify DWARF debug information
|
|
========================================================
|
|
|
|
.. program:: llvm-dwarfdump
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
:program:`llvm-dwarfdump` [*options*] [*filename ...*]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
:program:`llvm-dwarfdump` parses DWARF sections in object files,
|
|
archives, and `.dSYM` bundles and prints their contents in
|
|
human-readable form. Only the .debug_info section is printed unless one of
|
|
the section-specific options or :option:`--all` is specified.
|
|
|
|
If no input file is specified, `a.out` is used instead. If `-` is used as the
|
|
input file, :program:`llvm-dwarfdump` reads the input from its standard input
|
|
stream.
|
|
|
|
OPTIONS
|
|
-------
|
|
|
|
.. option:: -a, --all
|
|
|
|
Dump all supported DWARF sections.
|
|
|
|
.. option:: --arch=<arch>
|
|
|
|
Dump DWARF debug information for the specified CPU architecture.
|
|
Architectures may be specified by name or by number. This
|
|
option can be specified multiple times, once for each desired
|
|
architecture. All CPU architectures will be printed by
|
|
default.
|
|
|
|
.. option:: -c, --show-children
|
|
|
|
Show a debug info entry's children when selectively printing with
|
|
the `=<offset>` argument of :option:`--debug-info`, or options such
|
|
as :option:`--find` or :option:`--name`.
|
|
|
|
.. option:: --color
|
|
|
|
Use colors in output.
|
|
|
|
.. option:: --error-display=<value>
|
|
|
|
Set the level of detail and summary to display when verifying.
|
|
Implies :option:`--verify`. The supported values are:
|
|
|
|
`quiet` - Only display whether errors occurred.
|
|
`summary` - Display only a summary of the errors found.
|
|
`details` - Display each error in detail but no summary.
|
|
`full` - Display each error as well as a summary. [default]
|
|
|
|
.. option:: -f <name>, --find=<name>
|
|
|
|
Search for the exact text <name> in the accelerator tables
|
|
and print the matching debug information entries.
|
|
When there is no accelerator tables or the name of the DIE
|
|
you are looking for is not found in the accelerator tables,
|
|
try using the slower but more complete :option:`--name` option.
|
|
|
|
.. option:: -F, --show-form
|
|
|
|
Show DWARF form types after the DWARF attribute types.
|
|
|
|
.. option:: -h, --help
|
|
|
|
Show help and usage for this command.
|
|
|
|
.. option:: --help-list
|
|
|
|
Show help and usage for this command without grouping the options
|
|
into categories.
|
|
|
|
.. option:: -i, --ignore-case
|
|
|
|
Ignore case distinctions when using :option:`--name`.
|
|
|
|
.. option:: -n <name>, --name=<name>
|
|
|
|
Find and print all debug info entries whose name
|
|
(`DW_AT_name`/`DW_AT_linkage_name` attribute) is <name>.
|
|
|
|
.. option:: --lookup=<address>
|
|
|
|
Look up <address> in the debug information and print out the file,
|
|
function, block, and line table details.
|
|
|
|
.. option:: -o <path>
|
|
|
|
Redirect output to a file specified by <path>, where `-` is the
|
|
standard output stream.
|
|
|
|
.. option:: -p, --show-parents
|
|
|
|
Show a debug info entry's parents when selectively printing with
|
|
the `=<offset>` argument of :option:`--debug-info`, or options such
|
|
as :option:`--find` or :option:`--name`.
|
|
|
|
.. option:: --parent-recurse-depth=<N>
|
|
|
|
When displaying debug info entry parents, only show them to a
|
|
maximum depth of <N>.
|
|
|
|
.. option:: --quiet
|
|
|
|
Use with :option:`--verify` to not emit to `STDOUT`.
|
|
|
|
.. option:: -r <N>, --recurse-depth=<N>
|
|
|
|
When displaying debug info entries, only show children to a maximum
|
|
depth of <N>.
|
|
|
|
.. option:: --show-section-sizes
|
|
|
|
Show the sizes of all debug sections, expressed in bytes.
|
|
|
|
.. option:: --show-sources
|
|
|
|
Print all source files mentioned in the debug information. Absolute
|
|
paths are given whenever possible.
|
|
|
|
.. option:: --statistics
|
|
|
|
Collect debug info quality metrics and print the results
|
|
as machine-readable single-line JSON output. The output
|
|
format is described in the section below (:ref:`stats-format`).
|
|
|
|
.. option:: --summarize-types
|
|
|
|
Abbreviate the description of type unit entries.
|
|
|
|
.. option:: -t, --filter-child-tag
|
|
|
|
Only dump children whose DWARF tag is one of the specified tags.
|
|
Example usage:
|
|
|
|
.. code-block:: c
|
|
|
|
llvm-dwarfdump -t DW_TAG_structure_type -t DW_TAG_member -c
|
|
|
|
.. option:: -x, --regex
|
|
|
|
Treat any <name> strings as regular expressions when searching
|
|
with :option:`--name`. If :option:`--ignore-case` is also specified,
|
|
the regular expression becomes case-insensitive.
|
|
|
|
.. option:: -u, --uuid
|
|
|
|
Show the UUID for each architecture.
|
|
|
|
.. option:: --diff
|
|
|
|
Dump the output in a format that is more friendly for comparing
|
|
DWARF output from two different files.
|
|
|
|
.. option:: -v, --verbose
|
|
|
|
Display verbose information when dumping. This can help to debug
|
|
DWARF issues.
|
|
|
|
.. option:: --verify
|
|
|
|
Verify the structure of the DWARF information by verifying the
|
|
compile unit chains, DIE relationships graph, address
|
|
ranges, and more.
|
|
|
|
.. option:: --verify-json=<path>
|
|
|
|
Output JSON-formatted error summary to the file specified by
|
|
<path>. Implies :option:`--verify`. The output format is described
|
|
in the section below (:ref:`verify-json-format`).
|
|
|
|
.. option:: --version
|
|
|
|
Display the version of the tool.
|
|
|
|
.. option:: --debug-abbrev, --debug-addr, --debug-aranges, --debug-cu-index, --debug-frame [=<offset>], --debug-gnu-pubnames, --debug-gnu-pubtypes, --debug-info [=<offset>], --debug-line [=<offset>], --debug-line-str, --debug-loc [=<offset>], --debug-loclists [=<offset>], --debug-macro, --debug-names, --debug-pubnames, --debug-pubtypes, --debug-ranges, --debug-rnglists, --debug-str, --debug-str-offsets, --debug-tu-index, --debug-types [=<offset>], --eh-frame [=<offset>], --gdb-index, --apple-names, --apple-types, --apple-namespaces, --apple-objc
|
|
|
|
Dump the specified DWARF section by name. Only the
|
|
`.debug_info` section is shown by default. Some entries
|
|
support adding an `=<offset>` as a way to provide an
|
|
optional offset of the exact entry to dump within the
|
|
respective section. When an offset is provided, only the
|
|
entry at that offset will be dumped, else the entire
|
|
section will be dumped.
|
|
|
|
The :option:`--debug-macro` option prints both the .debug_macro and the .debug_macinfo sections.
|
|
|
|
The :option:`--debug-frame` and :option:`--eh-frame` options are aliases, in cases where both sections are present one command outputs both.
|
|
|
|
.. option:: --show-variable-coverage
|
|
|
|
Show per-variable coverage metrics. The output format is described
|
|
in the section below (:ref:`variable-coverage-format`).
|
|
|
|
.. option:: --combine-inline-variable-instances
|
|
|
|
Use with :option:`--show-variable-coverage` to average variable
|
|
coverage across inlined subroutine instances instead of printing
|
|
them separately.
|
|
|
|
.. option:: @<FILE>
|
|
|
|
Read command-line options from `<FILE>`.
|
|
|
|
.. _stats-format:
|
|
|
|
FORMAT OF STATISTICS OUTPUT
|
|
---------------------------
|
|
|
|
The :option:`--statistics` option generates single-line JSON output
|
|
representing quality metrics of the processed debug info. These metrics are
|
|
useful to compare changes between two compilers, particularly for judging
|
|
the effect that a change to the compiler has on the debug info quality.
|
|
|
|
The output is formatted as key-value pairs. The first pair contains a version
|
|
number. The following naming scheme is used for the keys:
|
|
|
|
- `variables` ==> local variables and parameters
|
|
- `local vars` ==> local variables
|
|
- `params` ==> formal parameters
|
|
|
|
For aggregated values, the following keys are used:
|
|
|
|
- `sum_of_all_variables(...)` ==> the sum applied to all variables
|
|
- `#bytes` ==> the number of bytes
|
|
- `#variables - entry values ...` ==> the number of variables excluding
|
|
the entry values etc.
|
|
|
|
.. _verify-json-format:
|
|
|
|
FORMAT OF VERIFY JSON OUTPUT
|
|
----------------------------
|
|
|
|
The format of the JSON output created by the :option:`--verify-json` is::
|
|
|
|
{
|
|
"error-categories": {
|
|
"<first category description>": {"count": 1234},
|
|
"<next category description>": {"count": 4321}
|
|
},
|
|
"error-count": 5555
|
|
}
|
|
|
|
The following is generated if there are no errors reported::
|
|
|
|
{
|
|
"error-categories": {},
|
|
"error-count": 0
|
|
}
|
|
|
|
.. _variable-coverage-format:
|
|
|
|
FORMAT OF VARIABLE COVERAGE OUTPUT
|
|
----------------------------------
|
|
|
|
The :option:`--show-variable-coverage` option differs from
|
|
:option:`--statistics` by printing per-variable debug info coverage metrics
|
|
based on the number of source lines covered instead of the number of
|
|
instruction bytes. Compared to counting instruction bytes, this is more stable
|
|
across compilations and better reflects the debugging experience. The output is
|
|
a tab-separated table containing the following columns:
|
|
|
|
- `Function` ==> Name of the function the variable was found in
|
|
- `InstanceCount` (when :option:`--combine-inline-variable-instances` is
|
|
specified) ==> Number of instances of the function; this is 1 for
|
|
functions that have not been inlined, and n+1 for functions that have
|
|
been inlined n times
|
|
- `InlChain` (when :option:`--combine-inline-variable-instances` is not
|
|
specified) ==> Chain of call sites (file and line number) that the
|
|
function has been inlined into; this will be empty if the function has
|
|
not been inlined
|
|
- `Variable` ==> Name of the variable
|
|
- `Decl` ==> Source location (file and line number) of the variable's
|
|
declaration
|
|
- `LinesCovered` ==> Number of source lines covered by the variable's
|
|
debug information in the input file
|
|
|
|
|
|
EXIT STATUS
|
|
-----------
|
|
|
|
:program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
|
|
successfully. Otherwise, it returns 1.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
:manpage:`dsymutil(1)`
|