docs/HowToUseInstrMappings.rst

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