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
72namespace llvm {
73namespace mca {
74
75/// A region of assembly code.
76///
77/// It identifies a sequence of machine instructions.
78class 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
90public:
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(Args: 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
114using AnalysisRegion = CodeRegion;
115
116/// A CodeRegion that contains instrumentation that can be used
117/// in analysis of the region.
118class InstrumentRegion : public CodeRegion {
119 /// Instrument for this region.
120 UniqueInstrument I;
121
122public:
123 InstrumentRegion(llvm::StringRef Desc, llvm::SMLoc Start, UniqueInstrument I)
124 : CodeRegion(Desc, Start), I(std::move(I)) {}
125
126public:
127 Instrument *getInstrument() const { return I.get(); }
128};
129
130class CodeRegionParseError final : public Error {};
131
132class CodeRegions {
133 CodeRegions(const CodeRegions &) = delete;
134 CodeRegions &operator=(const CodeRegions &) = delete;
135
136protected:
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
145public:
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(Range: Regions, P: [](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(Key: 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
182struct 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
191struct 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

source code of llvm/tools/llvm-mca/CodeRegion.h