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   void addInstruction(const llvm::MCInst &Instruction) {
95     Instructions.emplace_back(Instruction);
96   }
97 
98   llvm::SMLoc startLoc() const { return RangeStart; }
99   llvm::SMLoc endLoc() const { return RangeEnd; }
100 
101   void setEndLocation(llvm::SMLoc End) { RangeEnd = End; }
102   bool empty() const { return Instructions.empty(); }
103   bool isLocInRange(llvm::SMLoc Loc) const;
104 
105   llvm::ArrayRef<llvm::MCInst> getInstructions() const { return Instructions; }
106 
107   llvm::StringRef getDescription() const { return Description; }
108 };
109 
110 /// Alias AnalysisRegion with CodeRegion since CodeRegionGenerator
111 /// is absract and AnalysisRegionGenerator operates on AnalysisRegions
112 using AnalysisRegion = CodeRegion;
113 
114 /// A CodeRegion that contains instrumentation that can be used
115 /// in analysis of the region.
116 class InstrumentRegion : public CodeRegion {
117   /// Instrument for this region.
118   SharedInstrument Instrument;
119 
120 public:
121   InstrumentRegion(llvm::StringRef Desc, llvm::SMLoc Start, SharedInstrument I)
122       : CodeRegion(Desc, Start), Instrument(I) {}
123 
124 public:
125   SharedInstrument getInstrument() const { return Instrument; }
126 };
127 
128 class CodeRegionParseError final : public Error {};
129 
130 class CodeRegions {
131   CodeRegions(const CodeRegions &) = delete;
132   CodeRegions &operator=(const CodeRegions &) = delete;
133 
134 protected:
135   // A source manager. Used by the tool to generate meaningful warnings.
136   llvm::SourceMgr &SM;
137 
138   using UniqueCodeRegion = std::unique_ptr<CodeRegion>;
139   std::vector<UniqueCodeRegion> Regions;
140   llvm::StringMap<unsigned> ActiveRegions;
141   bool FoundErrors;
142 
143 public:
144   CodeRegions(llvm::SourceMgr &S) : SM(S), FoundErrors(false) {}
145 
146   typedef std::vector<UniqueCodeRegion>::iterator iterator;
147   typedef std::vector<UniqueCodeRegion>::const_iterator const_iterator;
148 
149   iterator begin() { return Regions.begin(); }
150   iterator end() { return Regions.end(); }
151   const_iterator begin() const { return Regions.cbegin(); }
152   const_iterator end() const { return Regions.cend(); }
153 
154   void addInstruction(const llvm::MCInst &Instruction);
155   llvm::SourceMgr &getSourceMgr() const { return SM; }
156 
157   llvm::ArrayRef<llvm::MCInst> getInstructionSequence(unsigned Idx) const {
158     return Regions[Idx]->getInstructions();
159   }
160 
161   bool empty() const {
162     return llvm::all_of(Regions, [](const UniqueCodeRegion &Region) {
163       return Region->empty();
164     });
165   }
166 
167   bool isValid() const { return !FoundErrors; }
168 
169   bool isRegionActive(llvm::StringRef Description) const {
170     return ActiveRegions.find(Description) != ActiveRegions.end();
171   }
172 };
173 
174 struct AnalysisRegions : public CodeRegions {
175   AnalysisRegions(llvm::SourceMgr &S);
176 
177   void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc);
178   void endRegion(llvm::StringRef Description, llvm::SMLoc Loc);
179 };
180 
181 struct InstrumentRegions : public CodeRegions {
182   InstrumentRegions(llvm::SourceMgr &S);
183 
184   void beginRegion(llvm::StringRef Description, llvm::SMLoc Loc,
185                    SharedInstrument Instrument);
186   void endRegion(llvm::StringRef Description, llvm::SMLoc Loc);
187 
188   const SmallVector<SharedInstrument>
189   getActiveInstruments(llvm::SMLoc Loc) const;
190 };
191 
192 } // namespace mca
193 } // namespace llvm
194 
195 #endif
196