1 =============================== 2 How To Use Instruction Mappings 3 =============================== 4 5 .. contents:: 6 :local: 7 8 Introduction 9 ============ 10 11 This document contains information about adding instruction mapping support 12 for a target. The motivation behind this feature comes from the need to switch 13 between different instruction formats during various optimizations. One approach 14 could be to use switch cases which list all the instructions along with formats 15 they can transition to. However, it has large maintenance overhead 16 because of the hardcoded instruction names. Also, whenever a new instruction is 17 added in the .td files, all the relevant switch cases should be modified 18 accordingly. Instead, the same functionality could be achieved with TableGen and 19 some support from the .td files for a fraction of maintenance cost. 20 21 ``InstrMapping`` Class Overview 22 =============================== 23 24 TableGen uses relationship models to map instructions with each other. These 25 models are described using ``InstrMapping`` class as a base. Each model sets 26 various fields of the ``InstrMapping`` class such that they can uniquely 27 describe all the instructions using that model. TableGen parses all the relation 28 models and uses the information to construct relation tables which relate 29 instructions with each other. These tables are emitted in the 30 ``XXXInstrInfo.inc`` file along with the functions to query them. Following 31 is the definition of ``InstrMapping`` class definied in Target.td file: 32 33 .. code-block:: llvm 34 35 class InstrMapping { 36 // Used to reduce search space only to the instructions using this 37 // relation model. 38 string FilterClass; 39 40 // List of fields/attributes that should be same for all the instructions in 41 // a row of the relation table. Think of this as a set of properties shared 42 // by all the instructions related by this relationship. 43 list<string> RowFields = []; 44 45 // List of fields/attributes that are same for all the instructions 46 // in a column of the relation table. 47 list<string> ColFields = []; 48 49 // Values for the fields/attributes listed in 'ColFields' corresponding to 50 // the key instruction. This is the instruction that will be transformed 51 // using this relation model. 52 list<string> KeyCol = []; 53 54 // List of values for the fields/attributes listed in 'ColFields', one for 55 // each column in the relation table. These are the instructions a key 56 // instruction will be transformed into. 57 list<list<string> > ValueCols = []; 58 } 59 60 Sample Example 61 -------------- 62 63 Let's say that we want to have a function 64 ``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` which 65 takes a non-predicated instruction and returns its predicated true or false form 66 depending on some input flag, ``inPredSense``. The first step in the process is 67 to define a relationship model that relates predicated instructions to their 68 non-predicated form by assigning appropriate values to the ``InstrMapping`` 69 fields. For this relationship, non-predicated instructions are treated as key 70 instruction since they are the one used to query the interface function. 71 72 .. code-block:: llvm 73 74 def getPredOpcode : InstrMapping { 75 // Choose a FilterClass that is used as a base class for all the 76 // instructions modeling this relationship. This is done to reduce the 77 // search space only to these set of instructions. 78 let FilterClass = "PredRel"; 79 80 // Instructions with same values for all the fields in RowFields form a 81 // row in the resulting relation table. 82 // For example, if we want to relate 'ADD' (non-predicated) with 'Add_pt' 83 // (predicated true) and 'Add_pf' (predicated false), then all 3 84 // instructions need to have same value for BaseOpcode field. It can be any 85 // unique value (Ex: XYZ) and should not be shared with any other 86 // instruction not related to 'add'. 87 let RowFields = ["BaseOpcode"]; 88 89 // List of attributes that can be used to define key and column instructions 90 // for a relation. Key instruction is passed as an argument 91 // to the function used for querying relation tables. Column instructions 92 // are the instructions they (key) can transform into. 93 // 94 // Here, we choose 'PredSense' as ColFields since this is the unique 95 // attribute of the key (non-predicated) and column (true/false) 96 // instructions involved in this relationship model. 97 let ColFields = ["PredSense"]; 98 99 // The key column contains non-predicated instructions. 100 let KeyCol = ["none"]; 101 102 // Two value columns - first column contains instructions with 103 // PredSense=true while second column has instructions with PredSense=false. 104 let ValueCols = [["true"], ["false"]]; 105 } 106 107 TableGen uses the above relationship model to emit relation table that maps 108 non-predicated instructions with their predicated forms. It also outputs the 109 interface function 110 ``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` to query 111 the table. Here, Function ``getPredOpcode`` takes two arguments, opcode of the 112 current instruction and PredSense of the desired instruction, and returns 113 predicated form of the instruction, if found in the relation table. 114 In order for an instruction to be added into the relation table, it needs 115 to include relevant information in its definition. For example, consider 116 following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false) 117 instructions: 118 119 .. code-block:: llvm 120 121 def ADD : ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b), 122 "$dst = add($a, $b)", 123 [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a), 124 (i32 IntRegs:$b)))]>; 125 126 def ADD_Pt : ALU32_rr<(outs IntRegs:$dst), 127 (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), 128 "if ($p) $dst = add($a, $b)", 129 []>; 130 131 def ADD_Pf : ALU32_rr<(outs IntRegs:$dst), 132 (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), 133 "if (!$p) $dst = add($a, $b)", 134 []>; 135 136 In this step, we modify these instructions to include the information 137 required by the relationship model, <tt>getPredOpcode</tt>, so that they can 138 be related. 139 140 .. code-block:: llvm 141 142 def ADD : PredRel, ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b), 143 "$dst = add($a, $b)", 144 [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a), 145 (i32 IntRegs:$b)))]> { 146 let BaseOpcode = "ADD"; 147 let PredSense = "none"; 148 } 149 150 def ADD_Pt : PredRel, ALU32_rr<(outs IntRegs:$dst), 151 (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), 152 "if ($p) $dst = add($a, $b)", 153 []> { 154 let BaseOpcode = "ADD"; 155 let PredSense = "true"; 156 } 157 158 def ADD_Pf : PredRel, ALU32_rr<(outs IntRegs:$dst), 159 (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), 160 "if (!$p) $dst = add($a, $b)", 161 []> { 162 let BaseOpcode = "ADD"; 163 let PredSense = "false"; 164 } 165 166 Please note that all the above instructions use ``PredRel`` as a base class. 167 This is extremely important since TableGen uses it as a filter for selecting 168 instructions for ``getPredOpcode`` model. Any instruction not derived from 169 ``PredRel`` is excluded from the analysis. ``BaseOpcode`` is another important 170 field. Since it's selected as a ``RowFields`` of the model, it is required 171 to have the same value for all 3 instructions in order to be related. Next, 172 ``PredSense`` is used to determine their column positions by comparing its value 173 with ``KeyCol`` and ``ValueCols``. If an instruction sets its ``PredSense`` 174 value to something not used in the relation model, it will not be assigned 175 a column in the relation table. 176
