1 //===- llvm/Support/DebugCounter.h - Debug counter support ------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
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
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.
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
33 /// if (!DebugCounter::shouldExecute(RenameCounter)
34 /// <continue or return or whatever not executing looks like>
36 /// Now I can, from the command line, make it rename or not rename certain uses
37 /// by setting the skip and count.
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 //===----------------------------------------------------------------------===//
43 #ifndef LLVM_SUPPORT_DEBUGCOUNTER_H
44 #define LLVM_SUPPORT_DEBUGCOUNTER_H
46 #include "llvm/ADT/DenseMap.h"
47 #include "llvm/ADT/StringRef.h"
48 #include "llvm/ADT/UniqueVector.h"
49 #include "llvm/Support/Debug.h"
60 /// Returns a reference to the singleton instance.
61 static DebugCounter &instance();
63 // Used by the command line option parser to push a new value it parsed.
64 void push_back(const std::string &);
66 // Register a counter with the specified name.
68 // FIXME: Currently, counter registration is required to happen before command
69 // line option parsing. The main reason to register counters is to produce a
70 // nice list of them on the command line, but i'm not sure this is worth it.
71 static unsigned registerCounter(StringRef Name, StringRef Desc) {
72 return instance().addCounter(std::string(Name), std::string(Desc));
74 inline static bool shouldExecute(unsigned CounterName) {
75 if (!isCountingEnabled())
78 auto &Us = instance();
79 auto Result = Us.Counters.find(CounterName);
80 if (Result != Us.Counters.end()) {
81 auto &CounterInfo = Result->second;
84 // We only execute while the Skip is not smaller than Count,
85 // and the StopAfter + Skip is larger than Count.
86 // Negative counters always execute.
87 if (CounterInfo.Skip < 0)
89 if (CounterInfo.Skip >= CounterInfo.Count)
91 if (CounterInfo.StopAfter < 0)
93 return CounterInfo.StopAfter + CounterInfo.Skip >= CounterInfo.Count;
95 // Didn't find the counter, should we warn?
99 // Return true if a given counter had values set (either programatically or on
100 // the command line). This will return true even if those values are
101 // currently in a state where the counter will always execute.
102 static bool isCounterSet(unsigned ID) {
103 return instance().Counters[ID].IsSet;
106 // Return the Count for a counter. This only works for set counters.
107 static int64_t getCounterValue(unsigned ID) {
108 auto &Us = instance();
109 auto Result = Us.Counters.find(ID);
110 assert(Result != Us.Counters.end() && "Asking about a non-set counter");
111 return Result->second.Count;
114 // Set a registered counter to a given Count value.
115 static void setCounterValue(unsigned ID, int64_t Count) {
116 auto &Us = instance();
117 Us.Counters[ID].Count = Count;
120 // Dump or print the current counter set into llvm::dbgs().
121 LLVM_DUMP_METHOD void dump() const;
123 void print(raw_ostream &OS) const;
125 // Get the counter ID for a given named counter, or return 0 if none is found.
126 unsigned getCounterId(const std::string &Name) const {
127 return RegisteredCounters.idFor(Name);
130 // Return the number of registered counters.
131 unsigned int getNumCounters() const { return RegisteredCounters.size(); }
133 // Return the name and description of the counter with the given ID.
134 std::pair<std::string, std::string> getCounterInfo(unsigned ID) const {
135 return std::make_pair(RegisteredCounters[ID], Counters.lookup(ID).Desc);
138 // Iterate through the registered counters
139 typedef UniqueVector<std::string> CounterVector;
140 CounterVector::const_iterator begin() const {
141 return RegisteredCounters.begin();
143 CounterVector::const_iterator end() const { return RegisteredCounters.end(); }
145 // Force-enables counting all DebugCounters.
147 // Since DebugCounters are incompatible with threading (not only do they not
148 // make sense, but we'll also see data races), this should only be used in
149 // contexts where we're certain we won't spawn threads.
150 static void enableAllCounters() { instance().Enabled = true; }
153 static bool isCountingEnabled() {
154 // Compile to nothing when debugging is off
158 return instance().Enabled;
162 unsigned addCounter(const std::string &Name, const std::string &Desc) {
163 unsigned Result = RegisteredCounters.insert(Name);
164 Counters[Result] = {};
165 Counters[Result].Desc = Desc;
168 // Struct to store counter info.
172 int64_t StopAfter = -1;
176 DenseMap<unsigned, CounterInfo> Counters;
177 CounterVector RegisteredCounters;
179 // Whether we should do DebugCounting at all. DebugCounters aren't
180 // thread-safe, so this should always be false in multithreaded scenarios.
181 bool Enabled = false;
184 #define DEBUG_COUNTER(VARNAME, COUNTERNAME, DESC) \
185 static const unsigned VARNAME = \
186 DebugCounter::registerCounter(COUNTERNAME, DESC)