blob: 39ac34b3d7790fd7f69e39de8ae14c9922be06a9 [file] [log] [blame]
Misha Brukman8eb67192004-09-06 22:58:13 +00001<!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 +00005 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Chris Lattner78975382008-11-11 19:30:41 +00006 <title>Writing an LLVM Compiler Backend</title>
Misha Brukman8eb67192004-09-06 22:58:13 +00007 <link rel="stylesheet" href="llvm.css" type="text/css">
8</head>
9
10<body>
11
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000012<h1>
Chris Lattner78975382008-11-11 19:30:41 +000013 Writing an LLVM Compiler Backend
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000014</h1>
Misha Brukman8eb67192004-09-06 22:58:13 +000015
16<ol>
17 <li><a href="#intro">Introduction</a>
Chris Lattner78975382008-11-11 19:30:41 +000018 <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 +000025 <li><a href="#TargetRegistration">Target Registration</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +000026 <li><a href="#RegisterSet">Register Set and Register Classes</a>
Chris Lattner78975382008-11-11 19:30:41 +000027 <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 +000031 </ul></li>
32 <li><a href="#InstructionSet">Instruction Set</a>
Chris Lattner78975382008-11-11 19:30:41 +000033 <ul>
Chris Lattner7a152732008-11-22 19:10:48 +000034 <li><a href="#operandMapping">Instruction Operand Mapping</a></li>
Chris Lattner78975382008-11-11 19:30:41 +000035 <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 +000037 </ul></li>
38 <li><a href="#InstructionSelector">Instruction Selector</a>
Chris Lattner78975382008-11-11 19:30:41 +000039 <ul>
Chris Lattner528875c2008-11-11 19:34:28 +000040 <li><a href="#LegalizePhase">The SelectionDAG Legalize Phase</a>
Chris Lattner78975382008-11-11 19:30:41 +000041 <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 +000046 </ul></li>
Chris Lattner78975382008-11-11 19:30:41 +000047 <li><a href="#callingConventions">Calling Conventions</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +000048 </ul></li>
Chris Lattner78975382008-11-11 19:30:41 +000049 <li><a href="#assemblyPrinter">Assembly Printer</a></li>
50 <li><a href="#subtargetSupport">Subtarget Support</a></li>
Chris Lattner528875c2008-11-11 19:34:28 +000051 <li><a href="#jitSupport">JIT Support</a>
Chris Lattner78975382008-11-11 19:30:41 +000052 <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 +000055 </ul></li>
Misha Brukman8eb67192004-09-06 22:58:13 +000056</ol>
57
58<div class="doc_author">
Bill Wendling4a2bca82009-04-05 00:41:19 +000059 <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 +000061</div>
62
63<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000064<h2>
Misha Brukman8eb67192004-09-06 22:58:13 +000065 <a name="intro">Introduction</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000066</h2>
Misha Brukman8eb67192004-09-06 22:58:13 +000067<!-- *********************************************************************** -->
68
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +000069<div>
Misha Brukman8eb67192004-09-06 22:58:13 +000070
Bill Wendling4a2bca82009-04-05 00:41:19 +000071<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 +000077
Bill Wendling4a2bca82009-04-05 00:41:19 +000078<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 +000090characteristics, such as a RISC instruction set and straightforward calling
Bill Wendling4a2bca82009-04-05 00:41:19 +000091conventions.
92</p>
93
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000094<h3>
Chris Lattner78975382008-11-11 19:30:41 +000095 <a name="Audience">Audience</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +000096</h3>
Misha Brukman8eb67192004-09-06 22:58:13 +000097
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +000098<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +000099
100<p>
101The audience for this document is anyone who needs to write an LLVM backend to
102generate code for a specific hardware or software target.
103</p>
104
Chris Lattner78975382008-11-11 19:30:41 +0000105</div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000106
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000107<h3>
Chris Lattner78975382008-11-11 19:30:41 +0000108 <a name="Prerequisite">Prerequisite Reading</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000109</h3>
Misha Brukman8eb67192004-09-06 22:58:13 +0000110
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000111<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000112
113<p>
114These essential documents must be read before reading this document:
115</p>
116
Chris Lattner78975382008-11-11 19:30:41 +0000117<ul>
NAKAMURA Takumi31c18062011-04-09 02:13:48 +0000118<li><i><a href="LangRef.html">LLVM Language Reference
Bill Wendling4a2bca82009-04-05 00:41:19 +0000119 Manual</a></i> &mdash; a reference manual for the LLVM assembly language.</li>
120
NAKAMURA Takumi31c18062011-04-09 02:13:48 +0000121<li><i><a href="CodeGenerator.html">The LLVM
Bill Wendling4a2bca82009-04-05 00:41:19 +0000122 Target-Independent Code Generator</a></i> &mdash; a guide to the components
123 (classes and code generation algorithms) for translating the LLVM internal
124 representation into machine code for a specified target. Pay particular
125 attention to the descriptions of code generation stages: Instruction
126 Selection, Scheduling and Formation, SSA-based Optimization, Register
127 Allocation, Prolog/Epilog Code Insertion, Late Machine Code Optimizations,
128 and Code Emission.</li>
129
NAKAMURA Takumi31c18062011-04-09 02:13:48 +0000130<li><i><a href="TableGenFundamentals.html">TableGen
Bill Wendling4a2bca82009-04-05 00:41:19 +0000131 Fundamentals</a></i> &mdash;a document that describes the TableGen
132 (<tt>tblgen</tt>) application that manages domain-specific information to
133 support LLVM code generation. TableGen processes input from a target
134 description file (<tt>.td</tt> suffix) and generates C++ code that can be
135 used for code generation.</li>
136
NAKAMURA Takumi31c18062011-04-09 02:13:48 +0000137<li><i><a href="WritingAnLLVMPass.html">Writing an LLVM
Bill Wendling4a2bca82009-04-05 00:41:19 +0000138 Pass</a></i> &mdash; The assembly printer is a <tt>FunctionPass</tt>, as are
139 several SelectionDAG processing steps.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000140</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000141
142<p>
143To follow the SPARC examples in this document, have a copy of
144<i><a href="http://www.sparc.org/standards/V8.pdf">The SPARC Architecture
145Manual, Version 8</a></i> for reference. For details about the ARM instruction
146set, refer to the <i><a href="http://infocenter.arm.com/">ARM Architecture
147Reference Manual</a></i>. For more about the GNU Assembler format
148(<tt>GAS</tt>), see
149<i><a href="http://sourceware.org/binutils/docs/as/index.html">Using As</a></i>,
150especially for the assembly printer. <i>Using As</i> contains a list of target
151machine dependent features.
152</p>
153
Chris Lattner78975382008-11-11 19:30:41 +0000154</div>
155
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000156<h3>
Chris Lattner78975382008-11-11 19:30:41 +0000157 <a name="Basic">Basic Steps</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000158</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000159
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000160<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000161
162<p>
163To write a compiler backend for LLVM that converts the LLVM IR to code for a
164specified target (machine or other language), follow these steps:
165</p>
Misha Brukman8eb67192004-09-06 22:58:13 +0000166
167<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000168<li>Create a subclass of the TargetMachine class that describes characteristics
169 of your target machine. Copy existing examples of specific TargetMachine
170 class and header files; for example, start with
171 <tt>SparcTargetMachine.cpp</tt> and <tt>SparcTargetMachine.h</tt>, but
172 change the file names for your target. Similarly, change code that
173 references "Sparc" to reference your target. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000174
Bill Wendling4a2bca82009-04-05 00:41:19 +0000175<li>Describe the register set of the target. Use TableGen to generate code for
176 register definition, register aliases, and register classes from a
177 target-specific <tt>RegisterInfo.td</tt> input file. You should also write
178 additional code for a subclass of the TargetRegisterInfo class that
179 represents the class register file data used for register allocation and
180 also describes the interactions between registers.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000181
Bill Wendling4a2bca82009-04-05 00:41:19 +0000182<li>Describe the instruction set of the target. Use TableGen to generate code
183 for target-specific instructions from target-specific versions of
184 <tt>TargetInstrFormats.td</tt> and <tt>TargetInstrInfo.td</tt>. You should
185 write additional code for a subclass of the TargetInstrInfo class to
186 represent machine instructions supported by the target machine. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000187
Bill Wendling4a2bca82009-04-05 00:41:19 +0000188<li>Describe the selection and conversion of the LLVM IR from a Directed Acyclic
189 Graph (DAG) representation of instructions to native target-specific
190 instructions. Use TableGen to generate code that matches patterns and
191 selects instructions based on additional information in a target-specific
192 version of <tt>TargetInstrInfo.td</tt>. Write code
193 for <tt>XXXISelDAGToDAG.cpp</tt>, where XXX identifies the specific target,
194 to perform pattern matching and DAG-to-DAG instruction selection. Also write
195 code in <tt>XXXISelLowering.cpp</tt> to replace or remove operations and
196 data types that are not supported natively in a SelectionDAG. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000197
Bill Wendling4a2bca82009-04-05 00:41:19 +0000198<li>Write code for an assembly printer that converts LLVM IR to a GAS format for
199 your target machine. You should add assembly strings to the instructions
200 defined in your target-specific version of <tt>TargetInstrInfo.td</tt>. You
201 should also write code for a subclass of AsmPrinter that performs the
202 LLVM-to-assembly conversion and a trivial subclass of TargetAsmInfo.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000203
Bill Wendling4a2bca82009-04-05 00:41:19 +0000204<li>Optionally, add support for subtargets (i.e., variants with different
205 capabilities). You should also write code for a subclass of the
206 TargetSubtarget class, which allows you to use the <tt>-mcpu=</tt>
207 and <tt>-mattr=</tt> command-line options.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000208
Bill Wendling4a2bca82009-04-05 00:41:19 +0000209<li>Optionally, add JIT support and create a machine code emitter (subclass of
210 TargetJITInfo) that is used to emit binary code directly into memory. </li>
Misha Brukman8eb67192004-09-06 22:58:13 +0000211</ul>
212
Bill Wendling4a2bca82009-04-05 00:41:19 +0000213<p>
214In the <tt>.cpp</tt> and <tt>.h</tt>. files, initially stub up these methods and
Chris Lattner78975382008-11-11 19:30:41 +0000215then implement them later. Initially, you may not know which private members
Bill Wendling4a2bca82009-04-05 00:41:19 +0000216that the class will need and which components will need to be subclassed.
217</p>
218
Misha Brukman8eb67192004-09-06 22:58:13 +0000219</div>
220
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000221<h3>
Chris Lattner78975382008-11-11 19:30:41 +0000222 <a name="Preliminaries">Preliminaries</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000223</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000224
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000225<div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000226
Bill Wendling4a2bca82009-04-05 00:41:19 +0000227<p>
228To actually create your compiler backend, you need to create and modify a few
229files. The absolute minimum is discussed here. But to actually use the LLVM
230target-independent code generator, you must perform the steps described in
NAKAMURA Takumi31c18062011-04-09 02:13:48 +0000231the <a href="CodeGenerator.html">LLVM
Bill Wendling4a2bca82009-04-05 00:41:19 +0000232Target-Independent Code Generator</a> document.
233</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000234
Bill Wendling4a2bca82009-04-05 00:41:19 +0000235<p>
236First, you should create a subdirectory under <tt>lib/Target</tt> to hold all
237the files related to your target. If your target is called "Dummy," create the
238directory <tt>lib/Target/Dummy</tt>.
239</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000240
Bill Wendling4a2bca82009-04-05 00:41:19 +0000241<p>
242In this new
243directory, create a <tt>Makefile</tt>. It is easiest to copy a
244<tt>Makefile</tt> of another target and modify it. It should at least contain
245the <tt>LEVEL</tt>, <tt>LIBRARYNAME</tt> and <tt>TARGET</tt> variables, and then
246include <tt>$(LEVEL)/Makefile.common</tt>. The library can be
247named <tt>LLVMDummy</tt> (for example, see the MIPS target). Alternatively, you
248can split the library into <tt>LLVMDummyCodeGen</tt>
249and <tt>LLVMDummyAsmPrinter</tt>, the latter of which should be implemented in a
250subdirectory below <tt>lib/Target/Dummy</tt> (for example, see the PowerPC
251target).
252</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000253
Bill Wendling4a2bca82009-04-05 00:41:19 +0000254<p>
255Note that these two naming schemes are hardcoded into <tt>llvm-config</tt>.
256Using any other naming scheme will confuse <tt>llvm-config</tt> and produce a
257lot of (seemingly unrelated) linker errors when linking <tt>llc</tt>.
258</p>
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000259
Bill Wendling4a2bca82009-04-05 00:41:19 +0000260<p>
261To make your target actually do something, you need to implement a subclass of
262<tt>TargetMachine</tt>. This implementation should typically be in the file
263<tt>lib/Target/DummyTargetMachine.cpp</tt>, but any file in
264the <tt>lib/Target</tt> directory will be built and should work. To use LLVM's
265target independent code generator, you should do what all current machine
266backends do: create a subclass of <tt>LLVMTargetMachine</tt>. (To create a
267target from scratch, create a subclass of <tt>TargetMachine</tt>.)
268</p>
269
270<p>
271To get LLVM to actually build and link your target, you need to add it to
272the <tt>TARGETS_TO_BUILD</tt> variable. To do this, you modify the configure
273script to know about your target when parsing the <tt>--enable-targets</tt>
274option. Search the configure script for <tt>TARGETS_TO_BUILD</tt>, add your
275target to the lists there (some creativity required), and then
Chris Lattner78975382008-11-11 19:30:41 +0000276reconfigure. Alternatively, you can change <tt>autotools/configure.ac</tt> and
Bill Wendling4a2bca82009-04-05 00:41:19 +0000277regenerate configure by running <tt>./autoconf/AutoRegen.sh</tt>.
278</p>
279
Matthijs Kooijman6aa81272008-09-29 11:52:22 +0000280</div>
Misha Brukman8eb67192004-09-06 22:58:13 +0000281
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000282</div>
283
Misha Brukman8eb67192004-09-06 22:58:13 +0000284<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000285<h2>
Chris Lattner78975382008-11-11 19:30:41 +0000286 <a name="TargetMachine">Target Machine</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000287</h2>
Chris Lattner78975382008-11-11 19:30:41 +0000288<!-- *********************************************************************** -->
Bill Wendling4a2bca82009-04-05 00:41:19 +0000289
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000290<div>
Chris Lattner78975382008-11-11 19:30:41 +0000291
Bill Wendling4a2bca82009-04-05 00:41:19 +0000292<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 +0000306instance, for the SPARC target, name the files <tt>SparcTargetMachine.h</tt> and
Bill Wendling4a2bca82009-04-05 00:41:19 +0000307<tt>SparcTargetMachine.cpp</tt>.
308</p>
Chris Lattner78975382008-11-11 19:30:41 +0000309
Bill Wendling4a2bca82009-04-05 00:41:19 +0000310<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 +0000320
Bill Wendling4a2bca82009-04-05 00:41:19 +0000321<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 +0000326
327<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +0000328<pre>
329namespace llvm {
Chris Lattner78975382008-11-11 19:30:41 +0000330
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 +0000340 virtual const TargetAsmInfo *createTargetAsmInfo() const;
Chris Lattner78975382008-11-11 19:30:41 +0000341
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);
Chris Lattner78975382008-11-11 19:30:41 +0000357};
358
359} // end namespace llvm
360</pre>
361</div>
362
Chris Lattner78975382008-11-11 19:30:41 +0000363<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000364<li><tt>getInstrInfo()</tt></li>
365<li><tt>getRegisterInfo()</tt></li>
366<li><tt>getFrameInfo()</tt></li>
367<li><tt>getTargetData()</tt></li>
368<li><tt>getSubtargetImpl()</tt></li>
Chris Lattner78975382008-11-11 19:30:41 +0000369</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000370
371<p>For some targets, you also need to support the following methods:</p>
372
373<ul>
374<li><tt>getTargetLowering()</tt></li>
375<li><tt>getJITInfo()</tt></li>
376</ul>
377
378<p>
379In addition, the <tt>XXXTargetMachine</tt> constructor should specify a
380<tt>TargetDescription</tt> string that determines the data layout for the target
381machine, including characteristics such as pointer size, alignment, and
382endianness. For example, the constructor for SparcTargetMachine contains the
383following:
384</p>
Chris Lattner78975382008-11-11 19:30:41 +0000385
386<div class="doc_code">
387<pre>
388SparcTargetMachine::SparcTargetMachine(const Module &amp;M, const std::string &amp;FS)
Bill Wendling4a2bca82009-04-05 00:41:19 +0000389 : DataLayout("E-p:32:32-f128:128:128"),
Chris Lattner78975382008-11-11 19:30:41 +0000390 Subtarget(M, FS), InstrInfo(Subtarget),
391 FrameInfo(TargetFrameInfo::StackGrowsDown, 8, 0) {
392}
393</pre>
394</div>
395
Bill Wendling4a2bca82009-04-05 00:41:19 +0000396<p>Hyphens separate portions of the <tt>TargetDescription</tt> string.</p>
397
398<ul>
399<li>An upper-case "<tt>E</tt>" in the string indicates a big-endian target data
400 model. a lower-case "<tt>e</tt>" indicates little-endian.</li>
401
402<li>"<tt>p:</tt>" is followed by pointer information: size, ABI alignment, and
403 preferred alignment. If only two figures follow "<tt>p:</tt>", then the
404 first value is pointer size, and the second value is both ABI and preferred
405 alignment.</li>
406
407<li>Then a letter for numeric type alignment: "<tt>i</tt>", "<tt>f</tt>",
408 "<tt>v</tt>", or "<tt>a</tt>" (corresponding to integer, floating point,
409 vector, or aggregate). "<tt>i</tt>", "<tt>v</tt>", or "<tt>a</tt>" are
410 followed by ABI alignment and preferred alignment. "<tt>f</tt>" is followed
411 by three values: the first indicates the size of a long double, then ABI
412 alignment, and then ABI preferred alignment.</li>
413</ul>
414
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000415</div>
416
417<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000418<h2>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000419 <a name="TargetRegistration">Target Registration</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000420</h2>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000421<!-- *********************************************************************** -->
422
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000423<div>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000424
Bill Wendling4a2bca82009-04-05 00:41:19 +0000425<p>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000426You must also register your target with the <tt>TargetRegistry</tt>, which is
427what other LLVM tools use to be able to lookup and use your target at
428runtime. The <tt>TargetRegistry</tt> can be used directly, but for most targets
429there are helper templates which should take care of the work for you.</p>
430
431<p>
432All targets should declare a global <tt>Target</tt> object which is used to
433represent the target during registration. Then, in the target's TargetInfo
434library, the target should define that object and use
435the <tt>RegisterTarget</tt> template to register the target. For example, the Sparc registration code looks like this:
Bill Wendling4a2bca82009-04-05 00:41:19 +0000436</p>
437
Chris Lattner78975382008-11-11 19:30:41 +0000438<div class="doc_code">
439<pre>
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000440Target llvm::TheSparcTarget;
441
442extern "C" void LLVMInitializeSparcTargetInfo() {
Benjamin Kramere15192b2009-08-05 15:42:44 +0000443 RegisterTarget&lt;Triple::sparc, /*HasJIT=*/false&gt;
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000444 X(TheSparcTarget, "sparc", "Sparc");
Chris Lattner78975382008-11-11 19:30:41 +0000445}
446</pre>
447</div>
448
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000449<p>
450This allows the <tt>TargetRegistry</tt> to look up the target by name or by
451target triple. In addition, most targets will also register additional features
452which are available in separate libraries. These registration steps are
453separate, because some clients may wish to only link in some parts of the target
454-- the JIT code generator does not require the use of the assembler printer, for
455example. Here is an example of registering the Sparc assembly printer:
456</p>
457
458<div class="doc_code">
459<pre>
460extern "C" void LLVMInitializeSparcAsmPrinter() {
Benjamin Kramere15192b2009-08-05 15:42:44 +0000461 RegisterAsmPrinter&lt;SparcAsmPrinter&gt; X(TheSparcTarget);
Daniel Dunbard6b06b12009-07-26 05:41:39 +0000462}
463</pre>
464</div>
465
466<p>
467For more information, see
468"<a href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>".
469</p>
470
Bill Wendling4a2bca82009-04-05 00:41:19 +0000471</div>
472
Chris Lattner78975382008-11-11 19:30:41 +0000473<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000474<h2>
Chris Lattner78975382008-11-11 19:30:41 +0000475 <a name="RegisterSet">Register Set and Register Classes</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000476</h2>
Chris Lattner78975382008-11-11 19:30:41 +0000477<!-- *********************************************************************** -->
Chris Lattner78975382008-11-11 19:30:41 +0000478
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000479<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000480
481<p>
482You should describe a concrete target-specific class that represents the
483register file of a target machine. This class is called <tt>XXXRegisterInfo</tt>
484(where <tt>XXX</tt> identifies the target) and represents the class register
485file data that is used for register allocation. It also describes the
486interactions between registers.
487</p>
488
489<p>
490You also need to define register classes to categorize related registers. A
491register class should be added for groups of registers that are all treated the
492same way for some instruction. Typical examples are register classes for
493integer, floating-point, or vector registers. A register allocator allows an
Chris Lattner78975382008-11-11 19:30:41 +0000494instruction to use any register in a specified register class to perform the
495instruction in a similar manner. Register classes allocate virtual registers to
496instructions from these sets, and register classes let the target-independent
Bill Wendling4a2bca82009-04-05 00:41:19 +0000497register allocator automatically choose the actual registers.
498</p>
Chris Lattner78975382008-11-11 19:30:41 +0000499
Bill Wendling4a2bca82009-04-05 00:41:19 +0000500<p>
501Much of the code for registers, including register definition, register aliases,
502and register classes, is generated by TableGen from <tt>XXXRegisterInfo.td</tt>
503input files and placed in <tt>XXXGenRegisterInfo.h.inc</tt> and
504<tt>XXXGenRegisterInfo.inc</tt> output files. Some of the code in the
505implementation of <tt>XXXRegisterInfo</tt> requires hand-coding.
506</p>
507
Chris Lattner78975382008-11-11 19:30:41 +0000508<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000509<h3>
Chris Lattner78975382008-11-11 19:30:41 +0000510 <a name="RegisterDef">Defining a Register</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000511</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000512
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000513<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000514
515<p>
516The <tt>XXXRegisterInfo.td</tt> file typically starts with register definitions
517for a target machine. The <tt>Register</tt> class (specified
518in <tt>Target.td</tt>) is used to define an object for each register. The
519specified string <tt>n</tt> becomes the <tt>Name</tt> of the register. The
520basic <tt>Register</tt> object does not have any subregisters and does not
521specify any aliases.
522</p>
523
Chris Lattner78975382008-11-11 19:30:41 +0000524<div class="doc_code">
525<pre>
526class Register&lt;string n&gt; {
Bill Wendling4a2bca82009-04-05 00:41:19 +0000527 string Namespace = "";
Chris Lattner78975382008-11-11 19:30:41 +0000528 string AsmName = n;
529 string Name = n;
530 int SpillSize = 0;
531 int SpillAlignment = 0;
532 list&lt;Register&gt; Aliases = [];
533 list&lt;Register&gt; SubRegs = [];
534 list&lt;int&gt; DwarfNumbers = [];
535}
536</pre>
537</div>
538
Bill Wendling4a2bca82009-04-05 00:41:19 +0000539<p>
540For example, in the <tt>X86RegisterInfo.td</tt> file, there are register
541definitions that utilize the Register class, such as:
542</p>
543
Chris Lattner78975382008-11-11 19:30:41 +0000544<div class="doc_code">
545<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000546def AL : Register&lt;"AL"&gt;, DwarfRegNum&lt;[0, 0, 0]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000547</pre>
548</div>
549
Bill Wendling4a2bca82009-04-05 00:41:19 +0000550<p>
551This defines the register <tt>AL</tt> and assigns it values (with
552<tt>DwarfRegNum</tt>) that are used by <tt>gcc</tt>, <tt>gdb</tt>, or a debug
Chris Lattnerc3107782010-04-05 04:11:11 +0000553information writer to identify a register. For register
Bill Wendling4a2bca82009-04-05 00:41:19 +0000554<tt>AL</tt>, <tt>DwarfRegNum</tt> takes an array of 3 values representing 3
555different modes: the first element is for X86-64, the second for exception
556handling (EH) on X86-32, and the third is generic. -1 is a special Dwarf number
557that indicates the gcc number is undefined, and -2 indicates the register number
558is invalid for this mode.
559</p>
Chris Lattner78975382008-11-11 19:30:41 +0000560
Bill Wendling4a2bca82009-04-05 00:41:19 +0000561<p>
562From the previously described line in the <tt>X86RegisterInfo.td</tt> file,
563TableGen generates this code in the <tt>X86GenRegisterInfo.inc</tt> file:
564</p>
565
Chris Lattner78975382008-11-11 19:30:41 +0000566<div class="doc_code">
567<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000568static const unsigned GR8[] = { X86::AL, ... };
569
570const unsigned AL_AliasSet[] = { X86::AX, X86::EAX, X86::RAX, 0 };
571
572const TargetRegisterDesc RegisterDescriptors[] = {
573 ...
574{ "AL", "AL", AL_AliasSet, Empty_SubRegsSet, Empty_SubRegsSet, AL_SuperRegsSet }, ...
Chris Lattner78975382008-11-11 19:30:41 +0000575</pre>
576</div>
577
Bill Wendling4a2bca82009-04-05 00:41:19 +0000578<p>
579From the register info file, TableGen generates a <tt>TargetRegisterDesc</tt>
580object for each register. <tt>TargetRegisterDesc</tt> is defined in
581<tt>include/llvm/Target/TargetRegisterInfo.h</tt> with the following fields:
582</p>
Chris Lattner78975382008-11-11 19:30:41 +0000583
584<div class="doc_code">
585<pre>
586struct TargetRegisterDesc {
587 const char *AsmName; // Assembly language name for the register
588 const char *Name; // Printable name for the reg (for debugging)
589 const unsigned *AliasSet; // Register Alias Set
590 const unsigned *SubRegs; // Sub-register set
591 const unsigned *ImmSubRegs; // Immediate sub-register set
592 const unsigned *SuperRegs; // Super-register set
593};</pre>
594</div>
595
Bill Wendling4a2bca82009-04-05 00:41:19 +0000596<p>
597TableGen uses the entire target description file (<tt>.td</tt>) to determine
598text names for the register (in the <tt>AsmName</tt> and <tt>Name</tt> fields of
599<tt>TargetRegisterDesc</tt>) and the relationships of other registers to the
600defined register (in the other <tt>TargetRegisterDesc</tt> fields). In this
601example, other definitions establish the registers "<tt>AX</tt>",
602"<tt>EAX</tt>", and "<tt>RAX</tt>" as aliases for one another, so TableGen
603generates a null-terminated array (<tt>AL_AliasSet</tt>) for this register alias
604set.
605</p>
Chris Lattner78975382008-11-11 19:30:41 +0000606
Bill Wendling4a2bca82009-04-05 00:41:19 +0000607<p>
608The <tt>Register</tt> class is commonly used as a base class for more complex
609classes. In <tt>Target.td</tt>, the <tt>Register</tt> class is the base for the
610<tt>RegisterWithSubRegs</tt> class that is used to define registers that need to
611specify subregisters in the <tt>SubRegs</tt> list, as shown here:
612</p>
613
Chris Lattner78975382008-11-11 19:30:41 +0000614<div class="doc_code">
615<pre>
616class RegisterWithSubRegs&lt;string n,
617list&lt;Register&gt; subregs&gt; : Register&lt;n&gt; {
618 let SubRegs = subregs;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000619}
620</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000621</div>
622
Bill Wendling4a2bca82009-04-05 00:41:19 +0000623<p>
624In <tt>SparcRegisterInfo.td</tt>, additional register classes are defined for
625SPARC: a Register subclass, SparcReg, and further subclasses: <tt>Ri</tt>,
626<tt>Rf</tt>, and <tt>Rd</tt>. SPARC registers are identified by 5-bit ID
627numbers, which is a feature common to these subclasses. Note the use of
628'<tt>let</tt>' expressions to override values that are initially defined in a
629superclass (such as <tt>SubRegs</tt> field in the <tt>Rd</tt> class).
630</p>
631
Chris Lattner78975382008-11-11 19:30:41 +0000632<div class="doc_code">
633<pre>
634class SparcReg&lt;string n&gt; : Register&lt;n&gt; {
635 field bits&lt;5&gt; Num;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000636 let Namespace = "SP";
Chris Lattner78975382008-11-11 19:30:41 +0000637}
638// Ri - 32-bit integer registers
639class Ri&lt;bits&lt;5&gt; num, string n&gt; :
640SparcReg&lt;n&gt; {
641 let Num = num;
642}
643// Rf - 32-bit floating-point registers
644class Rf&lt;bits&lt;5&gt; num, string n&gt; :
645SparcReg&lt;n&gt; {
646 let Num = num;
647}
648// Rd - Slots in the FP register file for 64-bit
649floating-point values.
650class Rd&lt;bits&lt;5&gt; num, string n,
651list&lt;Register&gt; subregs&gt; : SparcReg&lt;n&gt; {
652 let Num = num;
653 let SubRegs = subregs;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000654}
655</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000656</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000657
658<p>
659In the <tt>SparcRegisterInfo.td</tt> file, there are register definitions that
660utilize these subclasses of <tt>Register</tt>, such as:
661</p>
662
Chris Lattner78975382008-11-11 19:30:41 +0000663<div class="doc_code">
664<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000665def G0 : Ri&lt; 0, "G0"&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000666DwarfRegNum&lt;[0]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000667def G1 : Ri&lt; 1, "G1"&gt;, DwarfRegNum&lt;[1]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000668...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000669def F0 : Rf&lt; 0, "F0"&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000670DwarfRegNum&lt;[32]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000671def F1 : Rf&lt; 1, "F1"&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000672DwarfRegNum&lt;[33]&gt;;
673...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000674def D0 : Rd&lt; 0, "F0", [F0, F1]&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000675DwarfRegNum&lt;[32]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000676def D1 : Rd&lt; 2, "F2", [F2, F3]&gt;,
Chris Lattner78975382008-11-11 19:30:41 +0000677DwarfRegNum&lt;[34]&gt;;
678</pre>
679</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000680
681<p>
682The last two registers shown above (<tt>D0</tt> and <tt>D1</tt>) are
683double-precision floating-point registers that are aliases for pairs of
684single-precision floating-point sub-registers. In addition to aliases, the
685sub-register and super-register relationships of the defined register are in
686fields of a register's TargetRegisterDesc.
687</p>
688
Chris Lattner78975382008-11-11 19:30:41 +0000689</div>
690
691<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000692<h3>
Chris Lattner78975382008-11-11 19:30:41 +0000693 <a name="RegisterClassDef">Defining a Register Class</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000694</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000695
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000696<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000697
698<p>
699The <tt>RegisterClass</tt> class (specified in <tt>Target.td</tt>) is used to
Chris Lattner78975382008-11-11 19:30:41 +0000700define an object that represents a group of related registers and also defines
701the default allocation order of the registers. A target description file
Bill Wendling4a2bca82009-04-05 00:41:19 +0000702<tt>XXXRegisterInfo.td</tt> that uses <tt>Target.td</tt> can construct register
703classes using the following class:
704</p>
Chris Lattner78975382008-11-11 19:30:41 +0000705
706<div class="doc_code">
707<pre>
708class RegisterClass&lt;string namespace,
709list&lt;ValueType&gt; regTypes, int alignment,
710 list&lt;Register&gt; regList&gt; {
711 string Namespace = namespace;
712 list&lt;ValueType&gt; RegTypes = regTypes;
713 int Size = 0; // spill size, in bits; zero lets tblgen pick the size
714 int Alignment = alignment;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000715
Chris Lattner78975382008-11-11 19:30:41 +0000716 // CopyCost is the cost of copying a value between two registers
717 // default value 1 means a single instruction
718 // A negative value means copying is extremely expensive or impossible
719 int CopyCost = 1;
720 list&lt;Register&gt; MemberList = regList;
721
722 // for register classes that are subregisters of this class
723 list&lt;RegisterClass&gt; SubRegClassList = [];
724
725 code MethodProtos = [{}]; // to insert arbitrary code
726 code MethodBodies = [{}];
Bill Wendling4a2bca82009-04-05 00:41:19 +0000727}
728</pre>
Chris Lattner78975382008-11-11 19:30:41 +0000729</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000730
Chris Lattner78975382008-11-11 19:30:41 +0000731<p>To define a RegisterClass, use the following 4 arguments:</p>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000732
Chris Lattner78975382008-11-11 19:30:41 +0000733<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000734<li>The first argument of the definition is the name of the namespace.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000735
Bill Wendling4a2bca82009-04-05 00:41:19 +0000736<li>The second argument is a list of <tt>ValueType</tt> register type values
737 that are defined in <tt>include/llvm/CodeGen/ValueTypes.td</tt>. Defined
738 values include integer types (such as <tt>i16</tt>, <tt>i32</tt>,
739 and <tt>i1</tt> for Boolean), floating-point types
740 (<tt>f32</tt>, <tt>f64</tt>), and vector types (for example, <tt>v8i16</tt>
741 for an <tt>8 x i16</tt> vector). All registers in a <tt>RegisterClass</tt>
742 must have the same <tt>ValueType</tt>, but some registers may store vector
743 data in different configurations. For example a register that can process a
744 128-bit vector may be able to handle 16 8-bit integer elements, 8 16-bit
745 integers, 4 32-bit integers, and so on. </li>
Chris Lattner78975382008-11-11 19:30:41 +0000746
Bill Wendling4a2bca82009-04-05 00:41:19 +0000747<li>The third argument of the <tt>RegisterClass</tt> definition specifies the
748 alignment required of the registers when they are stored or loaded to
749 memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000750
Bill Wendling4a2bca82009-04-05 00:41:19 +0000751<li>The final argument, <tt>regList</tt>, specifies which registers are in this
752 class. If an <tt>allocation_order_*</tt> method is not specified,
753 then <tt>regList</tt> also defines the order of allocation used by the
754 register allocator.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000755</ul>
756
Bill Wendling4a2bca82009-04-05 00:41:19 +0000757<p>
758In <tt>SparcRegisterInfo.td</tt>, three RegisterClass objects are defined:
759<tt>FPRegs</tt>, <tt>DFPRegs</tt>, and <tt>IntRegs</tt>. For all three register
760classes, the first argument defines the namespace with the string
761'<tt>SP</tt>'. <tt>FPRegs</tt> defines a group of 32 single-precision
762floating-point registers (<tt>F0</tt> to <tt>F31</tt>); <tt>DFPRegs</tt> defines
763a group of 16 double-precision registers
764(<tt>D0-D15</tt>). For <tt>IntRegs</tt>, the <tt>MethodProtos</tt>
765and <tt>MethodBodies</tt> methods are used by TableGen to insert the specified
766code into generated output.
767</p>
768
Chris Lattner78975382008-11-11 19:30:41 +0000769<div class="doc_code">
770<pre>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000771def FPRegs : RegisterClass&lt;"SP", [f32], 32,
772 [F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15,
773 F16, F17, F18, F19, F20, F21, F22, F23, F24, F25, F26, F27, F28, F29, F30, F31]&gt;;
774
775def DFPRegs : RegisterClass&lt;"SP", [f64], 64,
776 [D0, D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, D14, D15]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +0000777&nbsp;
Bill Wendling4a2bca82009-04-05 00:41:19 +0000778def IntRegs : RegisterClass&lt;"SP", [i32], 32,
779 [L0, L1, L2, L3, L4, L5, L6, L7,
780 I0, I1, I2, I3, I4, I5,
781 O0, O1, O2, O3, O4, O5, O7,
782 G1,
783 // Non-allocatable regs:
784 G2, G3, G4,
785 O6, // stack ptr
786 I6, // frame ptr
787 I7, // return address
788 G0, // constant zero
789 G5, G6, G7 // reserved for kernel
790 ]&gt; {
Chris Lattner78975382008-11-11 19:30:41 +0000791 let MethodProtos = [{
792 iterator allocation_order_end(const MachineFunction &amp;MF) const;
793 }];
794 let MethodBodies = [{
795 IntRegsClass::iterator
796 IntRegsClass::allocation_order_end(const MachineFunction &amp;MF) const {
Bill Wendling4a2bca82009-04-05 00:41:19 +0000797 return end() - 10 // Don't allocate special registers
798 -1;
Chris Lattner78975382008-11-11 19:30:41 +0000799 }
800 }];
801}
802</pre>
803</div>
804
Bill Wendling4a2bca82009-04-05 00:41:19 +0000805<p>
806Using <tt>SparcRegisterInfo.td</tt> with TableGen generates several output files
807that are intended for inclusion in other source code that you write.
808<tt>SparcRegisterInfo.td</tt> generates <tt>SparcGenRegisterInfo.h.inc</tt>,
809which should be included in the header file for the implementation of the SPARC
810register implementation that you write (<tt>SparcRegisterInfo.h</tt>). In
Chris Lattner78975382008-11-11 19:30:41 +0000811<tt>SparcGenRegisterInfo.h.inc</tt> a new structure is defined called
Bill Wendling4a2bca82009-04-05 00:41:19 +0000812<tt>SparcGenRegisterInfo</tt> that uses <tt>TargetRegisterInfo</tt> as its
813base. It also specifies types, based upon the defined register
814classes: <tt>DFPRegsClass</tt>, <tt>FPRegsClass</tt>, and <tt>IntRegsClass</tt>.
815</p>
Chris Lattner78975382008-11-11 19:30:41 +0000816
Bill Wendling4a2bca82009-04-05 00:41:19 +0000817<p>
818<tt>SparcRegisterInfo.td</tt> also generates <tt>SparcGenRegisterInfo.inc</tt>,
819which is included at the bottom of <tt>SparcRegisterInfo.cpp</tt>, the SPARC
820register implementation. The code below shows only the generated integer
821registers and associated register classes. The order of registers
822in <tt>IntRegs</tt> reflects the order in the definition of <tt>IntRegs</tt> in
823the target description file. Take special note of the use
824of <tt>MethodBodies</tt> in <tt>SparcRegisterInfo.td</tt> to create code in
825<tt>SparcGenRegisterInfo.inc</tt>. <tt>MethodProtos</tt> generates similar code
826in <tt>SparcGenRegisterInfo.h.inc</tt>.
827</p>
Chris Lattner78975382008-11-11 19:30:41 +0000828
829<div class="doc_code">
830<pre> // IntRegs Register Class...
831 static const unsigned IntRegs[] = {
832 SP::L0, SP::L1, SP::L2, SP::L3, SP::L4, SP::L5,
Bill Wendling4a2bca82009-04-05 00:41:19 +0000833 SP::L6, SP::L7, SP::I0, SP::I1, SP::I2, SP::I3,
834 SP::I4, SP::I5, SP::O0, SP::O1, SP::O2, SP::O3,
835 SP::O4, SP::O5, SP::O7, SP::G1, SP::G2, SP::G3,
836 SP::G4, SP::O6, SP::I6, SP::I7, SP::G0, SP::G5,
837 SP::G6, SP::G7,
Chris Lattner78975382008-11-11 19:30:41 +0000838 };
Bill Wendling4a2bca82009-04-05 00:41:19 +0000839
Chris Lattner78975382008-11-11 19:30:41 +0000840 // IntRegsVTs Register Class Value Types...
841 static const MVT::ValueType IntRegsVTs[] = {
842 MVT::i32, MVT::Other
843 };
Bill Wendling4a2bca82009-04-05 00:41:19 +0000844
Chris Lattner78975382008-11-11 19:30:41 +0000845namespace SP { // Register class instances
846 DFPRegsClass&nbsp;&nbsp;&nbsp; DFPRegsRegClass;
847 FPRegsClass&nbsp;&nbsp;&nbsp;&nbsp; FPRegsRegClass;
848 IntRegsClass&nbsp;&nbsp;&nbsp; IntRegsRegClass;
849...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000850 // IntRegs Sub-register Classess...
Chris Lattner78975382008-11-11 19:30:41 +0000851 static const TargetRegisterClass* const IntRegsSubRegClasses [] = {
852 NULL
853 };
854...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000855 // IntRegs Super-register Classess...
Chris Lattner78975382008-11-11 19:30:41 +0000856 static const TargetRegisterClass* const IntRegsSuperRegClasses [] = {
857 NULL
858 };
Bill Wendling4a2bca82009-04-05 00:41:19 +0000859...
860 // IntRegs Register Class sub-classes...
Chris Lattner78975382008-11-11 19:30:41 +0000861 static const TargetRegisterClass* const IntRegsSubclasses [] = {
862 NULL
863 };
864...
Bill Wendling4a2bca82009-04-05 00:41:19 +0000865 // IntRegs Register Class super-classes...
Chris Lattner78975382008-11-11 19:30:41 +0000866 static const TargetRegisterClass* const IntRegsSuperclasses [] = {
867 NULL
868 };
869...
Chris Lattner78975382008-11-11 19:30:41 +0000870 IntRegsClass::iterator
871 IntRegsClass::allocation_order_end(const MachineFunction &amp;MF) const {
Chris Lattner78975382008-11-11 19:30:41 +0000872 return end()-10 // Don't allocate special registers
Bill Wendling4a2bca82009-04-05 00:41:19 +0000873 -1;
Chris Lattner78975382008-11-11 19:30:41 +0000874 }
875
Bill Wendling4a2bca82009-04-05 00:41:19 +0000876 IntRegsClass::IntRegsClass() : TargetRegisterClass(IntRegsRegClassID,
877 IntRegsVTs, IntRegsSubclasses, IntRegsSuperclasses, IntRegsSubRegClasses,
878 IntRegsSuperRegClasses, 4, 4, 1, IntRegs, IntRegs + 32) {}
Chris Lattner78975382008-11-11 19:30:41 +0000879}
880</pre>
881</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000882
883</div>
884
Chris Lattner78975382008-11-11 19:30:41 +0000885<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000886<h3>
Chris Lattner7d12b4b2008-11-11 19:36:31 +0000887 <a name="implementRegister">Implement a subclass of</a>
NAKAMURA Takumi31c18062011-04-09 02:13:48 +0000888 <a href="CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000889</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000890
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000891<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000892
893<p>
894The final step is to hand code portions of <tt>XXXRegisterInfo</tt>, which
895implements the interface described in <tt>TargetRegisterInfo.h</tt>. These
896functions return <tt>0</tt>, <tt>NULL</tt>, or <tt>false</tt>, unless
897overridden. Here is a list of functions that are overridden for the SPARC
898implementation in <tt>SparcRegisterInfo.cpp</tt>:
899</p>
900
Chris Lattner78975382008-11-11 19:30:41 +0000901<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000902<li><tt>getCalleeSavedRegs</tt> &mdash; Returns a list of callee-saved registers
903 in the order of the desired callee-save stack frame offset.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000904
Bill Wendling4a2bca82009-04-05 00:41:19 +0000905<li><tt>getReservedRegs</tt> &mdash; Returns a bitset indexed by physical
906 register numbers, indicating if a particular register is unavailable.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000907
Bill Wendling4a2bca82009-04-05 00:41:19 +0000908<li><tt>hasFP</tt> &mdash; Return a Boolean indicating if a function should have
909 a dedicated frame pointer register.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000910
Bill Wendling4a2bca82009-04-05 00:41:19 +0000911<li><tt>eliminateCallFramePseudoInstr</tt> &mdash; If call frame setup or
912 destroy pseudo instructions are used, this can be called to eliminate
913 them.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000914
Bill Wendling4a2bca82009-04-05 00:41:19 +0000915<li><tt>eliminateFrameIndex</tt> &mdash; Eliminate abstract frame indices from
916 instructions that may use them.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000917
Bill Wendling4a2bca82009-04-05 00:41:19 +0000918<li><tt>emitPrologue</tt> &mdash; Insert prologue code into the function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000919
Bill Wendling4a2bca82009-04-05 00:41:19 +0000920<li><tt>emitEpilogue</tt> &mdash; Insert epilogue code into the function.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000921</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000922
Chris Lattner78975382008-11-11 19:30:41 +0000923</div>
924
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000925</div>
926
Chris Lattner78975382008-11-11 19:30:41 +0000927<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000928<h2>
Chris Lattner78975382008-11-11 19:30:41 +0000929 <a name="InstructionSet">Instruction Set</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000930</h2>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000931
Chris Lattner78975382008-11-11 19:30:41 +0000932<!-- *********************************************************************** -->
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000933<div>
Chris Lattner78975382008-11-11 19:30:41 +0000934
Bill Wendling4a2bca82009-04-05 00:41:19 +0000935<p>
936During the early stages of code generation, the LLVM IR code is converted to a
937<tt>SelectionDAG</tt> with nodes that are instances of the <tt>SDNode</tt> class
938containing target instructions. An <tt>SDNode</tt> has an opcode, operands, type
939requirements, and operation properties. For example, is an operation
940commutative, does an operation load from memory. The various operation node
941types are described in the <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>
942file (values of the <tt>NodeType</tt> enum in the <tt>ISD</tt> namespace).
943</p>
944
945<p>
946TableGen uses the following target description (<tt>.td</tt>) input files to
947generate much of the code for instruction definition:
948</p>
949
Chris Lattner78975382008-11-11 19:30:41 +0000950<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +0000951<li><tt>Target.td</tt> &mdash; Where the <tt>Instruction</tt>, <tt>Operand</tt>,
952 <tt>InstrInfo</tt>, and other fundamental classes are defined.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000953
Bill Wendling4a2bca82009-04-05 00:41:19 +0000954<li><tt>TargetSelectionDAG.td</tt>&mdash; Used by <tt>SelectionDAG</tt>
955 instruction selection generators, contains <tt>SDTC*</tt> classes (selection
956 DAG type constraint), definitions of <tt>SelectionDAG</tt> nodes (such as
957 <tt>imm</tt>, <tt>cond</tt>, <tt>bb</tt>, <tt>add</tt>, <tt>fadd</tt>,
958 <tt>sub</tt>), and pattern support (<tt>Pattern</tt>, <tt>Pat</tt>,
959 <tt>PatFrag</tt>, <tt>PatLeaf</tt>, <tt>ComplexPattern</tt>.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000960
Bill Wendling4a2bca82009-04-05 00:41:19 +0000961<li><tt>XXXInstrFormats.td</tt> &mdash; Patterns for definitions of
962 target-specific instructions.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000963
Bill Wendling4a2bca82009-04-05 00:41:19 +0000964<li><tt>XXXInstrInfo.td</tt> &mdash; Target-specific definitions of instruction
965 templates, condition codes, and instructions of an instruction set. For
966 architecture modifications, a different file name may be used. For example,
967 for Pentium with SSE instruction, this file is <tt>X86InstrSSE.td</tt>, and
968 for Pentium with MMX, this file is <tt>X86InstrMMX.td</tt>.</li>
Chris Lattner78975382008-11-11 19:30:41 +0000969</ul>
970
Bill Wendling4a2bca82009-04-05 00:41:19 +0000971<p>
972There is also a target-specific <tt>XXX.td</tt> file, where <tt>XXX</tt> is the
973name of the target. The <tt>XXX.td</tt> file includes the other <tt>.td</tt>
974input files, but its contents are only directly important for subtargets.
975</p>
976
977<p>
978You should describe a concrete target-specific class <tt>XXXInstrInfo</tt> that
979represents machine instructions supported by a target machine.
980<tt>XXXInstrInfo</tt> contains an array of <tt>XXXInstrDescriptor</tt> objects,
981each of which describes one instruction. An instruction descriptor defines:</p>
982
983<ul>
984<li>Opcode mnemonic</li>
985
986<li>Number of operands</li>
987
988<li>List of implicit register definitions and uses</li>
989
990<li>Target-independent properties (such as memory access, is commutable)</li>
991
992<li>Target-specific flags </li>
993</ul>
994
995<p>
996The Instruction class (defined in <tt>Target.td</tt>) is mostly used as a base
997for more complex instruction classes.
998</p>
Chris Lattner78975382008-11-11 19:30:41 +0000999
1000<div class="doc_code">
1001<pre>class Instruction {
Bill Wendling4a2bca82009-04-05 00:41:19 +00001002 string Namespace = "";
Chris Lattner78975382008-11-11 19:30:41 +00001003 dag OutOperandList; // An dag containing the MI def operand list.
1004 dag InOperandList; // An dag containing the MI use operand list.
Bill Wendling4a2bca82009-04-05 00:41:19 +00001005 string AsmString = ""; // The .s format to print the instruction with.
Chris Lattner78975382008-11-11 19:30:41 +00001006 list&lt;dag&gt; Pattern; // Set to the DAG pattern for this instruction
1007 list&lt;Register&gt; Uses = [];
1008 list&lt;Register&gt; Defs = [];
1009 list&lt;Predicate&gt; Predicates = []; // predicates turned into isel match code
1010 ... remainder not shown for space ...
1011}
1012</pre>
1013</div>
Chris Lattner78975382008-11-11 19:30:41 +00001014
Bill Wendling4a2bca82009-04-05 00:41:19 +00001015<p>
1016A <tt>SelectionDAG</tt> node (<tt>SDNode</tt>) should contain an object
1017representing a target-specific instruction that is defined
1018in <tt>XXXInstrInfo.td</tt>. The instruction objects should represent
1019instructions from the architecture manual of the target machine (such as the
1020SPARC Architecture Manual for the SPARC target).
1021</p>
1022
1023<p>
1024A single instruction from the architecture manual is often modeled as multiple
1025target instructions, depending upon its operands. For example, a manual might
Chris Lattner78975382008-11-11 19:30:41 +00001026describe an add instruction that takes a register or an immediate operand. An
Bill Wendling4a2bca82009-04-05 00:41:19 +00001027LLVM target could model this with two instructions named <tt>ADDri</tt> and
1028<tt>ADDrr</tt>.
1029</p>
Chris Lattner78975382008-11-11 19:30:41 +00001030
Bill Wendling4a2bca82009-04-05 00:41:19 +00001031<p>
1032You should define a class for each instruction category and define each opcode
1033as a subclass of the category with appropriate parameters such as the fixed
1034binary encoding of opcodes and extended opcodes. You should map the register
1035bits to the bits of the instruction in which they are encoded (for the
1036JIT). Also you should specify how the instruction should be printed when the
1037automatic assembly printer is used.
1038</p>
Chris Lattner78975382008-11-11 19:30:41 +00001039
Bill Wendling4a2bca82009-04-05 00:41:19 +00001040<p>
1041As is described in the SPARC Architecture Manual, Version 8, there are three
1042major 32-bit formats for instructions. Format 1 is only for the <tt>CALL</tt>
1043instruction. Format 2 is for branch on condition codes and <tt>SETHI</tt> (set
1044high bits of a register) instructions. Format 3 is for other instructions.
1045</p>
Chris Lattner78975382008-11-11 19:30:41 +00001046
Bill Wendling4a2bca82009-04-05 00:41:19 +00001047<p>
1048Each of these formats has corresponding classes in <tt>SparcInstrFormat.td</tt>.
1049<tt>InstSP</tt> is a base class for other instruction classes. Additional base
1050classes are specified for more precise formats: for example
1051in <tt>SparcInstrFormat.td</tt>, <tt>F2_1</tt> is for <tt>SETHI</tt>,
1052and <tt>F2_2</tt> is for branches. There are three other base
1053classes: <tt>F3_1</tt> for register/register operations, <tt>F3_2</tt> for
1054register/immediate operations, and <tt>F3_3</tt> for floating-point
1055operations. <tt>SparcInstrInfo.td</tt> also adds the base class Pseudo for
1056synthetic SPARC instructions.
1057</p>
Chris Lattner78975382008-11-11 19:30:41 +00001058
Bill Wendling4a2bca82009-04-05 00:41:19 +00001059<p>
1060<tt>SparcInstrInfo.td</tt> largely consists of operand and instruction
1061definitions for the SPARC target. In <tt>SparcInstrInfo.td</tt>, the following
1062target description file entry, <tt>LDrr</tt>, defines the Load Integer
1063instruction for a Word (the <tt>LD</tt> SPARC opcode) from a memory address to a
1064register. The first parameter, the value 3 (<tt>11<sub>2</sub></tt>), is the
1065operation value for this category of operation. The second parameter
1066(<tt>000000<sub>2</sub></tt>) is the specific operation value
1067for <tt>LD</tt>/Load Word. The third parameter is the output destination, which
1068is a register operand and defined in the <tt>Register</tt> target description
1069file (<tt>IntRegs</tt>).
1070</p>
1071
Chris Lattner78975382008-11-11 19:30:41 +00001072<div class="doc_code">
1073<pre>def LDrr : F3_1 &lt;3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
Bill Wendling4a2bca82009-04-05 00:41:19 +00001074 "ld [$addr], $dst",
Chris Lattner78975382008-11-11 19:30:41 +00001075 [(set IntRegs:$dst, (load ADDRrr:$addr))]&gt;;
1076</pre>
1077</div>
1078
Bill Wendling4a2bca82009-04-05 00:41:19 +00001079<p>
1080The fourth parameter is the input source, which uses the address
1081operand <tt>MEMrr</tt> that is defined earlier in <tt>SparcInstrInfo.td</tt>:
1082</p>
1083
Chris Lattner78975382008-11-11 19:30:41 +00001084<div class="doc_code">
1085<pre>def MEMrr : Operand&lt;i32&gt; {
Bill Wendling4a2bca82009-04-05 00:41:19 +00001086 let PrintMethod = "printMemOperand";
Chris Lattner78975382008-11-11 19:30:41 +00001087 let MIOperandInfo = (ops IntRegs, IntRegs);
1088}
1089</pre>
1090</div>
Chris Lattner78975382008-11-11 19:30:41 +00001091
Bill Wendling4a2bca82009-04-05 00:41:19 +00001092<p>
1093The fifth parameter is a string that is used by the assembly printer and can be
1094left as an empty string until the assembly printer interface is implemented. The
1095sixth and final parameter is the pattern used to match the instruction during
1096the SelectionDAG Select Phase described in
NAKAMURA Takumi31c18062011-04-09 02:13:48 +00001097(<a href="CodeGenerator.html">The LLVM
Bill Wendling4a2bca82009-04-05 00:41:19 +00001098Target-Independent Code Generator</a>). This parameter is detailed in the next
1099section, <a href="#InstructionSelector">Instruction Selector</a>.
1100</p>
1101
1102<p>
1103Instruction class definitions are not overloaded for different operand types, so
1104separate versions of instructions are needed for register, memory, or immediate
1105value operands. For example, to perform a Load Integer instruction for a Word
Chris Lattner78975382008-11-11 19:30:41 +00001106from an immediate operand to a register, the following instruction class is
Bill Wendling4a2bca82009-04-05 00:41:19 +00001107defined:
1108</p>
1109
Chris Lattner78975382008-11-11 19:30:41 +00001110<div class="doc_code">
1111<pre>def LDri : F3_2 &lt;3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
Bill Wendling4a2bca82009-04-05 00:41:19 +00001112 "ld [$addr], $dst",
Chris Lattner78975382008-11-11 19:30:41 +00001113 [(set IntRegs:$dst, (load ADDRri:$addr))]&gt;;
1114</pre>
1115</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001116
1117<p>
1118Writing these definitions for so many similar instructions can involve a lot of
1119cut and paste. In td files, the <tt>multiclass</tt> directive enables the
1120creation of templates to define several instruction classes at once (using
1121the <tt>defm</tt> directive). For example in <tt>SparcInstrInfo.td</tt>, the
1122<tt>multiclass</tt> pattern <tt>F3_12</tt> is defined to create 2 instruction
1123classes each time <tt>F3_12</tt> is invoked:
1124</p>
1125
Chris Lattner78975382008-11-11 19:30:41 +00001126<div class="doc_code">
1127<pre>multiclass F3_12 &lt;string OpcStr, bits&lt;6&gt; Op3Val, SDNode OpNode&gt; {
1128 def rr : F3_1 &lt;2, Op3Val,
1129 (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
Bill Wendling4a2bca82009-04-05 00:41:19 +00001130 !strconcat(OpcStr, " $b, $c, $dst"),
Chris Lattner78975382008-11-11 19:30:41 +00001131 [(set IntRegs:$dst, (OpNode IntRegs:$b, IntRegs:$c))]&gt;;
1132 def ri : F3_2 &lt;2, Op3Val,
1133 (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c),
Bill Wendling4a2bca82009-04-05 00:41:19 +00001134 !strconcat(OpcStr, " $b, $c, $dst"),
Chris Lattner78975382008-11-11 19:30:41 +00001135 [(set IntRegs:$dst, (OpNode IntRegs:$b, simm13:$c))]&gt;;
1136}
1137</pre>
1138</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001139
1140<p>
1141So when the <tt>defm</tt> directive is used for the <tt>XOR</tt>
1142and <tt>ADD</tt> instructions, as seen below, it creates four instruction
1143objects: <tt>XORrr</tt>, <tt>XORri</tt>, <tt>ADDrr</tt>, and <tt>ADDri</tt>.
1144</p>
1145
Chris Lattner78975382008-11-11 19:30:41 +00001146<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001147<pre>
1148defm XOR : F3_12&lt;"xor", 0b000011, xor&gt;;
1149defm ADD : F3_12&lt;"add", 0b000000, add&gt;;
Chris Lattner78975382008-11-11 19:30:41 +00001150</pre>
1151</div>
1152
Bill Wendling4a2bca82009-04-05 00:41:19 +00001153<p>
1154<tt>SparcInstrInfo.td</tt> also includes definitions for condition codes that
1155are referenced by branch instructions. The following definitions
1156in <tt>SparcInstrInfo.td</tt> indicate the bit location of the SPARC condition
1157code. For example, the 10<sup>th</sup> bit represents the 'greater than'
1158condition for integers, and the 22<sup>nd</sup> bit represents the 'greater
1159than' condition for floats.
1160</p>
Chris Lattner78975382008-11-11 19:30:41 +00001161
1162<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001163<pre>
1164def ICC_NE : ICC_VAL&lt; 9&gt;; // Not Equal
Chris Lattner78975382008-11-11 19:30:41 +00001165def ICC_E : ICC_VAL&lt; 1&gt;; // Equal
1166def ICC_G : ICC_VAL&lt;10&gt;; // Greater
1167...
1168def FCC_U : FCC_VAL&lt;23&gt;; // Unordered
1169def FCC_G : FCC_VAL&lt;22&gt;; // Greater
1170def FCC_UG : FCC_VAL&lt;21&gt;; // Unordered or Greater
1171...
1172</pre>
1173</div>
1174
Bill Wendling4a2bca82009-04-05 00:41:19 +00001175<p>
1176(Note that <tt>Sparc.h</tt> also defines enums that correspond to the same SPARC
1177condition codes. Care must be taken to ensure the values in <tt>Sparc.h</tt>
1178correspond to the values in <tt>SparcInstrInfo.td</tt>. I.e.,
1179<tt>SPCC::ICC_NE = 9</tt>, <tt>SPCC::FCC_U = 23</tt> and so on.)
1180</p>
1181
Chris Lattner78975382008-11-11 19:30:41 +00001182<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001183<h3>
Chris Lattner7a152732008-11-22 19:10:48 +00001184 <a name="operandMapping">Instruction Operand Mapping</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001185</h3>
Chris Lattner7a152732008-11-22 19:10:48 +00001186
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001187<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001188
1189<p>
1190The code generator backend maps instruction operands to fields in the
1191instruction. Operands are assigned to unbound fields in the instruction in the
1192order they are defined. Fields are bound when they are assigned a value. For
1193example, the Sparc target defines the <tt>XNORrr</tt> instruction as
1194a <tt>F3_1</tt> format instruction having three operands.
1195</p>
1196
1197<div class="doc_code">
1198<pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001199def XNORrr : F3_1&lt;2, 0b000111,
1200 (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
1201 "xnor $b, $c, $dst",
1202 [(set IntRegs:$dst, (not (xor IntRegs:$b, IntRegs:$c)))]&gt;;
Bill Wendling4a2bca82009-04-05 00:41:19 +00001203</pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001204</div>
1205
Bill Wendling4a2bca82009-04-05 00:41:19 +00001206<p>
1207The instruction templates in <tt>SparcInstrFormats.td</tt> show the base class
1208for <tt>F3_1</tt> is <tt>InstSP</tt>.
1209</p>
1210
1211<div class="doc_code">
1212<pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001213class InstSP&lt;dag outs, dag ins, string asmstr, list&lt;dag&gt; pattern&gt; : Instruction {
1214 field bits&lt;32&gt; Inst;
1215 let Namespace = "SP";
1216 bits&lt;2&gt; op;
1217 let Inst{31-30} = op;
1218 dag OutOperandList = outs;
1219 dag InOperandList = ins;
1220 let AsmString = asmstr;
1221 let Pattern = pattern;
1222}
Bill Wendling4a2bca82009-04-05 00:41:19 +00001223</pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001224</div>
1225
Bill Wendling4a2bca82009-04-05 00:41:19 +00001226<p><tt>InstSP</tt> leaves the <tt>op</tt> field unbound.</p>
1227
1228<div class="doc_code">
1229<pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001230class F3&lt;dag outs, dag ins, string asmstr, list&lt;dag&gt; pattern&gt;
1231 : InstSP&lt;outs, ins, asmstr, pattern&gt; {
1232 bits&lt;5&gt; rd;
1233 bits&lt;6&gt; op3;
1234 bits&lt;5&gt; rs1;
1235 let op{1} = 1; // Op = 2 or 3
1236 let Inst{29-25} = rd;
1237 let Inst{24-19} = op3;
1238 let Inst{18-14} = rs1;
1239}
Bill Wendling4a2bca82009-04-05 00:41:19 +00001240</pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001241</div>
1242
Bill Wendling4a2bca82009-04-05 00:41:19 +00001243<p>
1244<tt>F3</tt> binds the <tt>op</tt> field and defines the <tt>rd</tt>,
1245<tt>op3</tt>, and <tt>rs1</tt> fields. <tt>F3</tt> format instructions will
1246bind the operands <tt>rd</tt>, <tt>op3</tt>, and <tt>rs1</tt> fields.
1247</p>
1248
1249<div class="doc_code">
1250<pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001251class F3_1&lt;bits&lt;2&gt; opVal, bits&lt;6&gt; op3val, dag outs, dag ins,
1252 string asmstr, list&lt;dag&gt; pattern&gt; : F3&lt;outs, ins, asmstr, pattern&gt; {
1253 bits&lt;8&gt; asi = 0; // asi not currently used
1254 bits&lt;5&gt; rs2;
1255 let op = opVal;
1256 let op3 = op3val;
1257 let Inst{13} = 0; // i field = 0
1258 let Inst{12-5} = asi; // address space identifier
1259 let Inst{4-0} = rs2;
1260}
Bill Wendling4a2bca82009-04-05 00:41:19 +00001261</pre>
Chris Lattner7a152732008-11-22 19:10:48 +00001262</div>
1263
Bill Wendling4a2bca82009-04-05 00:41:19 +00001264<p>
1265<tt>F3_1</tt> binds the <tt>op3</tt> field and defines the <tt>rs2</tt>
1266fields. <tt>F3_1</tt> format instructions will bind the operands to the <tt>rd</tt>,
1267<tt>rs1</tt>, and <tt>rs2</tt> fields. This results in the <tt>XNORrr</tt>
1268instruction binding <tt>$dst</tt>, <tt>$b</tt>, and <tt>$c</tt> operands to
1269the <tt>rd</tt>, <tt>rs1</tt>, and <tt>rs2</tt> fields respectively.
1270</p>
Chris Lattner7a152732008-11-22 19:10:48 +00001271
Bill Wendling4a2bca82009-04-05 00:41:19 +00001272</div>
Chris Lattner7a152732008-11-22 19:10:48 +00001273
1274<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001275<h3>
Chris Lattner7d12b4b2008-11-11 19:36:31 +00001276 <a name="implementInstr">Implement a subclass of </a>
NAKAMURA Takumi31c18062011-04-09 02:13:48 +00001277 <a href="CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001278</h3>
Chris Lattner78975382008-11-11 19:30:41 +00001279
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001280<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001281
1282<p>
1283The final step is to hand code portions of <tt>XXXInstrInfo</tt>, which
1284implements the interface described in <tt>TargetInstrInfo.h</tt>. These
1285functions return <tt>0</tt> or a Boolean or they assert, unless
1286overridden. Here's a list of functions that are overridden for the SPARC
1287implementation in <tt>SparcInstrInfo.cpp</tt>:
1288</p>
1289
Chris Lattner78975382008-11-11 19:30:41 +00001290<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001291<li><tt>isLoadFromStackSlot</tt> &mdash; If the specified machine instruction is
1292 a direct load from a stack slot, return the register number of the
1293 destination and the <tt>FrameIndex</tt> of the stack slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001294
Bill Wendling4a2bca82009-04-05 00:41:19 +00001295<li><tt>isStoreToStackSlot</tt> &mdash; If the specified machine instruction is
1296 a direct store to a stack slot, return the register number of the
1297 destination and the <tt>FrameIndex</tt> of the stack slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001298
Jakob Stoklund Olesen744b3a52010-07-11 17:01:17 +00001299<li><tt>copyPhysReg</tt> &mdash; Copy values between a pair of physical
1300 registers.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001301
Bill Wendling4a2bca82009-04-05 00:41:19 +00001302<li><tt>storeRegToStackSlot</tt> &mdash; Store a register value to a stack
1303 slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001304
Bill Wendling4a2bca82009-04-05 00:41:19 +00001305<li><tt>loadRegFromStackSlot</tt> &mdash; Load a register value from a stack
1306 slot.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001307
Bill Wendling4a2bca82009-04-05 00:41:19 +00001308<li><tt>storeRegToAddr</tt> &mdash; Store a register value to memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001309
Bill Wendling4a2bca82009-04-05 00:41:19 +00001310<li><tt>loadRegFromAddr</tt> &mdash; Load a register value from memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001311
Bill Wendling4a2bca82009-04-05 00:41:19 +00001312<li><tt>foldMemoryOperand</tt> &mdash; Attempt to combine instructions of any
1313 load or store instruction for the specified operand(s).</li>
Chris Lattner78975382008-11-11 19:30:41 +00001314</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001315
Chris Lattner78975382008-11-11 19:30:41 +00001316</div>
1317
1318<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001319<h3>
Chris Lattner78975382008-11-11 19:30:41 +00001320 <a name="branchFolding">Branch Folding and If Conversion</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001321</h3>
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001322<div>
Chris Lattner78975382008-11-11 19:30:41 +00001323
Bill Wendling4a2bca82009-04-05 00:41:19 +00001324<p>
1325Performance can be improved by combining instructions or by eliminating
1326instructions that are never reached. The <tt>AnalyzeBranch</tt> method
1327in <tt>XXXInstrInfo</tt> may be implemented to examine conditional instructions
1328and remove unnecessary instructions. <tt>AnalyzeBranch</tt> looks at the end of
1329a machine basic block (MBB) for opportunities for improvement, such as branch
1330folding and if conversion. The <tt>BranchFolder</tt> and <tt>IfConverter</tt>
1331machine function passes (see the source files <tt>BranchFolding.cpp</tt> and
1332<tt>IfConversion.cpp</tt> in the <tt>lib/CodeGen</tt> directory) call
1333<tt>AnalyzeBranch</tt> to improve the control flow graph that represents the
1334instructions.
1335</p>
1336
1337<p>
1338Several implementations of <tt>AnalyzeBranch</tt> (for ARM, Alpha, and X86) can
1339be examined as models for your own <tt>AnalyzeBranch</tt> implementation. Since
1340SPARC does not implement a useful <tt>AnalyzeBranch</tt>, the ARM target
1341implementation is shown below.
1342</p>
Chris Lattner78975382008-11-11 19:30:41 +00001343
1344<p><tt>AnalyzeBranch</tt> returns a Boolean value and takes four parameters:</p>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001345
Chris Lattner78975382008-11-11 19:30:41 +00001346<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001347<li><tt>MachineBasicBlock &amp;MBB</tt> &mdash; The incoming block to be
1348 examined.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001349
Bill Wendling4a2bca82009-04-05 00:41:19 +00001350<li><tt>MachineBasicBlock *&amp;TBB</tt> &mdash; A destination block that is
1351 returned. For a conditional branch that evaluates to true, <tt>TBB</tt> is
1352 the destination.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001353
Bill Wendling4a2bca82009-04-05 00:41:19 +00001354<li><tt>MachineBasicBlock *&amp;FBB</tt> &mdash; For a conditional branch that
1355 evaluates to false, <tt>FBB</tt> is returned as the destination.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001356
Bill Wendling4a2bca82009-04-05 00:41:19 +00001357<li><tt>std::vector&lt;MachineOperand&gt; &amp;Cond</tt> &mdash; List of
1358 operands to evaluate a condition for a conditional branch.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001359</ul>
1360
Bill Wendling4a2bca82009-04-05 00:41:19 +00001361<p>
1362In the simplest case, if a block ends without a branch, then it falls through to
1363the successor block. No destination blocks are specified for either <tt>TBB</tt>
1364or <tt>FBB</tt>, so both parameters return <tt>NULL</tt>. The start of
1365the <tt>AnalyzeBranch</tt> (see code below for the ARM target) shows the
1366function parameters and the code for the simplest case.
1367</p>
Chris Lattner78975382008-11-11 19:30:41 +00001368
1369<div class="doc_code">
1370<pre>bool ARMInstrInfo::AnalyzeBranch(MachineBasicBlock &amp;MBB,
1371 MachineBasicBlock *&amp;TBB, MachineBasicBlock *&amp;FBB,
1372 std::vector&lt;MachineOperand&gt; &amp;Cond) const
1373{
1374 MachineBasicBlock::iterator I = MBB.end();
1375 if (I == MBB.begin() || !isUnpredicatedTerminator(--I))
1376 return false;
1377</pre>
1378</div>
1379
Bill Wendling4a2bca82009-04-05 00:41:19 +00001380<p>
1381If a block ends with a single unconditional branch instruction, then
1382<tt>AnalyzeBranch</tt> (shown below) should return the destination of that
1383branch in the <tt>TBB</tt> parameter.
1384</p>
Chris Lattner78975382008-11-11 19:30:41 +00001385
1386<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001387<pre>
1388 if (LastOpc == ARM::B || LastOpc == ARM::tB) {
1389 TBB = LastInst-&gt;getOperand(0).getMBB();
1390 return false;
1391 }
Chris Lattner78975382008-11-11 19:30:41 +00001392</pre>
1393</div>
1394
Bill Wendling4a2bca82009-04-05 00:41:19 +00001395<p>
1396If a block ends with two unconditional branches, then the second branch is never
1397reached. In that situation, as shown below, remove the last branch instruction
1398and return the penultimate branch in the <tt>TBB</tt> parameter.
1399</p>
Chris Lattner78975382008-11-11 19:30:41 +00001400
1401<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001402<pre>
1403 if ((SecondLastOpc == ARM::B || SecondLastOpc==ARM::tB) &amp;&amp;
Chris Lattner78975382008-11-11 19:30:41 +00001404 (LastOpc == ARM::B || LastOpc == ARM::tB)) {
1405 TBB = SecondLastInst-&gt;getOperand(0).getMBB();
1406 I = LastInst;
1407 I-&gt;eraseFromParent();
1408 return false;
1409 }
1410</pre>
1411</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001412
1413<p>
1414A block may end with a single conditional branch instruction that falls through
1415to successor block if the condition evaluates to false. In that case,
1416<tt>AnalyzeBranch</tt> (shown below) should return the destination of that
1417conditional branch in the <tt>TBB</tt> parameter and a list of operands in
1418the <tt>Cond</tt> parameter to evaluate the condition.
1419</p>
Chris Lattner78975382008-11-11 19:30:41 +00001420
1421<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001422<pre>
1423 if (LastOpc == ARM::Bcc || LastOpc == ARM::tBcc) {
1424 // Block ends with fall-through condbranch.
1425 TBB = LastInst-&gt;getOperand(0).getMBB();
1426 Cond.push_back(LastInst-&gt;getOperand(1));
1427 Cond.push_back(LastInst-&gt;getOperand(2));
1428 return false;
1429 }
Chris Lattner78975382008-11-11 19:30:41 +00001430</pre>
1431</div>
1432
Bill Wendling4a2bca82009-04-05 00:41:19 +00001433<p>
1434If a block ends with both a conditional branch and an ensuing unconditional
1435branch, then <tt>AnalyzeBranch</tt> (shown below) should return the conditional
1436branch destination (assuming it corresponds to a conditional evaluation of
1437'<tt>true</tt>') in the <tt>TBB</tt> parameter and the unconditional branch
1438destination in the <tt>FBB</tt> (corresponding to a conditional evaluation of
1439'<tt>false</tt>'). A list of operands to evaluate the condition should be
1440returned in the <tt>Cond</tt> parameter.
1441</p>
Chris Lattner78975382008-11-11 19:30:41 +00001442
1443<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001444<pre>
1445 unsigned SecondLastOpc = SecondLastInst-&gt;getOpcode();
1446
Chris Lattner78975382008-11-11 19:30:41 +00001447 if ((SecondLastOpc == ARM::Bcc &amp;&amp; LastOpc == ARM::B) ||
1448 (SecondLastOpc == ARM::tBcc &amp;&amp; LastOpc == ARM::tB)) {
1449 TBB = SecondLastInst-&gt;getOperand(0).getMBB();
1450 Cond.push_back(SecondLastInst-&gt;getOperand(1));
1451 Cond.push_back(SecondLastInst-&gt;getOperand(2));
1452 FBB = LastInst-&gt;getOperand(0).getMBB();
1453 return false;
1454 }
1455</pre>
1456</div>
1457
Bill Wendling4a2bca82009-04-05 00:41:19 +00001458<p>
1459For the last two cases (ending with a single conditional branch or ending with
1460one conditional and one unconditional branch), the operands returned in
1461the <tt>Cond</tt> parameter can be passed to methods of other instructions to
1462create new branches or perform other operations. An implementation
1463of <tt>AnalyzeBranch</tt> requires the helper methods <tt>RemoveBranch</tt>
1464and <tt>InsertBranch</tt> to manage subsequent operations.
1465</p>
Chris Lattner78975382008-11-11 19:30:41 +00001466
Bill Wendling4a2bca82009-04-05 00:41:19 +00001467<p>
1468<tt>AnalyzeBranch</tt> should return false indicating success in most circumstances.
Chris Lattner78975382008-11-11 19:30:41 +00001469<tt>AnalyzeBranch</tt> should only return true when the method is stumped about what to
1470do, for example, if a block has three terminating branches. <tt>AnalyzeBranch</tt> may
1471return true if it encounters a terminator it cannot handle, such as an indirect
Bill Wendling4a2bca82009-04-05 00:41:19 +00001472branch.
1473</p>
1474
Chris Lattner78975382008-11-11 19:30:41 +00001475</div>
1476
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001477</div>
1478
Chris Lattner78975382008-11-11 19:30:41 +00001479<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001480<h2>
Chris Lattner78975382008-11-11 19:30:41 +00001481 <a name="InstructionSelector">Instruction Selector</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001482</h2>
Misha Brukman8eb67192004-09-06 22:58:13 +00001483<!-- *********************************************************************** -->
1484
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001485<div>
Misha Brukman8eb67192004-09-06 22:58:13 +00001486
Bill Wendling4a2bca82009-04-05 00:41:19 +00001487<p>
1488LLVM uses a <tt>SelectionDAG</tt> to represent LLVM IR instructions, and nodes
1489of the <tt>SelectionDAG</tt> ideally represent native target
1490instructions. During code generation, instruction selection passes are performed
1491to convert non-native DAG instructions into native target-specific
1492instructions. The pass described in <tt>XXXISelDAGToDAG.cpp</tt> is used to
1493match patterns and perform DAG-to-DAG instruction selection. Optionally, a pass
1494may be defined (in <tt>XXXBranchSelector.cpp</tt>) to perform similar DAG-to-DAG
1495operations for branch instructions. Later, the code in
1496<tt>XXXISelLowering.cpp</tt> replaces or removes operations and data types not
1497supported natively (legalizes) in a <tt>SelectionDAG</tt>.
1498</p>
1499
1500<p>
1501TableGen generates code for instruction selection using the following target
1502description input files:
1503</p>
1504
Misha Brukman8eb67192004-09-06 22:58:13 +00001505<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001506<li><tt>XXXInstrInfo.td</tt> &mdash; Contains definitions of instructions in a
1507 target-specific instruction set, generates <tt>XXXGenDAGISel.inc</tt>, which
1508 is included in <tt>XXXISelDAGToDAG.cpp</tt>.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001509
Bill Wendling4a2bca82009-04-05 00:41:19 +00001510<li><tt>XXXCallingConv.td</tt> &mdash; Contains the calling and return value
1511 conventions for the target architecture, and it generates
1512 <tt>XXXGenCallingConv.inc</tt>, which is included in
1513 <tt>XXXISelLowering.cpp</tt>.</li>
Misha Brukman8eb67192004-09-06 22:58:13 +00001514</ul>
1515
Bill Wendling4a2bca82009-04-05 00:41:19 +00001516<p>
1517The implementation of an instruction selection pass must include a header that
1518declares the <tt>FunctionPass</tt> class or a subclass of <tt>FunctionPass</tt>. In
1519<tt>XXXTargetMachine.cpp</tt>, a Pass Manager (PM) should add each instruction
1520selection pass into the queue of passes to run.
1521</p>
Chris Lattner78975382008-11-11 19:30:41 +00001522
Bill Wendling4a2bca82009-04-05 00:41:19 +00001523<p>
1524The LLVM static compiler (<tt>llc</tt>) is an excellent tool for visualizing the
1525contents of DAGs. To display the <tt>SelectionDAG</tt> before or after specific
1526processing phases, use the command line options for <tt>llc</tt>, described
NAKAMURA Takumi31c18062011-04-09 02:13:48 +00001527at <a href="CodeGenerator.html#selectiondag_process">
Chris Lattner78975382008-11-11 19:30:41 +00001528SelectionDAG Instruction Selection Process</a>.
1529</p>
1530
Bill Wendling4a2bca82009-04-05 00:41:19 +00001531<p>
1532To describe instruction selector behavior, you should add patterns for lowering
1533LLVM code into a <tt>SelectionDAG</tt> as the last parameter of the instruction
1534definitions in <tt>XXXInstrInfo.td</tt>. For example, in
1535<tt>SparcInstrInfo.td</tt>, this entry defines a register store operation, and
1536the last parameter describes a pattern with the store DAG operator.
1537</p>
Chris Lattner78975382008-11-11 19:30:41 +00001538
1539<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001540<pre>
1541def STrr : F3_1&lt; 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
1542 "st $src, [$addr]", [(store IntRegs:$src, ADDRrr:$addr)]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +00001543</pre>
1544</div>
1545
Bill Wendling4a2bca82009-04-05 00:41:19 +00001546<p>
1547<tt>ADDRrr</tt> is a memory mode that is also defined in
1548<tt>SparcInstrInfo.td</tt>:
1549</p>
Chris Lattner78975382008-11-11 19:30:41 +00001550
1551<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001552<pre>
1553def ADDRrr : ComplexPattern&lt;i32, 2, "SelectADDRrr", [], []&gt;;
Chris Lattner78975382008-11-11 19:30:41 +00001554</pre>
1555</div>
1556
Bill Wendling4a2bca82009-04-05 00:41:19 +00001557<p>
1558The definition of <tt>ADDRrr</tt> refers to <tt>SelectADDRrr</tt>, which is a
1559function defined in an implementation of the Instructor Selector (such
1560as <tt>SparcISelDAGToDAG.cpp</tt>).
1561</p>
Chris Lattner78975382008-11-11 19:30:41 +00001562
Bill Wendling4a2bca82009-04-05 00:41:19 +00001563<p>
1564In <tt>lib/Target/TargetSelectionDAG.td</tt>, the DAG operator for store is
1565defined below:
1566</p>
Chris Lattner78975382008-11-11 19:30:41 +00001567
1568<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001569<pre>
1570def store : PatFrag&lt;(ops node:$val, node:$ptr),
Chris Lattner78975382008-11-11 19:30:41 +00001571 (st node:$val, node:$ptr), [{
1572 if (StoreSDNode *ST = dyn_cast&lt;StoreSDNode&gt;(N))
1573 return !ST-&gt;isTruncatingStore() &amp;&amp;
1574 ST-&gt;getAddressingMode() == ISD::UNINDEXED;
1575 return false;
1576}]&gt;;
1577</pre>
1578</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001579
1580<p>
1581<tt>XXXInstrInfo.td</tt> also generates (in <tt>XXXGenDAGISel.inc</tt>) the
1582<tt>SelectCode</tt> method that is used to call the appropriate processing
1583method for an instruction. In this example, <tt>SelectCode</tt>
1584calls <tt>Select_ISD_STORE</tt> for the <tt>ISD::STORE</tt> opcode.
1585</p>
Chris Lattner78975382008-11-11 19:30:41 +00001586
1587<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001588<pre>
1589SDNode *SelectCode(SDValue N) {
Chris Lattner78975382008-11-11 19:30:41 +00001590 ...
Dan Gohman50ef90d2009-01-28 21:36:46 +00001591 MVT::ValueType NVT = N.getNode()-&gt;getValueType(0);
Chris Lattner78975382008-11-11 19:30:41 +00001592 switch (N.getOpcode()) {
1593 case ISD::STORE: {
1594 switch (NVT) {
1595 default:
1596 return Select_ISD_STORE(N);
1597 break;
1598 }
1599 break;
1600 }
1601 ...
1602</pre>
1603</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001604
1605<p>
1606The pattern for <tt>STrr</tt> is matched, so elsewhere in
1607<tt>XXXGenDAGISel.inc</tt>, code for <tt>STrr</tt> is created for
1608<tt>Select_ISD_STORE</tt>. The <tt>Emit_22</tt> method is also generated
1609in <tt>XXXGenDAGISel.inc</tt> to complete the processing of this
1610instruction.
1611</p>
Chris Lattner78975382008-11-11 19:30:41 +00001612
1613<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001614<pre>
1615SDNode *Select_ISD_STORE(const SDValue &amp;N) {
Dan Gohman50ef90d2009-01-28 21:36:46 +00001616 SDValue Chain = N.getOperand(0);
1617 if (Predicate_store(N.getNode())) {
1618 SDValue N1 = N.getOperand(1);
1619 SDValue N2 = N.getOperand(2);
1620 SDValue CPTmp0;
1621 SDValue CPTmp1;
Bill Wendling4a2bca82009-04-05 00:41:19 +00001622
Chris Lattner78975382008-11-11 19:30:41 +00001623 // Pattern: (st:void IntRegs:i32:$src,
1624 // ADDRrr:i32:$addr)&lt;&lt;P:Predicate_store&gt;&gt;
1625 // Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src)
1626 // Pattern complexity = 13 cost = 1 size = 0
1627 if (SelectADDRrr(N, N2, CPTmp0, CPTmp1) &amp;&amp;
Dan Gohman50ef90d2009-01-28 21:36:46 +00001628 N1.getNode()-&gt;getValueType(0) == MVT::i32 &amp;&amp;
1629 N2.getNode()-&gt;getValueType(0) == MVT::i32) {
Chris Lattner78975382008-11-11 19:30:41 +00001630 return Emit_22(N, SP::STrr, CPTmp0, CPTmp1);
1631 }
1632...
1633</pre>
1634</div>
1635
1636<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001637<h3>
Chris Lattner78975382008-11-11 19:30:41 +00001638 <a name="LegalizePhase">The SelectionDAG Legalize Phase</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001639</h3>
Chris Lattner78975382008-11-11 19:30:41 +00001640
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001641<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001642
1643<p>
1644The Legalize phase converts a DAG to use types and operations that are natively
1645supported by the target. For natively unsupported types and operations, you need
1646to add code to the target-specific XXXTargetLowering implementation to convert
1647unsupported types and operations to supported ones.
1648</p>
1649
1650<p>
1651In the constructor for the <tt>XXXTargetLowering</tt> class, first use the
1652<tt>addRegisterClass</tt> method to specify which types are supports and which
1653register classes are associated with them. The code for the register classes are
1654generated by TableGen from <tt>XXXRegisterInfo.td</tt> and placed
1655in <tt>XXXGenRegisterInfo.h.inc</tt>. For example, the implementation of the
1656constructor for the SparcTargetLowering class (in
1657<tt>SparcISelLowering.cpp</tt>) starts with the following code:
1658</p>
Chris Lattner78975382008-11-11 19:30:41 +00001659
1660<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001661<pre>
1662addRegisterClass(MVT::i32, SP::IntRegsRegisterClass);
Chris Lattner78975382008-11-11 19:30:41 +00001663addRegisterClass(MVT::f32, SP::FPRegsRegisterClass);
1664addRegisterClass(MVT::f64, SP::DFPRegsRegisterClass);
1665</pre>
1666</div>
1667
Bill Wendling4a2bca82009-04-05 00:41:19 +00001668<p>
1669You should examine the node types in the <tt>ISD</tt> namespace
1670(<tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>) and determine which
1671operations the target natively supports. For operations that do <b>not</b> have
1672native support, add a callback to the constructor for the XXXTargetLowering
1673class, so the instruction selection process knows what to do. The TargetLowering
1674class callback methods (declared in <tt>llvm/Target/TargetLowering.h</tt>) are:
1675</p>
1676
Chris Lattner78975382008-11-11 19:30:41 +00001677<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001678<li><tt>setOperationAction</tt> &mdash; General operation.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001679
Bill Wendling4a2bca82009-04-05 00:41:19 +00001680<li><tt>setLoadExtAction</tt> &mdash; Load with extension.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001681
Bill Wendling4a2bca82009-04-05 00:41:19 +00001682<li><tt>setTruncStoreAction</tt> &mdash; Truncating store.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001683
Bill Wendling4a2bca82009-04-05 00:41:19 +00001684<li><tt>setIndexedLoadAction</tt> &mdash; Indexed load.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001685
Bill Wendling4a2bca82009-04-05 00:41:19 +00001686<li><tt>setIndexedStoreAction</tt> &mdash; Indexed store.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001687
Bill Wendling4a2bca82009-04-05 00:41:19 +00001688<li><tt>setConvertAction</tt> &mdash; Type conversion.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001689
Bill Wendling4a2bca82009-04-05 00:41:19 +00001690<li><tt>setCondCodeAction</tt> &mdash; Support for a given condition code.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001691</ul>
1692
Bill Wendling4a2bca82009-04-05 00:41:19 +00001693<p>
1694Note: on older releases, <tt>setLoadXAction</tt> is used instead
1695of <tt>setLoadExtAction</tt>. Also, on older releases,
1696<tt>setCondCodeAction</tt> may not be supported. Examine your release
1697to see what methods are specifically supported.
1698</p>
Chris Lattner78975382008-11-11 19:30:41 +00001699
Bill Wendling4a2bca82009-04-05 00:41:19 +00001700<p>
1701These callbacks are used to determine that an operation does or does not work
1702with a specified type (or types). And in all cases, the third parameter is
1703a <tt>LegalAction</tt> type enum value: <tt>Promote</tt>, <tt>Expand</tt>,
Chris Lattner78975382008-11-11 19:30:41 +00001704<tt>Custom</tt>, or <tt>Legal</tt>. <tt>SparcISelLowering.cpp</tt>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001705contains examples of all four <tt>LegalAction</tt> values.
1706</p>
1707
Chris Lattner78975382008-11-11 19:30:41 +00001708<!-- _______________________________________________________________________ -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001709<h4>
Chris Lattner78975382008-11-11 19:30:41 +00001710 <a name="promote">Promote</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001711</h4>
Chris Lattner78975382008-11-11 19:30:41 +00001712
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001713<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001714
1715<p>
1716For an operation without native support for a given type, the specified type may
1717be promoted to a larger type that is supported. For example, SPARC does not
1718support a sign-extending load for Boolean values (<tt>i1</tt> type), so
1719in <tt>SparcISelLowering.cpp</tt> the third parameter below, <tt>Promote</tt>,
1720changes <tt>i1</tt> type values to a large type before loading.
1721</p>
Chris Lattner78975382008-11-11 19:30:41 +00001722
1723<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001724<pre>
1725setLoadExtAction(ISD::SEXTLOAD, MVT::i1, Promote);
Chris Lattner78975382008-11-11 19:30:41 +00001726</pre>
1727</div>
1728
Bill Wendling4a2bca82009-04-05 00:41:19 +00001729</div>
1730
Chris Lattner78975382008-11-11 19:30:41 +00001731<!-- _______________________________________________________________________ -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001732<h4>
Chris Lattner78975382008-11-11 19:30:41 +00001733 <a name="expand">Expand</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001734</h4>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001735
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001736<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001737
1738<p>
1739For a type without native support, a value may need to be broken down further,
1740rather than promoted. For an operation without native support, a combination of
1741other operations may be used to similar effect. In SPARC, the floating-point
1742sine and cosine trig operations are supported by expansion to other operations,
1743as indicated by the third parameter, <tt>Expand</tt>, to
1744<tt>setOperationAction</tt>:
1745</p>
Chris Lattner78975382008-11-11 19:30:41 +00001746
1747<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001748<pre>
1749setOperationAction(ISD::FSIN, MVT::f32, Expand);
Chris Lattner78975382008-11-11 19:30:41 +00001750setOperationAction(ISD::FCOS, MVT::f32, Expand);
1751</pre>
1752</div>
1753
Bill Wendling4a2bca82009-04-05 00:41:19 +00001754</div>
1755
Chris Lattner78975382008-11-11 19:30:41 +00001756<!-- _______________________________________________________________________ -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001757<h4>
Chris Lattner78975382008-11-11 19:30:41 +00001758 <a name="custom">Custom</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001759</h4>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001760
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001761<div>
Chris Lattner78975382008-11-11 19:30:41 +00001762
Bill Wendling4a2bca82009-04-05 00:41:19 +00001763<p>
1764For some operations, simple type promotion or operation expansion may be
1765insufficient. In some cases, a special intrinsic function must be implemented.
1766</p>
Chris Lattner78975382008-11-11 19:30:41 +00001767
Bill Wendling4a2bca82009-04-05 00:41:19 +00001768<p>
1769For example, a constant value may require special treatment, or an operation may
1770require spilling and restoring registers in the stack and working with register
1771allocators.
1772</p>
1773
1774<p>
1775As seen in <tt>SparcISelLowering.cpp</tt> code below, to perform a type
Chris Lattner78975382008-11-11 19:30:41 +00001776conversion from a floating point value to a signed integer, first the
Bill Wendling4a2bca82009-04-05 00:41:19 +00001777<tt>setOperationAction</tt> should be called with <tt>Custom</tt> as the third
1778parameter:
1779</p>
Chris Lattner78975382008-11-11 19:30:41 +00001780
1781<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001782<pre>
1783setOperationAction(ISD::FP_TO_SINT, MVT::i32, Custom);
Chris Lattner78975382008-11-11 19:30:41 +00001784</pre>
1785</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001786
1787<p>
1788In the <tt>LowerOperation</tt> method, for each <tt>Custom</tt> operation, a
1789case statement should be added to indicate what function to call. In the
1790following code, an <tt>FP_TO_SINT</tt> opcode will call
1791the <tt>LowerFP_TO_SINT</tt> method:
1792</p>
Chris Lattner78975382008-11-11 19:30:41 +00001793
1794<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001795<pre>
1796SDValue SparcTargetLowering::LowerOperation(SDValue Op, SelectionDAG &amp;DAG) {
Chris Lattner78975382008-11-11 19:30:41 +00001797 switch (Op.getOpcode()) {
1798 case ISD::FP_TO_SINT: return LowerFP_TO_SINT(Op, DAG);
1799 ...
1800 }
1801}
1802</pre>
Chris Lattner78975382008-11-11 19:30:41 +00001803</div>
1804
Bill Wendling4a2bca82009-04-05 00:41:19 +00001805<p>
1806Finally, the <tt>LowerFP_TO_SINT</tt> method is implemented, using an FP
1807register to convert the floating-point value to an integer.
1808</p>
1809
Chris Lattner78975382008-11-11 19:30:41 +00001810<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001811<pre>
1812static SDValue LowerFP_TO_SINT(SDValue Op, SelectionDAG &amp;DAG) {
1813 assert(Op.getValueType() == MVT::i32);
Chris Lattner78975382008-11-11 19:30:41 +00001814 Op = DAG.getNode(SPISD::FTOI, MVT::f32, Op.getOperand(0));
Wesley Peckbf17cfa2010-11-23 03:31:01 +00001815 return DAG.getNode(ISD::BITCAST, MVT::i32, Op);
Chris Lattner78975382008-11-11 19:30:41 +00001816}
1817</pre>
1818</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001819
1820</div>
1821
Chris Lattner78975382008-11-11 19:30:41 +00001822<!-- _______________________________________________________________________ -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001823<h4>
Chris Lattner78975382008-11-11 19:30:41 +00001824 <a name="legal">Legal</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001825</h4>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001826
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001827<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001828
1829<p>
1830The <tt>Legal</tt> LegalizeAction enum value simply indicates that an
1831operation <b>is</b> natively supported. <tt>Legal</tt> represents the default
1832condition, so it is rarely used. In <tt>SparcISelLowering.cpp</tt>, the action
1833for <tt>CTPOP</tt> (an operation to count the bits set in an integer) is
1834natively supported only for SPARC v9. The following code enables
1835the <tt>Expand</tt> conversion technique for non-v9 SPARC implementations.
1836</p>
Chris Lattner78975382008-11-11 19:30:41 +00001837
1838<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001839<pre>
1840setOperationAction(ISD::CTPOP, MVT::i32, Expand);
Chris Lattner78975382008-11-11 19:30:41 +00001841...
1842if (TM.getSubtarget&lt;SparcSubtarget&gt;().isV9())
1843 setOperationAction(ISD::CTPOP, MVT::i32, Legal);
1844 case ISD::SETULT: return SPCC::ICC_CS;
1845 case ISD::SETULE: return SPCC::ICC_LEU;
1846 case ISD::SETUGT: return SPCC::ICC_GU;
1847 case ISD::SETUGE: return SPCC::ICC_CC;
1848 }
1849}
1850</pre>
1851</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001852
1853</div>
1854
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001855</div>
1856
Chris Lattner78975382008-11-11 19:30:41 +00001857<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001858<h3>
Chris Lattner78975382008-11-11 19:30:41 +00001859 <a name="callingConventions">Calling Conventions</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00001860</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001861
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00001862<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001863
1864<p>
1865To support target-specific calling conventions, <tt>XXXGenCallingConv.td</tt>
Chris Lattner78975382008-11-11 19:30:41 +00001866uses interfaces (such as CCIfType and CCAssignToReg) that are defined in
Bill Wendling4a2bca82009-04-05 00:41:19 +00001867<tt>lib/Target/TargetCallingConv.td</tt>. TableGen can take the target
1868descriptor file <tt>XXXGenCallingConv.td</tt> and generate the header
1869file <tt>XXXGenCallingConv.inc</tt>, which is typically included
1870in <tt>XXXISelLowering.cpp</tt>. You can use the interfaces in
1871<tt>TargetCallingConv.td</tt> to specify:
1872</p>
1873
Chris Lattner78975382008-11-11 19:30:41 +00001874<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001875<li>The order of parameter allocation.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001876
Bill Wendling4a2bca82009-04-05 00:41:19 +00001877<li>Where parameters and return values are placed (that is, on the stack or in
1878 registers).</li>
Chris Lattner78975382008-11-11 19:30:41 +00001879
Bill Wendling4a2bca82009-04-05 00:41:19 +00001880<li>Which registers may be used.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001881
Bill Wendling4a2bca82009-04-05 00:41:19 +00001882<li>Whether the caller or callee unwinds the stack.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001883</ul>
1884
Bill Wendling4a2bca82009-04-05 00:41:19 +00001885<p>
1886The following example demonstrates the use of the <tt>CCIfType</tt> and
1887<tt>CCAssignToReg</tt> interfaces. If the <tt>CCIfType</tt> predicate is true
1888(that is, if the current argument is of type <tt>f32</tt> or <tt>f64</tt>), then
1889the action is performed. In this case, the <tt>CCAssignToReg</tt> action assigns
1890the argument value to the first available register: either <tt>R0</tt>
1891or <tt>R1</tt>.
1892</p>
Chris Lattner78975382008-11-11 19:30:41 +00001893
1894<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001895<pre>
1896CCIfType&lt;[f32,f64], CCAssignToReg&lt;[R0, R1]&gt;&gt;
1897</pre>
1898</div>
1899
1900<p>
1901<tt>SparcCallingConv.td</tt> contains definitions for a target-specific
1902return-value calling convention (RetCC_Sparc32) and a basic 32-bit C calling
1903convention (<tt>CC_Sparc32</tt>). The definition of <tt>RetCC_Sparc32</tt>
1904(shown below) indicates which registers are used for specified scalar return
1905types. A single-precision float is returned to register <tt>F0</tt>, and a
1906double-precision float goes to register <tt>D0</tt>. A 32-bit integer is
1907returned in register <tt>I0</tt> or <tt>I1</tt>.
1908</p>
1909
1910<div class="doc_code">
1911<pre>
1912def RetCC_Sparc32 : CallingConv&lt;[
Chris Lattner78975382008-11-11 19:30:41 +00001913 CCIfType&lt;[i32], CCAssignToReg&lt;[I0, I1]&gt;&gt;,
1914 CCIfType&lt;[f32], CCAssignToReg&lt;[F0]&gt;&gt;,
1915 CCIfType&lt;[f64], CCAssignToReg&lt;[D0]&gt;&gt;
1916]&gt;;
1917</pre>
1918</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001919
1920<p>
1921The definition of <tt>CC_Sparc32</tt> in <tt>SparcCallingConv.td</tt> introduces
1922<tt>CCAssignToStack</tt>, which assigns the value to a stack slot with the
1923specified size and alignment. In the example below, the first parameter, 4,
1924indicates the size of the slot, and the second parameter, also 4, indicates the
1925stack alignment along 4-byte units. (Special cases: if size is zero, then the
1926ABI size is used; if alignment is zero, then the ABI alignment is used.)
1927</p>
Chris Lattner78975382008-11-11 19:30:41 +00001928
1929<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001930<pre>
1931def CC_Sparc32 : CallingConv&lt;[
Chris Lattner78975382008-11-11 19:30:41 +00001932 // All arguments get passed in integer registers if there is space.
1933 CCIfType&lt;[i32, f32, f64], CCAssignToReg&lt;[I0, I1, I2, I3, I4, I5]&gt;&gt;,
1934 CCAssignToStack&lt;4, 4&gt;
1935]&gt;;
1936</pre>
1937</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001938
1939<p>
1940<tt>CCDelegateTo</tt> is another commonly used interface, which tries to find a
1941specified sub-calling convention, and, if a match is found, it is invoked. In
1942the following example (in <tt>X86CallingConv.td</tt>), the definition of
1943<tt>RetCC_X86_32_C</tt> ends with <tt>CCDelegateTo</tt>. After the current value
1944is assigned to the register <tt>ST0</tt> or <tt>ST1</tt>,
1945the <tt>RetCC_X86Common</tt> is invoked.
1946</p>
Chris Lattner78975382008-11-11 19:30:41 +00001947
1948<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001949<pre>
1950def RetCC_X86_32_C : CallingConv&lt;[
Chris Lattner78975382008-11-11 19:30:41 +00001951 CCIfType&lt;[f32], CCAssignToReg&lt;[ST0, ST1]&gt;&gt;,
1952 CCIfType&lt;[f64], CCAssignToReg&lt;[ST0, ST1]&gt;&gt;,
1953 CCDelegateTo&lt;RetCC_X86Common&gt;
1954]&gt;;
1955</pre>
1956</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001957
1958<p>
1959<tt>CCIfCC</tt> is an interface that attempts to match the given name to the
1960current calling convention. If the name identifies the current calling
Chris Lattner78975382008-11-11 19:30:41 +00001961convention, then a specified action is invoked. In the following example (in
Bill Wendling4a2bca82009-04-05 00:41:19 +00001962<tt>X86CallingConv.td</tt>), if the <tt>Fast</tt> calling convention is in use,
1963then <tt>RetCC_X86_32_Fast</tt> is invoked. If the <tt>SSECall</tt> calling
1964convention is in use, then <tt>RetCC_X86_32_SSE</tt> is invoked.
1965</p>
Chris Lattner78975382008-11-11 19:30:41 +00001966
1967<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00001968<pre>
1969def RetCC_X86_32 : CallingConv&lt;[
1970 CCIfCC&lt;"CallingConv::Fast", CCDelegateTo&lt;RetCC_X86_32_Fast&gt;&gt;,
1971 CCIfCC&lt;"CallingConv::X86_SSECall", CCDelegateTo&lt;RetCC_X86_32_SSE&gt;&gt;,
Chris Lattner78975382008-11-11 19:30:41 +00001972 CCDelegateTo&lt;RetCC_X86_32_C&gt;
1973]&gt;;
1974</pre>
1975</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001976
Chris Lattner78975382008-11-11 19:30:41 +00001977<p>Other calling convention interfaces include:</p>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001978
Chris Lattner78975382008-11-11 19:30:41 +00001979<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00001980<li><tt>CCIf &lt;predicate, action&gt;</tt> &mdash; If the predicate matches,
1981 apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001982
Bill Wendling4a2bca82009-04-05 00:41:19 +00001983<li><tt>CCIfInReg &lt;action&gt;</tt> &mdash; If the argument is marked with the
1984 '<tt>inreg</tt>' attribute, then apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001985
Bill Wendling4a2bca82009-04-05 00:41:19 +00001986<li><tt>CCIfNest &lt;action&gt;</tt> &mdash; Inf the argument is marked with the
1987 '<tt>nest</tt>' attribute, then apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001988
Bill Wendling4a2bca82009-04-05 00:41:19 +00001989<li><tt>CCIfNotVarArg &lt;action&gt;</tt> &mdash; If the current function does
1990 not take a variable number of arguments, apply the action.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001991
Bill Wendling4a2bca82009-04-05 00:41:19 +00001992<li><tt>CCAssignToRegWithShadow &lt;registerList, shadowList&gt;</tt> &mdash;
1993 similar to <tt>CCAssignToReg</tt>, but with a shadow list of registers.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001994
Bill Wendling4a2bca82009-04-05 00:41:19 +00001995<li><tt>CCPassByVal &lt;size, align&gt;</tt> &mdash; Assign value to a stack
1996 slot with the minimum specified size and alignment.</li>
Chris Lattner78975382008-11-11 19:30:41 +00001997
Bill Wendling4a2bca82009-04-05 00:41:19 +00001998<li><tt>CCPromoteToType &lt;type&gt;</tt> &mdash; Promote the current value to
1999 the specified type.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002000
Bill Wendling4a2bca82009-04-05 00:41:19 +00002001<li><tt>CallingConv &lt;[actions]&gt;</tt> &mdash; Define each calling
2002 convention that is supported.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002003</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002004
Chris Lattner78975382008-11-11 19:30:41 +00002005</div>
2006
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002007</div>
2008
Chris Lattner78975382008-11-11 19:30:41 +00002009<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002010<h2>
Chris Lattner78975382008-11-11 19:30:41 +00002011 <a name="assemblyPrinter">Assembly Printer</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002012</h2>
Chris Lattner78975382008-11-11 19:30:41 +00002013<!-- *********************************************************************** -->
2014
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002015<div>
Chris Lattner78975382008-11-11 19:30:41 +00002016
Bill Wendling4a2bca82009-04-05 00:41:19 +00002017<p>
2018During the code emission stage, the code generator may utilize an LLVM pass to
2019produce assembly output. To do this, you want to implement the code for a
2020printer that converts LLVM IR to a GAS-format assembly language for your target
2021machine, using the following steps:
2022</p>
2023
2024<ul>
2025<li>Define all the assembly strings for your target, adding them to the
2026 instructions defined in the <tt>XXXInstrInfo.td</tt> file.
2027 (See <a href="#InstructionSet">Instruction Set</a>.) TableGen will produce
2028 an output file (<tt>XXXGenAsmWriter.inc</tt>) with an implementation of
2029 the <tt>printInstruction</tt> method for the XXXAsmPrinter class.</li>
2030
2031<li>Write <tt>XXXTargetAsmInfo.h</tt>, which contains the bare-bones declaration
2032 of the <tt>XXXTargetAsmInfo</tt> class (a subclass
2033 of <tt>TargetAsmInfo</tt>).</li>
Chris Lattner78975382008-11-11 19:30:41 +00002034
2035<li>Write <tt>XXXTargetAsmInfo.cpp</tt>, which contains target-specific values
Bill Wendling4a2bca82009-04-05 00:41:19 +00002036 for <tt>TargetAsmInfo</tt> properties and sometimes new implementations for
2037 methods.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002038
Bill Wendling4a2bca82009-04-05 00:41:19 +00002039<li>Write <tt>XXXAsmPrinter.cpp</tt>, which implements the <tt>AsmPrinter</tt>
2040 class that performs the LLVM-to-assembly conversion.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002041</ul>
2042
Bill Wendling4a2bca82009-04-05 00:41:19 +00002043<p>
2044The code in <tt>XXXTargetAsmInfo.h</tt> is usually a trivial declaration of the
2045<tt>XXXTargetAsmInfo</tt> class for use in <tt>XXXTargetAsmInfo.cpp</tt>.
2046Similarly, <tt>XXXTargetAsmInfo.cpp</tt> usually has a few declarations of
2047<tt>XXXTargetAsmInfo</tt> replacement values that override the default values
2048in <tt>TargetAsmInfo.cpp</tt>. For example in <tt>SparcTargetAsmInfo.cpp</tt>:
2049</p>
Chris Lattner78975382008-11-11 19:30:41 +00002050
2051<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002052<pre>
2053SparcTargetAsmInfo::SparcTargetAsmInfo(const SparcTargetMachine &amp;TM) {
2054 Data16bitsDirective = "\t.half\t";
2055 Data32bitsDirective = "\t.word\t";
Chris Lattner78975382008-11-11 19:30:41 +00002056 Data64bitsDirective = 0; // .xword is only supported by V9.
Bill Wendling4a2bca82009-04-05 00:41:19 +00002057 ZeroDirective = "\t.skip\t";
2058 CommentString = "!";
2059 ConstantPoolSection = "\t.section \".rodata\",#alloc\n";
Chris Lattner78975382008-11-11 19:30:41 +00002060}
2061</pre>
2062</div>
Chris Lattner78975382008-11-11 19:30:41 +00002063
Bill Wendling4a2bca82009-04-05 00:41:19 +00002064<p>
2065The X86 assembly printer implementation (<tt>X86TargetAsmInfo</tt>) is an
Chris Lattnerb6d66742009-08-02 04:02:52 +00002066example where the target specific <tt>TargetAsmInfo</tt> class uses an
2067overridden methods: <tt>ExpandInlineAsm</tt>.
Bill Wendling4a2bca82009-04-05 00:41:19 +00002068</p>
2069
2070<p>
2071A target-specific implementation of AsmPrinter is written in
2072<tt>XXXAsmPrinter.cpp</tt>, which implements the <tt>AsmPrinter</tt> class that
2073converts the LLVM to printable assembly. The implementation must include the
2074following headers that have declarations for the <tt>AsmPrinter</tt> and
2075<tt>MachineFunctionPass</tt> classes. The <tt>MachineFunctionPass</tt> is a
2076subclass of <tt>FunctionPass</tt>.
2077</p>
Chris Lattner78975382008-11-11 19:30:41 +00002078
2079<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002080<pre>
2081#include "llvm/CodeGen/AsmPrinter.h"
2082#include "llvm/CodeGen/MachineFunctionPass.h"
Chris Lattner78975382008-11-11 19:30:41 +00002083</pre>
2084</div>
2085
Bill Wendling4a2bca82009-04-05 00:41:19 +00002086<p>
2087As a <tt>FunctionPass</tt>, <tt>AsmPrinter</tt> first
2088calls <tt>doInitialization</tt> to set up the <tt>AsmPrinter</tt>. In
2089<tt>SparcAsmPrinter</tt>, a <tt>Mangler</tt> object is instantiated to process
2090variable names.
2091</p>
Chris Lattner78975382008-11-11 19:30:41 +00002092
Bill Wendling4a2bca82009-04-05 00:41:19 +00002093<p>
2094In <tt>XXXAsmPrinter.cpp</tt>, the <tt>runOnMachineFunction</tt> method
2095(declared in <tt>MachineFunctionPass</tt>) must be implemented
2096for <tt>XXXAsmPrinter</tt>. In <tt>MachineFunctionPass</tt>,
2097the <tt>runOnFunction</tt> method invokes <tt>runOnMachineFunction</tt>.
2098Target-specific implementations of <tt>runOnMachineFunction</tt> differ, but
2099generally do the following to process each machine function:
2100</p>
2101
Chris Lattner78975382008-11-11 19:30:41 +00002102<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002103<li>Call <tt>SetupMachineFunction</tt> to perform initialization.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002104
Bill Wendling4a2bca82009-04-05 00:41:19 +00002105<li>Call <tt>EmitConstantPool</tt> to print out (to the output stream) constants
2106 which have been spilled to memory.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002107
Bill Wendling4a2bca82009-04-05 00:41:19 +00002108<li>Call <tt>EmitJumpTableInfo</tt> to print out jump tables used by the current
2109 function.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002110
Bill Wendling4a2bca82009-04-05 00:41:19 +00002111<li>Print out the label for the current function.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002112
Bill Wendling4a2bca82009-04-05 00:41:19 +00002113<li>Print out the code for the function, including basic block labels and the
2114 assembly for the instruction (using <tt>printInstruction</tt>)</li>
Chris Lattner78975382008-11-11 19:30:41 +00002115</ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002116
2117<p>
2118The <tt>XXXAsmPrinter</tt> implementation must also include the code generated
2119by TableGen that is output in the <tt>XXXGenAsmWriter.inc</tt> file. The code
2120in <tt>XXXGenAsmWriter.inc</tt> contains an implementation of the
2121<tt>printInstruction</tt> method that may call these methods:
2122</p>
2123
Chris Lattner78975382008-11-11 19:30:41 +00002124<ul>
2125<li><tt>printOperand</tt></li>
2126
2127<li><tt>printMemOperand</tt></li>
2128
2129<li><tt>printCCOperand (for conditional statements)</tt></li>
2130
2131<li><tt>printDataDirective</tt></li>
2132
2133<li><tt>printDeclare</tt></li>
2134
2135<li><tt>printImplicitDef</tt></li>
2136
2137<li><tt>printInlineAsm</tt></li>
Chris Lattner78975382008-11-11 19:30:41 +00002138</ul>
2139
Bill Wendling4a2bca82009-04-05 00:41:19 +00002140<p>
2141The implementations of <tt>printDeclare</tt>, <tt>printImplicitDef</tt>,
2142<tt>printInlineAsm</tt>, and <tt>printLabel</tt> in <tt>AsmPrinter.cpp</tt> are
2143generally adequate for printing assembly and do not need to be
Chris Lattnerdeb8c152009-09-12 22:57:37 +00002144overridden.
Bill Wendling4a2bca82009-04-05 00:41:19 +00002145</p>
Chris Lattner78975382008-11-11 19:30:41 +00002146
Bill Wendling4a2bca82009-04-05 00:41:19 +00002147<p>
2148The <tt>printOperand</tt> method is implemented with a long switch/case
Chris Lattner78975382008-11-11 19:30:41 +00002149statement for the type of operand: register, immediate, basic block, external
2150symbol, global address, constant pool index, or jump table index. For an
Bill Wendling4a2bca82009-04-05 00:41:19 +00002151instruction with a memory address operand, the <tt>printMemOperand</tt> method
2152should be implemented to generate the proper output. Similarly,
2153<tt>printCCOperand</tt> should be used to print a conditional operand.
2154</p>
Chris Lattner78975382008-11-11 19:30:41 +00002155
Bill Wendling4a2bca82009-04-05 00:41:19 +00002156<p><tt>doFinalization</tt> should be overridden in <tt>XXXAsmPrinter</tt>, and
2157it should be called to shut down the assembly printer. During
2158<tt>doFinalization</tt>, global variables and constants are printed to
2159output.
2160</p>
2161
Chris Lattner78975382008-11-11 19:30:41 +00002162</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002163
Chris Lattner78975382008-11-11 19:30:41 +00002164<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002165<h2>
Chris Lattner78975382008-11-11 19:30:41 +00002166 <a name="subtargetSupport">Subtarget Support</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002167</h2>
Chris Lattner78975382008-11-11 19:30:41 +00002168<!-- *********************************************************************** -->
2169
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002170<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002171
2172<p>
2173Subtarget support is used to inform the code generation process of instruction
2174set variations for a given chip set. For example, the LLVM SPARC implementation
2175provided covers three major versions of the SPARC microprocessor architecture:
2176Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a 64-bit
2177architecture), and the UltraSPARC architecture. V8 has 16 double-precision
2178floating-point registers that are also usable as either 32 single-precision or 8
2179quad-precision registers. V8 is also purely big-endian. V9 has 32
2180double-precision floating-point registers that are also usable as 16
Chris Lattner78975382008-11-11 19:30:41 +00002181quad-precision registers, but cannot be used as single-precision registers. The
2182UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set
Bill Wendling4a2bca82009-04-05 00:41:19 +00002183extensions.
2184</p>
Chris Lattner78975382008-11-11 19:30:41 +00002185
Bill Wendling4a2bca82009-04-05 00:41:19 +00002186<p>
2187If subtarget support is needed, you should implement a target-specific
2188XXXSubtarget class for your architecture. This class should process the
2189command-line options <tt>-mcpu=</tt> and <tt>-mattr=</tt>.
2190</p>
Chris Lattner78975382008-11-11 19:30:41 +00002191
Bill Wendling4a2bca82009-04-05 00:41:19 +00002192<p>
2193TableGen uses definitions in the <tt>Target.td</tt> and <tt>Sparc.td</tt> files
2194to generate code in <tt>SparcGenSubtarget.inc</tt>. In <tt>Target.td</tt>, shown
2195below, the <tt>SubtargetFeature</tt> interface is defined. The first 4 string
2196parameters of the <tt>SubtargetFeature</tt> interface are a feature name, an
2197attribute set by the feature, the value of the attribute, and a description of
2198the feature. (The fifth parameter is a list of features whose presence is
2199implied, and its default value is an empty array.)
2200</p>
Chris Lattner78975382008-11-11 19:30:41 +00002201
2202<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002203<pre>
2204class SubtargetFeature&lt;string n, string a, string v, string d,
Chris Lattner78975382008-11-11 19:30:41 +00002205 list&lt;SubtargetFeature&gt; i = []&gt; {
2206 string Name = n;
2207 string Attribute = a;
2208 string Value = v;
2209 string Desc = d;
2210 list&lt;SubtargetFeature&gt; Implies = i;
2211}
2212</pre>
2213</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002214
2215<p>
2216In the <tt>Sparc.td</tt> file, the SubtargetFeature is used to define the
2217following features.
2218</p>
Chris Lattner78975382008-11-11 19:30:41 +00002219
2220<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002221<pre>
2222def FeatureV9 : SubtargetFeature&lt;"v9", "IsV9", "true",
2223 "Enable SPARC-V9 instructions"&gt;;
2224def FeatureV8Deprecated : SubtargetFeature&lt;"deprecated-v8",
2225 "V8DeprecatedInsts", "true",
2226 "Enable deprecated V8 instructions in V9 mode"&gt;;
2227def FeatureVIS : SubtargetFeature&lt;"vis", "IsVIS", "true",
2228 "Enable UltraSPARC Visual Instruction Set extensions"&gt;;
Chris Lattner78975382008-11-11 19:30:41 +00002229</pre>
2230</div>
2231
Bill Wendling4a2bca82009-04-05 00:41:19 +00002232<p>
2233Elsewhere in <tt>Sparc.td</tt>, the Proc class is defined and then is used to
2234define particular SPARC processor subtypes that may have the previously
2235described features.
2236</p>
Chris Lattner78975382008-11-11 19:30:41 +00002237
2238<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002239<pre>
2240class Proc&lt;string Name, list&lt;SubtargetFeature&gt; Features&gt;
2241 : Processor&lt;Name, NoItineraries, Features&gt;;
Chris Lattner78975382008-11-11 19:30:41 +00002242&nbsp;
Bill Wendling4a2bca82009-04-05 00:41:19 +00002243def : Proc&lt;"generic", []&gt;;
2244def : Proc&lt;"v8", []&gt;;
2245def : Proc&lt;"supersparc", []&gt;;
2246def : Proc&lt;"sparclite", []&gt;;
2247def : Proc&lt;"f934", []&gt;;
2248def : Proc&lt;"hypersparc", []&gt;;
2249def : Proc&lt;"sparclite86x", []&gt;;
2250def : Proc&lt;"sparclet", []&gt;;
2251def : Proc&lt;"tsc701", []&gt;;
2252def : Proc&lt;"v9", [FeatureV9]&gt;;
2253def : Proc&lt;"ultrasparc", [FeatureV9, FeatureV8Deprecated]&gt;;
2254def : Proc&lt;"ultrasparc3", [FeatureV9, FeatureV8Deprecated]&gt;;
2255def : Proc&lt;"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]&gt;;
Chris Lattner78975382008-11-11 19:30:41 +00002256</pre>
2257</div>
2258
Bill Wendling4a2bca82009-04-05 00:41:19 +00002259<p>
2260From <tt>Target.td</tt> and <tt>Sparc.td</tt> files, the resulting
Chris Lattner78975382008-11-11 19:30:41 +00002261SparcGenSubtarget.inc specifies enum values to identify the features, arrays of
2262constants to represent the CPU features and CPU subtypes, and the
2263ParseSubtargetFeatures method that parses the features string that sets
Bill Wendling4a2bca82009-04-05 00:41:19 +00002264specified subtarget options. The generated <tt>SparcGenSubtarget.inc</tt> file
2265should be included in the <tt>SparcSubtarget.cpp</tt>. The target-specific
2266implementation of the XXXSubtarget method should follow this pseudocode:
2267</p>
Chris Lattner78975382008-11-11 19:30:41 +00002268
2269<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002270<pre>
2271XXXSubtarget::XXXSubtarget(const Module &amp;M, const std::string &amp;FS) {
Chris Lattner78975382008-11-11 19:30:41 +00002272 // Set the default features
2273 // Determine default and user specified characteristics of the CPU
2274 // Call ParseSubtargetFeatures(FS, CPU) to parse the features string
2275 // Perform any additional operations
2276}
2277</pre>
2278</div>
2279
Bill Wendlinge9e6fd92009-04-05 00:43:04 +00002280</div>
2281
Chris Lattner78975382008-11-11 19:30:41 +00002282<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002283<h2>
Chris Lattner78975382008-11-11 19:30:41 +00002284 <a name="jitSupport">JIT Support</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002285</h2>
Chris Lattner78975382008-11-11 19:30:41 +00002286<!-- *********************************************************************** -->
2287
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002288<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002289
2290<p>
2291The implementation of a target machine optionally includes a Just-In-Time (JIT)
2292code generator that emits machine code and auxiliary structures as binary output
2293that can be written directly to memory. To do this, implement JIT code
2294generation by performing the following steps:
2295</p>
2296
Chris Lattner78975382008-11-11 19:30:41 +00002297<ul>
2298<li>Write an <tt>XXXCodeEmitter.cpp</tt> file that contains a machine function
Bill Wendling4a2bca82009-04-05 00:41:19 +00002299 pass that transforms target-machine instructions into relocatable machine
2300 code.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002301
Bill Wendling4a2bca82009-04-05 00:41:19 +00002302<li>Write an <tt>XXXJITInfo.cpp</tt> file that implements the JIT interfaces for
2303 target-specific code-generation activities, such as emitting machine code
2304 and stubs.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002305
Bill Wendling4a2bca82009-04-05 00:41:19 +00002306<li>Modify <tt>XXXTargetMachine</tt> so that it provides a
2307 <tt>TargetJITInfo</tt> object through its <tt>getJITInfo</tt> method.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002308</ul>
2309
Bill Wendling4a2bca82009-04-05 00:41:19 +00002310<p>
2311There are several different approaches to writing the JIT support code. For
2312instance, TableGen and target descriptor files may be used for creating a JIT
2313code generator, but are not mandatory. For the Alpha and PowerPC target
2314machines, TableGen is used to generate <tt>XXXGenCodeEmitter.inc</tt>, which
Chris Lattner78975382008-11-11 19:30:41 +00002315contains the binary coding of machine instructions and the
Bill Wendling4a2bca82009-04-05 00:41:19 +00002316<tt>getBinaryCodeForInstr</tt> method to access those codes. Other JIT
2317implementations do not.
2318</p>
Chris Lattner78975382008-11-11 19:30:41 +00002319
Bill Wendling4a2bca82009-04-05 00:41:19 +00002320<p>
2321Both <tt>XXXJITInfo.cpp</tt> and <tt>XXXCodeEmitter.cpp</tt> must include the
2322<tt>llvm/CodeGen/MachineCodeEmitter.h</tt> header file that defines the
2323<tt>MachineCodeEmitter</tt> class containing code for several callback functions
2324that write data (in bytes, words, strings, etc.) to the output stream.
2325</p>
2326
Chris Lattner78975382008-11-11 19:30:41 +00002327<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002328<h3>
Chris Lattner78975382008-11-11 19:30:41 +00002329 <a name="mce">Machine Code Emitter</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002330</h3>
Chris Lattner78975382008-11-11 19:30:41 +00002331
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002332<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002333
2334<p>
2335In <tt>XXXCodeEmitter.cpp</tt>, a target-specific of the <tt>Emitter</tt> class
2336is implemented as a function pass (subclass
2337of <tt>MachineFunctionPass</tt>). The target-specific implementation
2338of <tt>runOnMachineFunction</tt> (invoked by
2339<tt>runOnFunction</tt> in <tt>MachineFunctionPass</tt>) iterates through the
2340<tt>MachineBasicBlock</tt> calls <tt>emitInstruction</tt> to process each
2341instruction and emit binary code. <tt>emitInstruction</tt> is largely
2342implemented with case statements on the instruction types defined in
2343<tt>XXXInstrInfo.h</tt>. For example, in <tt>X86CodeEmitter.cpp</tt>,
2344the <tt>emitInstruction</tt> method is built around the following switch/case
2345statements:
2346</p>
Chris Lattner78975382008-11-11 19:30:41 +00002347
2348<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002349<pre>
2350switch (Desc-&gt;TSFlags &amp; X86::FormMask) {
Chris Lattner78975382008-11-11 19:30:41 +00002351case X86II::Pseudo: // for not yet implemented instructions
2352 ... // or pseudo-instructions
2353 break;
2354case X86II::RawFrm: // for instructions with a fixed opcode value
2355 ...
2356 break;
2357case X86II::AddRegFrm: // for instructions that have one register operand
2358 ... // added to their opcode
2359 break;
2360case X86II::MRMDestReg:// for instructions that use the Mod/RM byte
2361 ... // to specify a destination (register)
2362 break;
2363case X86II::MRMDestMem:// for instructions that use the Mod/RM byte
2364 ... // to specify a destination (memory)
2365 break;
2366case X86II::MRMSrcReg: // for instructions that use the Mod/RM byte
2367 ... // to specify a source (register)
2368 break;
2369case X86II::MRMSrcMem: // for instructions that use the Mod/RM byte
2370 ... // to specify a source (memory)
2371 break;
2372case X86II::MRM0r: case X86II::MRM1r: // for instructions that operate on
2373case X86II::MRM2r: case X86II::MRM3r: // a REGISTER r/m operand and
2374case X86II::MRM4r: case X86II::MRM5r: // use the Mod/RM byte and a field
2375case X86II::MRM6r: case X86II::MRM7r: // to hold extended opcode data
2376 ...
2377 break;
2378case X86II::MRM0m: case X86II::MRM1m: // for instructions that operate on
2379case X86II::MRM2m: case X86II::MRM3m: // a MEMORY r/m operand and
2380case X86II::MRM4m: case X86II::MRM5m: // use the Mod/RM byte and a field
2381case X86II::MRM6m: case X86II::MRM7m: // to hold extended opcode data
2382 ...
2383 break;
2384case X86II::MRMInitReg: // for instructions whose source and
2385 ... // destination are the same register
2386 break;
2387}
2388</pre>
2389</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002390
2391<p>
2392The implementations of these case statements often first emit the opcode and
2393then get the operand(s). Then depending upon the operand, helper methods may be
2394called to process the operand(s). For example, in <tt>X86CodeEmitter.cpp</tt>,
2395for the <tt>X86II::AddRegFrm</tt> case, the first data emitted
2396(by <tt>emitByte</tt>) is the opcode added to the register operand. Then an
2397object representing the machine operand, <tt>MO1</tt>, is extracted. The helper
2398methods such as <tt>isImmediate</tt>,
Chris Lattner78975382008-11-11 19:30:41 +00002399<tt>isGlobalAddress</tt>, <tt>isExternalSymbol</tt>, <tt>isConstantPoolIndex</tt>, and
Bill Wendling4a2bca82009-04-05 00:41:19 +00002400<tt>isJumpTableIndex</tt> determine the operand
2401type. (<tt>X86CodeEmitter.cpp</tt> also has private methods such
2402as <tt>emitConstant</tt>, <tt>emitGlobalAddress</tt>,
Chris Lattner78975382008-11-11 19:30:41 +00002403<tt>emitExternalSymbolAddress</tt>, <tt>emitConstPoolAddress</tt>,
Bill Wendling4a2bca82009-04-05 00:41:19 +00002404and <tt>emitJumpTableAddress</tt> that emit the data into the output stream.)
2405</p>
Chris Lattner78975382008-11-11 19:30:41 +00002406
2407<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002408<pre>
2409case X86II::AddRegFrm:
Chris Lattner78975382008-11-11 19:30:41 +00002410 MCE.emitByte(BaseOpcode + getX86RegNum(MI.getOperand(CurOp++).getReg()));
2411
2412 if (CurOp != NumOps) {
2413 const MachineOperand &amp;MO1 = MI.getOperand(CurOp++);
2414 unsigned Size = X86InstrInfo::sizeOfImm(Desc);
2415 if (MO1.isImmediate())
2416 emitConstant(MO1.getImm(), Size);
2417 else {
2418 unsigned rt = Is64BitMode ? X86::reloc_pcrel_word
2419 : (IsPIC ? X86::reloc_picrel_word : X86::reloc_absolute_word);
2420 if (Opcode == X86::MOV64ri)
2421 rt = X86::reloc_absolute_dword; // FIXME: add X86II flag?
2422 if (MO1.isGlobalAddress()) {
2423 bool NeedStub = isa&lt;Function&gt;(MO1.getGlobal());
2424 bool isLazy = gvNeedsLazyPtr(MO1.getGlobal());
2425 emitGlobalAddress(MO1.getGlobal(), rt, MO1.getOffset(), 0,
2426 NeedStub, isLazy);
2427 } else if (MO1.isExternalSymbol())
2428 emitExternalSymbolAddress(MO1.getSymbolName(), rt);
2429 else if (MO1.isConstantPoolIndex())
2430 emitConstPoolAddress(MO1.getIndex(), rt);
2431 else if (MO1.isJumpTableIndex())
2432 emitJumpTableAddress(MO1.getIndex(), rt);
2433 }
2434 }
2435 break;
2436</pre>
2437</div>
Chris Lattner78975382008-11-11 19:30:41 +00002438
Bill Wendling4a2bca82009-04-05 00:41:19 +00002439<p>
2440In the previous example, <tt>XXXCodeEmitter.cpp</tt> uses the
2441variable <tt>rt</tt>, which is a RelocationType enum that may be used to
2442relocate addresses (for example, a global address with a PIC base offset). The
2443<tt>RelocationType</tt> enum for that target is defined in the short
2444target-specific <tt>XXXRelocations.h</tt> file. The <tt>RelocationType</tt> is used by
2445the <tt>relocate</tt> method defined in <tt>XXXJITInfo.cpp</tt> to rewrite
2446addresses for referenced global symbols.
2447</p>
2448
2449<p>
2450For example, <tt>X86Relocations.h</tt> specifies the following relocation types
2451for the X86 addresses. In all four cases, the relocated value is added to the
2452value already in memory. For <tt>reloc_pcrel_word</tt>
2453and <tt>reloc_picrel_word</tt>, there is an additional initial adjustment.
2454</p>
Chris Lattner78975382008-11-11 19:30:41 +00002455
2456<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002457<pre>
2458enum RelocationType {
2459 reloc_pcrel_word = 0, // add reloc value after adjusting for the PC loc
2460 reloc_picrel_word = 1, // add reloc value after adjusting for the PIC base
Chris Lattner78975382008-11-11 19:30:41 +00002461 reloc_absolute_word = 2, // absolute relocation; no additional adjustment
2462 reloc_absolute_dword = 3 // absolute relocation; no additional adjustment
2463};
2464</pre>
2465</div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002466
2467</div>
2468
Chris Lattner78975382008-11-11 19:30:41 +00002469<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002470<h3>
Chris Lattner78975382008-11-11 19:30:41 +00002471 <a name="targetJITInfo">Target JIT Info</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +00002472</h3>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002473
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002474<div>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002475
2476<p>
2477<tt>XXXJITInfo.cpp</tt> implements the JIT interfaces for target-specific
2478code-generation activities, such as emitting machine code and stubs. At minimum,
2479a target-specific version of <tt>XXXJITInfo</tt> implements the following:
2480</p>
2481
Chris Lattner78975382008-11-11 19:30:41 +00002482<ul>
Bill Wendling4a2bca82009-04-05 00:41:19 +00002483<li><tt>getLazyResolverFunction</tt> &mdash; Initializes the JIT, gives the
2484 target a function that is used for compilation.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002485
Bill Wendling4a2bca82009-04-05 00:41:19 +00002486<li><tt>emitFunctionStub</tt> &mdash; Returns a native function with a specified
2487 address for a callback function.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002488
Bill Wendling4a2bca82009-04-05 00:41:19 +00002489<li><tt>relocate</tt> &mdash; Changes the addresses of referenced globals, based
2490 on relocation types.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002491
Bill Wendling4a2bca82009-04-05 00:41:19 +00002492<li>Callback function that are wrappers to a function stub that is used when the
2493 real target is not initially known.</li>
Chris Lattner78975382008-11-11 19:30:41 +00002494</ul>
2495
Bill Wendling4a2bca82009-04-05 00:41:19 +00002496<p>
2497<tt>getLazyResolverFunction</tt> is generally trivial to implement. It makes the
2498incoming parameter as the global <tt>JITCompilerFunction</tt> and returns the
Chris Lattner78975382008-11-11 19:30:41 +00002499callback function that will be used a function wrapper. For the Alpha target
Bill Wendling4a2bca82009-04-05 00:41:19 +00002500(in <tt>AlphaJITInfo.cpp</tt>), the <tt>getLazyResolverFunction</tt>
2501implementation is simply:
2502</p>
Chris Lattner78975382008-11-11 19:30:41 +00002503
2504<div class="doc_code">
Bill Wendling4a2bca82009-04-05 00:41:19 +00002505<pre>
2506TargetJITInfo::LazyResolverFn AlphaJITInfo::getLazyResolverFunction(
2507 JITCompilerFn F) {
Chris Lattner78975382008-11-11 19:30:41 +00002508 JITCompilerFunction = F;
2509 return AlphaCompilationCallback;
2510}
2511</pre>
2512</div>
Chris Lattner78975382008-11-11 19:30:41 +00002513
Bill Wendling4a2bca82009-04-05 00:41:19 +00002514<p>
2515For the X86 target, the <tt>getLazyResolverFunction</tt> implementation is a
2516little more complication, because it returns a different callback function for
2517processors with SSE instructions and XMM registers.
2518</p>
2519
2520<p>
2521The callback function initially saves and later restores the callee register
2522values, incoming arguments, and frame and return address. The callback function
2523needs low-level access to the registers or stack, so it is typically implemented
2524with assembler.
2525</p>
2526
Misha Brukman8eb67192004-09-06 22:58:13 +00002527</div>
2528
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +00002529</div>
2530
Misha Brukman8eb67192004-09-06 22:58:13 +00002531<!-- *********************************************************************** -->
2532
2533<hr>
2534<address>
2535 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +00002536 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Misha Brukman8eb67192004-09-06 22:58:13 +00002537 <a href="http://validator.w3.org/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +00002538 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Misha Brukman8eb67192004-09-06 22:58:13 +00002539
Chris Lattner78975382008-11-11 19:30:41 +00002540 <a href="http://www.woo.com">Mason Woo</a> and <a href="http://misha.brukman.net">Misha Brukman</a><br>
NAKAMURA Takumib9a33632011-04-09 02:13:37 +00002541 <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
Misha Brukman8eb67192004-09-06 22:58:13 +00002542 <br>
2543 Last modified: $Date$
2544</address>
2545
2546</body>
2547</html>