[llvm-locstats] Add the --draw-plot option

[djtodoro]

Summary

When using the option, draw the histogram representing the debug
location buckets. The resulting histogram will be saved as an image.

[djtodoro]

An example of the plot on a GDB binary built with LLVM Trunk.

[dstenb]

Looks good to me! I'll let the others have their say about the code or the output format.

[vsk]

Thanks, LGTM as well.

[djtodoro]

@vsk, @dstenb Thank you both for your comments!

[djtodoro]

-Rebase

llvm/docs/CommandGuide/llvm-locstats.rst

.. option:: --only-formal-parameters
 
             calculate the location statistics only for formal parameters
 
 .. option:: --ignore-debug-entry-values
 
             ignore the location statistics on locations containing the
             debug entry values DWARF operation
 
+.. option:: --draw-plot
+
+            make histogram of location buckets generated (requires
+            matplotlib)
+
 EXIT STATUS
 -----------
 
 :program:`llvm-locstats` returns 0 if the input file were parsed
 successfully. Otherwise, it returns 1.
 
-OUTPUT EXAMPLE
+EXAMPLE 1
 --------------
 
+Pretty print the location coverage on the standard output.
+
 .. code-block:: none
 
+  llvm-locstats a.out
+
     =================================================
               Debug Location Statistics
     =================================================
           cov%          samples       percentage(~)
     -------------------------------------------------
        0%                    1              16%
        (0%,10%)              0               0%
        [10%,20%)             0               0%
        [20%,30%)             0               0%
        [30%,40%)             0               0%
        [40%,50%)             0               0%
        [50%,60%)             1              16%
        [60%,70%)             0               0%
        [70%,80%)             0               0%
        [80%,90%)             1              16%
        [90%,100%)            0               0%
        100%                  3              50%
     =================================================
     -the number of debug variables processed: 6
     -PC ranges covered: 81%
     -------------------------------------------------
     -total availability: 83%
     =================================================
 
+EXAMPLE 2
+--------------
+
+Generate a plot as an image file.
+
+.. code-block:: none
+
+  llvm-locstats --draw-plot file1.out
+
+.. image:: locstats-draw-plot.png
+  :align: center
+
 SEE ALSO
 --------
 
 :manpage:`llvm-dwarfdump(1)`

llvm/utils/llvm-locstats/llvm-locstats.py

 #!/usr/bin/env python
 #
 # This is a tool that works like debug location coverage calculator.
 # It parses the llvm-dwarfdump --statistics output by reporting it
 # in a more human readable way.
 #
 
 from __future__ import print_function
 import argparse
 import os
 import sys
 from json import loads
 from math import ceil
+from collections import OrderedDict
 from subprocess import Popen, PIPE
 
 # Holds the debug location statistics.
 class LocationStats:
   def __init__(self, file_name, variables_total, variables_total_locstats,
     variables_with_loc, variables_scope_bytes_covered, variables_scope_bytes,
     variables_coverage_map):
     self.file_name = file_name
     self.variables_total = variables_total
     self.variables_total_locstats = variables_total_locstats
     self.variables_with_loc = variables_with_loc
     self.scope_bytes_covered = variables_scope_bytes_covered
     self.scope_bytes = variables_scope_bytes
     self.variables_coverage_map = variables_coverage_map
 
+  # Get the PC ranges coverage.
+  def get_pc_coverage(self):
+    pc_ranges_covered = int(ceil(self.scope_bytes_covered * 100.0) \
+                / self.scope_bytes)
+    return pc_ranges_covered
+
   # Pretty print the debug location buckets.
   def pretty_print(self):
     if self.scope_bytes == 0:
       print ('No scope bytes found.')
       return -1
 
-    pc_ranges_covered = int(ceil(self.scope_bytes_covered * 100.0) \
-                / self.scope_bytes)
+    pc_ranges_covered = self.get_pc_coverage()
     variables_coverage_per_map = {}
     for cov_bucket in coverage_buckets():
       variables_coverage_per_map[cov_bucket] = \
         int(ceil(self.variables_coverage_map[cov_bucket] * 100.0) \
                  / self.variables_total_locstats)
 
     print (' =================================================')
     print ('            Debug Location Statistics       ')
if self.variables_total and self.variables_with_loc:
       total_availability = int(ceil(self.variables_with_loc * 100.0) \
                                     / self.variables_total)
       print (' -------------------------------------------------')
       print (' -total availability: ' + str(total_availability) + '%')
     print (' =================================================')
 
     return 0
 
+  # Draw a plot representing the location buckets.
+  def draw_plot(self):
+    try:
+      import matplotlib
+    except ImportError:
+      print('error: matplotlib not found.')
+      sys.exit(1)
+
+    from matplotlib import pyplot as plt
+
+    buckets = range(len(self.variables_coverage_map))
+    plt.figure(figsize=(12, 8))
+    plt.title('Debug Location Statistics', fontweight='bold')
+    plt.xlabel('location buckets')
+    plt.ylabel('number of variables in the location buckets')
+    plt.bar(buckets, self.variables_coverage_map.values(), align='center',
+            tick_label=self.variables_coverage_map.keys(),
+            label='variables of {}'.format(self.file_name))
+    plt.xticks(rotation=45, fontsize='x-small')
+    plt.yticks()
+
+    # Place the text box with the coverage info.
+    pc_ranges_covered = self.get_pc_coverage()
+    props = dict(boxstyle='round', facecolor='wheat', alpha=0.5)
+    plt.text(0.02, 0.90, 'PC ranges covered: {}%'.format(pc_ranges_covered),
+             transform=plt.gca().transAxes, fontsize=12,
+             verticalalignment='top', bbox=props)
+    plt.legend()
+    plt.grid(color='grey', which='major', axis='y', linestyle='-', linewidth=0.3)
+
+    plt.savefig('locstats.png')
+    print('The plot was saved within "locstats.png".')
+
 # Define the location buckets.
 def coverage_buckets():
   yield '0%'
   yield '(0%,10%)'
   for start in range(10, 91, 10):
     yield '[{0}%,{1}%)'.format(start, start + 10)
   yield '100%'
 
 # Parse the JSON representing the debug statistics, and create a
 # LocationStats object.
 def parse_locstats(opts, binary):
   # These will be different due to different options enabled.
   variables_total = None
   variables_total_locstats = None
   variables_with_loc = None
   variables_scope_bytes_covered = None
   variables_scope_bytes = None
   variables_scope_bytes_entry_values = None
-  variables_coverage_map = {}
+  variables_coverage_map = OrderedDict()
 
   # Get the directory of the LLVM tools.
   llvm_dwarfdump_cmd = os.path.join(os.path.dirname(__file__), \
                                     "llvm-dwarfdump")
   # The statistics llvm-dwarfdump option.
   llvm_dwarfdump_stats_opt = "--statistics"
 
   # Generate the stats with the llvm-dwarfdump.
parser.add_argument('--only-variables', action='store_true', default=False,
             help='calculate the location statistics only for local variables')
   parser.add_argument('--only-formal-parameters', action='store_true',
             default=False,
             help='calculate the location statistics only for formal parameters')
   parser.add_argument('--ignore-debug-entry-values', action='store_true',
             default=False,
             help='ignore the location statistics on locations with '
                  'entry values')
+  parser.add_argument('--draw-plot', action='store_true', default=False,
+            help='show histogram of location buckets generated (requires '
+                 'matplotlib)')
   parser.add_argument('file_name', type=str, help='file to process')
 
   return parser.parse_args()
 
 # Verify that the program inputs meet the requirements.
 def verify_program_inputs(opts):
   if len(sys.argv) < 2:
     print ('error: Too few arguments.')
def Main():
 
   if not verify_program_inputs(opts):
     parser.print_help()
     sys.exit(1)
 
   binary = opts.file_name
   locstats = parse_locstats(opts, binary)
 
-  # Pretty print collected info.
+  if opts.draw_plot:
+    # Draw a histogram representing the location buckets.
+    locstats.draw_plot()
+  else:
+    # Pretty print collected info on the standard output.
     if locstats.pretty_print() == -1:
       sys.exit(0)
 
 if __name__ == '__main__':
   Main()
   sys.exit(0)