cachegrind/cg_annotate.in

   1 #! @PERL@
   2
   3 ##--------------------------------------------------------------------##
   4 ##--- Cachegrind's annotator.                       cg_annotate.in ---##
   5 ##--------------------------------------------------------------------##
   6
   7 #  This file is part of Cachegrind, a Valgrind tool for cache
   8 #  profiling programs.
   9 #
  10 #  Copyright (C) 2002-2017 Nicholas Nethercote
  11 #     njn@valgrind.org
  12 #
  13 #  This program is free software; you can redistribute it and/or
  14 #  modify it under the terms of the GNU General Public License as
  15 #  published by the Free Software Foundation; either version 2 of the
  16 #  License, or (at your option) any later version.
  17 #
  18 #  This program is distributed in the hope that it will be useful, but
  19 #  WITHOUT ANY WARRANTY; without even the implied warranty of
  20 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 #  General Public License for more details.
  22 #
  23 #  You should have received a copy of the GNU General Public License
  24 #  along with this program; if not, see <http://www.gnu.org/licenses/>.
  25 #
  26 #  The GNU General Public License is contained in the file COPYING.
  27
  28 #----------------------------------------------------------------------------
  29 # The file format is simple, basically printing the cost centre for every
  30 # source line, grouped by files and functions.  The details are in
  31 # Cachegrind's manual.
  32
  33 #----------------------------------------------------------------------------
  34 # Performance improvements record, using cachegrind.out for cacheprof, doing no
  35 # source annotation (irrelevant ones removed):
  36 #                                                               user time
  37 # 1. turned off warnings in add_hash_a_to_b()                   3.81 --> 3.48s
  38 #    [now add_array_a_to_b()]
  39 # 6. make line_to_CC() return a ref instead of a hash           3.01 --> 2.77s
  40 #
  41 #10. changed file format to avoid file/fn name repetition       2.40s
  42 #    (not sure why higher;  maybe due to new '.' entries?)
  43 #11. changed file format to drop unnecessary end-line "."s      2.36s
  44 #    (shrunk file by about 37%)
  45 #12. switched from hash CCs to array CCs                        1.61s
  46 #13. only adding b[i] to a[i] if b[i] defined (was doing it if
  47 #    either a[i] or b[i] was defined, but if b[i] was undefined
  48 #    it just added 0)                                           1.48s
  49 #14. Stopped converting "." entries to undef and then back      1.16s
  50 #15. Using foreach $i (x..y) instead of for ($i = 0...) in
  51 #    add_array_a_to_b()                                         1.11s
  52 #
  53 # Auto-annotating primes:
  54 #16. Finding count lengths by int((length-1)/3), not by
  55 #    commifying (halves the number of commify calls)            1.68s --> 1.47s
  56
  57 use warnings;
  58 use strict;
  59
  60 #----------------------------------------------------------------------------
  61 # Overview: the running example in the comments is for:
  62 #   - events = A,B,C,D
  63 #   - --show=C,A,D
  64 #   - --sort=D,C
  65 #----------------------------------------------------------------------------
  66
  67 #----------------------------------------------------------------------------
  68 # Global variables, main data structures
  69 #----------------------------------------------------------------------------
  70 # CCs are arrays, the counts corresponding to @events, with 'undef'
  71 # representing '.'.  This makes things fast (faster than using hashes for CCs)
  72 # but we have to use @sort_order and @show_order below to handle the --sort and
  73 # --show options, which is a bit tricky.
  74 #----------------------------------------------------------------------------
  75
  76 # Total counts for summary (an array reference).
  77 my $summary_CC;
  78
  79 # Totals for each function, for overall summary.
  80 # hash(filename:fn_name => CC array)
  81 my %fn_totals;
  82
  83 # Individual CCs, organised by filename and line_num for easy annotation.
  84 # hash(filename => hash(line_num => CC array))
  85 my %allCCs;
  86
  87 # Files chosen for annotation on the command line.
  88 # key = basename (trimmed of any directory), value = full filename
  89 my %user_ann_files;
  90
  91 # Generic description string.
  92 my $desc = "";
  93
  94 # Command line of profiled program.
  95 my $cmd;
  96
  97 # Events in input file, eg. (A,B,C,D)
  98 my @events;
  99
 100 # Events to show, from command line, eg. (C,A,D)
 101 my @show_events;
 102
 103 # Map from @show_events indices to @events indices, eg. (2,0,3).  Gives the
 104 # order in which we must traverse @events in order to show the @show_events,
 105 # eg. (@events[$show_order[1]], @events[$show_order[2]]...) = @show_events.
 106 # (Might help to think of it like a hash (0 => 2, 1 => 0, 2 => 3).)
 107 my @show_order;
 108
 109 # Print out the function totals sorted by these events, eg. (D,C).
 110 my @sort_events;
 111
 112 # Map from @sort_events indices to @events indices, eg. (3,2).  Same idea as
 113 # for @show_order.
 114 my @sort_order;
 115
 116 # Thresholds, one for each sort event (or default to 1 if no sort events
 117 # specified).  We print out functions and do auto-annotations until we've
 118 # handled this proportion of all the events thresholded.
 119 my @thresholds;
 120
 121 my $default_threshold = 0.1;
 122
 123 my $single_threshold  = $default_threshold;
 124
 125 # If on, show a percentage for each non-zero count.
 126 my $show_percs = 1;
 127
 128 # If on, automatically annotates all files that are involved in getting over
 129 # all the threshold counts.
 130 my $auto_annotate = 1;
 131
 132 # Number of lines to show around each annotated line.
 133 my $context = 8;
 134
 135 # Directories in which to look for annotation files.
 136 my @include_dirs = ("");
 137
 138 # Input file name
 139 my $input_file = undef;
 140
 141 # Version number
 142 my $version = "@VERSION@";
 143
 144 # Usage message.
 145 my $usage = <<END
 146 usage: cg_annotate [options] cachegrind-out-file [source-files...]
 147
 148   options for the user, with defaults in [ ], are:
 149     -h --help             show this message
 150     --version             show version
 151     --show=A,B,C          only show figures for events A,B,C [all]
 152     --sort=A,B,C          sort columns by events A,B,C [event column order]
 153     --threshold=<0--20>   a function is shown if it accounts for more than x% of
 154                           the counts of the primary sort event [$default_threshold]
 155     --show-percs=yes|no   show a percentage for each non-zero count [yes]
 156     --auto=yes|no         annotate all source files containing functions
 157                           that helped reach the event count threshold [yes]
 158     --context=N           print N lines of context before and after
 159                           annotated lines [8]
 160     -I<d> --include=<d>   add <d> to list of directories to search for
 161                           source files
 162
 163   cg_annotate is Copyright (C) 2002-2017 Nicholas Nethercote.
 164   and licensed under the GNU General Public License, version 2.
 165   Bug reports, feedback, admiration, abuse, etc, to: njn\@valgrind.org.
 166
 167 END
 168 ;
 169
 170 # Used in various places of output.
 171 my $fancy = '-' x 80 . "\n";
 172
 173 sub safe_div($$)
 174 {
 175     my ($x, $y) = @_;
 176     return ($y == 0 ? 0 : $x / $y);
 177 }
 178
 179 #-----------------------------------------------------------------------------
 180 # Argument and option handling
 181 #-----------------------------------------------------------------------------
 182 sub process_cmd_line()
 183 {
 184     for my $arg (@ARGV) {
 185
 186         # Option handling
 187         if ($arg =~ /^-/) {
 188
 189             # --version
 190             if ($arg =~ /^--version$/) {
 191                 die("cg_annotate-$version\n");
 192
 193             # --show=A,B,C
 194             } elsif ($arg =~ /^--show=(.*)$/) {
 195                 @show_events = split(/,/, $1);
 196
 197             # --sort=A,B,C
 198             #   Nb: You can specify thresholds individually, eg.
 199             #   --sort=A:99,B:95,C:90.  These will override any --threshold
 200             #   argument.
 201             } elsif ($arg =~ /^--sort=(.*)$/) {
 202                 @sort_events = split(/,/, $1);
 203                 my $th_specified = 0;
 204                 foreach my $i (0 .. scalar @sort_events - 1) {
 205                     if ($sort_events[$i] =~ /.*:([\d\.]+)%?$/) {
 206                         my $th = $1;
 207                         ($th >= 0 && $th <= 100) or die($usage);
 208                         $sort_events[$i] =~ s/:.*//;
 209                         $thresholds[$i] = $th;
 210                         $th_specified = 1;
 211                     } else {
 212                         $thresholds[$i] = 0;
 213                     }
 214                 }
 215                 if (not $th_specified) {
 216                     @thresholds = ();
 217                 }
 218
 219             # --threshold=X (tolerates a trailing '%')
 220             } elsif ($arg =~ /^--threshold=([\d\.]+)%?$/) {
 221                 $single_threshold = $1;
 222                 ($1 >= 0 && $1 <= 20) or die($usage);
 223
 224             # --show-percs=yes|no
 225             } elsif ($arg =~ /^--show-percs=yes$/) {
 226                 $show_percs = 1;
 227             } elsif ($arg =~ /^--show-percs=no$/) {
 228                 $show_percs = 0;
 229
 230             # --auto=yes|no
 231             } elsif ($arg =~ /^--auto=yes$/) {
 232                 $auto_annotate = 1;
 233             } elsif ($arg =~ /^--auto=no$/) {
 234                 $auto_annotate = 0;
 235
 236             # --context=N
 237             } elsif ($arg =~ /^--context=([\d\.]+)$/) {
 238                 $context = $1;
 239                 if ($context < 0) {
 240                     die($usage);
 241                 }
 242
 243             # We don't handle "-I name" -- there can be no space.
 244             } elsif ($arg =~ /^-I$/) {
 245                 die("Sorry, no space is allowed after a -I flag\n");
 246
 247             # --include=A,B,C.  Allow -I=name for backwards compatibility.
 248             } elsif ($arg =~ /^(-I=|-I|--include=)(.*)$/) {
 249                 my $inc = $2;
 250                 $inc =~ s|/$||;         # trim trailing '/'
 251                 push(@include_dirs, "$inc/");
 252
 253             } else {            # -h and --help fall under this case
 254                 die($usage);
 255             }
 256
 257         # Argument handling -- annotation file checking and selection.
 258         # Stick filenames into a hash for quick 'n easy lookup throughout.
 259         } else {
 260             if (not defined $input_file) {
 261                 # First non-option argument is the output file.
 262                 $input_file = $arg;
 263             } else {
 264                 # Subsequent non-option arguments are source files.
 265                 my $readable = 0;
 266                 foreach my $include_dir (@include_dirs) {
 267                     if (-r $include_dir . $arg) {
 268                         $readable = 1;
 269                     }
 270                 }
 271                 $readable or die("File $arg not found in any of: @include_dirs\n");
 272                 $user_ann_files{$arg} = 1;
 273             }
 274         }
 275     }
 276
 277     # Must have chosen an input file
 278     if (not defined $input_file) {
 279         die($usage);
 280     }
 281 }
 282
 283 #-----------------------------------------------------------------------------
 284 # Reading of input file
 285 #-----------------------------------------------------------------------------
 286 sub max ($$)
 287 {
 288     my ($x, $y) = @_;
 289     return ($x > $y ? $x : $y);
 290 }
 291
 292 # Add the two arrays;  any '.' entries are ignored.  Two tricky things:
 293 # 1. If $a2->[$i] is undefined, it defaults to 0 which is what we want; we turn
 294 #    off warnings to allow this.  This makes things about 10% faster than
 295 #    checking for definedness ourselves.
 296 # 2. We don't add an undefined count or a ".", even though it's value is 0,
 297 #    because we don't want to make an $a2->[$i] that is undef become 0
 298 #    unnecessarily.
 299 sub add_array_a_to_b ($$)
 300 {
 301     my ($a1, $a2) = @_;
 302
 303     my $n = max(scalar @$a1, scalar @$a2);
 304     $^W = 0;
 305     foreach my $i (0 .. $n-1) {
 306         $a2->[$i] += $a1->[$i] if (defined $a1->[$i] && "." ne $a1->[$i]);
 307     }
 308     $^W = 1;
 309 }
 310
 311 # Add each event count to the CC array.  '.' counts become undef, as do
 312 # missing entries (implicitly).
 313 sub line_to_CC ($)
 314 {
 315     my @CC = (split /\s+/, $_[0]);
 316     (@CC <= @events) or die("Line $.: too many event counts\n");
 317     return \@CC;
 318 }
 319
 320 sub read_input_file()
 321 {
 322     open(INPUTFILE, "< $input_file")
 323          || die "Cannot open $input_file for reading\n";
 324
 325     # Read "desc:" lines.
 326     my $line;
 327     while ($line = <INPUTFILE>) {
 328         if ($line =~ s/desc:\s+//) {
 329             $desc .= $line;
 330         } else {
 331             last;
 332         }
 333     }
 334
 335     # Read "cmd:" line (Nb: will already be in $line from "desc:" loop above).
 336     ($line =~ s/^cmd:\s+//) or die("Line $.: missing command line\n");
 337     $cmd = $line;
 338     chomp($cmd);    # Remove newline
 339
 340     # Read "events:" line.  We make a temporary hash in which the Nth event's
 341     # value is N, which is useful for handling --show/--sort options below.
 342     $line = <INPUTFILE>;
 343     (defined $line && $line =~ s/^events:\s+//)
 344         or die("Line $.: missing events line\n");
 345     @events = split(/\s+/, $line);
 346     my %events;
 347     my $n = 0;
 348     foreach my $event (@events) {
 349         $events{$event} = $n;
 350         $n++
 351     }
 352
 353     # If no --show arg give, default to showing all events in the file.
 354     # If --show option is used, check all specified events appeared in the
 355     # "events:" line.  Then initialise @show_order.
 356     if (@show_events) {
 357         foreach my $show_event (@show_events) {
 358             (defined $events{$show_event}) or
 359                 die("--show event `$show_event' did not appear in input\n");
 360         }
 361     } else {
 362         @show_events = @events;
 363     }
 364     foreach my $show_event (@show_events) {
 365         push(@show_order, $events{$show_event});
 366     }
 367
 368     # Do as for --show, but if no --sort arg given, default to sorting by
 369     # column order (ie. first column event is primary sort key, 2nd column is
 370     # 2ndary key, etc).
 371     if (@sort_events) {
 372         foreach my $sort_event (@sort_events) {
 373             (defined $events{$sort_event}) or
 374                 die("--sort event `$sort_event' did not appear in input\n");
 375         }
 376     } else {
 377         @sort_events = @events;
 378     }
 379     foreach my $sort_event (@sort_events) {
 380         push(@sort_order, $events{$sort_event});
 381     }
 382
 383     # If multiple threshold args weren't given via --sort, stick in the single
 384     # threshold (either from --threshold if used, or the default otherwise) for
 385     # the primary sort event, and 0% for the rest.
 386     if (not @thresholds) {
 387         foreach my $e (@sort_order) {
 388             push(@thresholds, 100);
 389         }
 390         $thresholds[0] = $single_threshold;
 391     }
 392
 393     my $currFileName;
 394     my $currFileFuncName;
 395
 396     my $currFuncCC;
 397     my $currFileCCs = {};     # hash(line_num => CC)
 398
 399     # Read body of input file.
 400     while (<INPUTFILE>) {
 401         # Skip comments and empty lines.
 402         next if /^\s*$/ || /^\#/;
 403
 404         if (s/^(-?\d+)\s+//) {
 405             my $lineNum = $1;
 406             my $CC = line_to_CC($_);
 407             defined($currFuncCC) || die;
 408             add_array_a_to_b($CC, $currFuncCC);
 409
 410             # If currFileName is selected, add CC to currFileName list.  We look for
 411             # full filename matches;  or, if auto-annotating, we have to
 412             # remember everything -- we won't know until the end what's needed.
 413             defined($currFileCCs) || die;
 414             if ($auto_annotate || defined $user_ann_files{$currFileName}) {
 415                 my $currLineCC = $currFileCCs->{$lineNum};
 416                 if (not defined $currLineCC) {
 417                     $currLineCC = [];
 418                     $currFileCCs->{$lineNum} = $currLineCC;
 419                 }
 420                 add_array_a_to_b($CC, $currLineCC);
 421             }
 422
 423         } elsif (s/^fn=(.*)$//) {
 424             $currFileFuncName = "$currFileName:$1";
 425             $currFuncCC = $fn_totals{$currFileFuncName};
 426             if (not defined $currFuncCC) {
 427                 $currFuncCC = [];
 428                 $fn_totals{$currFileFuncName} = $currFuncCC;
 429             }
 430
 431         } elsif (s/^fl=(.*)$//) {
 432             $currFileName = $1;
 433             $currFileCCs = $allCCs{$currFileName};
 434             if (not defined $currFileCCs) {
 435                 $currFileCCs = {};
 436                 $allCCs{$currFileName} = $currFileCCs;
 437             }
 438             # Assume that a "fn=" line is followed by a "fl=" line.
 439             $currFileFuncName = undef;
 440
 441         } elsif (s/^summary:\s+//) {
 442             $summary_CC = line_to_CC($_);
 443             (scalar(@$summary_CC) == @events)
 444                 or die("Line $.: summary event and total event mismatch\n");
 445
 446         } else {
 447             warn("WARNING: line $. malformed, ignoring\n");
 448         }
 449     }
 450
 451     # Check if summary line was present
 452     if (not defined $summary_CC) {
 453         die("missing final summary line, aborting\n");
 454     }
 455
 456     close(INPUTFILE);
 457 }
 458
 459 #-----------------------------------------------------------------------------
 460 # Print options used
 461 #-----------------------------------------------------------------------------
 462 sub print_options ()
 463 {
 464     print($fancy);
 465     print($desc);
 466     print("Command:          $cmd\n");
 467     print("Data file:        $input_file\n");
 468     print("Events recorded:  @events\n");
 469     print("Events shown:     @show_events\n");
 470     print("Event sort order: @sort_events\n");
 471     print("Thresholds:       @thresholds\n");
 472
 473     my @include_dirs2 = @include_dirs;  # copy @include_dirs
 474     shift(@include_dirs2);       # remove "" entry, which is always the first
 475     unshift(@include_dirs2, "") if (0 == @include_dirs2);
 476     my $include_dir = shift(@include_dirs2);
 477     print("Include dirs:     $include_dir\n");
 478     foreach my $include_dir (@include_dirs2) {
 479         print("                  $include_dir\n");
 480     }
 481
 482     my @user_ann_files = keys %user_ann_files;
 483     unshift(@user_ann_files, "") if (0 == @user_ann_files);
 484     my $user_ann_file = shift(@user_ann_files);
 485     print("User annotated:   $user_ann_file\n");
 486     foreach $user_ann_file (@user_ann_files) {
 487         print("                  $user_ann_file\n");
 488     }
 489
 490     my $is_on = ($auto_annotate ? "on" : "off");
 491     print("Auto-annotation:  $is_on\n");
 492     print("\n");
 493 }
 494
 495 #-----------------------------------------------------------------------------
 496 # Print summary and sorted function totals
 497 #-----------------------------------------------------------------------------
 498 sub mycmp ($$)
 499 {
 500     my ($c, $d) = @_;
 501
 502     # Iterate through sort events (eg. 3,2); return result if two are different
 503     foreach my $i (@sort_order) {
 504         my ($x, $y);
 505         $x = $c->[$i];
 506         $y = $d->[$i];
 507         $x = -1 unless defined $x;
 508         $y = -1 unless defined $y;
 509
 510         my $cmp = abs($y) <=> abs($x);      # reverse sort of absolute size
 511         if (0 != $cmp) {
 512             return $cmp;
 513         }
 514     }
 515     # Exhausted events, equal
 516     return 0;
 517 }
 518
 519 sub commify ($) {
 520     my ($val) = @_;
 521     1 while ($val =~ s/^(-?\d+)(\d{3})/$1,$2/);
 522     return $val;
 523 }
 524
 525 # Because the counts can get very big, and we don't want to waste screen space
 526 # and make lines too long, we compute exactly how wide each column needs to be
 527 # by finding the widest entry for each one.
 528 sub compute_CC_col_widths (@)
 529 {
 530     my @CCs = @_;
 531     my $CC_col_widths = [];
 532
 533     # Initialise with minimum widths (from event names)
 534     foreach my $event (@events) {
 535         push(@$CC_col_widths, length($event));
 536     }
 537
 538     # Find maximum width count for each column.  @CC_col_width positions
 539     # correspond to @CC positions.
 540     foreach my $CC (@CCs) {
 541         foreach my $i (0 .. scalar(@$CC)-1) {
 542             if (defined $CC->[$i]) {
 543                 # Find length, accounting for commas that will be added, and
 544                 # possibly a percentage.
 545                 my $length = length $CC->[$i];
 546                 my $width = $length + int(($length - 1) / 3);
 547                 if ($show_percs) {
 548                     $width += 9;    # e.g. " (12.34%)" is 9 chars
 549                 }
 550                 $CC_col_widths->[$i] = max($CC_col_widths->[$i], $width);
 551             }
 552         }
 553     }
 554     return $CC_col_widths;
 555 }
 556
 557 # Print the CC with each column's size dictated by $CC_col_widths.
 558 sub print_CC ($$)
 559 {
 560     my ($CC, $CC_col_widths) = @_;
 561
 562     foreach my $i (@show_order) {
 563         my $count = (defined $CC->[$i] ? commify($CC->[$i]) : ".");
 564
 565         my $perc = "";
 566         if ($show_percs) {
 567             if (defined $CC->[$i] && $CC->[$i] != 0) {
 568                 # Try our best to keep the number fitting into 5 chars. This
 569                 # requires dropping a digit after the decimal place if it's
 570                 # sufficiently negative (e.g. "-10.0") or positive (e.g.
 571                 # "100.0"). Thanks to diffs it's possible to have even more
 572                 # extreme values, like "-100.0" or "1000.0"; those rare case
 573                 # will end up with slightly wrong indenting, oh well.
 574                 $perc = safe_div($CC->[$i] * 100, $summary_CC->[$i]);
 575                 $perc = (-9.995 < $perc && $perc < 99.995)
 576                       ? sprintf(" (%5.2f%%)", $perc)
 577                       : sprintf(" (%5.1f%%)", $perc);
 578             } else {
 579                 # Don't show percentages for "." and "0" entries.
 580                 $perc = "         ";
 581             }
 582         }
 583
 584         # $reps will be negative for the extreme values mentioned above. The
 585         # use of max() avoids a possible warning about a negative repeat count.
 586         my $text = $count . $perc;
 587         my $len = length($text);
 588         my $reps = $CC_col_widths->[$i] - length($text);
 589         my $space = ' ' x max($reps, 0);
 590         print("$space$text ");
 591     }
 592 }
 593
 594 sub print_events ($)
 595 {
 596     my ($CC_col_widths) = @_;
 597
 598     foreach my $i (@show_order) {
 599         my $event       = $events[$i];
 600         my $event_width = length($event);
 601         my $col_width   = $CC_col_widths->[$i];
 602         my $space       = ' ' x ($col_width - $event_width);
 603         print("$event$space ");
 604     }
 605 }
 606
 607 # Prints summary and function totals (with separate column widths, so that
 608 # function names aren't pushed over unnecessarily by huge summary figures).
 609 # Also returns a hash containing all the files that are involved in getting the
 610 # events count above the thresholds (ie. all the interesting ones).
 611 sub print_summary_and_fn_totals ()
 612 {
 613     my @fn_fullnames = keys   %fn_totals;
 614
 615     # Work out the size of each column for printing (summary and functions
 616     # separately).
 617     my $summary_CC_col_widths = compute_CC_col_widths($summary_CC);
 618     my      $fn_CC_col_widths = compute_CC_col_widths(values %fn_totals);
 619
 620     # Header and counts for summary
 621     print($fancy);
 622     print_events($summary_CC_col_widths);
 623     print("\n");
 624     print($fancy);
 625     print_CC($summary_CC, $summary_CC_col_widths);
 626     print(" PROGRAM TOTALS\n");
 627     print("\n");
 628
 629     # Header for functions
 630     print($fancy);
 631     print_events($fn_CC_col_widths);
 632     print(" file:function\n");
 633     print($fancy);
 634
 635     # Sort function names into order dictated by --sort option.
 636     @fn_fullnames = sort {
 637         mycmp($fn_totals{$a}, $fn_totals{$b})
 638     } @fn_fullnames;
 639
 640
 641     # Assertion
 642     (scalar @sort_order == scalar @thresholds) or
 643         die("sort_order length != thresholds length:\n",
 644             "  @sort_order\n  @thresholds\n");
 645
 646     my $threshold_files       = {};
 647     # @curr_totals has the same shape as @sort_order and @thresholds
 648     my @curr_totals = ();
 649     foreach my $e (@thresholds) {
 650         push(@curr_totals, 0);
 651     }
 652
 653     # Print functions, stopping when the threshold has been reached.
 654     foreach my $fn_name (@fn_fullnames) {
 655
 656         my $fn_CC = $fn_totals{$fn_name};
 657
 658         # Stop when we've reached all the thresholds
 659         my $any_thresholds_exceeded = 0;
 660         foreach my $i (0 .. scalar @thresholds - 1) {
 661             my $prop = safe_div(abs($fn_CC->[$sort_order[$i]] * 100),
 662                                 abs($summary_CC->[$sort_order[$i]]));
 663             $any_thresholds_exceeded ||= ($prop >= $thresholds[$i]);
 664         }
 665         last if not $any_thresholds_exceeded;
 666
 667         # Print function results
 668         print_CC($fn_CC, $fn_CC_col_widths);
 669         print(" $fn_name\n");
 670
 671         # Update the threshold counts
 672         my $filename = $fn_name;
 673         $filename =~ s/:.+$//;    # remove function name
 674         $threshold_files->{$filename} = 1;
 675         foreach my $i (0 .. scalar @sort_order - 1) {
 676             $curr_totals[$i] += $fn_CC->[$sort_order[$i]]
 677                 if (defined $fn_CC->[$sort_order[$i]]);
 678         }
 679     }
 680     print("\n");
 681
 682     return $threshold_files;
 683 }
 684
 685 #-----------------------------------------------------------------------------
 686 # Annotate selected files
 687 #-----------------------------------------------------------------------------
 688
 689 # Issue a warning that the source file is more recent than the input file.
 690 sub warning_on_src_more_recent_than_inputfile ($)
 691 {
 692     my $src_file = $_[0];
 693
 694     my $warning = <<END
 695 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 696 @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@
 697 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 698 @ Source file '$src_file' is more recent than input file '$input_file'.
 699 @ Annotations may not be correct.
 700 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 701
 702 END
 703 ;
 704     print($warning);
 705 }
 706
 707 # If there is information about lines not in the file, issue a warning
 708 # explaining possible causes.
 709 sub warning_on_nonexistent_lines ($$$)
 710 {
 711     my ($src_more_recent_than_inputfile, $src_file, $excess_line_nums) = @_;
 712     my $cause_and_solution;
 713
 714     if ($src_more_recent_than_inputfile) {
 715         $cause_and_solution = <<END
 716 @@ cause:    '$src_file' has changed since information was gathered.
 717 @@           If so, a warning will have already been issued about this.
 718 @@ solution: Recompile program and rerun under "valgrind --cachesim=yes" to
 719 @@           gather new information.
 720 END
 721     # We suppress warnings about .h files
 722     } elsif ($src_file =~ /\.h$/) {
 723         $cause_and_solution = <<END
 724 @@ cause:    bug in the Valgrind's debug info reader that screws up with .h
 725 @@           files sometimes
 726 @@ solution: none, sorry
 727 END
 728     } else {
 729         $cause_and_solution = <<END
 730 @@ cause:    not sure, sorry
 731 END
 732     }
 733
 734     my $warning = <<END
 735 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 736 @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@ WARNING @@
 737 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 738 @@
 739 @@ Information recorded about lines past the end of '$src_file'.
 740 @@
 741 @@ Probable cause and solution:
 742 $cause_and_solution@@
 743 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 744 END
 745 ;
 746     print($warning);
 747 }
 748
 749 sub annotate_ann_files($)
 750 {
 751     my ($threshold_files) = @_;
 752
 753     my %all_ann_files;
 754     my @unfound_auto_annotate_files;
 755     my $printed_totals_CC = [];
 756
 757     # If auto-annotating, add interesting files (but not "???")
 758     if ($auto_annotate) {
 759         delete $threshold_files->{"???"};
 760         %all_ann_files = (%user_ann_files, %$threshold_files)
 761     } else {
 762         %all_ann_files = %user_ann_files;
 763     }
 764
 765     # Track if we did any annotations.
 766     my $did_annotations = 0;
 767
 768     LOOP:
 769     foreach my $src_file (keys %all_ann_files) {
 770
 771         my $opened_file = "";
 772         my $full_file_name = "";
 773         # Nb: include_dirs already includes "", so it works in the case
 774         # where the filename has the full path.
 775         foreach my $include_dir (@include_dirs) {
 776             my $try_name = $include_dir . $src_file;
 777             if (open(INPUTFILE, "< $try_name")) {
 778                 $opened_file    = $try_name;
 779                 $full_file_name = ($include_dir eq ""
 780                                   ? $src_file
 781                                   : "$include_dir + $src_file");
 782                 last;
 783             }
 784         }
 785
 786         if (not $opened_file) {
 787             # Failed to open the file.  If chosen on the command line, die.
 788             # If arose from auto-annotation, print a little message.
 789             if (defined $user_ann_files{$src_file}) {
 790                 die("File $src_file not opened in any of: @include_dirs\n");
 791
 792             } else {
 793                 push(@unfound_auto_annotate_files, $src_file);
 794             }
 795
 796         } else {
 797             # File header (distinguish between user- and auto-selected files).
 798             print("$fancy");
 799             my $ann_type =
 800                 (defined $user_ann_files{$src_file} ? "User" : "Auto");
 801             print("-- $ann_type-annotated source: $full_file_name\n");
 802             print("$fancy");
 803
 804             # Get file's CCs
 805             my $src_file_CCs = $allCCs{$src_file};
 806             if (!defined $src_file_CCs) {
 807                 print("  No information has been collected for $src_file\n\n");
 808                 next LOOP;
 809             }
 810
 811             $did_annotations = 1;
 812
 813             # Numeric, not lexicographic sort!
 814             my @line_nums = sort {$a <=> $b} keys %$src_file_CCs;
 815
 816             # If $src_file more recent than cachegrind.out, issue warning
 817             my $src_more_recent_than_inputfile = 0;
 818             if ((stat $opened_file)[9] > (stat $input_file)[9]) {
 819                 $src_more_recent_than_inputfile = 1;
 820                 warning_on_src_more_recent_than_inputfile($src_file);
 821             }
 822
 823             # Work out the size of each column for printing
 824             my $CC_col_widths = compute_CC_col_widths(values %$src_file_CCs);
 825
 826             # Events header
 827             print_events($CC_col_widths);
 828             print("\n\n");
 829
 830             # Shift out 0 if it's in the line numbers (from unknown entries,
 831             # likely due to bugs in Valgrind's stabs debug info reader)
 832             shift(@line_nums) if (0 == $line_nums[0]);
 833
 834             # Finds interesting line ranges -- all lines with a CC, and all
 835             # lines within $context lines of a line with a CC.
 836             my $n = @line_nums;
 837             my @pairs;
 838             for (my $i = 0; $i < $n; $i++) {
 839                 push(@pairs, $line_nums[$i] - $context);   # lower marker
 840                 while ($i < $n-1 &&
 841                        $line_nums[$i] + 2*$context >= $line_nums[$i+1]) {
 842                     $i++;
 843                 }
 844                 push(@pairs, $line_nums[$i] + $context);   # upper marker
 845             }
 846
 847             # Annotate chosen lines, tracking total counts of lines printed
 848             $pairs[0] = 1 if ($pairs[0] < 1);
 849             while (@pairs) {
 850                 my $low  = shift @pairs;
 851                 my $high = shift @pairs;
 852                 while ($. < $low-1) {
 853                     my $tmp = <INPUTFILE>;
 854                     last unless (defined $tmp);     # hack to detect EOF
 855                 }
 856                 my $src_line;
 857                 # Print line number, unless start of file
 858                 print("-- line $low " . '-' x 40 . "\n") if ($low != 1);
 859                 while (($. < $high) && ($src_line = <INPUTFILE>)) {
 860                     if (defined $line_nums[0] && $. == $line_nums[0]) {
 861                         print_CC($src_file_CCs->{$.}, $CC_col_widths);
 862                         add_array_a_to_b($src_file_CCs->{$.},
 863                                          $printed_totals_CC);
 864                         shift(@line_nums);
 865
 866                     } else {
 867                         print_CC([], $CC_col_widths);
 868                     }
 869
 870                     print(" $src_line");
 871                 }
 872                 # Print line number, unless EOF
 873                 if ($src_line) {
 874                     print("-- line $high " . '-' x 40 . "\n");
 875                 } else {
 876                     last;
 877                 }
 878             }
 879
 880             # If there was info on lines past the end of the file...
 881             if (@line_nums) {
 882                 foreach my $line_num (@line_nums) {
 883                     print_CC($src_file_CCs->{$line_num}, $CC_col_widths);
 884                     print(" <bogus line $line_num>\n");
 885                 }
 886                 print("\n");
 887                 warning_on_nonexistent_lines($src_more_recent_than_inputfile,
 888                                              $src_file, \@line_nums);
 889             }
 890             print("\n");
 891
 892             # Print summary of counts attributed to file but not to any
 893             # particular line (due to incomplete debug info).
 894             if ($src_file_CCs->{0}) {
 895                 print_CC($src_file_CCs->{0}, $CC_col_widths);
 896                 print(" <counts for unidentified lines in $src_file>\n\n");
 897             }
 898
 899             close(INPUTFILE);
 900         }
 901     }
 902
 903     # Print list of unfound auto-annotate selected files.
 904     if (@unfound_auto_annotate_files) {
 905         print("$fancy");
 906         print("The following files chosen for auto-annotation could not be found:\n");
 907         print($fancy);
 908         foreach my $f (sort @unfound_auto_annotate_files) {
 909             print("  $f\n");
 910         }
 911         print("\n");
 912     }
 913
 914     # If we did any annotating, show how many events were covered by annotated
 915     # lines above.
 916     if ($did_annotations) {
 917         my $CC_col_widths = compute_CC_col_widths($printed_totals_CC);
 918         print($fancy);
 919         print_events($CC_col_widths);
 920         print("\n");
 921         print($fancy);
 922         print_CC($printed_totals_CC, $CC_col_widths);
 923         print(" events annotated\n\n");
 924     }
 925 }
 926
 927 #----------------------------------------------------------------------------
 928 # "main()"
 929 #----------------------------------------------------------------------------
 930 process_cmd_line();
 931 read_input_file();
 932 print_options();
 933 my $threshold_files = print_summary_and_fn_totals();
 934 annotate_ann_files($threshold_files);
 935
 936 ##--------------------------------------------------------------------##
 937 ##--- end                                           cg_annotate.in ---##
 938 ##--------------------------------------------------------------------##
 939
 940