diff options
Diffstat (limited to 'docs')
| -rwxr-xr-x | docs/HowToUseInstrMappings.rst | 179 | ||||
| -rw-r--r-- | docs/WritingAnLLVMBackend.html | 24 |
2 files changed, 203 insertions, 0 deletions
diff --git a/docs/HowToUseInstrMappings.rst b/docs/HowToUseInstrMappings.rst new file mode 100755 index 0000000000..b51e74e23c --- /dev/null +++ b/docs/HowToUseInstrMappings.rst @@ -0,0 +1,179 @@ +.. _how_to_use_instruction_mappings: + +=============================== +How To Use Instruction Mappings +=============================== + +.. sectionauthor:: Jyotsna Verma <jverma@codeaurora.org> + +.. contents:: + :local: + +Introduction +============ + +This document contains information about adding instruction mapping support +for a target. The motivation behind this feature comes from the need to switch +between different instruction formats during various optimizations. One approach +could be to use switch cases which list all the instructions along with formats +they can transition to. However, it has large maintenance overhead +because of the hardcoded instruction names. Also, whenever a new instruction is +added in the .td files, all the relevant switch cases should be modified +accordingly. Instead, the same functionality could be achieved with TableGen and +some support from the .td files for a fraction of maintenance cost. + +``InstrMapping`` Class Overview +=============================== + +TableGen uses relationship models to map instructions with each other. These +models are described using ``InstrMapping`` class as a base. Each model sets +various fields of the ``InstrMapping`` class such that they can uniquely +describe all the instructions using that model. TableGen parses all the relation +models and uses the information to construct relation tables which relate +instructions with each other. These tables are emitted in the +``XXXInstrInfo.inc`` file along with the functions to query them. Following +is the definition of ``InstrMapping`` class definied in Target.td file: + +.. code-block:: llvm + + class InstrMapping { + // Used to reduce search space only to the instructions using this + // relation model. + string FilterClass; + + // List of fields/attributes that should be same for all the instructions in + // a row of the relation table. Think of this as a set of properties shared + // by all the instructions related by this relationship. + list<string> RowFields = []; + + // List of fields/attributes that are same for all the instructions + // in a column of the relation table. + list<string> ColFields = []; + + // Values for the fields/attributes listed in 'ColFields' corresponding to + // the key instruction. This is the instruction that will be transformed + // using this relation model. + list<string> KeyCol = []; + + // List of values for the fields/attributes listed in 'ColFields', one for + // each column in the relation table. These are the instructions a key + // instruction will be transformed into. + list<list<string> > ValueCols = []; + } + +Sample Example +-------------- + +Let's say that we want to have a function +``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` which +takes a non-predicated instruction and returns its predicated true or false form +depending on some input flag, ``inPredSense``. The first step in the process is +to define a relationship model that relates predicated instructions to their +non-predicated form by assigning appropriate values to the ``InstrMapping`` +fields. For this relationship, non-predicated instructions are treated as key +instruction since they are the one used to query the interface function. + +.. code-block:: llvm + + def getPredOpcode : InstrMapping { + // Choose a FilterClass that is used as a base class for all the + // instructions modeling this relationship. This is done to reduce the + // search space only to these set of instructions. + let FilterClass = "PredRel"; + + // Instructions with same values for all the fields in RowFields form a + // row in the resulting relation table. + // For example, if we want to relate 'ADD' (non-predicated) with 'Add_pt' + // (predicated true) and 'Add_pf' (predicated false), then all 3 + // instructions need to have same value for BaseOpcode field. It can be any + // unique value (Ex: XYZ) and should not be shared with any other + // instruction not related to 'add'. + let RowFields = ["BaseOpcode"]; + + // List of attributes that can be used to define key and column instructions + // for a relation. Key instruction is passed as an argument + // to the function used for querying relation tables. Column instructions + // are the instructions they (key) can transform into. + // + // Here, we choose 'PredSense' as ColFields since this is the unique + // attribute of the key (non-predicated) and column (true/false) + // instructions involved in this relationship model. + let ColFields = ["PredSense"]; + + // The key column contains non-predicated instructions. + let KeyCol = ["none"]; + + // Two value columns - first column contains instructions with + // PredSense=true while second column has instructions with PredSense=false. + let ValueCols = [["true"], ["false"]]; + } + +TableGen uses the above relationship model to emit relation table that maps +non-predicated instructions with their predicated forms. It also outputs the +interface function +``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` to query +the table. Here, Function ``getPredOpcode`` takes two arguments, opcode of the +current instruction and PredSense of the desired instruction, and returns +predicated form of the instruction, if found in the relation table. +In order for an instruction to be added into the relation table, it needs +to include relevant information in its definition. For example, consider +following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false) +instructions: + +.. code-block::llvm + + def ADD : ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b), + "$dst = add($a, $b)", + [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a), + (i32 IntRegs:$b)))]>; + + def ADD_Pt : ALU32_rr<(outs IntRegs:$dst), + (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), + "if ($p) $dst = add($a, $b)", + []>; + + def ADD_Pf : ALU32_rr<(outs IntRegs:$dst), + (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), + "if (!$p) $dst = add($a, $b)", + []>; + +In this step, we modify these instructions to include the information +required by the relationship model, <tt>getPredOpcode</tt>, so that they can +be related. + +.. code-block::llvm + + def ADD : PredRel, ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b), + "$dst = add($a, $b)", + [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a), + (i32 IntRegs:$b)))]> { + let BaseOpcode = "ADD"; + let PredSense = "none"; + } + + def ADD_Pt : PredRel, ALU32_rr<(outs IntRegs:$dst), + (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), + "if ($p) $dst = add($a, $b)", + []> { + let BaseOpcode = "ADD"; + let PredSense = "true"; + } + + def ADD_Pf : PredRel, ALU32_rr<(outs IntRegs:$dst), + (ins PredRegs:$p, IntRegs:$a, IntRegs:$b), + "if (!$p) $dst = add($a, $b)", + []> { + let BaseOpcode = "ADD"; + let PredSense = "false"; + } + +Please note that all the above instructions use ``PredRel`` as a base class. +This is extremely important since TableGen uses it as a filter for selecting +instructions for ``getPredOpcode`` model. Any instruction not derived from +``PredRel`` is excluded from the analysis. ``BaseOpcode`` is another important +field. Since it's selected as a ``RowFields`` of the model, it is required +to have the same value for all 3 instructions in order to be related. Next, +``PredSense`` is used to determine their column positions by comparing its value +with ``KeyCol`` and ``ValueCols``. If an instruction sets its ``PredSense`` +value to something not used in the relation model, it will not be assigned +a column in the relation table. diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html index 7576d490d7..0ad472cb92 100644 --- a/docs/WritingAnLLVMBackend.html +++ b/docs/WritingAnLLVMBackend.html @@ -32,6 +32,7 @@ <li><a href="#InstructionSet">Instruction Set</a> <ul> <li><a href="#operandMapping">Instruction Operand Mapping</a></li> + <li><a href="#relationMapping">Instruction Relation Mapping</a></li> <li><a href="#implementInstr">Implement a subclass of TargetInstrInfo</a></li> <li><a href="#branchFolding">Branch Folding and If Conversion</a></li> </ul></li> @@ -1259,6 +1260,29 @@ the <tt>rd</tt>, <tt>rs1</tt>, and <tt>rs2</tt> fields respectively. <!-- ======================================================================= --> <h3> + <a name="relationMapping">Instruction Relation Mapping</a> +</h3> + +<div> + +<p> +This TableGen feature is used to relate instructions with each other. It is +particularly useful when you have multiple instruction formats and need to +switch between them after instruction selection. This entire feature is driven +by relation models which can be defined in <tt>XXXInstrInfo.td</tt> files +according to the target-specific instruction set. Relation models are defined +using <tt>InstrMapping</tt> class as a base. TableGen parses all the models +and generates instruction relation maps using the specified information. +Relation maps are emitted as tables in the <tt>XXXGenInstrInfo.inc</tt> file +along with the functions to query them. For the detailed information on how to +use this feature, please refer to +<a href="HowToUseInstrMappings.html">How to add Instruction Mappings</a> +document. +</p> +</div> + +<!-- ======================================================================= --> +<h3> <a name="implementInstr">Implement a subclass of </a> <a href="CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a> </h3> |