From f5af6ada3b0570db1afc19029cad8fb8320676ef Mon Sep 17 00:00:00 2001 From: NAKAMURA Takumi Date: Sat, 23 Apr 2011 00:30:22 +0000 Subject: [PATCH] docs: Introduce cascading style
and

continued on .

Section Example

Section preamble.

Subsection Example

Subsection body

FIXME: Care H5 better. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@130040 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/BitCodeFormat.html | 171 ++++++----- docs/Bugpoint.html | 18 +- docs/CMake.html | 36 +-- docs/CodeGenerator.html | 217 +++++++------- docs/CodingStandards.html | 93 +++--- docs/CommandGuide/index.html | 10 +- docs/CommandLine.html | 97 +++--- docs/CompilerWriterInfo.html | 42 ++- docs/DebuggingJITedCode.html | 4 +- docs/DeveloperPolicy.html | 38 +-- docs/ExceptionHandling.html | 62 ++-- docs/ExtendingLLVM.html | 18 +- docs/GCCFEBuildInstrs.html | 8 +- docs/GarbageCollection.html | 59 ++-- docs/GetElementPtr.html | 61 ++-- docs/GettingStarted.html | 77 +++-- docs/GettingStartedVS.html | 20 +- docs/GoldPlugin.html | 15 +- docs/HowToReleaseLLVM.html | 75 +++-- docs/HowToSubmitABug.html | 18 +- docs/LangRef.html | 471 +++++++++++++++--------------- docs/Lexicon.html | 31 +- docs/LinkTimeOptimization.html | 33 ++- docs/MakefileGuide.html | 97 +++--- docs/Packaging.html | 10 +- docs/Passes.html | 257 ++++++++-------- docs/ProgrammersManual.html | 324 ++++++++++---------- docs/Projects.html | 26 +- docs/SourceLevelDebugging.html | 104 +++---- docs/SystemLibrary.html | 37 +-- docs/TableGenFundamentals.html | 55 ++-- docs/TestingGuide.html | 74 +++-- docs/UsingLibraries.html | 18 +- docs/WritingAnLLVMBackend.html | 87 +++--- docs/WritingAnLLVMPass.html | 168 +++++------ docs/index.html | 2 - docs/tutorial/LangImpl1.html | 6 +- docs/tutorial/LangImpl2.html | 18 +- docs/tutorial/LangImpl3.html | 12 +- docs/tutorial/LangImpl4.html | 10 +- docs/tutorial/LangImpl5.html | 36 +-- docs/tutorial/LangImpl6.html | 12 +- docs/tutorial/LangImpl7.html | 16 +- docs/tutorial/LangImpl8.html | 24 +- docs/tutorial/OCamlLangImpl1.html | 6 +- docs/tutorial/OCamlLangImpl2.html | 18 +- docs/tutorial/OCamlLangImpl3.html | 12 +- docs/tutorial/OCamlLangImpl4.html | 10 +- docs/tutorial/OCamlLangImpl5.html | 36 +-- docs/tutorial/OCamlLangImpl6.html | 12 +- docs/tutorial/OCamlLangImpl7.html | 16 +- docs/tutorial/OCamlLangImpl8.html | 24 +- 52 files changed, 1632 insertions(+), 1569 deletions(-) diff --git a/docs/BitCodeFormat.html b/docs/BitCodeFormat.html index 396904a3d6d1e..d2088487aa765 100644 --- a/docs/BitCodeFormat.html +++ b/docs/BitCodeFormat.html @@ -50,7 +50,7 @@

LLVM Bitcode File Format

Abstract

-
+

This document describes the LLVM bitstream file format and the encoding of the LLVM IR into it.

@@ -61,7 +61,7 @@

Abstract

Overview

-
+

What is commonly known as the LLVM bitcode file format (also, sometimes @@ -91,7 +91,7 @@

Overview

Bitstream Format

-
+

The bitstream format is literally a stream of bits, with a very simple @@ -114,14 +114,12 @@

Bitstream Format

used to dump and inspect arbitrary bitstreams, which is very useful for understanding the encoding.

-
-

Magic Numbers

-
+

The first two bytes of a bitcode file are 'BC' (0x42, 0x43). The second two bytes are an application-specific magic number. Generic @@ -135,7 +133,7 @@

Primitives

-
+

A bitstream literally consists of a stream of bits, which are read in order @@ -146,14 +144,12 @@

Integers.

-

-

Fixed Width Integers

-
+

Fixed-width integer values have their low bits emitted directly to the file. For example, a 3-bit integer value encodes 1 as 001. Fixed width integers @@ -168,7 +164,7 @@

Variable Width Integers

-
+

Variable-width integer (VBR) values encode values of arbitrary size, optimizing for the case where the values are small. Given a 4-bit VBR field, @@ -188,7 +184,7 @@

6-bit characters

-
+

6-bit characters encode common characters into a fixed 6-bit field. They represent the following characters with the following 6-bit values:

@@ -212,7 +208,7 @@

6-bit characters

Word Alignment

-
+

Occasionally, it is useful to emit zero bits until the bitstream is a multiple of 32 bits. This ensures that the bit position in the stream can be @@ -220,13 +216,14 @@

Word Alignment

+

Abbreviation IDs

-
+

A bitstream is a sequential series of Blocks and @@ -262,7 +259,7 @@

Blocks

-
+

Blocks in a bitstream denote nested regions of the stream, and are identified by @@ -303,12 +300,10 @@

popped, the saved values are restored.

-

-

ENTER_SUBBLOCK Encoding

-
+

[ENTER_SUBBLOCK, blockidvbr8, newabbrevlenvbr4, <align32bits>, blocklen32]

@@ -329,7 +324,7 @@

ENTER_SUBBLOCK Encoding

END_BLOCK Encoding

-
+

[END_BLOCK, <align32bits>]

@@ -341,14 +336,14 @@

END_BLOCK Encoding

- +

Data Records

-
+

Data records consist of a record code and a number of (up to) 64-bit integer values. The interpretation of the code and values is @@ -360,12 +355,10 @@

ASCII codes for the characters in the string.

-

-

UNABBREV_RECORD Encoding

-
+

[UNABBREV_RECORD, codevbr6, numopsvbr6, op0vbr6, op1vbr6, ...]

@@ -391,7 +384,7 @@

UNABBREV_RECORD Encoding

Abbreviated Record Encoding

-
+

[<abbrevid>, fields...]

@@ -412,12 +405,14 @@

Abbreviated Record Encoding

+
+

Abbreviations

-
+

Abbreviations are an important form of compression for bitstreams. The idea is to specify a dense encoding for a class of records once, then use that encoding @@ -435,12 +430,11 @@

for binary operators. If a specific LLVM module contained no or few binary operators, the abbreviation does not need to be emitted.

-

DEFINE_ABBREV Encoding

-
+

[DEFINE_ABBREV, numabbrevopsvbr5, abbrevop0, abbrevop1, ...]

@@ -555,12 +549,14 @@

DEFINE_ABBREV Encoding

+
+

Standard Blocks

-
+

In addition to the basic block structure and record encodings, the bitstream @@ -569,12 +565,10 @@

may be added. Block IDs 0-7 are reserved for standard blocks.

-

-

#0 - BLOCKINFO Block

-
+

The BLOCKINFO block allows the description of metadata for other @@ -623,11 +617,15 @@

#0 - BLOCKINFO Block

+
+ +
+

Bitcode Wrapper Format

-
+

Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper @@ -658,7 +656,7 @@

Bitcode Wrapper Format

LLVM IR Encoding

-
+

LLVM IR is encoded into a bitstream by defining blocks and records. It uses @@ -669,17 +667,17 @@

LLVM IR Encoding

reader is not allowed to build in any knowledge of this.

-
-

Basics

+
+

LLVM IR Magic Number

-
+

The magic number for LLVM IR files is: @@ -701,7 +699,7 @@

LLVM IR Magic Number

Signed VBRs

-
+

Variable Width Integer encoding is an efficient way to @@ -734,7 +732,7 @@

Signed VBRs

LLVM IR Blocks

-
+

LLVM IR is defined with the following blocks: @@ -762,12 +760,14 @@

LLVM IR Blocks

+
+

MODULE_BLOCK Contents

-
+

The MODULE_BLOCK block (id 8) is the top-level block for LLVM bitcode files, and each bitcode file must contain exactly one. In @@ -787,12 +787,10 @@

  • METADATA_BLOCK
  • -

    -

    MODULE_CODE_VERSION Record

    -
    +

    [VERSION, version#]

    @@ -804,7 +802,7 @@

    MODULE_CODE_VERSION Record

    MODULE_CODE_TRIPLE Record

    -
    +

    [TRIPLE, ...string...]

    The TRIPLE record (code 2) contains a variable number of @@ -815,7 +813,7 @@

    MODULE_CODE_TRIPLE Record

    MODULE_CODE_DATALAYOUT Record

    -
    +

    [DATALAYOUT, ...string...]

    The DATALAYOUT record (code 3) contains a variable number of @@ -826,7 +824,7 @@

    MODULE_CODE_DATALAYOUT Record

    MODULE_CODE_ASM Record

    -
    +

    [ASM, ...string...]

    The ASM record (code 4) contains a variable number of @@ -837,7 +835,7 @@

    MODULE_CODE_ASM Record

    MODULE_CODE_SECTIONNAME Record

    -
    +

    [SECTIONNAME, ...string...]

    The SECTIONNAME record (code 5) contains a variable number @@ -852,7 +850,7 @@

    MODULE_CODE_SECTIONNAME Record

    MODULE_CODE_DEPLIB Record

    -
    +

    [DEPLIB, ...string...]

    The DEPLIB record (code 6) contains a variable number of @@ -865,7 +863,7 @@

    MODULE_CODE_DEPLIB Record

    MODULE_CODE_GLOBALVAR Record

    -
    +

    [GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]

    The GLOBALVAR record (code 7) marks the declaration or @@ -929,7 +927,7 @@

    MODULE_CODE_GLOBALVAR Record

    MODULE_CODE_FUNCTION Record

    -
    +

    [FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]

    @@ -985,7 +983,7 @@

    MODULE_CODE_FUNCTION Record

    MODULE_CODE_ALIAS Record

    -
    +

    [ALIAS, alias type, aliasee val#, linkage, visibility]

    @@ -1009,7 +1007,7 @@

    MODULE_CODE_ALIAS Record

    MODULE_CODE_PURGEVALS Record

    -
    +

    [PURGEVALS, numvals]

    The PURGEVALS record (code 10) resets the module-level @@ -1022,7 +1020,7 @@

    MODULE_CODE_PURGEVALS Record

    MODULE_CODE_GCNAME Record

    -
    +

    [GCNAME, ...string...]

    The GCNAME record (code 11) contains a variable number of @@ -1033,12 +1031,14 @@

    MODULE_CODE_GCNAME Record

    fields of FUNCTION records.

    +
    +

    PARAMATTR_BLOCK Contents

    -
    +

    The PARAMATTR_BLOCK block (id 9) contains a table of entries describing the attributes of function parameters. These @@ -1052,13 +1052,10 @@

    that each is unique (i.e., no two indicies represent equivalent attribute lists).

    -

    - -

    PARAMATTR_CODE_ENTRY Record

    -
    +

    [ENTRY, paramidx0, attr0, paramidx1, attr1...]

    @@ -1099,12 +1096,14 @@

    PARAMATTR_CODE_ENTRY Record

    +
    +

    TYPE_BLOCK Contents

    -
    +

    The TYPE_BLOCK block (id 10) contains records which constitute a table of type operator entries used to represent types @@ -1119,12 +1118,10 @@

    each entry is unique (i.e., no two indicies represent structurally equivalent types).

    -

    -

    TYPE_CODE_NUMENTRY Record

    -
    +

    [NUMENTRY, numentries]

    @@ -1138,7 +1135,7 @@

    TYPE_CODE_NUMENTRY Record

    TYPE_CODE_VOID Record

    -
    +

    [VOID]

    @@ -1150,7 +1147,7 @@

    TYPE_CODE_VOID Record

    TYPE_CODE_FLOAT Record

    -
    +

    [FLOAT]

    @@ -1162,7 +1159,7 @@

    TYPE_CODE_FLOAT Record

    TYPE_CODE_DOUBLE Record

    -
    +

    [DOUBLE]

    @@ -1174,7 +1171,7 @@

    TYPE_CODE_DOUBLE Record

    TYPE_CODE_LABEL Record

    -
    +

    [LABEL]

    @@ -1186,7 +1183,7 @@

    TYPE_CODE_LABEL Record

    TYPE_CODE_OPAQUE Record

    -
    +

    [OPAQUE]

    @@ -1199,7 +1196,7 @@

    TYPE_CODE_OPAQUE Record

    TYPE_CODE_INTEGER Record

    -
    +

    [INTEGER, width]

    @@ -1212,7 +1209,7 @@

    TYPE_CODE_INTEGER Record

    TYPE_CODE_POINTER Record

    -
    +

    [POINTER, pointee type, address space]

    @@ -1232,7 +1229,7 @@

    TYPE_CODE_POINTER Record

    TYPE_CODE_FUNCTION Record

    -
    +

    [FUNCTION, vararg, ignored, retty, ...paramty... ]

    @@ -1256,7 +1253,7 @@

    TYPE_CODE_FUNCTION Record

    TYPE_CODE_STRUCT Record

    -
    +

    [STRUCT, ispacked, ...eltty...]

    @@ -1274,7 +1271,7 @@

    TYPE_CODE_STRUCT Record

    TYPE_CODE_ARRAY Record

    -
    +

    [ARRAY, numelts, eltty]

    @@ -1291,7 +1288,7 @@

    TYPE_CODE_ARRAY Record

    TYPE_CODE_VECTOR Record

    -
    +

    [VECTOR, numelts, eltty]

    @@ -1308,7 +1305,7 @@

    TYPE_CODE_VECTOR Record

    TYPE_CODE_X86_FP80 Record

    -
    +

    [X86_FP80]

    @@ -1320,7 +1317,7 @@

    TYPE_CODE_X86_FP80 Record

    TYPE_CODE_FP128 Record

    -
    +

    [FP128]

    @@ -1332,7 +1329,7 @@

    TYPE_CODE_FP128 Record

    TYPE_CODE_PPC_FP128 Record

    -
    +

    [PPC_FP128]

    @@ -1344,7 +1341,7 @@

    TYPE_CODE_PPC_FP128 Record

    TYPE_CODE_METADATA Record

    -
    +

    [METADATA]

    @@ -1353,12 +1350,14 @@

    TYPE_CODE_METADATA Record

    +
    +

    CONSTANTS_BLOCK Contents

    -
    +

    The CONSTANTS_BLOCK block (id 11) ...

    @@ -1371,7 +1370,7 @@

    FUNCTION_BLOCK Contents

    -
    +

    The FUNCTION_BLOCK block (id 12) ...

    @@ -1394,19 +1393,17 @@

    TYPE_SYMTAB_BLOCK Contents

    -
    +

    The TYPE_SYMTAB_BLOCK block (id 13) contains entries which map between module-level named types and their corresponding type indices.

    -
    -

    TST_CODE_ENTRY Record

    -
    +

    [ENTRY, typeid, ...string...]

    @@ -1417,13 +1414,14 @@

    TST_CODE_ENTRY Record

    +

    VALUE_SYMTAB_BLOCK Contents

    -
    +

    The VALUE_SYMTAB_BLOCK block (id 14) ...

    @@ -1436,7 +1434,7 @@

    METADATA_BLOCK Contents

    -
    +

    The METADATA_BLOCK block (id 15) ...

    @@ -1449,13 +1447,14 @@

    METADATA_ATTACHMENT Contents

    -
    +

    The METADATA_ATTACHMENT block (id 16) ...

    +

    diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html index 5568fc7baf972..154edfdad331d 100644 --- a/docs/Bugpoint.html +++ b/docs/Bugpoint.html @@ -32,7 +32,7 @@

    -
    +

    bugpoint narrows down the source of problems in LLVM tools and passes. It can be used to debug three types of failures: optimizer crashes, @@ -55,7 +55,7 @@

    -
    +

    bugpoint is designed to be a useful tool without requiring any hooks into the LLVM infrastructure at all. It works with any and all LLVM @@ -68,14 +68,12 @@

    debugging a miscompilation where each test of the program (which requires executing it) takes a long time.

    -

    -

    Automatic Debugger Selection

    -
    +

    bugpoint reads each .bc or .ll file specified on the command line and links them together into a single module, called the test @@ -108,7 +106,7 @@

    Crash debugger

    -
    +

    If an optimizer or code generator crashes, bugpoint will try as hard as it can to reduce the list of passes (for optimizer crashes) and the size of @@ -133,7 +131,7 @@

    Code generator debugger

    -
    +

    The code generator debugger attempts to narrow down the amount of code that is being miscompiled by the selected code generator. To do this, it takes the @@ -154,7 +152,7 @@

    Miscompilation debugger

    -
    +

    The miscompilation debugger works similarly to the code generator debugger. It works by splitting the test program into two pieces, running the @@ -166,13 +164,15 @@

    +
    +

    Advice for using bugpoint

    -
    +
    bugpoint can be a remarkably useful tool, but it sometimes works in non-obvious ways. Here are some hints and tips:

    diff --git a/docs/CMake.html b/docs/CMake.html index 8ea4377dd51fe..ba232080cd26d 100644 --- a/docs/CMake.html +++ b/docs/CMake.html @@ -41,7 +41,7 @@

    -
    +

    CMake is a cross-platform build-generator tool. CMake does not build the project, it generates @@ -64,7 +64,7 @@

    -
    +

    We use here the command-line, non-interactive CMake interface

    @@ -117,7 +117,7 @@

    -
    +

    This section explains basic aspects of CMake, mostly for explaining those options which you may need on your day-to-day @@ -165,7 +165,7 @@

    -
    +

    Variables customize how the build will be generated. Options are boolean variables, with possible values ON/OFF. Options and @@ -194,14 +194,12 @@

    cmake -DVARIABLE:TYPE=value path/to/llvm/source

    -
    -

    Frequently-used CMake variables

    -
    +

    Here are listed some of the CMake variables that are used often, along with a brief explanation and LLVM-specific notes. For full @@ -244,7 +242,7 @@

    LLVM-specific variables

    -
    +
    LLVM_TARGETS_TO_BUILD:STRING
    @@ -357,13 +355,15 @@

    +
    +

    Executing the test suite

    -
    +

    Testing is performed when the check target is built. For instance, if you are using makefiles, execute this command while on @@ -383,7 +383,7 @@

    -
    +

    See this wiki page for generic instructions on how to cross-compile @@ -404,7 +404,7 @@

    -
    +

    The most difficult part of adding LLVM to the build of a project is to determine the set of LLVM libraries corresponding to the set @@ -459,14 +459,12 @@

    -
    -

    Developing LLVM pass out of source

    -
    +

    It is possible to develop LLVM passes against installed LLVM. An example of project layout provided below:

    @@ -518,23 +516,23 @@

    +
    +

    Compiler/Platform specific topics

    -
    +

    Notes for specific compilers and/or platforms.

    -
    -

    Microsoft Visual C++

    -
    +
    LLVM_COMPILER_JOBS:STRING
    @@ -546,6 +544,8 @@

    +
    +
    diff --git a/docs/CodeGenerator.html b/docs/CodeGenerator.html index 50036f2ed73f9..9185563323924 100644 --- a/docs/CodeGenerator.html +++ b/docs/CodeGenerator.html @@ -132,7 +132,7 @@

    -
    +

    The LLVM target-independent code generator is a framework that provides a suite of reusable components for translating the LLVM internal representation @@ -188,14 +188,12 @@

    depend on the target-description and machine code representation classes, ensuring that it is portable.

    -

    -

    Required components in the code generator

    -
    +

    The two pieces of the LLVM code generator are the high-level interface to the code generator and the set of reusable components that can be used to build @@ -227,7 +225,7 @@

    The high-level design of the code generator

    -
    +

    The LLVM target-independent code generator is designed to support efficient and quality code generation for standard register-based microprocessors. @@ -301,7 +299,7 @@

    Using TableGen for target description

    -
    +

    The target description classes require a detailed description of the target architecture. These target descriptions often have a large amount of common @@ -324,13 +322,15 @@

    +
    +

    Target description classes

    -
    +

    The LLVM target description classes (located in the include/llvm/Target directory) provide an abstract description of @@ -346,14 +346,12 @@

    TargetMachine class provides accessors that should be implemented by the target.

    -

    -

    The TargetMachine class

    -
    +

    The TargetMachine class provides virtual methods that are used to access the target-specific implementations of the various target description @@ -373,7 +371,7 @@

    The TargetData class

    -
    +

    The TargetData class is the only required target description class, and it is the only class that is not extensible (you cannot derived a new @@ -389,7 +387,7 @@

    The TargetLowering class

    -
    +

    The TargetLowering class is used by SelectionDAG based instruction selectors primarily to describe how LLVM code should be lowered to @@ -415,7 +413,7 @@

    The TargetRegisterInfo class

    -
    +

    The TargetRegisterInfo class is used to describe the register file of the target and any interactions between the registers.

    @@ -449,7 +447,7 @@

    The TargetInstrInfo class

    -
    +

    The TargetInstrInfo class is used to describe the machine instructions supported by the target. It is essentially an array of @@ -467,7 +465,7 @@

    The TargetFrameInfo class

    -
    +

    The TargetFrameInfo class is used to provide information about the stack frame layout of the target. It holds the direction of stack growth, the @@ -483,7 +481,7 @@

    The TargetSubtarget class

    -
    +

    The TargetSubtarget class is used to provide information about the specific chip set being targeted. A sub-target informs code generation of @@ -499,7 +497,7 @@

    The TargetJITInfo class

    -
    +

    The TargetJITInfo class exposes an abstract interface used by the Just-In-Time code generator to perform target-specific activities, such as @@ -509,13 +507,15 @@

    +
    +

    Machine code description classes

    -
    +

    At the high-level, LLVM code is translated to a machine specific representation formed out of @@ -528,14 +528,12 @@

    SSA representation for machine code, as well as a register allocated, non-SSA form.

    -

    -

    The MachineInstr class

    -
    +

    Target machine instructions are represented as instances of the MachineInstr class. This class is an extremely abstract way of @@ -576,14 +574,12 @@

    Also if the first operand is a def, it is easier to create instructions whose only def is the first operand.

    -

    -

    Using the MachineInstrBuilder.h functions

    -
    +

    Machine instructions are created by using the BuildMI functions, located in the include/llvm/CodeGen/MachineInstrBuilder.h file. The @@ -634,7 +630,7 @@

    Fixed (preassigned) registers

    -
    +

    One important issue that the code generator needs to be aware of is the presence of fixed registers. In particular, there are often places in the @@ -706,7 +702,7 @@

    Machine code in SSA form

    -
    +

    MachineInstr's are initially selected in SSA-form, and are maintained in SSA-form until register allocation happens. For the most part, @@ -719,12 +715,14 @@

    +
    +

    The MachineBasicBlock class

    -
    +

    The MachineBasicBlock class contains a list of machine instructions (MachineInstr instances). It roughly @@ -741,7 +739,7 @@

    The MachineFunction class

    -
    +

    The MachineFunction class contains a list of machine basic blocks (MachineBasicBlock instances). It @@ -754,6 +752,7 @@

    +

    @@ -761,7 +760,7 @@

    -
    +

    The MC Layer is used to represent and process code at the raw machine code @@ -779,15 +778,12 @@

    in this manual.

    -

    - -

    The MCStreamer API

    -
    +

    MCStreamer is best thought of as an assembler API. It is an abstract API which @@ -821,7 +817,7 @@

    The MCContext class

    -
    +

    The MCContext class is the owner of a variety of uniqued data structures at the @@ -836,7 +832,7 @@

    The MCSymbol class

    -
    +

    The MCSymbol class represents a symbol (aka label) in the assembly file. There @@ -868,7 +864,7 @@

    The MCSection class

    -
    +

    The MCSection class represents an object-file specific section. It is subclassed @@ -886,7 +882,7 @@

    The MCInst class

    -
    +

    The MCInst class is a target-independent representation of an instruction. It @@ -904,6 +900,7 @@

    +

    @@ -911,20 +908,18 @@

    -
    +

    This section documents the phases described in the high-level design of the code generator. It explains how they work and some of the rationale behind their design.

    -
    -

    Instruction Selection

    -
    +

    Instruction Selection is the process of translating LLVM code presented to the code generator into target-specific machine instructions. There are @@ -936,14 +931,12 @@

    selector to be generated from these .td files, though currently there are still things that require custom C++ code.

    -

    -

    Introduction to SelectionDAGs

    -
    +

    The SelectionDAG provides an abstraction for code representation in a way that is amenable to instruction selection using automatic techniques @@ -1005,7 +998,7 @@

    SelectionDAG Instruction Selection Process

    -
    +

    SelectionDAG-based instruction selection consists of the following steps:

    @@ -1086,7 +1079,7 @@

    Initial SelectionDAG Construction

    -
    +

    The initial SelectionDAG is naïvely peephole expanded from the LLVM input by the SelectionDAGLowering class in the @@ -1106,7 +1099,7 @@

    SelectionDAG LegalizeTypes Phase

    -
    +

    The Legalize phase is in charge of converting a DAG to only use the types that are natively supported by the target.

    @@ -1139,7 +1132,7 @@

    SelectionDAG Legalize Phase

    -
    +

    The Legalize phase is in charge of converting a DAG to only use the operations that are natively supported by the target.

    @@ -1173,7 +1166,7 @@

    -
    +

    The SelectionDAG optimization phase is run multiple times for code generation, immediately after the DAG is built and once after each @@ -1207,7 +1200,7 @@

    SelectionDAG Select Phase

    -
    +

    The Select phase is the bulk of the target-specific code for instruction selection. This phase takes a legal SelectionDAG as input, pattern matches @@ -1368,7 +1361,7 @@

    SelectionDAG Scheduling and Formation Phase

    -
    +

    The scheduling phase takes the DAG of target instructions from the selection phase and assigns an order. The scheduler can pick an order depending on @@ -1389,7 +1382,7 @@

    Future directions for the SelectionDAG

    -
    +
    1. Optional function-at-a-time selection.
    2. @@ -1399,18 +1392,20 @@

    +
    +

    SSA-based Machine Code Optimizations

    -

    To Be Written

    +

    To Be Written

    Live Intervals

    -
    +

    Live Intervals are the ranges (intervals) where a variable is live. They are used by some register allocator passes to @@ -1418,14 +1413,12 @@

    register are live at the same point in the program (i.e., they conflict). When this situation occurs, one virtual register must be spilled.

    -

    -

    Live Variable Analysis

    -
    +

    The first step in determining the live intervals of variables is to calculate the set of registers that are immediately dead after the instruction (i.e., @@ -1471,7 +1464,7 @@

    Live Intervals Analysis

    -
    +

    We now have the information available to perform the live intervals analysis and build the live intervals themselves. We start off by numbering the basic @@ -1486,12 +1479,14 @@

    +
    +

    Register Allocation

    -
    +

    The Register Allocation problem consists in mapping a program Pv, that can use an unbounded number of virtual registers, @@ -1501,15 +1496,13 @@

    accommodate all the virtual registers, some of them will have to be mapped into memory. These virtuals are called spilled virtuals.

    -

    -

    How registers are represented in LLVM

    -
    +

    In LLVM, physical registers are denoted by integer numbers that normally range from 1 to 1023. To see how this numbering is defined for a particular @@ -1622,7 +1615,7 @@

    Mapping virtual registers to physical registers

    -
    +

    There are two ways to map virtual registers to physical registers (or to memory slots). The first way, that we will call direct mapping, is @@ -1672,7 +1665,7 @@

    Handling two address instructions

    -
    +

    With very rare exceptions (e.g., function calls), the LLVM machine code instructions are three address instructions. That is, each instruction is @@ -1708,7 +1701,7 @@

    The SSA deconstruction phase

    -
    +

    An important transformation that happens during register allocation is called the SSA Deconstruction Phase. The SSA form simplifies many analyses @@ -1732,7 +1725,7 @@

    Instruction folding

    -
    +

    Instruction folding is an optimization performed during register allocation that removes unnecessary copy instructions. For instance, a @@ -1769,7 +1762,7 @@

    Built in register allocators

    -
    +

    The LLVM infrastructure provides the application developer with three different register allocators:

    @@ -1806,23 +1799,25 @@

    +
    +

    Prolog/Epilog Code Insertion

    -

    To Be Written

    +

    To Be Written

    Late Machine Code Optimizations

    -

    To Be Written

    +

    To Be Written

    Code Emission

    -
    +

    The code emission step of code generation is responsible for lowering from the code generator abstractions (like

    +

    @@ -1888,7 +1884,7 @@

    -
    +

    Though you're probably reading this because you want to write or maintain a compiler backend, LLVM also fully supports building a native assemblers too. @@ -1897,12 +1893,10 @@

    part of the manual and repetitive data entry can be factored and shared with the compiler.

    -

    -

    Instruction Parsing

    -

    To Be Written

    +

    To Be Written

    @@ -1910,7 +1904,7 @@

    Instruction Alias Processing

    -
    +

    Once the instruction is parsed, it enters the MatchInstructionImpl function. The MatchInstructionImpl function performs alias processing and then does actual matching.

    @@ -1923,12 +1917,10 @@

    meets the needs of your instruction, because it will allow a more concise description.

    -

    -

    Mnemonic Aliases

    -
    +

    The first phase of alias processing is simple instruction mnemonic remapping for classes of instructions which are allowed with two different @@ -1968,7 +1960,7 @@

    Mnemonic Aliases

    Instruction Aliases

    -
    +

    The most general phase of alias processing occurs while matching is happening: it provides new forms for the matcher to match along with a specific @@ -2029,15 +2021,14 @@

    Instruction Aliases

    - +

    Instruction Matching

    -

    To Be Written

    - - +

    To Be Written

    +

    @@ -2045,20 +2036,18 @@

    -
    +

    This section of the document explains features or design decisions that are specific to the code generator for a particular target. First we start with a table that summarizes what features are supported by each target.

    -
    -

    Target Feature Matrix

    -
    +

    Note that this table does not include the C backend or Cpp backends, since they do not use the target independent code generator infrastructure. It also @@ -2229,12 +2218,10 @@

    -

    -

    Is Generally Reliable

    -
    +

    This box indicates whether the target is considered to be production quality. This indicates that the target has been used as a static compiler to compile large amounts of code by a variety of different people and is in @@ -2244,7 +2231,7 @@

    Is Generally Reliable

    Assembly Parser

    -
    +

    This box indicates whether the target supports parsing target specific .s files by implementing the MCAsmParser interface. This is required for llvm-mc to be able to act as a native assembler and is required for inline assembly @@ -2256,7 +2243,7 @@

    Assembly Parser

    Disassembler

    -
    +

    This box indicates whether the target supports the MCDisassembler API for disassembling machine opcode bytes into MCInst's.

    @@ -2265,7 +2252,7 @@

    Disassembler

    Inline Asm

    -
    +

    This box indicates whether the target supports most popular inline assembly constraints and modifiers.

    @@ -2277,7 +2264,7 @@

    Inline Asm

    JIT Support

    -
    +

    This box indicates whether the target supports the JIT compiler through the ExecutionEngine interface.

    @@ -2289,7 +2276,7 @@

    JIT Support

    .o File Writing

    -
    +

    This box indicates whether the target supports writing .o files (e.g. MachO, ELF, and/or COFF) files directly from the target. Note that the target also @@ -2305,7 +2292,7 @@

    .o File Writing

    Tail Calls

    -
    +

    This box indicates whether the target supports guaranteed tail calls. These are calls marked "tail" and use the fastcc @@ -2314,15 +2301,14 @@

    Tail Calls

    - - +

    Tail call optimization

    -
    +

    Tail call optimization, callee reusing the stack of the caller, is currently supported on x86/x86-64 and PowerPC. It is performed if:

    @@ -2388,7 +2374,7 @@

    Sibling call optimization

    -
    +

    Sibling call optimization is a restricted form of tail call optimization. Unlike tail call optimization described in the previous section, it can be @@ -2432,20 +2418,18 @@

    The X86 backend

    -
    +

    The X86 code generator lives in the lib/Target/X86 directory. This code generator is capable of targeting a variety of x86-32 and x86-64 processors, and includes support for ISA extensions such as MMX and SSE.

    -
    -

    X86 Target Triples supported

    -
    +

    The following are the known target triples that are supported by the X86 backend. This is not an exhaustive list, and it would be useful to add those @@ -2475,7 +2459,7 @@

    -
    +

    The following target-specific calling conventions are known to backend:

    @@ -2494,7 +2478,7 @@

    Representing X86 addressing modes in MachineInstrs

    -
    +

    The x86 has a very flexible way of accessing memory. It is capable of forming memory addresses of the following expression directly in integer @@ -2531,7 +2515,7 @@

    X86 address spaces supported

    -
    +

    x86 has a feature which provides the ability to perform loads and stores to different address spaces @@ -2576,7 +2560,7 @@

    Instruction naming

    -
    +

    An instruction name consists of the base name, a default operand size, and a a character per operand with an optional special size. For example:

    @@ -2592,25 +2576,25 @@

    +
    +

    The PowerPC backend

    -
    +

    The PowerPC code generator lives in the lib/Target/PowerPC directory. The code generation is retargetable to several variations or subtargets of the PowerPC ISA; including ppc32, ppc64 and altivec.

    -
    -

    LLVM PowerPC ABI

    -
    +

    LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC relative (PIC) or static addressing for accessing global values, so no TOC @@ -2630,7 +2614,7 @@

    Frame Layout

    -
    +

    The size of a PowerPC frame is usually fixed for the duration of a function's invocation. Since the frame is fixed size, all references @@ -2777,7 +2761,7 @@

    Prolog/Epilog

    -
    +

    The llvm prolog and epilog are the same as described in the PowerPC ABI, with the following exceptions. Callee saved registers are spilled after the frame @@ -2794,12 +2778,15 @@

    Dynamic Allocation

    -
    +

    TODO - More to come.

    +
    + +

    diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index ca31cab2ca094..7f92b9a7cf0b2 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -88,7 +88,7 @@

    -
    +

    This document attempts to describe a few coding standards that are being used in the LLVM source tree. Although no coding standards should be regarded as @@ -122,17 +122,21 @@

    +
    +

    Source Code Formatting

    +
    +

    Commenting

    -
    +

    Comments are one critical part of readability and maintainability. Everyone knows they should comment, so should you. When writing comments, write them as @@ -141,7 +145,9 @@

    comment our code more than we do, there are a few very critical places that documentation is very useful:

    -File Headers +

    File Headers
    + +

    Every source file should have a header on it that describes the basic purpose of the file. If a file does not have a header, it should not be @@ -184,7 +190,9 @@

    tricky is going on, a reference to the paper where it is published should be included, as well as any notes or "gotchas" in the code to watch out for.

    -Class overviews +

    + +
    Class overviews

    Classes are one fundamental part of a good object oriented design. As such, a class definition should have a comment block that explains what the class is @@ -193,7 +201,9 @@

    something sane goes a long ways towards avoiding writing documentation.

    -Method information +

    Method information
    + +

    Methods defined in a class (as well as any global functions) should also be documented properly. A quick note about what it does and a description of the @@ -207,12 +217,14 @@

    +
    +

    Comment Formatting

    -
    +

    In general, prefer C++ style (//) comments. They take less space, require less typing, don't have nesting problems, etc. There are a few cases @@ -237,7 +249,7 @@

    #include Style

    -
    +

    Immediately after the header file comment (and include guards if working on a header file), the Source Code Width -

    +

    Write your code to fit within 80 columns of text. This helps those of us who like to print out code and look at your code in an xterm without resizing @@ -302,7 +314,7 @@

    Use Spaces Instead of Tabs

    -
    +

    In all cases, prefer spaces to tabs in source files. People have different preferred indentation levels, and different styles of indentation that they @@ -323,7 +335,7 @@

    Indent Code Consistently

    -
    +

    Okay, in your first year of programming you were told that indentation is important. If you didn't believe and internalize this then, now is the time. @@ -331,19 +343,21 @@

    +

    Compiler Issues

    +

    Treat Compiler Warnings Like Errors

    -
    +

    If your code has compiler warnings in it, something is wrong — you aren't casting values correctly, your have "questionable" constructs in your @@ -397,7 +411,7 @@

    Write Portable Code

    -
    +

    In almost all cases, it is possible and within reason to write completely portable code. If there are cases where it isn't possible to write portable @@ -415,7 +429,7 @@

    Do not use RTTI or Exceptions

    -
    +

    In an effort to reduce code and executable size, LLVM does not use RTTI (e.g. dynamic_cast<>) or exceptions. These two language features @@ -436,7 +450,7 @@

    Use of class and struct Keywords

    -
    +

    In C++, the class and struct keywords can be used almost interchangeably. The only difference is when they are used to declare a class: @@ -454,12 +468,17 @@

    +
    + +
    +

    Style Issues

    +

    @@ -467,13 +486,14 @@

    +

    A Public Header File is a Module

    -
    +

    C++ doesn't do too well in the modularity department. There is no real encapsulation or data hiding (unless you use expensive protocol classes), but it @@ -503,7 +523,7 @@

    #include as Little as Possible

    -
    +

    #include hurts compile time performance. Don't do it unless you have to, especially in header files.

    @@ -532,7 +552,7 @@

    Keep "Internal" Headers Private

    -
    +

    Many modules have a complex implementation that causes them to use more than one implementation (.cpp) file. It is often tempting to put the @@ -553,7 +573,7 @@

    Use Early Exits and continue to Simplify Code

    -
    +

    When reading code, keep in mind how much state and how many previous decisions have to be remembered by the reader to understand a block of code. @@ -662,7 +682,7 @@

    Don't use else after a return

    -
    +

    For similar reasons above (reduction of indentation and easier reading), please do not use 'else' or 'else if' after something that @@ -745,7 +765,7 @@

    Turn Predicate Loops into Predicate Functions

    -
    +

    It is very common to write small loops that just compute a boolean value. There are a number of ways that people commonly write these, but an example of @@ -802,6 +822,7 @@

    +

    @@ -809,6 +830,7 @@

    +

    @@ -817,7 +839,7 @@

    -
    +

    Poorly-chosen names can mislead the reader and cause bugs. We cannot stress enough how important it is to use descriptive names. Pick names that @@ -900,7 +922,7 @@

    Assert Liberally

    -
    +

    Use the "assert" macro to its fullest. Check all of your preconditions and assumptions, you never know when a bug (not necessarily even @@ -1003,7 +1025,7 @@

    Do Not Use 'using namespace std'

    -
    +

    In LLVM, we prefer to explicitly prefix all identifiers from the standard namespace with an "std::" prefix, rather than rely on @@ -1043,7 +1065,7 @@

    -
    +

    If a class is defined in a header file and has a v-table (either it has virtual methods or it derives from classes with virtual methods), it must @@ -1059,7 +1081,7 @@

    Don't evaluate end() every time through a loop

    -
    +

    Because C++ doesn't have a standard "foreach" loop (though it can be emulated with macros and may be coming in C++'0x) we end up writing a lot of @@ -1121,7 +1143,7 @@

    #include <iostream> is Forbidden

    -
    +

    The use of #include <iostream> in library files is hereby forbidden. The primary reason for doing this is to @@ -1156,7 +1178,7 @@

    Use raw_ostream

    -
    +

    LLVM includes a lightweight, simple, and efficient stream implementation in llvm/Support/raw_ostream.h, which provides all of the common @@ -1176,7 +1198,7 @@

    Avoid std::endl

    -
    +

    The std::endl modifier, when used with iostreams outputs a newline to the output stream specified. In addition to doing this, however, it @@ -1194,6 +1216,7 @@

    +

    @@ -1201,6 +1224,8 @@

    +
    +

    This section describes preferred low-level formatting guidelines along with reasoning on why we prefer them.

    @@ -1209,7 +1234,7 @@

    Spaces Before Parentheses

    -
    +

    We prefer to put a space before an open parenthesis only in control flow statements, but not in normal function call expressions and function-like @@ -1267,7 +1292,7 @@

    Prefer Preincrement

    -
    +

    Hard fast rule: Preincrement (++X) may be no slower than postincrement (X++) and could very well be a lot faster than it. Use @@ -1287,7 +1312,7 @@

    Namespace Indentation

    -
    +

    In general, we strive to reduce indentation wherever possible. This is useful @@ -1375,7 +1400,7 @@

    Anonymous Namespaces

    -
    +

    After talking about namespaces in general, you may be wondering about anonymous namespaces in particular. @@ -1455,7 +1480,9 @@

    +
    +

    @@ -1463,7 +1490,7 @@

    -
    +

    A lot of these comments and recommendations have been culled for other sources. Two particularly important books for our work are:

    diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html index 98e97ee000f31..b839d3cb32c79 100644 --- a/docs/CommandGuide/index.html +++ b/docs/CommandGuide/index.html @@ -11,7 +11,7 @@

    LLVM Command Guide

    -
    +

    These documents are HTML versions of the man pages for all of the LLVM tools. These pages describe how to use the LLVM commands @@ -28,7 +28,7 @@

    -
    +
      @@ -85,7 +85,7 @@

      -
      +
      • llvm-gcc - @@ -105,7 +105,7 @@

        -
        +
          @@ -128,7 +128,7 @@

          -
          +
          • FileCheck - diff --git a/docs/CommandLine.html b/docs/CommandLine.html index 0bcd38267cc96..179e8e6c0b3dd 100644 --- a/docs/CommandLine.html +++ b/docs/CommandLine.html @@ -105,7 +105,7 @@

            -
            +

            This document describes the CommandLine argument processing library. It will show you how to use it, and what it can do. The CommandLine library uses a @@ -189,7 +189,7 @@

            -
            +

            This section of the manual runs through a simple CommandLine'ification of a basic compiler tool. This is intended to show you how to jump into using the @@ -321,14 +321,12 @@

            ... indicating that an input filename is expected.

            -

            -

            Boolean Arguments

            -
            +

            In addition to input and output filenames, we would like the compiler example to support three boolean flags: "-f" to force writing binary output to @@ -410,7 +408,7 @@

            Argument Aliases

            -
            +

            So far, the example works well, except for the fact that we need to check the quiet condition like this now:

            @@ -461,7 +459,7 @@

            possibilities

            -
            +

            So far we have seen how the CommandLine library handles builtin types like std::string, bool and int, but how does it handle @@ -571,7 +569,7 @@

            Named Alternatives

            -
            +

            Another useful argument form is a named alternative style. We shall use this style in our compiler to specify different debug levels that can be used. @@ -633,7 +631,7 @@

            Parsing a list of options

            -
            +

            Now that we have the standard run-of-the-mill argument types out of the way, lets get a little wild and crazy. Lets say that we want our optimizer to accept @@ -703,7 +701,7 @@

            Collecting options as a set of flags

            -
            +

            Instead of collecting sets of options in a list, it is also possible to gather information for enum values in a bit vector. The representation used by @@ -762,7 +760,7 @@

            Adding freeform text to help output

            -
            +

            As our program grows and becomes more mature, we may decide to put summary information about what it does into the help output. The help output is styled @@ -800,6 +798,7 @@

            +

            @@ -807,21 +806,19 @@

            -
            +

            Now that you know the basics of how to use the CommandLine library, this section will give you the detailed information you need to tune how command line options work, as well as information on more "advanced" command line option processing capabilities.

            -
            -

            Positional Arguments

            -
            +

            Positional arguments are those arguments that are not named, and are not specified with a hyphen. Positional arguments should be used when an option is @@ -854,15 +851,12 @@

            are defined in multiple .cpp files. The fix for this problem is simply to define all of your positional arguments in one .cpp file.

            -

            - -

            Specifying positional options with hyphens

            -
            +

            Sometimes you may want to specify a value to your positional argument that starts with a hyphen (for example, searching for '-foo' in a file). At @@ -898,7 +892,7 @@

            Determining absolute position with getPosition()

            -
            +

            Sometimes an option can affect or modify the meaning of another option. For example, consider gcc's -x LANG option. This tells gcc to ignore the suffix of subsequent positional arguments and force @@ -958,7 +952,7 @@

            The cl::ConsumeAfter modifier

            -
            +

            The cl::ConsumeAfter formatting option is used to construct programs that use "interpreter style" option processing. With @@ -1006,12 +1000,14 @@

            +
            +

            Internal vs External Storage

            -
            +

            By default, all command line options automatically hold the value that they parse from the command line. This is very convenient in the common case, @@ -1080,7 +1076,7 @@

            Option Attributes

            -
            +

            This section describes the basic attributes that you can specify on options.

            @@ -1170,7 +1166,7 @@

            Option Modifiers

            -
            +

            Option modifiers are the flags and expressions that you pass into the constructors for cl::opt and that are the most useful in practice and the most common, which mean that you usually shouldn't have to worry about these.

            -
            -

            Hiding an option from -help output

            -
            +

            The cl::NotHidden, cl::Hidden, and cl::ReallyHidden modifiers are used to control whether or not an option @@ -1235,7 +1229,7 @@

            allowed

            -
            +

            This group of options is used to control how many time an option is allowed (or required) to be specified on the command line of your program. Specifying a @@ -1283,7 +1277,7 @@

            Controlling whether or not a value must be specified

            -
            +

            This group of options is used to control whether or not the option allows a value to be present. In the case of the CommandLine library, a value is either @@ -1332,7 +1326,7 @@

            Controlling other formatting options

            -
            +

            The formatting option group is used to specify that the command line option has special abilities and is otherwise different from other command line @@ -1413,7 +1407,7 @@

            Miscellaneous option modifiers

            -
            +

            The miscellaneous option modifiers are the only flags where you can specify more than one flag from the set: they are not mutually exclusive. These flags @@ -1457,7 +1451,7 @@

            Response files

            -
            +

            Some systems, such as certain variants of Microsoft Windows and some older Unices have a relatively low limit on command-line @@ -1474,13 +1468,14 @@

            +

            Top-Level Classes and Functions

            -
            +

            Despite all of the built-in flexibility, the CommandLine option library really only consists of one function ( href="#cl::alias">cl::alias. This section describes these three classes in detail.

            -
            -

            The cl::ParseCommandLineOptions function

            -
            +

            The cl::ParseCommandLineOptions function is designed to be called directly from main, and is used to fill in the values of all of the @@ -1519,7 +1512,7 @@

            function

            -
            +

            The cl::ParseEnvironmentOptions function has mostly the same effects as function

        -
        +

        The cl::SetVersionPrinter function is designed to be called directly from main and before @@ -1576,7 +1569,7 @@

        The cl::opt class

        -
        +

        The cl::opt class is the class used to represent scalar command line options, and is the one used most of the time. It is a templated class which @@ -1611,7 +1604,7 @@

        The cl::list class

        -
        +

        The cl::list class is the class used to represent a list of command line options. It too is a templated class which can take up to three @@ -1638,7 +1631,7 @@

        The cl::bits class

        -
        +

        The cl::bits class is the class used to represent a list of command line options in the form of a bit vector. It is also a templated class which @@ -1663,7 +1656,7 @@

        The cl::alias class

        -
        +

        The cl::alias class is a nontemplated class that is used to form aliases for other arguments.

        @@ -1686,7 +1679,7 @@

        The cl::extrahelp class

        -
        +

        The cl::extrahelp class is a nontemplated class that allows extra help text to be printed out for the -help option.

        @@ -1709,12 +1702,14 @@

        +
        +

        Builtin parsers

        -
        +

        Parsers control how the string value taken from the command line is translated into a typed value, suitable for use in a C++ program. By default, @@ -1773,27 +1768,27 @@

        +
        +

        Extension Guide

        -
        +

        Although the CommandLine library has a lot of functionality built into it already (as discussed previously), one of its true strengths lie in its extensibility. This section discusses how the CommandLine library works under the covers and illustrates how to do some simple, common, extensions.

        -
        -

        Writing a custom parser

        -
        +

        One of the simplest and most common extensions is the use of a custom parser. As discussed previously, parsers are the portion @@ -1936,7 +1931,7 @@

        Exploiting external storage

        -
        +

        Several of the LLVM libraries define static cl::opt instances that will automatically be included in any program that links with that library. This is a feature. However, sometimes it is necessary to know the value of the @@ -1955,12 +1950,14 @@

        Dynamically adding command line options

        -
        +

        TODO: fill in this section

        +
        +
        diff --git a/docs/CompilerWriterInfo.html b/docs/CompilerWriterInfo.html index 6be1b63e6523b..d9201fc8a4e2f 100644 --- a/docs/CompilerWriterInfo.html +++ b/docs/CompilerWriterInfo.html @@ -46,10 +46,12 @@

        Hardware

        +
        +

        Alpha

        -
        +
        • Alpha manuals @@ -60,7 +62,7 @@

          Alpha

          ARM

          -
          +
          • ARM documentation (Processor @@ -72,7 +74,7 @@

            ARM

            Itanium (ia64)

            -
            +
            • Itanium documentation @@ -83,7 +85,7 @@

              Itanium (ia64)

              MIPS

              -
              +
              • MIPS @@ -94,10 +96,12 @@

                MIPS

                PowerPC

                +
                +

                IBM - Official manuals and docs

                -
                +
                • IBM - Official manuals and docs

                  Other documents, collections, notes

                  -
                  +
                  +
                  +

                  SPARC

                  -
                  +
                  • SPARC resources
                  • @@ -158,10 +164,12 @@

                    SPARC

                    X86

                    +
                    +

                    AMD - Official manuals and docs

                    -
                    +
                    • AMD processor manuals
                    • @@ -172,7 +180,7 @@

                      AMD - Official manuals and docs

                      Intel - Official manuals and docs

                      -
                      +
                      • IA-32 @@ -186,17 +194,19 @@

                        Intel - Official manuals and docs

                        Other x86-specific information

                        -
                        +

                        Other relevant lists

                        -
                        +
                        +
                        +

                        ABI

                        +
                        +

                        Linux

                        -
                        +
                        1. PowerPC 64-bit ELF ABI Supplement
                        2. @@ -221,7 +235,7 @@

                          Linux

                          OS X

                          - +

                          Miscellaneous resources

                          diff --git a/docs/DebuggingJITedCode.html b/docs/DebuggingJITedCode.html index f23fdf6f39189..3911ea75ffb91 100644 --- a/docs/DebuggingJITedCode.html +++ b/docs/DebuggingJITedCode.html @@ -17,7 +17,7 @@

                          Debugging JITed Code With GDB

                          Example usage

                          -
                          +

                          In order to debug code JITed by LLVM, you need GDB 7.0 or newer, which is available on most modern distributions of Linux. The version of GDB that Apple @@ -98,7 +98,7 @@

                          Example usage

                          Background

                          -
                          +

                          Without special runtime support, debugging dynamically generated code with GDB (as well as most debuggers) can be quite painful. Debuggers generally read diff --git a/docs/DeveloperPolicy.html b/docs/DeveloperPolicy.html index 5d6c2d8559025..fee28384ebb16 100644 --- a/docs/DeveloperPolicy.html +++ b/docs/DeveloperPolicy.html @@ -36,7 +36,7 @@

                          LLVM Developer Policy

                          Introduction

                          -
                          +

                          This document contains the LLVM Developer Policy which defines the project's policy towards developers and their contributions. The intent of this policy is to eliminate miscommunication, rework, and confusion that might arise from @@ -65,18 +65,17 @@

                          Introduction

                          Developer Policies

                          -
                          +

                          This section contains policies that pertain to frequent LLVM developers. We always welcome one-off patches from people who do not routinely contribute to LLVM, but we expect more from frequent contributors to keep the system as efficient as possible for everyone. Frequent LLVM contributors are expected to meet the following requirements in order for LLVM to maintain a high standard of quality.

                          -

                          Stay Informed

                          -
                          +

                          Developers should stay informed by reading at least the "dev" mailing list for the projects you are interested in, such as llvmdev for @@ -104,7 +103,7 @@

                          Stay Informed

                          Making a Patch

                          -
                          +

                          When making a patch for review, the goal is to make it as easy for the reviewer to read it as possible. As such, we recommend that you:

                          @@ -143,7 +142,7 @@

                          Making a Patch

                          Code Reviews

                          -
                          +

                          LLVM has a code review policy. Code review is one way to increase the quality of software. We generally follow these policies:

                          @@ -175,7 +174,7 @@

                          Code Reviews

                          Code Owners

                          -
                          +

                          The LLVM Project relies on two features of its process to maintain rapid development in addition to the high quality of its source base: the @@ -226,7 +225,7 @@

                          Code Owners

                          Test Cases

                          -
                          +

                          Developers are required to create test cases for any bugs fixed and any new features added. Some tips for getting your testcase approved:

                          @@ -259,7 +258,7 @@

                          Test Cases

                          Quality

                          -
                          +

                          The minimum quality standards that any change must satisfy before being committed to the main development branch are:

                          @@ -319,7 +318,7 @@

                          Quality

                          Obtaining Commit Access

                          -
                          +

                          We grant commit access to contributors with a track record of submitting high quality patches. If you would like commit access, please send an email to @@ -381,7 +380,7 @@

                          Obtaining Commit Access

                          Making a Major Change

                          -
                          +

                          When a developer begins a major new project with the aim of contributing it back to LLVM, s/he should inform the community with an email to the llvmdev @@ -410,7 +409,7 @@

                          Making a Major Change

                          Incremental Development

                          -
                          +

                          In the LLVM project, we do all significant changes as a series of incremental patches. We have a strong dislike for huge changes or long-term development branches. Long-term development branches have a number of drawbacks:

                          @@ -471,7 +470,7 @@

                          Incremental Development

                          Attribution of Changes

                          -
                          +

                          We believe in correct attribution of contributions to their contributors. However, we do not want the source code to be littered with random attributions "this code written by J. Random Hacker" (this is noisy and @@ -483,13 +482,15 @@

                          Attribution of Changes

                          Overall, please do not add contributor names to the source code.

                          +
                          +

                          Copyright, License, and Patents

                          -
                          +

                          This section addresses the issues of copyright, license and patents for the LLVM project. Currently, the University of Illinois is the LLVM copyright holder and the terms of its license to LLVM users and developers is the @@ -501,11 +502,10 @@

                          legal matters but does not provide legal advice. We are not lawyers, please seek legal counsel from an attorney.

                          -

                          Copyright

                          -
                          +

                          The LLVM project does not require copyright assignments, which means that the copyright for the code in the project is held by its respective contributors @@ -528,7 +528,7 @@

                          Copyright

                          License

                          -
                          +

                          We intend to keep LLVM perpetually open source and to use a liberal open source license. All of the code in LLVM is available under the University of @@ -583,7 +583,7 @@

                          License

                          Patents

                          -
                          +

                          To the best of our knowledge, LLVM does not infringe on any patents (we have actually removed code from LLVM in the past that was found to infringe). Having code in LLVM that infringes on patents would violate an important goal @@ -599,6 +599,8 @@

                          Patents

                          details.

                          +
                          +
                          diff --git a/docs/ExceptionHandling.html b/docs/ExceptionHandling.html index 09e094614292a..0d3ea1b62405a 100644 --- a/docs/ExceptionHandling.html +++ b/docs/ExceptionHandling.html @@ -61,7 +61,7 @@

                          Exception Handling in LLVM

                          Introduction

                          -
                          +

                          This document is the central repository for all information pertaining to exception handling in LLVM. It describes the format that LLVM exception @@ -70,14 +70,12 @@

                          Introduction

                          provides specific examples of what exception handling information is used for in C/C++.

                          -
                          -

                          Itanium ABI Zero-cost Exception Handling

                          -
                          +

                          Exception handling for most programming languages is designed to recover from conditions that rarely occur during general use of an application. To that @@ -110,7 +108,7 @@

                          Setjmp/Longjmp Exception Handling

                          -
                          +

                          Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics llvm.eh.sjlj.setjmp and @@ -142,7 +140,7 @@

                          Overview

                          -
                          +

                          When an exception is thrown in LLVM code, the runtime does its best to find a handler suited to processing the circumstance.

                          @@ -185,12 +183,14 @@

                          +
                          +

                          LLVM Code Generation

                          -
                          +

                          At the time of this writing, only C++ exception handling support is available in LLVM. So the remainder of this document will be somewhat C++-centric.

                          @@ -200,14 +200,12 @@

                          we will describe the implementation of LLVM exception handling in terms of C++ examples.

                          -

                          -

                          Throw

                          -
                          +

                          Languages that support exception handling typically provide a throw operation to initiate the exception process. Internally, a throw operation @@ -229,7 +227,7 @@

                          Try/Catch

                          -
                          +

                          A call within the scope of a try statement can potentially raise an exception. In those circumstances, the LLVM C++ front-end replaces the call @@ -317,7 +315,7 @@

                          Cleanups

                          -
                          +

                          To handle destructors and cleanups in try code, control may not run directly from a landing pad to the first catch. Control may actually flow @@ -336,7 +334,7 @@

                          Throw Filters

                          -
                          +

                          C++ allows the specification of which exception types can be thrown from a function. To represent this a top level landing pad may exist to filter out @@ -363,7 +361,7 @@

                          Restrictions

                          -
                          +

                          The semantics of the invoke instruction require that any exception that unwinds through an invoke call should result in a branch to the invoke's @@ -384,25 +382,25 @@

                          +
                          +

                          Exception Handling Intrinsics

                          -
                          +

                          LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to provide exception handling information at various points in generated code.

                          -
                          -

                          llvm.eh.exception

                          -
                          +
                             i8* %llvm.eh.exception()
                          @@ -417,7 +415,7 @@ 

                          llvm.eh.selector

                          -
                          +
                             i32 %llvm.eh.selector(i8*, i8*, ...)
                          @@ -449,7 +447,7 @@ 

                          llvm.eh.typeid.for

                          -
                          +
                             i32 %llvm.eh.typeid.for(i8*)
                          @@ -467,7 +465,7 @@ 

                          llvm.eh.sjlj.setjmp

                          -
                          +
                             i32 %llvm.eh.sjlj.setjmp(i8*)
                          @@ -496,7 +494,7 @@ 

                          llvm.eh.sjlj.longjmp

                          -
                          +
                             void %llvm.eh.sjlj.setjmp(i8*)
                          @@ -516,7 +514,7 @@ 

                          llvm.eh.sjlj.lsda

                          -
                          +
                             i8* %llvm.eh.sjlj.lsda()
                          @@ -535,7 +533,7 @@ 

                          llvm.eh.sjlj.callsite

                          -
                          +
                             void %llvm.eh.sjlj.callsite(i32)
                          @@ -553,7 +551,7 @@ 

                          llvm.eh.sjlj.dispatchsetup

                          -
                          +
                             void %llvm.eh.sjlj.dispatchsetup(i32)
                          @@ -565,24 +563,24 @@ 

                          +
                          +

                          Asm Table Formats

                          -
                          +

                          There are two tables that are used by the exception handling runtime to determine which actions should take place when an exception is thrown.

                          -
                          -

                          Exception Handling Frame

                          -
                          +

                          An exception handling frame eh_frame is very similar to the unwind frame used by dwarf debug info. The frame contains all the information @@ -600,7 +598,7 @@

                          Exception Tables

                          -
                          +

                          An exception table contains information about what actions to take when an exception is thrown in a particular part of a function's code. There is one @@ -611,12 +609,14 @@

                          +
                          +

                          ToDo

                          -
                          +
                            diff --git a/docs/ExtendingLLVM.html b/docs/ExtendingLLVM.html index 7f77bb77921f9..b720911df0a5f 100644 --- a/docs/ExtendingLLVM.html +++ b/docs/ExtendingLLVM.html @@ -36,7 +36,7 @@

                            -
                            +

                            During the course of using LLVM, you may wish to customize it for your research project or for experimentation. At this point, you may realize that @@ -73,7 +73,7 @@

                            -
                            +

                            Adding a new intrinsic function to LLVM is much easier than adding a new instruction. Almost all extensions to LLVM should start as an intrinsic @@ -135,7 +135,7 @@

                            -
                            +

                            As with intrinsics, adding a new SelectionDAG node to LLVM is much easier than adding a new instruction. New nodes are often added to help represent @@ -225,7 +225,7 @@

                            -
                            +

                            WARNING: adding instructions changes the bitcode format, and it will take some effort to maintain compatibility with @@ -282,20 +282,18 @@

                            -
                            +

                            WARNING: adding new types changes the bitcode format, and will break compatibility with currently-existing LLVM installations. Only add new types if it is absolutely necessary.

                            -
                            -

                            Adding a fundamental type

                            -
                            +
                              @@ -321,7 +319,7 @@

                              Adding a derived type

                              -
                              +
                              1. llvm/include/llvm/Type.h: @@ -373,6 +371,8 @@

                              +
                              +
                              diff --git a/docs/GCCFEBuildInstrs.html b/docs/GCCFEBuildInstrs.html index f3c94594977fb..6eb409b79c278 100644 --- a/docs/GCCFEBuildInstrs.html +++ b/docs/GCCFEBuildInstrs.html @@ -27,7 +27,7 @@

                              Building llvm-gcc from Source

                              -
                              +

                              This section describes how to acquire and build llvm-gcc 4.2, which is based on the GCC 4.2.1 front-end. Supported languages are Ada, C, C++, Fortran, @@ -70,7 +70,7 @@

                              Building llvm-gcc from Source

                              Building the Ada front-end

                              -
                              +

                              Building with support for Ada amounts to following the directions in the top-level README.LLVM file, adding ",ada" to EXTRALANGS, for example: EXTRALANGS=,ada

                              @@ -236,7 +236,7 @@

                              Building the Ada front-end

                              Building the Fortran front-end

                              -
                              +

                              To build with support for Fortran, follow the directions in the top-level README.LLVM file, adding ",fortran" to EXTRALANGS, for example:

                              @@ -250,7 +250,7 @@

                              Building the Fortran front-end

                              License Information

                              -
                              +

                              The LLVM GCC frontend is licensed to you under the GNU General Public License and the GNU Lesser General Public License. Please see the files COPYING and diff --git a/docs/GarbageCollection.html b/docs/GarbageCollection.html index aa83a2d6d832f..761e1d08cafc9 100644 --- a/docs/GarbageCollection.html +++ b/docs/GarbageCollection.html @@ -84,7 +84,7 @@

                              -
                              +

                              Garbage collection is a widely used technique that frees the programmer from having to know the lifetimes of heap objects, making software easier to produce @@ -124,14 +124,12 @@

                              This document describes the mechanisms and interfaces provided by LLVM to support accurate garbage collection.

                              -

                              -

                              Goals and non-goals

                              -
                              +

                              LLVM's intermediate representation provides garbage collection intrinsics that offer support for a broad class of @@ -198,13 +196,15 @@

                              +
                              +

                              Getting started

                              -
                              +

                              Using a GC with LLVM implies many things, for example:

                              @@ -246,14 +246,12 @@

                              includes a highly portable, built-in ShadowStack code generator. It is compiled into llc and works even with the interpreter and C backends.

                              -

                              -

                              In your compiler

                              -
                              +

                              To turn the shadow stack on for your functions, first call:

                              @@ -280,7 +278,7 @@

                              In your runtime

                              -
                              +

                              The shadow stack doesn't imply a memory allocation algorithm. A semispace collector or building atop malloc are great places to start, and can @@ -347,7 +345,7 @@

                              About the shadow stack

                              -
                              +

                              Unlike many GC algorithms which rely on a cooperative code generator to compile stack maps, this algorithm carefully maintains a linked list of stack @@ -372,13 +370,15 @@

                              +
                              +

                              IR features

                              -
                              +

                              This section describes the garbage collection facilities provided by the LLVM intermediate representation. The exact behavior @@ -390,8 +390,6 @@

                              need to interface with the GC library using the facilities provided by that program.

                              -

                              -

                              Specifying GC code generation: gc "..." @@ -401,7 +399,7 @@

                              define ty @name(...) gc "name" { ...

                              -
                              +

                              The gc function attribute is used to specify the desired GC style to the compiler. Its programmatic equivalent is the setGC method of @@ -426,7 +424,7 @@

                              void @llvm.gcroot(i8** %ptrloc, i8* %metadata)

                              -
                              +

                              The llvm.gcroot intrinsic is used to inform LLVM that a stack variable references an object on the heap and is to be tracked for garbage @@ -498,7 +496,7 @@

                              Reading and writing references in the heap

                              -
                              +

                              Some collectors need to be informed when the mutator (the program that needs garbage collection) either reads a pointer from or writes a pointer to a field @@ -534,8 +532,6 @@

                              calls with the corresponding load or store instruction if they are used.

                              -

                              -

                              Write barrier: llvm.gcwrite @@ -545,7 +541,7 @@

                              void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)

                              -
                              +

                              For write barriers, LLVM provides the llvm.gcwrite intrinsic function. It has exactly the same semantics as a non-volatile store to @@ -567,7 +563,7 @@

                              i8* @llvm.gcread(i8* %object, i8** %derived)

                              -
                              +

                              For read barriers, LLVM provides the llvm.gcread intrinsic function. It has exactly the same semantics as a non-volatile load from the @@ -580,13 +576,17 @@

                              +
                              + +
                              +

                              Implementing a collector plugin

                              -
                              +

                              User code specifies which GC code generation to use with the gc function attribute or, equivalently, with the setGC method of @@ -666,14 +666,12 @@

                              It is also possible to statically link the collector plugin into tools, such as a language-specific compiler front-end.

                              -

                              -

                              Overview of available features

                              -
                              +

                              GCStrategy provides a range of features through which a plugin may do useful work. Some of these are callbacks, some are algorithms that can @@ -962,7 +960,7 @@

                              Computing stack maps

                              -
                              +

                              LLVM automatically computes a stack map. One of the most important features of a GCStrategy is to compile this information into the executable in @@ -1018,7 +1016,7 @@

                              Initializing roots to null: InitRoots

                              -
                              +
                              MyGC::MyGC() {
                              @@ -1044,7 +1042,7 @@ 

                              CustomReadBarriers, and CustomWriteBarriers

                              -
                              +

                              For GCs which use barriers or unusual treatment of stack roots, these flags allow the collector to perform arbitrary transformations of the LLVM @@ -1133,7 +1131,7 @@

                              Generating safe points: NeededSafePoints

                              -
                              +

                              LLVM can compute four kinds of safe points:

                              @@ -1197,7 +1195,7 @@

                              Emitting assembly code: GCMetadataPrinter

                              -
                              +

                              LLVM allows a plugin to print arbitrary assembly code before and after the rest of a module's assembly code. At the end of the module, the GC can compile @@ -1341,6 +1339,7 @@

                              +

                              @@ -1348,7 +1347,7 @@

                              -
                              +

                              [Appel89] Runtime Tags Aren't Necessary. Andrew W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.

                              diff --git a/docs/GetElementPtr.html b/docs/GetElementPtr.html index d1c5b6c5367c0..2c32a9ea7cc73 100644 --- a/docs/GetElementPtr.html +++ b/docs/GetElementPtr.html @@ -61,7 +61,7 @@

                              Introduction

                              -
                              +

                              This document seeks to dispel the mystery and confusion surrounding LLVM's GetElementPtr (GEP) instruction. Questions about the wily GEP instruction are @@ -74,19 +74,18 @@

                              Introduction

                              Address Computation

                              -
                              +

                              When people are first confronted with the GEP instruction, they tend to relate it to known concepts from other programming paradigms, most notably C array indexing and field selection. GEP closely resembles C array indexing and field selection, however it's is a little different and this leads to the following questions.

                              -

                              What is the first index of the GEP instruction?

                              -
                              +

                              Quick answer: The index stepping through the first operand.

                              The confusion with the first index usually arises from thinking about the GetElementPtr instruction as if it was a C index operator. They aren't the @@ -209,7 +208,7 @@

                              Why is the extra 0 index required?

                              -
                              +

                              Quick answer: there are no superfluous indices.

                              This question arises most often when the GEP instruction is applied to a global variable which is always a pointer type. For example, consider @@ -250,7 +249,7 @@

                              What is dereferenced by GEP?

                              -
                              +

                              Quick answer: nothing.

                              The GetElementPtr instruction dereferences nothing. That is, it doesn't access memory in any way. That's what the Load and Store instructions are for. @@ -305,7 +304,7 @@

                              Why don't GEP x,0,0,1 and GEP x,1 alias?

                              -
                              +

                              Quick Answer: They compute different address locations.

                              If you look at the first indices in these GEP instructions you find that they are different (0 and 1), therefore the address @@ -334,7 +333,7 @@

                              Why do GEP x,1,0,0 and GEP x,1 alias?

                              -
                              +

                              Quick Answer: They compute the same address location.

                              These two GEP instructions will compute the same address because indexing through the 0th element does not change the address. However, it does change @@ -358,7 +357,7 @@

                              Can GEP index into vector elements?

                              -
                              +

                              This hasn't always been forcefully disallowed, though it's not recommended. It leads to awkward special cases in the optimizers, and fundamental inconsistency in the IR. In the future, it will probably be outright @@ -371,7 +370,7 @@

                              What effect do address spaces have on GEPs?

                              -
                              +

                              None, except that the address space qualifier on the first operand pointer type always matches the address space qualifier on the result type.

                              @@ -384,7 +383,7 @@

                              How is GEP different from ptrtoint, arithmetic, and inttoptr?

                              -
                              +

                              It's very similar; there are only subtle differences.

                              With ptrtoint, you have to pick an integer type. One approach is to pick i64; @@ -416,7 +415,7 @@

                              How do I do this?

                              -
                              +

                              You don't. The integer computation implied by a GEP is target-independent. Typically what you'll need to do is make your backend pattern-match expressions trees involving ADD, MUL, etc., which are what GEP is lowered @@ -437,7 +436,7 @@

                              How does VLA addressing work with GEPs?

                              -
                              +

                              GEPs don't natively support VLAs. LLVM's type system is entirely static, and GEP address computations are guided by an LLVM type.

                              @@ -453,16 +452,18 @@

                              VLA and non-VLA indexing in the same manner.

                              +
                              +

                              Rules

                              - +

                              What happens if an array index is out of bounds?

                              -
                              +

                              There are two senses in which an array index can be out of bounds.

                              First, there's the array type which comes from the (static) type of @@ -504,7 +505,7 @@

                              Can array indices be negative?

                              -
                              +

                              Yes. This is basically a special case of array indices being out of bounds.

                              @@ -514,7 +515,7 @@

                              Can I compare two values computed with GEPs?

                              -
                              +

                              Yes. If both addresses are within the same allocated object, or one-past-the-end, you'll get the comparison result you expect. If either is outside of it, integer arithmetic wrapping may occur, so the @@ -529,7 +530,7 @@

                              the underlying object?

                              -
                              +

                              Yes. There are no restrictions on bitcasting a pointer value to an arbitrary pointer type. The types in a GEP serve only to define the parameters for the underlying integer computation. They need not correspond with the actual @@ -548,7 +549,7 @@

                              Can I cast an object's address to integer and add it to null?

                              -
                              +

                              You can compute an address that way, but if you use GEP to do the add, you can't use that pointer to actually access the object, unless the object is managed outside of LLVM.

                              @@ -574,7 +575,7 @@

                              that value to one address to compute the other address?

                              -
                              +

                              As with arithmetic on null, You can use GEP to compute an address that way, but you can't use that pointer to actually access the object if you do, unless the object is managed outside of LLVM.

                              @@ -588,7 +589,7 @@

                              Can I do type-based alias analysis on LLVM IR?

                              -
                              +

                              You can't do type-based alias analysis using LLVM's built-in type system, because LLVM has no restrictions on mixing types in addressing, loads or stores.

                              @@ -605,7 +606,7 @@

                              What happens if a GEP computation overflows?

                              -
                              +

                              If the GEP lacks the inbounds keyword, the value is the result from evaluating the implied two's complement integer computation. However, since there's no guarantee of where an object will be allocated in the @@ -637,7 +638,7 @@

                              How can I tell if my front-end is following the rules?

                              -
                              +

                              There is currently no checker for the getelementptr rules. Currently, the only way to do this is to manually check each place in your front-end where GetElementPtr operators are created.

                              @@ -650,16 +651,18 @@

                              +
                              +

                              Rationale

                              - +

                              Why is GEP designed this way?

                              -
                              +

                              The design of GEP has the following goals, in rough unofficial order of priority:

                                @@ -681,7 +684,7 @@

                                Why do struct member indices always use i32?

                                -
                                +

                                The specific type i32 is probably just a historical artifact, however it's wide enough for all practical purposes, so there's been no need to change it. It doesn't necessarily imply i32 address arithmetic; it's just an identifier @@ -696,7 +699,7 @@

                                What's an uglygep?

                                -
                                +

                                Some LLVM optimizers operate on GEPs by internally lowering them into more primitive integer expressions, which allows them to be combined with other integer expressions and/or split into multiple separate @@ -713,11 +716,13 @@

                                +
                                +

                                Summary

                                -
                                +

                                In summary, here's some things to always remember about the GetElementPtr instruction:

                                  diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 2bca7ae643a20..7360893520f64 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -75,7 +75,7 @@

                                  -
                                  +

                                  Welcome to LLVM! In order to get started, you first need to know some basic information.

                                  @@ -107,7 +107,7 @@

                                  -
                                  +

                                  Here's the short story for getting up and running quickly with LLVM:

                                  @@ -196,20 +196,18 @@

                                  -
                                  +

                                  Before you begin to use the LLVM system, review the requirements given below. This may save you some trouble by knowing ahead of time what hardware and software you will need.

                                  -
                                  -

                                  Hardware

                                  -
                                  +

                                  LLVM is known to work on the following platforms:

                                  @@ -373,7 +371,7 @@

                                  Software

                                  -
                                  +

                                  Compiling LLVM requires that you have several software packages installed. The table below lists those required packages. The Package column is the usual name for the software package that LLVM depends on. The Version @@ -514,7 +512,7 @@

                                  Broken versions of GCC and other tools

                                  -
                                  +

                                  LLVM is very demanding of the host C++ compiler, and as such tends to expose bugs in the compiler. In particular, several versions of GCC crash when trying @@ -607,7 +605,7 @@

                                  - +

                                  @@ -615,7 +613,7 @@

                                  -
                                  +

                                  The remainder of this guide is meant to get you up and running with LLVM and to give you some basic information about the LLVM environment.

                                  @@ -625,14 +623,13 @@

                                  href="#tutorial">simple example using the LLVM tool chain, and links to find more information about LLVM or to get help via e-mail.

                                  -

                                  Terminology and Notation

                                  -
                                  +

                                  Throughout this manual, the following names are used to denote paths specific to the local system and working environment. These are not @@ -669,7 +666,7 @@

                                  Setting Up Your Environment

                                  -
                                  +

                                  In order to compile and use LLVM, you may need to set some environment @@ -692,7 +689,7 @@

                                  Unpacking the LLVM Archives

                                  -
                                  +

                                  If you have the LLVM distribution, you will need to unpack it before you @@ -726,7 +723,7 @@

                                  Checkout LLVM from Subversion

                                  -
                                  +

                                  If you have access to our Subversion repository, you can get a fresh copy of the entire source code. All you need to do is check it out from Subversion as @@ -797,7 +794,7 @@

                                  GIT mirror

                                  -
                                  +

                                  GIT mirrors are available for a number of LLVM subprojects. These mirrors sync automatically with each Subversion commit and contain all necessary @@ -816,7 +813,7 @@

                                  Install the GCC Front End

                                  -
                                  +

                                  Before configuring and compiling the LLVM suite (or if you want to use just the LLVM GCC front end) you can optionally extract the front end from the binary distribution. @@ -886,7 +883,7 @@

                                  Local LLVM Configuration

                                  -
                                  +

                                  Once checked out from the Subversion repository, the LLVM suite source code must be @@ -1008,7 +1005,7 @@

                                  Compiling the LLVM Suite Source Code

                                  -
                                  +

                                  Once you have configured LLVM, you can build it. There are three types of builds:

                                  @@ -1142,7 +1139,7 @@

                                  Cross-Compiling LLVM

                                  -
                                  +

                                  It is possible to cross-compile LLVM itself. That is, you can create LLVM executables and libraries to be hosted on a platform different from the platform where they are build (a Canadian Cross build). To configure a @@ -1160,7 +1157,7 @@

                                  The Location of LLVM Object Files

                                  -
                                  +

                                  The LLVM build system is capable of sharing a single LLVM source tree among several LLVM builds. Hence, it is possible to build LLVM for several different @@ -1220,7 +1217,7 @@

                                  Optional Configuration Items

                                  -
                                  +

                                  If you're running on a Linux system that supports the "

                                  +
                                  +

                                  Program Layout

                                  -
                                  +

                                  One useful source of information about the LLVM source base is the LLVM doxygen documentation available at http://llvm.org/doxygen/. The following is a brief introduction to code layout:

                                  -
                                  -

                                  llvm/examples

                                  -
                                  +

                                  This directory contains some simple examples of how to use the LLVM IR and JIT.

                                  @@ -1281,7 +1278,7 @@

                                  llvm/include

                                  -
                                  +

                                  This directory contains public header files exported from the LLVM library. The three main subdirectories of this directory are:

                                  @@ -1312,7 +1309,7 @@

                                  llvm/lib

                                  -
                                  +

                                  This directory contains most of the source files of the LLVM system. In LLVM, almost all code exists in libraries, making it very easy to share code among the @@ -1381,7 +1378,7 @@

                                  llvm/projects

                                  -
                                  +

                                  This directory contains projects that are not strictly part of LLVM but are shipped with LLVM. This is also the directory where you should create your own LLVM-based projects. See llvm/projects/sample for an example of how @@ -1393,7 +1390,7 @@

                                  llvm/runtime

                                  -
                                  +

                                  This directory contains libraries which are compiled into LLVM bitcode and used when linking programs with the GCC front end. Most of these libraries are @@ -1410,7 +1407,7 @@

                                  llvm/test

                                  -
                                  +

                                  This directory contains feature and regression tests and other basic sanity checks on the LLVM infrastructure. These are intended to run quickly and cover a lot of territory without being exhaustive.

                                  @@ -1421,7 +1418,7 @@

                                  test-suite

                                  -
                                  +

                                  This is not a directory in the normal llvm module; it is a separate Subversion module that must be checked out (usually to projects/test-suite). @@ -1440,7 +1437,7 @@

                                  llvm/tools

                                  -
                                  +

                                  The tools directory contains the executables built out of the libraries above, which form the main part of the user interface. You can @@ -1528,7 +1525,7 @@

                                  llvm/utils

                                  -
                                  +

                                  This directory contains utilities for working with LLVM source code, and some of the utilities are actually required as part of the build process because they @@ -1589,13 +1586,15 @@

                                  +
                                  +

                                  An Example Using the LLVM Tool Chain

                                  -
                                  +

                                  This section gives an example of using LLVM. llvm-gcc3 is now obsolete, so we only include instructions for llvm-gcc4.

                                  @@ -1606,14 +1605,13 @@

                                  the '--emit-llvm' flag is needed to produce LLVM bitcode output. For makefiles and configure scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode output.

                                  -

                                  Example with llvm-gcc4

                                  -
                                  +
                                  1. First, create a simple C file, name it 'hello.c':

                                    @@ -1694,6 +1692,7 @@

                                  +

                                  @@ -1701,7 +1700,7 @@

                                  -
                                  +

                                  If you are having problems building or using LLVM, or if you have any other general questions about LLVM, please consult the Frequently @@ -1715,7 +1714,7 @@

                                  -
                                  +

                                  This document is just an introduction on how to use LLVM to do some simple things... there are many more interesting and complicated things diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html index 469b5376afb05..d6bf1b66839ad 100644 --- a/docs/GettingStartedVS.html +++ b/docs/GettingStartedVS.html @@ -36,7 +36,7 @@

                                  -
                                  +

                                  Welcome to LLVM on Windows! This document only covers LLVM on Windows using Visual Studio, not mingw or cygwin. In order to get started, you first need to @@ -75,20 +75,18 @@

                                  -
                                  +

                                  Before you begin to use the LLVM system, review the requirements given below. This may save you some trouble by knowing ahead of time what hardware and software you will need.

                                  -
                                  -

                                  Hardware

                                  -
                                  +

                                  Any system that can adequately run Visual Studio .NET 2005 SP1 is fine. The LLVM source tree and object files, libraries and executables will consume @@ -98,7 +96,7 @@

                                  Software

                                  -
                                  +

                                  You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1 beta and the normal VS2005 still have bugs that are not completely @@ -118,13 +116,15 @@

                                  Software

                                  +
                                  +

                                  Getting Started

                                  -
                                  +

                                  Here's the short story for getting up and running quickly with LLVM:

                                  @@ -234,7 +234,7 @@

                                  -
                                  +
                                  1. First, create a simple C file, name it 'hello.c':

                                    @@ -324,7 +324,7 @@

                                    -
                                    +

                                    If you are having problems building or using LLVM, or if you have any other general questions about LLVM, please consult the Frequently @@ -338,7 +338,7 @@

                                    -
                                    +

                                    This document is just an introduction to how to use LLVM to do some simple things... there are many more interesting and complicated things diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html index 7ba11866278ae..e25c45751929f 100644 --- a/docs/GoldPlugin.html +++ b/docs/GoldPlugin.html @@ -23,7 +23,7 @@

                                    LLVM gold plugin

                                    Introduction

                                    -
                                    +

                                    Building with link time optimization requires cooperation from the system linker. LTO support on Linux systems requires that you use the gold linker which supports @@ -40,7 +40,7 @@

                                    Introduction

                                    How to build it

                                    -
                                    +

                                    You need to have gold with plugin support and build the LLVMgold plugin. Check whether you have gold running /usr/bin/ld -v. It will report “GNU gold” or else “GNU ld” if not. If you have @@ -74,7 +74,7 @@

                                    How to build it

                                    Usage

                                    -
                                    +

                                    The linker takes a -plugin option that points to the path of the plugin .so file. To find out what link command gcc would run in a given situation, run gcc -v [...] and look @@ -95,14 +95,13 @@

                                    Usage

                                    own gold, be sure to install the ar and nm-new you built to /usr/bin.

                                    -

                                    Example of link time optimization

                                    -
                                    +

                                    The following example shows a worked example of the gold plugin mixing LLVM bitcode and native code.

                                    @@ -149,6 +148,8 @@ 

                                    example gold does not currently eliminate foo4.

                                    +
                                    +

                                    @@ -156,7 +157,7 @@

                                    -
                                    +

                                    Once your system ld, ar and nm all support LLVM bitcode, everything is in place for an easy to use LTO build of autotooled projects:

                                    @@ -195,7 +196,7 @@

                                    Licensing

                                    -
                                    +

                                    Gold is licensed under the GPLv3. LLVMgold uses the interface file plugin-api.h from gold which means that the resulting LLVMgold.so binary is also GPLv3. This can still be used to link non-GPLv3 programs just diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index 59e78646300a3..8a7d7f4b88104 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -26,7 +26,7 @@

                                    How To Release LLVM To The Public

                                    Introduction

                                    -
                                    +

                                    This document contains information about successfully releasing LLVM — including subprojects: e.g., llvm-gcc and clang — to @@ -38,7 +38,7 @@

                                    Introduction

                                    Release Timeline

                                    -
                                    +

                                    LLVM is released on a time based schedule — roughly every 6 months. We do not normally have dot releases because of the nature of LLVM's incremental @@ -79,7 +79,7 @@

                                    Release Timeline

                                    Release Process

                                    -
                                    + -

                                    Release Administrative Tasks

                                    -
                                    +

                                    This section describes a few administrative tasks that need to be done for the release process to begin. Specifically, it involves:

                                    @@ -135,12 +133,10 @@

                                    Release Administrative Tasks

                                  2. Tagging release candidates for the release team to begin testing
                              -
                              -

                              Create Release Branch

                              -
                              +

                              Branch the Subversion trunk using the following procedure:

                              @@ -200,7 +196,7 @@

                              Create Release Branch

                              Update LLVM Version

                              -
                              +

                              After creating the LLVM release branch, update the release branches' autoconf and configure.ac versions from 'X.Ysvn' @@ -216,7 +212,7 @@

                              Update LLVM Version

                              Build the LLVM Release Candidates

                              -
                              +

                              Create release candidates for llvm, llvm-gcc, clang, and the LLVM test-suite by tagging the branch with @@ -268,10 +264,12 @@

                              Build the LLVM Release Candidates

                              +
                              +

                              Building the Release

                              -
                              +

                              The builds of llvm, llvm-gcc, and clang must be free of errors and warnings in Debug, Release+Asserts, and @@ -287,12 +285,10 @@

                              Building the Release

                              ReleaseENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1 -
                              -

                              Build LLVM

                              -
                              +

                              Build Debug, Release+Asserts, and Release versions of llvm on all supported platforms. Directions to build @@ -304,7 +300,7 @@

                              Build LLVM

                              Build the LLVM GCC Binary Distribution

                              -
                              +

                              Creating the llvm-gcc binary distribution (Release/Optimized) requires performing the following steps for each supported platform:

                              @@ -331,7 +327,7 @@

                              Build the LLVM GCC Binary Distribution

                              Build Clang Binary Distribution

                              -
                              +

                              Creating the clang binary distribution (Debug/Release+Asserts/Release) requires performing the following steps for @@ -352,7 +348,7 @@

                              Build Clang Binary Distribution

                              Target Specific Build Details

                              -
                              +

                              The table below specifies which compilers are used for each Arch/OS combination when qualifying the build of llvm, llvm-gcc, @@ -371,10 +367,12 @@

                              Target Specific Build Details

                              +
                              +

                              Building the Release

                              -
                              +

                              A release is qualified when it has no regressions from the previous release (or baseline). Regressions are related to correctness first and performance @@ -390,12 +388,10 @@

                              Building the Release

                              criteria, but these are the criteria which we found to be most important and which must be satisfied before a release can go out

                              -
                              -

                              Qualify LLVM

                              -
                              +

                              LLVM is qualified when it has a clean test run without a front-end. And it has no regressions when using either llvm-gcc or clang with @@ -406,7 +402,7 @@

                              Qualify LLVM

                              Qualify LLVM-GCC

                              -
                              +

                              LLVM-GCC is qualified when front-end specific tests in the llvm regression test suite all pass and there are no regressions in @@ -419,7 +415,7 @@

                              Qualify LLVM-GCC

                              Qualify Clang

                              -
                              +

                              Clang is qualified when front-end specific tests in the llvm dejagnu test suite all pass, clang's own test suite passes @@ -430,7 +426,7 @@

                              Qualify Clang

                              Specific Target Qualification Details

                              -
                              +
                              @@ -444,9 +440,11 @@

                              Specific Target Qualification Details

                              + +

                              Community Testing

                              -
                              +

                              Once all testing has been completed and appropriate bugs filed, the release candidate tarballs are put on the website and the LLVM community is @@ -484,7 +482,7 @@

                              Community Testing

                              Release Patch Rules

                              -
                              +

                              Below are the rules regarding patching the release branch:

                              @@ -508,19 +506,16 @@

                              Release Patch Rules

                              Release Final Tasks

                              -
                              +

                              The final stages of the release process involves tagging the "final" release branch, updating documentation that refers to the release, and updating the demo page.

                              -
                              - -

                              Update Documentation

                              -
                              +

                              Review the documentation and ensure that it is up to date. The "Release Notes" must be updated to reflect new features, bug fixes, new known issues, @@ -534,7 +529,7 @@

                              Update Documentation

                              Tag the LLVM Final Release

                              -
                              +

                              Tag the final release sources using the following procedure:

                              @@ -556,20 +551,20 @@

                              Tag the LLVM Final Release

                              +
                              +

                              Update the LLVM Demo Page

                              -
                              +

                              The LLVM demo page must be updated to use the new release. This consists of using the new llvm-gcc binary and building LLVM.

                              -
                              -

                              Update the LLVM Website

                              -
                              +

                              The website must be updated before the release announcement is sent out. Here is what to do:

                              @@ -605,12 +600,16 @@

                              Update the LLVM Website

                              Announce the Release

                              -
                              +

                              Have Chris send out the release announcement when everything is finished.

                              +
                              + +
                              +
                              diff --git a/docs/HowToSubmitABug.html b/docs/HowToSubmitABug.html index ca34384621b3f..0af273f40319c 100644 --- a/docs/HowToSubmitABug.html +++ b/docs/HowToSubmitABug.html @@ -42,7 +42,7 @@

                              -
                              +

                              If you're working with LLVM and run into a bug, we definitely want to know about it. This document describes what you can do to increase the odds of @@ -81,7 +81,7 @@

                              -
                              +

                              More often than not, bugs in the compiler cause it to crash—often due to an assertion failure of some sort. The most important @@ -109,14 +109,12 @@

                              -

                              -

                              Front-end bugs

                              -
                              +

                              If the problem is in the front-end, you should re-run the same llvm-gcc command that resulted in the crash, but add the @@ -141,7 +139,7 @@

                              Compile-time optimization bugs

                              -
                              +

                              If you find that a bug crashes in the optimizer, compile your test-case to a .bc file by passing "-emit-llvm -O0 -c -o foo.bc". @@ -175,7 +173,7 @@

                              Code generator bugs

                              -
                              +

                              If you find a bug that crashes llvm-gcc in the code generator, compile your source file to a .bc file by passing "-emit-llvm -c -o foo.bc" @@ -207,13 +205,15 @@

                              +
                              +

                              Miscompilations

                              -
                              +

                              If llvm-gcc successfully produces an executable, but that executable doesn't run right, this is either a bug in the code or a bug in the @@ -246,7 +246,7 @@

                              -
                              +

                              Similarly to debugging incorrect compilation by mis-behaving passes, you can debug incorrect code generation by either LLC or the JIT, using diff --git a/docs/LangRef.html b/docs/LangRef.html index 69e0a75951f4f..381fed5c6d3de 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -324,7 +324,7 @@

                              LLVM Language Reference Manual

                              Abstract

                              -
                              +

                              This document is a reference manual for the LLVM assembly language. LLVM is a Static Single Assignment (SSA) based representation that provides type @@ -338,7 +338,7 @@

                              Abstract

                              Introduction

                              -
                              +

                              The LLVM code representation is designed to be used in three different forms: as an in-memory compiler IR, as an on-disk bitcode representation (suitable @@ -359,14 +359,12 @@

                              Introduction

                              variable is never accessed outside of the current function, allowing it to be promoted to a simple SSA value instead of a memory location.

                              -
                              -

                              Well-Formedness

                              -
                              +

                              It is important to note that this document describes 'well formed' LLVM assembly language. There is a difference between what the parser accepts and @@ -386,13 +384,15 @@

                              +
                              +

                              Identifiers

                              -
                              +

                              LLVM identifiers come in two basic types: global and local. Global identifiers (functions, global variables) begin with the '@' @@ -479,13 +479,13 @@

                              Identifiers

                              High Level Structure

                              - +

                              Module Structure

                              -
                              +

                              LLVM programs are composed of "Module"s, each of which is a translation unit of the input programs. Each module consists of functions, global variables, @@ -535,7 +535,7 @@

                              Linkage Types

                              -
                              +

                              All Global Variables and Functions have one of the following types of linkage:

                              @@ -684,7 +684,7 @@

                              Calling Conventions

                              -
                              +

                              LLVM functions, calls and invokes can all have an optional calling @@ -757,7 +757,7 @@

                              Visibility Styles

                              -
                              +

                              All Global Variables and Functions have one of the following visibility styles:

                              @@ -791,7 +791,7 @@

                              Named Types

                              -
                              +

                              LLVM IR allows you to specify name aliases for certain types. This can make it easier to read the IR and make the IR more condensed (particularly when @@ -822,7 +822,7 @@

                              Global Variables

                              -
                              +

                              Global variables define regions of memory allocated at compilation time instead of run-time. Global variables may optionally be initialized, may @@ -890,7 +890,7 @@

                              Functions

                              -
                              +

                              LLVM function definitions consist of the "define" keyword, an optional linkage type, an optional @@ -953,7 +953,7 @@

                              Aliases

                              -
                              +

                              Aliases act as "second name" for the aliasee value (which can be either function, global variable, another alias or bitcast of global value). Aliases @@ -972,7 +972,7 @@

                              Named Metadata

                              -
                              +

                              Named metadata is a collection of metadata. Metadata nodes (but not metadata strings) are the only valid operands for @@ -995,7 +995,7 @@

                              Parameter Attributes

                              -
                              +

                              The return type and each parameter of a function type may have a set of parameter attributes associated with them. Parameter attributes are @@ -1106,7 +1106,7 @@

                              Garbage Collector Names

                              -
                              +

                              Each function may specify a garbage collector name, which is simply a string:

                              @@ -1126,7 +1126,7 @@

                              Function Attributes

                              -
                              +

                              Function attributes are set to communicate additional information about a function. Function attributes are considered to be part of the function, not @@ -1249,7 +1249,7 @@

                              Module-Level Inline Assembly

                              -
                              +

                              Modules may contain "module-level inline asm" blocks, which corresponds to the GCC "file scope inline asm" blocks. These blocks are internally @@ -1275,7 +1275,7 @@

                              Data Layout

                              -
                              +

                              A module may specify a target specific data layout string that specifies how data is to be laid out in memory. The syntax for the data layout is @@ -1387,7 +1387,7 @@

                              Pointer Aliasing Rules

                              -
                              +

                              Any memory access must be done through a pointer value associated with an address range of the memory access, otherwise the behavior @@ -1451,7 +1451,7 @@

                              Volatile Memory Accesses

                              -
                              +

                              Certain memory accesses, such as loads, stores, and

                              +
                              +

                              Type System

                              -
                              +

                              The LLVM type system is one of the most important features of the intermediate representation. Being typed enables a number of optimizations @@ -1478,14 +1480,12 @@

                              Type System

                              and transformations that are not feasible to perform on normal three address code representations.

                              -
                              -

                              Type Classifications

                              -
                              +

                              The types fall into a few useful classifications:

                              @@ -1546,19 +1546,17 @@

                              Primitive Types

                              -
                              +

                              The primitive types are the fundamental building blocks of the LLVM system.

                              -
                              -

                              Integer Type

                              -
                              +
                              Overview:

                              The integer type is a very simple type that simply specifies an arbitrary @@ -1596,7 +1594,7 @@

                              Floating Point Types

                              -
                              +
                              ArchitectureOSllvm-gcc baselineclang baselinetests
                              @@ -1616,7 +1614,7 @@

                              X86mmx Type

                              -
                              +
                              Overview:

                              The x86mmx type represents a value held in an MMX register on an x86 machine. The operations allowed on it are quite limited: parameters and return values, load and store, and bitcast. User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type. There are no arrays, vectors or constants of this type.

                              @@ -1633,7 +1631,7 @@

                              Void Type

                              -
                              +
                              Overview:

                              The void type does not represent any value and has no size.

                              @@ -1650,7 +1648,7 @@

                              Label Type

                              -
                              +
                              Overview:

                              The label type represents code labels.

                              @@ -1667,7 +1665,7 @@

                              Metadata Type

                              -
                              +
                              Overview:

                              The metadata type represents embedded metadata. No derived types may be @@ -1681,13 +1679,14 @@

                              Syntax:
                              +

                              Derived Types

                              -
                              +

                              The real power in LLVM comes from the derived types in the system. This is what allows a programmer to represent arrays, functions, pointers, and other @@ -1697,14 +1696,12 @@

                              of another array.

                              -

                              -

                              Aggregate Types

                              -
                              +

                              Aggregate Types are a subset of derived types that can contain multiple member types. Arrays, @@ -1718,7 +1715,7 @@

                              Array Type

                              -
                              +
                              Overview:

                              The array type is a very simple derived type that arranges elements @@ -1778,7 +1775,7 @@

                              Function Type

                              -
                              +
                              Overview:

                              The function type can be thought of as a function signature. It consists of @@ -1833,7 +1830,7 @@

                              Structure Type

                              -
                              +
                              Overview:

                              The structure type is used to represent a collection of data members together @@ -1873,7 +1870,7 @@

                              Packed Structure Type

                              -
                              +
                              Overview:

                              The packed structure type is used to represent a collection of data members @@ -1912,7 +1909,7 @@

                              Pointer Type

                              -
                              +
                              Overview:

                              The pointer type is used to specify memory locations. @@ -1958,7 +1955,7 @@

                              Vector Type

                              -
                              +
                              Overview:

                              A vector type is a simple derived type that represents a vector of elements. @@ -1999,7 +1996,7 @@

                              Opaque Type

                              -
                              +
                              Overview:

                              Opaque types are used to represent unknown types in the system. This @@ -2022,12 +2019,14 @@

                              Examples:
                              +
                              +

                              Type Up-references

                              -
                              +
                              Overview:

                              An "up reference" allows you to refer to a lexically enclosing type without @@ -2070,23 +2069,23 @@

                              Examples:
                              +
                              +

                              Constants

                              -
                              +

                              LLVM has several different basic types of constants. This section describes them all and their syntax.

                              -
                              -

                              Simple Constants

                              -
                              +
                              Boolean constants
                              @@ -2144,7 +2143,7 @@

                              Complex Constants

                              -
                              +

                              Complex constants are a (potentially recursive) combination of simple constants and smaller complex constants.

                              @@ -2198,7 +2197,7 @@

                              Global Variable and Function Addresses

                              -
                              +

                              The addresses of global variables and functions are always implicitly valid @@ -2220,7 +2219,7 @@

                              Undefined Values

                              -
                              +

                              The string 'undef' can be used anywhere a constant is expected, and indicates that the user of the value may receive an unspecified bit-pattern. @@ -2363,7 +2362,7 @@

                              Trap Values

                              -
                              +

                              Trap values are similar to undef values, however instead of representing an unspecified bit pattern, they represent the @@ -2491,7 +2490,7 @@

                              Addresses of Basic Blocks

                              -
                              +

                              blockaddress(@function, %block)

                              @@ -2520,7 +2519,7 @@

                              Constant Expressions

                              -
                              +

                              Constant expressions are used to allow expressions involving other constants to be used as constants. Constant expressions may be of @@ -2646,16 +2645,18 @@

                              +
                              +

                              Other Values

                              - +

                              Inline Assembler Expressions

                              -
                              +

                              LLVM supports inline assembler expressions (as opposed to Module-Level Inline Assembly) through the use of @@ -2704,13 +2705,12 @@

                              documented here. Constraints on what can be done (e.g. duplication, moving, etc need to be documented). This is probably best done by reference to another document that covers inline asm from a holistic perspective.

                              -

                              Inline Asm Metadata

                              -
                              +

                              The call instructions that wrap inline asm nodes may have a "!srcloc" MDNode attached to it that contains a list of constant integers. If present, the @@ -2731,12 +2731,14 @@

                              +
                              +

                              Metadata Nodes and Metadata Strings

                              -
                              +

                              LLVM IR allows metadata to be attached to instructions in the program that can convey extra information about the code to the optimizers and code @@ -2778,13 +2780,14 @@

                              +

                              Intrinsic Global Variables

                              - +

                              LLVM has a number of "magic" global variables that contain data that affect code generation or other IR semantics. These are documented here. All globals of this sort should have a section specified as "llvm.metadata". This @@ -2796,7 +2799,7 @@

                              The 'llvm.used' Global Variable

                              -
                              +

                              The @llvm.used global is an array with i8* element type which has appending linkage. This array contains a list of @@ -2833,7 +2836,7 @@

                              -
                              +

                              The @llvm.compiler.used directive is the same as the @llvm.used directive, except that it only prevents the compiler from @@ -2851,7 +2854,7 @@

                              The 'llvm.global_ctors' Global Variable

                              -
                              +
                               %0 = type { i32, void ()* }
                               @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
                              @@ -2866,7 +2869,7 @@ 

                              The 'llvm.global_dtors' Global Variable

                              -
                              +
                               %0 = type { i32, void ()* }
                               @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
                              @@ -2877,12 +2880,13 @@ 

                              +

                              Instruction Reference

                              -
                              +

                              The LLVM instruction set consists of several different classifications of instructions: terminator @@ -2891,14 +2895,12 @@

                              Instruction Reference

                              memory instructions, and other instructions.

                              -
                              -

                              Terminator Instructions

                              -
                              +

                              As mentioned previously, every basic block in a program ends with a "Terminator" instruction, which indicates which @@ -2916,14 +2918,12 @@

                              'unwind' instruction, and the 'unreachable' instruction.

                              -

                              -

                              'ret' Instruction

                              -
                              +
                              Syntax:
                              @@ -2973,7 +2973,7 @@ 

                              'br' Instruction

                              -
                              +
                              Syntax:
                              @@ -3016,7 +3016,7 @@ 

                              'switch' Instruction

                              -
                              +
                              Syntax:
                              @@ -3071,7 +3071,7 @@ 

                              'indirectbr' Instruction

                              -
                              +
                              Syntax:
                              @@ -3119,7 +3119,7 @@ 

                              'invoke' Instruction

                              -
                              +
                              Syntax:
                              @@ -3209,7 +3209,7 @@ 

                              'unwind' Instruction

                              -
                              +
                              Syntax:
                              @@ -3241,7 +3241,7 @@ 

                              'unreachable' Instruction

                              -
                              +
                              Syntax:
                              @@ -3259,12 +3259,14 @@ 
                              Semantics:
                              +
                              +

                              Binary Operations

                              -
                              +

                              Binary operators are used to do most of the computation in a program. They require two operands of the same type, execute an operation on them, and @@ -3274,14 +3276,12 @@

                              There are several different binary operators:

                              -

                              -

                              'add' Instruction

                              -
                              +
                              Syntax:
                              @@ -3326,7 +3326,7 @@ 

                              'fadd' Instruction

                              -
                              +
                              Syntax:
                              @@ -3356,7 +3356,7 @@ 

                              'sub' Instruction

                              -
                              +
                              Syntax:
                              @@ -3408,7 +3408,7 @@ 

                              'fsub' Instruction

                              -
                              +
                              Syntax:
                              @@ -3444,7 +3444,7 @@ 

                              'mul' Instruction

                              -
                              +
                              Syntax:
                              @@ -3494,7 +3494,7 @@ 

                              'fmul' Instruction

                              -
                              +
                              Syntax:
                              @@ -3524,7 +3524,7 @@ 

                              'udiv' Instruction

                              -
                              +
                              Syntax:
                              @@ -3565,7 +3565,7 @@ 

                              'sdiv' Instruction

                              -
                              +
                              Syntax:
                              @@ -3608,7 +3608,7 @@ 

                              'fdiv' Instruction

                              -
                              +
                              Syntax:
                              @@ -3638,7 +3638,7 @@ 

                              'urem' Instruction

                              -
                              +
                              Syntax:
                              @@ -3676,7 +3676,7 @@ 

                              'srem' Instruction

                              -
                              +
                              Syntax:
                              @@ -3727,7 +3727,7 @@ 

                              'frem' Instruction

                              -
                              +
                              Syntax:
                              @@ -3754,12 +3754,14 @@ 
                              Example:
                              +
                              +

                              Bitwise Binary Operations

                              -
                              +

                              Bitwise binary operators are used to do various forms of bit-twiddling in a program. They are generally very efficient instructions and can commonly be @@ -3767,14 +3769,12 @@

                              same type, execute an operation on them, and produce a single value. The resulting value is the same type as its operands.

                              -

                              -

                              'shl' Instruction

                              -
                              +
                              Syntax:
                              @@ -3825,7 +3825,7 @@ 

                              'lshr' Instruction

                              -
                              +
                              Syntax:
                              @@ -3872,7 +3872,7 @@ 

                              'ashr' Instruction

                              -
                              +
                              Syntax:
                              @@ -3919,7 +3919,7 @@ 

                              'and' Instruction

                              -
                              +
                              Syntax:
                              @@ -3980,7 +3980,7 @@ 

                              'or' Instruction

                              -
                              +
                              Syntax:
                              @@ -4043,7 +4043,7 @@ 

                              'xor' Instruction

                              -
                              +
                              Syntax:
                              @@ -4103,12 +4103,14 @@ 
                              Example:
                              +
                              +

                              Vector Operations

                              -
                              +

                              LLVM supports several instructions to represent vector operations in a target-independent manner. These instructions cover the element-access and @@ -4117,14 +4119,12 @@

                              will want to use target-specific intrinsics to take full advantage of a specific target.

                              -

                              -

                              'extractelement' Instruction

                              -
                              +
                              Syntax:
                              @@ -4160,7 +4160,7 @@ 

                              'insertelement' Instruction

                              -
                              +
                              Syntax:
                              @@ -4196,7 +4196,7 @@ 

                              'shufflevector' Instruction

                              -
                              +
                              Syntax:
                              @@ -4239,24 +4239,24 @@ 
                              Example:
                              +
                              +

                              Aggregate Operations

                              -
                              +

                              LLVM supports several instructions for working with aggregate values.

                              -
                              -

                              'extractvalue' Instruction

                              -
                              +
                              Syntax:
                              @@ -4298,7 +4298,7 @@ 

                              'insertvalue' Instruction

                              -
                              +
                              Syntax:
                              @@ -4332,27 +4332,26 @@ 
                              Example:
                              +

                              Memory Access and Addressing Operations

                              -
                              +

                              A key design point of an SSA-based representation is how it represents memory. In LLVM, no memory locations are in SSA form, which makes things very simple. This section describes how to read, write, and allocate memory in LLVM.

                              -
                              -

                              'alloca' Instruction

                              -
                              +
                              Syntax:
                              @@ -4403,7 +4402,7 @@ 

                              'load' Instruction

                              -
                              +
                              Syntax:
                              @@ -4462,7 +4461,7 @@ 

                              'store' Instruction

                              -
                              +
                              Syntax:
                              @@ -4524,7 +4523,7 @@ 

                              'getelementptr' Instruction

                              -
                              +
                              Syntax:
                              @@ -4650,25 +4649,25 @@ 
                              Example:
                              +
                              +

                              Conversion Operations

                              -
                              +

                              The instructions in this category are the conversion instructions (casting) which all take a single operand and a type. They perform various bit conversions on the operand.

                              -
                              -

                              'trunc .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4708,7 +4707,7 @@ 

                              'zext .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4748,7 +4747,7 @@ 

                              'sext .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4787,7 +4786,7 @@ 

                              'fptrunc .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4825,7 +4824,7 @@ 

                              'fpext .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4862,7 +4861,7 @@ 

                              'fptoui .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4900,7 +4899,7 @@ 

                              'fptosi .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4939,7 +4938,7 @@ 

                              'uitofp .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -4976,7 +4975,7 @@ 

                              'sitofp .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -5012,7 +5011,7 @@ 

                              'ptrtoint .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -5050,7 +5049,7 @@ 

                              'inttoptr .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -5088,7 +5087,7 @@ 

                              'bitcast .. to' Instruction

                              -
                              +
                              Syntax:
                              @@ -5127,24 +5126,24 @@ 
                              Example:
                              +
                              +

                              Other Operations

                              -
                              +

                              The instructions in this category are the "miscellaneous" instructions, which defy better classification.

                              -
                              -

                              'icmp' Instruction

                              -
                              +
                              Syntax:
                              @@ -5247,7 +5246,7 @@ 

                              'fcmp' Instruction

                              -
                              +
                              Syntax:
                              @@ -5368,7 +5367,7 @@ 

                              'phi' Instruction

                              -
                              +
                              Syntax:
                              @@ -5416,7 +5415,7 @@ 

                              'select' Instruction

                              -
                              +
                              Syntax:
                              @@ -5459,7 +5458,7 @@ 

                              'call' Instruction

                              -
                              +
                              Syntax:
                              @@ -5568,7 +5567,7 @@ 

                              'va_arg' Instruction

                              -
                              +
                              Syntax:
                              @@ -5609,11 +5608,15 @@ 
                              Example:
                              +
                              + +
                              +

                              Intrinsic Functions

                              -
                              +

                              LLVM supports the notion of an "intrinsic function". These functions have well known names and semantics and are required to follow certain @@ -5656,14 +5659,12 @@

                              Intrinsic Functions

                              To learn how to add an intrinsic function, please see the Extending LLVM Guide.

                              -
                              -

                              Variable Argument Handling Intrinsics

                              -
                              +

                              Variable argument support is defined in LLVM with the va_arg instruction and these three @@ -5705,15 +5706,13 @@

                              declare void @llvm.va_end(i8*)

                              -
                              -

                              'llvm.va_start' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5743,7 +5742,7 @@ 

                              'llvm.va_end' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5774,7 +5773,7 @@ 

                              'llvm.va_copy' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5800,12 +5799,14 @@ 
                              Semantics:
                              +
                              +

                              Accurate Garbage Collection Intrinsics

                              -
                              +

                              LLVM support for Accurate Garbage Collection (GC) requires the implementation and generation of these @@ -5820,14 +5821,12 @@

                              The garbage collection intrinsics only operate on objects in the generic address space (address space zero).

                              -

                              -

                              'llvm.gcroot' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5858,7 +5857,7 @@ 

                              'llvm.gcread' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5890,7 +5889,7 @@ 

                              'llvm.gcwrite' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5917,24 +5916,24 @@ 
                              Semantics:
                              +
                              +

                              Code Generator Intrinsics

                              -
                              +

                              These intrinsics are provided by LLVM to expose special features that may only be implemented with code generator support.

                              -
                              -

                              'llvm.returnaddress' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -5969,7 +5968,7 @@ 

                              'llvm.frameaddress' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -6003,7 +6002,7 @@ 

                              'llvm.stacksave' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -6033,7 +6032,7 @@ 

                              'llvm.stackrestore' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -6058,7 +6057,7 @@ 

                              'llvm.prefetch' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -6091,7 +6090,7 @@ 

                              'llvm.pcmarker' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -6122,7 +6121,7 @@ 

                              'llvm.readcyclecounter' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -6144,26 +6143,26 @@ 
                              Semantics:
                              +
                              +

                              Standard C Library Intrinsics

                              -
                              +

                              LLVM provides intrinsics for a few important standard C library functions. These intrinsics allow source-language front-ends to pass information about the alignment of the pointer arguments to the code generator, providing opportunity for more efficient code generation.

                              -
                              -

                              'llvm.memcpy' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.memcpy on any @@ -6217,7 +6216,7 @@

                              'llvm.memmove' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.memmove on any integer bit @@ -6273,7 +6272,7 @@

                              'llvm.memset.*' Intrinsics

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.memset on any integer bit @@ -6323,7 +6322,7 @@

                              'llvm.sqrt.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.sqrt on any @@ -6361,7 +6360,7 @@

                              'llvm.powi.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.powi on any @@ -6397,7 +6396,7 @@

                              'llvm.sin.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.sin on any @@ -6431,7 +6430,7 @@

                              'llvm.cos.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.cos on any @@ -6465,7 +6464,7 @@

                              'llvm.pow.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.pow on any @@ -6495,24 +6494,24 @@

                              Semantics:
                              +
                              +

                              Bit Manipulation Intrinsics

                              -
                              +

                              LLVM provides intrinsics for a few important bit manipulation operations. These allow efficient code generation for some algorithms.

                              -
                              -

                              'llvm.bswap.*' Intrinsics

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic function. You can use bswap on any integer @@ -6547,7 +6546,7 @@

                              'llvm.ctpop.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit @@ -6579,7 +6578,7 @@

                              'llvm.ctlz.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.ctlz on any @@ -6613,7 +6612,7 @@

                              'llvm.cttz.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.cttz on any @@ -6642,17 +6641,17 @@

                              Semantics:
                              +
                              +

                              Arithmetic with Overflow Intrinsics

                              -
                              +

                              LLVM provides intrinsics for some arithmetic with overflow operations.

                              -
                              -

                              @@ -6660,7 +6659,7 @@

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.sadd.with.overflow @@ -6708,7 +6707,7 @@

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.uadd.with.overflow @@ -6755,7 +6754,7 @@

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.ssub.with.overflow @@ -6803,7 +6802,7 @@

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.usub.with.overflow @@ -6851,7 +6850,7 @@

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.smul.with.overflow @@ -6900,7 +6899,7 @@

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.umul.with.overflow @@ -6941,12 +6940,14 @@

                              Examples:
                              +
                              +

                              Half Precision Floating Point Intrinsics

                              -
                              +

                              Half precision floating point is a storage-only format. This means that it is a dense encoding (in memory) but does not support computation in the @@ -6960,7 +6961,6 @@

                              float if needed, then converted to i16 with llvm.convert.to.fp16, then storing as an i16 value.

                              -

                              @@ -6969,7 +6969,7 @@

                              -
                              +
                              Syntax:
                              @@ -7006,7 +7006,7 @@ 

                              -
                              +
                              Syntax:
                              @@ -7036,12 +7036,14 @@ 
                              Examples:
                              +
                              +

                              Debugger Intrinsics

                              -
                              +

                              The LLVM debugger intrinsics (which all start with llvm.dbg. prefix), are described in @@ -7055,7 +7057,7 @@

                              Exception Handling Intrinsics

                              -
                              +

                              The LLVM exception handling intrinsics (which all start with llvm.eh. prefix), are described in @@ -7069,7 +7071,7 @@

                              Trampoline Intrinsic

                              -
                              +

                              This intrinsic makes it possible to excise one parameter, marked with the nest attribute, from a function. @@ -7095,8 +7097,6 @@

                              The call %val = call i32 %fp(i32 %x, i32 %y) is then equivalent to %val = call i32 %f(i8* %nval, i32 %x, i32 %y).

                              -

                              -

                              @@ -7104,7 +7104,7 @@

                              -
                              +
                              Syntax:
                              @@ -7141,12 +7141,14 @@ 
                              Semantics:
                              +
                              +

                              Atomic Operations and Synchronization Intrinsics

                              -
                              +

                              These intrinsic functions expand the "universal IR" of LLVM to represent hardware constructs for atomic operations and memory synchronization. This @@ -7166,14 +7168,12 @@

                              No one model or paradigm should be selected above others unless the hardware itself ubiquitously does so.

                              -

                              -

                              'llvm.memory.barrier' Intrinsic

                              -
                              +
                              Syntax:
                                 declare void @llvm.memory.barrier(i1 <ll>, i1 <ls>, i1 <sl>, i1 <ss>, i1 <device>)
                              @@ -7245,7 +7245,7 @@ 

                              'llvm.atomic.cmp.swap.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.atomic.cmp.swap on @@ -7305,7 +7305,7 @@

                              'llvm.atomic.swap.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.atomic.swap on any @@ -7362,7 +7362,7 @@

                              'llvm.atomic.load.add.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.atomic.load.add on @@ -7411,7 +7411,7 @@

                              'llvm.atomic.load.sub.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use llvm.atomic.load.sub on @@ -7476,7 +7476,7 @@

                              -
                              +
                              Syntax:

                              These are overloaded intrinsics. You can @@ -7567,7 +7567,7 @@

                              -
                              +
                              Syntax:

                              These are overloaded intrinsics. You can use llvm.atomic.load_max, @@ -7638,25 +7638,24 @@

                              Examples:
                              +

                              Memory Use Markers

                              -
                              +

                              This class of intrinsics exists to information about the lifetime of memory objects and ranges where variables are immutable.

                              -
                              -

                              'llvm.lifetime.start' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7686,7 +7685,7 @@ 

                              'llvm.lifetime.end' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7715,7 +7714,7 @@ 

                              'llvm.invariant.start' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7743,7 +7742,7 @@ 

                              'llvm.invariant.end' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7765,24 +7764,24 @@ 
                              Semantics:
                              +
                              +

                              General Intrinsics

                              -
                              +

                              This class of intrinsics is designed to be generic and has no specific purpose.

                              -
                              -

                              'llvm.var.annotation' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7810,7 +7809,7 @@ 

                              'llvm.annotation.*' Intrinsic

                              -
                              +
                              Syntax:

                              This is an overloaded intrinsic. You can use 'llvm.annotation' on @@ -7846,7 +7845,7 @@

                              'llvm.trap' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7871,7 +7870,7 @@ 

                              'llvm.stackprotector' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7905,7 +7904,7 @@ 

                              'llvm.objectsize' Intrinsic

                              -
                              +
                              Syntax:
                              @@ -7935,6 +7934,10 @@ 
                              Semantics:
                              +
                              + +
                              +
                              diff --git a/docs/Lexicon.html b/docs/Lexicon.html index 458da8013ed4e..b1c2638e6828c 100644 --- a/docs/Lexicon.html +++ b/docs/Lexicon.html @@ -14,7 +14,7 @@

                              The LLVM Lexicon

                              Table Of Contents

                              -
                              +

                              @@ -85,9 +85,10 @@

                              Table Of Contents

                              Definitions

                              +

                              - A -

                              -
                              +
                              ADCE
                              Aggressive Dead Code Elimination
                              @@ -95,7 +96,7 @@

                              - A -

                              - B -

                              -
                              +
                              BURS
                              Bottom Up Rewriting System—A method of instruction selection for @@ -105,7 +106,7 @@

                              - B -

                              - C -

                              -
                              +
                              CSE
                              Common Subexpression Elimination. An optimization that removes common @@ -117,7 +118,7 @@

                              - C -

                              - D -

                              -
                              +
                              DAG
                              Directed Acyclic Graph
                              @@ -137,7 +138,7 @@

                              - D -

                              - G -

                              -
                              +
                              GC
                              Garbage Collection. The practice of using reachability analysis instead @@ -146,7 +147,7 @@

                              - G -

                              - H -

                              -
                              +
                              Heap
                              In garbage collection, the region of memory which is managed using @@ -155,7 +156,7 @@

                              - H -

                              - I -

                              -
                              +
                              IPA
                              Inter-Procedural Analysis. Refers to any variety of code analysis that @@ -170,7 +171,7 @@

                              - I -

                              - L -

                              -
                              +
                              LCSSA
                              Loop-Closed Static Single Assignment Form
                              @@ -184,7 +185,7 @@

                              - L -

                              - M -

                              -
                              +
                              MC
                              Machine Code
                              @@ -192,7 +193,7 @@

                              - M -

                              - O -

                              -
                              +
                              Object Pointer
                              A pointer to an object such that the garbage collector is able to trace @@ -203,7 +204,7 @@

                              - O -

                              - P -

                              -
                              +
                              PRE
                              Partial Redundancy Elimination
                              @@ -212,7 +213,7 @@

                              - P -

                              - R -

                              -
                              +
                              RAUW
                              An abbreviation for Replace All Uses With. The functions User::replaceUsesOfWith(), @@ -235,7 +236,7 @@

                              - R -

                              - S -

                              -
                              +
                              Safe Point
                              In garbage collection, it is necessary to identify stack @@ -261,6 +262,8 @@

                              - S -

                              function.
                              + +

                              -
                              +

                              LLVM features powerful intermodular optimizations which can be used at link time. Link Time Optimization (LTO) is another name for intermodular optimization @@ -55,7 +55,7 @@

                              -
                              +

                              The LLVM Link Time Optimizer provides complete transparency, while doing intermodular optimization, in the compiler tool chain. Its main goal is to let @@ -69,14 +69,13 @@

                              in other models. The linker input allows the optimizer to avoid relying on conservative escape analysis.

                              -

                              Example of link time optimization

                              -
                              +

                              The following example illustrates the advantages of LTO's integrated approach and clean interface. This example requires a system linker which supports LTO through the interface described in this document. Here, @@ -149,7 +148,7 @@

                              Alternative Approaches

                              -
                              +
                              Compiler driver invokes link time optimizer separately.
                              In this model the link time optimizer is not able to take advantage of @@ -175,12 +174,14 @@

                              +
                              +

                              Multi-phase communication between libLTO and linker

                              -
                              +

                              The linker collects information about symbol defininitions and uses in various link objects which is more accurate than any information collected by other tools during typical build cycles. The linker collects this @@ -192,14 +193,13 @@

                              Our goal is to take advantage of tight integration between the linker and the optimizer by sharing this information during various linking phases.

                              -

                              Phase 1 : Read LLVM Bitcode Files

                              -
                              +

                              The linker first reads all object files in natural order and collects symbol information. This includes native object files as well as LLVM bitcode files. To minimize the cost to the linker in the case that all .o files @@ -223,7 +223,7 @@

                              Phase 2 : Symbol Resolution

                              -
                              +

                              In this stage, the linker resolves symbols using global symbol table. It may report undefined symbol errors, read archive members, replace weak symbols, etc. The linker is able to do this seamlessly even though it @@ -236,7 +236,7 @@

                              Phase 3 : Optimize Bitcode Files

                              -
                              +

                              After symbol resolution, the linker tells the LTO shared object which symbols are needed by native object files. In the example above, the linker reports that only foo1() is used by native object files using @@ -252,7 +252,7 @@

                              Phase 4 : Symbol Resolution after optimization

                              -
                              +

                              In this phase, the linker reads optimized a native object file and updates the internal global symbol table to reflect any changes. The linker also collects information about any changes in use of external symbols by @@ -264,12 +264,14 @@

                              bitcode files.

                              +
                              +

                              libLTO

                              -
                              +

                              libLTO is a shared object that is part of the LLVM tools, and is intended for use by a linker. libLTO provides an abstract C interface to use the LLVM interprocedural optimizer without exposing details @@ -278,14 +280,13 @@

                              be possible for a completely different compilation technology to provide a different libLTO that works with their object files and the standard linker tool.

                              -

                              lto_module_t

                              -
                              +

                              A non-native object file is handled via an lto_module_t. The following functions allow the linker to check if a file (on disk @@ -329,7 +330,7 @@

                              lto_code_gen_t

                              -
                              +

                              Once the linker has loaded each non-native object files into an lto_module_t, it can request libLTO to process them all and @@ -371,6 +372,8 @@

                              +
                              +
                              diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index a85314ab282f8..ee0115d209c17 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -80,7 +80,7 @@

                              LLVM Makefile Guide

                              Introduction

                              -
                              +

                              This document provides usage information about the LLVM makefile system. While loosely patterned after the BSD makefile system, LLVM has taken a departure from BSD in order to implement additional features needed by LLVM. @@ -102,17 +102,16 @@

                              Introduction

                              General Concepts

                              -
                              +

                              The LLVM Makefile System is the component of LLVM that is responsible for building the software, testing it, generating distributions, checking those distributions, installing and uninstalling, etc. It consists of a several files throughout the source tree. These files and other general concepts are described in this section.

                              -

                              Projects

                              -
                              +

                              The LLVM Makefile System is quite generous. It not only builds its own software, but it can build yours too. Built into the system is knowledge of the llvm/projects directory. Any directory under projects @@ -130,7 +129,7 @@

                              Projects

                              Variable Values

                              -
                              +

                              To use the makefile system, you simply create a file named Makefile in your directory and declare values for certain variables. The variables and values that you select determine what the makefile system @@ -140,15 +139,14 @@

                              Variable Values

                              Including Makefiles

                              -
                              +

                              Setting variables alone is not enough. You must include into your Makefile additional files that provide the rules of the LLVM Makefile system. The various files involved are described in the sections that follow.

                              -

                              Makefile

                              -
                              +

                              Each directory to participate in the build needs to have a file named Makefile. This is the file first read by make. It has three sections:

                              @@ -164,7 +162,7 @@

                              Makefile

                              Makefile.common

                              -
                              +

                              Every project must have a Makefile.common file at its top source directory. This file serves three purposes:

                                @@ -182,7 +180,7 @@

                                Makefile.common

                                Makefile.config

                                -
                                +

                                Every project must have a Makefile.config at the top of its build directory. This file is generated by the configure script from the pattern provided by the @@ -195,7 +193,7 @@

                                Makefile.config

                                Makefile.rules

                                -
                                +

                                This file, located at $(LLVM_SRC_ROOT)/Makefile.rules is the heart of the LLVM Makefile System. It provides all the logic, dependencies, and rules for building the targets supported by the system. What it does largely @@ -203,9 +201,11 @@

                                Makefile.rules

                                have been set before Makefile.rules is included.
                                +
                                +

                                Comments

                                -
                                +

                                User Makefiles need not have comments in them unless the construction is unusual or it does not strictly follow the rules and patterns of the LLVM makefile system. Makefile comments are invoked with the pound (#) character. @@ -213,19 +213,20 @@

                                Comments

                                by make.

                                +
                                +

                                Tutorial

                                -
                                +

                                This section provides some examples of the different kinds of modules you can build with the LLVM makefile system. In general, each directory you provide will build a single object although that object may be composed of additionally compiled components.

                                -

                                Libraries

                                -
                                +

                                Only a few variable definitions are needed to build a regular library. Normally, the makefile system will build all the software into a single libname.o (pre-linked) object. This means the library is not @@ -254,11 +255,10 @@

                                Libraries

                                -load option. See the WritingAnLLVMPass.html document for an example of why you might want to do this. -

                                Bitcode Modules

                                -
                                +

                                In some situations, it is desirable to build a single bitcode module from a variety of sources, instead of an archive, shared library, or bitcode library. Bitcode modules can be specified in addition to any of the other @@ -281,7 +281,7 @@

                                Bitcode Modules

                                Loadable Modules

                                -
                                +

                                In some situations, you need to create a loadable module. Loadable modules can be loaded into programs like opt or llc to specify additional passes to run or targets to support. Loadable modules are also @@ -309,9 +309,11 @@

                                library which is part of lib/System implementation.

                                +
                                +

                                Tools

                                -
                                +

                                For building executable programs (tools), you must provide the name of the tool and the names of the libraries you wish to link with the tool. For example:

                                @@ -342,11 +344,10 @@

                                Tools

                                syntax is used. Note that in order to use the .a suffix, the library in question must have been built with the ARCHIVE_LIBRARY option set.

                                -

                                JIT Tools

                                -
                                +

                                Many tools will want to use the JIT features of LLVM. To do this, you simply specify that you want an execution 'engine', and the makefiles will automatically link in the appropriate JIT for the host or an interpreter @@ -365,11 +366,15 @@

                                JIT Tools

                                +
                                + +
                                +

                                Targets Supported

                                -
                                +

                                This section describes each of the targets that can be built using the LLVM Makefile system. Any target can be invoked from any directory but not all are applicable to a given directory (e.g. "check", "dist" and "install" will @@ -424,11 +429,10 @@

                                Targets Supported

                              - A -
                              Remove built objects from installation directory.
                              -

                              all (default)

                              -
                              +

                              When you invoke make with no arguments, you are implicitly instructing it to seek the "all" target (goal). This target is used for building the software recursively and will do different things in different @@ -439,14 +443,14 @@

                              all (default)

                              all-local

                              -
                              +

                              This target is the same as all but it operates only on the current directory instead of recursively.

                              check

                              -
                              +

                              This target can be invoked from anywhere within a project's directories but always invokes the check-local target in the project's test directory, if it exists and has a @@ -463,7 +467,7 @@

                              check

                              check-local

                              -
                              +

                              This target should be implemented by the Makefile in the project's test directory. It is invoked by the check target elsewhere. Each project is free to define the actions of check-local as @@ -474,7 +478,7 @@

                              check-local

                              clean

                              -
                              +

                              This target cleans the build directory, recursively removing all things that the Makefile builds. The cleaning rules have been made guarded so they shouldn't go awry (via rm -f $(UNSET_VARIABLE)/* which will attempt @@ -483,14 +487,14 @@

                              clean

                              clean-local

                              -
                              +

                              This target does the same thing as clean but only for the current (local) directory.

                              dist

                              -
                              +

                              This target builds a distribution tarball. It first builds the entire project using the all target and then tars up the necessary files and compresses it. The generated tarball is sufficient for a casual source @@ -499,7 +503,7 @@

                              dist

                              dist-check

                              -
                              +

                              This target does the same thing as the dist target but also checks the distribution tarball. The check is made by unpacking the tarball to a new directory, configuring it, building it, installing it, and then verifying that @@ -511,7 +515,7 @@

                              dist-check

                              dist-clean

                              -
                              +

                              This is a special form of the clean clean target. It performs a normal clean but also removes things pertaining to building the distribution.

                              @@ -519,7 +523,7 @@

                              dist-clean

                              install

                              -
                              +

                              This target finalizes shared objects and executables and copies all libraries, headers, executables and documentation to the directory given with the --prefix option to configure. When completed, @@ -537,7 +541,7 @@

                              install

                              preconditions

                              -
                              +

                              This utility target checks to see if the Makefile in the object directory is older than the Makefile in the source directory and copies it if so. It also reruns the configure script if that needs to @@ -548,14 +552,14 @@

                              preconditions

                              printvars

                              -
                              +

                              This utility target just causes the LLVM makefiles to print out some of the makefile variables so that you can double check how things are set.

                              reconfigure

                              -
                              +

                              This utility target will force a reconfigure of LLVM or your project. It simply runs $(PROJ_OBJ_ROOT)/config.status --recheck to rerun the configuration tests and rebuild the configured files. This isn't generally @@ -565,7 +569,7 @@

                              reconfigure

                              spotless

                              -
                              +

                              This utility target, only available when $(PROJ_OBJ_ROOT) is not the same as $(PROJ_SRC_ROOT), will completely clean the $(PROJ_OBJ_ROOT) directory by removing its content entirely and @@ -577,7 +581,7 @@

                              spotless

                              tags

                              -
                              +

                              This target will generate a TAGS file in the top-level source directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file provides an index of symbol definitions so that the editor can jump you to the @@ -586,17 +590,19 @@

                              tags

                              uninstall

                              -
                              +

                              This target is the opposite of the install target. It removes the header, library and executable files from the installation directories. Note that the directories themselves are not removed because it is not guaranteed that LLVM is the only thing installing there (e.g. --prefix=/usr).

                              +
                              +

                              Variables

                              -
                              +

                              Variables are used to tell the LLVM Makefile System what to do and to obtain information from it. Variables are also used internally by the LLVM Makefile System. Variable names that contain only the upper case alphabetic @@ -604,11 +610,10 @@

                              Variables

                              variables are internal to the LLVM Makefile System and should not be relied upon nor modified. The sections below describe how to use the LLVM Makefile variables.

                              -

                              Control Variables

                              -
                              +

                              Variables listed in the table below should be set before the inclusion of $(LEVEL)/Makefile.common. These variables provide input to the LLVM make system that tell it what to do @@ -761,7 +766,7 @@

                              Control Variables

                              Override Variables

                              -
                              +

                              Override variables can be used to override the default values provided by the LLVM makefile system. These variables can be set in several ways:

                              @@ -867,7 +872,7 @@

                              Override Variables

                              Readable Variables

                              -
                              +

                              Variables listed in the table below can be used by the user's Makefile but should not be changed. Changing the value will generally cause the build to go wrong, so don't do it.

                              @@ -938,7 +943,7 @@

                              Readable Variables

                              Internal Variables

                              -
                              +

                              Variables listed below are used by the LLVM Makefile System and considered internal. You should not use these variables under any circumstances.

                              @@ -1016,6 +1021,8 @@

                              Internal Variables

                              +
                              +
                              diff --git a/docs/Packaging.html b/docs/Packaging.html index 86d6ca1ef0356..7261cc2ac0f70 100644 --- a/docs/Packaging.html +++ b/docs/Packaging.html @@ -19,7 +19,7 @@

                              Advice on Packaging LLVM

                              Overview

                              -
                              +

                              LLVM sets certain default configure options to make sure our developers don't break things for constrained platforms. These settings are not optimal for most @@ -36,7 +36,7 @@

                              Overview

                              Compile Flags

                              -
                              +

                              LLVM runs much more quickly when it's optimized and assertions are removed. However, such a build is currently incompatible with users who build without @@ -67,7 +67,7 @@

                              Compile Flags

                              C++ Features

                              -
                              +
                              RTTI
                              LLVM disables RTTI by default. Add REQUIRES_RTTI=1 @@ -80,7 +80,7 @@

                              C++ Features

                              Shared Library

                              -
                              +

                              Configure with --enable-shared to build libLLVM-major.minor.(so|dylib) and link the tools @@ -91,7 +91,7 @@

                              Shared Library

                              Dependencies

                              -
                              +
                              --enable-libffi
                              Depend on LLVM's Analysis and Transform Passes

                              Introduction

                              -
                              +

                              This document serves as a high level summary of the optimization features that LLVM provides. Optimizations are implemented as Passes that traverse some portion of a program to either collect information or transform the program. @@ -69,8 +69,7 @@

                              Introduction

                              bitcode are neither analysis nor transform passes.

                              The table below provides a quick summary of each pass and links to the more complete pass description later in the document.

                              -
                              -
                              + @@ -201,19 +200,19 @@

                              Introduction

                              ANALYSIS PASSES
                              OptionName
                              -view-postdomView postdominance tree of function
                              -view-postdom-onlyView postdominance tree of function (with no function bodies)
                              +

                              Analysis Passes

                              -
                              +

                              This section describes the LLVM Analysis Passes.

                              -

                              -aa-eval: Exhaustive Alias Analysis Precision Evaluator

                              -
                              +

                              This is a simple N^2 alias analysis accuracy evaluator. Basically, for each function in the program, it simply queries to see how the alias analysis implementation answers alias queries between each pair of @@ -227,7 +226,7 @@

                              -basicaa: Basic Alias Analysis (stateless AA impl)

                              -
                              +

                              This is the default implementation of the Alias Analysis interface that simply implements a few identities (two different globals cannot alias, @@ -239,7 +238,7 @@

                              -basiccg: Basic CallGraph Construction

                              -
                              +

                              Yet to be written.

                              @@ -247,7 +246,7 @@

                              -count-aa: Count Alias Analysis Query Responses

                              -
                              +

                              A pass which can be used to count how many alias queries are being made and how the alias analysis implementation being used responds. @@ -258,7 +257,7 @@

                              -debug-aa: AA use debugger

                              -
                              +

                              This simple pass checks alias analysis users to ensure that if they create a new value, they do not query AA without informing it of the value. @@ -275,7 +274,7 @@

                              -domfrontier: Dominance Frontier Construction

                              -
                              +

                              This pass is a simple dominator construction algorithm for finding forward dominator frontiers. @@ -286,7 +285,7 @@

                              -domtree: Dominator Tree Construction

                              -
                              +

                              This pass is a simple dominator construction algorithm for finding forward dominators. @@ -297,7 +296,7 @@

                              -dot-callgraph: Print Call Graph to 'dot' file

                              -
                              +

                              This pass, only available in opt, prints the call graph into a .dot graph. This graph can then be processed with the "dot" tool @@ -309,7 +308,7 @@

                              -dot-cfg: Print CFG of function to 'dot' file

                              -
                              +

                              This pass, only available in opt, prints the control flow graph into a .dot graph. This graph can then be processed with the @@ -321,7 +320,7 @@

                              -dot-cfg-only: Print CFG of function to 'dot' file (with no function bodies)

                              -
                              +

                              This pass, only available in opt, prints the control flow graph into a .dot graph, omitting the function bodies. This graph can @@ -334,7 +333,7 @@

                              -dot-dom: Print dominance tree of function to 'dot' file

                              -
                              +

                              This pass, only available in opt, prints the dominator tree into a .dot graph. This graph can then be processed with the @@ -346,7 +345,7 @@

                              -dot-dom-only: Print dominance tree of function to 'dot' file (with no function bodies)

                              -
                              +

                              This pass, only available in opt, prints the dominator tree into a .dot graph, omitting the function bodies. This graph can @@ -359,7 +358,7 @@

                              -dot-postdom: Print postdominance tree of function to 'dot' file

                              -
                              +

                              This pass, only available in opt, prints the post dominator tree into a .dot graph. This graph can then be processed with the @@ -371,7 +370,7 @@

                              -dot-postdom-only: Print postdominance tree of function to 'dot' file (with no function bodies)

                              -
                              +

                              This pass, only available in opt, prints the post dominator tree into a .dot graph, omitting the function bodies. This graph can @@ -384,7 +383,7 @@

                              -globalsmodref-aa: Simple mod/ref analysis for globals

                              -
                              +

                              This simple pass provides alias and mod/ref information for global values that do not have their address taken, and keeps track of whether functions @@ -397,7 +396,7 @@

                              -instcount: Counts the various types of Instructions

                              -
                              +

                              This pass collects the count of all instructions and reports them

                              @@ -407,7 +406,7 @@

                              -intervals: Interval Partition Construction

                              -
                              +

                              This analysis calculates and represents the interval partition of a function, or a preexisting interval partition. @@ -423,7 +422,7 @@

                              -iv-users: Induction Variable Users

                              -
                              +

                              Bookkeeping for "interesting" users of expressions computed from induction variables.

                              @@ -432,7 +431,7 @@

                              -lazy-value-info: Lazy Value Information Analysis

                              -
                              +

                              Interface for lazy computation of value constraint information.

                              @@ -440,7 +439,7 @@

                              -lda: Loop Dependence Analysis

                              -
                              +

                              Loop dependence analysis framework, which is used to detect dependences in memory accesses in loops.

                              @@ -449,7 +448,7 @@

                              -libcall-aa: LibCall Alias Analysis

                              -
                              +

                              LibCall Alias Analysis.

                              @@ -457,7 +456,7 @@

                              -lint: Statically lint-checks LLVM IR

                              -
                              +

                              This pass statically checks for common and easily-identified constructs which produce undefined or likely unintended behavior in LLVM IR.

                              @@ -488,7 +487,7 @@

                              -loops: Natural Loop Information

                              -
                              +

                              This analysis is used to identify natural loops and determine the loop depth of various nodes of the CFG. Note that the loops identified may actually be @@ -501,7 +500,7 @@

                              -memdep: Memory Dependence Analysis

                              -
                              +

                              An analysis that determines, for a given memory operation, what preceding memory operations it depends on. It builds on alias analysis information, and @@ -514,7 +513,7 @@

                              -module-debuginfo: Decodes module-level debug info

                              -
                              +

                              This pass decodes the debug info metadata in a module and prints in a (sufficiently-prepared-) human-readable form. @@ -527,7 +526,7 @@

                              -no-aa: No Alias Analysis (always returns 'may' alias)

                              -
                              +

                              Always returns "I don't know" for alias queries. NoAA is unlike other alias analysis implementations, in that it does not chain to a previous analysis. As @@ -539,7 +538,7 @@

                              -no-profile: No Profile Information

                              -
                              +

                              The default "no profile" implementation of the abstract ProfileInfo interface. @@ -550,7 +549,7 @@

                              -postdomfrontier: Post-Dominance Frontier Construction

                              -
                              +

                              This pass is a simple post-dominator construction algorithm for finding post-dominator frontiers. @@ -561,7 +560,7 @@

                              -postdomtree: Post-Dominator Tree Construction

                              -
                              +

                              This pass is a simple post-dominator construction algorithm for finding post-dominators. @@ -572,7 +571,7 @@

                              -print-alias-sets: Alias Set Printer

                              -
                              +

                              Yet to be written.

                              @@ -580,7 +579,7 @@

                              -print-callgraph: Print a call graph

                              -
                              +

                              This pass, only available in opt, prints the call graph to standard error in a human-readable form. @@ -591,7 +590,7 @@

                              -print-callgraph-sccs: Print SCCs of the Call Graph

                              -
                              +

                              This pass, only available in opt, prints the SCCs of the call graph to standard error in a human-readable form. @@ -602,7 +601,7 @@

                              -print-cfg-sccs: Print SCCs of each function CFG

                              -
                              +

                              This pass, only available in opt, prints the SCCs of each function CFG to standard error in a human-readable form. @@ -613,7 +612,7 @@

                              -print-dbginfo: Print debug info in human readable form

                              -
                              +

                              Pass that prints instructions, and associated debug info:

                                @@ -627,7 +626,7 @@

                                -print-dom-info: Dominator Info Printer

                                -
                                +

                                Dominator Info Printer.

                                @@ -635,7 +634,7 @@

                                -print-externalfnconstants: Print external fn callsites passed constants

                                -
                                +

                                This pass, only available in opt, prints out call sites to external functions that are called with constant arguments. This can be @@ -648,7 +647,7 @@

                                -print-function: Print function to stderr

                                -
                                +

                                The PrintFunctionPass class is designed to be pipelined with other FunctionPasses, and prints out the functions of the module @@ -660,7 +659,7 @@

                                -print-module: Print module to stderr

                                -
                                +

                                This pass simply prints out the entire module when it is executed.

                                @@ -670,7 +669,7 @@

                                -print-used-types: Find Used Types

                                -
                                +

                                This pass is used to seek out all of the types in use by the program. Note that this analysis explicitly does not include types only used by the symbol @@ -681,7 +680,7 @@

                                -profile-estimator: Estimate profiling information

                                -
                                +

                                Profiling information that estimates the profiling information in a very crude and unimaginative way.

                                @@ -691,7 +690,7 @@

                                -profile-loader: Load profile information from llvmprof.out

                                -
                                +

                                A concrete implementation of profiling information that loads the information from a profile dump file. @@ -702,13 +701,13 @@

                                -profile-verifier: Verify profiling information

                                -
                                +

                                Pass that checks profiling information for plausibility.

                                -regions: Detect single entry single exit regions

                                -
                                +

                                The RegionInfo pass detects single entry single exit regions in a function, where a region is defined as any subgraph that is connected to the @@ -721,7 +720,7 @@

                                -scalar-evolution: Scalar Evolution Analysis

                                -
                                +

                                The ScalarEvolution analysis can be used to analyze and catagorize scalar expressions in loops. It specializes in recognizing general @@ -740,7 +739,7 @@

                                -scev-aa: ScalarEvolution-based Alias Analysis

                                -
                                +

                                Simple alias analysis implemented in terms of ScalarEvolution queries. This differs from traditional loop dependence analysis in that it tests @@ -756,22 +755,23 @@

                                -targetdata: Target Data Layout

                                -
                                +

                                Provides other passes access to information on how the size and alignment required by the the target ABI for various data types.

                                +
                                +

                                Transform Passes

                                -
                                +

                                This section describes the LLVM Transform Passes.

                                -

                                -adce: Aggressive Dead Code Elimination

                                -
                                +

                                ADCE aggressively tries to eliminate code. This pass is similar to DCE but it assumes that values are dead until proven otherwise. This is similar to SCCP, except applied to @@ -782,7 +782,7 @@

                                -always-inline: Inliner for always_inline functions

                                -
                                +

                                A custom inliner that handles only functions that are marked as "always inline".

                                @@ -791,7 +791,7 @@

                                -argpromotion: Promote 'by reference' arguments to scalars

                                -
                                +

                                This pass promotes "by reference" arguments to be "by value" arguments. In practice, this means looking for internal functions that have pointer @@ -822,7 +822,7 @@

                                -block-placement: Profile Guided Basic Block Placement

                                -
                                +

                                This pass is a very simple profile guided basic block placement algorithm. The idea is to put frequently executed blocks together at the start of the function and hopefully increase the number of fall-through conditional @@ -834,7 +834,7 @@

                                -break-crit-edges: Break critical edges in CFG

                                -
                                +

                                Break all of the critical edges in the CFG by inserting a dummy basic block. It may be "required" by passes that cannot deal with critical edges. This @@ -847,7 +847,7 @@

                                -codegenprepare: Optimize for code generation

                                -
                                +
                                This pass munges the code in the input function to better prepare it for SelectionDAG-based code generation. This works around limitations in it's basic-block-at-a-time approach. It should eventually be removed. @@ -857,7 +857,7 @@

                                -constmerge: Merge Duplicate Global Constants

                                -
                                +

                                Merges duplicate global constants together into a single constant that is shared. This is useful because some passes (ie TraceValues) insert a lot of @@ -870,7 +870,7 @@

                                -constprop: Simple constant propagation

                                -
                                +

                                This file implements constant propagation and merging. It looks for instructions involving only constant operands and replaces them with a constant value instead of an instruction. For example:

                                @@ -886,7 +886,7 @@

                                -dce: Dead Code Elimination

                                -
                                +

                                Dead code elimination is similar to dead instruction elimination, but it rechecks instructions that were used by removed @@ -898,7 +898,7 @@

                                -deadargelim: Dead Argument Elimination

                                -
                                +

                                This pass deletes dead arguments from internal functions. Dead argument elimination removes arguments which are directly dead, as well as arguments @@ -916,7 +916,7 @@

                                -deadtypeelim: Dead Type Elimination

                                -
                                +

                                This pass is used to cleanup the output of GCC. It eliminate names for types that are unused in the entire translation unit, using the

                                -die: Dead Instruction Elimination

                                -
                                +

                                Dead instruction elimination performs a single pass over the function, removing instructions that are obviously dead. @@ -939,7 +939,7 @@

                                -dse: Dead Store Elimination

                                -
                                +

                                A trivial dead store elimination that only considers basic-block local redundant stores. @@ -950,7 +950,7 @@

                                -functionattrs: Deduce function attributes

                                -
                                +

                                A simple interprocedural pass which walks the call-graph, looking for functions which do not access or only read non-local memory, and marking them readnone/readonly. In addition, it marks function arguments (of pointer type) @@ -965,7 +965,7 @@

                                -globaldce: Dead Global Elimination

                                -
                                +

                                This transform is designed to eliminate unreachable internal globals from the program. It uses an aggressive algorithm, searching out globals that are @@ -979,7 +979,7 @@

                                -globalopt: Global Variable Optimizer

                                -
                                +

                                This pass transforms simple global variables that never have their address taken. If obviously true, it marks read/write globals as constant, deletes @@ -991,7 +991,7 @@

                                -gvn: Global Value Numbering

                                -
                                +

                                This pass performs global value numbering to eliminate fully and partially redundant instructions. It also performs redundant load elimination. @@ -1002,7 +1002,7 @@

                                -indvars: Canonicalize Induction Variables

                                -
                                +

                                This transformation analyzes and transforms the induction variables (and computations derived from them) into simpler forms suitable for subsequent @@ -1053,7 +1053,7 @@

                                -inline: Function Integration/Inlining

                                -
                                +

                                Bottom-up inlining of functions into callees.

                                @@ -1063,7 +1063,7 @@

                                -insert-edge-profiling: Insert instrumentation for edge profiling

                                -
                                +

                                This pass instruments the specified program with counters for edge profiling. Edge profiling can give a reasonable approximation of the hot paths through a @@ -1081,7 +1081,7 @@

                                -insert-optimal-edge-profiling: Insert optimal instrumentation for edge profiling

                                -
                                +

                                This pass instruments the specified program with counters for edge profiling. Edge profiling can give a reasonable approximation of the hot paths through a program, and is used for a wide variety of program transformations. @@ -1092,7 +1092,7 @@

                                -instcombine: Combine redundant instructions

                                -
                                +

                                Combine instructions to form fewer, simple instructions. This pass does not modify the CFG This pass is where algebraic @@ -1146,7 +1146,7 @@

                                -internalize: Internalize Global Symbols

                                -
                                +

                                This pass loops over all of the functions in the input module, looking for a main function. If a main function is found, all other functions and all @@ -1158,7 +1158,7 @@

                                -ipconstprop: Interprocedural constant propagation

                                -
                                +

                                This pass implements an extremely simple interprocedural constant propagation pass. It could certainly be improved in many different ways, @@ -1172,7 +1172,7 @@

                                -ipsccp: Interprocedural Sparse Conditional Constant Propagation

                                -
                                +

                                An interprocedural variant of Sparse Conditional Constant Propagation. @@ -1183,7 +1183,7 @@

                                -jump-threading: Jump Threading

                                -
                                +

                                Jump threading tries to find distinct threads of control flow running through a basic block. This pass looks at blocks that have multiple predecessors and @@ -1212,7 +1212,7 @@

                                -lcssa: Loop-Closed SSA Form Pass

                                -
                                +

                                This pass transforms loops by placing phi nodes at the end of the loops for all values that are live across the loop boundary. For example, it turns @@ -1241,7 +1241,7 @@

                                -licm: Loop Invariant Code Motion

                                -
                                +

                                This pass performs loop invariant code motion, attempting to remove as much code from the body of a loop as possible. It does this by either hoisting @@ -1278,7 +1278,7 @@

                                -loop-deletion: Delete dead loops

                                -
                                +

                                This file implements the Dead Loop Deletion Pass. This pass is responsible for eliminating loops with non-infinite computable trip counts that have no @@ -1291,7 +1291,7 @@

                                -loop-extract: Extract loops into new functions

                                -
                                +

                                A pass wrapper around the ExtractLoop() scalar transformation to extract each top-level loop into its own new function. If the loop is the @@ -1304,7 +1304,7 @@

                                -loop-extract-single: Extract at most one loop into a new function

                                -
                                +

                                Similar to Extract loops into new functions, this pass extracts one natural loop from the program into a function if it @@ -1316,7 +1316,7 @@

                                -loop-reduce: Loop Strength Reduction

                                -
                                +

                                This pass performs a strength reduction on array references inside loops that have as one or more of their components the loop induction variable. This is @@ -1330,7 +1330,7 @@

                                -loop-rotate: Rotate Loops

                                -
                                +

                                A simple loop rotation transformation.

                                @@ -1338,7 +1338,7 @@

                                -loop-simplify: Canonicalize natural loops

                                -
                                +

                                This pass performs several transformations to transform natural loops into a simpler form, which makes subsequent analyses and transformations simpler and @@ -1379,7 +1379,7 @@

                                -loop-unroll: Unroll loops

                                -
                                +

                                This pass implements a simple loop unroller. It works best when loops have been canonicalized by the -indvars pass, @@ -1391,7 +1391,7 @@

                                -loop-unswitch: Unswitch loops

                                -
                                +

                                This pass transforms loops that contain branches on loop-invariant conditions to have multiple loops. For example, it turns the left into the right code: @@ -1421,7 +1421,7 @@

                                -loweratomic: Lower atomic intrinsics to non-atomic form

                                -
                                +

                                This pass lowers atomic intrinsics to non-atomic form for use in a known non-preemptible environment. @@ -1439,7 +1439,7 @@

                                -lowerinvoke: Lower invoke and unwind, for unwindless code generators

                                -
                                +

                                This transformation is designed for use by code generators which do not yet support stack unwinding. This pass supports two models of exception handling @@ -1480,7 +1480,7 @@

                                -lowersetjmp: Lower Set Jump

                                -
                                +

                                Lowers setjmp and longjmp to use the LLVM invoke and unwind instructions as necessary. @@ -1509,7 +1509,7 @@

                                -lowerswitch: Lower SwitchInst's to branches

                                -
                                +

                                Rewrites switch instructions with a sequence of branches, which allows targets to get away with not implementing the switch instruction until @@ -1521,7 +1521,7 @@

                                -mem2reg: Promote Memory to Register

                                -
                                +

                                This file promotes memory references to be register references. It promotes alloca instructions which only have loads and @@ -1537,7 +1537,7 @@

                                -memcpyopt: MemCpy Optimization

                                -
                                +

                                This pass performs various transformations related to eliminating memcpy calls, or transforming sets of stores into memset's. @@ -1548,7 +1548,7 @@

                                -mergefunc: Merge Functions

                                -
                                +

                                This pass looks for equivalent functions that are mergable and folds them. A hash is computed from the function, based on its type and number of @@ -1569,7 +1569,7 @@

                                -mergereturn: Unify function exit nodes

                                -
                                +

                                Ensure that functions have at most one ret instruction in them. Additionally, it keeps track of which node is the new exit node of the CFG. @@ -1580,7 +1580,7 @@

                                -partial-inliner: Partial Inliner

                                -
                                +

                                This pass performs partial inlining, typically by inlining an if statement that surrounds the body of the function.

                                @@ -1590,7 +1590,7 @@

                                -prune-eh: Remove unused exception handling info

                                -
                                +

                                This file implements a simple interprocedural pass which walks the call-graph, turning invoke instructions into call instructions if and @@ -1603,7 +1603,7 @@

                                -reassociate: Reassociate expressions

                                -
                                +

                                This pass reassociates commutative expressions in an order that is designed to promote better constant propagation, GCSE, LICM, PRE, etc. @@ -1626,7 +1626,7 @@

                                -reg2mem: Demote all values to stack slots

                                -
                                +

                                This file demotes all registers to memory references. It is intented to be the inverse of -mem2reg. By converting to @@ -1643,7 +1643,7 @@

                                -scalarrepl: Scalar Replacement of Aggregates (DT)

                                -
                                +

                                The well-known scalar replacement of aggregates transformation. This transform breaks up alloca instructions of aggregate type (structure @@ -1665,7 +1665,7 @@

                                -sccp: Sparse Conditional Constant Propagation

                                -
                                +

                                Sparse conditional constant propagation and merging, which can be summarized as: @@ -1688,7 +1688,7 @@

                                -simplify-libcalls: Simplify well-known library calls

                                -
                                +

                                Applies a variety of small optimizations for calls to specific well-known function calls (e.g. runtime library functions). For example, a call @@ -1701,7 +1701,7 @@

                                -simplifycfg: Simplify the CFG

                                -
                                +

                                Performs dead code elimination and basic block merging. Specifically:

                                @@ -1720,7 +1720,7 @@

                                -sink: Code sinking

                                -
                                +

                                This pass moves instructions into successor blocks, when possible, so that they aren't executed on paths where their results aren't needed.

                                @@ -1730,7 +1730,7 @@

                                -sretpromotion: Promote sret arguments to multiple ret values

                                -
                                +

                                This pass finds functions that return a struct (using a pointer to the struct as the first argument of the function, marked with the 'sret' attribute) and @@ -1753,7 +1753,7 @@

                                -strip: Strip all symbols from a module

                                -
                                +

                                performs code stripping. this transformation can delete:

                                @@ -1775,7 +1775,7 @@

                                -strip-dead-debug-info: Strip debug info for unused symbols

                                -
                                +

                                performs code stripping. this transformation can delete:

                                @@ -1797,7 +1797,7 @@

                                -strip-dead-prototypes: Strip Unused Function Prototypes

                                -
                                +

                                This pass loops over all of the functions in the input module, looking for dead declarations and removes them. Dead declarations are declarations of @@ -1810,7 +1810,7 @@

                                -strip-debug-declare: Strip all llvm.dbg.declare intrinsics

                                -
                                +

                                This pass implements code stripping. Specifically, it can delete:

                                • names for virtual registers
                                • @@ -1828,7 +1828,7 @@

                                  -strip-nondebug: Strip all symbols, except dbg symbols, from a module

                                  -
                                  +

                                  This pass implements code stripping. Specifically, it can delete:

                                  • names for virtual registers
                                  • @@ -1846,7 +1846,7 @@

                                    -tailcallelim: Tail Call Elimination

                                    -
                                    +

                                    This file transforms calls of the current function (self recursion) followed by a return instruction with a branch to the entry of the function, creating @@ -1878,7 +1878,7 @@

                                    -tailduplicate: Tail Duplication

                                    -
                                    +

                                    This pass performs a limited form of tail duplication, intended to simplify CFGs by removing some unconditional branches. This pass is necessary to @@ -1888,17 +1888,18 @@

                                    +
                                    +

                                    Utility Passes

                                    -
                                    +

                                    This section describes the LLVM Utility Passes.

                                    -

                                    -deadarghaX0r: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)

                                    -
                                    +

                                    Same as dead argument elimination, but deletes arguments to functions which are external. This is only for use by

                                    -extract-blocks: Extract Basic Blocks From Module (for bugpoint use)

                                    -
                                    +

                                    This pass is used by bugpoint to extract all blocks from the module into their own functions.

                                    @@ -1919,7 +1920,7 @@

                                    -instnamer: Assign names to anonymous instructions

                                    -
                                    +

                                    This is a little utility pass that gives instructions names, this is mostly useful when diffing the effect of an optimization because deleting an unnamed instruction can change all other instruction numbering, making the @@ -1931,7 +1932,7 @@

                                    -preverify: Preliminary module verification

                                    -
                                    +

                                    Ensures that the module is in the form required by the Module Verifier pass. @@ -1947,7 +1948,7 @@

                                    -verify: Module Verifier

                                    -
                                    +

                                    Verifies an LLVM IR code. This is useful to run after an optimization which is undergoing testing. Note that llvm-as verifies its input before @@ -1998,7 +1999,7 @@

                                    -view-cfg: View CFG of function

                                    -
                                    +

                                    Displays the control flow graph using the GraphViz tool.

                                    @@ -2008,7 +2009,7 @@

                                    -view-cfg-only: View CFG of function (with no function bodies)

                                    -
                                    +

                                    Displays the control flow graph using the GraphViz tool, but omitting function bodies. @@ -2019,7 +2020,7 @@

                                    -view-dom: View dominance tree of function

                                    -
                                    +

                                    Displays the dominator tree using the GraphViz tool.

                                    @@ -2029,7 +2030,7 @@

                                    -view-dom-only: View dominance tree of function (with no function bodies)

                                    -
                                    +

                                    Displays the dominator tree using the GraphViz tool, but omitting function bodies. @@ -2040,7 +2041,7 @@

                                    -view-postdom: View postdominance tree of function

                                    -
                                    +

                                    Displays the post dominator tree using the GraphViz tool.

                                    @@ -2050,13 +2051,15 @@

                                    -view-postdom-only: View postdominance tree of function (with no function bodies)

                                    -
                                    +

                                    Displays the post dominator tree using the GraphViz tool, but omitting function bodies.

                                    +
                                    +
                                    diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index b29c582612451..060bbb6d91b0f 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -215,7 +215,7 @@

                                    -
                                    +

                                    This document is meant to highlight some of the important classes and interfaces available in the LLVM source-base. This manual is not @@ -247,19 +247,17 @@

                                    -
                                    +

                                    This section contains general information that is useful if you are working in the LLVM source-base, but that isn't specific to any particular API.

                                    -
                                    -

                                    The C++ Standard Template Library

                                    -
                                    +

                                    LLVM makes heavy use of the C++ Standard Template Library (STL), perhaps much more than you are used to, or have seen before. Because of @@ -309,7 +307,7 @@

                                    Other useful references

                                    - +

                                    Important and useful LLVM APIs

                                    -
                                    +

                                    Here we highlight some LLVM APIs that are generally useful and good to know about when writing transformations.

                                    -
                                    -

                                    The isa<>, cast<> and dyn_cast<> templates

                                    -
                                    +

                                    The LLVM source-base makes extensive use of a custom form of RTTI. These templates have many similarities to the C++ dynamic_cast<> @@ -447,7 +445,7 @@

                                    and Twine classes)

                                    -
                                    +

                                    Although LLVM generally does not do much string manipulation, we do have several important APIs which take strings. Two important examples are the @@ -461,14 +459,12 @@

                                    many LLVM APIs use a StringRef or a const Twine& for passing strings efficiently.

                                    -

                                    -

                                    The StringRef class

                                    -
                                    +

                                    The StringRef data type represents a reference to a constant string (a character array and a length) and supports the common operations available @@ -508,7 +504,7 @@

                                    The Twine class

                                    -
                                    +

                                    The Twine class is an efficient way for APIs to accept concatenated strings. For example, a common LLVM paradigm is to name one instruction based on @@ -539,13 +535,14 @@

                                    +

                                    The DEBUG() macro and -debug option

                                    -
                                    +

                                    Often when working on your pass you will put a bunch of debugging printouts and other code into your pass. After you get it working, you want to remove @@ -591,15 +588,13 @@

                                    program hasn't been started yet, you can always just run it with -debug.

                                    -

                                    -

                                    Fine grained debug info with DEBUG_TYPE and the -debug-only option

                                    -
                                    +

                                    Sometimes you may find yourself in a situation where enabling -debug just turns on too much information (such as when working on the code @@ -667,13 +662,15 @@

                                    +
                                    +

                                    The Statistic class & -stats option

                                    -
                                    +

                                    The "llvm/ADT/Statistic.h" file @@ -772,7 +769,7 @@

                                    Viewing graphs while debugging code

                                    -
                                    +

                                    Several of the important data structures in LLVM are graphs: for example CFGs made out of LLVM BasicBlocks, CFGs made out of @@ -816,13 +813,15 @@

                                    +
                                    +

                                    Picking the Right Data Structure for a Task

                                    -
                                    +

                                    LLVM has a plethora of data structures in the llvm/ADT/ directory, and we commonly use STL data structures. This section describes the trade-offs @@ -878,24 +877,21 @@

                                    . Doing so avoids (relatively) expensive malloc/free calls, which dwarf the cost of adding the elements to the container.

                                    -

                                    -

                                    Sequential Containers (std::vector, std::list, etc)

                                    -
                                    +
                                    There are a variety of sequential containers available for you, based on your needs. Pick the first in this section that will do what you want. -

                                    llvm/ADT/ArrayRef.h

                                    -
                                    +

                                    The llvm::ArrayRef class is the preferred class to use in an interface that accepts a sequential list of elements in memory and just reads from them. By taking an ArrayRef, the API can be passed a fixed size array, an std::vector, @@ -910,7 +906,7 @@

                                    Fixed Size Arrays

                                    -
                                    +

                                    Fixed size arrays are very simple and very fast. They are good if you know exactly how many elements you have, or you have a (low) upper bound on how many you have.

                                    @@ -921,7 +917,7 @@

                                    Heap Allocated Arrays

                                    -
                                    +

                                    Heap allocated arrays (new[] + delete[]) are also simple. They are good if the number of elements is variable, if you know how many elements you will need before the array is allocated, and if the array is usually large (if not, @@ -937,7 +933,7 @@

                                    "llvm/ADT/SmallVector.h"

                                    -
                                    +

                                    SmallVector<Type, N> is a simple class that looks and smells just like vector<Type>: it supports efficient iteration, lays out elements in memory order (so you can @@ -966,7 +962,7 @@

                                    <vector>

                                    -
                                    +

                                    std::vector is well loved and respected. It is useful when SmallVector isn't: when the size of the vector is often large (thus the small optimization will @@ -1008,7 +1004,7 @@

                                    <deque>

                                    -
                                    +

                                    std::deque is, in some senses, a generalized version of std::vector. Like std::vector, it provides constant time random access and other similar properties, but it also provides efficient access to the front of the list. It @@ -1024,7 +1020,7 @@

                                    <list>

                                    -
                                    +

                                    std::list is an extremely inefficient class that is rarely useful. It performs a heap allocation for every element inserted into it, thus having an extremely high constant factor, particularly for small data types. std::list @@ -1042,7 +1038,7 @@

                                    llvm/ADT/ilist.h

                                    -
                                    +

                                    ilist<T> implements an 'intrusive' doubly-linked list. It is intrusive, because it requires the element to store and provide access to the prev/next pointers for the list.

                                    @@ -1072,7 +1068,7 @@

                                    ilist_traits

                                    -
                                    +

                                    ilist_traits<T> is ilist<T>'s customization mechanism. iplist<T> (and consequently ilist<T>) publicly derive from this traits class.

                                    @@ -1083,7 +1079,7 @@

                                    iplist

                                    -
                                    +

                                    iplist<T> is ilist<T>'s base and as such supports a slightly narrower interface. Notably, inserters from T& are absent.

                                    @@ -1097,7 +1093,7 @@

                                    llvm/ADT/ilist_node.h

                                    -
                                    +

                                    ilist_node<T> implements a the forward and backward links that are expected by the ilist<T> (and analogous containers) in the default manner.

                                    @@ -1112,7 +1108,7 @@

                                    Sentinels

                                    -
                                    +

                                    ilists have another specialty that must be considered. To be a good citizen in the C++ ecosystem, it needs to support the standard container operations, such as begin and end iterators, etc. Also, the @@ -1150,7 +1146,7 @@

                                    Other Sequential Container options

                                    -
                                    +

                                    Other STL containers are available, such as std::string.

                                    There are also various STL adapter classes such as std::queue, @@ -1159,27 +1155,25 @@

                                    +

                                    Set-Like Containers (std::set, SmallSet, SetVector, etc)

                                    -
                                    +

                                    Set-like containers are useful when you need to canonicalize multiple values into a single representation. There are several different choices for how to do this, providing various trade-offs.

                                    -
                                    - -

                                    A sorted 'vector'

                                    -
                                    +

                                    If you intend to insert a lot of elements, then do a lot of queries, a great approach is to use a vector (or other sequential container) with @@ -1201,7 +1195,7 @@

                                    "llvm/ADT/SmallSet.h"

                                    -
                                    +

                                    If you have a set-like data structure that is usually small and whose elements are reasonably small, a SmallSet<Type, N> is a good choice. This set @@ -1224,7 +1218,7 @@

                                    "llvm/ADT/SmallPtrSet.h"

                                    -
                                    +

                                    SmallPtrSet has all the advantages of SmallSet (and a SmallSet of pointers is transparently implemented with a SmallPtrSet), but also supports iterators. If @@ -1244,7 +1238,7 @@

                                    "llvm/ADT/DenseSet.h"

                                    -
                                    +

                                    DenseSet is a simple quadratically probed hash table. It excels at supporting @@ -1263,7 +1257,7 @@

                                    "llvm/ADT/FoldingSet.h"

                                    -
                                    +

                                    FoldingSet is an aggregate class that is really good at uniquing @@ -1300,7 +1294,7 @@

                                    <set>

                                    -
                                    +

                                    std::set is a reasonable all-around set class, which is decent at many things but great at nothing. std::set allocates memory for each element @@ -1325,7 +1319,7 @@

                                    "llvm/ADT/SetVector.h"

                                    -
                                    +

                                    LLVM's SetVector<Type> is an adapter class that combines your choice of a set-like container along with a Sequential Container. The important property @@ -1365,7 +1359,7 @@

                                    "llvm/ADT/UniqueVector.h"

                                    -
                                    +

                                    UniqueVector is similar to SetVector, but it @@ -1385,7 +1379,7 @@

                                    Other Set-Like Container Options

                                    -
                                    +

                                    The STL provides several other options, such as std::multiset and the various @@ -1401,22 +1395,23 @@

                                    +
                                    +

                                    Map-Like Containers (std::map, DenseMap, etc)

                                    -
                                    +
                                    Map-like containers are useful when you want to associate data to a key. As usual, there are a lot of different ways to do this. :) -

                                    A sorted 'vector'

                                    -
                                    +

                                    If your usage pattern follows a strict insert-then-query approach, you can @@ -1433,7 +1428,7 @@

                                    "llvm/ADT/StringMap.h"

                                    -
                                    +

                                    Strings are commonly used as keys in maps, and they are difficult to support @@ -1467,7 +1462,7 @@

                                    "llvm/ADT/IndexedMap.h"

                                    -
                                    +

                                    IndexedMap is a specialized container for mapping small dense integers (or values that can be mapped to small dense integers) to some other type. It is @@ -1487,7 +1482,7 @@

                                    "llvm/ADT/DenseMap.h"

                                    -
                                    +

                                    DenseMap is a simple quadratically probed hash table. It excels at supporting @@ -1513,7 +1508,7 @@

                                    "llvm/ADT/ValueMap.h"

                                    -
                                    +

                                    ValueMap is a wrapper around a DenseMap mapping @@ -1530,7 +1525,7 @@

                                    "llvm/ADT/IntervalMap.h"

                                    -
                                    +

                                    IntervalMap is a compact map for small keys and values. It maps key intervals instead of single keys, and it will automatically coalesce adjacent @@ -1547,7 +1542,7 @@

                                    <map>

                                    -
                                    +

                                    std::map has similar characteristics to std::set: it uses @@ -1567,7 +1562,7 @@

                                    "llvm/ADT/IntEqClasses.h"

                                    -
                                    +

                                    IntEqClasses provides a compact representation of equivalence classes of small integers. Initially, each integer in the range 0..n-1 has its own @@ -1587,7 +1582,7 @@

                                    Other Map-Like Container Options

                                    -
                                    +

                                    The STL provides several other options, such as std::multimap and the various @@ -1601,12 +1596,14 @@

                                    +
                                    +

                                    String-like containers

                                    -
                                    +

                                    TODO: const char* vs stringref vs smallstring vs std::string. Describe twine, @@ -1620,7 +1617,7 @@

                                    Bit storage containers (BitVector, SparseBitVector)

                                    -
                                    +

                                    Unlike the other containers, there are only two bit storage containers, and choosing when to use each is relatively straightforward.

                                    @@ -1630,14 +1627,13 @@

                                    GCC) is extremely inefficient and 2) the C++ standards committee is likely to deprecate this container and/or change it significantly somehow. In any case, please don't use it.

                                    -

                                    BitVector

                                    -
                                    +

                                    The BitVector container provides a dynamic size set of bits for manipulation. It supports individual bit setting/testing, as well as set operations. The set operations take time O(size of bitvector), but operations are performed one word @@ -1652,7 +1648,7 @@

                                    SmallBitVector

                                    -
                                    +

                                    The SmallBitVector container provides the same interface as BitVector, but it is optimized for the case where only a small number of bits, less than 25 or so, are needed. It also transparently supports larger bit counts, but @@ -1671,7 +1667,7 @@

                                    SparseBitVector

                                    -
                                    +

                                    The SparseBitVector container is much like BitVector, with one major difference: Only the bits that are set, are stored. This makes the SparseBitVector much more space efficient than BitVector when the set is sparse, @@ -1681,13 +1677,17 @@

                                    +
                                    + +
                                    +

                                    Helpful Hints for Common Operations

                                    -
                                    +

                                    This section describes how to perform some very simple transformations of LLVM code. This is meant to give examples of common idioms used, showing the @@ -1696,15 +1696,13 @@

                                    Core LLVM Class Hierarchy Reference contains details and descriptions of the main classes that you should know about.

                                    -

                                    -

                                    Basic Inspection and Traversal Routines

                                    -
                                    +

                                    The LLVM compiler infrastructure have many different data structures that may be traversed. Following the example of the C++ standard template library, the @@ -1721,8 +1719,6 @@

                                    examples of the data structures that need to be traversed. Other data structures are traversed in very similar ways.

                                    -

                                    -

                                    Iterating over the href="#Function">Function

                                    -
                                    +

                                    It's quite common to have a Function instance that you'd like to transform in some way; in particular, you'd like to manipulate its @@ -1765,7 +1761,7 @@

                                    href="#BasicBlock">BasicBlock

                                    -
                                    +

                                    Just like when dealing with BasicBlocks in Functions, it's easy to iterate over the individual instructions that make up @@ -1796,7 +1792,7 @@

                                    href="#Function">Function

                                    -
                                    +

                                    If you're finding that you commonly iterate over a Function's BasicBlocks and then that BasicBlock's Instructions, @@ -1841,7 +1837,7 @@

                                    vice-versa)

                                    -
                                    +

                                    Sometimes, it'll be useful to grab a reference (or pointer) to a class instance when all you've got at hand is an iterator. Well, extracting @@ -1918,7 +1914,7 @@

                                    example

                                    -
                                    +

                                    Say that you're writing a FunctionPass and would like to count all the locations in the entire module (that is, across every Function) where a @@ -1979,7 +1975,7 @@

                                    Treating calls and invokes the same way

                                    -
                                    +

                                    You may have noticed that the previous example was a bit oversimplified in that it did not deal with call sites generated by 'invoke' instructions. In @@ -2006,7 +2002,7 @@

                                    Iterating over def-use & use-def chains

                                    -
                                    +

                                    Frequently, we might have an instance of the Value Class and we want to @@ -2068,7 +2064,7 @@

                                    successors of blocks

                                    -
                                    +

                                    Iterating over the predecessors and successors of a block is quite easy with the routines defined in "llvm/Support/CFG.h". Just use code like @@ -2091,13 +2087,14 @@

                                    +

                                    Making simple changes

                                    -
                                    +

                                    There are some primitive transformation operations present in the LLVM infrastructure that are worth knowing about. When performing @@ -2105,15 +2102,13 @@

                                    blocks. This section describes some of the common methods for doing so and gives example code.

                                    -

                                    -

                                    Creating and inserting new Instructions

                                    -
                                    +

                                    Instantiating Instructions

                                    @@ -2253,7 +2248,7 @@

                                    Deleting Instructions

                                    -
                                    +

                                    Deleting an instruction from an existing sequence of instructions that form a BasicBlock is very straight-forward: just @@ -2278,7 +2273,7 @@

                                    Value

                                    -
                                    +

                                    Replacing individual instructions

                                    @@ -2343,7 +2338,7 @@

                                    Deleting GlobalVariables

                                    -
                                    +

                                    Deleting a global variable from a module is just as easy as deleting an Instruction. First, you must have a pointer to the global variable that you wish @@ -2360,12 +2355,14 @@

                                    +
                                    +

                                    How to Create Types

                                    -
                                    +

                                    In generating IR, you may need some complex types. If you know these types statically, you can use TypeBuilder<...>::get(), defined @@ -2400,13 +2397,15 @@

                                    +
                                    +

                                    Threads and LLVM

                                    -
                                    +

                                    This section describes the interaction of the LLVM APIs with multithreading, both on the part of client applications, and in the JIT, in the hosted @@ -2429,14 +2428,13 @@

                                    using the resultant compiler to build a copy of LLVM with multithreading support.

                                    -

                                    Entering and Exiting Multithreaded Mode

                                    -
                                    +

                                    In order to properly protect its internal data structures while avoiding @@ -2473,7 +2471,7 @@

                                    Ending Execution with llvm_shutdown()

                                    -
                                    +

                                    When you are done using the LLVM APIs, you should call llvm_shutdown() to deallocate memory used for internal structures. This will also invoke @@ -2493,7 +2491,7 @@

                                    Lazy Initialization with ManagedStatic

                                    -
                                    +

                                    ManagedStatic is a utility class in LLVM used to implement static initialization of static resources, such as the global type tables. Before the @@ -2522,7 +2520,7 @@

                                    Achieving Isolation with LLVMContext

                                    -
                                    +

                                    LLVMContext is an opaque class in the LLVM API which clients can use to operate multiple, isolated instances of LLVM concurrently within the same @@ -2566,7 +2564,7 @@

                                    Threads and the JIT

                                    -
                                    +

                                    LLVM's "eager" JIT compiler is safe to use in threaded programs. Multiple threads can call ExecutionEngine::getPointerToFunction() or @@ -2589,26 +2587,27 @@

                                    +
                                    +

                                    Advanced Topics

                                    -
                                    +

                                    This section describes some of the advanced or obscure API's that most clients do not need to be aware of. These API's tend manage the inner workings of the LLVM system, and only need to be accessed in unusual circumstances.

                                    -

                                    LLVM Type Resolution

                                    -
                                    +

                                    The LLVM type system has a very simple goal: allow clients to compare types for @@ -2637,14 +2636,12 @@

                                    float }").

                                    -

                                    -

                                    Basic Recursive Type Construction

                                    -
                                    +

                                    Because the most common question is "how do I build a recursive type with LLVM", @@ -2700,7 +2697,7 @@

                                    The refineAbstractTypeTo method

                                    -
                                    +

                                    The refineAbstractTypeTo method starts the type unification process. While this method is actually a member of the DerivedType class, it is most @@ -2730,7 +2727,7 @@

                                    The PATypeHolder Class

                                    -
                                    +

                                    PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore happily goes about nuking types that become isomorphic to existing types, it @@ -2752,7 +2749,7 @@

                                    The AbstractTypeUser Class

                                    -
                                    +

                                    Some data structures need more to perform more complex updates when types get @@ -2766,6 +2763,7 @@

                                    +

                                    @@ -2773,7 +2771,7 @@

                                    TypeSymbolTable classes

                                    -
                                    +

                                    The ValueSymbolTable class provides a symbol table that the Function and @@ -2808,7 +2806,7 @@

                                    The User and owned Use classes' memory layout

                                    -
                                    +

                                    The User class provides a basis for expressing the ownership of User towards other @@ -2823,14 +2821,13 @@

                                    -
                                    +

                                    A subclass of User can choose between incorporating its Use objects or refer to them out-of-line by means of a pointer. A mixed variant (some Uses inline others hung off) is impractical and breaks the invariant that the Use objects belonging to the same User form a contiguous array.

                                    -

                                    We have 2 different layouts in the User (sub)classes: @@ -2879,17 +2876,18 @@

                                    (In the above figures 'P' stands for the Use** that is stored in each Use object in the member Use::Prev) +

                                    +

                                    The waymarking algorithm

                                    -
                                    +

                                    Since the Use objects are deprived of the direct (back)pointer to their User objects, there must be a fast and exact method to recover it. This is accomplished by the following scheme:

                                    -
                                    A bit-encoding in the 2 LSBits (least significant bits) of the Use::Prev allows to find the start of the User object: @@ -2920,15 +2918,16 @@

                                    stops, so that the worst case is 20 memory accesses when there are 1000 Use objects associated with a User.

                                    +

                                    +

                                    Reference implementation

                                    -
                                    +

                                    The following literate Haskell fragment demonstrates the concept:

                                    -
                                    @@ -3010,11 +3009,15 @@ 

                                    OK, passed 500 tests.

                                    +
                                    +

                                    Tagging considerations

                                    +
                                    +

                                    To maintain the invariant that the 2 LSBits of each Use** in Use never change after being set up, setters of Use::Prev must re-tag the @@ -3029,13 +3032,17 @@

                                    - +
                                    + +
                                    + +

                                    The Core LLVM Class Hierarchy Reference

                                    -
                                    +

                                    #include "llvm/Type.h"
                                    doxygen info: Type Class

                                    @@ -3044,14 +3051,12 @@

                                    header files in the include/llvm/ directory, and implemented in the lib/VMCore directory.

                                    -

                                    -

                                    The Type class and Derived Types

                                    -
                                    +

                                    Type is a superclass of all type classes. Every Value has a Type. Type cannot be instantiated directly but only @@ -3066,14 +3071,13 @@

                                    be performed with address equality of the Type Instance. That is, given two Type* values, the types are identical if the pointers are identical.

                                    -

                                    Important Public Methods

                                    -
                                    +
                                    • bool isIntegerTy() const: Returns true for any integer type.
                                    • @@ -3094,7 +3098,7 @@

                                      Important Derived Types

                                      -
                                      +
                                      IntegerType
                                      Subclass of DerivedType that represents integer types of any bit width. @@ -3156,14 +3160,14 @@

                                      - +

                                      The Module class

                                      -
                                      +

                                      #include "llvm/Module.h"
                                      doxygen info: @@ -3178,14 +3182,12 @@

                                      href="#SymbolTable">SymbolTable. Additionally, it contains a few helpful member functions that try to make common operations easy.

                                      -

                                      -

                                      Important Public Members of the Module class

                                      -
                                      +
                                      • Module::Module(std::string name = "")
                                      • @@ -3284,13 +3286,14 @@

                                      +

                                      The Value class

                                      -
                                      +

                                      #include "llvm/Value.h"
                                      @@ -3341,14 +3344,12 @@

                                      represents this value. Although this may take some getting used to, it simplifies the representation and makes it easier to manipulate.

                                      -

                                      -

                                      Important Public Members of the Value class

                                      -
                                      +
                                      • Value::use_iterator - Typedef for iterator over the @@ -3395,12 +3396,14 @@

                                      +
                                      +

                                      The User class

                                      -
                                      +

                                      #include "llvm/User.h"
                                      @@ -3419,14 +3422,12 @@

                                      allowing this direct connection. This connection provides the use-def information in LLVM.

                                      -

                                      -

                                      Important Public Members of the User class

                                      -
                                      +

                                      The User class exposes the operand list in two ways: through an index access interface and through an iterator based interface.

                                      @@ -3449,12 +3450,14 @@

                                      +
                                      +

                                      The Instruction class

                                      -
                                      +

                                      #include "llvm/Instruction.h"
                                      @@ -3485,15 +3488,13 @@

                                      this file confuses doxygen, so these enum values don't show up correctly in the doxygen output.

                                      -

                                      -

                                      Important Subclasses of the Instruction class

                                      -
                                      +
                                      • BinaryOperator

                                        This subclasses represents all two operand instructions whose operands @@ -3518,7 +3519,7 @@

                                        -
                                        +
                                        +
                                        +

                                        The Constant class and subclasses

                                        -
                                        +

                                        Constant represents a base class for different types of constants. It is subclassed by ConstantInt, ConstantArray, etc. for representing @@ -3551,11 +3554,9 @@

                                        a subclass, which represents the address of a global variable or function.

                                        -

                                        -

                                        Important Subclasses of Constant

                                        -
                                        +
                                        • ConstantInt : This subclass of Constant represents an integer constant of any width. @@ -3603,13 +3604,14 @@

                                          Important Subclasses of Constant

                                        +

                                        The GlobalValue class

                                        -
                                        +

                                        #include "llvm/GlobalValue.h"
                                        @@ -3649,8 +3651,6 @@

                                        can be accessed. This is explained in the LLVM Language Reference Manual.

                                        -

                                        -

                                        @@ -3658,7 +3658,7 @@

                                        -
                                        +
                                        • bool hasInternalLinkage() const
                                          @@ -3674,12 +3674,14 @@

                                        +
                                        +

                                        The Function class

                                        -
                                        +

                                        #include "llvm/Function.h"
                                        doxygen @@ -3726,7 +3728,6 @@

                                        Note that Function is a GlobalValue and therefore also a Constant. The value of the function is its address (after linking) which is guaranteed to be constant.

                                        -

                                        @@ -3735,7 +3736,7 @@

                                        -
                                        +
                                        +
                                        +

                                        The GlobalVariable class

                                        -
                                        +

                                        #include "llvm/GlobalVariable.h" @@ -3840,7 +3843,6 @@

                                        Constant), and if they have an initializer, they may be marked as "constant" themselves (indicating that their contents never change at runtime).

                                        -

                                        @@ -3849,7 +3851,7 @@

                                        -
                                        +
                                        • GlobalVariable(const Type *Ty, bool @@ -3887,13 +3889,14 @@

                                        +

                                        The BasicBlock class

                                        -
                                        +

                                        #include "llvm/BasicBlock.h"
                                        @@ -3918,8 +3921,6 @@

                                        like branches and can go in the switch tables. BasicBlocks have type label.

                                        -

                                        -

                                        @@ -3927,7 +3928,7 @@

                                        -
                                        +
                                        • BasicBlock(const std::string &Name = "",
                                        +

                                        The Argument class

                                        -
                                        +

                                        This subclass of Value defines the interface for incoming formal arguments to a function. A Function maintains a list of its formal @@ -3993,6 +3995,8 @@

                                        +
                                        +
                                        diff --git a/docs/Projects.html b/docs/Projects.html index 8ba87837649da..1ee53c05033c6 100644 --- a/docs/Projects.html +++ b/docs/Projects.html @@ -33,7 +33,7 @@

                                        Creating an LLVM Project

                                        Overview

                                        -
                                        +

                                        The LLVM build system is designed to facilitate the building of third party projects that use LLVM header files, libraries, and tools. In order to use @@ -78,7 +78,7 @@

                                        -
                                        +

                                        Follow these simple steps to start your project:

                                        @@ -150,7 +150,7 @@

                                        -
                                        +

                                        In order to use the LLVM build system, you will want to organize your source code so that it can benefit from the build system's features. @@ -235,21 +235,19 @@

                                        -
                                        +

                                        The LLVM build system provides a convenient way to build libraries and executables. Most of your project Makefiles will only need to define a few variables. Below is a list of the variables one can set and what they can do:

                                        -
                                        -

                                        Required Variables

                                        -
                                        +
                                        LEVEL @@ -267,7 +265,7 @@

                                        Variables for Building Subdirectories

                                        -
                                        +
                                        DIRS @@ -298,7 +296,7 @@

                                        Variables for Building Libraries

                                        -
                                        +
                                        LIBRARYNAME @@ -329,7 +327,7 @@

                                        Variables for Building Programs

                                        -
                                        +
                                        TOOLNAME @@ -372,7 +370,7 @@

                                        Miscellaneous Variables

                                        -
                                        +
                                        ExtraSource @@ -398,13 +396,15 @@

                                        +
                                        +

                                        Placement of Object Code

                                        -
                                        +

                                        The final location of built libraries and executables will depend upon whether you do a Debug, Release, or Profile build.

                                        @@ -432,7 +432,7 @@

                                        -
                                        +

                                        If you have any questions or need any help creating an LLVM project, the LLVM team would be more than happy to help. You can always post your diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index e4566179ea2b1..c9ae0202def4e 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -71,7 +71,7 @@

                                        Source Level Debugging with LLVM

                                        Introduction

                                        -
                                        +

                                        This document is the central repository for all information pertaining to debug information in LLVM. It describes the actual format @@ -80,14 +80,12 @@

                                        Introduction

                                        Further, this document provides specific examples of what debug information for C/C++ looks like.

                                        -
                                        -

                                        Philosophy behind LLVM debugging information

                                        -
                                        +

                                        The idea of the LLVM debugging information is to capture how the important pieces of the source-language's Abstract Syntax Tree map onto LLVM code. @@ -137,7 +135,7 @@

                                        Debug information consumers

                                        -
                                        +

                                        The role of debug information is to provide meta information normally stripped away during the compilation process. This meta information provides @@ -161,7 +159,7 @@

                                        Debugging optimized code

                                        -
                                        +

                                        An extremely high priority of LLVM debugging information is to make it interact well with optimizations and analysis. In particular, the LLVM debug @@ -226,13 +224,15 @@

                                        +
                                        +

                                        Debugging information format

                                        -
                                        +

                                        LLVM debugging information has been carefully designed to make it possible for the optimizer to optimize the program and debugging information without @@ -265,14 +265,12 @@

                                        common to any source-language. The next section describes the data layout conventions used by the C and C++ front-ends.

                                        -

                                        -

                                        Debug information descriptors

                                        -
                                        +

                                        In consideration of the complexity and volume of debug information, LLVM provides a specification for well formed debug descriptors.

                                        @@ -312,14 +310,12 @@

                                        The details of the various descriptors follow.

                                        -

                                        -

                                        Compile unit descriptors

                                        -
                                        +
                                        @@ -355,7 +351,7 @@ 

                                        File descriptors

                                        -
                                        +
                                        @@ -384,7 +380,7 @@ 

                                        Global variable descriptors

                                        -
                                        +
                                        @@ -417,7 +413,7 @@ 

                                        Subprogram descriptors

                                        -
                                        +
                                        @@ -461,7 +457,7 @@ 

                                        Block descriptors

                                        -
                                        +
                                        @@ -487,7 +483,7 @@ 

                                        Basic type descriptors

                                        -
                                        +
                                        @@ -539,7 +535,7 @@ 

                                        Derived type descriptors

                                        -
                                        +
                                        @@ -611,7 +607,7 @@ 

                                        Composite type descriptors

                                        -
                                        +
                                        @@ -698,7 +694,7 @@ 

                                        Subrange descriptors

                                        -
                                        +
                                        @@ -724,7 +720,7 @@ 

                                        Enumerator descriptors

                                        -
                                        +
                                        @@ -748,7 +744,7 @@ 

                                        Local variables

                                        -
                                        +
                                        @@ -787,24 +783,24 @@ 

                                        +
                                        +

                                        Debugger intrinsic functions

                                        -
                                        +

                                        LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to provide debug information at various points in generated code.

                                        -
                                        -

                                        llvm.dbg.declare

                                        -
                                        +
                                           void %llvm.dbg.declare(metadata, metadata)
                                         
                                        @@ -819,7 +815,7 @@

                                        llvm.dbg.value

                                        -
                                        +
                                           void %llvm.dbg.value(metadata, i64, metadata)
                                         
                                        @@ -831,12 +827,14 @@

                                        user source variable.

                                        +
                                        +

                                        Object lifetimes and scoping

                                        -
                                        +

                                        In many languages, the local variables in functions can have their lifetimes or scopes limited to a subset of a function. In the C family of languages, for example, variables are only live (readable and writable) within the @@ -994,13 +992,15 @@

                                        +
                                        +

                                        C/C++ front-end specific debug information

                                        -
                                        +

                                        The C and C++ front-ends represent information about the program in a format that is effectively identical @@ -1021,14 +1021,12 @@

                                        The following sections provide examples of various C/C++ constructs and the debug information that would best describe those constructs.

                                        -

                                        -

                                        C/C++ source file information

                                        -
                                        +

                                        Given the source files MySource.cpp and MyHeader.h located in the directory /Users/mine/sources, the following code:

                                        @@ -1106,7 +1104,7 @@

                                        C/C++ global variable information

                                        -
                                        +

                                        Given an integer global variable declared as follows:

                                        @@ -1176,7 +1174,7 @@

                                        C/C++ function information

                                        -
                                        +

                                        Given a function declared as follows:

                                        @@ -1233,18 +1231,16 @@

                                        C/C++ basic types

                                        -
                                        +

                                        The following are the basic type descriptors for C/C++ core types:

                                        -
                                        -

                                        bool

                                        -
                                        +
                                        @@ -1270,7 +1266,7 @@ 

                                        char

                                        -
                                        +
                                        @@ -1296,7 +1292,7 @@ 

                                        unsigned char

                                        -
                                        +
                                        @@ -1322,7 +1318,7 @@ 

                                        short

                                        -
                                        +
                                        @@ -1348,7 +1344,7 @@ 

                                        unsigned short

                                        -
                                        +
                                        @@ -1374,7 +1370,7 @@ 

                                        int

                                        -
                                        +
                                        @@ -1399,7 +1395,7 @@ 

                                        unsigned int

                                        -
                                        +
                                        @@ -1425,7 +1421,7 @@ 

                                        long long

                                        -
                                        +
                                        @@ -1451,7 +1447,7 @@ 

                                        unsigned long long

                                        -
                                        +
                                        @@ -1477,7 +1473,7 @@ 

                                        float

                                        -
                                        +
                                        @@ -1503,7 +1499,7 @@ 

                                        double

                                        -
                                        +
                                        @@ -1524,12 +1520,14 @@ 

                                        +
                                        +

                                        C/C++ derived types

                                        -
                                        +

                                        Given the following as an example of C/C++ derived type:

                                        @@ -1614,7 +1612,7 @@

                                        C/C++ struct/union types

                                        -
                                        +

                                        Given the following as an example of C/C++ struct type:

                                        @@ -1727,7 +1725,7 @@

                                        C/C++ enumeration types

                                        -
                                        +

                                        Given the following as an example of C/C++ enumeration type:

                                        @@ -1788,6 +1786,8 @@

                                        +
                                        +
                                        diff --git a/docs/SystemLibrary.html b/docs/SystemLibrary.html index db60a47138117..614737e9561bf 100644 --- a/docs/SystemLibrary.html +++ b/docs/SystemLibrary.html @@ -37,7 +37,7 @@

                                        System Library

                                        Abstract

                                        -
                                        +

                                        This document provides some details on LLVM's System Library, located in the source at lib/System and include/llvm/System. The library's purpose is to shield LLVM from the differences between operating @@ -66,17 +66,16 @@

                                        Abstract

                                        Keeping LLVM Portable

                                        -
                                        +

                                        In order to keep LLVM portable, LLVM developers should adhere to a set of portability rules associated with the System Library. Adherence to these rules should help the System Library achieve its goal of shielding LLVM from the variations in operating system interfaces and doing so efficiently. The following sections define the rules needed to fulfill this objective.

                                        -

                                        Don't Include System Headers

                                        -
                                        +

                                        Except in lib/System, no LLVM source code should directly #include a system header. Care has been taken to remove all such #includes from LLVM while lib/System was being @@ -91,7 +90,7 @@

                                        Don't Include System Headers

                                        Don't Expose System Headers

                                        -
                                        +

                                        The System Library must shield LLVM from all system headers. To obtain system level functionality, LLVM source must #include "llvm/System/Thing.h" and nothing else. This means that @@ -102,7 +101,7 @@

                                        Don't Expose System Headers

                                        Use Standard C Headers

                                        -
                                        +

                                        The standard C headers (the ones beginning with "c") are allowed to be exposed through the lib/System interface. These headers and the things they declare are considered to be platform agnostic. LLVM source @@ -112,7 +111,7 @@

                                        Use Standard C Headers

                                        Use Standard C++ Headers

                                        -
                                        +

                                        The standard C++ headers from the standard C++ library and standard template library may be exposed through the lib/System interface. These headers and the things they declare are considered to be @@ -122,7 +121,7 @@

                                        Use Standard C++ Headers

                                        High Level Interface

                                        -
                                        +

                                        The entry points specified in the interface of lib/System must be aimed at completing some reasonably high level task needed by LLVM. We do not want to simply wrap each operating system call. It would be preferable to wrap several @@ -141,7 +140,7 @@

                                        High Level Interface

                                        No Unused Functionality

                                        -
                                        +

                                        There must be no functionality specified in the interface of lib/System that isn't actually used by LLVM. We're not writing a general purpose operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM @@ -151,7 +150,7 @@

                                        No Unused Functionality

                                        No Duplicate Implementations

                                        -
                                        +

                                        The implementation of a function for a given platform must be written exactly once. This implies that it must be possible to apply a function's implementation to multiple operating systems if those operating systems can @@ -162,7 +161,7 @@

                                        No Duplicate Implementations

                                        No Virtual Methods

                                        -
                                        +

                                        The System Library interfaces can be called quite frequently by LLVM. In order to make those calls as efficient as possible, we discourage the use of virtual methods. There is no need to use inheritance for implementation @@ -172,7 +171,7 @@

                                        No Virtual Methods

                                        No Exposed Functions

                                        -
                                        +

                                        Any functions defined by system libraries (i.e. not defined by lib/System) must not be exposed through the lib/System interface, even if the header file for that function is not exposed. This prevents inadvertent use of system @@ -188,7 +187,7 @@

                                        No Exposed Functions

                                        No Exposed Data

                                        -
                                        +

                                        Any data defined by system libraries (i.e. not defined by lib/System) must not be exposed through the lib/System interface, even if the header file for that function is not exposed. As with functions, this prevents inadvertent use @@ -197,7 +196,7 @@

                                        No Exposed Data

                                        Minimize Soft Errors

                                        -
                                        +

                                        Operating system interfaces will generally provide error results for every little thing that could go wrong. In almost all cases, you can divide these error results into two groups: normal/good/soft and abnormal/bad/hard. That @@ -236,7 +235,7 @@

                                        Minimize Soft Errors

                                        No throw Specifications

                                        -
                                        +

                                        None of the lib/System interface functions may be declared with C++ throw() specifications on them. This requirement makes sure that the compiler does not insert additional exception handling code into the interface @@ -248,7 +247,7 @@

                                        No throw Specifications

                                        Code Organization

                                        -
                                        +

                                        Implementations of the System Library interface are separated by their general class of operating system. Currently only Unix and Win32 classes are defined but more could be added for other operating system classifications. @@ -277,7 +276,7 @@

                                        Code Organization

                                        Consistent Semantics

                                        -
                                        +

                                        The implementation of a lib/System interface can vary drastically between platforms. That's okay as long as the end result of the interface function is the same. For example, a function to create a directory is pretty straight @@ -292,11 +291,13 @@

                                        Consistent Semantics

                                        Bug 351

                                        -
                                        +

                                        See bug 351 for further details on the progress of this work

                                        +
                                        +
                                        diff --git a/docs/TableGenFundamentals.html b/docs/TableGenFundamentals.html index 7efdfbb7cec01..e8fca325130b5 100644 --- a/docs/TableGenFundamentals.html +++ b/docs/TableGenFundamentals.html @@ -9,7 +9,7 @@

                                        TableGen Fundamentals

                                        -
                                        +
                                        • Introduction
                                            @@ -53,7 +53,7 @@

                                            TableGen Fundamentals

                                            Introduction

                                            -
                                            +

                                            TableGen's purpose is to help a human develop and maintain records of domain-specific information. Because there may be a large number of these @@ -72,12 +72,10 @@

                                            Introduction

                                            llvm/utils/emacs and llvm/utils/vim directories of your LLVM distribution, respectively.

                                            -
                                            -

                                            Basic concepts

                                            -
                                            +

                                            TableGen files consist of two key parts: 'classes' and 'definitions', both of which are considered 'records'.

                                            @@ -114,7 +112,7 @@

                                            Basic concepts

                                            An example record

                                            -
                                            +

                                            With no other arguments, TableGen parses the specified file and prints out all of the classes, then all of the definitions. This is a good way to see what @@ -214,7 +212,7 @@

                                            An example record

                                            Running TableGen

                                            -
                                            +

                                            TableGen runs just like any other LLVM tool. The first (optional) argument specifies the file to read. If a filename is not specified, tblgen @@ -256,27 +254,28 @@

                                            Running TableGen

                                            +

                                            TableGen syntax

                                            -
                                            +

                                            TableGen doesn't care about the meaning of data (that is up to the backend to define), but it does care about syntax, and it enforces a simple type system. This section describes the syntax and the constructs allowed in a TableGen file.

                                            -
                                            -

                                            TableGen primitives

                                            +
                                            +

                                            TableGen comments

                                            -
                                            +

                                            TableGen supports BCPL style "//" comments, which run to the end of the line, and it also supports nestable "/* */" comments.

                                            @@ -288,7 +287,7 @@

                                            The TableGen type system

                                            -
                                            +

                                            TableGen files are strongly typed, in a simple (but complete) type-system. These types are used to perform automatic conversions, check for errors, and to @@ -348,7 +347,7 @@

                                            TableGen values and expressions

                                            -
                                            +

                                            TableGen allows for a pretty reasonable number of different expression forms when building up values. These forms allow the TableGen file to be written in a @@ -433,12 +432,14 @@

                                            +
                                            +

                                            Classes and definitions

                                            -
                                            +

                                            As mentioned in the intro, classes and definitions (collectively known as 'records') in TableGen are the main high-level unit of @@ -473,14 +474,12 @@

                                            permit the specification of default values for their subclasses, allowing the subclasses to override them as they wish.

                                            -

                                            -

                                            Value definitions

                                            -
                                            +

                                            Value definitions define named entries in records. A value must be defined before it can be referred to as the operand for another value definition or @@ -496,7 +495,7 @@

                                            'let' expressions

                                            -
                                            +

                                            A record-level let expression is used to change the value of a value definition in a record. This is primarily useful when a superclass defines a @@ -523,7 +522,7 @@

                                            Class template arguments

                                            -
                                            +

                                            TableGen permits the definition of parameterized classes as well as normal concrete classes. Parameterized TableGen classes specify a list of variable @@ -614,7 +613,7 @@

                                            Multiclass definitions and instances

                                            -
                                            +

                                            While classes with template arguments are a good way to factor commonality @@ -772,17 +771,21 @@

                                            +
                                            +

                                            File scope entities

                                            +
                                            +

                                            File inclusion

                                            -
                                            +

                                            TableGen supports the 'include' token, which textually substitutes the specified file in place of the include directive. The filename should be specified as a double quoted string immediately after the 'include' @@ -801,7 +804,7 @@

                                            'let' expressions

                                            -
                                            +

                                            "Let" expressions at file scope are similar to "let" expressions within a record, except they can specify a value binding for @@ -864,11 +867,15 @@

                                        +
                                        + +
                                        +

                                        Code Generator backend info

                                        -
                                        +

                                        Expressions used by code generator to describe instructions and isel patterns:

                                        @@ -885,7 +892,7 @@

                                        Code Generator backend info

                                        TableGen backends

                                        -
                                        +

                                        TODO: How they work, how to write one. This section should not contain details about any particular backend, except maybe -print-enums as an example. diff --git a/docs/TestingGuide.html b/docs/TestingGuide.html index 3d6aa92ffb161..12b29c9b36d57 100644 --- a/docs/TestingGuide.html +++ b/docs/TestingGuide.html @@ -55,7 +55,7 @@

                                        Overview

                                        -
                                        +

                                        This document is the reference manual for the LLVM testing infrastructure. It documents the structure of the LLVM testing infrastructure, the tools needed to @@ -67,7 +67,7 @@

                                        Overview

                                        Requirements

                                        -
                                        +

                                        In order to use the LLVM testing infrastructure, you will need all of the software required to build LLVM, as well @@ -79,7 +79,7 @@

                                        Requirements

                                        LLVM testing infrastructure organization

                                        -
                                        +

                                        The LLVM testing infrastructure contains two major categories of tests: regression tests and whole programs. The regression tests are contained inside @@ -89,13 +89,11 @@

                                        LLVM testing infrastructure organization

                                        in subversion.

                                        -
                                        -

                                        Regression tests

                                        -
                                        +

                                        The regression tests are small pieces of code that test a specific feature of LLVM or trigger a specific bug in LLVM. They are usually written in LLVM @@ -122,7 +120,7 @@

                                        Regression tests

                                        Test suite

                                        -
                                        +

                                        The test suite contains whole programs, which are pieces of code which can be compiled and linked into a stand-alone program that can be @@ -147,7 +145,7 @@

                                        Test suite

                                        Debugging Information tests

                                        -
                                        +

                                        The test suite contains tests to check quality of debugging information. The test are written in C based languages or in LLVM assembly language.

                                        @@ -159,11 +157,13 @@

                                        Debugging Information tests

                                        +
                                        +

                                        Quick start

                                        -
                                        +

                                        The tests are located in two separate Subversion modules. The regressions tests are in the main "llvm" module under the directory @@ -179,6 +179,7 @@

                                        Quick start

                                        Regression tests

                                        +

                                        To run all of the LLVM regression tests, use master Makefile in the llvm/test directory:

                                        @@ -238,10 +239,14 @@

                                        Regression tests

                                        For more information on using the 'lit' tool, see 'llvm-lit --help' or the 'lit' man page.

                                        +
                                        +

                                        Test suite

                                        +
                                        +

                                        To run the comprehensive test suite (tests that compile and execute whole programs), first checkout and setup the test-suite module:

                                        @@ -292,8 +297,9 @@

                                        Test suite

                                        Debugging Information tests

                                        +
                                        -
                                        +

                                        To run debugging information tests simply checkout the tests inside clang/test directory.

                                        @@ -309,10 +315,14 @@

                                        Debugging Information tests

                                        +
                                        + +
                                        +

                                        Regression test structure

                                        -
                                        +

                                        The LLVM regression tests are driven by 'lit' and are located in the llvm/test directory. @@ -334,12 +344,10 @@

                                        Regression test structure

                                      • Verifier: tests the IR verifier.
                                      -
                                      -

                                      Writing new regression tests

                                      -
                                      +

                                      The regression test structure is very simple, but does require some information to be set. This information is gathered via configure and is written to a file, lit.site.cfg @@ -494,7 +502,7 @@

                                      Writing new regression tests

                                      The FileCheck utility

                                      -
                                      +

                                      A powerful feature of the RUN: lines is that it allows any arbitrary commands to be executed as part of the test harness. While standard (portable) unix @@ -560,14 +568,12 @@

                                      The FileCheck utility

                                      that would not count: "grep subl" matches if subl exists anywhere in the file.

                                      -
                                      -

                                      The FileCheck -check-prefix option

                                      -
                                      +

                                      The FileCheck -check-prefix option allows multiple test configurations to be driven from one .ll file. This is useful in many circumstances, for example, @@ -602,7 +608,7 @@

                                      The "CHECK-NEXT:" directive

                                      -
                                      +

                                      Sometimes you want to match lines and would like to verify that matches happen on exactly consecutive lines with no other lines in between them. In @@ -643,7 +649,7 @@

                                      The "CHECK-NOT:" directive

                                      -
                                      +

                                      The CHECK-NOT: directive is used to verify that a string doesn't occur between two matches (or the first match and the beginning of the file). For @@ -674,7 +680,7 @@

                                      FileCheck Pattern Matching Syntax

                                      -
                                      +

                                      The CHECK: and CHECK-NOT: directives both take a pattern to match. For most uses of FileCheck, fixed string matching is perfectly sufficient. For some @@ -707,7 +713,7 @@

                                      FileCheck Variables

                                      -
                                      +

                                      It is often useful to match a pattern and then verify that it occurs again later in the file. For codegen tests, this can be useful to allow any register, @@ -742,10 +748,12 @@

                                      +
                                      +

                                      Variables and substitutions

                                      -
                                      +

                                      With a RUN line there are a number of substitutions that are permitted. In general, any Tcl variable that is available in the substitute function (in test/lib/llvm.exp) can be substituted into a RUN line. @@ -840,7 +848,7 @@

                                      Variables and substitutions

                                      Other Features

                                      -
                                      +

                                      To make RUN line writing easier, there are several shell scripts located in the llvm/test/Scripts directory. This directory is in the PATH when running tests, so you can just call these scripts using their name. For @@ -895,11 +903,13 @@

                                      Other Features

                                      +
                                      +

                                      Test suite Structure

                                      -
                                      +

                                      The test-suite module contains a number of programs that can be compiled with LLVM and executed. These programs are compiled using the native compiler @@ -967,7 +977,7 @@

                                      Test suite Structure

                                      Running the test suite

                                      -
                                      +

                                      First, all tests are executed within the LLVM object directory tree. They are not executed inside of the LLVM source tree. This is because the @@ -1022,15 +1032,13 @@

                                      Running the test suite

                                      have the suite checked out and configured, you don't need to do it again (unless the test code or configure script changes).

                                      -
                                      -

                                      Configuring External Tests

                                      -
                                      +

                                      In order to run the External tests in the test-suite module, you must specify --with-externals. This must be done during the re-configuration step (see above), @@ -1062,7 +1070,7 @@

                                      Running different tests

                                      -
                                      +

                                      In addition to the regular "whole program" tests, the test-suite module also provides a mechanism for compiling the programs in different ways. If the variable TEST is defined on the gmake command line, the test system will @@ -1086,7 +1094,7 @@

                                      Generating test output

                                      -
                                      +

                                      There are a number of ways to run the tests and generate output. The most simple one is simply running gmake with no arguments. This will compile and run all programs in the tree using a number of different methods @@ -1119,7 +1127,7 @@

                                      -
                                      +

                                      Assuming you can run the test suite, (e.g. "gmake TEST=nightly report" should work), it is really easy to run optimizations or code generator @@ -1185,6 +1193,8 @@

                                      +
                                      +
                                      diff --git a/docs/UsingLibraries.html b/docs/UsingLibraries.html index e8067ed0f8d83..2973452532960 100644 --- a/docs/UsingLibraries.html +++ b/docs/UsingLibraries.html @@ -31,7 +31,7 @@

                                      Using The LLVM Libraries

                                      Abstract

                                      -
                                      +

                                      Amongst other things, LLVM is a toolkit for building compilers, linkers, runtime executives, virtual machines, and other program execution related tools. In addition to the LLVM tool set, the functionality of LLVM is @@ -46,7 +46,7 @@

                                      Abstract

                                      Introduction

                                      -
                                      +

                                      If you're writing a compiler, virtual machine, or any other utility based on LLVM, you'll need to figure out which of the many libraries files you will need to link with to be successful. An understanding of the contents of these @@ -75,7 +75,7 @@

                                      Introduction

                                      Library Descriptions

                                      -
                                      +

                                      The table below categorizes each library @@ -153,7 +153,7 @@

                                      Library Descriptions

                                      Using llvm-config

                                      -
                                      +

                                      The llvm-config tool is a perl script that produces on its output various kinds of information. For example, the source or object directories used to build LLVM can be accessed by passing options to llvm-config. @@ -402,15 +402,14 @@

                                      Dependency Relationships Of Object Files

                                      Linkage Rules Of Thumb

                                      -
                                      +

                                      This section contains various "rules of thumb" about what files you should link into your programs.

                                      -

                                      Always Link LLVMCore, LLVMSupport, and LLVMSystem

                                      -
                                      +

                                      No matter what you do with LLVM, the last three entries in the value of your LLVMLIBS make variable should always be: LLVMCore LLVMSupport.a LLVMSystem.a. There are no LLVM @@ -420,13 +419,16 @@

                                      Never link both archive and re-linked library

                                      -
                                      +

                                      There is never any point to linking both the re-linked (.o) and the archive (.a) versions of a library. Since the re-linked version includes the entire library, the archive version will not resolve any symbols. You could even end up with link error if you place the archive version before the re-linked version on the linker's command line.

                                      + +
                                      +
                                      LibraryFormsDescription
                                      • LLVM Design
                                      • @@ -32,7 +31,6 @@

                                        Documentation for the LLVM System at SVN head

                                      -

                                      Written by The LLVM Team

                                      diff --git a/docs/tutorial/LangImpl1.html b/docs/tutorial/LangImpl1.html index cc2fa9735f357..2e1746f1a66cf 100644 --- a/docs/tutorial/LangImpl1.html +++ b/docs/tutorial/LangImpl1.html @@ -33,7 +33,7 @@

                                      Kaleidoscope: Tutorial Introduction and the Lexer

                                      Tutorial Introduction

                                      -
                                      +

                                      Welcome to the "Implementing a language with LLVM" tutorial. This tutorial runs through the implementation of a simple language, showing how fun and @@ -126,7 +126,7 @@

                                      Tutorial Introduction

                                      The Basic Language

                                      -
                                      +

                                      This tutorial will be illustrated with a toy language that we'll call "Kaleidoscope" (derived @@ -184,7 +184,7 @@

                                      The Basic Language

                                      The Lexer

                                      -
                                      +

                                      When it comes to implementing a language, the first thing needed is the ability to process a text file and recognize what it says. The traditional diff --git a/docs/tutorial/LangImpl2.html b/docs/tutorial/LangImpl2.html index bfe8d3fca0912..acccd20a09048 100644 --- a/docs/tutorial/LangImpl2.html +++ b/docs/tutorial/LangImpl2.html @@ -39,7 +39,7 @@

                                      Kaleidoscope: Implementing a Parser and AST

                                      Chapter 2 Introduction

                                      -
                                      +

                                      Welcome to Chapter 2 of the "Implementing a language with LLVM" tutorial. This chapter shows you how to use the lexer, built in @@ -64,7 +64,7 @@

                                      Chapter 2 Introduction

                                      The Abstract Syntax Tree (AST)

                                      -
                                      +

                                      The AST for a program captures its behavior in such a way that it is easy for later stages of the compiler (e.g. code generation) to interpret. We basically @@ -181,7 +181,7 @@

                                      The Abstract Syntax Tree (AST)

                                      Parser Basics

                                      -
                                      +

                                      Now that we have an AST to build, we need to define the parser code to build it. The idea here is that we want to parse something like "x+y" (which is @@ -242,7 +242,7 @@

                                      Parser Basics

                                      Basic Expression Parsing

                                      -
                                      +

                                      We start with numeric literals, because they are the simplest to process. For each production in our grammar, we'll define a function which parses that @@ -396,7 +396,7 @@

                                      Basic Expression Parsing

                                      Binary Expression Parsing

                                      -
                                      +

                                      Binary expressions are significantly harder to parse because they are often ambiguous. For example, when given the string "x+y*z", the parser can choose @@ -618,7 +618,7 @@

                                      Binary Expression Parsing

                                      Parsing the Rest

                                      -
                                      +

                                      The next thing missing is handling of function prototypes. In Kaleidoscope, @@ -715,7 +715,7 @@

                                      Parsing the Rest

                                      The Driver

                                      -
                                      +

                                      The driver for this simply invokes all of the parsing pieces with a top-level dispatch loop. There isn't much interesting here, so I'll just include the @@ -754,7 +754,7 @@

                                      The Driver

                                      Conclusions

                                      -
                                      +

                                      With just under 400 lines of commented code (240 lines of non-comment, non-blank code), we fully defined our minimal language, including a lexer, @@ -791,7 +791,7 @@

                                      Conclusions

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for this and the previous chapter. diff --git a/docs/tutorial/LangImpl3.html b/docs/tutorial/LangImpl3.html index 468a1bfe5ff1f..c9f4cee42a5bd 100644 --- a/docs/tutorial/LangImpl3.html +++ b/docs/tutorial/LangImpl3.html @@ -37,7 +37,7 @@

                                      Kaleidoscope: Code generation to LLVM IR

                                      Chapter 3 Introduction

                                      -
                                      +

                                      Welcome to Chapter 3 of the "Implementing a language with LLVM" tutorial. This chapter shows you how to transform the Chapter 3 Introduction

                                      Code Generation Setup

                                      -
                                      +

                                      In order to generate LLVM IR, we want some simple setup to get started. First @@ -150,7 +150,7 @@

                                      Code Generation Setup

                                      Expression Code Generation

                                      -
                                      +

                                      Generating LLVM code for expression nodes is very straightforward: less than 45 lines of commented code for all four of our expression nodes. First @@ -296,7 +296,7 @@

                                      Expression Code Generation

                                      Function Code Generation

                                      -
                                      +

                                      Code generation for prototypes and functions must handle a number of details, which make their code less beautiful than expression code @@ -518,7 +518,7 @@

                                      Function Code Generation

                                      Driver Changes and Closing Thoughts

                                      -
                                      +

                                      For now, code generation to LLVM doesn't really get us much, except that we can @@ -659,7 +659,7 @@

                                      Driver Changes and Closing Thoughts

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/LangImpl4.html b/docs/tutorial/LangImpl4.html index d73f8a351d8ec..fe54fb5c01f6b 100644 --- a/docs/tutorial/LangImpl4.html +++ b/docs/tutorial/LangImpl4.html @@ -36,7 +36,7 @@

                                      Kaleidoscope: Adding JIT and Optimizer Support

                                      Chapter 4 Introduction

                                      -
                                      +

                                      Welcome to Chapter 4 of the "Implementing a language with LLVM" tutorial. Chapters 1-3 described the implementation of a simple @@ -51,7 +51,7 @@

                                      Chapter 4 Introduction

                                      Trivial Constant Folding

                                      -
                                      +

                                      Our demonstration for Chapter 3 is elegant and easy to extend. Unfortunately, @@ -136,7 +136,7 @@

                                      Trivial Constant Folding

                                      LLVM Optimization Passes

                                      -
                                      +

                                      LLVM provides many optimization passes, which do many different sorts of things and have different tradeoffs. Unlike other systems, LLVM doesn't hold @@ -267,7 +267,7 @@

                                      LLVM Optimization Passes

                                      Adding a JIT Compiler

                                      -
                                      +

                                      Code that is available in LLVM IR can have a wide variety of tools applied to it. For example, you can run optimizations on it (as we did above), @@ -475,7 +475,7 @@

                                      Adding a JIT Compiler

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/LangImpl5.html b/docs/tutorial/LangImpl5.html index 4fbf7beca42bc..e46ded13ae53c 100644 --- a/docs/tutorial/LangImpl5.html +++ b/docs/tutorial/LangImpl5.html @@ -51,7 +51,7 @@

                                      Kaleidoscope: Extending the Language: Control Flow

                                      Chapter 5 Introduction

                                      -
                                      +

                                      Welcome to Chapter 5 of the "Implementing a language with LLVM" tutorial. Parts 1-4 described the implementation of the simple @@ -68,7 +68,7 @@

                                      Chapter 5 Introduction

                                      If/Then/Else

                                      -
                                      +

                                      Extending Kaleidoscope to support if/then/else is quite straightforward. It @@ -108,14 +108,12 @@

                                      If/Then/Else

                                      Now that we know what we "want", lets break this down into its constituent pieces.

                                      -
                                      -

                                      Lexer Extensions for If/Then/Else

                                      -
                                      +

                                      The lexer extensions are straightforward. First we add new enum values for the relevant tokens:

                                      @@ -148,7 +146,7 @@

                                      Lexer Extensions for If/Then/Else

                                      AST Extensions for If/Then/Else

                                      -
                                      +

                                      To represent the new expression we add a new AST node for it:

                                      @@ -173,7 +171,7 @@

                                      AST Extensions for If/Then/Else

                                      Parser Extensions for If/Then/Else

                                      -
                                      +

                                      Now that we have the relevant tokens coming from the lexer and we have the AST node to build, our parsing logic is relatively straightforward. First we @@ -231,7 +229,7 @@

                                      Parser Extensions for If/Then/Else

                                      LLVM IR for If/Then/Else

                                      -
                                      +

                                      Now that we have it parsing and building the AST, the final piece is adding LLVM code generation support. This is the most interesting part of the @@ -347,7 +345,7 @@

                                      LLVM IR for If/Then/Else

                                      Code Generation for If/Then/Else

                                      -
                                      +

                                      In order to generate code for this, we implement the Codegen method for IfExprAST:

                                      @@ -496,11 +494,13 @@

                                      Code Generation for If/Then/Else

                                      +
                                      +

                                      'for' Loop Expression

                                      -
                                      +

                                      Now that we know how to add basic control flow constructs to the language, we have the tools to add more powerful things. Lets add something more @@ -529,13 +529,11 @@

                                      'for' Loop Expression

                                      As before, lets talk about the changes that we need to Kaleidoscope to support this.

                                      -
                                      -

                                      Lexer Extensions for the 'for' Loop

                                      -
                                      +

                                      The lexer extensions are the same sort of thing as for if/then/else:

                                      @@ -564,7 +562,7 @@

                                      Lexer Extensions for the 'for' Loop

                                      AST Extensions for the 'for' Loop

                                      -
                                      +

                                      The AST node is just as simple. It basically boils down to capturing the variable name and the constituent expressions in the node.

                                      @@ -590,7 +588,7 @@

                                      AST Extensions for the 'for' Loop

                                      Parser Extensions for the 'for' Loop

                                      -
                                      +

                                      The parser code is also fairly standard. The only interesting thing here is handling of the optional step value. The parser code handles it by checking to @@ -649,7 +647,7 @@

                                      Parser Extensions for the 'for' Loop

                                      LLVM IR for the 'for' Loop

                                      -
                                      +

                                      Now we get to the good part: the LLVM IR we want to generate for this thing. With the simple example above, we get this LLVM IR (note that this dump is @@ -694,7 +692,7 @@

                                      LLVM IR for the 'for' Loop

                                      Code Generation for the 'for' Loop

                                      -
                                      +

                                      The first part of Codegen is very simple: we just output the start expression for the loop value:

                                      @@ -867,11 +865,13 @@

                                      Code Generation for the 'for' Loop

                                      +
                                      +

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/LangImpl6.html b/docs/tutorial/LangImpl6.html index 510d9dde09a97..39264cf830fbe 100644 --- a/docs/tutorial/LangImpl6.html +++ b/docs/tutorial/LangImpl6.html @@ -37,7 +37,7 @@

                                      Kaleidoscope: Extending the Language: User-defined Operators

                                      Chapter 6 Introduction

                                      -
                                      +

                                      Welcome to Chapter 6 of the "Implementing a language with LLVM" tutorial. At this point in our tutorial, we now have a fully @@ -63,7 +63,7 @@

                                      Chapter 6 Introduction

                                      User-defined Operators: the Idea

                                      -
                                      +

                                      The "operator overloading" that we will add to Kaleidoscope is more general than @@ -128,7 +128,7 @@

                                      User-defined Operators: the Idea

                                      User-defined Binary Operators

                                      -
                                      +

                                      Adding support for user-defined binary operators is pretty simple with our current framework. We'll first add support for the unary/binary keywords:

                                      @@ -345,7 +345,7 @@

                                      User-defined Binary Operators

                                      User-defined Unary Operators

                                      -
                                      +

                                      Since we don't currently support unary operators in the Kaleidoscope language, we'll need to add everything to support them. Above, we added simple @@ -494,7 +494,7 @@

                                      User-defined Unary Operators

                                      Kicking the Tires

                                      -
                                      +

                                      It is somewhat hard to believe, but with a few simple extensions we've covered in the last chapters, we have grown a real-ish language. With this, we @@ -799,7 +799,7 @@

                                      Kicking the Tires

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html index fc49d07047649..b2b26bdfa0708 100644 --- a/docs/tutorial/LangImpl7.html +++ b/docs/tutorial/LangImpl7.html @@ -41,7 +41,7 @@

                                      Kaleidoscope: Extending the Language: Mutable Variables

                                      Chapter 7 Introduction

                                      -
                                      +

                                      Welcome to Chapter 7 of the "Implementing a language with LLVM" tutorial. In chapters 1 through 6, we've built a very @@ -69,7 +69,7 @@

                                      Chapter 7 Introduction

                                      Why is this a hard problem?

                                      -
                                      +

                                      To understand why mutable variables cause complexities in SSA construction, @@ -143,7 +143,7 @@

                                      Why is this a hard problem?

                                      Memory in LLVM

                                      -
                                      +

                                      The 'trick' here is that while LLVM does require all register values to be in SSA form, it does not require (or permit) memory objects to be in SSA form. @@ -324,7 +324,7 @@

                                      Memory in LLVM

                                      Mutable Variables in Kaleidoscope

                                      -
                                      +

                                      Now that we know the sort of problem we want to tackle, lets see what this looks like in the context of our little Kaleidoscope language. We're going to @@ -380,7 +380,7 @@

                                      Mutable Variables in Kaleidoscope

                                      Adjusting Existing Variables for Mutation

                                      -
                                      +

                                      The symbol table in Kaleidoscope is managed at code generation time by the @@ -649,7 +649,7 @@

                                      Adjusting Existing Variables for Mutation

                                      New Assignment Operator

                                      -
                                      +

                                      With our current framework, adding a new assignment operator is really simple. We will parse it just like any other binary operator, but handle it @@ -746,7 +746,7 @@

                                      New Assignment Operator

                                      User-defined Local Variables

                                      -
                                      +

                                      Adding var/in is just like any other other extensions we made to Kaleidoscope: we extend the lexer, the parser, the AST and the code generator. @@ -979,7 +979,7 @@

                                      User-defined Local Variables

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with mutable diff --git a/docs/tutorial/LangImpl8.html b/docs/tutorial/LangImpl8.html index 449ac706620a7..eed8c03d21cac 100644 --- a/docs/tutorial/LangImpl8.html +++ b/docs/tutorial/LangImpl8.html @@ -45,7 +45,7 @@

                                      Kaleidoscope: Conclusion and other useful LLVM tidbits

                                      Tutorial Conclusion

                                      -
                                      +

                                      Welcome to the the final chapter of the "Implementing a language with LLVM" tutorial. In the course of this tutorial, we have grown @@ -156,18 +156,16 @@

                                      Tutorial Conclusion

                                      Properties of the LLVM IR

                                      -
                                      +

                                      We have a couple common questions about code in the LLVM IR form - lets just get these out of the way right now, shall we?

                                      -
                                      -

                                      Target Independence

                                      -
                                      +

                                      Kaleidoscope is an example of a "portable language": any program written in Kaleidoscope will work the same way on any target that it runs on. Many other @@ -221,7 +219,7 @@

                                      Target Independence

                                      Safety Guarantees

                                      -
                                      +

                                      Many of the languages above are also "safe" languages: it is impossible for a program written in Java to corrupt its address space and crash the process @@ -243,7 +241,7 @@

                                      Safety Guarantees

                                      Language-Specific Optimizations

                                      -
                                      +

                                      One thing about LLVM that turns off many people is that it does not solve all the world's problems in one system (sorry 'world hunger', someone else will have @@ -293,23 +291,23 @@

                                      Language-Specific Optimizations

                                      +
                                      +

                                      Tips and Tricks

                                      -
                                      +

                                      There is a variety of useful tips and tricks that you come to know after working on/with LLVM that aren't obvious at first glance. Instead of letting everyone rediscover them, this section talks about some of these issues.

                                      -
                                      -

                                      Implementing portable offsetof/sizeof

                                      -
                                      +

                                      One interesting thing that comes up, if you are trying to keep the code generated by your compiler "target independent", is that you often need to know @@ -329,7 +327,7 @@

                                      Implementing portable offsetof/sizeof

                                      Garbage Collected Stack Frames

                                      -
                                      +

                                      Some languages want to explicitly manage their stack frames, often so that they are garbage collected or to allow easy implementation of closures. There @@ -343,6 +341,8 @@

                                      Garbage Collected Stack Frames

                                      +
                                      +
                                      diff --git a/docs/tutorial/OCamlLangImpl1.html b/docs/tutorial/OCamlLangImpl1.html index 5446b7a729b2d..aa2bd8760043f 100644 --- a/docs/tutorial/OCamlLangImpl1.html +++ b/docs/tutorial/OCamlLangImpl1.html @@ -38,7 +38,7 @@

                                      Kaleidoscope: Tutorial Introduction and the Lexer

                                      Tutorial Introduction

                                      -
                                      +

                                      Welcome to the "Implementing a language with LLVM" tutorial. This tutorial runs through the implementation of a simple language, showing how fun and @@ -133,7 +133,7 @@

                                      Tutorial Introduction

                                      The Basic Language

                                      -
                                      +

                                      This tutorial will be illustrated with a toy language that we'll call "Kaleidoscope" (derived @@ -191,7 +191,7 @@

                                      The Basic Language

                                      The Lexer

                                      -
                                      +

                                      When it comes to implementing a language, the first thing needed is the ability to process a text file and recognize what it says. The traditional diff --git a/docs/tutorial/OCamlLangImpl2.html b/docs/tutorial/OCamlLangImpl2.html index deb592ee41135..20e006d97c8dd 100644 --- a/docs/tutorial/OCamlLangImpl2.html +++ b/docs/tutorial/OCamlLangImpl2.html @@ -43,7 +43,7 @@

                                      Kaleidoscope: Implementing a Parser and AST

                                      Chapter 2 Introduction

                                      -
                                      +

                                      Welcome to Chapter 2 of the "Implementing a language with LLVM in Objective Caml" tutorial. This chapter shows you how to use @@ -68,7 +68,7 @@

                                      Chapter 2 Introduction

                                      The Abstract Syntax Tree (AST)

                                      -
                                      +

                                      The AST for a program captures its behavior in such a way that it is easy for later stages of the compiler (e.g. code generation) to interpret. We basically @@ -149,7 +149,7 @@

                                      The Abstract Syntax Tree (AST)

                                      Parser Basics

                                      -
                                      +

                                      Now that we have an AST to build, we need to define the parser code to build it. The idea here is that we want to parse something like "x+y" (which is @@ -184,7 +184,7 @@

                                      Parser Basics

                                      Basic Expression Parsing

                                      -
                                      +

                                      We start with numeric literals, because they are the simplest to process. For each production in our grammar, we'll define a function which parses that @@ -305,7 +305,7 @@

                                      Basic Expression Parsing

                                      Binary Expression Parsing

                                      -
                                      +

                                      Binary expressions are significantly harder to parse because they are often ambiguous. For example, when given the string "x+y*z", the parser can choose @@ -518,7 +518,7 @@

                                      Binary Expression Parsing

                                      Parsing the Rest

                                      -
                                      +

                                      The next thing missing is handling of function prototypes. In Kaleidoscope, @@ -597,7 +597,7 @@

                                      Parsing the Rest

                                      The Driver

                                      -
                                      +

                                      The driver for this simply invokes all of the parsing pieces with a top-level dispatch loop. There isn't much interesting here, so I'll just include the @@ -653,7 +653,7 @@

                                      The Driver

                                      Conclusions

                                      -
                                      +

                                      With just under 300 lines of commented code (240 lines of non-comment, non-blank code), we fully defined our minimal language, including a lexer, @@ -690,7 +690,7 @@

                                      Conclusions

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for this and the previous chapter. diff --git a/docs/tutorial/OCamlLangImpl3.html b/docs/tutorial/OCamlLangImpl3.html index cf5afe9b71822..45ee6e9ffc31c 100644 --- a/docs/tutorial/OCamlLangImpl3.html +++ b/docs/tutorial/OCamlLangImpl3.html @@ -41,7 +41,7 @@

                                      Kaleidoscope: Code generation to LLVM IR

                                      Chapter 3 Introduction

                                      -
                                      +

                                      Welcome to Chapter 3 of the "Implementing a language with LLVM" tutorial. This chapter shows you how to transform the Chapter 3 Introduction

                                      Code Generation Setup

                                      -
                                      +

                                      In order to generate LLVM IR, we want some simple setup to get started. First @@ -131,7 +131,7 @@

                                      Code Generation Setup

                                      Expression Code Generation

                                      -
                                      +

                                      Generating LLVM code for expression nodes is very straightforward: less than 30 lines of commented code for all four of our expression nodes. First @@ -266,7 +266,7 @@

                                      Expression Code Generation

                                      Function Code Generation

                                      -
                                      +

                                      Code generation for prototypes and functions must handle a number of details, which make their code less beautiful than expression code @@ -469,7 +469,7 @@

                                      Function Code Generation

                                      Driver Changes and Closing Thoughts

                                      -
                                      +

                                      For now, code generation to LLVM doesn't really get us much, except that we can @@ -609,7 +609,7 @@

                                      Driver Changes and Closing Thoughts

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/OCamlLangImpl4.html b/docs/tutorial/OCamlLangImpl4.html index e42404561cc24..fd2b5ad7c8f84 100644 --- a/docs/tutorial/OCamlLangImpl4.html +++ b/docs/tutorial/OCamlLangImpl4.html @@ -40,7 +40,7 @@

                                      Kaleidoscope: Adding JIT and Optimizer Support

                                      Chapter 4 Introduction

                                      -
                                      +

                                      Welcome to Chapter 4 of the "Implementing a language with LLVM" tutorial. Chapters 1-3 described the implementation of a simple @@ -55,7 +55,7 @@

                                      Chapter 4 Introduction

                                      Trivial Constant Folding

                                      -
                                      +

                                      Note: the default IRBuilder now always includes the constant folding optimisations below.

                                      @@ -150,7 +150,7 @@

                                      Trivial Constant Folding

                                      LLVM Optimization Passes

                                      -
                                      +

                                      LLVM provides many optimization passes, which do many different sorts of things and have different tradeoffs. Unlike other systems, LLVM doesn't hold @@ -284,7 +284,7 @@

                                      LLVM Optimization Passes

                                      Adding a JIT Compiler

                                      -
                                      +

                                      Code that is available in LLVM IR can have a wide variety of tools applied to it. For example, you can run optimizations on it (as we did above), @@ -487,7 +487,7 @@

                                      Adding a JIT Compiler

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/OCamlLangImpl5.html b/docs/tutorial/OCamlLangImpl5.html index 59c17492a37e0..d356f126a4c1a 100644 --- a/docs/tutorial/OCamlLangImpl5.html +++ b/docs/tutorial/OCamlLangImpl5.html @@ -55,7 +55,7 @@

                                      Kaleidoscope: Extending the Language: Control Flow

                                      Chapter 5 Introduction

                                      -
                                      +

                                      Welcome to Chapter 5 of the "Implementing a language with LLVM" tutorial. Parts 1-4 described the implementation of the simple @@ -72,7 +72,7 @@

                                      Chapter 5 Introduction

                                      If/Then/Else

                                      -
                                      +

                                      Extending Kaleidoscope to support if/then/else is quite straightforward. It @@ -112,14 +112,12 @@

                                      If/Then/Else

                                      Now that we know what we "want", lets break this down into its constituent pieces.

                                      -
                                      -

                                      Lexer Extensions for If/Then/Else

                                      -
                                      +

                                      The lexer extensions are straightforward. First we add new variants for the relevant tokens:

                                      @@ -155,7 +153,7 @@

                                      Lexer Extensions for If/Then/Else

                                      AST Extensions for If/Then/Else

                                      -
                                      +

                                      To represent the new expression we add a new AST variant for it:

                                      @@ -176,7 +174,7 @@

                                      AST Extensions for If/Then/Else

                                      Parser Extensions for If/Then/Else

                                      -
                                      +

                                      Now that we have the relevant tokens coming from the lexer and we have the AST node to build, our parsing logic is relatively straightforward. First we @@ -214,7 +212,7 @@

                                      Parser Extensions for If/Then/Else

                                      LLVM IR for If/Then/Else

                                      -
                                      +

                                      Now that we have it parsing and building the AST, the final piece is adding LLVM code generation support. This is the most interesting part of the @@ -331,7 +329,7 @@

                                      LLVM IR for If/Then/Else

                                      Code Generation for If/Then/Else

                                      -
                                      +

                                      In order to generate code for this, we implement the Codegen method for IfExprAST:

                                      @@ -488,11 +486,13 @@

                                      Code Generation for If/Then/Else

                                      +
                                      +

                                      'for' Loop Expression

                                      -
                                      +

                                      Now that we know how to add basic control flow constructs to the language, we have the tools to add more powerful things. Lets add something more @@ -521,13 +521,11 @@

                                      'for' Loop Expression

                                      As before, lets talk about the changes that we need to Kaleidoscope to support this.

                                      -
                                      -

                                      Lexer Extensions for the 'for' Loop

                                      -
                                      +

                                      The lexer extensions are the same sort of thing as for if/then/else:

                                      @@ -557,7 +555,7 @@

                                      Lexer Extensions for the 'for' Loop

                                      AST Extensions for the 'for' Loop

                                      -
                                      +

                                      The AST variant is just as simple. It basically boils down to capturing the variable name and the constituent expressions in the node.

                                      @@ -577,7 +575,7 @@

                                      AST Extensions for the 'for' Loop

                                      Parser Extensions for the 'for' Loop

                                      -
                                      +

                                      The parser code is also fairly standard. The only interesting thing here is handling of the optional step value. The parser code handles it by checking to @@ -624,7 +622,7 @@

                                      Parser Extensions for the 'for' Loop

                                      LLVM IR for the 'for' Loop

                                      -
                                      +

                                      Now we get to the good part: the LLVM IR we want to generate for this thing. With the simple example above, we get this LLVM IR (note that this dump is @@ -669,7 +667,7 @@

                                      LLVM IR for the 'for' Loop

                                      Code Generation for the 'for' Loop

                                      -
                                      +

                                      The first part of Codegen is very simple: we just output the start expression for the loop value:

                                      @@ -842,11 +840,13 @@

                                      Code Generation for the 'for' Loop

                                      +
                                      +

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/OCamlLangImpl6.html b/docs/tutorial/OCamlLangImpl6.html index 693aafc0b3819..480aab38f3c48 100644 --- a/docs/tutorial/OCamlLangImpl6.html +++ b/docs/tutorial/OCamlLangImpl6.html @@ -41,7 +41,7 @@

                                      Kaleidoscope: Extending the Language: User-defined Operators

                                      Chapter 6 Introduction

                                      -
                                      +

                                      Welcome to Chapter 6 of the "Implementing a language with LLVM" tutorial. At this point in our tutorial, we now have a fully @@ -67,7 +67,7 @@

                                      Chapter 6 Introduction

                                      User-defined Operators: the Idea

                                      -
                                      +

                                      The "operator overloading" that we will add to Kaleidoscope is more general than @@ -132,7 +132,7 @@

                                      User-defined Operators: the Idea

                                      User-defined Binary Operators

                                      -
                                      +

                                      Adding support for user-defined binary operators is pretty simple with our current framework. We'll first add support for the unary/binary keywords:

                                      @@ -323,7 +323,7 @@

                                      User-defined Binary Operators

                                      User-defined Unary Operators

                                      -
                                      +

                                      Since we don't currently support unary operators in the Kaleidoscope language, we'll need to add everything to support them. Above, we added simple @@ -475,7 +475,7 @@

                                      User-defined Unary Operators

                                      Kicking the Tires

                                      -
                                      +

                                      It is somewhat hard to believe, but with a few simple extensions we've covered in the last chapters, we have grown a real-ish language. With this, we @@ -781,7 +781,7 @@

                                      Kicking the Tires

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with the diff --git a/docs/tutorial/OCamlLangImpl7.html b/docs/tutorial/OCamlLangImpl7.html index aebc81c08e738..51986b51a1166 100644 --- a/docs/tutorial/OCamlLangImpl7.html +++ b/docs/tutorial/OCamlLangImpl7.html @@ -45,7 +45,7 @@

                                      Kaleidoscope: Extending the Language: Mutable Variables

                                      Chapter 7 Introduction

                                      -
                                      +

                                      Welcome to Chapter 7 of the "Implementing a language with LLVM" tutorial. In chapters 1 through 6, we've built a very @@ -73,7 +73,7 @@

                                      Chapter 7 Introduction

                                      Why is this a hard problem?

                                      -
                                      +

                                      To understand why mutable variables cause complexities in SSA construction, @@ -147,7 +147,7 @@

                                      Why is this a hard problem?

                                      Memory in LLVM

                                      -
                                      +

                                      The 'trick' here is that while LLVM does require all register values to be in SSA form, it does not require (or permit) memory objects to be in SSA form. @@ -328,7 +328,7 @@

                                      Memory in LLVM

                                      Mutable Variables in Kaleidoscope

                                      -
                                      +

                                      Now that we know the sort of problem we want to tackle, lets see what this looks like in the context of our little Kaleidoscope language. We're going to @@ -384,7 +384,7 @@

                                      Mutable Variables in Kaleidoscope

                                      Adjusting Existing Variables for Mutation

                                      -
                                      +

                                      The symbol table in Kaleidoscope is managed at code generation time by the @@ -673,7 +673,7 @@

                                      Adjusting Existing Variables for Mutation

                                      New Assignment Operator

                                      -
                                      +

                                      With our current framework, adding a new assignment operator is really simple. We will parse it just like any other binary operator, but handle it @@ -774,7 +774,7 @@

                                      New Assignment Operator

                                      User-defined Local Variables

                                      -
                                      +

                                      Adding var/in is just like any other other extensions we made to Kaleidoscope: we extend the lexer, the parser, the AST and the code generator. @@ -956,7 +956,7 @@

                                      User-defined Local Variables

                                      Full Code Listing

                                      -
                                      +

                                      Here is the complete code listing for our running example, enhanced with mutable diff --git a/docs/tutorial/OCamlLangImpl8.html b/docs/tutorial/OCamlLangImpl8.html index 449ac706620a7..eed8c03d21cac 100644 --- a/docs/tutorial/OCamlLangImpl8.html +++ b/docs/tutorial/OCamlLangImpl8.html @@ -45,7 +45,7 @@

                                      Kaleidoscope: Conclusion and other useful LLVM tidbits

                                      Tutorial Conclusion

                                      -
                                      +

                                      Welcome to the the final chapter of the "Implementing a language with LLVM" tutorial. In the course of this tutorial, we have grown @@ -156,18 +156,16 @@

                                      Tutorial Conclusion

                                      Properties of the LLVM IR

                                      -
                                      +

                                      We have a couple common questions about code in the LLVM IR form - lets just get these out of the way right now, shall we?

                                      -
                                      -

                                      Target Independence

                                      -
                                      +

                                      Kaleidoscope is an example of a "portable language": any program written in Kaleidoscope will work the same way on any target that it runs on. Many other @@ -221,7 +219,7 @@

                                      Target Independence

                                      Safety Guarantees

                                      -
                                      +

                                      Many of the languages above are also "safe" languages: it is impossible for a program written in Java to corrupt its address space and crash the process @@ -243,7 +241,7 @@

                                      Safety Guarantees

                                      Language-Specific Optimizations

                                      -
                                      +

                                      One thing about LLVM that turns off many people is that it does not solve all the world's problems in one system (sorry 'world hunger', someone else will have @@ -293,23 +291,23 @@

                                      Language-Specific Optimizations

                                      +
                                      +

                                      Tips and Tricks

                                      -
                                      +

                                      There is a variety of useful tips and tricks that you come to know after working on/with LLVM that aren't obvious at first glance. Instead of letting everyone rediscover them, this section talks about some of these issues.

                                      -
                                      -

                                      Implementing portable offsetof/sizeof

                                      -
                                      +

                                      One interesting thing that comes up, if you are trying to keep the code generated by your compiler "target independent", is that you often need to know @@ -329,7 +327,7 @@

                                      Implementing portable offsetof/sizeof

                                      Garbage Collected Stack Frames

                                      -
                                      +

                                      Some languages want to explicitly manage their stack frames, often so that they are garbage collected or to allow easy implementation of closures. There @@ -343,6 +341,8 @@

                                      Garbage Collected Stack Frames

                                      +
                                      +