1 //===-------------------------- CodeRegion.h -------------------*- 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 ///
10 /// This file implements class CodeRegion and CodeRegions, InstrumentRegion,
11 /// AnalysisRegions, and InstrumentRegions.
12 ///
13 /// A CodeRegion describes a region of assembly code guarded by special LLVM-MCA
14 /// comment directives.
15 ///
16 ///   # LLVM-MCA-BEGIN foo
17 ///     ...  ## asm
18 ///   # LLVM-MCA-END
19 ///
20 /// A comment starting with substring LLVM-MCA-BEGIN marks the beginning of a
21 /// new region of code.
22 /// A comment starting with substring LLVM-MCA-END marks the end of the
23 /// last-seen region of code.
24 ///
25 /// Code regions are not allowed to overlap. Each region can have a optional
26 /// description; internally, regions are described by a range of source
27 /// locations (SMLoc objects).
28 ///
29 /// An instruction (a MCInst) is added to a CodeRegion R only if its
30 /// location is in range [R.RangeStart, R.RangeEnd].
31 ///
32 /// A InstrumentRegion describes a region of assembly code guarded by
33 /// special LLVM-MCA comment directives.
34 ///
35 ///   # LLVM-MCA-<INSTRUMENTATION_TYPE> <data>
36 ///     ...  ## asm
37 ///
38 /// where INSTRUMENTATION_TYPE is a type defined in llvm and expects to use
39 /// data.
40 ///
41 /// A comment starting with substring LLVM-MCA-<INSTRUMENTATION_TYPE>
42 /// brings data into scope for llvm-mca to use in its analysis for
43 /// all following instructions.
44 ///
45 /// If the same INSTRUMENTATION_TYPE is found later in the instruction list,
46 /// then the original InstrumentRegion will be automatically ended,
47 /// and a new InstrumentRegion will begin.
48 ///
49 /// If there are comments containing the different INSTRUMENTATION_TYPEs,
50 /// then both data sets remain available. In contrast with a CodeRegion,
51 /// an InstrumentRegion does not need a comment to end the region.
52 //
53 // An instruction (a MCInst) is added to an InstrumentRegion R only
54 // if its location is in range [R.RangeStart, R.RangeEnd].
55 //
56 //===----------------------------------------------------------------------===//
57 
58 #ifndef LLVM_TOOLS_LLVM_MCA_CODEREGION_H
59 #define LLVM_TOOLS_LLVM_MCA_CODEREGION_H
60 
61 #include "llvm/ADT/ArrayRef.h"
62 #include "llvm/ADT/SmallVector.h"
63 #include "llvm/ADT/StringMap.h"
64 #include "llvm/ADT/StringRef.h"
65 #include "llvm/MC/MCInst.h"
66 #include "llvm/MCA/CustomBehaviour.h"
67 #include "llvm/Support/Error.h"
68 #include "llvm/Support/SMLoc.h"
69 #include "llvm/Support/SourceMgr.h"
70 #include <vector>
71 
72 namespace llvm {
73 namespace mca {
74 
75 /// A region of assembly code.
76 ///
77 /// It identifies a sequence of machine instructions.
78 class CodeRegion {
79   // An optional descriptor for this region.
80   llvm::StringRef Description;
81   // Instructions that form this region.
82   llvm::SmallVector<llvm::MCInst, 16> Instructions;
83   // Source location range.
84   llvm::SMLoc RangeStart;
85   llvm::SMLoc RangeEnd;
86 
87   CodeRegion(const CodeRegion &) = delete;
88   CodeRegion &operator=(const CodeRegion &) = delete;
89 
90 public:
91   CodeRegion(llvm::StringRef Desc, llvm::SMLoc Start)
92       : Description(Desc), RangeStart(Start) {}
93 
94   virtual ~CodeRegion() = default;
95 
96   void addInstruction(const llvm::MCInst &Instruction) {
97     Instructions.emplace_back(Instruction);
98   }
99 
100   llvm::SMLoc startLoc() const { return RangeStart; }
101   llvm::SMLoc endLoc() const { return RangeEnd; }
102 
103   void setEndLocation(llvm::SMLoc End) { RangeEnd = End; }
104   bool empty() const { return Instructions.empty(); }
105   bool isLocInRange(llvm::SMLoc Loc) const;
106 
107   llvm::ArrayRef<llvm::MCInst> getInstructions() const { return Instructions; }
108 
109   llvm::StringRef getDescription() const { return Description; }
110 };
111 
112 /// Alias AnalysisRegion with CodeRegion since CodeRegionGenerator
113 /// is absract and AnalysisRegionGenerator operates on AnalysisRegions
114 using AnalysisRegion = CodeRegion;
115 
116 /// A CodeRegion that contains instrumentation that can be used
117 /// in analysis of the region.
118 class InstrumentRegion : public CodeRegion {
119   /// Instrument for this region.
120   UniqueInstrument I;
121 
122 public:
123   InstrumentRegion(llvm::StringRef Desc, llvm::SMLoc Start, UniqueInstrument I)
124       : CodeRegion(Desc, Start), I(std::move(I)) {}
125 
126 public:
127   Instrument *getInstrument() const { return I.get(); }
128 };
129 
130 class CodeRegionParseError final : public Error {};
131 
132 class CodeRegions {
133   CodeRegions(const CodeRegions &) = delete;
134   CodeRegions &operator=(const CodeRegions &) = delete;
135 
136 protected:
137   // A source manager. Used by the tool to generate meaningful warnings.
138   llvm::SourceMgr &SM;
139 
140   using UniqueCodeRegion = std::unique_ptr<CodeRegion>;
141   std::vector<UniqueCodeRegion> Regions;
142   llvm::StringMap<unsigned> ActiveRegions;
143   bool FoundErrors;
144 
145 public:
146   CodeRegions(llvm::SourceMgr &S) : SM(S), FoundErrors(false) {}
147   virtual ~CodeRegions() = default;
148 
149   typedef std::vector<UniqueCodeRegion>::iterator iterator;
150   typedef std::vector<UniqueCodeRegion>::const_iterator const_iterator;
151 
152   iterator begin() { return Regions.begin(); }
153   iterator end() { return Regions.end(); }
154   const_iterator begin() const { return Regions.cbegin(); }
155   const_iterator end() const { return Regions.cend(); }
156 
157   void addInstruction(const llvm::MCInst &Instruction);
158   llvm::SourceMgr &getSourceMgr() const { return SM; }
159 
160   llvm::ArrayRef<llvm::MCInst> getInstructionSequence(unsigned Idx) const {
161     return Regions[Idx]->getInstructions();
162   }
163 
164   bool empty() const {
165     return llvm::all_of(Regions, [](const UniqueCodeRegion &Region) {
166       return Region->empty();
167     });
168   }
169 
170   bool isValid() const { return !FoundErrors; }
171 
172   bool isRegionActive(llvm::StringRef Description) const {
173     return ActiveRegions.contains(Description);
174   }
175 
176   virtual void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc) = 0;
177   virtual void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc,
178                            UniqueInstrument Instrument) = 0;
179   virtual void endRegion(llvm::StringRef Description, llvm::SMLoc Loc) = 0;
180 };
181 
182 struct AnalysisRegions : public CodeRegions {
183   AnalysisRegions(llvm::SourceMgr &S);
184 
185   void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc) override;
186   void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc,
187                    UniqueInstrument Instrument) override {}
188   void endRegion(llvm::StringRef Description, llvm::SMLoc Loc) override;
189 };
190 
191 struct InstrumentRegions : public CodeRegions {
192 
193   InstrumentRegions(llvm::SourceMgr &S);
194 
195   void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc) override{};
196   void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc,
197                    UniqueInstrument Instrument) override;
198   void endRegion(llvm::StringRef Description, llvm::SMLoc Loc) override;
199 
200   const SmallVector<Instrument *> getActiveInstruments(llvm::SMLoc Loc) const;
201 };
202 
203 } // namespace mca
204 } // namespace llvm
205 
206 #endif
207