1dwlocstat(1)                General Commands Manual               dwlocstat(1)
2
3
4

NAME

6       dwlocstat - A tool for examining Dwarf location info coverage
7
8

SYNOPSIS

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

DESCRIPTION

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
23       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
30           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
42       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
48       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
53

OPTIONS

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
65              Several regularly spaced stops can be abbreviated using a short-
66              hand notation START:STEP.  STEP is integer 0-100.
67
68              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
74
75       --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
80              single_addr  DIEs  whose  location expression is sole DW_OP_addr
81              operand.  Those are generally global and static variables.
82
83              artificial DIEs with attribute DW_AT_artificial.
84
85              inlined DIEs with attribute DW_AT_inline  or  children  of  such
86              DIE.
87
88              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
92              no_coverage DIEs with coverage of 0.0 (see above).
93
94              implicit_pointer DIEs that use DW_OP_GNU_implicit_pointer.
95
96              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
100              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
108
109       --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
114
115       --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
125
126       -p, --show-progress
127              Show each CU DIE as the file is processed.
128
129

AUTHOR

131       Written by Petr Machata <pmachata@redhat.com>
132
133

REPORTING BUGS

135       Report dwlocstat bugs to <https://github.com/pmachata/dwlocstat/issues>
136       or by mail to <pmachata@redhat.com>.
137
138
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
146

SEE ALSO

148       readelf(1)
149
150
151
152                                                                  dwlocstat(1)
Impressum