docs/HowToUseInstrMappings.rst

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