docs/WritingAnLLVMBackend.html

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