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