Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 2d5e3acd2a69070c4e3550e014a54626e18bf12c / . / docs / WritingAnLLVMBackend.html
blob: 5edc117e33645f8b39d43747e52d9b3cf61d8d11 [file] [log] [blame]
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
Bill Wendlinge6b48792009-04-05 00:44:06 +0000[diff] [blame]5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]6 <title>Writing an LLVM Compiler Backend</title>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]7 <link rel="stylesheet" href="llvm.css" type="text/css">
8</head>
9
10<body>
11
Chris Lattner611944b2008-11-11 19:31:26 +0000[diff] [blame]12<div class="doc_title">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]13 Writing an LLVM Compiler Backend
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]14</div>
15
16<ol>
17 <li><a href="#intro">Introduction</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]18 <ul>
19 <li><a href="#Audience">Audience</a></li>
20 <li><a href="#Prerequisite">Prerequisite Reading</a></li>
21 <li><a href="#Basic">Basic Steps</a></li>
22 <li><a href="#Preliminaries">Preliminaries</a></li>
23 </ul>
24 <li><a href="#TargetMachine">Target Machine</a></li>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]25 <li><a href="#TargetRegistration">Target Registration</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]26 <li><a href="#RegisterSet">Register Set and Register Classes</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]27 <ul>
28 <li><a href="#RegisterDef">Defining a Register</a></li>
29 <li><a href="#RegisterClassDef">Defining a Register Class</a></li>
30 <li><a href="#implementRegister">Implement a subclass of TargetRegisterInfo</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]31 </ul></li>
32 <li><a href="#InstructionSet">Instruction Set</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]33 <ul>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]34 <li><a href="#operandMapping">Instruction Operand Mapping</a></li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]35 <li><a href="#implementInstr">Implement a subclass of TargetInstrInfo</a></li>
36 <li><a href="#branchFolding">Branch Folding and If Conversion</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]37 </ul></li>
38 <li><a href="#InstructionSelector">Instruction Selector</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]39 <ul>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]40 <li><a href="#LegalizePhase">The SelectionDAG Legalize Phase</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]41 <ul>
42 <li><a href="#promote">Promote</a></li>
43 <li><a href="#expand">Expand</a></li>
44 <li><a href="#custom">Custom</a></li>
45 <li><a href="#legal">Legal</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]46 </ul></li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]47 <li><a href="#callingConventions">Calling Conventions</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]48 </ul></li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]49 <li><a href="#assemblyPrinter">Assembly Printer</a></li>
50 <li><a href="#subtargetSupport">Subtarget Support</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]51 <li><a href="#jitSupport">JIT Support</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]52 <ul>
53 <li><a href="#mce">Machine Code Emitter</a></li>
54 <li><a href="#targetJITInfo">Target JIT Info</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +0000[diff] [blame]55 </ul></li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]56</ol>
57
58<div class="doc_author">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]59 <p>Written by <a href="http://www.woo.com">Mason Woo</a> and
60 <a href="http://misha.brukman.net">Misha Brukman</a></p>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]61</div>
62
63<!-- *********************************************************************** -->
64<div class="doc_section">
65 <a name="intro">Introduction</a>
66</div>
67<!-- *********************************************************************** -->
68
69<div class="doc_text">
70
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]71<p>
72This document describes techniques for writing compiler backends that convert
73the LLVM Intermediate Representation (IR) to code for a specified machine or
74other languages. Code intended for a specific machine can take the form of
75either assembly code or binary code (usable for a JIT compiler).
76</p>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]77
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]78<p>
79The backend of LLVM features a target-independent code generator that may create
80output for several types of target CPUs &mdash; including X86, PowerPC, Alpha,
81and SPARC. The backend may also be used to generate code targeted at SPUs of the
82Cell processor or GPUs to support the execution of compute kernels.
83</p>
84
85<p>
86The document focuses on existing examples found in subdirectories
87of <tt>llvm/lib/Target</tt> in a downloaded LLVM release. In particular, this
88document focuses on the example of creating a static compiler (one that emits
89text assembly) for a SPARC target, because SPARC has fairly standard
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]90characteristics, such as a RISC instruction set and straightforward calling
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]91conventions.
92</p>
93
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]94</div>
95
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]96<div class="doc_subsection">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]97 <a name="Audience">Audience</a>
98</div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]99
100<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]101
102<p>
103The audience for this document is anyone who needs to write an LLVM backend to
104generate code for a specific hardware or software target.
105</p>
106
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]107</div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]108
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]109<div class="doc_subsection">
110 <a name="Prerequisite">Prerequisite Reading</a>
111</div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]112
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]113<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]114
115<p>
116These essential documents must be read before reading this document:
117</p>
118
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]119<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]120<li><i><a href="http://www.llvm.org/docs/LangRef.html">LLVM Language Reference
121 Manual</a></i> &mdash; a reference manual for the LLVM assembly language.</li>
122
123<li><i><a href="http://www.llvm.org/docs/CodeGenerator.html">The LLVM
124 Target-Independent Code Generator</a></i> &mdash; a guide to the components
125 (classes and code generation algorithms) for translating the LLVM internal
126 representation into machine code for a specified target. Pay particular
127 attention to the descriptions of code generation stages: Instruction
128 Selection, Scheduling and Formation, SSA-based Optimization, Register
129 Allocation, Prolog/Epilog Code Insertion, Late Machine Code Optimizations,
130 and Code Emission.</li>
131
132<li><i><a href="http://www.llvm.org/docs/TableGenFundamentals.html">TableGen
133 Fundamentals</a></i> &mdash;a document that describes the TableGen
134 (<tt>tblgen</tt>) application that manages domain-specific information to
135 support LLVM code generation. TableGen processes input from a target
136 description file (<tt>.td</tt> suffix) and generates C++ code that can be
137 used for code generation.</li>
138
139<li><i><a href="http://www.llvm.org/docs/WritingAnLLVMPass.html">Writing an LLVM
140 Pass</a></i> &mdash; The assembly printer is a <tt>FunctionPass</tt>, as are
141 several SelectionDAG processing steps.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]142</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]143
144<p>
145To follow the SPARC examples in this document, have a copy of
146<i><a href="http://www.sparc.org/standards/V8.pdf">The SPARC Architecture
147Manual, Version 8</a></i> for reference. For details about the ARM instruction
148set, refer to the <i><a href="http://infocenter.arm.com/">ARM Architecture
149Reference Manual</a></i>. For more about the GNU Assembler format
150(<tt>GAS</tt>), see
151<i><a href="http://sourceware.org/binutils/docs/as/index.html">Using As</a></i>,
152especially for the assembly printer. <i>Using As</i> contains a list of target
153machine dependent features.
154</p>
155
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]156</div>
157
158<div class="doc_subsection">
159 <a name="Basic">Basic Steps</a>
160</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]161
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]162<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]163
164<p>
165To write a compiler backend for LLVM that converts the LLVM IR to code for a
166specified target (machine or other language), follow these steps:
167</p>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]168
169<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]170<li>Create a subclass of the TargetMachine class that describes characteristics
171 of your target machine. Copy existing examples of specific TargetMachine
172 class and header files; for example, start with
173 <tt>SparcTargetMachine.cpp</tt> and <tt>SparcTargetMachine.h</tt>, but
174 change the file names for your target. Similarly, change code that
175 references "Sparc" to reference your target. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]176
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]177<li>Describe the register set of the target. Use TableGen to generate code for
178 register definition, register aliases, and register classes from a
179 target-specific <tt>RegisterInfo.td</tt> input file. You should also write
180 additional code for a subclass of the TargetRegisterInfo class that
181 represents the class register file data used for register allocation and
182 also describes the interactions between registers.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]183
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]184<li>Describe the instruction set of the target. Use TableGen to generate code
185 for target-specific instructions from target-specific versions of
186 <tt>TargetInstrFormats.td</tt> and <tt>TargetInstrInfo.td</tt>. You should
187 write additional code for a subclass of the TargetInstrInfo class to
188 represent machine instructions supported by the target machine. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]189
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]190<li>Describe the selection and conversion of the LLVM IR from a Directed Acyclic
191 Graph (DAG) representation of instructions to native target-specific
192 instructions. Use TableGen to generate code that matches patterns and
193 selects instructions based on additional information in a target-specific
194 version of <tt>TargetInstrInfo.td</tt>. Write code
195 for <tt>XXXISelDAGToDAG.cpp</tt>, where XXX identifies the specific target,
196 to perform pattern matching and DAG-to-DAG instruction selection. Also write
197 code in <tt>XXXISelLowering.cpp</tt> to replace or remove operations and
198 data types that are not supported natively in a SelectionDAG. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]199
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]200<li>Write code for an assembly printer that converts LLVM IR to a GAS format for
201 your target machine. You should add assembly strings to the instructions
202 defined in your target-specific version of <tt>TargetInstrInfo.td</tt>. You
203 should also write code for a subclass of AsmPrinter that performs the
204 LLVM-to-assembly conversion and a trivial subclass of TargetAsmInfo.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]205
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]206<li>Optionally, add support for subtargets (i.e., variants with different
207 capabilities). You should also write code for a subclass of the
208 TargetSubtarget class, which allows you to use the <tt>-mcpu=</tt>
209 and <tt>-mattr=</tt> command-line options.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]210
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]211<li>Optionally, add JIT support and create a machine code emitter (subclass of
212 TargetJITInfo) that is used to emit binary code directly into memory. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]213</ul>
214
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]215<p>
216In the <tt>.cpp</tt> and <tt>.h</tt>. files, initially stub up these methods and
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]217then implement them later. Initially, you may not know which private members
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]218that the class will need and which components will need to be subclassed.
219</p>
220
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]221</div>
222
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]223<div class="doc_subsection">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]224 <a name="Preliminaries">Preliminaries</a>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]225</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]226
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]227<div class="doc_text">
228
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]229<p>
230To actually create your compiler backend, you need to create and modify a few
231files. The absolute minimum is discussed here. But to actually use the LLVM
232target-independent code generator, you must perform the steps described in
233the <a href="http://www.llvm.org/docs/CodeGenerator.html">LLVM
234Target-Independent Code Generator</a> document.
235</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000[diff] [blame]236
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]237<p>
238First, you should create a subdirectory under <tt>lib/Target</tt> to hold all
239the files related to your target. If your target is called "Dummy," create the
240directory <tt>lib/Target/Dummy</tt>.
241</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000[diff] [blame]242
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]243<p>
244In this new
245directory, create a <tt>Makefile</tt>. It is easiest to copy a
246<tt>Makefile</tt> of another target and modify it. It should at least contain
247the <tt>LEVEL</tt>, <tt>LIBRARYNAME</tt> and <tt>TARGET</tt> variables, and then
248include <tt>$(LEVEL)/Makefile.common</tt>. The library can be
249named <tt>LLVMDummy</tt> (for example, see the MIPS target). Alternatively, you
250can split the library into <tt>LLVMDummyCodeGen</tt>
251and <tt>LLVMDummyAsmPrinter</tt>, the latter of which should be implemented in a
252subdirectory below <tt>lib/Target/Dummy</tt> (for example, see the PowerPC
253target).
254</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000[diff] [blame]255
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]256<p>
257Note that these two naming schemes are hardcoded into <tt>llvm-config</tt>.
258Using any other naming scheme will confuse <tt>llvm-config</tt> and produce a
259lot of (seemingly unrelated) linker errors when linking <tt>llc</tt>.
260</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000[diff] [blame]261
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]262<p>
263To make your target actually do something, you need to implement a subclass of
264<tt>TargetMachine</tt>. This implementation should typically be in the file
265<tt>lib/Target/DummyTargetMachine.cpp</tt>, but any file in
266the <tt>lib/Target</tt> directory will be built and should work. To use LLVM's
267target independent code generator, you should do what all current machine
268backends do: create a subclass of <tt>LLVMTargetMachine</tt>. (To create a
269target from scratch, create a subclass of <tt>TargetMachine</tt>.)
270</p>
271
272<p>
273To get LLVM to actually build and link your target, you need to add it to
274the <tt>TARGETS_TO_BUILD</tt> variable. To do this, you modify the configure
275script to know about your target when parsing the <tt>--enable-targets</tt>
276option. Search the configure script for <tt>TARGETS_TO_BUILD</tt>, add your
277target to the lists there (some creativity required), and then
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]278reconfigure. Alternatively, you can change <tt>autotools/configure.ac</tt> and
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]279regenerate configure by running <tt>./autoconf/AutoRegen.sh</tt>.
280</p>
281
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000[diff] [blame]282</div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]283
284<!-- *********************************************************************** -->
285<div class="doc_section">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]286 <a name="TargetMachine">Target Machine</a>
287</div>
288<!-- *********************************************************************** -->
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]289
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]290<div class="doc_text">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]291
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]292<p>
293<tt>LLVMTargetMachine</tt> is designed as a base class for targets implemented
294with the LLVM target-independent code generator. The <tt>LLVMTargetMachine</tt>
295class should be specialized by a concrete target class that implements the
296various virtual methods. <tt>LLVMTargetMachine</tt> is defined as a subclass of
297<tt>TargetMachine</tt> in <tt>include/llvm/Target/TargetMachine.h</tt>. The
298<tt>TargetMachine</tt> class implementation (<tt>TargetMachine.cpp</tt>) also
299processes numerous command-line options.
300</p>
301
302<p>
303To create a concrete target-specific subclass of <tt>LLVMTargetMachine</tt>,
304start by copying an existing <tt>TargetMachine</tt> class and header. You
305should name the files that you create to reflect your specific target. For
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]306instance, for the SPARC target, name the files <tt>SparcTargetMachine.h</tt> and
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]307<tt>SparcTargetMachine.cpp</tt>.
308</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]309
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]310<p>
311For a target machine <tt>XXX</tt>, the implementation of
312<tt>XXXTargetMachine</tt> must have access methods to obtain objects that
313represent target components. These methods are named <tt>get*Info</tt>, and are
314intended to obtain the instruction set (<tt>getInstrInfo</tt>), register set
315(<tt>getRegisterInfo</tt>), stack frame layout (<tt>getFrameInfo</tt>), and
316similar information. <tt>XXXTargetMachine</tt> must also implement the
317<tt>getTargetData</tt> method to access an object with target-specific data
318characteristics, such as data type size and alignment requirements.
319</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]320
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]321<p>
322For instance, for the SPARC target, the header file
323<tt>SparcTargetMachine.h</tt> declares prototypes for several <tt>get*Info</tt>
324and <tt>getTargetData</tt> methods that simply return a class member.
325</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]326
327<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]328<pre>
329namespace llvm {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]330
331class Module;
332
333class SparcTargetMachine : public LLVMTargetMachine {
334 const TargetData DataLayout; // Calculates type size &amp; alignment
335 SparcSubtarget Subtarget;
336 SparcInstrInfo InstrInfo;
337 TargetFrameInfo FrameInfo;
338
339protected:
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]340 virtual const TargetAsmInfo *createTargetAsmInfo() const;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]341
342public:
343 SparcTargetMachine(const Module &amp;M, const std::string &amp;FS);
344
345 virtual const SparcInstrInfo *getInstrInfo() const {return &amp;InstrInfo; }
346 virtual const TargetFrameInfo *getFrameInfo() const {return &amp;FrameInfo; }
347 virtual const TargetSubtarget *getSubtargetImpl() const{return &amp;Subtarget; }
348 virtual const TargetRegisterInfo *getRegisterInfo() const {
349 return &amp;InstrInfo.getRegisterInfo();
350 }
351 virtual const TargetData *getTargetData() const { return &amp;DataLayout; }
352 static unsigned getModuleMatchQuality(const Module &amp;M);
353
354 // Pass Pipeline Configuration
355 virtual bool addInstSelector(PassManagerBase &amp;PM, bool Fast);
356 virtual bool addPreEmitPass(PassManagerBase &amp;PM, bool Fast);
357 virtual bool addAssemblyEmitter(PassManagerBase &amp;PM, bool Fast,
358 std::ostream &amp;Out);
359};
360
361} // end namespace llvm
362</pre>
363</div>
364
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]365</div>
366
367
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]368<div class="doc_text">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]369
370<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]371<li><tt>getInstrInfo()</tt></li>
372<li><tt>getRegisterInfo()</tt></li>
373<li><tt>getFrameInfo()</tt></li>
374<li><tt>getTargetData()</tt></li>
375<li><tt>getSubtargetImpl()</tt></li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]376</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]377
378<p>For some targets, you also need to support the following methods:</p>
379
380<ul>
381<li><tt>getTargetLowering()</tt></li>
382<li><tt>getJITInfo()</tt></li>
383</ul>
384
385<p>
386In addition, the <tt>XXXTargetMachine</tt> constructor should specify a
387<tt>TargetDescription</tt> string that determines the data layout for the target
388machine, including characteristics such as pointer size, alignment, and
389endianness. For example, the constructor for SparcTargetMachine contains the
390following:
391</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]392
393<div class="doc_code">
394<pre>
395SparcTargetMachine::SparcTargetMachine(const Module &amp;M, const std::string &amp;FS)
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]396 : DataLayout("E-p:32:32-f128:128:128"),
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]397 Subtarget(M, FS), InstrInfo(Subtarget),
398 FrameInfo(TargetFrameInfo::StackGrowsDown, 8, 0) {
399}
400</pre>
401</div>
402
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]403</div>
404
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]405<div class="doc_text">
406
407<p>Hyphens separate portions of the <tt>TargetDescription</tt> string.</p>
408
409<ul>
410<li>An upper-case "<tt>E</tt>" in the string indicates a big-endian target data
411 model. a lower-case "<tt>e</tt>" indicates little-endian.</li>
412
413<li>"<tt>p:</tt>" is followed by pointer information: size, ABI alignment, and
414 preferred alignment. If only two figures follow "<tt>p:</tt>", then the
415 first value is pointer size, and the second value is both ABI and preferred
416 alignment.</li>
417
418<li>Then a letter for numeric type alignment: "<tt>i</tt>", "<tt>f</tt>",
419 "<tt>v</tt>", or "<tt>a</tt>" (corresponding to integer, floating point,
420 vector, or aggregate). "<tt>i</tt>", "<tt>v</tt>", or "<tt>a</tt>" are
421 followed by ABI alignment and preferred alignment. "<tt>f</tt>" is followed
422 by three values: the first indicates the size of a long double, then ABI
423 alignment, and then ABI preferred alignment.</li>
424</ul>
425
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]426</div>
427
428<!-- *********************************************************************** -->
429<div class="doc_section">
430 <a name="TargetRegistration">Target Registration</a>
431</div>
432<!-- *********************************************************************** -->
433
434<div class="doc_text">
435
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]436<p>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]437You must also register your target with the <tt>TargetRegistry</tt>, which is
438what other LLVM tools use to be able to lookup and use your target at
439runtime. The <tt>TargetRegistry</tt> can be used directly, but for most targets
440there are helper templates which should take care of the work for you.</p>
441
442<p>
443All targets should declare a global <tt>Target</tt> object which is used to
444represent the target during registration. Then, in the target's TargetInfo
445library, the target should define that object and use
446the <tt>RegisterTarget</tt> template to register the target. For example, the Sparc registration code looks like this:
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]447</p>
448
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]449<div class="doc_code">
450<pre>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]451Target llvm::TheSparcTarget;
452
453extern "C" void LLVMInitializeSparcTargetInfo() {
Benjamin Kramere15192b2009-08-05 15:42:44 +0000[diff] [blame]454 RegisterTarget&lt;Triple::sparc, /*HasJIT=*/false&gt;
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]455 X(TheSparcTarget, "sparc", "Sparc");
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]456}
457</pre>
458</div>
459
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]460<p>
461This allows the <tt>TargetRegistry</tt> to look up the target by name or by
462target triple. In addition, most targets will also register additional features
463which are available in separate libraries. These registration steps are
464separate, because some clients may wish to only link in some parts of the target
465-- the JIT code generator does not require the use of the assembler printer, for
466example. Here is an example of registering the Sparc assembly printer:
467</p>
468
469<div class="doc_code">
470<pre>
471extern "C" void LLVMInitializeSparcAsmPrinter() {
Benjamin Kramere15192b2009-08-05 15:42:44 +0000[diff] [blame]472 RegisterAsmPrinter&lt;SparcAsmPrinter&gt; X(TheSparcTarget);
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000[diff] [blame]473}
474</pre>
475</div>
476
477<p>
478For more information, see
479"<a href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>".
480</p>
481
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]482</div>
483
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]484<!-- *********************************************************************** -->
485<div class="doc_section">
486 <a name="RegisterSet">Register Set and Register Classes</a>
487</div>
488<!-- *********************************************************************** -->
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]489
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]490<div class="doc_text">
491
492<p>
493You should describe a concrete target-specific class that represents the
494register file of a target machine. This class is called <tt>XXXRegisterInfo</tt>
495(where <tt>XXX</tt> identifies the target) and represents the class register
496file data that is used for register allocation. It also describes the
497interactions between registers.
498</p>
499
500<p>
501You also need to define register classes to categorize related registers. A
502register class should be added for groups of registers that are all treated the
503same way for some instruction. Typical examples are register classes for
504integer, floating-point, or vector registers. A register allocator allows an
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]505instruction to use any register in a specified register class to perform the
506instruction in a similar manner. Register classes allocate virtual registers to
507instructions from these sets, and register classes let the target-independent
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]508register allocator automatically choose the actual registers.
509</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]510
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]511<p>
512Much of the code for registers, including register definition, register aliases,
513and register classes, is generated by TableGen from <tt>XXXRegisterInfo.td</tt>
514input files and placed in <tt>XXXGenRegisterInfo.h.inc</tt> and
515<tt>XXXGenRegisterInfo.inc</tt> output files. Some of the code in the
516implementation of <tt>XXXRegisterInfo</tt> requires hand-coding.
517</p>
518
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]519</div>
520
521<!-- ======================================================================= -->
522<div class="doc_subsection">
523 <a name="RegisterDef">Defining a Register</a>
524</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]525
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]526<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]527
528<p>
529The <tt>XXXRegisterInfo.td</tt> file typically starts with register definitions
530for a target machine. The <tt>Register</tt> class (specified
531in <tt>Target.td</tt>) is used to define an object for each register. The
532specified string <tt>n</tt> becomes the <tt>Name</tt> of the register. The
533basic <tt>Register</tt> object does not have any subregisters and does not
534specify any aliases.
535</p>
536
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]537<div class="doc_code">
538<pre>
539class Register&lt;string n&gt; {
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]540 string Namespace = "";
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]541 string AsmName = n;
542 string Name = n;
543 int SpillSize = 0;
544 int SpillAlignment = 0;
545 list&lt;Register&gt; Aliases = [];
546 list&lt;Register&gt; SubRegs = [];
547 list&lt;int&gt; DwarfNumbers = [];
548}
549</pre>
550</div>
551
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]552<p>
553For example, in the <tt>X86RegisterInfo.td</tt> file, there are register
554definitions that utilize the Register class, such as:
555</p>
556
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]557<div class="doc_code">
558<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]559def AL : Register&lt;"AL"&gt;, DwarfRegNum&lt;[0, 0, 0]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]560</pre>
561</div>
562
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]563<p>
564This defines the register <tt>AL</tt> and assigns it values (with
565<tt>DwarfRegNum</tt>) that are used by <tt>gcc</tt>, <tt>gdb</tt>, or a debug
566information writer (such as <tt>DwarfWriter</tt>
567in <tt>llvm/lib/CodeGen/AsmPrinter</tt>) to identify a register. For register
568<tt>AL</tt>, <tt>DwarfRegNum</tt> takes an array of 3 values representing 3
569different modes: the first element is for X86-64, the second for exception
570handling (EH) on X86-32, and the third is generic. -1 is a special Dwarf number
571that indicates the gcc number is undefined, and -2 indicates the register number
572is invalid for this mode.
573</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]574
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]575<p>
576From the previously described line in the <tt>X86RegisterInfo.td</tt> file,
577TableGen generates this code in the <tt>X86GenRegisterInfo.inc</tt> file:
578</p>
579
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]580<div class="doc_code">
581<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]582static const unsigned GR8[] = { X86::AL, ... };
583
584const unsigned AL_AliasSet[] = { X86::AX, X86::EAX, X86::RAX, 0 };
585
586const TargetRegisterDesc RegisterDescriptors[] = {
587 ...
588{ "AL", "AL", AL_AliasSet, Empty_SubRegsSet, Empty_SubRegsSet, AL_SuperRegsSet }, ...
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]589</pre>
590</div>
591
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]592<p>
593From the register info file, TableGen generates a <tt>TargetRegisterDesc</tt>
594object for each register. <tt>TargetRegisterDesc</tt> is defined in
595<tt>include/llvm/Target/TargetRegisterInfo.h</tt> with the following fields:
596</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]597
598<div class="doc_code">
599<pre>
600struct TargetRegisterDesc {
601 const char *AsmName; // Assembly language name for the register
602 const char *Name; // Printable name for the reg (for debugging)
603 const unsigned *AliasSet; // Register Alias Set
604 const unsigned *SubRegs; // Sub-register set
605 const unsigned *ImmSubRegs; // Immediate sub-register set
606 const unsigned *SuperRegs; // Super-register set
607};</pre>
608</div>
609
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]610<p>
611TableGen uses the entire target description file (<tt>.td</tt>) to determine
612text names for the register (in the <tt>AsmName</tt> and <tt>Name</tt> fields of
613<tt>TargetRegisterDesc</tt>) and the relationships of other registers to the
614defined register (in the other <tt>TargetRegisterDesc</tt> fields). In this
615example, other definitions establish the registers "<tt>AX</tt>",
616"<tt>EAX</tt>", and "<tt>RAX</tt>" as aliases for one another, so TableGen
617generates a null-terminated array (<tt>AL_AliasSet</tt>) for this register alias
618set.
619</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]620
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]621<p>
622The <tt>Register</tt> class is commonly used as a base class for more complex
623classes. In <tt>Target.td</tt>, the <tt>Register</tt> class is the base for the
624<tt>RegisterWithSubRegs</tt> class that is used to define registers that need to
625specify subregisters in the <tt>SubRegs</tt> list, as shown here:
626</p>
627
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]628<div class="doc_code">
629<pre>
630class RegisterWithSubRegs&lt;string n,
631list&lt;Register&gt; subregs&gt; : Register&lt;n&gt; {
632 let SubRegs = subregs;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]633}
634</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]635</div>
636
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]637<p>
638In <tt>SparcRegisterInfo.td</tt>, additional register classes are defined for
639SPARC: a Register subclass, SparcReg, and further subclasses: <tt>Ri</tt>,
640<tt>Rf</tt>, and <tt>Rd</tt>. SPARC registers are identified by 5-bit ID
641numbers, which is a feature common to these subclasses. Note the use of
642'<tt>let</tt>' expressions to override values that are initially defined in a
643superclass (such as <tt>SubRegs</tt> field in the <tt>Rd</tt> class).
644</p>
645
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]646<div class="doc_code">
647<pre>
648class SparcReg&lt;string n&gt; : Register&lt;n&gt; {
649 field bits&lt;5&gt; Num;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]650 let Namespace = "SP";
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]651}
652// Ri - 32-bit integer registers
653class Ri&lt;bits&lt;5&gt; num, string n&gt; :
654SparcReg&lt;n&gt; {
655 let Num = num;
656}
657// Rf - 32-bit floating-point registers
658class Rf&lt;bits&lt;5&gt; num, string n&gt; :
659SparcReg&lt;n&gt; {
660 let Num = num;
661}
662// Rd - Slots in the FP register file for 64-bit
663floating-point values.
664class Rd&lt;bits&lt;5&gt; num, string n,
665list&lt;Register&gt; subregs&gt; : SparcReg&lt;n&gt; {
666 let Num = num;
667 let SubRegs = subregs;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]668}
669</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]670</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]671
672<p>
673In the <tt>SparcRegisterInfo.td</tt> file, there are register definitions that
674utilize these subclasses of <tt>Register</tt>, such as:
675</p>
676
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]677<div class="doc_code">
678<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]679def G0 : Ri&lt; 0, "G0"&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]680DwarfRegNum&lt;[0]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]681def G1 : Ri&lt; 1, "G1"&gt;, DwarfRegNum&lt;[1]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]682...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]683def F0 : Rf&lt; 0, "F0"&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]684DwarfRegNum&lt;[32]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]685def F1 : Rf&lt; 1, "F1"&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]686DwarfRegNum&lt;[33]&gt;;
687...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]688def D0 : Rd&lt; 0, "F0", [F0, F1]&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]689DwarfRegNum&lt;[32]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]690def D1 : Rd&lt; 2, "F2", [F2, F3]&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]691DwarfRegNum&lt;[34]&gt;;
692</pre>
693</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]694
695<p>
696The last two registers shown above (<tt>D0</tt> and <tt>D1</tt>) are
697double-precision floating-point registers that are aliases for pairs of
698single-precision floating-point sub-registers. In addition to aliases, the
699sub-register and super-register relationships of the defined register are in
700fields of a register's TargetRegisterDesc.
701</p>
702
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]703</div>
704
705<!-- ======================================================================= -->
706<div class="doc_subsection">
707 <a name="RegisterClassDef">Defining a Register Class</a>
708</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]709
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]710<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]711
712<p>
713The <tt>RegisterClass</tt> class (specified in <tt>Target.td</tt>) is used to
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]714define an object that represents a group of related registers and also defines
715the default allocation order of the registers. A target description file
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]716<tt>XXXRegisterInfo.td</tt> that uses <tt>Target.td</tt> can construct register
717classes using the following class:
718</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]719
720<div class="doc_code">
721<pre>
722class RegisterClass&lt;string namespace,
723list&lt;ValueType&gt; regTypes, int alignment,
724 list&lt;Register&gt; regList&gt; {
725 string Namespace = namespace;
726 list&lt;ValueType&gt; RegTypes = regTypes;
727 int Size = 0; // spill size, in bits; zero lets tblgen pick the size
728 int Alignment = alignment;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]729
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]730 // CopyCost is the cost of copying a value between two registers
731 // default value 1 means a single instruction
732 // A negative value means copying is extremely expensive or impossible
733 int CopyCost = 1;
734 list&lt;Register&gt; MemberList = regList;
735
736 // for register classes that are subregisters of this class
737 list&lt;RegisterClass&gt; SubRegClassList = [];
738
739 code MethodProtos = [{}]; // to insert arbitrary code
740 code MethodBodies = [{}];
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]741}
742</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]743</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]744
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]745<p>To define a RegisterClass, use the following 4 arguments:</p>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]746
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]747<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]748<li>The first argument of the definition is the name of the namespace.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]749
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]750<li>The second argument is a list of <tt>ValueType</tt> register type values
751 that are defined in <tt>include/llvm/CodeGen/ValueTypes.td</tt>. Defined
752 values include integer types (such as <tt>i16</tt>, <tt>i32</tt>,
753 and <tt>i1</tt> for Boolean), floating-point types
754 (<tt>f32</tt>, <tt>f64</tt>), and vector types (for example, <tt>v8i16</tt>
755 for an <tt>8 x i16</tt> vector). All registers in a <tt>RegisterClass</tt>
756 must have the same <tt>ValueType</tt>, but some registers may store vector
757 data in different configurations. For example a register that can process a
758 128-bit vector may be able to handle 16 8-bit integer elements, 8 16-bit
759 integers, 4 32-bit integers, and so on. </li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]760
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]761<li>The third argument of the <tt>RegisterClass</tt> definition specifies the
762 alignment required of the registers when they are stored or loaded to
763 memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]764
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]765<li>The final argument, <tt>regList</tt>, specifies which registers are in this
766 class. If an <tt>allocation_order_*</tt> method is not specified,
767 then <tt>regList</tt> also defines the order of allocation used by the
768 register allocator.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]769</ul>
770
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]771<p>
772In <tt>SparcRegisterInfo.td</tt>, three RegisterClass objects are defined:
773<tt>FPRegs</tt>, <tt>DFPRegs</tt>, and <tt>IntRegs</tt>. For all three register
774classes, the first argument defines the namespace with the string
775'<tt>SP</tt>'. <tt>FPRegs</tt> defines a group of 32 single-precision
776floating-point registers (<tt>F0</tt> to <tt>F31</tt>); <tt>DFPRegs</tt> defines
777a group of 16 double-precision registers
778(<tt>D0-D15</tt>). For <tt>IntRegs</tt>, the <tt>MethodProtos</tt>
779and <tt>MethodBodies</tt> methods are used by TableGen to insert the specified
780code into generated output.
781</p>
782
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]783<div class="doc_code">
784<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]785def FPRegs : RegisterClass&lt;"SP", [f32], 32,
786 [F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15,
787 F16, F17, F18, F19, F20, F21, F22, F23, F24, F25, F26, F27, F28, F29, F30, F31]&gt;;
788
789def DFPRegs : RegisterClass&lt;"SP", [f64], 64,
790 [D0, D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, D14, D15]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]791&nbsp;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]792def IntRegs : RegisterClass&lt;"SP", [i32], 32,
793 [L0, L1, L2, L3, L4, L5, L6, L7,
794 I0, I1, I2, I3, I4, I5,
795 O0, O1, O2, O3, O4, O5, O7,
796 G1,
797 // Non-allocatable regs:
798 G2, G3, G4,
799 O6, // stack ptr
800 I6, // frame ptr
801 I7, // return address
802 G0, // constant zero
803 G5, G6, G7 // reserved for kernel
804 ]&gt; {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]805 let MethodProtos = [{
806 iterator allocation_order_end(const MachineFunction &amp;MF) const;
807 }];
808 let MethodBodies = [{
809 IntRegsClass::iterator
810 IntRegsClass::allocation_order_end(const MachineFunction &amp;MF) const {
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]811 return end() - 10 // Don't allocate special registers
812 -1;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]813 }
814 }];
815}
816</pre>
817</div>
818
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]819<p>
820Using <tt>SparcRegisterInfo.td</tt> with TableGen generates several output files
821that are intended for inclusion in other source code that you write.
822<tt>SparcRegisterInfo.td</tt> generates <tt>SparcGenRegisterInfo.h.inc</tt>,
823which should be included in the header file for the implementation of the SPARC
824register implementation that you write (<tt>SparcRegisterInfo.h</tt>). In
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]825<tt>SparcGenRegisterInfo.h.inc</tt> a new structure is defined called
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]826<tt>SparcGenRegisterInfo</tt> that uses <tt>TargetRegisterInfo</tt> as its
827base. It also specifies types, based upon the defined register
828classes: <tt>DFPRegsClass</tt>, <tt>FPRegsClass</tt>, and <tt>IntRegsClass</tt>.
829</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]830
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]831<p>
832<tt>SparcRegisterInfo.td</tt> also generates <tt>SparcGenRegisterInfo.inc</tt>,
833which is included at the bottom of <tt>SparcRegisterInfo.cpp</tt>, the SPARC
834register implementation. The code below shows only the generated integer
835registers and associated register classes. The order of registers
836in <tt>IntRegs</tt> reflects the order in the definition of <tt>IntRegs</tt> in
837the target description file. Take special note of the use
838of <tt>MethodBodies</tt> in <tt>SparcRegisterInfo.td</tt> to create code in
839<tt>SparcGenRegisterInfo.inc</tt>. <tt>MethodProtos</tt> generates similar code
840in <tt>SparcGenRegisterInfo.h.inc</tt>.
841</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]842
843<div class="doc_code">
844<pre> // IntRegs Register Class...
845 static const unsigned IntRegs[] = {
846 SP::L0, SP::L1, SP::L2, SP::L3, SP::L4, SP::L5,
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]847 SP::L6, SP::L7, SP::I0, SP::I1, SP::I2, SP::I3,
848 SP::I4, SP::I5, SP::O0, SP::O1, SP::O2, SP::O3,
849 SP::O4, SP::O5, SP::O7, SP::G1, SP::G2, SP::G3,
850 SP::G4, SP::O6, SP::I6, SP::I7, SP::G0, SP::G5,
851 SP::G6, SP::G7,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]852 };
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]853
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]854 // IntRegsVTs Register Class Value Types...
855 static const MVT::ValueType IntRegsVTs[] = {
856 MVT::i32, MVT::Other
857 };
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]858
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]859namespace SP { // Register class instances
860 DFPRegsClass&nbsp;&nbsp;&nbsp; DFPRegsRegClass;
861 FPRegsClass&nbsp;&nbsp;&nbsp;&nbsp; FPRegsRegClass;
862 IntRegsClass&nbsp;&nbsp;&nbsp; IntRegsRegClass;
863...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]864 // IntRegs Sub-register Classess...
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]865 static const TargetRegisterClass* const IntRegsSubRegClasses [] = {
866 NULL
867 };
868...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]869 // IntRegs Super-register Classess...
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]870 static const TargetRegisterClass* const IntRegsSuperRegClasses [] = {
871 NULL
872 };
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]873...
874 // IntRegs Register Class sub-classes...
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]875 static const TargetRegisterClass* const IntRegsSubclasses [] = {
876 NULL
877 };
878...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]879 // IntRegs Register Class super-classes...
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]880 static const TargetRegisterClass* const IntRegsSuperclasses [] = {
881 NULL
882 };
883...
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]884 IntRegsClass::iterator
885 IntRegsClass::allocation_order_end(const MachineFunction &amp;MF) const {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]886 return end()-10 // Don't allocate special registers
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]887 -1;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]888 }
889
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]890 IntRegsClass::IntRegsClass() : TargetRegisterClass(IntRegsRegClassID,
891 IntRegsVTs, IntRegsSubclasses, IntRegsSuperclasses, IntRegsSubRegClasses,
892 IntRegsSuperRegClasses, 4, 4, 1, IntRegs, IntRegs + 32) {}
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]893}
894</pre>
895</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]896
897</div>
898
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]899<!-- ======================================================================= -->
900<div class="doc_subsection">
Chris Lattner7d12b4b2008-11-11 19:36:31 +0000[diff] [blame]901 <a name="implementRegister">Implement a subclass of</a>
902 <a href="http://www.llvm.org/docs/CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]903</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]904
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]905<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]906
907<p>
908The final step is to hand code portions of <tt>XXXRegisterInfo</tt>, which
909implements the interface described in <tt>TargetRegisterInfo.h</tt>. These
910functions return <tt>0</tt>, <tt>NULL</tt>, or <tt>false</tt>, unless
911overridden. Here is a list of functions that are overridden for the SPARC
912implementation in <tt>SparcRegisterInfo.cpp</tt>:
913</p>
914
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]915<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]916<li><tt>getCalleeSavedRegs</tt> &mdash; Returns a list of callee-saved registers
917 in the order of the desired callee-save stack frame offset.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]918
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]919<li><tt>getCalleeSavedRegClasses</tt> &mdash; Returns a list of preferred
920 register classes with which to spill each callee saved register.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]921
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]922<li><tt>getReservedRegs</tt> &mdash; Returns a bitset indexed by physical
923 register numbers, indicating if a particular register is unavailable.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]924
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]925<li><tt>hasFP</tt> &mdash; Return a Boolean indicating if a function should have
926 a dedicated frame pointer register.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]927
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]928<li><tt>eliminateCallFramePseudoInstr</tt> &mdash; If call frame setup or
929 destroy pseudo instructions are used, this can be called to eliminate
930 them.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]931
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]932<li><tt>eliminateFrameIndex</tt> &mdash; Eliminate abstract frame indices from
933 instructions that may use them.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]934
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]935<li><tt>emitPrologue</tt> &mdash; Insert prologue code into the function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]936
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]937<li><tt>emitEpilogue</tt> &mdash; Insert epilogue code into the function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]938</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]939
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]940</div>
941
942<!-- *********************************************************************** -->
943<div class="doc_section">
944 <a name="InstructionSet">Instruction Set</a>
945</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]946
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]947<!-- *********************************************************************** -->
948<div class="doc_text">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]949
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]950<p>
951During the early stages of code generation, the LLVM IR code is converted to a
952<tt>SelectionDAG</tt> with nodes that are instances of the <tt>SDNode</tt> class
953containing target instructions. An <tt>SDNode</tt> has an opcode, operands, type
954requirements, and operation properties. For example, is an operation
955commutative, does an operation load from memory. The various operation node
956types are described in the <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>
957file (values of the <tt>NodeType</tt> enum in the <tt>ISD</tt> namespace).
958</p>
959
960<p>
961TableGen uses the following target description (<tt>.td</tt>) input files to
962generate much of the code for instruction definition:
963</p>
964
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]965<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]966<li><tt>Target.td</tt> &mdash; Where the <tt>Instruction</tt>, <tt>Operand</tt>,
967 <tt>InstrInfo</tt>, and other fundamental classes are defined.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]968
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]969<li><tt>TargetSelectionDAG.td</tt>&mdash; Used by <tt>SelectionDAG</tt>
970 instruction selection generators, contains <tt>SDTC*</tt> classes (selection
971 DAG type constraint), definitions of <tt>SelectionDAG</tt> nodes (such as
972 <tt>imm</tt>, <tt>cond</tt>, <tt>bb</tt>, <tt>add</tt>, <tt>fadd</tt>,
973 <tt>sub</tt>), and pattern support (<tt>Pattern</tt>, <tt>Pat</tt>,
974 <tt>PatFrag</tt>, <tt>PatLeaf</tt>, <tt>ComplexPattern</tt>.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]975
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]976<li><tt>XXXInstrFormats.td</tt> &mdash; Patterns for definitions of
977 target-specific instructions.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]978
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]979<li><tt>XXXInstrInfo.td</tt> &mdash; Target-specific definitions of instruction
980 templates, condition codes, and instructions of an instruction set. For
981 architecture modifications, a different file name may be used. For example,
982 for Pentium with SSE instruction, this file is <tt>X86InstrSSE.td</tt>, and
983 for Pentium with MMX, this file is <tt>X86InstrMMX.td</tt>.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]984</ul>
985
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]986<p>
987There is also a target-specific <tt>XXX.td</tt> file, where <tt>XXX</tt> is the
988name of the target. The <tt>XXX.td</tt> file includes the other <tt>.td</tt>
989input files, but its contents are only directly important for subtargets.
990</p>
991
992<p>
993You should describe a concrete target-specific class <tt>XXXInstrInfo</tt> that
994represents machine instructions supported by a target machine.
995<tt>XXXInstrInfo</tt> contains an array of <tt>XXXInstrDescriptor</tt> objects,
996each of which describes one instruction. An instruction descriptor defines:</p>
997
998<ul>
999<li>Opcode mnemonic</li>
1000
1001<li>Number of operands</li>
1002
1003<li>List of implicit register definitions and uses</li>
1004
1005<li>Target-independent properties (such as memory access, is commutable)</li>
1006
1007<li>Target-specific flags </li>
1008</ul>
1009
1010<p>
1011The Instruction class (defined in <tt>Target.td</tt>) is mostly used as a base
1012for more complex instruction classes.
1013</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1014
1015<div class="doc_code">
1016<pre>class Instruction {
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1017 string Namespace = "";
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1018 dag OutOperandList; // An dag containing the MI def operand list.
1019 dag InOperandList; // An dag containing the MI use operand list.
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1020 string AsmString = ""; // The .s format to print the instruction with.
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1021 list&lt;dag&gt; Pattern; // Set to the DAG pattern for this instruction
1022 list&lt;Register&gt; Uses = [];
1023 list&lt;Register&gt; Defs = [];
1024 list&lt;Predicate&gt; Predicates = []; // predicates turned into isel match code
1025 ... remainder not shown for space ...
1026}
1027</pre>
1028</div>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1029
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1030<p>
1031A <tt>SelectionDAG</tt> node (<tt>SDNode</tt>) should contain an object
1032representing a target-specific instruction that is defined
1033in <tt>XXXInstrInfo.td</tt>. The instruction objects should represent
1034instructions from the architecture manual of the target machine (such as the
1035SPARC Architecture Manual for the SPARC target).
1036</p>
1037
1038<p>
1039A single instruction from the architecture manual is often modeled as multiple
1040target instructions, depending upon its operands. For example, a manual might
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1041describe an add instruction that takes a register or an immediate operand. An
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1042LLVM target could model this with two instructions named <tt>ADDri</tt> and
1043<tt>ADDrr</tt>.
1044</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1045
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1046<p>
1047You should define a class for each instruction category and define each opcode
1048as a subclass of the category with appropriate parameters such as the fixed
1049binary encoding of opcodes and extended opcodes. You should map the register
1050bits to the bits of the instruction in which they are encoded (for the
1051JIT). Also you should specify how the instruction should be printed when the
1052automatic assembly printer is used.
1053</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1054
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1055<p>
1056As is described in the SPARC Architecture Manual, Version 8, there are three
1057major 32-bit formats for instructions. Format 1 is only for the <tt>CALL</tt>
1058instruction. Format 2 is for branch on condition codes and <tt>SETHI</tt> (set
1059high bits of a register) instructions. Format 3 is for other instructions.
1060</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1061
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1062<p>
1063Each of these formats has corresponding classes in <tt>SparcInstrFormat.td</tt>.
1064<tt>InstSP</tt> is a base class for other instruction classes. Additional base
1065classes are specified for more precise formats: for example
1066in <tt>SparcInstrFormat.td</tt>, <tt>F2_1</tt> is for <tt>SETHI</tt>,
1067and <tt>F2_2</tt> is for branches. There are three other base
1068classes: <tt>F3_1</tt> for register/register operations, <tt>F3_2</tt> for
1069register/immediate operations, and <tt>F3_3</tt> for floating-point
1070operations. <tt>SparcInstrInfo.td</tt> also adds the base class Pseudo for
1071synthetic SPARC instructions.
1072</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1073
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1074<p>
1075<tt>SparcInstrInfo.td</tt> largely consists of operand and instruction
1076definitions for the SPARC target. In <tt>SparcInstrInfo.td</tt>, the following
1077target description file entry, <tt>LDrr</tt>, defines the Load Integer
1078instruction for a Word (the <tt>LD</tt> SPARC opcode) from a memory address to a
1079register. The first parameter, the value 3 (<tt>11<sub>2</sub></tt>), is the
1080operation value for this category of operation. The second parameter
1081(<tt>000000<sub>2</sub></tt>) is the specific operation value
1082for <tt>LD</tt>/Load Word. The third parameter is the output destination, which
1083is a register operand and defined in the <tt>Register</tt> target description
1084file (<tt>IntRegs</tt>).
1085</p>
1086
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1087<div class="doc_code">
1088<pre>def LDrr : F3_1 &lt;3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1089 "ld [$addr], $dst",
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1090 [(set IntRegs:$dst, (load ADDRrr:$addr))]&gt;;
1091</pre>
1092</div>
1093
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1094<p>
1095The fourth parameter is the input source, which uses the address
1096operand <tt>MEMrr</tt> that is defined earlier in <tt>SparcInstrInfo.td</tt>:
1097</p>
1098
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1099<div class="doc_code">
1100<pre>def MEMrr : Operand&lt;i32&gt; {
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1101 let PrintMethod = "printMemOperand";
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1102 let MIOperandInfo = (ops IntRegs, IntRegs);
1103}
1104</pre>
1105</div>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1106
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1107<p>
1108The fifth parameter is a string that is used by the assembly printer and can be
1109left as an empty string until the assembly printer interface is implemented. The
1110sixth and final parameter is the pattern used to match the instruction during
1111the SelectionDAG Select Phase described in
1112(<a href="http://www.llvm.org/docs/CodeGenerator.html">The LLVM
1113Target-Independent Code Generator</a>). This parameter is detailed in the next
1114section, <a href="#InstructionSelector">Instruction Selector</a>.
1115</p>
1116
1117<p>
1118Instruction class definitions are not overloaded for different operand types, so
1119separate versions of instructions are needed for register, memory, or immediate
1120value operands. For example, to perform a Load Integer instruction for a Word
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1121from an immediate operand to a register, the following instruction class is
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1122defined:
1123</p>
1124
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1125<div class="doc_code">
1126<pre>def LDri : F3_2 &lt;3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1127 "ld [$addr], $dst",
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1128 [(set IntRegs:$dst, (load ADDRri:$addr))]&gt;;
1129</pre>
1130</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1131
1132<p>
1133Writing these definitions for so many similar instructions can involve a lot of
1134cut and paste. In td files, the <tt>multiclass</tt> directive enables the
1135creation of templates to define several instruction classes at once (using
1136the <tt>defm</tt> directive). For example in <tt>SparcInstrInfo.td</tt>, the
1137<tt>multiclass</tt> pattern <tt>F3_12</tt> is defined to create 2 instruction
1138classes each time <tt>F3_12</tt> is invoked:
1139</p>
1140
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1141<div class="doc_code">
1142<pre>multiclass F3_12 &lt;string OpcStr, bits&lt;6&gt; Op3Val, SDNode OpNode&gt; {
1143 def rr : F3_1 &lt;2, Op3Val,
1144 (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1145 !strconcat(OpcStr, " $b, $c, $dst"),
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1146 [(set IntRegs:$dst, (OpNode IntRegs:$b, IntRegs:$c))]&gt;;
1147 def ri : F3_2 &lt;2, Op3Val,
1148 (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c),
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1149 !strconcat(OpcStr, " $b, $c, $dst"),
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1150 [(set IntRegs:$dst, (OpNode IntRegs:$b, simm13:$c))]&gt;;
1151}
1152</pre>
1153</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1154
1155<p>
1156So when the <tt>defm</tt> directive is used for the <tt>XOR</tt>
1157and <tt>ADD</tt> instructions, as seen below, it creates four instruction
1158objects: <tt>XORrr</tt>, <tt>XORri</tt>, <tt>ADDrr</tt>, and <tt>ADDri</tt>.
1159</p>
1160
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1161<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1162<pre>
1163defm XOR : F3_12&lt;"xor", 0b000011, xor&gt;;
1164defm ADD : F3_12&lt;"add", 0b000000, add&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1165</pre>
1166</div>
1167
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1168<p>
1169<tt>SparcInstrInfo.td</tt> also includes definitions for condition codes that
1170are referenced by branch instructions. The following definitions
1171in <tt>SparcInstrInfo.td</tt> indicate the bit location of the SPARC condition
1172code. For example, the 10<sup>th</sup> bit represents the 'greater than'
1173condition for integers, and the 22<sup>nd</sup> bit represents the 'greater
1174than' condition for floats.
1175</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1176
1177<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1178<pre>
1179def ICC_NE : ICC_VAL&lt; 9&gt;; // Not Equal
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1180def ICC_E : ICC_VAL&lt; 1&gt;; // Equal
1181def ICC_G : ICC_VAL&lt;10&gt;; // Greater
1182...
1183def FCC_U : FCC_VAL&lt;23&gt;; // Unordered
1184def FCC_G : FCC_VAL&lt;22&gt;; // Greater
1185def FCC_UG : FCC_VAL&lt;21&gt;; // Unordered or Greater
1186...
1187</pre>
1188</div>
1189
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1190<p>
1191(Note that <tt>Sparc.h</tt> also defines enums that correspond to the same SPARC
1192condition codes. Care must be taken to ensure the values in <tt>Sparc.h</tt>
1193correspond to the values in <tt>SparcInstrInfo.td</tt>. I.e.,
1194<tt>SPCC::ICC_NE = 9</tt>, <tt>SPCC::FCC_U = 23</tt> and so on.)
1195</p>
1196
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1197</div>
1198
1199<!-- ======================================================================= -->
1200<div class="doc_subsection">
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1201 <a name="operandMapping">Instruction Operand Mapping</a>
1202</div>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1203
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1204<div class="doc_text">
1205
1206<p>
1207The code generator backend maps instruction operands to fields in the
1208instruction. Operands are assigned to unbound fields in the instruction in the
1209order they are defined. Fields are bound when they are assigned a value. For
1210example, the Sparc target defines the <tt>XNORrr</tt> instruction as
1211a <tt>F3_1</tt> format instruction having three operands.
1212</p>
1213
1214<div class="doc_code">
1215<pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1216def XNORrr : F3_1&lt;2, 0b000111,
1217 (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
1218 "xnor $b, $c, $dst",
1219 [(set IntRegs:$dst, (not (xor IntRegs:$b, IntRegs:$c)))]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1220</pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1221</div>
1222
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1223<p>
1224The instruction templates in <tt>SparcInstrFormats.td</tt> show the base class
1225for <tt>F3_1</tt> is <tt>InstSP</tt>.
1226</p>
1227
1228<div class="doc_code">
1229<pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1230class InstSP&lt;dag outs, dag ins, string asmstr, list&lt;dag&gt; pattern&gt; : Instruction {
1231 field bits&lt;32&gt; Inst;
1232 let Namespace = "SP";
1233 bits&lt;2&gt; op;
1234 let Inst{31-30} = op;
1235 dag OutOperandList = outs;
1236 dag InOperandList = ins;
1237 let AsmString = asmstr;
1238 let Pattern = pattern;
1239}
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1240</pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1241</div>
1242
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1243<p><tt>InstSP</tt> leaves the <tt>op</tt> field unbound.</p>
1244
1245<div class="doc_code">
1246<pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1247class F3&lt;dag outs, dag ins, string asmstr, list&lt;dag&gt; pattern&gt;
1248 : InstSP&lt;outs, ins, asmstr, pattern&gt; {
1249 bits&lt;5&gt; rd;
1250 bits&lt;6&gt; op3;
1251 bits&lt;5&gt; rs1;
1252 let op{1} = 1; // Op = 2 or 3
1253 let Inst{29-25} = rd;
1254 let Inst{24-19} = op3;
1255 let Inst{18-14} = rs1;
1256}
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1257</pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1258</div>
1259
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1260<p>
1261<tt>F3</tt> binds the <tt>op</tt> field and defines the <tt>rd</tt>,
1262<tt>op3</tt>, and <tt>rs1</tt> fields. <tt>F3</tt> format instructions will
1263bind the operands <tt>rd</tt>, <tt>op3</tt>, and <tt>rs1</tt> fields.
1264</p>
1265
1266<div class="doc_code">
1267<pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1268class F3_1&lt;bits&lt;2&gt; opVal, bits&lt;6&gt; op3val, dag outs, dag ins,
1269 string asmstr, list&lt;dag&gt; pattern&gt; : F3&lt;outs, ins, asmstr, pattern&gt; {
1270 bits&lt;8&gt; asi = 0; // asi not currently used
1271 bits&lt;5&gt; rs2;
1272 let op = opVal;
1273 let op3 = op3val;
1274 let Inst{13} = 0; // i field = 0
1275 let Inst{12-5} = asi; // address space identifier
1276 let Inst{4-0} = rs2;
1277}
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1278</pre>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1279</div>
1280
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1281<p>
1282<tt>F3_1</tt> binds the <tt>op3</tt> field and defines the <tt>rs2</tt>
1283fields. <tt>F3_1</tt> format instructions will bind the operands to the <tt>rd</tt>,
1284<tt>rs1</tt>, and <tt>rs2</tt> fields. This results in the <tt>XNORrr</tt>
1285instruction binding <tt>$dst</tt>, <tt>$b</tt>, and <tt>$c</tt> operands to
1286the <tt>rd</tt>, <tt>rs1</tt>, and <tt>rs2</tt> fields respectively.
1287</p>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1288
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1289</div>
Chris Lattner7a152732008-11-22 19:10:48 +0000[diff] [blame]1290
1291<!-- ======================================================================= -->
1292<div class="doc_subsection">
Chris Lattner7d12b4b2008-11-11 19:36:31 +0000[diff] [blame]1293 <a name="implementInstr">Implement a subclass of </a>
1294 <a href="http://www.llvm.org/docs/CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1295</div>
1296
1297<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1298
1299<p>
1300The final step is to hand code portions of <tt>XXXInstrInfo</tt>, which
1301implements the interface described in <tt>TargetInstrInfo.h</tt>. These
1302functions return <tt>0</tt> or a Boolean or they assert, unless
1303overridden. Here's a list of functions that are overridden for the SPARC
1304implementation in <tt>SparcInstrInfo.cpp</tt>:
1305</p>
1306
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1307<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1308<li><tt>isMoveInstr</tt> &mdash; Return true if the instruction is a register to
1309 register move; false, otherwise.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1310
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1311<li><tt>isLoadFromStackSlot</tt> &mdash; If the specified machine instruction is
1312 a direct load from a stack slot, return the register number of the
1313 destination and the <tt>FrameIndex</tt> of the stack slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1314
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1315<li><tt>isStoreToStackSlot</tt> &mdash; If the specified machine instruction is
1316 a direct store to a stack slot, return the register number of the
1317 destination and the <tt>FrameIndex</tt> of the stack slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1318
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1319<li><tt>copyRegToReg</tt> &mdash; Copy values between a pair of registers.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1320
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1321<li><tt>storeRegToStackSlot</tt> &mdash; Store a register value to a stack
1322 slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1323
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1324<li><tt>loadRegFromStackSlot</tt> &mdash; Load a register value from a stack
1325 slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1326
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1327<li><tt>storeRegToAddr</tt> &mdash; Store a register value to memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1328
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1329<li><tt>loadRegFromAddr</tt> &mdash; Load a register value from memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1330
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1331<li><tt>foldMemoryOperand</tt> &mdash; Attempt to combine instructions of any
1332 load or store instruction for the specified operand(s).</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1333</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1334
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1335</div>
1336
1337<!-- ======================================================================= -->
1338<div class="doc_subsection">
1339 <a name="branchFolding">Branch Folding and If Conversion</a>
1340</div>
1341<div class="doc_text">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1342
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1343<p>
1344Performance can be improved by combining instructions or by eliminating
1345instructions that are never reached. The <tt>AnalyzeBranch</tt> method
1346in <tt>XXXInstrInfo</tt> may be implemented to examine conditional instructions
1347and remove unnecessary instructions. <tt>AnalyzeBranch</tt> looks at the end of
1348a machine basic block (MBB) for opportunities for improvement, such as branch
1349folding and if conversion. The <tt>BranchFolder</tt> and <tt>IfConverter</tt>
1350machine function passes (see the source files <tt>BranchFolding.cpp</tt> and
1351<tt>IfConversion.cpp</tt> in the <tt>lib/CodeGen</tt> directory) call
1352<tt>AnalyzeBranch</tt> to improve the control flow graph that represents the
1353instructions.
1354</p>
1355
1356<p>
1357Several implementations of <tt>AnalyzeBranch</tt> (for ARM, Alpha, and X86) can
1358be examined as models for your own <tt>AnalyzeBranch</tt> implementation. Since
1359SPARC does not implement a useful <tt>AnalyzeBranch</tt>, the ARM target
1360implementation is shown below.
1361</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1362
1363<p><tt>AnalyzeBranch</tt> returns a Boolean value and takes four parameters:</p>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1364
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1365<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1366<li><tt>MachineBasicBlock &amp;MBB</tt> &mdash; The incoming block to be
1367 examined.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1368
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1369<li><tt>MachineBasicBlock *&amp;TBB</tt> &mdash; A destination block that is
1370 returned. For a conditional branch that evaluates to true, <tt>TBB</tt> is
1371 the destination.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1372
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1373<li><tt>MachineBasicBlock *&amp;FBB</tt> &mdash; For a conditional branch that
1374 evaluates to false, <tt>FBB</tt> is returned as the destination.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1375
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1376<li><tt>std::vector&lt;MachineOperand&gt; &amp;Cond</tt> &mdash; List of
1377 operands to evaluate a condition for a conditional branch.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1378</ul>
1379
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1380<p>
1381In the simplest case, if a block ends without a branch, then it falls through to
1382the successor block. No destination blocks are specified for either <tt>TBB</tt>
1383or <tt>FBB</tt>, so both parameters return <tt>NULL</tt>. The start of
1384the <tt>AnalyzeBranch</tt> (see code below for the ARM target) shows the
1385function parameters and the code for the simplest case.
1386</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1387
1388<div class="doc_code">
1389<pre>bool ARMInstrInfo::AnalyzeBranch(MachineBasicBlock &amp;MBB,
1390 MachineBasicBlock *&amp;TBB, MachineBasicBlock *&amp;FBB,
1391 std::vector&lt;MachineOperand&gt; &amp;Cond) const
1392{
1393 MachineBasicBlock::iterator I = MBB.end();
1394 if (I == MBB.begin() || !isUnpredicatedTerminator(--I))
1395 return false;
1396</pre>
1397</div>
1398
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1399<p>
1400If a block ends with a single unconditional branch instruction, then
1401<tt>AnalyzeBranch</tt> (shown below) should return the destination of that
1402branch in the <tt>TBB</tt> parameter.
1403</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1404
1405<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1406<pre>
1407 if (LastOpc == ARM::B || LastOpc == ARM::tB) {
1408 TBB = LastInst-&gt;getOperand(0).getMBB();
1409 return false;
1410 }
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1411</pre>
1412</div>
1413
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1414<p>
1415If a block ends with two unconditional branches, then the second branch is never
1416reached. In that situation, as shown below, remove the last branch instruction
1417and return the penultimate branch in the <tt>TBB</tt> parameter.
1418</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1419
1420<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1421<pre>
1422 if ((SecondLastOpc == ARM::B || SecondLastOpc==ARM::tB) &amp;&amp;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1423 (LastOpc == ARM::B || LastOpc == ARM::tB)) {
1424 TBB = SecondLastInst-&gt;getOperand(0).getMBB();
1425 I = LastInst;
1426 I-&gt;eraseFromParent();
1427 return false;
1428 }
1429</pre>
1430</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1431
1432<p>
1433A block may end with a single conditional branch instruction that falls through
1434to successor block if the condition evaluates to false. In that case,
1435<tt>AnalyzeBranch</tt> (shown below) should return the destination of that
1436conditional branch in the <tt>TBB</tt> parameter and a list of operands in
1437the <tt>Cond</tt> parameter to evaluate the condition.
1438</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1439
1440<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1441<pre>
1442 if (LastOpc == ARM::Bcc || LastOpc == ARM::tBcc) {
1443 // Block ends with fall-through condbranch.
1444 TBB = LastInst-&gt;getOperand(0).getMBB();
1445 Cond.push_back(LastInst-&gt;getOperand(1));
1446 Cond.push_back(LastInst-&gt;getOperand(2));
1447 return false;
1448 }
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1449</pre>
1450</div>
1451
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1452<p>
1453If a block ends with both a conditional branch and an ensuing unconditional
1454branch, then <tt>AnalyzeBranch</tt> (shown below) should return the conditional
1455branch destination (assuming it corresponds to a conditional evaluation of
1456'<tt>true</tt>') in the <tt>TBB</tt> parameter and the unconditional branch
1457destination in the <tt>FBB</tt> (corresponding to a conditional evaluation of
1458'<tt>false</tt>'). A list of operands to evaluate the condition should be
1459returned in the <tt>Cond</tt> parameter.
1460</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1461
1462<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1463<pre>
1464 unsigned SecondLastOpc = SecondLastInst-&gt;getOpcode();
1465
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1466 if ((SecondLastOpc == ARM::Bcc &amp;&amp; LastOpc == ARM::B) ||
1467 (SecondLastOpc == ARM::tBcc &amp;&amp; LastOpc == ARM::tB)) {
1468 TBB = SecondLastInst-&gt;getOperand(0).getMBB();
1469 Cond.push_back(SecondLastInst-&gt;getOperand(1));
1470 Cond.push_back(SecondLastInst-&gt;getOperand(2));
1471 FBB = LastInst-&gt;getOperand(0).getMBB();
1472 return false;
1473 }
1474</pre>
1475</div>
1476
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1477<p>
1478For the last two cases (ending with a single conditional branch or ending with
1479one conditional and one unconditional branch), the operands returned in
1480the <tt>Cond</tt> parameter can be passed to methods of other instructions to
1481create new branches or perform other operations. An implementation
1482of <tt>AnalyzeBranch</tt> requires the helper methods <tt>RemoveBranch</tt>
1483and <tt>InsertBranch</tt> to manage subsequent operations.
1484</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1485
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1486<p>
1487<tt>AnalyzeBranch</tt> should return false indicating success in most circumstances.
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1488<tt>AnalyzeBranch</tt> should only return true when the method is stumped about what to
1489do, for example, if a block has three terminating branches. <tt>AnalyzeBranch</tt> may
1490return true if it encounters a terminator it cannot handle, such as an indirect
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1491branch.
1492</p>
1493
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1494</div>
1495
1496<!-- *********************************************************************** -->
1497<div class="doc_section">
1498 <a name="InstructionSelector">Instruction Selector</a>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]1499</div>
1500<!-- *********************************************************************** -->
1501
1502<div class="doc_text">
1503
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1504<p>
1505LLVM uses a <tt>SelectionDAG</tt> to represent LLVM IR instructions, and nodes
1506of the <tt>SelectionDAG</tt> ideally represent native target
1507instructions. During code generation, instruction selection passes are performed
1508to convert non-native DAG instructions into native target-specific
1509instructions. The pass described in <tt>XXXISelDAGToDAG.cpp</tt> is used to
1510match patterns and perform DAG-to-DAG instruction selection. Optionally, a pass
1511may be defined (in <tt>XXXBranchSelector.cpp</tt>) to perform similar DAG-to-DAG
1512operations for branch instructions. Later, the code in
1513<tt>XXXISelLowering.cpp</tt> replaces or removes operations and data types not
1514supported natively (legalizes) in a <tt>SelectionDAG</tt>.
1515</p>
1516
1517<p>
1518TableGen generates code for instruction selection using the following target
1519description input files:
1520</p>
1521
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]1522<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1523<li><tt>XXXInstrInfo.td</tt> &mdash; Contains definitions of instructions in a
1524 target-specific instruction set, generates <tt>XXXGenDAGISel.inc</tt>, which
1525 is included in <tt>XXXISelDAGToDAG.cpp</tt>.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1526
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1527<li><tt>XXXCallingConv.td</tt> &mdash; Contains the calling and return value
1528 conventions for the target architecture, and it generates
1529 <tt>XXXGenCallingConv.inc</tt>, which is included in
1530 <tt>XXXISelLowering.cpp</tt>.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]1531</ul>
1532
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1533<p>
1534The implementation of an instruction selection pass must include a header that
1535declares the <tt>FunctionPass</tt> class or a subclass of <tt>FunctionPass</tt>. In
1536<tt>XXXTargetMachine.cpp</tt>, a Pass Manager (PM) should add each instruction
1537selection pass into the queue of passes to run.
1538</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1539
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1540<p>
1541The LLVM static compiler (<tt>llc</tt>) is an excellent tool for visualizing the
1542contents of DAGs. To display the <tt>SelectionDAG</tt> before or after specific
1543processing phases, use the command line options for <tt>llc</tt>, described
1544at <a href="http://llvm.org/docs/CodeGenerator.html#selectiondag_process">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1545SelectionDAG Instruction Selection Process</a>.
1546</p>
1547
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1548<p>
1549To describe instruction selector behavior, you should add patterns for lowering
1550LLVM code into a <tt>SelectionDAG</tt> as the last parameter of the instruction
1551definitions in <tt>XXXInstrInfo.td</tt>. For example, in
1552<tt>SparcInstrInfo.td</tt>, this entry defines a register store operation, and
1553the last parameter describes a pattern with the store DAG operator.
1554</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1555
1556<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1557<pre>
1558def STrr : F3_1&lt; 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
1559 "st $src, [$addr]", [(store IntRegs:$src, ADDRrr:$addr)]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1560</pre>
1561</div>
1562
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1563<p>
1564<tt>ADDRrr</tt> is a memory mode that is also defined in
1565<tt>SparcInstrInfo.td</tt>:
1566</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1567
1568<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1569<pre>
1570def ADDRrr : ComplexPattern&lt;i32, 2, "SelectADDRrr", [], []&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1571</pre>
1572</div>
1573
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1574<p>
1575The definition of <tt>ADDRrr</tt> refers to <tt>SelectADDRrr</tt>, which is a
1576function defined in an implementation of the Instructor Selector (such
1577as <tt>SparcISelDAGToDAG.cpp</tt>).
1578</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1579
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1580<p>
1581In <tt>lib/Target/TargetSelectionDAG.td</tt>, the DAG operator for store is
1582defined below:
1583</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1584
1585<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1586<pre>
1587def store : PatFrag&lt;(ops node:$val, node:$ptr),
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1588 (st node:$val, node:$ptr), [{
1589 if (StoreSDNode *ST = dyn_cast&lt;StoreSDNode&gt;(N))
1590 return !ST-&gt;isTruncatingStore() &amp;&amp;
1591 ST-&gt;getAddressingMode() == ISD::UNINDEXED;
1592 return false;
1593}]&gt;;
1594</pre>
1595</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1596
1597<p>
1598<tt>XXXInstrInfo.td</tt> also generates (in <tt>XXXGenDAGISel.inc</tt>) the
1599<tt>SelectCode</tt> method that is used to call the appropriate processing
1600method for an instruction. In this example, <tt>SelectCode</tt>
1601calls <tt>Select_ISD_STORE</tt> for the <tt>ISD::STORE</tt> opcode.
1602</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1603
1604<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1605<pre>
1606SDNode *SelectCode(SDValue N) {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1607 ...
Dan Gohman50ef90d2009-01-28 21:36:46 +0000[diff] [blame]1608 MVT::ValueType NVT = N.getNode()-&gt;getValueType(0);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1609 switch (N.getOpcode()) {
1610 case ISD::STORE: {
1611 switch (NVT) {
1612 default:
1613 return Select_ISD_STORE(N);
1614 break;
1615 }
1616 break;
1617 }
1618 ...
1619</pre>
1620</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1621
1622<p>
1623The pattern for <tt>STrr</tt> is matched, so elsewhere in
1624<tt>XXXGenDAGISel.inc</tt>, code for <tt>STrr</tt> is created for
1625<tt>Select_ISD_STORE</tt>. The <tt>Emit_22</tt> method is also generated
1626in <tt>XXXGenDAGISel.inc</tt> to complete the processing of this
1627instruction.
1628</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1629
1630<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1631<pre>
1632SDNode *Select_ISD_STORE(const SDValue &amp;N) {
Dan Gohman50ef90d2009-01-28 21:36:46 +0000[diff] [blame]1633 SDValue Chain = N.getOperand(0);
1634 if (Predicate_store(N.getNode())) {
1635 SDValue N1 = N.getOperand(1);
1636 SDValue N2 = N.getOperand(2);
1637 SDValue CPTmp0;
1638 SDValue CPTmp1;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1639
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1640 // Pattern: (st:void IntRegs:i32:$src,
1641 // ADDRrr:i32:$addr)&lt;&lt;P:Predicate_store&gt;&gt;
1642 // Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src)
1643 // Pattern complexity = 13 cost = 1 size = 0
1644 if (SelectADDRrr(N, N2, CPTmp0, CPTmp1) &amp;&amp;
Dan Gohman50ef90d2009-01-28 21:36:46 +0000[diff] [blame]1645 N1.getNode()-&gt;getValueType(0) == MVT::i32 &amp;&amp;
1646 N2.getNode()-&gt;getValueType(0) == MVT::i32) {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1647 return Emit_22(N, SP::STrr, CPTmp0, CPTmp1);
1648 }
1649...
1650</pre>
1651</div>
1652
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1653</div>
1654
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1655<!-- ======================================================================= -->
1656<div class="doc_subsection">
1657 <a name="LegalizePhase">The SelectionDAG Legalize Phase</a>
1658</div>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1659
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1660<div class="doc_text">
1661
1662<p>
1663The Legalize phase converts a DAG to use types and operations that are natively
1664supported by the target. For natively unsupported types and operations, you need
1665to add code to the target-specific XXXTargetLowering implementation to convert
1666unsupported types and operations to supported ones.
1667</p>
1668
1669<p>
1670In the constructor for the <tt>XXXTargetLowering</tt> class, first use the
1671<tt>addRegisterClass</tt> method to specify which types are supports and which
1672register classes are associated with them. The code for the register classes are
1673generated by TableGen from <tt>XXXRegisterInfo.td</tt> and placed
1674in <tt>XXXGenRegisterInfo.h.inc</tt>. For example, the implementation of the
1675constructor for the SparcTargetLowering class (in
1676<tt>SparcISelLowering.cpp</tt>) starts with the following code:
1677</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1678
1679<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1680<pre>
1681addRegisterClass(MVT::i32, SP::IntRegsRegisterClass);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1682addRegisterClass(MVT::f32, SP::FPRegsRegisterClass);
1683addRegisterClass(MVT::f64, SP::DFPRegsRegisterClass);
1684</pre>
1685</div>
1686
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1687<p>
1688You should examine the node types in the <tt>ISD</tt> namespace
1689(<tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>) and determine which
1690operations the target natively supports. For operations that do <b>not</b> have
1691native support, add a callback to the constructor for the XXXTargetLowering
1692class, so the instruction selection process knows what to do. The TargetLowering
1693class callback methods (declared in <tt>llvm/Target/TargetLowering.h</tt>) are:
1694</p>
1695
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1696<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1697<li><tt>setOperationAction</tt> &mdash; General operation.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1698
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1699<li><tt>setLoadExtAction</tt> &mdash; Load with extension.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1700
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1701<li><tt>setTruncStoreAction</tt> &mdash; Truncating store.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1702
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1703<li><tt>setIndexedLoadAction</tt> &mdash; Indexed load.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1704
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1705<li><tt>setIndexedStoreAction</tt> &mdash; Indexed store.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1706
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1707<li><tt>setConvertAction</tt> &mdash; Type conversion.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1708
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1709<li><tt>setCondCodeAction</tt> &mdash; Support for a given condition code.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1710</ul>
1711
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1712<p>
1713Note: on older releases, <tt>setLoadXAction</tt> is used instead
1714of <tt>setLoadExtAction</tt>. Also, on older releases,
1715<tt>setCondCodeAction</tt> may not be supported. Examine your release
1716to see what methods are specifically supported.
1717</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1718
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1719<p>
1720These callbacks are used to determine that an operation does or does not work
1721with a specified type (or types). And in all cases, the third parameter is
1722a <tt>LegalAction</tt> type enum value: <tt>Promote</tt>, <tt>Expand</tt>,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1723<tt>Custom</tt>, or <tt>Legal</tt>. <tt>SparcISelLowering.cpp</tt>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1724contains examples of all four <tt>LegalAction</tt> values.
1725</p>
1726
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1727</div>
1728
1729<!-- _______________________________________________________________________ -->
1730<div class="doc_subsubsection">
1731 <a name="promote">Promote</a>
1732</div>
1733
1734<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1735
1736<p>
1737For an operation without native support for a given type, the specified type may
1738be promoted to a larger type that is supported. For example, SPARC does not
1739support a sign-extending load for Boolean values (<tt>i1</tt> type), so
1740in <tt>SparcISelLowering.cpp</tt> the third parameter below, <tt>Promote</tt>,
1741changes <tt>i1</tt> type values to a large type before loading.
1742</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1743
1744<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1745<pre>
1746setLoadExtAction(ISD::SEXTLOAD, MVT::i1, Promote);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1747</pre>
1748</div>
1749
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1750</div>
1751
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1752<!-- _______________________________________________________________________ -->
1753<div class="doc_subsubsection">
1754 <a name="expand">Expand</a>
1755</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1756
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1757<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1758
1759<p>
1760For a type without native support, a value may need to be broken down further,
1761rather than promoted. For an operation without native support, a combination of
1762other operations may be used to similar effect. In SPARC, the floating-point
1763sine and cosine trig operations are supported by expansion to other operations,
1764as indicated by the third parameter, <tt>Expand</tt>, to
1765<tt>setOperationAction</tt>:
1766</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1767
1768<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1769<pre>
1770setOperationAction(ISD::FSIN, MVT::f32, Expand);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1771setOperationAction(ISD::FCOS, MVT::f32, Expand);
1772</pre>
1773</div>
1774
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1775</div>
1776
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1777<!-- _______________________________________________________________________ -->
1778<div class="doc_subsubsection">
1779 <a name="custom">Custom</a>
1780</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1781
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1782<div class="doc_text">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1783
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1784<p>
1785For some operations, simple type promotion or operation expansion may be
1786insufficient. In some cases, a special intrinsic function must be implemented.
1787</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1788
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1789<p>
1790For example, a constant value may require special treatment, or an operation may
1791require spilling and restoring registers in the stack and working with register
1792allocators.
1793</p>
1794
1795<p>
1796As seen in <tt>SparcISelLowering.cpp</tt> code below, to perform a type
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1797conversion from a floating point value to a signed integer, first the
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1798<tt>setOperationAction</tt> should be called with <tt>Custom</tt> as the third
1799parameter:
1800</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1801
1802<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1803<pre>
1804setOperationAction(ISD::FP_TO_SINT, MVT::i32, Custom);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1805</pre>
1806</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1807
1808<p>
1809In the <tt>LowerOperation</tt> method, for each <tt>Custom</tt> operation, a
1810case statement should be added to indicate what function to call. In the
1811following code, an <tt>FP_TO_SINT</tt> opcode will call
1812the <tt>LowerFP_TO_SINT</tt> method:
1813</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1814
1815<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1816<pre>
1817SDValue SparcTargetLowering::LowerOperation(SDValue Op, SelectionDAG &amp;DAG) {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1818 switch (Op.getOpcode()) {
1819 case ISD::FP_TO_SINT: return LowerFP_TO_SINT(Op, DAG);
1820 ...
1821 }
1822}
1823</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1824</div>
1825
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1826<p>
1827Finally, the <tt>LowerFP_TO_SINT</tt> method is implemented, using an FP
1828register to convert the floating-point value to an integer.
1829</p>
1830
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1831<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1832<pre>
1833static SDValue LowerFP_TO_SINT(SDValue Op, SelectionDAG &amp;DAG) {
1834 assert(Op.getValueType() == MVT::i32);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1835 Op = DAG.getNode(SPISD::FTOI, MVT::f32, Op.getOperand(0));
1836 return DAG.getNode(ISD::BIT_CONVERT, MVT::i32, Op);
1837}
1838</pre>
1839</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1840
1841</div>
1842
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1843<!-- _______________________________________________________________________ -->
1844<div class="doc_subsubsection">
1845 <a name="legal">Legal</a>
1846</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1847
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1848<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1849
1850<p>
1851The <tt>Legal</tt> LegalizeAction enum value simply indicates that an
1852operation <b>is</b> natively supported. <tt>Legal</tt> represents the default
1853condition, so it is rarely used. In <tt>SparcISelLowering.cpp</tt>, the action
1854for <tt>CTPOP</tt> (an operation to count the bits set in an integer) is
1855natively supported only for SPARC v9. The following code enables
1856the <tt>Expand</tt> conversion technique for non-v9 SPARC implementations.
1857</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1858
1859<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1860<pre>
1861setOperationAction(ISD::CTPOP, MVT::i32, Expand);
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1862...
1863if (TM.getSubtarget&lt;SparcSubtarget&gt;().isV9())
1864 setOperationAction(ISD::CTPOP, MVT::i32, Legal);
1865 case ISD::SETULT: return SPCC::ICC_CS;
1866 case ISD::SETULE: return SPCC::ICC_LEU;
1867 case ISD::SETUGT: return SPCC::ICC_GU;
1868 case ISD::SETUGE: return SPCC::ICC_CC;
1869 }
1870}
1871</pre>
1872</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1873
1874</div>
1875
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1876<!-- ======================================================================= -->
1877<div class="doc_subsection">
1878 <a name="callingConventions">Calling Conventions</a>
1879</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1880
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1881<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1882
1883<p>
1884To support target-specific calling conventions, <tt>XXXGenCallingConv.td</tt>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1885uses interfaces (such as CCIfType and CCAssignToReg) that are defined in
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1886<tt>lib/Target/TargetCallingConv.td</tt>. TableGen can take the target
1887descriptor file <tt>XXXGenCallingConv.td</tt> and generate the header
1888file <tt>XXXGenCallingConv.inc</tt>, which is typically included
1889in <tt>XXXISelLowering.cpp</tt>. You can use the interfaces in
1890<tt>TargetCallingConv.td</tt> to specify:
1891</p>
1892
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1893<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1894<li>The order of parameter allocation.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1895
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1896<li>Where parameters and return values are placed (that is, on the stack or in
1897 registers).</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1898
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1899<li>Which registers may be used.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1900
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1901<li>Whether the caller or callee unwinds the stack.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1902</ul>
1903
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1904<p>
1905The following example demonstrates the use of the <tt>CCIfType</tt> and
1906<tt>CCAssignToReg</tt> interfaces. If the <tt>CCIfType</tt> predicate is true
1907(that is, if the current argument is of type <tt>f32</tt> or <tt>f64</tt>), then
1908the action is performed. In this case, the <tt>CCAssignToReg</tt> action assigns
1909the argument value to the first available register: either <tt>R0</tt>
1910or <tt>R1</tt>.
1911</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1912
1913<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1914<pre>
1915CCIfType&lt;[f32,f64], CCAssignToReg&lt;[R0, R1]&gt;&gt;
1916</pre>
1917</div>
1918
1919<p>
1920<tt>SparcCallingConv.td</tt> contains definitions for a target-specific
1921return-value calling convention (RetCC_Sparc32) and a basic 32-bit C calling
1922convention (<tt>CC_Sparc32</tt>). The definition of <tt>RetCC_Sparc32</tt>
1923(shown below) indicates which registers are used for specified scalar return
1924types. A single-precision float is returned to register <tt>F0</tt>, and a
1925double-precision float goes to register <tt>D0</tt>. A 32-bit integer is
1926returned in register <tt>I0</tt> or <tt>I1</tt>.
1927</p>
1928
1929<div class="doc_code">
1930<pre>
1931def RetCC_Sparc32 : CallingConv&lt;[
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1932 CCIfType&lt;[i32], CCAssignToReg&lt;[I0, I1]&gt;&gt;,
1933 CCIfType&lt;[f32], CCAssignToReg&lt;[F0]&gt;&gt;,
1934 CCIfType&lt;[f64], CCAssignToReg&lt;[D0]&gt;&gt;
1935]&gt;;
1936</pre>
1937</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1938
1939<p>
1940The definition of <tt>CC_Sparc32</tt> in <tt>SparcCallingConv.td</tt> introduces
1941<tt>CCAssignToStack</tt>, which assigns the value to a stack slot with the
1942specified size and alignment. In the example below, the first parameter, 4,
1943indicates the size of the slot, and the second parameter, also 4, indicates the
1944stack alignment along 4-byte units. (Special cases: if size is zero, then the
1945ABI size is used; if alignment is zero, then the ABI alignment is used.)
1946</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1947
1948<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1949<pre>
1950def CC_Sparc32 : CallingConv&lt;[
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1951 // All arguments get passed in integer registers if there is space.
1952 CCIfType&lt;[i32, f32, f64], CCAssignToReg&lt;[I0, I1, I2, I3, I4, I5]&gt;&gt;,
1953 CCAssignToStack&lt;4, 4&gt;
1954]&gt;;
1955</pre>
1956</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1957
1958<p>
1959<tt>CCDelegateTo</tt> is another commonly used interface, which tries to find a
1960specified sub-calling convention, and, if a match is found, it is invoked. In
1961the following example (in <tt>X86CallingConv.td</tt>), the definition of
1962<tt>RetCC_X86_32_C</tt> ends with <tt>CCDelegateTo</tt>. After the current value
1963is assigned to the register <tt>ST0</tt> or <tt>ST1</tt>,
1964the <tt>RetCC_X86Common</tt> is invoked.
1965</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1966
1967<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1968<pre>
1969def RetCC_X86_32_C : CallingConv&lt;[
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1970 CCIfType&lt;[f32], CCAssignToReg&lt;[ST0, ST1]&gt;&gt;,
1971 CCIfType&lt;[f64], CCAssignToReg&lt;[ST0, ST1]&gt;&gt;,
1972 CCDelegateTo&lt;RetCC_X86Common&gt;
1973]&gt;;
1974</pre>
1975</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1976
1977<p>
1978<tt>CCIfCC</tt> is an interface that attempts to match the given name to the
1979current calling convention. If the name identifies the current calling
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1980convention, then a specified action is invoked. In the following example (in
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1981<tt>X86CallingConv.td</tt>), if the <tt>Fast</tt> calling convention is in use,
1982then <tt>RetCC_X86_32_Fast</tt> is invoked. If the <tt>SSECall</tt> calling
1983convention is in use, then <tt>RetCC_X86_32_SSE</tt> is invoked.
1984</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1985
1986<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1987<pre>
1988def RetCC_X86_32 : CallingConv&lt;[
1989 CCIfCC&lt;"CallingConv::Fast", CCDelegateTo&lt;RetCC_X86_32_Fast&gt;&gt;,
1990 CCIfCC&lt;"CallingConv::X86_SSECall", CCDelegateTo&lt;RetCC_X86_32_SSE&gt;&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1991 CCDelegateTo&lt;RetCC_X86_32_C&gt;
1992]&gt;;
1993</pre>
1994</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1995
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1996<p>Other calling convention interfaces include:</p>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1997
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]1998<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]1999<li><tt>CCIf &lt;predicate, action&gt;</tt> &mdash; If the predicate matches,
2000 apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2001
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2002<li><tt>CCIfInReg &lt;action&gt;</tt> &mdash; If the argument is marked with the
2003 '<tt>inreg</tt>' attribute, then apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2004
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2005<li><tt>CCIfNest &lt;action&gt;</tt> &mdash; Inf the argument is marked with the
2006 '<tt>nest</tt>' attribute, then apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2007
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2008<li><tt>CCIfNotVarArg &lt;action&gt;</tt> &mdash; If the current function does
2009 not take a variable number of arguments, apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2010
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2011<li><tt>CCAssignToRegWithShadow &lt;registerList, shadowList&gt;</tt> &mdash;
2012 similar to <tt>CCAssignToReg</tt>, but with a shadow list of registers.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2013
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2014<li><tt>CCPassByVal &lt;size, align&gt;</tt> &mdash; Assign value to a stack
2015 slot with the minimum specified size and alignment.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2016
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2017<li><tt>CCPromoteToType &lt;type&gt;</tt> &mdash; Promote the current value to
2018 the specified type.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2019
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2020<li><tt>CallingConv &lt;[actions]&gt;</tt> &mdash; Define each calling
2021 convention that is supported.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2022</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2023
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2024</div>
2025
2026<!-- *********************************************************************** -->
2027<div class="doc_section">
2028 <a name="assemblyPrinter">Assembly Printer</a>
2029</div>
2030<!-- *********************************************************************** -->
2031
2032<div class="doc_text">
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2033
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2034<p>
2035During the code emission stage, the code generator may utilize an LLVM pass to
2036produce assembly output. To do this, you want to implement the code for a
2037printer that converts LLVM IR to a GAS-format assembly language for your target
2038machine, using the following steps:
2039</p>
2040
2041<ul>
2042<li>Define all the assembly strings for your target, adding them to the
2043 instructions defined in the <tt>XXXInstrInfo.td</tt> file.
2044 (See <a href="#InstructionSet">Instruction Set</a>.) TableGen will produce
2045 an output file (<tt>XXXGenAsmWriter.inc</tt>) with an implementation of
2046 the <tt>printInstruction</tt> method for the XXXAsmPrinter class.</li>
2047
2048<li>Write <tt>XXXTargetAsmInfo.h</tt>, which contains the bare-bones declaration
2049 of the <tt>XXXTargetAsmInfo</tt> class (a subclass
2050 of <tt>TargetAsmInfo</tt>).</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2051
2052<li>Write <tt>XXXTargetAsmInfo.cpp</tt>, which contains target-specific values
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2053 for <tt>TargetAsmInfo</tt> properties and sometimes new implementations for
2054 methods.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2055
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2056<li>Write <tt>XXXAsmPrinter.cpp</tt>, which implements the <tt>AsmPrinter</tt>
2057 class that performs the LLVM-to-assembly conversion.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2058</ul>
2059
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2060<p>
2061The code in <tt>XXXTargetAsmInfo.h</tt> is usually a trivial declaration of the
2062<tt>XXXTargetAsmInfo</tt> class for use in <tt>XXXTargetAsmInfo.cpp</tt>.
2063Similarly, <tt>XXXTargetAsmInfo.cpp</tt> usually has a few declarations of
2064<tt>XXXTargetAsmInfo</tt> replacement values that override the default values
2065in <tt>TargetAsmInfo.cpp</tt>. For example in <tt>SparcTargetAsmInfo.cpp</tt>:
2066</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2067
2068<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2069<pre>
2070SparcTargetAsmInfo::SparcTargetAsmInfo(const SparcTargetMachine &amp;TM) {
2071 Data16bitsDirective = "\t.half\t";
2072 Data32bitsDirective = "\t.word\t";
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2073 Data64bitsDirective = 0; // .xword is only supported by V9.
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2074 ZeroDirective = "\t.skip\t";
2075 CommentString = "!";
2076 ConstantPoolSection = "\t.section \".rodata\",#alloc\n";
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2077}
2078</pre>
2079</div>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2080
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2081<p>
2082The X86 assembly printer implementation (<tt>X86TargetAsmInfo</tt>) is an
Chris Lattnerb6d66742009-08-02 04:02:52 +0000[diff] [blame]2083example where the target specific <tt>TargetAsmInfo</tt> class uses an
2084overridden methods: <tt>ExpandInlineAsm</tt>.
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2085</p>
2086
2087<p>
2088A target-specific implementation of AsmPrinter is written in
2089<tt>XXXAsmPrinter.cpp</tt>, which implements the <tt>AsmPrinter</tt> class that
2090converts the LLVM to printable assembly. The implementation must include the
2091following headers that have declarations for the <tt>AsmPrinter</tt> and
2092<tt>MachineFunctionPass</tt> classes. The <tt>MachineFunctionPass</tt> is a
2093subclass of <tt>FunctionPass</tt>.
2094</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2095
2096<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2097<pre>
2098#include "llvm/CodeGen/AsmPrinter.h"
2099#include "llvm/CodeGen/MachineFunctionPass.h"
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2100</pre>
2101</div>
2102
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2103<p>
2104As a <tt>FunctionPass</tt>, <tt>AsmPrinter</tt> first
2105calls <tt>doInitialization</tt> to set up the <tt>AsmPrinter</tt>. In
2106<tt>SparcAsmPrinter</tt>, a <tt>Mangler</tt> object is instantiated to process
2107variable names.
2108</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2109
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2110<p>
2111In <tt>XXXAsmPrinter.cpp</tt>, the <tt>runOnMachineFunction</tt> method
2112(declared in <tt>MachineFunctionPass</tt>) must be implemented
2113for <tt>XXXAsmPrinter</tt>. In <tt>MachineFunctionPass</tt>,
2114the <tt>runOnFunction</tt> method invokes <tt>runOnMachineFunction</tt>.
2115Target-specific implementations of <tt>runOnMachineFunction</tt> differ, but
2116generally do the following to process each machine function:
2117</p>
2118
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2119<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2120<li>Call <tt>SetupMachineFunction</tt> to perform initialization.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2121
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2122<li>Call <tt>EmitConstantPool</tt> to print out (to the output stream) constants
2123 which have been spilled to memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2124
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2125<li>Call <tt>EmitJumpTableInfo</tt> to print out jump tables used by the current
2126 function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2127
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2128<li>Print out the label for the current function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2129
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2130<li>Print out the code for the function, including basic block labels and the
2131 assembly for the instruction (using <tt>printInstruction</tt>)</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2132</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2133
2134<p>
2135The <tt>XXXAsmPrinter</tt> implementation must also include the code generated
2136by TableGen that is output in the <tt>XXXGenAsmWriter.inc</tt> file. The code
2137in <tt>XXXGenAsmWriter.inc</tt> contains an implementation of the
2138<tt>printInstruction</tt> method that may call these methods:
2139</p>
2140
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2141<ul>
2142<li><tt>printOperand</tt></li>
2143
2144<li><tt>printMemOperand</tt></li>
2145
2146<li><tt>printCCOperand (for conditional statements)</tt></li>
2147
2148<li><tt>printDataDirective</tt></li>
2149
2150<li><tt>printDeclare</tt></li>
2151
2152<li><tt>printImplicitDef</tt></li>
2153
2154<li><tt>printInlineAsm</tt></li>
2155
2156<li><tt>printLabel</tt></li>
2157
2158<li><tt>printPICJumpTableEntry</tt></li>
2159
2160<li><tt>printPICJumpTableSetLabel</tt></li>
2161</ul>
2162
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2163<p>
2164The implementations of <tt>printDeclare</tt>, <tt>printImplicitDef</tt>,
2165<tt>printInlineAsm</tt>, and <tt>printLabel</tt> in <tt>AsmPrinter.cpp</tt> are
2166generally adequate for printing assembly and do not need to be
2167overridden. (<tt>printBasicBlockLabel</tt> is another method that is implemented
2168in <tt>AsmPrinter.cpp</tt> that may be directly used in an implementation of
2169<tt>XXXAsmPrinter</tt>.)
2170</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2171
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2172<p>
2173The <tt>printOperand</tt> method is implemented with a long switch/case
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2174statement for the type of operand: register, immediate, basic block, external
2175symbol, global address, constant pool index, or jump table index. For an
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2176instruction with a memory address operand, the <tt>printMemOperand</tt> method
2177should be implemented to generate the proper output. Similarly,
2178<tt>printCCOperand</tt> should be used to print a conditional operand.
2179</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2180
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2181<p><tt>doFinalization</tt> should be overridden in <tt>XXXAsmPrinter</tt>, and
2182it should be called to shut down the assembly printer. During
2183<tt>doFinalization</tt>, global variables and constants are printed to
2184output.
2185</p>
2186
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2187</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2188
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2189<!-- *********************************************************************** -->
2190<div class="doc_section">
2191 <a name="subtargetSupport">Subtarget Support</a>
2192</div>
2193<!-- *********************************************************************** -->
2194
2195<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2196
2197<p>
2198Subtarget support is used to inform the code generation process of instruction
2199set variations for a given chip set. For example, the LLVM SPARC implementation
2200provided covers three major versions of the SPARC microprocessor architecture:
2201Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a 64-bit
2202architecture), and the UltraSPARC architecture. V8 has 16 double-precision
2203floating-point registers that are also usable as either 32 single-precision or 8
2204quad-precision registers. V8 is also purely big-endian. V9 has 32
2205double-precision floating-point registers that are also usable as 16
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2206quad-precision registers, but cannot be used as single-precision registers. The
2207UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2208extensions.
2209</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2210
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2211<p>
2212If subtarget support is needed, you should implement a target-specific
2213XXXSubtarget class for your architecture. This class should process the
2214command-line options <tt>-mcpu=</tt> and <tt>-mattr=</tt>.
2215</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2216
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2217<p>
2218TableGen uses definitions in the <tt>Target.td</tt> and <tt>Sparc.td</tt> files
2219to generate code in <tt>SparcGenSubtarget.inc</tt>. In <tt>Target.td</tt>, shown
2220below, the <tt>SubtargetFeature</tt> interface is defined. The first 4 string
2221parameters of the <tt>SubtargetFeature</tt> interface are a feature name, an
2222attribute set by the feature, the value of the attribute, and a description of
2223the feature. (The fifth parameter is a list of features whose presence is
2224implied, and its default value is an empty array.)
2225</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2226
2227<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2228<pre>
2229class SubtargetFeature&lt;string n, string a, string v, string d,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2230 list&lt;SubtargetFeature&gt; i = []&gt; {
2231 string Name = n;
2232 string Attribute = a;
2233 string Value = v;
2234 string Desc = d;
2235 list&lt;SubtargetFeature&gt; Implies = i;
2236}
2237</pre>
2238</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2239
2240<p>
2241In the <tt>Sparc.td</tt> file, the SubtargetFeature is used to define the
2242following features.
2243</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2244
2245<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2246<pre>
2247def FeatureV9 : SubtargetFeature&lt;"v9", "IsV9", "true",
2248 "Enable SPARC-V9 instructions"&gt;;
2249def FeatureV8Deprecated : SubtargetFeature&lt;"deprecated-v8",
2250 "V8DeprecatedInsts", "true",
2251 "Enable deprecated V8 instructions in V9 mode"&gt;;
2252def FeatureVIS : SubtargetFeature&lt;"vis", "IsVIS", "true",
2253 "Enable UltraSPARC Visual Instruction Set extensions"&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2254</pre>
2255</div>
2256
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2257<p>
2258Elsewhere in <tt>Sparc.td</tt>, the Proc class is defined and then is used to
2259define particular SPARC processor subtypes that may have the previously
2260described features.
2261</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2262
2263<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2264<pre>
2265class Proc&lt;string Name, list&lt;SubtargetFeature&gt; Features&gt;
2266 : Processor&lt;Name, NoItineraries, Features&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2267&nbsp;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2268def : Proc&lt;"generic", []&gt;;
2269def : Proc&lt;"v8", []&gt;;
2270def : Proc&lt;"supersparc", []&gt;;
2271def : Proc&lt;"sparclite", []&gt;;
2272def : Proc&lt;"f934", []&gt;;
2273def : Proc&lt;"hypersparc", []&gt;;
2274def : Proc&lt;"sparclite86x", []&gt;;
2275def : Proc&lt;"sparclet", []&gt;;
2276def : Proc&lt;"tsc701", []&gt;;
2277def : Proc&lt;"v9", [FeatureV9]&gt;;
2278def : Proc&lt;"ultrasparc", [FeatureV9, FeatureV8Deprecated]&gt;;
2279def : Proc&lt;"ultrasparc3", [FeatureV9, FeatureV8Deprecated]&gt;;
2280def : Proc&lt;"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2281</pre>
2282</div>
2283
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2284<p>
2285From <tt>Target.td</tt> and <tt>Sparc.td</tt> files, the resulting
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2286SparcGenSubtarget.inc specifies enum values to identify the features, arrays of
2287constants to represent the CPU features and CPU subtypes, and the
2288ParseSubtargetFeatures method that parses the features string that sets
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2289specified subtarget options. The generated <tt>SparcGenSubtarget.inc</tt> file
2290should be included in the <tt>SparcSubtarget.cpp</tt>. The target-specific
2291implementation of the XXXSubtarget method should follow this pseudocode:
2292</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2293
2294<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2295<pre>
2296XXXSubtarget::XXXSubtarget(const Module &amp;M, const std::string &amp;FS) {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2297 // Set the default features
2298 // Determine default and user specified characteristics of the CPU
2299 // Call ParseSubtargetFeatures(FS, CPU) to parse the features string
2300 // Perform any additional operations
2301}
2302</pre>
2303</div>
2304
Bill Wendlinge9e6fd92009-04-05 00:43:04 +0000[diff] [blame]2305</div>
2306
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2307<!-- *********************************************************************** -->
2308<div class="doc_section">
2309 <a name="jitSupport">JIT Support</a>
2310</div>
2311<!-- *********************************************************************** -->
2312
2313<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2314
2315<p>
2316The implementation of a target machine optionally includes a Just-In-Time (JIT)
2317code generator that emits machine code and auxiliary structures as binary output
2318that can be written directly to memory. To do this, implement JIT code
2319generation by performing the following steps:
2320</p>
2321
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2322<ul>
2323<li>Write an <tt>XXXCodeEmitter.cpp</tt> file that contains a machine function
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2324 pass that transforms target-machine instructions into relocatable machine
2325 code.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2326
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2327<li>Write an <tt>XXXJITInfo.cpp</tt> file that implements the JIT interfaces for
2328 target-specific code-generation activities, such as emitting machine code
2329 and stubs.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2330
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2331<li>Modify <tt>XXXTargetMachine</tt> so that it provides a
2332 <tt>TargetJITInfo</tt> object through its <tt>getJITInfo</tt> method.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2333</ul>
2334
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2335<p>
2336There are several different approaches to writing the JIT support code. For
2337instance, TableGen and target descriptor files may be used for creating a JIT
2338code generator, but are not mandatory. For the Alpha and PowerPC target
2339machines, TableGen is used to generate <tt>XXXGenCodeEmitter.inc</tt>, which
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2340contains the binary coding of machine instructions and the
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2341<tt>getBinaryCodeForInstr</tt> method to access those codes. Other JIT
2342implementations do not.
2343</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2344
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2345<p>
2346Both <tt>XXXJITInfo.cpp</tt> and <tt>XXXCodeEmitter.cpp</tt> must include the
2347<tt>llvm/CodeGen/MachineCodeEmitter.h</tt> header file that defines the
2348<tt>MachineCodeEmitter</tt> class containing code for several callback functions
2349that write data (in bytes, words, strings, etc.) to the output stream.
2350</p>
2351
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2352</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2353
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2354<!-- ======================================================================= -->
2355<div class="doc_subsection">
2356 <a name="mce">Machine Code Emitter</a>
2357</div>
2358
2359<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2360
2361<p>
2362In <tt>XXXCodeEmitter.cpp</tt>, a target-specific of the <tt>Emitter</tt> class
2363is implemented as a function pass (subclass
2364of <tt>MachineFunctionPass</tt>). The target-specific implementation
2365of <tt>runOnMachineFunction</tt> (invoked by
2366<tt>runOnFunction</tt> in <tt>MachineFunctionPass</tt>) iterates through the
2367<tt>MachineBasicBlock</tt> calls <tt>emitInstruction</tt> to process each
2368instruction and emit binary code. <tt>emitInstruction</tt> is largely
2369implemented with case statements on the instruction types defined in
2370<tt>XXXInstrInfo.h</tt>. For example, in <tt>X86CodeEmitter.cpp</tt>,
2371the <tt>emitInstruction</tt> method is built around the following switch/case
2372statements:
2373</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2374
2375<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2376<pre>
2377switch (Desc-&gt;TSFlags &amp; X86::FormMask) {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2378case X86II::Pseudo: // for not yet implemented instructions
2379 ... // or pseudo-instructions
2380 break;
2381case X86II::RawFrm: // for instructions with a fixed opcode value
2382 ...
2383 break;
2384case X86II::AddRegFrm: // for instructions that have one register operand
2385 ... // added to their opcode
2386 break;
2387case X86II::MRMDestReg:// for instructions that use the Mod/RM byte
2388 ... // to specify a destination (register)
2389 break;
2390case X86II::MRMDestMem:// for instructions that use the Mod/RM byte
2391 ... // to specify a destination (memory)
2392 break;
2393case X86II::MRMSrcReg: // for instructions that use the Mod/RM byte
2394 ... // to specify a source (register)
2395 break;
2396case X86II::MRMSrcMem: // for instructions that use the Mod/RM byte
2397 ... // to specify a source (memory)
2398 break;
2399case X86II::MRM0r: case X86II::MRM1r: // for instructions that operate on
2400case X86II::MRM2r: case X86II::MRM3r: // a REGISTER r/m operand and
2401case X86II::MRM4r: case X86II::MRM5r: // use the Mod/RM byte and a field
2402case X86II::MRM6r: case X86II::MRM7r: // to hold extended opcode data
2403 ...
2404 break;
2405case X86II::MRM0m: case X86II::MRM1m: // for instructions that operate on
2406case X86II::MRM2m: case X86II::MRM3m: // a MEMORY r/m operand and
2407case X86II::MRM4m: case X86II::MRM5m: // use the Mod/RM byte and a field
2408case X86II::MRM6m: case X86II::MRM7m: // to hold extended opcode data
2409 ...
2410 break;
2411case X86II::MRMInitReg: // for instructions whose source and
2412 ... // destination are the same register
2413 break;
2414}
2415</pre>
2416</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2417
2418<p>
2419The implementations of these case statements often first emit the opcode and
2420then get the operand(s). Then depending upon the operand, helper methods may be
2421called to process the operand(s). For example, in <tt>X86CodeEmitter.cpp</tt>,
2422for the <tt>X86II::AddRegFrm</tt> case, the first data emitted
2423(by <tt>emitByte</tt>) is the opcode added to the register operand. Then an
2424object representing the machine operand, <tt>MO1</tt>, is extracted. The helper
2425methods such as <tt>isImmediate</tt>,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2426<tt>isGlobalAddress</tt>, <tt>isExternalSymbol</tt>, <tt>isConstantPoolIndex</tt>, and
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2427<tt>isJumpTableIndex</tt> determine the operand
2428type. (<tt>X86CodeEmitter.cpp</tt> also has private methods such
2429as <tt>emitConstant</tt>, <tt>emitGlobalAddress</tt>,
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2430<tt>emitExternalSymbolAddress</tt>, <tt>emitConstPoolAddress</tt>,
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2431and <tt>emitJumpTableAddress</tt> that emit the data into the output stream.)
2432</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2433
2434<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2435<pre>
2436case X86II::AddRegFrm:
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2437 MCE.emitByte(BaseOpcode + getX86RegNum(MI.getOperand(CurOp++).getReg()));
2438
2439 if (CurOp != NumOps) {
2440 const MachineOperand &amp;MO1 = MI.getOperand(CurOp++);
2441 unsigned Size = X86InstrInfo::sizeOfImm(Desc);
2442 if (MO1.isImmediate())
2443 emitConstant(MO1.getImm(), Size);
2444 else {
2445 unsigned rt = Is64BitMode ? X86::reloc_pcrel_word
2446 : (IsPIC ? X86::reloc_picrel_word : X86::reloc_absolute_word);
2447 if (Opcode == X86::MOV64ri)
2448 rt = X86::reloc_absolute_dword; // FIXME: add X86II flag?
2449 if (MO1.isGlobalAddress()) {
2450 bool NeedStub = isa&lt;Function&gt;(MO1.getGlobal());
2451 bool isLazy = gvNeedsLazyPtr(MO1.getGlobal());
2452 emitGlobalAddress(MO1.getGlobal(), rt, MO1.getOffset(), 0,
2453 NeedStub, isLazy);
2454 } else if (MO1.isExternalSymbol())
2455 emitExternalSymbolAddress(MO1.getSymbolName(), rt);
2456 else if (MO1.isConstantPoolIndex())
2457 emitConstPoolAddress(MO1.getIndex(), rt);
2458 else if (MO1.isJumpTableIndex())
2459 emitJumpTableAddress(MO1.getIndex(), rt);
2460 }
2461 }
2462 break;
2463</pre>
2464</div>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2465
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2466<p>
2467In the previous example, <tt>XXXCodeEmitter.cpp</tt> uses the
2468variable <tt>rt</tt>, which is a RelocationType enum that may be used to
2469relocate addresses (for example, a global address with a PIC base offset). The
2470<tt>RelocationType</tt> enum for that target is defined in the short
2471target-specific <tt>XXXRelocations.h</tt> file. The <tt>RelocationType</tt> is used by
2472the <tt>relocate</tt> method defined in <tt>XXXJITInfo.cpp</tt> to rewrite
2473addresses for referenced global symbols.
2474</p>
2475
2476<p>
2477For example, <tt>X86Relocations.h</tt> specifies the following relocation types
2478for the X86 addresses. In all four cases, the relocated value is added to the
2479value already in memory. For <tt>reloc_pcrel_word</tt>
2480and <tt>reloc_picrel_word</tt>, there is an additional initial adjustment.
2481</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2482
2483<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2484<pre>
2485enum RelocationType {
2486 reloc_pcrel_word = 0, // add reloc value after adjusting for the PC loc
2487 reloc_picrel_word = 1, // add reloc value after adjusting for the PIC base
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2488 reloc_absolute_word = 2, // absolute relocation; no additional adjustment
2489 reloc_absolute_dword = 3 // absolute relocation; no additional adjustment
2490};
2491</pre>
2492</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2493
2494</div>
2495
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2496<!-- ======================================================================= -->
2497<div class="doc_subsection">
2498 <a name="targetJITInfo">Target JIT Info</a>
2499</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2500
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2501<div class="doc_text">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2502
2503<p>
2504<tt>XXXJITInfo.cpp</tt> implements the JIT interfaces for target-specific
2505code-generation activities, such as emitting machine code and stubs. At minimum,
2506a target-specific version of <tt>XXXJITInfo</tt> implements the following:
2507</p>
2508
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2509<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2510<li><tt>getLazyResolverFunction</tt> &mdash; Initializes the JIT, gives the
2511 target a function that is used for compilation.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2512
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2513<li><tt>emitFunctionStub</tt> &mdash; Returns a native function with a specified
2514 address for a callback function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2515
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2516<li><tt>relocate</tt> &mdash; Changes the addresses of referenced globals, based
2517 on relocation types.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2518
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2519<li>Callback function that are wrappers to a function stub that is used when the
2520 real target is not initially known.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2521</ul>
2522
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2523<p>
2524<tt>getLazyResolverFunction</tt> is generally trivial to implement. It makes the
2525incoming parameter as the global <tt>JITCompilerFunction</tt> and returns the
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2526callback function that will be used a function wrapper. For the Alpha target
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2527(in <tt>AlphaJITInfo.cpp</tt>), the <tt>getLazyResolverFunction</tt>
2528implementation is simply:
2529</p>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2530
2531<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2532<pre>
2533TargetJITInfo::LazyResolverFn AlphaJITInfo::getLazyResolverFunction(
2534 JITCompilerFn F) {
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2535 JITCompilerFunction = F;
2536 return AlphaCompilationCallback;
2537}
2538</pre>
2539</div>
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2540
Bill Wendling4a2bca82009-04-05 00:41:19 +0000[diff] [blame]2541<p>
2542For the X86 target, the <tt>getLazyResolverFunction</tt> implementation is a
2543little more complication, because it returns a different callback function for
2544processors with SSE instructions and XMM registers.
2545</p>
2546
2547<p>
2548The callback function initially saves and later restores the callee register
2549values, incoming arguments, and frame and return address. The callback function
2550needs low-level access to the registers or stack, so it is typically implemented
2551with assembler.
2552</p>
2553
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]2554</div>
2555
2556<!-- *********************************************************************** -->
2557
2558<hr>
2559<address>
2560 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]2561 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]2562 <a href="http://validator.w3.org/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]2563 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]2564
Chris Lattner78975382008-11-11 19:30:41 +0000[diff] [blame]2565 <a href="http://www.woo.com">Mason Woo</a> and <a href="http://misha.brukman.net">Misha Brukman</a><br>
Reid Spencer05fe4b02006-03-14 05:39:39 +0000[diff] [blame]2566 <a href="http://llvm.org">The LLVM Compiler Infrastructure</a>
Misha Brukman8eb67192004-09-06 22:58:13 +0000[diff] [blame]2567 <br>
2568 Last modified: $Date$
2569</address>
2570
2571</body>
2572</html>