diff options
| author | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
|---|---|---|
| committer | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
| commit | e2c3a49c8029ebd9ef530101cc24c66562e3dff5 (patch) | |
| tree | 91bf9600cc8df90cf99751a8f8bafc317cffc91e /docs/WritingAnLLVMBackend.html | |
| parent | c10b5afbe8138b0fdf3af4ed3e1ddf96cf3cb4cb (diff) | |
| download | external_llvm-e2c3a49c8029ebd9ef530101cc24c66562e3dff5.zip external_llvm-e2c3a49c8029ebd9ef530101cc24c66562e3dff5.tar.gz external_llvm-e2c3a49c8029ebd9ef530101cc24c66562e3dff5.tar.bz2 | |
Revert r103213. It broke several sections of live website.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103219 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/WritingAnLLVMBackend.html')
| -rw-r--r-- | docs/WritingAnLLVMBackend.html | 2561 |
1 files changed, 2561 insertions, 0 deletions
diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html new file mode 100644 index 0000000..f49875c --- /dev/null +++ b/docs/WritingAnLLVMBackend.html @@ -0,0 +1,2561 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <title>Writing an LLVM Compiler Backend</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> + +<body> + +<div class="doc_title"> + Writing an LLVM Compiler Backend +</div> + +<ol> + <li><a href="#intro">Introduction</a> + <ul> + <li><a href="#Audience">Audience</a></li> + <li><a href="#Prerequisite">Prerequisite Reading</a></li> + <li><a href="#Basic">Basic Steps</a></li> + <li><a href="#Preliminaries">Preliminaries</a></li> + </ul> + <li><a href="#TargetMachine">Target Machine</a></li> + <li><a href="#TargetRegistration">Target Registration</a></li> + <li><a href="#RegisterSet">Register Set and Register Classes</a> + <ul> + <li><a href="#RegisterDef">Defining a Register</a></li> + <li><a href="#RegisterClassDef">Defining a Register Class</a></li> + <li><a href="#implementRegister">Implement a subclass of TargetRegisterInfo</a></li> + </ul></li> + <li><a href="#InstructionSet">Instruction Set</a> + <ul> + <li><a href="#operandMapping">Instruction Operand Mapping</a></li> + <li><a href="#implementInstr">Implement a subclass of TargetInstrInfo</a></li> + <li><a href="#branchFolding">Branch Folding and If Conversion</a></li> + </ul></li> + <li><a href="#InstructionSelector">Instruction Selector</a> + <ul> + <li><a href="#LegalizePhase">The SelectionDAG Legalize Phase</a> + <ul> + <li><a href="#promote">Promote</a></li> + <li><a href="#expand">Expand</a></li> + <li><a href="#custom">Custom</a></li> + <li><a href="#legal">Legal</a></li> + </ul></li> + <li><a href="#callingConventions">Calling Conventions</a></li> + </ul></li> + <li><a href="#assemblyPrinter">Assembly Printer</a></li> + <li><a href="#subtargetSupport">Subtarget Support</a></li> + <li><a href="#jitSupport">JIT Support</a> + <ul> + <li><a href="#mce">Machine Code Emitter</a></li> + <li><a href="#targetJITInfo">Target JIT Info</a></li> + </ul></li> +</ol> + +<div class="doc_author"> + <p>Written by <a href="http://www.woo.com">Mason Woo</a> and + <a href="http://misha.brukman.net">Misha Brukman</a></p> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="intro">Introduction</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +This document describes techniques for writing compiler backends that convert +the LLVM Intermediate Representation (IR) to code for a specified machine or +other languages. Code intended for a specific machine can take the form of +either assembly code or binary code (usable for a JIT compiler). +</p> + +<p> +The backend of LLVM features a target-independent code generator that may create +output for several types of target CPUs — including X86, PowerPC, Alpha, +and SPARC. The backend may also be used to generate code targeted at SPUs of the +Cell processor or GPUs to support the execution of compute kernels. +</p> + +<p> +The document focuses on existing examples found in subdirectories +of <tt>llvm/lib/Target</tt> in a downloaded LLVM release. In particular, this +document focuses on the example of creating a static compiler (one that emits +text assembly) for a SPARC target, because SPARC has fairly standard +characteristics, such as a RISC instruction set and straightforward calling +conventions. +</p> + +</div> + +<div class="doc_subsection"> + <a name="Audience">Audience</a> +</div> + +<div class="doc_text"> + +<p> +The audience for this document is anyone who needs to write an LLVM backend to +generate code for a specific hardware or software target. +</p> + +</div> + +<div class="doc_subsection"> + <a name="Prerequisite">Prerequisite Reading</a> +</div> + +<div class="doc_text"> + +<p> +These essential documents must be read before reading this document: +</p> + +<ul> +<li><i><a href="http://www.llvm.org/docs/LangRef.html">LLVM Language Reference + Manual</a></i> — a reference manual for the LLVM assembly language.</li> + +<li><i><a href="http://www.llvm.org/docs/CodeGenerator.html">The LLVM + Target-Independent Code Generator</a></i> — a guide to the components + (classes and code generation algorithms) for translating the LLVM internal + representation into machine code for a specified target. Pay particular + attention to the descriptions of code generation stages: Instruction + Selection, Scheduling and Formation, SSA-based Optimization, Register + Allocation, Prolog/Epilog Code Insertion, Late Machine Code Optimizations, + and Code Emission.</li> + +<li><i><a href="http://www.llvm.org/docs/TableGenFundamentals.html">TableGen + Fundamentals</a></i> —a document that describes the TableGen + (<tt>tblgen</tt>) application that manages domain-specific information to + support LLVM code generation. TableGen processes input from a target + description file (<tt>.td</tt> suffix) and generates C++ code that can be + used for code generation.</li> + +<li><i><a href="http://www.llvm.org/docs/WritingAnLLVMPass.html">Writing an LLVM + Pass</a></i> — The assembly printer is a <tt>FunctionPass</tt>, as are + several SelectionDAG processing steps.</li> +</ul> + +<p> +To follow the SPARC examples in this document, have a copy of +<i><a href="http://www.sparc.org/standards/V8.pdf">The SPARC Architecture +Manual, Version 8</a></i> for reference. For details about the ARM instruction +set, refer to the <i><a href="http://infocenter.arm.com/">ARM Architecture +Reference Manual</a></i>. For more about the GNU Assembler format +(<tt>GAS</tt>), see +<i><a href="http://sourceware.org/binutils/docs/as/index.html">Using As</a></i>, +especially for the assembly printer. <i>Using As</i> contains a list of target +machine dependent features. +</p> + +</div> + +<div class="doc_subsection"> + <a name="Basic">Basic Steps</a> +</div> + +<div class="doc_text"> + +<p> +To write a compiler backend for LLVM that converts the LLVM IR to code for a +specified target (machine or other language), follow these steps: +</p> + +<ul> +<li>Create a subclass of the TargetMachine class that describes characteristics + of your target machine. Copy existing examples of specific TargetMachine + class and header files; for example, start with + <tt>SparcTargetMachine.cpp</tt> and <tt>SparcTargetMachine.h</tt>, but + change the file names for your target. Similarly, change code that + references "Sparc" to reference your target. </li> + +<li>Describe the register set of the target. Use TableGen to generate code for + register definition, register aliases, and register classes from a + target-specific <tt>RegisterInfo.td</tt> input file. You should also write + additional code for a subclass of the TargetRegisterInfo class that + represents the class register file data used for register allocation and + also describes the interactions between registers.</li> + +<li>Describe the instruction set of the target. Use TableGen to generate code + for target-specific instructions from target-specific versions of + <tt>TargetInstrFormats.td</tt> and <tt>TargetInstrInfo.td</tt>. You should + write additional code for a subclass of the TargetInstrInfo class to + represent machine instructions supported by the target machine. </li> + +<li>Describe the selection and conversion of the LLVM IR from a Directed Acyclic + Graph (DAG) representation of instructions to native target-specific + instructions. Use TableGen to generate code that matches patterns and + selects instructions based on additional information in a target-specific + version of <tt>TargetInstrInfo.td</tt>. Write code + for <tt>XXXISelDAGToDAG.cpp</tt>, where XXX identifies the specific target, + to perform pattern matching and DAG-to-DAG instruction selection. Also write + code in <tt>XXXISelLowering.cpp</tt> to replace or remove operations and + data types that are not supported natively in a SelectionDAG. </li> + +<li>Write code for an assembly printer that converts LLVM IR to a GAS format for + your target machine. You should add assembly strings to the instructions + defined in your target-specific version of <tt>TargetInstrInfo.td</tt>. You + should also write code for a subclass of AsmPrinter that performs the + LLVM-to-assembly conversion and a trivial subclass of TargetAsmInfo.</li> + +<li>Optionally, add support for subtargets (i.e., variants with different + capabilities). You should also write code for a subclass of the + TargetSubtarget class, which allows you to use the <tt>-mcpu=</tt> + and <tt>-mattr=</tt> command-line options.</li> + +<li>Optionally, add JIT support and create a machine code emitter (subclass of + TargetJITInfo) that is used to emit binary code directly into memory. </li> +</ul> + +<p> +In the <tt>.cpp</tt> and <tt>.h</tt>. files, initially stub up these methods and +then implement them later. Initially, you may not know which private members +that the class will need and which components will need to be subclassed. +</p> + +</div> + +<div class="doc_subsection"> + <a name="Preliminaries">Preliminaries</a> +</div> + +<div class="doc_text"> + +<p> +To actually create your compiler backend, you need to create and modify a few +files. The absolute minimum is discussed here. But to actually use the LLVM +target-independent code generator, you must perform the steps described in +the <a href="http://www.llvm.org/docs/CodeGenerator.html">LLVM +Target-Independent Code Generator</a> document. +</p> + +<p> +First, you should create a subdirectory under <tt>lib/Target</tt> to hold all +the files related to your target. If your target is called "Dummy," create the +directory <tt>lib/Target/Dummy</tt>. +</p> + +<p> +In this new +directory, create a <tt>Makefile</tt>. It is easiest to copy a +<tt>Makefile</tt> of another target and modify it. It should at least contain +the <tt>LEVEL</tt>, <tt>LIBRARYNAME</tt> and <tt>TARGET</tt> variables, and then +include <tt>$(LEVEL)/Makefile.common</tt>. The library can be +named <tt>LLVMDummy</tt> (for example, see the MIPS target). Alternatively, you +can split the library into <tt>LLVMDummyCodeGen</tt> +and <tt>LLVMDummyAsmPrinter</tt>, the latter of which should be implemented in a +subdirectory below <tt>lib/Target/Dummy</tt> (for example, see the PowerPC +target). +</p> + +<p> +Note that these two naming schemes are hardcoded into <tt>llvm-config</tt>. +Using any other naming scheme will confuse <tt>llvm-config</tt> and produce a +lot of (seemingly unrelated) linker errors when linking <tt>llc</tt>. +</p> + +<p> +To make your target actually do something, you need to implement a subclass of +<tt>TargetMachine</tt>. This implementation should typically be in the file +<tt>lib/Target/DummyTargetMachine.cpp</tt>, but any file in +the <tt>lib/Target</tt> directory will be built and should work. To use LLVM's +target independent code generator, you should do what all current machine +backends do: create a subclass of <tt>LLVMTargetMachine</tt>. (To create a +target from scratch, create a subclass of <tt>TargetMachine</tt>.) +</p> + +<p> +To get LLVM to actually build and link your target, you need to add it to +the <tt>TARGETS_TO_BUILD</tt> variable. To do this, you modify the configure +script to know about your target when parsing the <tt>--enable-targets</tt> +option. Search the configure script for <tt>TARGETS_TO_BUILD</tt>, add your +target to the lists there (some creativity required), and then +reconfigure. Alternatively, you can change <tt>autotools/configure.ac</tt> and +regenerate configure by running <tt>./autoconf/AutoRegen.sh</tt>. +</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="TargetMachine">Target Machine</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +<tt>LLVMTargetMachine</tt> is designed as a base class for targets implemented +with the LLVM target-independent code generator. The <tt>LLVMTargetMachine</tt> +class should be specialized by a concrete target class that implements the +various virtual methods. <tt>LLVMTargetMachine</tt> is defined as a subclass of +<tt>TargetMachine</tt> in <tt>include/llvm/Target/TargetMachine.h</tt>. The +<tt>TargetMachine</tt> class implementation (<tt>TargetMachine.cpp</tt>) also +processes numerous command-line options. +</p> + +<p> +To create a concrete target-specific subclass of <tt>LLVMTargetMachine</tt>, +start by copying an existing <tt>TargetMachine</tt> class and header. You +should name the files that you create to reflect your specific target. For +instance, for the SPARC target, name the files <tt>SparcTargetMachine.h</tt> and +<tt>SparcTargetMachine.cpp</tt>. +</p> + +<p> +For a target machine <tt>XXX</tt>, the implementation of +<tt>XXXTargetMachine</tt> must have access methods to obtain objects that +represent target components. These methods are named <tt>get*Info</tt>, and are +intended to obtain the instruction set (<tt>getInstrInfo</tt>), register set +(<tt>getRegisterInfo</tt>), stack frame layout (<tt>getFrameInfo</tt>), and +similar information. <tt>XXXTargetMachine</tt> must also implement the +<tt>getTargetData</tt> method to access an object with target-specific data +characteristics, such as data type size and alignment requirements. +</p> + +<p> +For instance, for the SPARC target, the header file +<tt>SparcTargetMachine.h</tt> declares prototypes for several <tt>get*Info</tt> +and <tt>getTargetData</tt> methods that simply return a class member. +</p> + +<div class="doc_code"> +<pre> +namespace llvm { + +class Module; + +class SparcTargetMachine : public LLVMTargetMachine { + const TargetData DataLayout; // Calculates type size & alignment + SparcSubtarget Subtarget; + SparcInstrInfo InstrInfo; + TargetFrameInfo FrameInfo; + +protected: + virtual const TargetAsmInfo *createTargetAsmInfo() const; + +public: + SparcTargetMachine(const Module &M, const std::string &FS); + + virtual const SparcInstrInfo *getInstrInfo() const {return &InstrInfo; } + virtual const TargetFrameInfo *getFrameInfo() const {return &FrameInfo; } + virtual const TargetSubtarget *getSubtargetImpl() const{return &Subtarget; } + virtual const TargetRegisterInfo *getRegisterInfo() const { + return &InstrInfo.getRegisterInfo(); + } + virtual const TargetData *getTargetData() const { return &DataLayout; } + static unsigned getModuleMatchQuality(const Module &M); + + // Pass Pipeline Configuration + virtual bool addInstSelector(PassManagerBase &PM, bool Fast); + virtual bool addPreEmitPass(PassManagerBase &PM, bool Fast); +}; + +} // end namespace llvm +</pre> +</div> + +</div> + + +<div class="doc_text"> + +<ul> +<li><tt>getInstrInfo()</tt></li> +<li><tt>getRegisterInfo()</tt></li> +<li><tt>getFrameInfo()</tt></li> +<li><tt>getTargetData()</tt></li> +<li><tt>getSubtargetImpl()</tt></li> +</ul> + +<p>For some targets, you also need to support the following methods:</p> + +<ul> +<li><tt>getTargetLowering()</tt></li> +<li><tt>getJITInfo()</tt></li> +</ul> + +<p> +In addition, the <tt>XXXTargetMachine</tt> constructor should specify a +<tt>TargetDescription</tt> string that determines the data layout for the target +machine, including characteristics such as pointer size, alignment, and +endianness. For example, the constructor for SparcTargetMachine contains the +following: +</p> + +<div class="doc_code"> +<pre> +SparcTargetMachine::SparcTargetMachine(const Module &M, const std::string &FS) + : DataLayout("E-p:32:32-f128:128:128"), + Subtarget(M, FS), InstrInfo(Subtarget), + FrameInfo(TargetFrameInfo::StackGrowsDown, 8, 0) { +} +</pre> +</div> + +</div> + +<div class="doc_text"> + +<p>Hyphens separate portions of the <tt>TargetDescription</tt> string.</p> + +<ul> +<li>An upper-case "<tt>E</tt>" in the string indicates a big-endian target data + model. a lower-case "<tt>e</tt>" indicates little-endian.</li> + +<li>"<tt>p:</tt>" is followed by pointer information: size, ABI alignment, and + preferred alignment. If only two figures follow "<tt>p:</tt>", then the + first value is pointer size, and the second value is both ABI and preferred + alignment.</li> + +<li>Then a letter for numeric type alignment: "<tt>i</tt>", "<tt>f</tt>", + "<tt>v</tt>", or "<tt>a</tt>" (corresponding to integer, floating point, + vector, or aggregate). "<tt>i</tt>", "<tt>v</tt>", or "<tt>a</tt>" are + followed by ABI alignment and preferred alignment. "<tt>f</tt>" is followed + by three values: the first indicates the size of a long double, then ABI + alignment, and then ABI preferred alignment.</li> +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="TargetRegistration">Target Registration</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +You must also register your target with the <tt>TargetRegistry</tt>, which is +what other LLVM tools use to be able to lookup and use your target at +runtime. The <tt>TargetRegistry</tt> can be used directly, but for most targets +there are helper templates which should take care of the work for you.</p> + +<p> +All targets should declare a global <tt>Target</tt> object which is used to +represent the target during registration. Then, in the target's TargetInfo +library, the target should define that object and use +the <tt>RegisterTarget</tt> template to register the target. For example, the Sparc registration code looks like this: +</p> + +<div class="doc_code"> +<pre> +Target llvm::TheSparcTarget; + +extern "C" void LLVMInitializeSparcTargetInfo() { + RegisterTarget<Triple::sparc, /*HasJIT=*/false> + X(TheSparcTarget, "sparc", "Sparc"); +} +</pre> +</div> + +<p> +This allows the <tt>TargetRegistry</tt> to look up the target by name or by +target triple. In addition, most targets will also register additional features +which are available in separate libraries. These registration steps are +separate, because some clients may wish to only link in some parts of the target +-- the JIT code generator does not require the use of the assembler printer, for +example. Here is an example of registering the Sparc assembly printer: +</p> + +<div class="doc_code"> +<pre> +extern "C" void LLVMInitializeSparcAsmPrinter() { + RegisterAsmPrinter<SparcAsmPrinter> X(TheSparcTarget); +} +</pre> +</div> + +<p> +For more information, see +"<a href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>". +</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="RegisterSet">Register Set and Register Classes</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +You should describe a concrete target-specific class that represents the +register file of a target machine. This class is called <tt>XXXRegisterInfo</tt> +(where <tt>XXX</tt> identifies the target) and represents the class register +file data that is used for register allocation. It also describes the +interactions between registers. +</p> + +<p> +You also need to define register classes to categorize related registers. A +register class should be added for groups of registers that are all treated the +same way for some instruction. Typical examples are register classes for +integer, floating-point, or vector registers. A register allocator allows an +instruction to use any register in a specified register class to perform the +instruction in a similar manner. Register classes allocate virtual registers to +instructions from these sets, and register classes let the target-independent +register allocator automatically choose the actual registers. +</p> + +<p> +Much of the code for registers, including register definition, register aliases, +and register classes, is generated by TableGen from <tt>XXXRegisterInfo.td</tt> +input files and placed in <tt>XXXGenRegisterInfo.h.inc</tt> and +<tt>XXXGenRegisterInfo.inc</tt> output files. Some of the code in the +implementation of <tt>XXXRegisterInfo</tt> requires hand-coding. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="RegisterDef">Defining a Register</a> +</div> + +<div class="doc_text"> + +<p> +The <tt>XXXRegisterInfo.td</tt> file typically starts with register definitions +for a target machine. The <tt>Register</tt> class (specified +in <tt>Target.td</tt>) is used to define an object for each register. The +specified string <tt>n</tt> becomes the <tt>Name</tt> of the register. The +basic <tt>Register</tt> object does not have any subregisters and does not +specify any aliases. +</p> + +<div class="doc_code"> +<pre> +class Register<string n> { + string Namespace = ""; + string AsmName = n; + string Name = n; + int SpillSize = 0; + int SpillAlignment = 0; + list<Register> Aliases = []; + list<Register> SubRegs = []; + list<int> DwarfNumbers = []; +} +</pre> +</div> + +<p> +For example, in the <tt>X86RegisterInfo.td</tt> file, there are register +definitions that utilize the Register class, such as: +</p> + +<div class="doc_code"> +<pre> +def AL : Register<"AL">, DwarfRegNum<[0, 0, 0]>; +</pre> +</div> + +<p> +This defines the register <tt>AL</tt> and assigns it values (with +<tt>DwarfRegNum</tt>) that are used by <tt>gcc</tt>, <tt>gdb</tt>, or a debug +information writer to identify a register. For register +<tt>AL</tt>, <tt>DwarfRegNum</tt> takes an array of 3 values representing 3 +different modes: the first element is for X86-64, the second for exception +handling (EH) on X86-32, and the third is generic. -1 is a special Dwarf number +that indicates the gcc number is undefined, and -2 indicates the register number +is invalid for this mode. +</p> + +<p> +From the previously described line in the <tt>X86RegisterInfo.td</tt> file, +TableGen generates this code in the <tt>X86GenRegisterInfo.inc</tt> file: +</p> + +<div class="doc_code"> +<pre> +static const unsigned GR8[] = { X86::AL, ... }; + +const unsigned AL_AliasSet[] = { X86::AX, X86::EAX, X86::RAX, 0 }; + +const TargetRegisterDesc RegisterDescriptors[] = { + ... +{ "AL", "AL", AL_AliasSet, Empty_SubRegsSet, Empty_SubRegsSet, AL_SuperRegsSet }, ... +</pre> +</div> + +<p> +From the register info file, TableGen generates a <tt>TargetRegisterDesc</tt> +object for each register. <tt>TargetRegisterDesc</tt> is defined in +<tt>include/llvm/Target/TargetRegisterInfo.h</tt> with the following fields: +</p> + +<div class="doc_code"> +<pre> +struct TargetRegisterDesc { + const char *AsmName; // Assembly language name for the register + const char *Name; // Printable name for the reg (for debugging) + const unsigned *AliasSet; // Register Alias Set + const unsigned *SubRegs; // Sub-register set + const unsigned *ImmSubRegs; // Immediate sub-register set + const unsigned *SuperRegs; // Super-register set +};</pre> +</div> + +<p> +TableGen uses the entire target description file (<tt>.td</tt>) to determine +text names for the register (in the <tt>AsmName</tt> and <tt>Name</tt> fields of +<tt>TargetRegisterDesc</tt>) and the relationships of other registers to the +defined register (in the other <tt>TargetRegisterDesc</tt> fields). In this +example, other definitions establish the registers "<tt>AX</tt>", +"<tt>EAX</tt>", and "<tt>RAX</tt>" as aliases for one another, so TableGen +generates a null-terminated array (<tt>AL_AliasSet</tt>) for this register alias +set. +</p> + +<p> +The <tt>Register</tt> class is commonly used as a base class for more complex +classes. In <tt>Target.td</tt>, the <tt>Register</tt> class is the base for the +<tt>RegisterWithSubRegs</tt> class that is used to define registers that need to +specify subregisters in the <tt>SubRegs</tt> list, as shown here: +</p> + +<div class="doc_code"> +<pre> +class RegisterWithSubRegs<string n, +list<Register> subregs> : Register<n> { + let SubRegs = subregs; +} +</pre> +</div> + +<p> +In <tt>SparcRegisterInfo.td</tt>, additional register classes are defined for +SPARC: a Register subclass, SparcReg, and further subclasses: <tt>Ri</tt>, +<tt>Rf</tt>, and <tt>Rd</tt>. SPARC registers are identified by 5-bit ID +numbers, which is a feature common to these subclasses. Note the use of +'<tt>let</tt>' expressions to override values that are initially defined in a +superclass (such as <tt>SubRegs</tt> field in the <tt>Rd</tt> class). +</p> + +<div class="doc_code"> +<pre> +class SparcReg<string n> : Register<n> { + field bits<5> Num; + let Namespace = "SP"; +} +// Ri - 32-bit integer registers +class Ri<bits<5> num, string n> : +SparcReg<n> { + let Num = num; +} +// Rf - 32-bit floating-point registers +class Rf<bits<5> num, string n> : +SparcReg<n> { + let Num = num; +} +// Rd - Slots in the FP register file for 64-bit +floating-point values. +class Rd<bits<5> num, string n, +list<Register> subregs> : SparcReg<n> { + let Num = num; + let SubRegs = subregs; +} +</pre> +</div> + +<p> +In the <tt>SparcRegisterInfo.td</tt> file, there are register definitions that +utilize these subclasses of <tt>Register</tt>, such as: +</p> + +<div class="doc_code"> +<pre> +def G0 : Ri< 0, "G0">, +DwarfRegNum<[0]>; +def G1 : Ri< 1, "G1">, DwarfRegNum<[1]>; +... +def F0 : Rf< 0, "F0">, +DwarfRegNum<[32]>; +def F1 : Rf< 1, "F1">, +DwarfRegNum<[33]>; +... +def D0 : Rd< 0, "F0", [F0, F1]>, +DwarfRegNum<[32]>; +def D1 : Rd< 2, "F2", [F2, F3]>, +DwarfRegNum<[34]>; +</pre> +</div> + +<p> +The last two registers shown above (<tt>D0</tt> and <tt>D1</tt>) are +double-precision floating-point registers that are aliases for pairs of +single-precision floating-point sub-registers. In addition to aliases, the +sub-register and super-register relationships of the defined register are in +fields of a register's TargetRegisterDesc. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="RegisterClassDef">Defining a Register Class</a> +</div> + +<div class="doc_text"> + +<p> +The <tt>RegisterClass</tt> class (specified in <tt>Target.td</tt>) is used to +define an object that represents a group of related registers and also defines +the default allocation order of the registers. A target description file +<tt>XXXRegisterInfo.td</tt> that uses <tt>Target.td</tt> can construct register +classes using the following class: +</p> + +<div class="doc_code"> +<pre> +class RegisterClass<string namespace, +list<ValueType> regTypes, int alignment, + list<Register> regList> { + string Namespace = namespace; + list<ValueType> RegTypes = regTypes; + int Size = 0; // spill size, in bits; zero lets tblgen pick the size + int Alignment = alignment; + + // CopyCost is the cost of copying a value between two registers + // default value 1 means a single instruction + // A negative value means copying is extremely expensive or impossible + int CopyCost = 1; + list<Register> MemberList = regList; + + // for register classes that are subregisters of this class + list<RegisterClass> SubRegClassList = []; + + code MethodProtos = [{}]; // to insert arbitrary code + code MethodBodies = [{}]; +} +</pre> +</div> + +<p>To define a RegisterClass, use the following 4 arguments:</p> + +<ul> +<li>The first argument of the definition is the name of the namespace.</li> + +<li>The second argument is a list of <tt>ValueType</tt> register type values + that are defined in <tt>include/llvm/CodeGen/ValueTypes.td</tt>. Defined + values include integer types (such as <tt>i16</tt>, <tt>i32</tt>, + and <tt>i1</tt> for Boolean), floating-point types + (<tt>f32</tt>, <tt>f64</tt>), and vector types (for example, <tt>v8i16</tt> + for an <tt>8 x i16</tt> vector). All registers in a <tt>RegisterClass</tt> + must have the same <tt>ValueType</tt>, but some registers may store vector + data in different configurations. For example a register that can process a + 128-bit vector may be able to handle 16 8-bit integer elements, 8 16-bit + integers, 4 32-bit integers, and so on. </li> + +<li>The third argument of the <tt>RegisterClass</tt> definition specifies the + alignment required of the registers when they are stored or loaded to + memory.</li> + +<li>The final argument, <tt>regList</tt>, specifies which registers are in this + class. If an <tt>allocation_order_*</tt> method is not specified, + then <tt>regList</tt> also defines the order of allocation used by the + register allocator.</li> +</ul> + +<p> +In <tt>SparcRegisterInfo.td</tt>, three RegisterClass objects are defined: +<tt>FPRegs</tt>, <tt>DFPRegs</tt>, and <tt>IntRegs</tt>. For all three register +classes, the first argument defines the namespace with the string +'<tt>SP</tt>'. <tt>FPRegs</tt> defines a group of 32 single-precision +floating-point registers (<tt>F0</tt> to <tt>F31</tt>); <tt>DFPRegs</tt> defines +a group of 16 double-precision registers +(<tt>D0-D15</tt>). For <tt>IntRegs</tt>, the <tt>MethodProtos</tt> +and <tt>MethodBodies</tt> methods are used by TableGen to insert the specified +code into generated output. +</p> + +<div class="doc_code"> +<pre> +def FPRegs : RegisterClass<"SP", [f32], 32, + [F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, + F16, F17, F18, F19, F20, F21, F22, F23, F24, F25, F26, F27, F28, F29, F30, F31]>; + +def DFPRegs : RegisterClass<"SP", [f64], 64, + [D0, D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, D14, D15]>; + +def IntRegs : RegisterClass<"SP", [i32], 32, + [L0, L1, L2, L3, L4, L5, L6, L7, + I0, I1, I2, I3, I4, I5, + O0, O1, O2, O3, O4, O5, O7, + G1, + // Non-allocatable regs: + G2, G3, G4, + O6, // stack ptr + I6, // frame ptr + I7, // return address + G0, // constant zero + G5, G6, G7 // reserved for kernel + ]> { + let MethodProtos = [{ + iterator allocation_order_end(const MachineFunction &MF) const; + }]; + let MethodBodies = [{ + IntRegsClass::iterator + IntRegsClass::allocation_order_end(const MachineFunction &MF) const { + return end() - 10 // Don't allocate special registers + -1; + } + }]; +} +</pre> +</div> + +<p> +Using <tt>SparcRegisterInfo.td</tt> with TableGen generates several output files +that are intended for inclusion in other source code that you write. +<tt>SparcRegisterInfo.td</tt> generates <tt>SparcGenRegisterInfo.h.inc</tt>, +which should be included in the header file for the implementation of the SPARC +register implementation that you write (<tt>SparcRegisterInfo.h</tt>). In +<tt>SparcGenRegisterInfo.h.inc</tt> a new structure is defined called +<tt>SparcGenRegisterInfo</tt> that uses <tt>TargetRegisterInfo</tt> as its +base. It also specifies types, based upon the defined register +classes: <tt>DFPRegsClass</tt>, <tt>FPRegsClass</tt>, and <tt>IntRegsClass</tt>. +</p> + +<p> +<tt>SparcRegisterInfo.td</tt> also generates <tt>SparcGenRegisterInfo.inc</tt>, +which is included at the bottom of <tt>SparcRegisterInfo.cpp</tt>, the SPARC +register implementation. The code below shows only the generated integer +registers and associated register classes. The order of registers +in <tt>IntRegs</tt> reflects the order in the definition of <tt>IntRegs</tt> in +the target description file. Take special note of the use +of <tt>MethodBodies</tt> in <tt>SparcRegisterInfo.td</tt> to create code in +<tt>SparcGenRegisterInfo.inc</tt>. <tt>MethodProtos</tt> generates similar code +in <tt>SparcGenRegisterInfo.h.inc</tt>. +</p> + +<div class="doc_code"> +<pre> // IntRegs Register Class... + static const unsigned IntRegs[] = { + SP::L0, SP::L1, SP::L2, SP::L3, SP::L4, SP::L5, + SP::L6, SP::L7, SP::I0, SP::I1, SP::I2, SP::I3, + SP::I4, SP::I5, SP::O0, SP::O1, SP::O2, SP::O3, + SP::O4, SP::O5, SP::O7, SP::G1, SP::G2, SP::G3, + SP::G4, SP::O6, SP::I6, SP::I7, SP::G0, SP::G5, + SP::G6, SP::G7, + }; + + // IntRegsVTs Register Class Value Types... + static const MVT::ValueType IntRegsVTs[] = { + MVT::i32, MVT::Other + }; + +namespace SP { // Register class instances + DFPRegsClass DFPRegsRegClass; + FPRegsClass FPRegsRegClass; + IntRegsClass IntRegsRegClass; +... + // IntRegs Sub-register Classess... + static const TargetRegisterClass* const IntRegsSubRegClasses [] = { + NULL + }; +... + // IntRegs Super-register Classess... + static const TargetRegisterClass* const IntRegsSuperRegClasses [] = { + NULL + }; +... + // IntRegs Register Class sub-classes... + static const TargetRegisterClass* const IntRegsSubclasses [] = { + NULL + }; +... + // IntRegs Register Class super-classes... + static const TargetRegisterClass* const IntRegsSuperclasses [] = { + NULL + }; +... + IntRegsClass::iterator + IntRegsClass::allocation_order_end(const MachineFunction &MF) const { + return end()-10 // Don't allocate special registers + -1; + } + + IntRegsClass::IntRegsClass() : TargetRegisterClass(IntRegsRegClassID, + IntRegsVTs, IntRegsSubclasses, IntRegsSuperclasses, IntRegsSubRegClasses, + IntRegsSuperRegClasses, 4, 4, 1, IntRegs, IntRegs + 32) {} +} +</pre> +</div> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="implementRegister">Implement a subclass of</a> + <a href="http://www.llvm.org/docs/CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a> +</div> + +<div class="doc_text"> + +<p> +The final step is to hand code portions of <tt>XXXRegisterInfo</tt>, which +implements the interface described in <tt>TargetRegisterInfo.h</tt>. These +functions return <tt>0</tt>, <tt>NULL</tt>, or <tt>false</tt>, unless +overridden. Here is a list of functions that are overridden for the SPARC +implementation in <tt>SparcRegisterInfo.cpp</tt>: +</p> + +<ul> +<li><tt>getCalleeSavedRegs</tt> — Returns a list of callee-saved registers + in the order of the desired callee-save stack frame offset.</li> + +<li><tt>getCalleeSavedRegClasses</tt> — Returns a list of preferred + register classes with which to spill each callee saved register.</li> + +<li><tt>getReservedRegs</tt> — Returns a bitset indexed by physical + register numbers, indicating if a particular register is unavailable.</li> + +<li><tt>hasFP</tt> — Return a Boolean indicating if a function should have + a dedicated frame pointer register.</li> + +<li><tt>eliminateCallFramePseudoInstr</tt> — If call frame setup or + destroy pseudo instructions are used, this can be called to eliminate + them.</li> + +<li><tt>eliminateFrameIndex</tt> — Eliminate abstract frame indices from + instructions that may use them.</li> + +<li><tt>emitPrologue</tt> — Insert prologue code into the function.</li> + +<li><tt>emitEpilogue</tt> — Insert epilogue code into the function.</li> +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="InstructionSet">Instruction Set</a> +</div> + +<!-- *********************************************************************** --> +<div class="doc_text"> + +<p> +During the early stages of code generation, the LLVM IR code is converted to a +<tt>SelectionDAG</tt> with nodes that are instances of the <tt>SDNode</tt> class +containing target instructions. An <tt>SDNode</tt> has an opcode, operands, type +requirements, and operation properties. For example, is an operation +commutative, does an operation load from memory. The various operation node +types are described in the <tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt> +file (values of the <tt>NodeType</tt> enum in the <tt>ISD</tt> namespace). +</p> + +<p> +TableGen uses the following target description (<tt>.td</tt>) input files to +generate much of the code for instruction definition: +</p> + +<ul> +<li><tt>Target.td</tt> — Where the <tt>Instruction</tt>, <tt>Operand</tt>, + <tt>InstrInfo</tt>, and other fundamental classes are defined.</li> + +<li><tt>TargetSelectionDAG.td</tt>— Used by <tt>SelectionDAG</tt> + instruction selection generators, contains <tt>SDTC*</tt> classes (selection + DAG type constraint), definitions of <tt>SelectionDAG</tt> nodes (such as + <tt>imm</tt>, <tt>cond</tt>, <tt>bb</tt>, <tt>add</tt>, <tt>fadd</tt>, + <tt>sub</tt>), and pattern support (<tt>Pattern</tt>, <tt>Pat</tt>, + <tt>PatFrag</tt>, <tt>PatLeaf</tt>, <tt>ComplexPattern</tt>.</li> + +<li><tt>XXXInstrFormats.td</tt> — Patterns for definitions of + target-specific instructions.</li> + +<li><tt>XXXInstrInfo.td</tt> — Target-specific definitions of instruction + templates, condition codes, and instructions of an instruction set. For + architecture modifications, a different file name may be used. For example, + for Pentium with SSE instruction, this file is <tt>X86InstrSSE.td</tt>, and + for Pentium with MMX, this file is <tt>X86InstrMMX.td</tt>.</li> +</ul> + +<p> +There is also a target-specific <tt>XXX.td</tt> file, where <tt>XXX</tt> is the +name of the target. The <tt>XXX.td</tt> file includes the other <tt>.td</tt> +input files, but its contents are only directly important for subtargets. +</p> + +<p> +You should describe a concrete target-specific class <tt>XXXInstrInfo</tt> that +represents machine instructions supported by a target machine. +<tt>XXXInstrInfo</tt> contains an array of <tt>XXXInstrDescriptor</tt> objects, +each of which describes one instruction. An instruction descriptor defines:</p> + +<ul> +<li>Opcode mnemonic</li> + +<li>Number of operands</li> + +<li>List of implicit register definitions and uses</li> + +<li>Target-independent properties (such as memory access, is commutable)</li> + +<li>Target-specific flags </li> +</ul> + +<p> +The Instruction class (defined in <tt>Target.td</tt>) is mostly used as a base +for more complex instruction classes. +</p> + +<div class="doc_code"> +<pre>class Instruction { + string Namespace = ""; + dag OutOperandList; // An dag containing the MI def operand list. + dag InOperandList; // An dag containing the MI use operand list. + string AsmString = ""; // The .s format to print the instruction with. + list<dag> Pattern; // Set to the DAG pattern for this instruction + list<Register> Uses = []; + list<Register> Defs = []; + list<Predicate> Predicates = []; // predicates turned into isel match code + ... remainder not shown for space ... +} +</pre> +</div> + +<p> +A <tt>SelectionDAG</tt> node (<tt>SDNode</tt>) should contain an object +representing a target-specific instruction that is defined +in <tt>XXXInstrInfo.td</tt>. The instruction objects should represent +instructions from the architecture manual of the target machine (such as the +SPARC Architecture Manual for the SPARC target). +</p> + +<p> +A single instruction from the architecture manual is often modeled as multiple +target instructions, depending upon its operands. For example, a manual might +describe an add instruction that takes a register or an immediate operand. An +LLVM target could model this with two instructions named <tt>ADDri</tt> and +<tt>ADDrr</tt>. +</p> + +<p> +You should define a class for each instruction category and define each opcode +as a subclass of the category with appropriate parameters such as the fixed +binary encoding of opcodes and extended opcodes. You should map the register +bits to the bits of the instruction in which they are encoded (for the +JIT). Also you should specify how the instruction should be printed when the +automatic assembly printer is used. +</p> + +<p> +As is described in the SPARC Architecture Manual, Version 8, there are three +major 32-bit formats for instructions. Format 1 is only for the <tt>CALL</tt> +instruction. Format 2 is for branch on condition codes and <tt>SETHI</tt> (set +high bits of a register) instructions. Format 3 is for other instructions. +</p> + +<p> +Each of these formats has corresponding classes in <tt>SparcInstrFormat.td</tt>. +<tt>InstSP</tt> is a base class for other instruction classes. Additional base +classes are specified for more precise formats: for example +in <tt>SparcInstrFormat.td</tt>, <tt>F2_1</tt> is for <tt>SETHI</tt>, +and <tt>F2_2</tt> is for branches. There are three other base +classes: <tt>F3_1</tt> for register/register operations, <tt>F3_2</tt> for +register/immediate operations, and <tt>F3_3</tt> for floating-point +operations. <tt>SparcInstrInfo.td</tt> also adds the base class Pseudo for +synthetic SPARC instructions. +</p> + +<p> +<tt>SparcInstrInfo.td</tt> largely consists of operand and instruction +definitions for the SPARC target. In <tt>SparcInstrInfo.td</tt>, the following +target description file entry, <tt>LDrr</tt>, defines the Load Integer +instruction for a Word (the <tt>LD</tt> SPARC opcode) from a memory address to a +register. The first parameter, the value 3 (<tt>11<sub>2</sub></tt>), is the +operation value for this category of operation. The second parameter +(<tt>000000<sub>2</sub></tt>) is the specific operation value +for <tt>LD</tt>/Load Word. The third parameter is the output destination, which +is a register operand and defined in the <tt>Register</tt> target description +file (<tt>IntRegs</tt>). +</p> + +<div class="doc_code"> +<pre>def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr), + "ld [$addr], $dst", + [(set IntRegs:$dst, (load ADDRrr:$addr))]>; +</pre> +</div> + +<p> +The fourth parameter is the input source, which uses the address +operand <tt>MEMrr</tt> that is defined earlier in <tt>SparcInstrInfo.td</tt>: +</p> + +<div class="doc_code"> +<pre>def MEMrr : Operand<i32> { + let PrintMethod = "printMemOperand"; + let MIOperandInfo = (ops IntRegs, IntRegs); +} +</pre> +</div> + +<p> +The fifth parameter is a string that is used by the assembly printer and can be +left as an empty string until the assembly printer interface is implemented. The +sixth and final parameter is the pattern used to match the instruction during +the SelectionDAG Select Phase described in +(<a href="http://www.llvm.org/docs/CodeGenerator.html">The LLVM +Target-Independent Code Generator</a>). This parameter is detailed in the next +section, <a href="#InstructionSelector">Instruction Selector</a>. +</p> + +<p> +Instruction class definitions are not overloaded for different operand types, so +separate versions of instructions are needed for register, memory, or immediate +value operands. For example, to perform a Load Integer instruction for a Word +from an immediate operand to a register, the following instruction class is +defined: +</p> + +<div class="doc_code"> +<pre>def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr), + "ld [$addr], $dst", + [(set IntRegs:$dst, (load ADDRri:$addr))]>; +</pre> +</div> + +<p> +Writing these definitions for so many similar instructions can involve a lot of +cut and paste. In td files, the <tt>multiclass</tt> directive enables the +creation of templates to define several instruction classes at once (using +the <tt>defm</tt> directive). For example in <tt>SparcInstrInfo.td</tt>, the +<tt>multiclass</tt> pattern <tt>F3_12</tt> is defined to create 2 instruction +classes each time <tt>F3_12</tt> is invoked: +</p> + +<div class="doc_code"> +<pre>multiclass F3_12 <string OpcStr, bits<6> Op3Val, SDNode OpNode> { + def rr : F3_1 <2, Op3Val, + (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c), + !strconcat(OpcStr, " $b, $c, $dst"), + [(set IntRegs:$dst, (OpNode IntRegs:$b, IntRegs:$c))]>; + def ri : F3_2 <2, Op3Val, + (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c), + !strconcat(OpcStr, " $b, $c, $dst"), + [(set IntRegs:$dst, (OpNode IntRegs:$b, simm13:$c))]>; +} +</pre> +</div> + +<p> +So when the <tt>defm</tt> directive is used for the <tt>XOR</tt> +and <tt>ADD</tt> instructions, as seen below, it creates four instruction +objects: <tt>XORrr</tt>, <tt>XORri</tt>, <tt>ADDrr</tt>, and <tt>ADDri</tt>. +</p> + +<div class="doc_code"> +<pre> +defm XOR : F3_12<"xor", 0b000011, xor>; +defm ADD : F3_12<"add", 0b000000, add>; +</pre> +</div> + +<p> +<tt>SparcInstrInfo.td</tt> also includes definitions for condition codes that +are referenced by branch instructions. The following definitions +in <tt>SparcInstrInfo.td</tt> indicate the bit location of the SPARC condition +code. For example, the 10<sup>th</sup> bit represents the 'greater than' +condition for integers, and the 22<sup>nd</sup> bit represents the 'greater +than' condition for floats. +</p> + +<div class="doc_code"> +<pre> +def ICC_NE : ICC_VAL< 9>; // Not Equal +def ICC_E : ICC_VAL< 1>; // Equal +def ICC_G : ICC_VAL<10>; // Greater +... +def FCC_U : FCC_VAL<23>; // Unordered +def FCC_G : FCC_VAL<22>; // Greater +def FCC_UG : FCC_VAL<21>; // Unordered or Greater +... +</pre> +</div> + +<p> +(Note that <tt>Sparc.h</tt> also defines enums that correspond to the same SPARC +condition codes. Care must be taken to ensure the values in <tt>Sparc.h</tt> +correspond to the values in <tt>SparcInstrInfo.td</tt>. I.e., +<tt>SPCC::ICC_NE = 9</tt>, <tt>SPCC::FCC_U = 23</tt> and so on.) +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="operandMapping">Instruction Operand Mapping</a> +</div> + +<div class="doc_text"> + +<p> +The code generator backend maps instruction operands to fields in the +instruction. Operands are assigned to unbound fields in the instruction in the +order they are defined. Fields are bound when they are assigned a value. For +example, the Sparc target defines the <tt>XNORrr</tt> instruction as +a <tt>F3_1</tt> format instruction having three operands. +</p> + +<div class="doc_code"> +<pre> +def XNORrr : F3_1<2, 0b000111, + (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c), + "xnor $b, $c, $dst", + [(set IntRegs:$dst, (not (xor IntRegs:$b, IntRegs:$c)))]>; +</pre> +</div> + +<p> +The instruction templates in <tt>SparcInstrFormats.td</tt> show the base class +for <tt>F3_1</tt> is <tt>InstSP</tt>. +</p> + +<div class="doc_code"> +<pre> +class InstSP<dag outs, dag ins, string asmstr, list<dag> pattern> : Instruction { + field bits<32> Inst; + let Namespace = "SP"; + bits<2> op; + let Inst{31-30} = op; + dag OutOperandList = outs; + dag InOperandList = ins; + let AsmString = asmstr; + let Pattern = pattern; +} +</pre> +</div> + +<p><tt>InstSP</tt> leaves the <tt>op</tt> field unbound.</p> + +<div class="doc_code"> +<pre> +class F3<dag outs, dag ins, string asmstr, list<dag> pattern> + : InstSP<outs, ins, asmstr, pattern> { + bits<5> rd; + bits<6> op3; + bits<5> rs1; + let op{1} = 1; // Op = 2 or 3 + let Inst{29-25} = rd; + let Inst{24-19} = op3; + let Inst{18-14} = rs1; +} +</pre> +</div> + +<p> +<tt>F3</tt> binds the <tt>op</tt> field and defines the <tt>rd</tt>, +<tt>op3</tt>, and <tt>rs1</tt> fields. <tt>F3</tt> format instructions will +bind the operands <tt>rd</tt>, <tt>op3</tt>, and <tt>rs1</tt> fields. +</p> + +<div class="doc_code"> +<pre> +class F3_1<bits<2> opVal, bits<6> op3val, dag outs, dag ins, + string asmstr, list<dag> pattern> : F3<outs, ins, asmstr, pattern> { + bits<8> asi = 0; // asi not currently used + bits<5> rs2; + let op = opVal; + let op3 = op3val; + let Inst{13} = 0; // i field = 0 + let Inst{12-5} = asi; // address space identifier + let Inst{4-0} = rs2; +} +</pre> +</div> + +<p> +<tt>F3_1</tt> binds the <tt>op3</tt> field and defines the <tt>rs2</tt> +fields. <tt>F3_1</tt> format instructions will bind the operands to the <tt>rd</tt>, +<tt>rs1</tt>, and <tt>rs2</tt> fields. This results in the <tt>XNORrr</tt> +instruction binding <tt>$dst</tt>, <tt>$b</tt>, and <tt>$c</tt> operands to +the <tt>rd</tt>, <tt>rs1</tt>, and <tt>rs2</tt> fields respectively. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="implementInstr">Implement a subclass of </a> + <a href="http://www.llvm.org/docs/CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a> +</div> + +<div class="doc_text"> + +<p> +The final step is to hand code portions of <tt>XXXInstrInfo</tt>, which +implements the interface described in <tt>TargetInstrInfo.h</tt>. These +functions return <tt>0</tt> or a Boolean or they assert, unless +overridden. Here's a list of functions that are overridden for the SPARC +implementation in <tt>SparcInstrInfo.cpp</tt>: +</p> + +<ul> +<li><tt>isMoveInstr</tt> — Return true if the instruction is a register to + register move; false, otherwise.</li> + +<li><tt>isLoadFromStackSlot</tt> — If the specified machine instruction is + a direct load from a stack slot, return the register number of the + destination and the <tt>FrameIndex</tt> of the stack slot.</li> + +<li><tt>isStoreToStackSlot</tt> — If the specified machine instruction is + a direct store to a stack slot, return the register number of the + destination and the <tt>FrameIndex</tt> of the stack slot.</li> + +<li><tt>copyRegToReg</tt> — Copy values between a pair of registers.</li> + +<li><tt>storeRegToStackSlot</tt> — Store a register value to a stack + slot.</li> + +<li><tt>loadRegFromStackSlot</tt> — Load a register value from a stack + slot.</li> + +<li><tt>storeRegToAddr</tt> — Store a register value to memory.</li> + +<li><tt>loadRegFromAddr</tt> — Load a register value from memory.</li> + +<li><tt>foldMemoryOperand</tt> — Attempt to combine instructions of any + load or store instruction for the specified operand(s).</li> +</ul> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="branchFolding">Branch Folding and If Conversion</a> +</div> +<div class="doc_text"> + +<p> +Performance can be improved by combining instructions or by eliminating +instructions that are never reached. The <tt>AnalyzeBranch</tt> method +in <tt>XXXInstrInfo</tt> may be implemented to examine conditional instructions +and remove unnecessary instructions. <tt>AnalyzeBranch</tt> looks at the end of +a machine basic block (MBB) for opportunities for improvement, such as branch +folding and if conversion. The <tt>BranchFolder</tt> and <tt>IfConverter</tt> +machine function passes (see the source files <tt>BranchFolding.cpp</tt> and +<tt>IfConversion.cpp</tt> in the <tt>lib/CodeGen</tt> directory) call +<tt>AnalyzeBranch</tt> to improve the control flow graph that represents the +instructions. +</p> + +<p> +Several implementations of <tt>AnalyzeBranch</tt> (for ARM, Alpha, and X86) can +be examined as models for your own <tt>AnalyzeBranch</tt> implementation. Since +SPARC does not implement a useful <tt>AnalyzeBranch</tt>, the ARM target +implementation is shown below. +</p> + +<p><tt>AnalyzeBranch</tt> returns a Boolean value and takes four parameters:</p> + +<ul> +<li><tt>MachineBasicBlock &MBB</tt> — The incoming block to be + examined.</li> + +<li><tt>MachineBasicBlock *&TBB</tt> — A destination block that is + returned. For a conditional branch that evaluates to true, <tt>TBB</tt> is + the destination.</li> + +<li><tt>MachineBasicBlock *&FBB</tt> — For a conditional branch that + evaluates to false, <tt>FBB</tt> is returned as the destination.</li> + +<li><tt>std::vector<MachineOperand> &Cond</tt> — List of + operands to evaluate a condition for a conditional branch.</li> +</ul> + +<p> +In the simplest case, if a block ends without a branch, then it falls through to +the successor block. No destination blocks are specified for either <tt>TBB</tt> +or <tt>FBB</tt>, so both parameters return <tt>NULL</tt>. The start of +the <tt>AnalyzeBranch</tt> (see code below for the ARM target) shows the +function parameters and the code for the simplest case. +</p> + +<div class="doc_code"> +<pre>bool ARMInstrInfo::AnalyzeBranch(MachineBasicBlock &MBB, + MachineBasicBlock *&TBB, MachineBasicBlock *&FBB, + std::vector<MachineOperand> &Cond) const +{ + MachineBasicBlock::iterator I = MBB.end(); + if (I == MBB.begin() || !isUnpredicatedTerminator(--I)) + return false; +</pre> +</div> + +<p> +If a block ends with a single unconditional branch instruction, then +<tt>AnalyzeBranch</tt> (shown below) should return the destination of that +branch in the <tt>TBB</tt> parameter. +</p> + +<div class="doc_code"> +<pre> + if (LastOpc == ARM::B || LastOpc == ARM::tB) { + TBB = LastInst->getOperand(0).getMBB(); + return false; + } +</pre> +</div> + +<p> +If a block ends with two unconditional branches, then the second branch is never +reached. In that situation, as shown below, remove the last branch instruction +and return the penultimate branch in the <tt>TBB</tt> parameter. +</p> + +<div class="doc_code"> +<pre> + if ((SecondLastOpc == ARM::B || SecondLastOpc==ARM::tB) && + (LastOpc == ARM::B || LastOpc == ARM::tB)) { + TBB = SecondLastInst->getOperand(0).getMBB(); + I = LastInst; + I->eraseFromParent(); + return false; + } +</pre> +</div> + +<p> +A block may end with a single conditional branch instruction that falls through +to successor block if the condition evaluates to false. In that case, +<tt>AnalyzeBranch</tt> (shown below) should return the destination of that +conditional branch in the <tt>TBB</tt> parameter and a list of operands in +the <tt>Cond</tt> parameter to evaluate the condition. +</p> + +<div class="doc_code"> +<pre> + if (LastOpc == ARM::Bcc || LastOpc == ARM::tBcc) { + // Block ends with fall-through condbranch. + TBB = LastInst->getOperand(0).getMBB(); + Cond.push_back(LastInst->getOperand(1)); + Cond.push_back(LastInst->getOperand(2)); + return false; + } +</pre> +</div> + +<p> +If a block ends with both a conditional branch and an ensuing unconditional +branch, then <tt>AnalyzeBranch</tt> (shown below) should return the conditional +branch destination (assuming it corresponds to a conditional evaluation of +'<tt>true</tt>') in the <tt>TBB</tt> parameter and the unconditional branch +destination in the <tt>FBB</tt> (corresponding to a conditional evaluation of +'<tt>false</tt>'). A list of operands to evaluate the condition should be +returned in the <tt>Cond</tt> parameter. +</p> + +<div class="doc_code"> +<pre> + unsigned SecondLastOpc = SecondLastInst->getOpcode(); + + if ((SecondLastOpc == ARM::Bcc && LastOpc == ARM::B) || + (SecondLastOpc == ARM::tBcc && LastOpc == ARM::tB)) { + TBB = SecondLastInst->getOperand(0).getMBB(); + Cond.push_back(SecondLastInst->getOperand(1)); + Cond.push_back(SecondLastInst->getOperand(2)); + FBB = LastInst->getOperand(0).getMBB(); + return false; + } +</pre> +</div> + +<p> +For the last two cases (ending with a single conditional branch or ending with +one conditional and one unconditional branch), the operands returned in +the <tt>Cond</tt> parameter can be passed to methods of other instructions to +create new branches or perform other operations. An implementation +of <tt>AnalyzeBranch</tt> requires the helper methods <tt>RemoveBranch</tt> +and <tt>InsertBranch</tt> to manage subsequent operations. +</p> + +<p> +<tt>AnalyzeBranch</tt> should return false indicating success in most circumstances. +<tt>AnalyzeBranch</tt> should only return true when the method is stumped about what to +do, for example, if a block has three terminating branches. <tt>AnalyzeBranch</tt> may +return true if it encounters a terminator it cannot handle, such as an indirect +branch. +</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="InstructionSelector">Instruction Selector</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +LLVM uses a <tt>SelectionDAG</tt> to represent LLVM IR instructions, and nodes +of the <tt>SelectionDAG</tt> ideally represent native target +instructions. During code generation, instruction selection passes are performed +to convert non-native DAG instructions into native target-specific +instructions. The pass described in <tt>XXXISelDAGToDAG.cpp</tt> is used to +match patterns and perform DAG-to-DAG instruction selection. Optionally, a pass +may be defined (in <tt>XXXBranchSelector.cpp</tt>) to perform similar DAG-to-DAG +operations for branch instructions. Later, the code in +<tt>XXXISelLowering.cpp</tt> replaces or removes operations and data types not +supported natively (legalizes) in a <tt>SelectionDAG</tt>. +</p> + +<p> +TableGen generates code for instruction selection using the following target +description input files: +</p> + +<ul> +<li><tt>XXXInstrInfo.td</tt> — Contains definitions of instructions in a + target-specific instruction set, generates <tt>XXXGenDAGISel.inc</tt>, which + is included in <tt>XXXISelDAGToDAG.cpp</tt>.</li> + +<li><tt>XXXCallingConv.td</tt> — Contains the calling and return value + conventions for the target architecture, and it generates + <tt>XXXGenCallingConv.inc</tt>, which is included in + <tt>XXXISelLowering.cpp</tt>.</li> +</ul> + +<p> +The implementation of an instruction selection pass must include a header that +declares the <tt>FunctionPass</tt> class or a subclass of <tt>FunctionPass</tt>. In +<tt>XXXTargetMachine.cpp</tt>, a Pass Manager (PM) should add each instruction +selection pass into the queue of passes to run. +</p> + +<p> +The LLVM static compiler (<tt>llc</tt>) is an excellent tool for visualizing the +contents of DAGs. To display the <tt>SelectionDAG</tt> before or after specific +processing phases, use the command line options for <tt>llc</tt>, described +at <a href="http://llvm.org/docs/CodeGenerator.html#selectiondag_process"> +SelectionDAG Instruction Selection Process</a>. +</p> + +<p> +To describe instruction selector behavior, you should add patterns for lowering +LLVM code into a <tt>SelectionDAG</tt> as the last parameter of the instruction +definitions in <tt>XXXInstrInfo.td</tt>. For example, in +<tt>SparcInstrInfo.td</tt>, this entry defines a register store operation, and +the last parameter describes a pattern with the store DAG operator. +</p> + +<div class="doc_code"> +<pre> +def STrr : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src), + "st $src, [$addr]", [(store IntRegs:$src, ADDRrr:$addr)]>; +</pre> +</div> + +<p> +<tt>ADDRrr</tt> is a memory mode that is also defined in +<tt>SparcInstrInfo.td</tt>: +</p> + +<div class="doc_code"> +<pre> +def ADDRrr : ComplexPattern<i32, 2, "SelectADDRrr", [], []>; +</pre> +</div> + +<p> +The definition of <tt>ADDRrr</tt> refers to <tt>SelectADDRrr</tt>, which is a +function defined in an implementation of the Instructor Selector (such +as <tt>SparcISelDAGToDAG.cpp</tt>). +</p> + +<p> +In <tt>lib/Target/TargetSelectionDAG.td</tt>, the DAG operator for store is +defined below: +</p> + +<div class="doc_code"> +<pre> +def store : PatFrag<(ops node:$val, node:$ptr), + (st node:$val, node:$ptr), [{ + if (StoreSDNode *ST = dyn_cast<StoreSDNode>(N)) + return !ST->isTruncatingStore() && + ST->getAddressingMode() == ISD::UNINDEXED; + return false; +}]>; +</pre> +</div> + +<p> +<tt>XXXInstrInfo.td</tt> also generates (in <tt>XXXGenDAGISel.inc</tt>) the +<tt>SelectCode</tt> method that is used to call the appropriate processing +method for an instruction. In this example, <tt>SelectCode</tt> +calls <tt>Select_ISD_STORE</tt> for the <tt>ISD::STORE</tt> opcode. +</p> + +<div class="doc_code"> +<pre> +SDNode *SelectCode(SDValue N) { + ... + MVT::ValueType NVT = N.getNode()->getValueType(0); + switch (N.getOpcode()) { + case ISD::STORE: { + switch (NVT) { + default: + return Select_ISD_STORE(N); + break; + } + break; + } + ... +</pre> +</div> + +<p> +The pattern for <tt>STrr</tt> is matched, so elsewhere in +<tt>XXXGenDAGISel.inc</tt>, code for <tt>STrr</tt> is created for +<tt>Select_ISD_STORE</tt>. The <tt>Emit_22</tt> method is also generated +in <tt>XXXGenDAGISel.inc</tt> to complete the processing of this +instruction. +</p> + +<div class="doc_code"> +<pre> +SDNode *Select_ISD_STORE(const SDValue &N) { + SDValue Chain = N.getOperand(0); + if (Predicate_store(N.getNode())) { + SDValue N1 = N.getOperand(1); + SDValue N2 = N.getOperand(2); + SDValue CPTmp0; + SDValue CPTmp1; + + // Pattern: (st:void IntRegs:i32:$src, + // ADDRrr:i32:$addr)<<P:Predicate_store>> + // Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src) + // Pattern complexity = 13 cost = 1 size = 0 + if (SelectADDRrr(N, N2, CPTmp0, CPTmp1) && + N1.getNode()->getValueType(0) == MVT::i32 && + N2.getNode()->getValueType(0) == MVT::i32) { + return Emit_22(N, SP::STrr, CPTmp0, CPTmp1); + } +... +</pre> +</div> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="LegalizePhase">The SelectionDAG Legalize Phase</a> +</div> + +<div class="doc_text"> + +<p> +The Legalize phase converts a DAG to use types and operations that are natively +supported by the target. For natively unsupported types and operations, you need +to add code to the target-specific XXXTargetLowering implementation to convert +unsupported types and operations to supported ones. +</p> + +<p> +In the constructor for the <tt>XXXTargetLowering</tt> class, first use the +<tt>addRegisterClass</tt> method to specify which types are supports and which +register classes are associated with them. The code for the register classes are +generated by TableGen from <tt>XXXRegisterInfo.td</tt> and placed +in <tt>XXXGenRegisterInfo.h.inc</tt>. For example, the implementation of the +constructor for the SparcTargetLowering class (in +<tt>SparcISelLowering.cpp</tt>) starts with the following code: +</p> + +<div class="doc_code"> +<pre> +addRegisterClass(MVT::i32, SP::IntRegsRegisterClass); +addRegisterClass(MVT::f32, SP::FPRegsRegisterClass); +addRegisterClass(MVT::f64, SP::DFPRegsRegisterClass); +</pre> +</div> + +<p> +You should examine the node types in the <tt>ISD</tt> namespace +(<tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>) and determine which +operations the target natively supports. For operations that do <b>not</b> have +native support, add a callback to the constructor for the XXXTargetLowering +class, so the instruction selection process knows what to do. The TargetLowering +class callback methods (declared in <tt>llvm/Target/TargetLowering.h</tt>) are: +</p> + +<ul> +<li><tt>setOperationAction</tt> — General operation.</li> + +<li><tt>setLoadExtAction</tt> — Load with extension.</li> + +<li><tt>setTruncStoreAction</tt> — Truncating store.</li> + +<li><tt>setIndexedLoadAction</tt> — Indexed load.</li> + +<li><tt>setIndexedStoreAction</tt> — Indexed store.</li> + +<li><tt>setConvertAction</tt> — Type conversion.</li> + +<li><tt>setCondCodeAction</tt> — Support for a given condition code.</li> +</ul> + +<p> +Note: on older releases, <tt>setLoadXAction</tt> is used instead +of <tt>setLoadExtAction</tt>. Also, on older releases, +<tt>setCondCodeAction</tt> may not be supported. Examine your release +to see what methods are specifically supported. +</p> + +<p> +These callbacks are used to determine that an operation does or does not work +with a specified type (or types). And in all cases, the third parameter is +a <tt>LegalAction</tt> type enum value: <tt>Promote</tt>, <tt>Expand</tt>, +<tt>Custom</tt>, or <tt>Legal</tt>. <tt>SparcISelLowering.cpp</tt> +contains examples of all four <tt>LegalAction</tt> values. +</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="promote">Promote</a> +</div> + +<div class="doc_text"> + +<p> +For an operation without native support for a given type, the specified type may +be promoted to a larger type that is supported. For example, SPARC does not +support a sign-extending load for Boolean values (<tt>i1</tt> type), so +in <tt>SparcISelLowering.cpp</tt> the third parameter below, <tt>Promote</tt>, +changes <tt>i1</tt> type values to a large type before loading. +</p> + +<div class="doc_code"> +<pre> +setLoadExtAction(ISD::SEXTLOAD, MVT::i1, Promote); +</pre> +</div> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="expand">Expand</a> +</div> + +<div class="doc_text"> + +<p> +For a type without native support, a value may need to be broken down further, +rather than promoted. For an operation without native support, a combination of +other operations may be used to similar effect. In SPARC, the floating-point +sine and cosine trig operations are supported by expansion to other operations, +as indicated by the third parameter, <tt>Expand</tt>, to +<tt>setOperationAction</tt>: +</p> + +<div class="doc_code"> +<pre> +setOperationAction(ISD::FSIN, MVT::f32, Expand); +setOperationAction(ISD::FCOS, MVT::f32, Expand); +</pre> +</div> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="custom">Custom</a> +</div> + +<div class="doc_text"> + +<p> +For some operations, simple type promotion or operation expansion may be +insufficient. In some cases, a special intrinsic function must be implemented. +</p> + +<p> +For example, a constant value may require special treatment, or an operation may +require spilling and restoring registers in the stack and working with register +allocators. +</p> + +<p> +As seen in <tt>SparcISelLowering.cpp</tt> code below, to perform a type +conversion from a floating point value to a signed integer, first the +<tt>setOperationAction</tt> should be called with <tt>Custom</tt> as the third +parameter: +</p> + +<div class="doc_code"> +<pre> +setOperationAction(ISD::FP_TO_SINT, MVT::i32, Custom); +</pre> +</div> + +<p> +In the <tt>LowerOperation</tt> method, for each <tt>Custom</tt> operation, a +case statement should be added to indicate what function to call. In the +following code, an <tt>FP_TO_SINT</tt> opcode will call +the <tt>LowerFP_TO_SINT</tt> method: +</p> + +<div class="doc_code"> +<pre> +SDValue SparcTargetLowering::LowerOperation(SDValue Op, SelectionDAG &DAG) { + switch (Op.getOpcode()) { + case ISD::FP_TO_SINT: return LowerFP_TO_SINT(Op, DAG); + ... + } +} +</pre> +</div> + +<p> +Finally, the <tt>LowerFP_TO_SINT</tt> method is implemented, using an FP +register to convert the floating-point value to an integer. +</p> + +<div class="doc_code"> +<pre> +static SDValue LowerFP_TO_SINT(SDValue Op, SelectionDAG &DAG) { + assert(Op.getValueType() == MVT::i32); + Op = DAG.getNode(SPISD::FTOI, MVT::f32, Op.getOperand(0)); + return DAG.getNode(ISD::BIT_CONVERT, MVT::i32, Op); +} +</pre> +</div> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="legal">Legal</a> +</div> + +<div class="doc_text"> + +<p> +The <tt>Legal</tt> LegalizeAction enum value simply indicates that an +operation <b>is</b> natively supported. <tt>Legal</tt> represents the default +condition, so it is rarely used. In <tt>SparcISelLowering.cpp</tt>, the action +for <tt>CTPOP</tt> (an operation to count the bits set in an integer) is +natively supported only for SPARC v9. The following code enables +the <tt>Expand</tt> conversion technique for non-v9 SPARC implementations. +</p> + +<div class="doc_code"> +<pre> +setOperationAction(ISD::CTPOP, MVT::i32, Expand); +... +if (TM.getSubtarget<SparcSubtarget>().isV9()) + setOperationAction(ISD::CTPOP, MVT::i32, Legal); + case ISD::SETULT: return SPCC::ICC_CS; + case ISD::SETULE: return SPCC::ICC_LEU; + case ISD::SETUGT: return SPCC::ICC_GU; + case ISD::SETUGE: return SPCC::ICC_CC; + } +} +</pre> +</div> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="callingConventions">Calling Conventions</a> +</div> + +<div class="doc_text"> + +<p> +To support target-specific calling conventions, <tt>XXXGenCallingConv.td</tt> +uses interfaces (such as CCIfType and CCAssignToReg) that are defined in +<tt>lib/Target/TargetCallingConv.td</tt>. TableGen can take the target +descriptor file <tt>XXXGenCallingConv.td</tt> and generate the header +file <tt>XXXGenCallingConv.inc</tt>, which is typically included +in <tt>XXXISelLowering.cpp</tt>. You can use the interfaces in +<tt>TargetCallingConv.td</tt> to specify: +</p> + +<ul> +<li>The order of parameter allocation.</li> + +<li>Where parameters and return values are placed (that is, on the stack or in + registers).</li> + +<li>Which registers may be used.</li> + +<li>Whether the caller or callee unwinds the stack.</li> +</ul> + +<p> +The following example demonstrates the use of the <tt>CCIfType</tt> and +<tt>CCAssignToReg</tt> interfaces. If the <tt>CCIfType</tt> predicate is true +(that is, if the current argument is of type <tt>f32</tt> or <tt>f64</tt>), then +the action is performed. In this case, the <tt>CCAssignToReg</tt> action assigns +the argument value to the first available register: either <tt>R0</tt> +or <tt>R1</tt>. +</p> + +<div class="doc_code"> +<pre> +CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>> +</pre> +</div> + +<p> +<tt>SparcCallingConv.td</tt> contains definitions for a target-specific +return-value calling convention (RetCC_Sparc32) and a basic 32-bit C calling +convention (<tt>CC_Sparc32</tt>). The definition of <tt>RetCC_Sparc32</tt> +(shown below) indicates which registers are used for specified scalar return +types. A single-precision float is returned to register <tt>F0</tt>, and a +double-precision float goes to register <tt>D0</tt>. A 32-bit integer is +returned in register <tt>I0</tt> or <tt>I1</tt>. +</p> + +<div class="doc_code"> +<pre> +def RetCC_Sparc32 : CallingConv<[ + CCIfType<[i32], CCAssignToReg<[I0, I1]>>, + CCIfType<[f32], CCAssignToReg<[F0]>>, + CCIfType<[f64], CCAssignToReg<[D0]>> +]>; +</pre> +</div> + +<p> +The definition of <tt>CC_Sparc32</tt> in <tt>SparcCallingConv.td</tt> introduces +<tt>CCAssignToStack</tt>, which assigns the value to a stack slot with the +specified size and alignment. In the example below, the first parameter, 4, +indicates the size of the slot, and the second parameter, also 4, indicates the +stack alignment along 4-byte units. (Special cases: if size is zero, then the +ABI size is used; if alignment is zero, then the ABI alignment is used.) +</p> + +<div class="doc_code"> +<pre> +def CC_Sparc32 : CallingConv<[ + // All arguments get passed in integer registers if there is space. + CCIfType<[i32, f32, f64], CCAssignToReg<[I0, I1, I2, I3, I4, I5]>>, + CCAssignToStack<4, 4> +]>; +</pre> +</div> + +<p> +<tt>CCDelegateTo</tt> is another commonly used interface, which tries to find a +specified sub-calling convention, and, if a match is found, it is invoked. In +the following example (in <tt>X86CallingConv.td</tt>), the definition of +<tt>RetCC_X86_32_C</tt> ends with <tt>CCDelegateTo</tt>. After the current value +is assigned to the register <tt>ST0</tt> or <tt>ST1</tt>, +the <tt>RetCC_X86Common</tt> is invoked. +</p> + +<div class="doc_code"> +<pre> +def RetCC_X86_32_C : CallingConv<[ + CCIfType<[f32], CCAssignToReg<[ST0, ST1]>>, + CCIfType<[f64], CCAssignToReg<[ST0, ST1]>>, + CCDelegateTo<RetCC_X86Common> +]>; +</pre> +</div> + +<p> +<tt>CCIfCC</tt> is an interface that attempts to match the given name to the +current calling convention. If the name identifies the current calling +convention, then a specified action is invoked. In the following example (in +<tt>X86CallingConv.td</tt>), if the <tt>Fast</tt> calling convention is in use, +then <tt>RetCC_X86_32_Fast</tt> is invoked. If the <tt>SSECall</tt> calling +convention is in use, then <tt>RetCC_X86_32_SSE</tt> is invoked. +</p> + +<div class="doc_code"> +<pre> +def RetCC_X86_32 : CallingConv<[ + CCIfCC<"CallingConv::Fast", CCDelegateTo<RetCC_X86_32_Fast>>, + CCIfCC<"CallingConv::X86_SSECall", CCDelegateTo<RetCC_X86_32_SSE>>, + CCDelegateTo<RetCC_X86_32_C> +]>; +</pre> +</div> + +<p>Other calling convention interfaces include:</p> + +<ul> +<li><tt>CCIf <predicate, action></tt> — If the predicate matches, + apply the action.</li> + +<li><tt>CCIfInReg <action></tt> — If the argument is marked with the + '<tt>inreg</tt>' attribute, then apply the action.</li> + +<li><tt>CCIfNest <action></tt> — Inf the argument is marked with the + '<tt>nest</tt>' attribute, then apply the action.</li> + +<li><tt>CCIfNotVarArg <action></tt> — If the current function does + not take a variable number of arguments, apply the action.</li> + +<li><tt>CCAssignToRegWithShadow <registerList, shadowList></tt> — + similar to <tt>CCAssignToReg</tt>, but with a shadow list of registers.</li> + +<li><tt>CCPassByVal <size, align></tt> — Assign value to a stack + slot with the minimum specified size and alignment.</li> + +<li><tt>CCPromoteToType <type></tt> — Promote the current value to + the specified type.</li> + +<li><tt>CallingConv <[actions]></tt> — Define each calling + convention that is supported.</li> +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="assemblyPrinter">Assembly Printer</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +During the code emission stage, the code generator may utilize an LLVM pass to +produce assembly output. To do this, you want to implement the code for a +printer that converts LLVM IR to a GAS-format assembly language for your target +machine, using the following steps: +</p> + +<ul> +<li>Define all the assembly strings for your target, adding them to the + instructions defined in the <tt>XXXInstrInfo.td</tt> file. + (See <a href="#InstructionSet">Instruction Set</a>.) TableGen will produce + an output file (<tt>XXXGenAsmWriter.inc</tt>) with an implementation of + the <tt>printInstruction</tt> method for the XXXAsmPrinter class.</li> + +<li>Write <tt>XXXTargetAsmInfo.h</tt>, which contains the bare-bones declaration + of the <tt>XXXTargetAsmInfo</tt> class (a subclass + of <tt>TargetAsmInfo</tt>).</li> + +<li>Write <tt>XXXTargetAsmInfo.cpp</tt>, which contains target-specific values + for <tt>TargetAsmInfo</tt> properties and sometimes new implementations for + methods.</li> + +<li>Write <tt>XXXAsmPrinter.cpp</tt>, which implements the <tt>AsmPrinter</tt> + class that performs the LLVM-to-assembly conversion.</li> +</ul> + +<p> +The code in <tt>XXXTargetAsmInfo.h</tt> is usually a trivial declaration of the +<tt>XXXTargetAsmInfo</tt> class for use in <tt>XXXTargetAsmInfo.cpp</tt>. +Similarly, <tt>XXXTargetAsmInfo.cpp</tt> usually has a few declarations of +<tt>XXXTargetAsmInfo</tt> replacement values that override the default values +in <tt>TargetAsmInfo.cpp</tt>. For example in <tt>SparcTargetAsmInfo.cpp</tt>: +</p> + +<div class="doc_code"> +<pre> +SparcTargetAsmInfo::SparcTargetAsmInfo(const SparcTargetMachine &TM) { + Data16bitsDirective = "\t.half\t"; + Data32bitsDirective = "\t.word\t"; + Data64bitsDirective = 0; // .xword is only supported by V9. + ZeroDirective = "\t.skip\t"; + CommentString = "!"; + ConstantPoolSection = "\t.section \".rodata\",#alloc\n"; +} +</pre> +</div> + +<p> +The X86 assembly printer implementation (<tt>X86TargetAsmInfo</tt>) is an +example where the target specific <tt>TargetAsmInfo</tt> class uses an +overridden methods: <tt>ExpandInlineAsm</tt>. +</p> + +<p> +A target-specific implementation of AsmPrinter is written in +<tt>XXXAsmPrinter.cpp</tt>, which implements the <tt>AsmPrinter</tt> class that +converts the LLVM to printable assembly. The implementation must include the +following headers that have declarations for the <tt>AsmPrinter</tt> and +<tt>MachineFunctionPass</tt> classes. The <tt>MachineFunctionPass</tt> is a +subclass of <tt>FunctionPass</tt>. +</p> + +<div class="doc_code"> +<pre> +#include "llvm/CodeGen/AsmPrinter.h" +#include "llvm/CodeGen/MachineFunctionPass.h" +</pre> +</div> + +<p> +As a <tt>FunctionPass</tt>, <tt>AsmPrinter</tt> first +calls <tt>doInitialization</tt> to set up the <tt>AsmPrinter</tt>. In +<tt>SparcAsmPrinter</tt>, a <tt>Mangler</tt> object is instantiated to process +variable names. +</p> + +<p> +In <tt>XXXAsmPrinter.cpp</tt>, the <tt>runOnMachineFunction</tt> method +(declared in <tt>MachineFunctionPass</tt>) must be implemented +for <tt>XXXAsmPrinter</tt>. In <tt>MachineFunctionPass</tt>, +the <tt>runOnFunction</tt> method invokes <tt>runOnMachineFunction</tt>. +Target-specific implementations of <tt>runOnMachineFunction</tt> differ, but +generally do the following to process each machine function: +</p> + +<ul> +<li>Call <tt>SetupMachineFunction</tt> to perform initialization.</li> + +<li>Call <tt>EmitConstantPool</tt> to print out (to the output stream) constants + which have been spilled to memory.</li> + +<li>Call <tt>EmitJumpTableInfo</tt> to print out jump tables used by the current + function.</li> + +<li>Print out the label for the current function.</li> + +<li>Print out the code for the function, including basic block labels and the + assembly for the instruction (using <tt>printInstruction</tt>)</li> +</ul> + +<p> +The <tt>XXXAsmPrinter</tt> implementation must also include the code generated +by TableGen that is output in the <tt>XXXGenAsmWriter.inc</tt> file. The code +in <tt>XXXGenAsmWriter.inc</tt> contains an implementation of the +<tt>printInstruction</tt> method that may call these methods: +</p> + +<ul> +<li><tt>printOperand</tt></li> + +<li><tt>printMemOperand</tt></li> + +<li><tt>printCCOperand (for conditional statements)</tt></li> + +<li><tt>printDataDirective</tt></li> + +<li><tt>printDeclare</tt></li> + +<li><tt>printImplicitDef</tt></li> + +<li><tt>printInlineAsm</tt></li> +</ul> + +<p> +The implementations of <tt>printDeclare</tt>, <tt>printImplicitDef</tt>, +<tt>printInlineAsm</tt>, and <tt>printLabel</tt> in <tt>AsmPrinter.cpp</tt> are +generally adequate for printing assembly and do not need to be +overridden. +</p> + +<p> +The <tt>printOperand</tt> method is implemented with a long switch/case +statement for the type of operand: register, immediate, basic block, external +symbol, global address, constant pool index, or jump table index. For an +instruction with a memory address operand, the <tt>printMemOperand</tt> method +should be implemented to generate the proper output. Similarly, +<tt>printCCOperand</tt> should be used to print a conditional operand. +</p> + +<p><tt>doFinalization</tt> should be overridden in <tt>XXXAsmPrinter</tt>, and +it should be called to shut down the assembly printer. During +<tt>doFinalization</tt>, global variables and constants are printed to +output. +</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="subtargetSupport">Subtarget Support</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +Subtarget support is used to inform the code generation process of instruction +set variations for a given chip set. For example, the LLVM SPARC implementation +provided covers three major versions of the SPARC microprocessor architecture: +Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a 64-bit +architecture), and the UltraSPARC architecture. V8 has 16 double-precision +floating-point registers that are also usable as either 32 single-precision or 8 +quad-precision registers. V8 is also purely big-endian. V9 has 32 +double-precision floating-point registers that are also usable as 16 +quad-precision registers, but cannot be used as single-precision registers. The +UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set +extensions. +</p> + +<p> +If subtarget support is needed, you should implement a target-specific +XXXSubtarget class for your architecture. This class should process the +command-line options <tt>-mcpu=</tt> and <tt>-mattr=</tt>. +</p> + +<p> +TableGen uses definitions in the <tt>Target.td</tt> and <tt>Sparc.td</tt> files +to generate code in <tt>SparcGenSubtarget.inc</tt>. In <tt>Target.td</tt>, shown +below, the <tt>SubtargetFeature</tt> interface is defined. The first 4 string +parameters of the <tt>SubtargetFeature</tt> interface are a feature name, an +attribute set by the feature, the value of the attribute, and a description of +the feature. (The fifth parameter is a list of features whose presence is +implied, and its default value is an empty array.) +</p> + +<div class="doc_code"> +<pre> +class SubtargetFeature<string n, string a, string v, string d, + list<SubtargetFeature> i = []> { + string Name = n; + string Attribute = a; + string Value = v; + string Desc = d; + list<SubtargetFeature> Implies = i; +} +</pre> +</div> + +<p> +In the <tt>Sparc.td</tt> file, the SubtargetFeature is used to define the +following features. +</p> + +<div class="doc_code"> +<pre> +def FeatureV9 : SubtargetFeature<"v9", "IsV9", "true", + "Enable SPARC-V9 instructions">; +def FeatureV8Deprecated : SubtargetFeature<"deprecated-v8", + "V8DeprecatedInsts", "true", + "Enable deprecated V8 instructions in V9 mode">; +def FeatureVIS : SubtargetFeature<"vis", "IsVIS", "true", + "Enable UltraSPARC Visual Instruction Set extensions">; +</pre> +</div> + +<p> +Elsewhere in <tt>Sparc.td</tt>, the Proc class is defined and then is used to +define particular SPARC processor subtypes that may have the previously +described features. +</p> + +<div class="doc_code"> +<pre> +class Proc<string Name, list<SubtargetFeature> Features> + : Processor<Name, NoItineraries, Features>; + +def : Proc<"generic", []>; +def : Proc<"v8", []>; +def : Proc<"supersparc", []>; +def : Proc<"sparclite", []>; +def : Proc<"f934", []>; +def : Proc<"hypersparc", []>; +def : Proc<"sparclite86x", []>; +def : Proc<"sparclet", []>; +def : Proc<"tsc701", []>; +def : Proc<"v9", [FeatureV9]>; +def : Proc<"ultrasparc", [FeatureV9, FeatureV8Deprecated]>; +def : Proc<"ultrasparc3", [FeatureV9, FeatureV8Deprecated]>; +def : Proc<"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]>; +</pre> +</div> + +<p> +From <tt>Target.td</tt> and <tt>Sparc.td</tt> files, the resulting +SparcGenSubtarget.inc specifies enum values to identify the features, arrays of +constants to represent the CPU features and CPU subtypes, and the +ParseSubtargetFeatures method that parses the features string that sets +specified subtarget options. The generated <tt>SparcGenSubtarget.inc</tt> file +should be included in the <tt>SparcSubtarget.cpp</tt>. The target-specific +implementation of the XXXSubtarget method should follow this pseudocode: +</p> + +<div class="doc_code"> +<pre> +XXXSubtarget::XXXSubtarget(const Module &M, const std::string &FS) { + // Set the default features + // Determine default and user specified characteristics of the CPU + // Call ParseSubtargetFeatures(FS, CPU) to parse the features string + // Perform any additional operations +} +</pre> +</div> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="jitSupport">JIT Support</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p> +The implementation of a target machine optionally includes a Just-In-Time (JIT) +code generator that emits machine code and auxiliary structures as binary output +that can be written directly to memory. To do this, implement JIT code +generation by performing the following steps: +</p> + +<ul> +<li>Write an <tt>XXXCodeEmitter.cpp</tt> file that contains a machine function + pass that transforms target-machine instructions into relocatable machine + code.</li> + +<li>Write an <tt>XXXJITInfo.cpp</tt> file that implements the JIT interfaces for + target-specific code-generation activities, such as emitting machine code + and stubs.</li> + +<li>Modify <tt>XXXTargetMachine</tt> so that it provides a + <tt>TargetJITInfo</tt> object through its <tt>getJITInfo</tt> method.</li> +</ul> + +<p> +There are several different approaches to writing the JIT support code. For +instance, TableGen and target descriptor files may be used for creating a JIT +code generator, but are not mandatory. For the Alpha and PowerPC target +machines, TableGen is used to generate <tt>XXXGenCodeEmitter.inc</tt>, which +contains the binary coding of machine instructions and the +<tt>getBinaryCodeForInstr</tt> method to access those codes. Other JIT +implementations do not. +</p> + +<p> +Both <tt>XXXJITInfo.cpp</tt> and <tt>XXXCodeEmitter.cpp</tt> must include the +<tt>llvm/CodeGen/MachineCodeEmitter.h</tt> header file that defines the +<tt>MachineCodeEmitter</tt> class containing code for several callback functions +that write data (in bytes, words, strings, etc.) to the output stream. +</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="mce">Machine Code Emitter</a> +</div> + +<div class="doc_text"> + +<p> +In <tt>XXXCodeEmitter.cpp</tt>, a target-specific of the <tt>Emitter</tt> class +is implemented as a function pass (subclass +of <tt>MachineFunctionPass</tt>). The target-specific implementation +of <tt>runOnMachineFunction</tt> (invoked by +<tt>runOnFunction</tt> in <tt>MachineFunctionPass</tt>) iterates through the +<tt>MachineBasicBlock</tt> calls <tt>emitInstruction</tt> to process each +instruction and emit binary code. <tt>emitInstruction</tt> is largely +implemented with case statements on the instruction types defined in +<tt>XXXInstrInfo.h</tt>. For example, in <tt>X86CodeEmitter.cpp</tt>, +the <tt>emitInstruction</tt> method is built around the following switch/case +statements: +</p> + +<div class="doc_code"> +<pre> +switch (Desc->TSFlags & X86::FormMask) { +case X86II::Pseudo: // for not yet implemented instructions + ... // or pseudo-instructions + break; +case X86II::RawFrm: // for instructions with a fixed opcode value + ... + break; +case X86II::AddRegFrm: // for instructions that have one register operand + ... // added to their opcode + break; +case X86II::MRMDestReg:// for instructions that use the Mod/RM byte + ... // to specify a destination (register) + break; +case X86II::MRMDestMem:// for instructions that use the Mod/RM byte + ... // to specify a destination (memory) + break; +case X86II::MRMSrcReg: // for instructions that use the Mod/RM byte + ... // to specify a source (register) + break; +case X86II::MRMSrcMem: // for instructions that use the Mod/RM byte + ... // to specify a source (memory) + break; +case X86II::MRM0r: case X86II::MRM1r: // for instructions that operate on +case X86II::MRM2r: case X86II::MRM3r: // a REGISTER r/m operand and +case X86II::MRM4r: case X86II::MRM5r: // use the Mod/RM byte and a field +case X86II::MRM6r: case X86II::MRM7r: // to hold extended opcode data + ... + break; +case X86II::MRM0m: case X86II::MRM1m: // for instructions that operate on +case X86II::MRM2m: case X86II::MRM3m: // a MEMORY r/m operand and +case X86II::MRM4m: case X86II::MRM5m: // use the Mod/RM byte and a field +case X86II::MRM6m: case X86II::MRM7m: // to hold extended opcode data + ... + break; +case X86II::MRMInitReg: // for instructions whose source and + ... // destination are the same register + break; +} +</pre> +</div> + +<p> +The implementations of these case statements often first emit the opcode and +then get the operand(s). Then depending upon the operand, helper methods may be +called to process the operand(s). For example, in <tt>X86CodeEmitter.cpp</tt>, +for the <tt>X86II::AddRegFrm</tt> case, the first data emitted +(by <tt>emitByte</tt>) is the opcode added to the register operand. Then an +object representing the machine operand, <tt>MO1</tt>, is extracted. The helper +methods such as <tt>isImmediate</tt>, +<tt>isGlobalAddress</tt>, <tt>isExternalSymbol</tt>, <tt>isConstantPoolIndex</tt>, and +<tt>isJumpTableIndex</tt> determine the operand +type. (<tt>X86CodeEmitter.cpp</tt> also has private methods such +as <tt>emitConstant</tt>, <tt>emitGlobalAddress</tt>, +<tt>emitExternalSymbolAddress</tt>, <tt>emitConstPoolAddress</tt>, +and <tt>emitJumpTableAddress</tt> that emit the data into the output stream.) +</p> + +<div class="doc_code"> +<pre> +case X86II::AddRegFrm: + MCE.emitByte(BaseOpcode + getX86RegNum(MI.getOperand(CurOp++).getReg())); + + if (CurOp != NumOps) { + const MachineOperand &MO1 = MI.getOperand(CurOp++); + unsigned Size = X86InstrInfo::sizeOfImm(Desc); + if (MO1.isImmediate()) + emitConstant(MO1.getImm(), Size); + else { + unsigned rt = Is64BitMode ? X86::reloc_pcrel_word + : (IsPIC ? X86::reloc_picrel_word : X86::reloc_absolute_word); + if (Opcode == X86::MOV64ri) + rt = X86::reloc_absolute_dword; // FIXME: add X86II flag? + if (MO1.isGlobalAddress()) { + bool NeedStub = isa<Function>(MO1.getGlobal()); + bool isLazy = gvNeedsLazyPtr(MO1.getGlobal()); + emitGlobalAddress(MO1.getGlobal(), rt, MO1.getOffset(), 0, + NeedStub, isLazy); + } else if (MO1.isExternalSymbol()) + emitExternalSymbolAddress(MO1.getSymbolName(), rt); + else if (MO1.isConstantPoolIndex()) + emitConstPoolAddress(MO1.getIndex(), rt); + else if (MO1.isJumpTableIndex()) + emitJumpTableAddress(MO1.getIndex(), rt); + } + } + break; +</pre> +</div> + +<p> +In the previous example, <tt>XXXCodeEmitter.cpp</tt> uses the +variable <tt>rt</tt>, which is a RelocationType enum that may be used to +relocate addresses (for example, a global address with a PIC base offset). The +<tt>RelocationType</tt> enum for that target is defined in the short +target-specific <tt>XXXRelocations.h</tt> file. The <tt>RelocationType</tt> is used by +the <tt>relocate</tt> method defined in <tt>XXXJITInfo.cpp</tt> to rewrite +addresses for referenced global symbols. +</p> + +<p> +For example, <tt>X86Relocations.h</tt> specifies the following relocation types +for the X86 addresses. In all four cases, the relocated value is added to the +value already in memory. For <tt>reloc_pcrel_word</tt> +and <tt>reloc_picrel_word</tt>, there is an additional initial adjustment. +</p> + +<div class="doc_code"> +<pre> +enum RelocationType { + reloc_pcrel_word = 0, // add reloc value after adjusting for the PC loc + reloc_picrel_word = 1, // add reloc value after adjusting for the PIC base + reloc_absolute_word = 2, // absolute relocation; no additional adjustment + reloc_absolute_dword = 3 // absolute relocation; no additional adjustment +}; +</pre> +</div> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="targetJITInfo">Target JIT Info</a> +</div> + +<div class="doc_text"> + +<p> +<tt>XXXJITInfo.cpp</tt> implements the JIT interfaces for target-specific +code-generation activities, such as emitting machine code and stubs. At minimum, +a target-specific version of <tt>XXXJITInfo</tt> implements the following: +</p> + +<ul> +<li><tt>getLazyResolverFunction</tt> — Initializes the JIT, gives the + target a function that is used for compilation.</li> + +<li><tt>emitFunctionStub</tt> — Returns a native function with a specified + address for a callback function.</li> + +<li><tt>relocate</tt> — Changes the addresses of referenced globals, based + on relocation types.</li> + +<li>Callback function that are wrappers to a function stub that is used when the + real target is not initially known.</li> +</ul> + +<p> +<tt>getLazyResolverFunction</tt> is generally trivial to implement. It makes the +incoming parameter as the global <tt>JITCompilerFunction</tt> and returns the +callback function that will be used a function wrapper. For the Alpha target +(in <tt>AlphaJITInfo.cpp</tt>), the <tt>getLazyResolverFunction</tt> +implementation is simply: +</p> + +<div class="doc_code"> +<pre> +TargetJITInfo::LazyResolverFn AlphaJITInfo::getLazyResolverFunction( + JITCompilerFn F) { + JITCompilerFunction = F; + return AlphaCompilationCallback; +} +</pre> +</div> + +<p> +For the X86 target, the <tt>getLazyResolverFunction</tt> implementation is a +little more complication, because it returns a different callback function for +processors with SSE instructions and XMM registers. +</p> + +<p> +The callback function initially saves and later restores the callee register +values, incoming arguments, and frame and return address. The callback function +needs low-level access to the registers or stack, so it is typically implemented +with assembler. +</p> + +</div> + +<!-- *********************************************************************** --> + +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> + + <a href="http://www.woo.com">Mason Woo</a> and <a href="http://misha.brukman.net">Misha Brukman</a><br> + <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> + <br> + Last modified: $Date$ +</address> + +</body> +</html> |