include/llvm/Support/DebugCounter.h

   1 //===- llvm/Support/DebugCounter.h - Debug counter support ------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 /// \file
   9 /// This file provides an implementation of debug counters.  Debug
  10 /// counters are a tool that let you narrow down a miscompilation to a specific
  11 /// thing happening.
  12 ///
  13 /// To give a use case: Imagine you have a file, very large, and you
  14 /// are trying to understand the minimal transformation that breaks it. Bugpoint
  15 /// and bisection is often helpful here in narrowing it down to a specific pass,
  16 /// but it's still a very large file, and a very complicated pass to try to
  17 /// debug.  That is where debug counting steps in.  You can instrument the pass
  18 /// with a debug counter before it does a certain thing, and depending on the
  19 /// counts, it will either execute that thing or not.  The debug counter itself
  20 /// consists of a skip and a count.  Skip is the number of times shouldExecute
  21 /// needs to be called before it returns true.  Count is the number of times to
  22 /// return true once Skip is 0.  So a skip=47, count=2 ,would skip the first 47
  23 /// executions by returning false from shouldExecute, then execute twice, and
  24 /// then return false again.
  25 /// Note that a counter set to a negative number will always execute.
  26 /// For a concrete example, during predicateinfo creation, the renaming pass
  27 /// replaces each use with a renamed use.
  28 ////
  29 /// If I use DEBUG_COUNTER to create a counter called "predicateinfo", and
  30 /// variable name RenameCounter, and then instrument this renaming with a debug
  31 /// counter, like so:
  32 ///
  33 /// if (!DebugCounter::shouldExecute(RenameCounter)
  34 /// <continue or return or whatever not executing looks like>
  35 ///
  36 /// Now I can, from the command line, make it rename or not rename certain uses
  37 /// by setting the skip and count.
  38 /// So for example
  39 /// bin/opt -debug-counter=predicateinfo-skip=47,predicateinfo-count=1
  40 /// will skip renaming the first 47 uses, then rename one, then skip the rest.
  41 //===----------------------------------------------------------------------===//
  42
  43 #ifndef LLVM_SUPPORT_DEBUGCOUNTER_H
  44 #define LLVM_SUPPORT_DEBUGCOUNTER_H
  45
  46 #include "llvm/ADT/DenseMap.h"
  47 #include "llvm/ADT/UniqueVector.h"
  48 #include "llvm/Support/CommandLine.h"
  49 #include "llvm/Support/Debug.h"
  50 #include "llvm/Support/raw_ostream.h"
  51 #include <string>
  52
  53 namespace llvm {
  54
  55 class DebugCounter {
  56 public:
  57   ~DebugCounter();
  58
  59   /// Returns a reference to the singleton instance.
  60   static DebugCounter &instance();
  61
  62   // Used by the command line option parser to push a new value it parsed.
  63   void push_back(const std::string &);
  64
  65   // Register a counter with the specified name.
  66   //
  67   // FIXME: Currently, counter registration is required to happen before command
  68   // line option parsing. The main reason to register counters is to produce a
  69   // nice list of them on the command line, but i'm not sure this is worth it.
  70   static unsigned registerCounter(StringRef Name, StringRef Desc) {
  71     return instance().addCounter(Name, Desc);
  72   }
  73   inline static bool shouldExecute(unsigned CounterName) {
  74     if (!isCountingEnabled())
  75       return true;
  76
  77     auto &Us = instance();
  78     auto Result = Us.Counters.find(CounterName);
  79     if (Result != Us.Counters.end()) {
  80       auto &CounterInfo = Result->second;
  81       ++CounterInfo.Count;
  82
  83       // We only execute while the Skip is not smaller than Count,
  84       // and the StopAfter + Skip is larger than Count.
  85       // Negative counters always execute.
  86       if (CounterInfo.Skip < 0)
  87         return true;
  88       if (CounterInfo.Skip >= CounterInfo.Count)
  89         return false;
  90       if (CounterInfo.StopAfter < 0)
  91         return true;
  92       return CounterInfo.StopAfter + CounterInfo.Skip >= CounterInfo.Count;
  93     }
  94     // Didn't find the counter, should we warn?
  95     return true;
  96   }
  97
  98   // Return true if a given counter had values set (either programatically or on
  99   // the command line).  This will return true even if those values are
 100   // currently in a state where the counter will always execute.
 101   static bool isCounterSet(unsigned ID) {
 102     return instance().Counters[ID].IsSet;
 103   }
 104
 105   // Return the Count for a counter. This only works for set counters.
 106   static int64_t getCounterValue(unsigned ID) {
 107     auto &Us = instance();
 108     auto Result = Us.Counters.find(ID);
 109     assert(Result != Us.Counters.end() && "Asking about a non-set counter");
 110     return Result->second.Count;
 111   }
 112
 113   // Set a registered counter to a given Count value.
 114   static void setCounterValue(unsigned ID, int64_t Count) {
 115     auto &Us = instance();
 116     Us.Counters[ID].Count = Count;
 117   }
 118
 119   // Dump or print the current counter set into llvm::dbgs().
 120   LLVM_DUMP_METHOD void dump() const;
 121
 122   void print(raw_ostream &OS) const;
 123
 124   // Get the counter ID for a given named counter, or return 0 if none is found.
 125   unsigned getCounterId(const std::string &Name) const {
 126     return RegisteredCounters.idFor(Name);
 127   }
 128
 129   // Return the number of registered counters.
 130   unsigned int getNumCounters() const { return RegisteredCounters.size(); }
 131
 132   // Return the name and description of the counter with the given ID.
 133   std::pair<std::string, std::string> getCounterInfo(unsigned ID) const {
 134     return std::make_pair(RegisteredCounters[ID], Counters.lookup(ID).Desc);
 135   }
 136
 137   // Iterate through the registered counters
 138   typedef UniqueVector<std::string> CounterVector;
 139   CounterVector::const_iterator begin() const {
 140     return RegisteredCounters.begin();
 141   }
 142   CounterVector::const_iterator end() const { return RegisteredCounters.end(); }
 143
 144   // Force-enables counting all DebugCounters.
 145   //
 146   // Since DebugCounters are incompatible with threading (not only do they not
 147   // make sense, but we'll also see data races), this should only be used in
 148   // contexts where we're certain we won't spawn threads.
 149   static void enableAllCounters() { instance().Enabled = true; }
 150
 151 private:
 152   static bool isCountingEnabled() {
 153 // Compile to nothing when debugging is off
 154 #ifdef NDEBUG
 155     return false;
 156 #else
 157     return instance().Enabled;
 158 #endif
 159   }
 160
 161   unsigned addCounter(const std::string &Name, const std::string &Desc) {
 162     unsigned Result = RegisteredCounters.insert(Name);
 163     Counters[Result] = {};
 164     Counters[Result].Desc = Desc;
 165     return Result;
 166   }
 167   // Struct to store counter info.
 168   struct CounterInfo {
 169     int64_t Count = 0;
 170     int64_t Skip = 0;
 171     int64_t StopAfter = -1;
 172     bool IsSet = false;
 173     std::string Desc;
 174   };
 175   DenseMap<unsigned, CounterInfo> Counters;
 176   CounterVector RegisteredCounters;
 177
 178   // Whether we should do DebugCounting at all. DebugCounters aren't
 179   // thread-safe, so this should always be false in multithreaded scenarios.
 180   bool Enabled = false;
 181 };
 182
 183 #define DEBUG_COUNTER(VARNAME, COUNTERNAME, DESC)                              \
 184   static const unsigned VARNAME =                                              \
 185       DebugCounter::registerCounter(COUNTERNAME, DESC)
 186
 187 } // namespace llvm
 188 #endif