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