1===============================
2How To Use Instruction Mappings
3===============================
4
5.. contents::
6   :local:
7
8Introduction
9============
10
11This document contains information about adding instruction mapping support
12for a target. The motivation behind this feature comes from the need to switch
13between different instruction formats during various optimizations. One approach
14could be to use switch cases which list all the instructions along with formats
15they can transition to. However, it has large maintenance overhead
16because of the hardcoded instruction names. Also, whenever a new instruction is
17added in the .td files, all the relevant switch cases should be modified
18accordingly. Instead, the same functionality could be achieved with TableGen and
19some support from the .td files for a fraction of maintenance cost.
20
21``InstrMapping`` Class Overview
22===============================
23
24TableGen uses relationship models to map instructions with each other. These
25models are described using ``InstrMapping`` class as a base. Each model sets
26various fields of the ``InstrMapping`` class such that they can uniquely
27describe all the instructions using that model. TableGen parses all the relation
28models and uses the information to construct relation tables which relate
29instructions with each other. These tables are emitted in the
30``XXXInstrInfo.inc`` file along with the functions to query them. Following
31is 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
60Sample Example
61--------------
62
63Let's say that we want to have a function
64``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` which
65takes a non-predicated instruction and returns its predicated true or false form
66depending on some input flag, ``inPredSense``. The first step in the process is
67to define a relationship model that relates predicated instructions to their
68non-predicated form by assigning appropriate values to the ``InstrMapping``
69fields. For this relationship, non-predicated instructions are treated as key
70instruction 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
107TableGen uses the above relationship model to emit relation table that maps
108non-predicated instructions with their predicated forms. It also outputs the
109interface function
110``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` to query
111the table. Here, Function ``getPredOpcode`` takes two arguments, opcode of the
112current instruction and PredSense of the desired instruction, and returns
113predicated form of the instruction, if found in the relation table.
114In order for an instruction to be added into the relation table, it needs
115to include relevant information in its definition. For example, consider
116following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false)
117instructions:
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
136In this step, we modify these instructions to include the information
137required by the relationship model, <tt>getPredOpcode</tt>, so that they can
138be 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
166Please note that all the above instructions use ``PredRel`` as a base class.
167This is extremely important since TableGen uses it as a filter for selecting
168instructions for ``getPredOpcode`` model. Any instruction not derived from
169``PredRel`` is excluded from the analysis. ``BaseOpcode`` is another important
170field. Since it's selected as a ``RowFields`` of the model, it is required
171to 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
173with ``KeyCol`` and ``ValueCols``. If an instruction sets its ``PredSense``
174value to something not used in the relation model, it will not be assigned
175a column in the relation table.
176