llvm/docs/CommandGuide/llvm-locstats.rst

   1 llvm-locstats - calculate statistics on DWARF debug location
   2 ============================================================
   3
   4 .. program:: llvm-locstats
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-locstats` [*options*] [*filename*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-locstats` works like a wrapper around :program:`llvm-dwarfdump`.
  15 It parses :program:`llvm-dwarfdump` statistics regarding debug location by
  16 pretty printing it in a more human readable way.
  17
  18 The line 0% shows the number and the percentage of DIEs with no location
  19 information, but the line 100% shows the information for DIEs where there is
  20 location information in all code section bytes (where the variable or parameter
  21 is in the scope). The line [50%,60%) shows the number and the percentage of DIEs
  22 where the location information is between 50 and 60 percentage of its scope
  23 covered.
  24
  25 OPTIONS
  26 -------
  27
  28 .. option:: --only-variables
  29
  30             calculate the location statistics only for local variables
  31
  32 .. option:: --only-formal-parameters
  33
  34             calculate the location statistics only for formal parameters
  35
  36 .. option:: --ignore-debug-entry-values
  37
  38             ignore the location statistics on locations containing the
  39             debug entry values DWARF operation
  40
  41 .. option:: --draw-plot
  42
  43             make histogram of location buckets generated (requires
  44             matplotlib)
  45
  46 .. option:: --compare
  47
  48             compare the debug location coverage on two files provided, and draw
  49             a plot showing the difference (requires matplotlib)
  50
  51 EXIT STATUS
  52 -----------
  53
  54 :program:`llvm-locstats` returns 0 if the input file were parsed
  55 successfully. Otherwise, it returns 1.
  56
  57 EXAMPLE 1
  58 --------------
  59
  60 Pretty print the location coverage on the standard output.
  61
  62 .. code-block:: none
  63
  64   llvm-locstats a.out
  65
  66     =================================================
  67               Debug Location Statistics
  68     =================================================
  69           cov%          samples       percentage(~)
  70     -------------------------------------------------
  71        0%                    1              16%
  72        (0%,10%)              0               0%
  73        [10%,20%)             0               0%
  74        [20%,30%)             0               0%
  75        [30%,40%)             0               0%
  76        [40%,50%)             0               0%
  77        [50%,60%)             1              16%
  78        [60%,70%)             0               0%
  79        [70%,80%)             0               0%
  80        [80%,90%)             1              16%
  81        [90%,100%)            0               0%
  82        100%                  3              50%
  83     =================================================
  84     -the number of debug variables processed: 6
  85     -PC ranges covered: 81%
  86     -------------------------------------------------
  87     -total availability: 83%
  88     =================================================
  89
  90 EXAMPLE 2
  91 --------------
  92
  93 Generate a plot as an image file.
  94
  95 .. code-block:: none
  96
  97   llvm-locstats --draw-plot file1.out
  98
  99 .. image:: locstats-draw-plot.png
 100   :align: center
 101
 102 EXAMPLE 3
 103 --------------
 104
 105 Generate a plot as an image file showing the difference in the debug location
 106 coverage.
 107
 108 .. code-block:: none
 109
 110   llvm-locstats --compare file1.out file1.withentryvals.out
 111
 112 .. image:: locstats-compare.png
 113   :align: center
 114
 115 SEE ALSO
 116 --------
 117
 118 :manpage:`llvm-dwarfdump(1)`