diff options
| author | Chris Lattner <sabre@nondot.org> | 2008-11-11 19:30:41 +0000 |
|---|---|---|
| committer | Chris Lattner <sabre@nondot.org> | 2008-11-11 19:30:41 +0000 |
| commit | 7897538376ee96dabc010481dddbab4292991fb0 (patch) | |
| tree | f0ef26bbd717436877a6e8275959a953cb7f7194 /docs | |
| parent | 89d0a4dd8446bba2a233d76043d9151fd40a27d0 (diff) | |
| download | llvm-7897538376ee96dabc010481dddbab4292991fb0.tar.gz llvm-7897538376ee96dabc010481dddbab4292991fb0.tar.bz2 llvm-7897538376ee96dabc010481dddbab4292991fb0.tar.xz | |
Make this document *substantially* better and cover a lot more territory.
Document written by Mason Woo (http://www.woo.com)!
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@59066 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/WritingAnLLVMBackend.html | 2145 |
1 files changed, 1957 insertions, 188 deletions
diff --git a/docs/WritingAnLLVMBackend.html b/docs/WritingAnLLVMBackend.html index bddc021a32..a19f6494de 100644 --- a/docs/WritingAnLLVMBackend.html +++ b/docs/WritingAnLLVMBackend.html @@ -2,32 +2,58 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> - <title>Writing an LLVM backend</title> + <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 backend +<div class="doc_title"><p> + Writing an LLVM Compiler Backend </div> <ol> <li><a href="#intro">Introduction</a> - <li><a href="#backends">Writing a backend</a> - <ol> - <li><a href="#machine">Machine backends</a> - <ol> - <li><a href="#machineTOC">Outline</a></li> - <li><a href="#machineDetails">Implementation details</a></li> - </ol></li> - <li><a href="#lang">Language backends</a></li> - </ol></li> - <li><a href="#related">Related reading material</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="#RegisterSet">Register Set and Register Classes</a></li> + <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><a href="#InstructionSet">Instruction Set</a></li> + <ul> + <li><a href="#implementInstr">Implement a subclass of TargetInstrInfo</a></li> + <li><a href="#branchFolding">Branch Folding and If Conversion</a></li> + </ul> + <li><a href="#InstructionSelector">Instruction Selector</a></li> + <ul> + <li><a href="#LegalizePhase">The SelectionDAG Legalize Phase</a></li> + <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><a href="#callingConventions">Calling Conventions</a></li> + </ul> + <li><a href="#assemblyPrinter">Assembly Printer</a></li> + <li><a href="#subtargetSupport">Subtarget Support</a></li> + <li><a href="#jitSupport">JIT Support</a></li> + <ul> + <li><a href="#mce">Machine Code Emitter</a></li> + <li><a href="#targetJITInfo">Target JIT Info</a></li> + </ul> </ol> <div class="doc_author"> - <p>Written by <a href="http://misha.brukman.net">Misha Brukman</a></p> + <p>Written by <a href="http://www.woo.com">Mason Woo</a> and <a href="http://misha.brukman.net">Misha Brukman</a></p> </div> <!-- *********************************************************************** --> @@ -37,258 +63,2001 @@ <!-- *********************************************************************** --> <div class="doc_text"> +<p>This document describes techniques for writing compiler backends +that convert the LLVM IR (intermediate representation) 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> -<p>This document describes techniques for writing backends for LLVM which -convert the LLVM representation to machine assembly code or other languages.</p> +<div class="doc_subsection"> + <a name="Prerequisite">Prerequisite Reading</a> +</div> +<div class="doc_text"> +These essential documents must be read before reading this document: +<ul> +<li> +<it><a href="http://www.llvm.org/docs/LangRef.html">LLVM Language Reference Manual</a></it> - +a reference manual for the LLVM assembly language +</li> +<li> +<it><a href="http://www.llvm.org/docs/CodeGenerator.html">The LLVM Target-Independent Code Generator </a></it> - +a guide to the components (classes and code generation algorithms) for translating +the LLVM internal representation to the 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> +<it><a href="http://www.llvm.org/docs/TableGenFundamentals.html">TableGen Fundamentals</a></it> - +a document that describes the TableGen (tblgen) application that manages domain-specific +information to support LLVM code generation. TableGen processes input from a +target description file (.td suffix) and generates C++ code that can be used +for code generation. +</li> +<li> +<it><a href="http://www.llvm.org/docs/WritingAnLLVMPass.html">Writing an LLVM Pass</a></it> - +The assembly printer is a FunctionPass, as are several SelectionDAG processing steps. +</li> +</ul> +To follow the SPARC examples in this document, have a copy of +<it><a href="http://www.sparc.org/standards/V8.pdf">The SPARC Architecture Manual, Version 8</a></it> +for reference. For details about the ARM instruction set, refer to the +<it><a href="http://infocenter.arm.com/">ARM Architecture Reference Manual</a></it> +For more about the GNU Assembler format (GAS), see +<it><a href="http://sourceware.org/binutils/docs/as/index.html">Using As</a></it> +especially for the assembly printer. <it>Using As</it> contains lists of target machine dependent features. +</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 (intermediate representation) +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 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 DAG (directed +acyclic graph) 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 (that is, 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 .cpp and .h 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 LLVMDummy (for example, see the MIPS target). Alternatively, you can +split the library into LLVMDummyCodeGen and LLVMDummyAsmPrinter, 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 lots 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 TargetMachine. 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 LLVMTargetMachine. (To create a target from scratch, create a subclass of +TargetMachine.)</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="backends">Writing a backend</a> + <a name="TargetMachine">Target Machine</a> </div> <!-- *********************************************************************** --> +<div class="doc_text"> +<p>LLVMTargetMachine is designed as a base class for targets +implemented with the LLVM target-independent code generator. The +LLVMTargetMachine class should be specialized by a concrete target class that +implements the various virtual methods. LLVMTargetMachine is defined as a +subclass of TargetMachine in <tt>include/llvm/Target/TargetMachine.h</tt>. The +TargetMachine class implementation (<tt>TargetMachine.cpp</tt>) also processes numerous +command-line options. </p> + +<p>To create a concrete target-specific subclass of +LLVMTargetMachine, start by copying an existing TargetMachine 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 XXX, the implementation of XXXTargetMachine +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. XXXTargetMachine 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> + +<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); + virtual bool addAssemblyEmitter(PassManagerBase &PM, bool Fast, + std::ostream &Out); +}; + +} // end namespace llvm +</pre> +</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 XXXTargetMachine constructor should specify a +TargetDescription 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> + +<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 class="doc_text"> +<p>Hyphens separate portions of the TargetDescription string. </p> +<ul> +<li>The "E" in the string indicates a big-endian target data model; a +lower-case "e" would indicate little-endian. </li> +<li>"p:" is followed by pointer information: size, ABI alignment, and +preferred alignment. If only two figures follow "p:", 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: "i", "f", "v", or "a" +(corresponding to integer, floating point, vector, or aggregate). "i", "v", or +"a" are followed by ABI alignment and preferred alignment. "f" is followed by +three values, the first indicates the size of a long double, then ABI alignment +and preferred alignment.</li> +</ul> +<p>You must also register your target using the RegisterTarget +template. (See the TargetMachineRegistry class.) For example, in <tt>SparcTargetMachine.cpp</tt>, +the target is registered with:</p> +</div> + +<div class="doc_code"> +<pre> +namespace { + // Register the target. + RegisterTarget<SparcTargetMachine>X("sparc", "SPARC"); +} +</pre> +</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 XXXRegisterInfo (where XXX identifies the target) and represents the +class register file data that is used for register allocation and 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 that include 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 +XXXRegisterInfo requires hand-coding. </p> +</div> <!-- ======================================================================= --> <div class="doc_subsection"> - <a name="machine">Machine backends</a> + <a name="RegisterDef">Defining a Register</a> </div> - -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="machineTOC">Outline</a> +<div class="doc_text"> +<p>The <tt>XXXRegisterInfo.td</tt> file typically starts with register definitions +for a target machine. The Register class (specified in <tt>Target.td</tt>) is used to +define an object for each register. The specified string n becomes the Name of +the register. The basic Register object does not have any subregisters and does +not specify any aliases.</p> +</div> +<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> <div class="doc_text"> +<p>For example, in the <tt>X86RegisterInfo.td</tt> file, there are register +definitions that utilize the Register class, such as:</p> +</div> +<div class="doc_code"> +<pre> +def AL : Register<"AL">, +DwarfRegNum<[0, 0, 0]>; +</pre> +</div> -<p>In general, you want to follow the format of SPARC, X86 or PowerPC (in -<tt>lib/Target</tt>). SPARC is the simplest backend, and is RISC, so if -you're working on a RISC target, it is a good one to start with.</p> +<div class="doc_text"> +<p>This defines the register AL and assigns it values (with +DwarfRegNum) that are used by <tt>gcc</tt>, <tt>gdb</tt>, or a debug information writer (such as +DwarfWriter in <tt>llvm/lib/CodeGen</tt>) to identify a register. For register AL, +DwarfRegNum takes an array of 3 values, representing 3 different modes: the +first element is for X86-64, the second for EH (exception handling) 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>To create a static compiler (one that emits text assembly), you need to -implement the following:</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> +<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> +<div class="doc_text"> +<p>From the register info file, TableGen generates a +TargetRegisterDesc object for each register. TargetRegisterDesc is defined in +<tt>include/llvm/Target/TargetRegisterInfo.h</tt> with the following fields:</p> +</div> + +<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> + +<div class="doc_text"> +<p>TableGen uses the entire target description file (<tt>.td</tt>) to +determine text names for the register (in the AsmName and Name fields of +TargetRegisterDesc) and the relationships of other registers to the defined +register (in the other TargetRegisterDesc fields). In this example, other +definitions establish the registers "AX", "EAX", and "RAX" as aliases for one +another, so TableGen generates a null-terminated array (AL_AliasSet) for this +register alias set. </p> + +<p>The Register class is commonly used as a base class for more +complex classes. In <tt>Target.td</tt>, the Register class is the base for the +RegisterWithSubRegs class that is used to define registers that need to specify +subregisters in the SubRegs list, as shown here:</p> +</div> +<div class="doc_code"> +<pre> +class RegisterWithSubRegs<string n, +list<Register> subregs> : Register<n> { + let SubRegs = subregs; +}</pre> +</div> + +<div class="doc_text"> +<p>In <tt>SparcRegisterInfo.td</tt>, additional register classes are defined +for SPARC: a Register subclass, SparcReg, and further subclasses: Ri, Rf, and +Rd. SPARC registers are identified by 5-bit ID numbers, which is a feature +common to these subclasses. Note the use of ‘let’ expressions to override values +that are initially defined in a superclass (such as SubRegs field in the Rd +class). </p> +</div> +<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> +<div class="doc_text"> +<p>In the <tt>SparcRegisterInfo.td</tt> file, there are register definitions +that utilize these subclasses of Register, such as:</p> +</div> +<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> +<div class="doc_text"> +<p>The last two registers shown above (D0 and D1) 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 RegisterClass 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> + +<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> +<div class="doc_text"> +<p>To define a RegisterClass, use the following 4 arguments:</p> <ul> -<li>Describe the register set. - <ul> - <li>Create a <a href="TableGenFundamentals.html">TableGen</a> description of - the register set and register classes</li> - <li>Implement a subclass of <tt><a - href="CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a></tt></li> - </ul></li> -<li>Describe the instruction set. - <ul> - <li>Create a <a href="TableGenFundamentals.html">TableGen</a> description of - the instruction set</li> - <li>Implement a subclass of <tt><a - href="CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a></tt></li> - </ul></li> -<li>Describe the target machine. - <ul> - <li>Create a <a href="TableGenFundamentals.html">TableGen</a> description of - the target that describes the pointer size and references the instruction - set</li> - <li>Implement a subclass of <tt><a - href="CodeGenerator.html#targetmachine">TargetMachine</a></tt>, which - configures <tt><a href="CodeGenerator.html#targetdata">TargetData</a></tt> - correctly</li> - <li>Register your new target using the <tt>RegisterTarget</tt> - template:<br><br> -<div class="doc_code"><pre> -RegisterTarget<<em>MyTargetMachine</em>> M("short_name", " Target name"); -</pre></div> - <br>Here, <em>MyTargetMachine</em> is the name of your implemented - subclass of <tt><a - href="CodeGenerator.html#targetmachine">TargetMachine</a></tt>, - <em>short_name</em> is the option that will be active following - <tt>-march=</tt> to select a target in llc and lli, and the last string - is the description of your target to appear in <tt>-help</tt> - listing.</li> - </ul></li> -<li>Implement the assembly printer for the architecture. - <ul> - <li>Define all of the assembly strings for your target, adding them to the - instructions in your *InstrInfo.td file.</li> - <li>Implement the <tt>llvm::AsmPrinter</tt> interface.</li> - </ul> -</li> -<li>Implement an instruction selector for the architecture. - <ul> - <li>The recommended method is the <a href="CodeGenerator.html#instselect"> - pattern-matching DAG-to-DAG instruction selector</a> (for example, see - the PowerPC backend in PPCISelDAGtoDAG.cpp). Parts of instruction - selector creation can be performed by adding patterns to the instructions - in your <tt>.td</tt> file.</li> - </ul> -</li> -<li>Optionally, add subtarget support. -<ul> - <li>If your target has multiple subtargets (e.g. variants with different - capabilities), implement the <tt>llvm::TargetSubtarget</tt> interface - for your architecture. This allows you to add <tt>-mcpu=</tt> and - <tt>-mattr=</tt> options.</li> -</ul> -<li>Optionally, add JIT support. - <ul> - <li>Create a subclass of <tt><a - href="CodeGenerator.html#targetjitinfo">TargetJITInfo</a></tt></li> - <li>Create a machine code emitter that will be used to emit binary code - directly into memory, given <tt>MachineInstr</tt>s</li> - </ul> +<li>The first argument of the definition is the name of the +namespace. </li> + +<li>The second argument is a list of ValueType register type values +that are defined in <tt>include/llvm/CodeGen/ValueTypes.td</tt>. Defined values include +integer types (such as i16, i32, and i1 for Boolean), floating-point types +(f32, f64), and vector types (for example, v8i16 for an 8 x i16 vector). All +registers in a RegisterClass must have the same ValueType, 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 RegisterClass 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: +FPRegs, DFPRegs, and IntRegs. For all three register classes, the first +argument defines the namespace with the string “SP”. FPRegs defines a group of 32 +single-precision floating-point registers (F0 to F31); DFPRegs defines a group +of 16 double-precision registers (D0-D15). For IntRegs, the MethodProtos and +MethodBodies methods are used by TableGen to insert the specified code into generated +output.</p> +</div> +<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> -<!-- _______________________________________________________________________ --> -<div class="doc_subsubsection"> - <a name="machineDetails">Implementation details</a> +<div class="doc_text"> +<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 +SparcGenRegisterInfo that uses TargetRegisterInfo as its base. It also +specifies types, based upon the defined register classes: DFPRegsClass, FPRegsClass, +and IntRegsClass. </p> + +<p><tt>SparcRegisterInfo.td</tt> also generates SparcGenRegisterInfo.inc, +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 IntRegs reflects the +order in the definition of IntRegs in the target description file. Take special +note of the use of MethodBodies in <tt>SparcRegisterInfo.td</tt> to create code in +<tt>SparcGenRegisterInfo.inc</tt>. MethodProtos generates similar code in +<tt>SparcGenRegisterInfo.h.inc</tt>.</p> +</div> + +<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 class="doc_subsection"> + <a name="implementRegister">Implement a subclass of + <a href="http://www.llvm.org/docs/CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a></a> +</div> +<div class="doc_text"> +<p>The final step is to hand code portions of XXXRegisterInfo, which +implements the interface described in <tt>TargetRegisterInfo.h</tt>. These functions +return 0, NULL, or false, unless overridden. Here’s 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 SelectionDAG with nodes that are instances of the SDNode class +containing target instructions. An SDNode 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 NodeType enum in the ISD namespace).</p> +<p>TableGen uses the following target description (.td) input files +to generate much of the code for instruction definition:</p> <ul> +<li><tt>Target.td</tt>, where the Instruction, Operand, InstrInfo, and other +fundamental classes are defined</li> -<li><p><b>TableGen register info description</b> - describe a class which -will store the register's number in the binary encoding of the instruction -(e.g., for JIT purposes).</p> +<li><tt>TargetSelectionDAG.td</tt>, used by SelectionDAG instruction selection +generators, contains SDTC* classes (selection DAG type constraint), definitions +of SelectionDAG nodes (such as imm, cond, bb, add, fadd, sub), and pattern +support (Pattern, Pat, PatFrag, PatLeaf, ComplexPattern)</li> -<p>You also need to define register classes to contain these registers, such as -the integer register class and floating-point register class, so that you can -allocate virtual registers to instructions from these sets, and let the -target-independent register allocator automatically choose the actual -architected registers.</p> +<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 XXX is the +name of the target. The <tt>XXX.td</tt> file includes the other .td input files, but its +contents are only directly important for subtargets.</p> + +<p>You should describe +a concrete target-specific class +XXXInstrInfo that represents machine +instructions supported by a target machine. XXXInstrInfo contains an array of +XXXInstrDescriptor 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> <div class="doc_code"> -<pre> -// class Register is defined in Target.td -<b>class</b> <em>Target</em>Reg<string name> : Register<name> { - <b>let</b> Namespace = "<em>Target</em>"; +<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> +<div class="doc_text"> +<p>A SelectionDAG node (SDNode) 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 ADDri and ADDrr.</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 CALL instruction. Format 2 is for +branch on condition codes and SETHI (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>. InstSP is a base +class for other instruction classes. Additional base classes are specified for +more precise formats: for example in <tt>SparcInstrFormat.td</tt>, F2_1 is for SETHI, +and F2_2 is for branches. There are three other base classes: F3_1 for +register/register operations, F3_2 for register/immediate operations, and F3_3 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, LDrr, defines +the Load Integer instruction for a Word (the LD SPARC opcode) from a memory +address to a register. The first parameter, the value 3 (11<sub>2</sub>), is +the operation value for this category of operation. The second parameter +(000000<sub>2</sub>) is the specific operation value for LD/Load Word. The +third parameter is the output destination, which is a register operand and +defined in the Register target description file (IntRegs). </p> +</div> +<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> + +<div class="doc_text"> +<p>The fourth +parameter is the input source, which uses the address operand MEMrr that is +defined earlier in <tt>SparcInstrInfo.td</tt>:</p> +</div> +<div class="doc_code"> +<pre>def MEMrr : Operand<i32> { + let PrintMethod = "printMemOperand"; + let MIOperandInfo = (ops IntRegs, IntRegs); } +</pre> +</div> +<div class="doc_text"> +<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> -<b>class</b> IntReg<<b>bits</b><5> num, string name> : <em>Target</em>Reg<name> { - <b>field</b> <b>bits</b><5> Num = num; +<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> +<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> +<div class="doc_text"> +<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 F3_12 is defined to create 2 +instruction classes each time F3_12 is invoked: </p> +</div> +<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> +<div class="doc_text"> +<p>So when the <tt>defm</tt> directive is used for the XOR and ADD +instructions, as seen below, it creates four instruction objects: XORrr, XORri, +ADDrr, and ADDri.</p> +</div> +<div class="doc_code"> +<pre>defm XOR : F3_12<"xor", 0b000011, xor>; +defm ADD : F3_12<"add", 0b000000, add>; +</pre> +</div> -<b>def</b> R0 : IntReg<0, "%R0">; +<div class="doc_text"> +<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> + +<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> + +<div class="doc_text"> +<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>; that is, <tt>SPCC::ICC_NE = 9</tt>, <tt>SPCC::FCC_U = 23</tt> and so on.)</p> +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="implementInstr">Implement a subclass of + <a href="http://www.llvm.org/docs/CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a></a> +</div> + +<div class="doc_text"> +<p>The final step is to hand code portions of XXXInstrInfo, which +implements the interface described in <tt>TargetInstrInfo.h</tt>. These functions return +0 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 FrameIndex 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 FrameIndex 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 XXXInstrInfo 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>MachineBasicBlock &MBB – the incoming block to be +examined</li> -// class RegisterClass is defined in Target.td -<b>def</b> IReg : RegisterClass<i64, 64, [R0, ... ]>; +<li>MachineBasicBlock *&TBB – a destination block that is +returned; for a conditional branch that evaluates to true, TBB is the +destination </li> + +<li>MachineBasicBlock *&FBB – for a conditional branch that +evaluates to false, FBB is returned as the destination</li> + +<li>std::vector<MachineOperand> &Cond – 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 TBB or FBB, so both parameters return NULL. 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> + +<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> -</li> -<li><p><b>TableGen instruction info description</b> - break up instructions into -classes, usually that's already done by the manufacturer (see instruction -manual). Define a class for each instruction category. Define each opcode as a -subclass of the category, with appropriate parameters such as the fixed binary -encoding of opcodes and extended opcodes, and map the register bits to the bits -of the instruction which they are encoded in (for the JIT). Also specify how -the instruction should be printed so it can use the automatic assembly printer, -e.g.:</p> +<div class="doc_text"> +<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 TBB parameter. </p> +</div> <div class="doc_code"> -<pre> -// class Instruction is defined in Target.td -<b>class</b> Form<<b>bits</b><6> opcode, <b>dag</b> OL, <b>string</b> asmstr> : Instruction { - <b>field</b> <b>bits</b><42> Inst; - - <b>let</b> Namespace = "<em>Target</em>"; - <b>let</b> Inst{0-6} = opcode; - <b>let</b> OperandList = OL; - <b>let</b> AsmString = asmstr; -} +<pre>if (LastOpc == ARM::B || LastOpc == ARM::tB) { + TBB = LastInst->getOperand(0).getMBB(); + return false; + } +</pre> +</div> -<b>def</b> ADD : Form<42, (ops IReg:$rD, IReg:$rA, IReg:$rB), "add $rD, $rA, $rB">; +<div class="doc_text"> +<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 TBB parameter. </p> +</div> + +<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> -</li> +<div class="doc_text"> +<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 TBB parameter and a list of operands in the <tt>Cond</tt> +parameter to evaluate the condition. </p> +</div> + +<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> + +<div class="doc_text"> +<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 ‘true’) in the TBB parameter and the unconditional branch +destination in the FBB (corresponding to a conditional evaluation of ‘false’). +A list of operands to evaluate the condition should be returned in the <tt>Cond</tt> +parameter.</p> +</div> + +<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> + +<div class="doc_text"> +<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 SelectionDAG to represent LLVM IR instructions, and nodes +of the SelectionDAG 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 Selection DAG. </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 FunctionPass class or a subclass of FunctionPass. 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 SelectionDAG 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 SelectionDAG 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> + +<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> + +<div class="doc_text"> +<p>ADDRrr is a memory mode that is also defined in <tt>SparcInstrInfo.td</tt>:</p> +</div> + +<div class="doc_code"> +<pre>def ADDRrr : ComplexPattern<i32, 2, "SelectADDRrr", [], []>; +</pre> +</div> + +<div class="doc_text"> +<p>The definition of ADDRrr refers to SelectADDRrr, 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> + +<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> +<div class="doc_text"> +<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 +ISD::STORE opcode.</p> +</div> + +<div class="doc_code"> +<pre>SDNode *SelectCode(SDOperand N) { + ... + MVT::ValueType NVT = N.Val->getValueType(0); + switch (N.getOpcode()) { + case ISD::STORE: { + switch (NVT) { + default: + return Select_ISD_STORE(N); + break; + } + break; + } + ... +</pre> +</div> +<div class="doc_text"> +<p>The pattern for STrr is matched, so elsewhere in +<tt>XXXGenDAGISel.inc</tt>, code for STrr 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> + +<div class="doc_code"> +<pre>SDNode *Select_ISD_STORE(const SDOperand &N) { + SDOperand Chain = N.getOperand(0); + if (Predicate_store(N.Val)) { + SDOperand N1 = N.getOperand(1); + SDOperand N2 = N.getOperand(2); + SDOperand CPTmp0; + SDOperand 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.Val->getValueType(0) == MVT::i32 && + N2.Val->getValueType(0) == MVT::i32) { + return Emit_22(N, SP::STrr, CPTmp0, CPTmp1); + } +... +</pre> </div> <!-- ======================================================================= --> <div class="doc_subsection"> - <a name="lang">Language backends</a> + <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 XXXTargetLowering 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> + +<div class="doc_code"> +<pre>addRegisterClass(MVT::i32, SP::IntRegsRegisterClass); +addRegisterClass(MVT::f32, SP::FPRegsRegisterClass); +addRegisterClass(MVT::f64, SP::DFPRegsRegisterClass); +</pre> </div> <div class="doc_text"> +<p>You should examine the node types in the ISD namespace +(<tt>include/llvm/CodeGen/SelectionDAGNodes.h</tt>) +and determine which operations the target natively supports. For operations +that do <u>not</u> 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> -<p>For now, just take a look at <tt>lib/Target/CBackend</tt> for an example of -how the C backend is written.</p> +<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 LegalAction 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 LegalAction 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> + +<div class="doc_code"> +<pre>setLoadExtAction(ISD::SEXTLOAD, MVT::i1, Promote); +</pre> +</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> + +<div class="doc_code"> +<pre>setOperationAction(ISD::FSIN, MVT::f32, Expand); +setOperationAction(ISD::FCOS, MVT::f32, Expand); +</pre> +</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> + +<div class="doc_code"> +<pre>setOperationAction(ISD::FP_TO_SINT, MVT::i32, Custom); +</pre> +</div> +<div class="doc_text"> +<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 FP_TO_SINT opcode will call the <tt>LowerFP_TO_SINT</tt> method:</p> +</div> + +<div class="doc_code"> +<pre>SDOperand SparcTargetLowering::LowerOperation( + SDOperand Op, SelectionDAG &DAG) { + switch (Op.getOpcode()) { + case ISD::FP_TO_SINT: return LowerFP_TO_SINT(Op, DAG); + ... + } +} +</pre> +</div> +<div class="doc_text"> +<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> + +<div class="doc_code"> +<pre>static SDOperand LowerFP_TO_SINT(SDOperand 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 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 <u>is</u> natively supported. <tt>Legal</tt> represents the default condition, +so it is rarely used. In <tt>SparcISelLowering.cpp</tt>, the action for CTPOP (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> + +<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 class="doc_subsection"> - <a name="files">Files to create/modify</a> + <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 CCIfType and +CCAssignToReg interfaces. If the CCIfType predicate is true (that is, if the +current argument is of type f32 or f64), then the action is performed. In this +case, the CCAssignToReg action assigns the argument value to the first +available register: either R0 or R1. </p> +</div> +<div class="doc_code"> +<pre>CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>> +</pre> +</div> <div class="doc_text"> +<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 +(CC_Sparc32). The definition of RetCC_Sparc32 (shown below) indicates which +registers are used for specified scalar return types. A single-precision float +is returned to register F0, and a double-precision float goes to register D0. A +32-bit integer is returned in register I0 or I1. </p> +</div> -<p>To actually create your backend, you need to create and modify a few files. -Here, the absolute minimum will be discussed. To actually use LLVM's target -independent codegenerator, you must <a href="CodeGenerator.html">implement extra -things</a>.</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> +<div class="doc_text"> +<p>The definition of CC_Sparc32 in <tt>SparcCallingConv.td</tt> introduces +CCAssignToStack, 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> -<p>First of all, you should create a subdirectory under <tt>lib/Target</tt>, -which will hold all the files related to your target. Let's assume that our -target is called, "Dummy", we would create the directory -<tt>lib/Target/Dummy</tt>.</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> +<div class="doc_text"> +<p>CCDelegateTo 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 RetCC_X86_32_C +ends with CCDelegateTo. After the current value is assigned to the register ST0 +or ST1, the RetCC_X86Common is invoked.</p> +</div> + +<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> +<div class="doc_text"> +<p>CCIfCC 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 Fast calling convention is in use, then RetCC_X86_32_Fast +is invoked. If the SSECall calling convention is in use, then RetCC_X86_32_SSE +is invoked. </p> +</div> + +<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> +<div class="doc_text"> +<p>Other calling convention interfaces include:</p> +<ul> +<li>CCIf <predicate, action> - if the predicate matches, apply +the action</li> + +<li>CCIfInReg <action> - if the argument is marked with the +‘inreg’ attribute, then apply the action </li> + +<li>CCIfNest <action> - if the argument is marked with the +‘nest’ attribute, then apply the action</li> + +<li>CCIfNotVarArg <action> - if the current function does not +take a variable number of arguments, apply the action</li> + +<li>CCAssignToRegWithShadow <registerList, shadowList> - +similar to CCAssignToReg, but with a shadow list of registers</li> + +<li>CCPassByVal <size, align> - assign value to a stack slot +with the minimum specified size and alignment </li> + +<li>CCPromoteToType <type> - promote the current value to the specified +type</li> + +<li>CallingConv <[actions]> - 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 XXXTargetAsmInfo class (a subclass of TargetAsmInfo). </li> + +<li>Write <tt>XXXTargetAsmInfo.cpp</tt>, which contains target-specific values +for TargetAsmInfo properties and sometimes new implementations for methods</li> + +<li>Write <tt>XXXAsmPrinter.cpp</tt>, which implements the AsmPrinter 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 XXXTargetAsmInfo class for use in <tt>XXXTargetAsmInfo.cpp</tt>. Similarly, +<tt>XXXTargetAsmInfo.cpp</tt> usually has a few declarations of XXXTargetAsmInfo replacement +values that override the default values in <tt>TargetAsmInfo.cpp</tt>. For example in +<tt>SparcTargetAsmInfo.cpp</tt>, </p> +</div> + +<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> +<div class="doc_text"> +<p>The X86 assembly printer implementation (X86TargetAsmInfo) is an +example where the target specific TargetAsmInfo class uses overridden methods: +<tt>ExpandInlineAsm</tt> and <tt>PreferredEHDataFormat</tt>. </p> + +<p>A target-specific implementation of AsmPrinter is written in +<tt>XXXAsmPrinter.cpp</tt>, which implements the AsmPrinter class that converts the LLVM +to printable assembly. The implementation must include the following headers +that have declarations for the AsmPrinter and MachineFunctionPass classes. The +MachineFunctionPass is a subclass of FunctionPass. </p> +</div> + +<div class="doc_code"> +<pre>#include "llvm/CodeGen/AsmPrinter.h" +#include "llvm/CodeGen/MachineFunctionPass.h" +</pre> +</div> + +<div class="doc_text"> +<p>As a FunctionPass, AsmPrinter first calls <tt>doInitialization</tt> to set +up the AsmPrinter. In SparcAsmPrinter, a Mangler object is instantiated to +process variable names.</p> + +<p>In <tt>XXXAsmPrinter.cpp</tt>, the <tt>runOnMachineFunction</tt> method (declared +in MachineFunctionPass) must be implemented for XXXAsmPrinter. In +MachineFunctionPass, 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 XXXAsmPrinter 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> + +<li><tt>printLabel</tt></li> + +<li><tt>printPICJumpTableEntry</tt></li> + +<li><tt>printPICJumpTableSetLabel</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. (<tt>printBasicBlockLabel</tt> is +another method that is implemented in <tt>AsmPrinter.cpp</tt> that may be directly used +in an implementation of XXXAsmPrinter.)</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 XXXAsmPrinter, 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 +SubtargetFeature interface is defined. The first 4 string parameters of the +SubtargetFeature 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> + +<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> +<div class="doc_text"> +<p>In the <tt>Sparc.td</tt> file, the SubtargetFeature is used to define the +following features. </p> +</div> + +<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>In this new directory, you should put a <tt>Makefile</tt>. You can probably -copy one from 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>. Be careful to give the library the -correct name, it must be named <tt>LLVMDummy</tt> (see the MIPS target, for -example). 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> (see the -PowerPC target, for example).</p> - -<p>Note that these two naming schemes are hardcoded into llvm-config. Using any -other naming scheme will confuse llvm-config and produce lots 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 <a -href="CodeGenerator.html">target independent code generator</a>, you should -create a subclass of <tt>LLVMTargetMachine</tt>. This is what all current -machine backends do. To create a target from scratch, create a subclass of -<tt>TargetMachine</tt>. This is what the current language backends do.</p> - -<p>To get LLVM to actually build and link your target, you also need to add it -to the <tt>TARGETS_TO_BUILD</tt> variable. To do this, you need to modify the -<tt>configure</tt> script to know about your target when parsing the -<tt>--enable-targets</tt> option. Search the <tt>configure</tt> 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 <tt>configure</tt> by running -<tt>./autoconf/AutoRegen.sh</tt>. +<div class="doc_text"> +<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> + +<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> +<div class="doc_text"> +<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> + +<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 class="doc_section"> - <a name="related">Related reading material</a> + <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 XXXTargetMachine so that it provides a TargetJITInfo +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 MachineCodeEmitter +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 Emitter class is +implemented as a function pass (subclass of MachineFunctionPass). The +target-specific implementation of <tt>runOnMachineFunction</tt> (invoked by +<tt>runOnFunction</tt> in MachineFunctionPass) iterates through the MachineBasicBlock +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> + +<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> +<div class="doc_text"> +<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, MO1, 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> + +<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> +<div class="doc_text"> +<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 RelocationType enum for +that target is defined in the short target-specific <tt>XXXRelocations.h</tt> file. The +RelocationType 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> +<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 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 XXXJITInfo implements the following:</p> <ul> -<li><a href="CodeGenerator.html">Code generator</a> - - describes some of the classes in code generation at a high level, but - it is not (yet) complete</li> -<li><a href="TableGenFundamentals.html">TableGen fundamentals</a> - - describes how to use TableGen to describe your target information - succinctly</li> -<li><a href="HowToSubmitABug.html#codegen">Debugging code generation with - bugpoint</a> - shows bugpoint usage scenarios to simplify backend - development</li> +<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 JITCompilerFunction 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> + +<div class="doc_code"> +<pre>TargetJITInfo::LazyResolverFn AlphaJITInfo::getLazyResolverFunction( + JITCompilerFn F) +{ + JITCompilerFunction = F; + return AlphaCompilationCallback; +} +</pre> +</div> +<div class="doc_text"> +<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> <!-- *********************************************************************** --> @@ -300,7 +2069,7 @@ required) and then reconfigure. Alternatively, you can change <a href="http://validator.w3.org/check/referer"><img src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a> - <a href="http://misha.brukman.net">Misha Brukman</a><br> + <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$ |