1dwlocstat(1) General Commands Manual dwlocstat(1)
2
6 dwlocstat - A tool for examining Dwarf location info coverage
7
10 dwlocstat [--dump=CLASSES] [--ignore=CLASSES] [--ignore-implicit-
11 pointer] [{-p|--show-progress}] [--tabulate=START[:STEP][,...]] FILE...
12 dwlocstat [{--help|-?}] [--usage]
13
16 ltrace is a tool for examining Dwarf location info coverage. It goes
17 through DIEs of given binary's debug info that represent variables and
18 function parameters. For each such DIE, it computes coverage of that
19 DIE's range (list of addresses of DIE's scope) by location expressions
20 (a description of where given variable is located at given location:
21 e.g. a variable can be in a register).
22 Coverage is expressed by percentage of covered addresses of DIE's
24 scope. If each address of DIE's scope is covered by at least one loca‐
25 tion expression, the coverage is 100%. If none are covered at all, the
26 coverage is 0.0% (sharp zero). The program assigns coverage to each
27 relevant DIE, and then tabulates the data. Output might look something
28 like this:
29 coverage% samples cumulative
31 0..10 1049/29% 1049/29%
32 11..20 67/1% 1116/31%
33 21..30 95/2% 1211/34%
34 31..40 84/2% 1295/36%
35 41..50 69/1% 1364/38%
36 51..60 100/2% 1464/41%
37 61..70 58/1% 1522/42%
38 71..80 85/2% 1607/45%
39 81..90 102/2% 1709/48%
40 91..100 1851/51% 3560/100%
41 This says that there were 1049 variable or parameter DIEs whose cover‐
43 age was less than or equal to 10%. Those 1049 DIEs comprise 29% of
44 total number of processed DIEs, which is 3560. The way theh tabulation
45 is done can be adjusted by using option --tabulate. See below for
46 details on how to adjust tabulation.
47 In addition to this, dwlocstat allows dumping DIEs matching certain
49 criteria, such as all inlined DIEs. It can similarly exclude such DIEs
50 from consideration. This is configurable using options --dump and
51 --ignore respectively. See below for details on supported classes.
52
55 --tabulate=START[:STEP][,...]
56 Tabulation script consists of series of comma-separated stops.
57 Each line of tabulation output captures percentages that are
58 above previous stop and below or at the next stop. Each stop
59 can be either an integer 0-100, or a special mark 0.0, which
60 denotes DIEs whose no addresses at all are covered. This def‐
61 fers from plain 0, which describes also DIEs that are covered so
62 poorly, that the percentage rounds down to zero. (Percentages
63 round down.)
64 Several regularly spaced stops can be abbreviated using a short-
66 hand notation START:STEP. STEP is integer 0-100.
67 Default tabulation script is 10:10, the output of which is dis‐
69 played above. As an example, the tabulation script 0.0,10:10,99
70 would have two extra lines: one for sharp zero, one for 100%.
71 That covers cases that have either no coverage at all, or are
72 covered fully.
73 --ignore=CLASS[,...]
76 DIEs that match those passed in comma-separated list of classes
77 are not included in analysis. The following classes are recog‐
78 nized:
79 single_addr DIEs whose location expression is sole DW_OP_addr
81 operand. Those are generally global and static variables.
82 artificial DIEs with attribute DW_AT_artificial.
84 inlined DIEs with attribute DW_AT_inline or children of such
86 DIE.
87 inlined_subroutine DIEs that are DW_TAG_inlined_subroutine,
89 inlined (in the above sense) DIEs that are DW_TAG_subprogram, or
90 children on such DIEs.
91 no_coverage DIEs with coverage of 0.0 (see above).
93 implicit_pointer DIEs that use DW_OP_GNU_implicit_pointer.
95 immutable DIEs whose location expression describes immutable
97 object. Location expressions that don't use with
98 DW_OP_implicit_value, DW_OP_stack_value are immutable.
99 mutable DIEs whose location expression is not immutable. Not
101 that DIE can be both mutable and immutable. When location
102 expression is complex (uses DW_OP_bit_piece or DW_OP_piece),
103 each part can have different mutability. Furthermore, if full
104 analysis of DW_OP_GNU_implicit_pointer is disabled, the DIEs
105 that use that operator are considered both mutable and
106 immutable.
107 --dump=CLASS[,...]
110 This shows references to DIEs (including full path from the root
111 of the CU) that match classes passed in argument. Possible
112 classes and their meaning is the same as with --ignore option.
113 --ignore-implicit-pointer
116 When a location expression uses operator
117 DW_OP_GNU_implicit_pointer, then it is handled a bit differ‐
118 ently. When an expression is encountered that uses this opera‐
119 tor, and no other expression covers the address under considera‐
120 tion, such address is not counted as covered. Instead the pro‐
121 gram checks whether the location expression at the DIE refer‐
122 enced by this operator covers this address. With this option,
123 dwlocstat will instead consider such addresses covered.
124 -p, --show-progress
127 Show each CU DIE as the file is processed.
128
131 Written by Petr Machata <pmachata@redhat.com>
132
135 Report dwlocstat bugs to <https://github.com/pmachata/dwlocstat/issues>
136 or by mail to <pmachata@redhat.com>.
137
140 Copyright © 2012 Red Hat, Inc.
141 License GPLv3+: GNU GPL version 3 or later
142 <http://gnu.org/licenses/gpl.html>.
143 Portions are licensed under LGPLv3+: GNU LGPL version 3 or later
144 <http://gnu.org/licenses/lgpl.html>.
145
148 readelf(1)
149 dwlocstat(1)