dwlocstat(1)

📦 version 0.1, in fedora 43, fedora 44

🦋 NAME 🦋

Okay so this is dwlocstat(1), straight outta the General Commands Manual, and she is a tool for examining Dwarf location info coverage. That's the name, that's the game, no notes. 💅

✨ SYNOPSIS ✨

dwlocstat [--dump=CLASSES] [--ignore=CLASSES] [--ignore-implicit-pointer] [{-p|--show-progress}] [--tabulate=START[:STEP][,...]] FILE...
dwlocstat [{--help|-?}] [--usage]

👑 DESCRIPTION 👑

okay so first things first, bestie: the page literally opens with the sentence "ltrace is a tool for examining Dwarf location info coverage." Yes. It says ltrace. That is a typo that lives in the original and we are keeping it because facts don't change around here — the tool is dwlocstat, periodt.

So what does she actually do? She goes through DIEs of the given binary's debug info that represent variables and function parameters. For each such DIE, she computes the coverage of that DIE's range — that's the list of addresses of the DIE's scope — by location expressions. And a location expression is just a description of where the given variable is located at a given location, like, e.g. a variable can be in a register. iconic.

Coverage is expressed as the percentage of covered addresses of the DIE's scope. If every single address of the DIE's scope is covered by at least one location expression, coverage is 100%. If none are covered at all, coverage is 0.0% (sharp zero, we love a sharp zero). The program assigns coverage to each relevant DIE, and then tabulates the data. The output might look something like this:

coverage%       samples         cumulative
0..10           1049/29%        1049/29%
11..20          67/1%           1116/31%
21..30          95/2%           1211/34%
31..40          84/2%           1295/36%
41..50          69/1%           1364/38%
51..60          100/2%          1464/41%
61..70          58/1%           1522/42%
71..80          85/2%           1607/45%
81..90          102/2%          1709/48%
91..100         1851/51%        3560/100%

So this is saying: there were 1049 variable or parameter DIEs whose coverage was less than or equal to 10%. Those 1049 DIEs comprise 29% of the total number of processed DIEs, which is 3560. And the way the tabulation is done can be adjusted with the option --tabulate — scroll down for the deets on how to adjust it. 🫶

On top of all that, dwlocstat also lets you dump DIEs matching certain criteria, like all inlined DIEs. She can similarly exclude such DIEs from consideration. That's configurable with --dump and --ignore respectively. Again, details on the supported classes are below. 👇

💖 OPTIONS 💖

  • --tabulate=START[:STEP][,...] — the tabulation script. It's a series of comma-separated stops. Each line of tabulation output captures the percentages that are above the previous stop and below or at the next stop. Each stop can be either an integer 0-100, or the special mark 0.0, which denotes DIEs where no addresses at all are covered. And bestie, this is not the same as plain 0 — plain 0 also describes DIEs that are covered so poorly that the percentage rounds down to zero. (Percentages round down, just fyi. 📉)

Several regularly spaced stops can be abbreviated with the shorthand notation START:STEP. STEP is an integer 0-100.

The default tabulation script is 10:10, and the output of that is what we showed you up above. As an example: the tabulation script 0.0,10:10,99 would have two extra lines — one for sharp zero, one for 100%. That covers the cases that either have no coverage at all, or are covered fully. slay.

  • --ignore=CLASS[,...] — DIEs that match the classes passed in this comma-separated list are not included in the analysis. The following classes are recognized:
    • single_addr — DIEs whose location expression is a sole DW_OP_addr operand. Those are generally global and static variables.
    • artificial — DIEs with the attribute DW_AT_artificial.
    • inlined — DIEs with the attribute DW_AT_inline, or children of such a DIE.
    • inlined_subroutine — DIEs that are DW_TAG_inlined_subroutine, inlined (in the above sense) DIEs that are DW_TAG_subprogram, or children of such DIEs.
    • no_coverage — DIEs with coverage of 0.0 (see above).
    • implicit_pointer — DIEs that use DW_OP_GNU_implicit_pointer.
    • immutable — DIEs whose location expression describes an immutable object. Location expressions that don't use DW_OP_implicit_value, DW_OP_stack_value are immutable.
    • mutable — DIEs whose location expression is not immutable. Note that a DIE can be both mutable and immutable. When the location expression is complex (uses DW_OP_bit_piece or DW_OP_piece), each part can have a different mutability. Furthermore, if the full analysis of DW_OP_GNU_implicit_pointer is disabled, the DIEs that use that operator are considered both mutable and immutable. it's giving both, and honestly? valid. 💀
  • --dump=CLASS[,...] — this shows references to DIEs (including the full path from the root of the CU) that match the classes passed in the argument. The possible classes and their meanings are the same as with the --ignore option. same energy, different verb. ✨
  • --ignore-implicit-pointer — when a location expression uses the operator DW_OP_GNU_implicit_pointer, it gets handled a little differently. When an expression is encountered that uses this operator, and no other expression covers the address under consideration, that address is not counted as covered. Instead, the program checks whether the location expression at the DIE referenced by this operator covers this address. With this option, dwlocstat will instead consider such addresses covered. choose your fighter, bestie.
  • -p, --show-progress — show each CU DIE as the file is processed. main character energy for every compilation unit. 👑

🌸 AUTHOR 🌸

Written by Petr Machata <pmachata@redhat.com>. we stan a legend. 🫶

🎀 REPORTING BUGS 🎀

Report dwlocstat bugs to <https://github.com/pmachata/dwlocstat/issues> or by mail to <pmachata@redhat.com>. Found a bug? Tell her directly, she wants to hear it, fr fr. 🙈

Copyright © 2012 Red Hat, Inc.

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.

Portions are licensed under LGPLv3+: GNU LGPL version 3 or later <http://gnu.org/licenses/lgpl.html>.

🌈 SEE ALSO 🌈

and that's the whole page bestie 💋 this is dwlocstat(1) from the General Commands Manual — the footer is literally just dwlocstat(1) again, no date drama, no version drama, we keep it simple. mwah. 🎀✨

📦 where this page comes from