1 //===- TargetInstrPredicate.td - ---------------------------*- tablegen -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines class MCInstPredicate and its subclasses.
12 // MCInstPredicate definitions are used by target scheduling models to describe
13 // constraints on instructions.
15 // Here is an example of an MCInstPredicate definition in tablegen:
17 // def MCInstPredicateExample : CheckAll<[
18 // CheckOpcode<[BLR]>,
19 // CheckIsRegOperand<0>,
20 // CheckNot<CheckRegOperand<0, LR>>]>;
22 // The syntax for MCInstPredicate is declarative, and predicate definitions can
23 // be composed together in order to generate more complex constraints.
25 // The `CheckAll` from the example defines a composition of three different
26 // predicates. Definition `MCInstPredicateExample` identifies instructions
27 // whose opcode is BLR, and whose first operand is a register different from
30 // Every MCInstPredicate class has a well-known semantic in tablegen. For
31 // example, `CheckOpcode` is a special type of predicate used to describe a
32 // constraint on the value of an instruction opcode.
34 // MCInstPredicate definitions are typically used by scheduling models to
35 // construct MCSchedPredicate definitions (see the definition of class
36 // MCSchedPredicate in llvm/Target/TargetSchedule.td).
37 // In particular, an MCSchedPredicate can be used instead of a SchedPredicate
38 // when defining the set of SchedReadVariant and SchedWriteVariant of a
39 // processor scheduling model.
41 // The `MCInstPredicateExample` definition above is equivalent (and therefore
42 // could replace) the following definition from a previous ExynosM3 model (see
43 // AArch64SchedExynosM3.td):
45 // def M3BranchLinkFastPred : SchedPredicate<[{
46 // MI->getOpcode() == AArch64::BLR &&
47 // MI->getOperand(0).isReg() &&
48 // MI->getOperand(0).getReg() != AArch64::LR}]>;
50 // The main advantage of using MCInstPredicate instead of SchedPredicate is
51 // portability: users don't need to specify predicates in C++. As a consequence
52 // of this, MCInstPredicate definitions are not bound to a particular
53 // representation (i.e. MachineInstr vs MCInst).
55 // Tablegen backends know how to expand MCInstPredicate definitions into actual
56 // C++ code that works on MachineInstr (and/or MCInst).
58 // Instances of class PredicateExpander (see utils/Tablegen/PredicateExpander.h)
59 // know how to expand a predicate. For each MCInstPredicate class, there must be
60 // an "expand" method available in the PredicateExpander interface.
62 // For example, a `CheckOpcode` predicate is expanded using method
63 // `PredicateExpander::expandCheckOpcode()`.
65 // New MCInstPredicate classes must be added to this file. For each new class
66 // XYZ, an "expandXYZ" method must be added to the PredicateExpander.
68 //===----------------------------------------------------------------------===//
70 // Forward declarations.
72 class SchedMachineModel;
74 // A generic machine instruction predicate.
75 class MCInstPredicate;
77 class MCTrue : MCInstPredicate; // A predicate that always evaluates to True.
78 class MCFalse : MCInstPredicate; // A predicate that always evaluates to False.
79 def TruePred : MCTrue;
80 def FalsePred : MCFalse;
82 // A predicate used to negate the outcome of another predicate.
83 // It allows to easily express "set difference" operations. For example, it
84 // makes it easy to describe a check that tests if an opcode is not part of a
86 class CheckNot<MCInstPredicate P> : MCInstPredicate {
87 MCInstPredicate Pred = P;
90 // This class is used as a building block to define predicates on instruction
91 // operands. It is used to reference a specific machine operand.
92 class MCOperandPredicate<int Index> : MCInstPredicate {
96 // Return true if machine operand at position `Index` is a register operand.
97 class CheckIsRegOperand<int Index> : MCOperandPredicate<Index>;
99 // Return true if machine operand at position `Index` is an immediate operand.
100 class CheckIsImmOperand<int Index> : MCOperandPredicate<Index>;
102 // Check if machine operands at index `First` and index `Second` both reference
103 // the same register.
104 class CheckSameRegOperand<int First, int Second> : MCInstPredicate {
105 int FirstIndex = First;
106 int SecondIndex = Second;
109 // Base class for checks on register/immediate operands.
110 // It allows users to define checks like:
111 // MyFunction(MI->getOperand(Index).getImm()) == Val;
113 // In the example above, `MyFunction` is a function that takes as input an
114 // immediate operand value, and returns another value. Field `FunctionMapper` is
115 // the name of the function to call on the operand value.
116 class CheckOperandBase<int Index, string Fn = ""> : MCOperandPredicate<Index> {
117 string FunctionMapper = Fn;
120 // Check that the machine register operand at position `Index` references
121 // register R. This predicate assumes that we already checked that the machine
122 // operand at position `Index` is a register operand.
123 class CheckRegOperand<int Index, Register R> : CheckOperandBase<Index> {
127 // Check if register operand at index `Index` is the invalid register.
128 class CheckInvalidRegOperand<int Index> : CheckOperandBase<Index>;
130 // Check that the operand at position `Index` is immediate `Imm`.
131 // If field `FunctionMapper` is a non-empty string, then function
132 // `FunctionMapper` is applied to the operand value, and the return value is then
133 // compared against `Imm`.
134 class CheckImmOperand<int Index, int Imm> : CheckOperandBase<Index> {
138 // Similar to CheckImmOperand, however the immediate is not a literal number.
139 // This is useful when we want to compare the value of an operand against an
140 // enum value, and we know the actual integer value of that enum.
141 class CheckImmOperand_s<int Index, string Value> : CheckOperandBase<Index> {
142 string ImmVal = Value;
145 // Expands to a call to `FunctionMapper` if field `FunctionMapper` is set.
146 // Otherwise, it expands to a CheckNot<CheckInvalidRegOperand<Index>>.
147 class CheckRegOperandSimple<int Index> : CheckOperandBase<Index>;
149 // Expands to a call to `FunctionMapper` if field `FunctionMapper` is set.
150 // Otherwise, it simply evaluates to TruePred.
151 class CheckImmOperandSimple<int Index> : CheckOperandBase<Index>;
153 // Check that the operand at position `Index` is immediate value zero.
154 class CheckZeroOperand<int Index> : CheckImmOperand<Index, 0>;
156 // Check that the instruction has exactly `Num` operands.
157 class CheckNumOperands<int Num> : MCInstPredicate {
161 // Check that the instruction opcode is one of the opcodes in set `Opcodes`.
162 // This is a simple set membership query. The easier way to check if an opcode
163 // is not a member of the set is by using a `CheckNot<CheckOpcode<[...]>>`
165 class CheckOpcode<list<Instruction> Opcodes> : MCInstPredicate {
166 list<Instruction> ValidOpcodes = Opcodes;
169 // Check that the instruction opcode is a pseudo opcode member of the set
170 // `Opcodes`. This check is always expanded to "false" if we are generating
172 class CheckPseudo<list<Instruction> Opcodes> : CheckOpcode<Opcodes>;
174 // A non-portable predicate. Only to use as a last resort when a block of code
175 // cannot possibly be converted in a declarative way using other MCInstPredicate
176 // classes. This check is always expanded to "false" when generating code for
178 class CheckNonPortable<string Code> : MCInstPredicate {
179 string CodeBlock = Code;
182 // A sequence of predicates. It is used as the base class for CheckAll, and
183 // CheckAny. It allows to describe compositions of predicates.
184 class CheckPredicateSequence<list<MCInstPredicate> Preds> : MCInstPredicate {
185 list<MCInstPredicate> Predicates = Preds;
188 // Check that all of the predicates in `Preds` evaluate to true.
189 class CheckAll<list<MCInstPredicate> Sequence>
190 : CheckPredicateSequence<Sequence>;
192 // Check that at least one of the predicates in `Preds` evaluates to true.
193 class CheckAny<list<MCInstPredicate> Sequence>
194 : CheckPredicateSequence<Sequence>;
197 // Used to expand the body of a function predicate. See the definition of
198 // TIIPredicate below.
201 // Expands to a return statement. The return expression is a boolean expression
202 // described by a MCInstPredicate.
203 class MCReturnStatement<MCInstPredicate predicate> : MCStatement {
204 MCInstPredicate Pred = predicate;
207 // Used to automatically construct cases of a switch statement where the switch
208 // variable is an instruction opcode. There is a 'case' for every opcode in the
209 // `opcodes` list, and each case is associated with MCStatement `caseStmt`.
210 class MCOpcodeSwitchCase<list<Instruction> opcodes, MCStatement caseStmt> {
211 list<Instruction> Opcodes = opcodes;
212 MCStatement CaseStmt = caseStmt;
215 // Expands to a switch statement. The switch variable is an instruction opcode.
216 // The auto-generated switch is populated by a number of cases based on the
217 // `cases` list in input. A default case is automatically generated, and it
218 // evaluates to `default`.
219 class MCOpcodeSwitchStatement<list<MCOpcodeSwitchCase> cases,
220 MCStatement default> : MCStatement {
221 list<MCOpcodeSwitchCase> Cases = cases;
222 MCStatement DefaultCase = default;
225 // Base class for function predicates.
226 class FunctionPredicateBase<string name, MCStatement body> {
227 string FunctionName = name;
228 MCStatement Body = body;
231 // Check that a call to method `Name` in class "XXXInstrInfo" (where XXX is
232 // the name of a target) returns true.
234 // TIIPredicate definitions are used to model calls to the target-specific
235 // InstrInfo. A TIIPredicate is treated specially by the InstrInfoEmitter
236 // tablegen backend, which will use it to automatically generate a definition in
237 // the target specific `InstrInfo` class.
239 // There cannot be multiple TIIPredicate definitions with the same name for the
241 class TIIPredicate<string Name, MCStatement body>
242 : FunctionPredicateBase<Name, body>, MCInstPredicate;
244 // A function predicate that takes as input a machine instruction, and returns
247 // This predicate is expanded into a function call by the PredicateExpander.
248 // In particular, the PredicateExpander would either expand this predicate into
249 // a call to `MCInstFn`, or into a call to`MachineInstrFn` depending on whether
250 // it is lowering predicates for MCInst or MachineInstr.
252 // In this context, `MCInstFn` and `MachineInstrFn` are both function names.
253 class CheckFunctionPredicate<string MCInstFn, string MachineInstrFn> : MCInstPredicate {
254 string MCInstFnName = MCInstFn;
255 string MachineInstrFnName = MachineInstrFn;
258 // Used to classify machine instructions based on a machine instruction
261 // Let IC be an InstructionEquivalenceClass definition, and MI a machine
262 // instruction. We say that MI belongs to the equivalence class described by IC
263 // if and only if the following two conditions are met:
264 // a) MI's opcode is in the `opcodes` set, and
265 // b) `Predicate` evaluates to true when applied to MI.
267 // Instances of this class can be used by processor scheduling models to
268 // describe instructions that have a property in common. For example,
269 // InstructionEquivalenceClass definitions can be used to identify the set of
270 // dependency breaking instructions for a processor model.
272 // An (optional) list of operand indices can be used to further describe
273 // properties that apply to instruction operands. For example, it can be used to
274 // identify register uses of a dependency breaking instructions that are not in
276 class InstructionEquivalenceClass<list<Instruction> opcodes,
277 MCInstPredicate pred,
278 list<int> operands = []> {
279 list<Instruction> Opcodes = opcodes;
280 MCInstPredicate Predicate = pred;
281 list<int> OperandIndices = operands;
284 // Used by processor models to describe dependency breaking instructions.
286 // This is mainly an alias for InstructionEquivalenceClass. Input operand
287 // `BrokenDeps` identifies the set of "broken dependencies". There is one bit
288 // per each implicit and explicit input operand. An empty set of broken
289 // dependencies means: "explicit input register operands are independent."
290 class DepBreakingClass<list<Instruction> opcodes, MCInstPredicate pred,
291 list<int> BrokenDeps = []>
292 : InstructionEquivalenceClass<opcodes, pred, BrokenDeps>;
294 // A function descriptor used to describe the signature of a predicate methods
295 // which will be expanded by the STIPredicateExpander into a tablegen'd
296 // XXXGenSubtargetInfo class member definition (here, XXX is a target name).
298 // It describes the signature of a TargetSubtarget hook, as well as a few extra
299 // properties. Examples of extra properties are:
300 // - The default return value for the auto-generate function hook.
301 // - A list of subtarget hooks (Delegates) that are called from this function.
303 class STIPredicateDecl<string name, MCInstPredicate default = FalsePred,
304 bit overrides = 1, bit expandForMC = 1,
305 bit updatesOpcodeMask = 0,
306 list<STIPredicateDecl> delegates = []> {
309 MCInstPredicate DefaultReturnValue = default;
311 // True if this method is declared as virtual in class TargetSubtargetInfo.
312 bit OverridesBaseClassMember = overrides;
314 // True if we need an equivalent predicate function in the MC layer.
315 bit ExpandForMC = expandForMC;
317 // True if the autogenerated method has a extra in/out APInt param used as a
319 bit UpdatesOpcodeMask = updatesOpcodeMask;
321 // A list of STIPredicates used by this definition to delegate part of the
322 // computation. For example, STIPredicateFunction `isDependencyBreaking()`
323 // delegates to `isZeroIdiom()` part of its computation.
324 list<STIPredicateDecl> Delegates = delegates;
327 // A predicate function definition member of class `XXXGenSubtargetInfo`.
329 // If `Declaration.ExpandForMC` is true, then SubtargetEmitter
330 // will also expand another definition of this method that accepts a MCInst.
331 class STIPredicate<STIPredicateDecl declaration,
332 list<InstructionEquivalenceClass> classes> {
333 STIPredicateDecl Declaration = declaration;
334 list<InstructionEquivalenceClass> Classes = classes;
335 SchedMachineModel SchedModel = ?;
338 // Convenience classes and definitions used by processor scheduling models to
339 // describe dependency breaking instructions and move elimination candidates.
340 let UpdatesOpcodeMask = 1 in {
342 def IsZeroIdiomDecl : STIPredicateDecl<"isZeroIdiom">;
344 let Delegates = [IsZeroIdiomDecl] in
345 def IsDepBreakingDecl : STIPredicateDecl<"isDependencyBreaking">;
347 } // UpdatesOpcodeMask
349 def IsOptimizableRegisterMoveDecl
350 : STIPredicateDecl<"isOptimizableRegisterMove">;
352 class IsZeroIdiomFunction<list<DepBreakingClass> classes>
353 : STIPredicate<IsZeroIdiomDecl, classes>;
355 class IsDepBreakingFunction<list<DepBreakingClass> classes>
356 : STIPredicate<IsDepBreakingDecl, classes>;
358 class IsOptimizableRegisterMove<list<InstructionEquivalenceClass> classes>
359 : STIPredicate<IsOptimizableRegisterMoveDecl, classes>;