vim/YouCompleteMe
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Removing more llvm cruft files

Browse Source
This commit is contained in:
Strahinja Val Markovic 2012-07-05 20:58:10 -07:00
parent 1d1d72b039
commit 8da18e0319
578 changed files with 0 additions and 96931 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

268
cpp/llvm/Makefile
View File

@ -1,268 +0,0 @@
#===- ./Makefile -------------------------------------------*- Makefile -*--===#
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
#===------------------------------------------------------------------------===#
LEVEL := .
# Top-Level LLVM Build Stages:
# 1. Build lib/Support and lib/TableGen, which are used by utils (tblgen).
# 2. Build utils, which is used by VMCore.
# 3. Build VMCore, which builds the Intrinsics.inc file used by libs.
# 4. Build libs, which are needed by llvm-config.
# 5. Build llvm-config, which determines inter-lib dependencies for tools.
# 6. Build tools, runtime, docs.
#
# When cross-compiling, there are some things (tablegen) that need to
# be build for the build system first.
# If "RC_ProjectName" exists in the environment, and its value is
# "llvmCore", then this is an "Apple-style" build; search for
# "Apple-style" in the comments for more info. Anything else is a
# normal build.
ifneq ($(findstring llvmCore, $(RC_ProjectName)),llvmCore) # Normal build (not "Apple-style").
ifeq ($(BUILD_DIRS_ONLY),1)
DIRS := lib/Support lib/TableGen utils tools/llvm-config
OPTIONAL_DIRS := tools/clang/utils/TableGen
else
DIRS := lib/Support lib/TableGen utils lib/VMCore lib tools/llvm-shlib \
tools/llvm-config tools runtime docs unittests
OPTIONAL_DIRS := projects bindings
endif
ifeq ($(BUILD_EXAMPLES),1)
OPTIONAL_DIRS += examples
endif
EXTRA_DIST := test unittests llvm.spec include win32 Xcode
include $(LEVEL)/Makefile.config
ifneq ($(ENABLE_SHARED),1)
DIRS := $(filter-out tools/llvm-shlib, $(DIRS))
endif
ifneq ($(ENABLE_DOCS),1)
DIRS := $(filter-out docs, $(DIRS))
endif
ifeq ($(MAKECMDGOALS),libs-only)
DIRS := $(filter-out tools runtime docs, $(DIRS))
OPTIONAL_DIRS :=
endif
ifeq ($(MAKECMDGOALS),install-libs)
DIRS := $(filter-out tools runtime docs, $(DIRS))
OPTIONAL_DIRS := $(filter bindings, $(OPTIONAL_DIRS))
endif
ifeq ($(MAKECMDGOALS),tools-only)
DIRS := $(filter-out runtime docs, $(DIRS))
OPTIONAL_DIRS :=
endif
ifeq ($(MAKECMDGOALS),install-clang)
DIRS := tools/clang/tools/driver tools/clang/lib/Headers \
tools/clang/tools/libclang tools/clang/tools/c-index-test \
tools/clang/include/clang-c \
tools/clang/runtime tools/clang/docs \
tools/lto runtime
OPTIONAL_DIRS :=
NO_INSTALL = 1
endif
ifeq ($(MAKECMDGOALS),clang-only)
DIRS := $(filter-out tools docs unittests, $(DIRS)) \
tools/clang tools/lto
OPTIONAL_DIRS :=
endif
ifeq ($(MAKECMDGOALS),unittests)
DIRS := $(filter-out tools runtime docs, $(DIRS)) utils unittests
OPTIONAL_DIRS :=
endif
# Use NO_INSTALL define of the Makefile of each directory for deciding
# if the directory is installed or not
ifeq ($(MAKECMDGOALS),install)
OPTIONAL_DIRS := $(filter bindings, $(OPTIONAL_DIRS))
endif
# Don't build unittests when ONLY_TOOLS is set.
ifneq ($(ONLY_TOOLS),)
DIRS := $(filter-out unittests, $(DIRS))
endif
# If we're cross-compiling, build the build-hosted tools first
ifeq ($(LLVM_CROSS_COMPILING),1)
all:: cross-compile-build-tools
clean::
$(Verb) rm -rf BuildTools
cross-compile-build-tools:
$(Verb) if [ ! -f BuildTools/Makefile ]; then \
$(MKDIR) BuildTools; \
cd BuildTools ; \
unset CFLAGS ; \
unset CXXFLAGS ; \
$(PROJ_SRC_DIR)/configure --build=$(BUILD_TRIPLE) \
--host=$(BUILD_TRIPLE) --target=$(BUILD_TRIPLE) \
--disable-polly ; \
cd .. ; \
fi; \
(unset SDKROOT; \
$(MAKE) -C BuildTools \
BUILD_DIRS_ONLY=1 \
UNIVERSAL= \
TARGET_NATIVE_ARCH="$(TARGET_NATIVE_ARCH)" \
TARGETS_TO_BUILD="$(TARGETS_TO_BUILD)" \
ENABLE_OPTIMIZED=$(ENABLE_OPTIMIZED) \
ENABLE_PROFILING=$(ENABLE_PROFILING) \
ENABLE_COVERAGE=$(ENABLE_COVERAGE) \
DISABLE_ASSERTIONS=$(DISABLE_ASSERTIONS) \
ENABLE_EXPENSIVE_CHECKS=$(ENABLE_EXPENSIVE_CHECKS) \
ENABLE_LIBCPP=$(ENABLE_LIBCPP) \
CFLAGS= \
CXXFLAGS= \
) || exit 1;
endif
# Include the main makefile machinery.
include $(LLVM_SRC_ROOT)/Makefile.rules
# Specify options to pass to configure script when we're
# running the dist-check target
DIST_CHECK_CONFIG_OPTIONS = --with-llvmgccdir=$(LLVMGCCDIR)
.PHONY: debug-opt-prof
debug-opt-prof:
$(Echo) Building Debug Version
$(Verb) $(MAKE)
$(Echo)
$(Echo) Building Optimized Version
$(Echo)
$(Verb) $(MAKE) ENABLE_OPTIMIZED=1
$(Echo)
$(Echo) Building Profiling Version
$(Echo)
$(Verb) $(MAKE) ENABLE_PROFILING=1
dist-hook::
$(Echo) Eliminating files constructed by configure
$(Verb) $(RM) -f \
$(TopDistDir)/include/llvm/Config/config.h \
$(TopDistDir)/include/llvm/Support/DataTypes.h
clang-only: all
tools-only: all
libs-only: all
install-clang: install
install-libs: install
# If SHOW_DIAGNOSTICS is enabled, clear the diagnostics file first.
ifeq ($(SHOW_DIAGNOSTICS),1)
clean-diagnostics:
$(Verb) rm -f $(LLVM_OBJ_ROOT)/$(BuildMode)/diags
.PHONY: clean-diagnostics
all-local:: clean-diagnostics
endif
#------------------------------------------------------------------------
# Make sure the generated files are up-to-date. This must be kept in
# sync with the AC_CONFIG_HEADER and AC_CONFIG_FILE invocations in
# autoconf/configure.ac.
# Note that Makefile.config is covered by its own separate rule
# in Makefile.rules where it can be reused by sub-projects.
#------------------------------------------------------------------------
FilesToConfig := \
bindings/ocaml/llvm/META.llvm \
docs/doxygen.cfg \
llvm.spec \
include/llvm/Config/config.h \
include/llvm/Config/llvm-config.h \
include/llvm/Config/Targets.def \
include/llvm/Config/AsmPrinters.def \
include/llvm/Config/AsmParsers.def \
include/llvm/Config/Disassemblers.def \
include/llvm/Support/DataTypes.h
FilesToConfigPATH := $(addprefix $(LLVM_OBJ_ROOT)/,$(FilesToConfig))
all-local:: $(FilesToConfigPATH)
$(FilesToConfigPATH) : $(LLVM_OBJ_ROOT)/% : $(LLVM_SRC_ROOT)/%.in
$(Echo) Regenerating $*
$(Verb) cd $(LLVM_OBJ_ROOT) && $(ConfigStatusScript) $*
.PRECIOUS: $(FilesToConfigPATH)
# NOTE: This needs to remain as the last target definition in this file so
# that it gets executed last.
ifneq ($(BUILD_DIRS_ONLY),1)
all::
$(Echo) '*****' Completed $(BuildMode) Build
ifneq ($(ENABLE_OPTIMIZED),1)
$(Echo) '*****' Note: Debug build can be 10 times slower than an
$(Echo) '*****' optimized build. Use 'make ENABLE_OPTIMIZED=1' to
$(Echo) '*****' make an optimized build. Alternatively you can
$(Echo) '*****' configure with --enable-optimized.
ifeq ($(SHOW_DIAGNOSTICS),1)
$(Verb) if test -s $(LLVM_OBJ_ROOT)/$(BuildMode)/diags; then \
$(LLVM_SRC_ROOT)/utils/clang-parse-diagnostics-file -a \
$(LLVM_OBJ_ROOT)/$(BuildMode)/diags; \
fi
endif
endif
endif
check-llvm2cpp:
$(Verb)$(MAKE) check TESTSUITE=Feature RUNLLVM2CPP=1
srpm: $(LLVM_OBJ_ROOT)/llvm.spec
rpmbuild -bs $(LLVM_OBJ_ROOT)/llvm.spec
rpm: $(LLVM_OBJ_ROOT)/llvm.spec
rpmbuild -bb --target $(TARGET_TRIPLE) $(LLVM_OBJ_ROOT)/llvm.spec
show-footprint:
$(Verb) du -sk $(LibDir)
$(Verb) du -sk $(ToolDir)
$(Verb) du -sk $(ExmplDir)
$(Verb) du -sk $(ObjDir)
build-for-llvm-top:
$(Verb) if test ! -f ./config.status ; then \
./configure --prefix="$(LLVM_TOP)/install" \
--with-llvm-gcc="$(LLVM_TOP)/llvm-gcc" ; \
fi
$(Verb) $(MAKE) tools-only
SVN = svn
SVN-UPDATE-OPTIONS =
AWK = awk
SUB-SVN-DIRS = $(AWK) '/\?\ \ \ \ \ \ / {print $$2}' \
| LC_ALL=C xargs $(SVN) info 2>/dev/null \
| $(AWK) '/^Path:\ / {print $$2}'
update:
$(SVN) $(SVN-UPDATE-OPTIONS) update $(LLVM_SRC_ROOT)
@ $(SVN) status $(LLVM_SRC_ROOT) | $(SUB-SVN-DIRS) | xargs $(SVN) $(SVN-UPDATE-OPTIONS) update
happiness: update all check-all
.PHONY: srpm rpm update happiness
# declare all targets at this level to be serial:
.NOTPARALLEL:
else # Building "Apple-style."
# In an Apple-style build, once configuration is done, lines marked
# "Apple-style" are removed with sed! Please don't remove these!
# Look for the string "Apple-style" in utils/buildit/build_llvm.
include $(shell find . -name GNUmakefile) # Building "Apple-style."
endif # Building "Apple-style."

16
cpp/llvm/bindings/Makefile
View File

@ -1,16 +0,0 @@
##===- bindings/Makefile -----------------------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
LEVEL := ..
include $(LEVEL)/Makefile.config
PARALLEL_DIRS = $(BINDINGS_TO_BUILD)
include $(LEVEL)/Makefile.common

19
cpp/llvm/bindings/ocaml/Makefile
View File

@ -1,19 +0,0 @@
##===- bindings/ocaml/Makefile -----------------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
LEVEL := ../..
DIRS = llvm bitreader bitwriter analysis target executionengine transforms
ExtraMakefiles = $(PROJ_OBJ_DIR)/Makefile.ocaml
ocamldoc:
$(Verb) for i in $(DIRS) ; do \
$(MAKE) -C $$i ocamldoc; \
done
include $(LEVEL)/Makefile.common

19
cpp/llvm/bindings/ocaml/analysis/Makefile
View File

@ -1,19 +0,0 @@
##===- bindings/ocaml/analysis/Makefile --------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_analysis interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
LIBRARYNAME := llvm_analysis
UsedComponents := analysis
UsedOcamlInterfaces := llvm
include ../Makefile.ocaml

19
cpp/llvm/bindings/ocaml/bitreader/Makefile
View File

@ -1,19 +0,0 @@
##===- bindings/ocaml/bitreader/Makefile -------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_bitreader interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
LIBRARYNAME := llvm_bitreader
UsedComponents := bitreader
UsedOcamlInterfaces := llvm
include ../Makefile.ocaml

19
cpp/llvm/bindings/ocaml/bitwriter/Makefile
View File

@ -1,19 +0,0 @@
##===- bindings/ocaml/bitwriter/Makefile -------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_bitwriter interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
LIBRARYNAME := llvm_bitwriter
UsedComponents := bitwriter
UsedOcamlInterfaces := llvm
include ../Makefile.ocaml

19
cpp/llvm/bindings/ocaml/executionengine/Makefile
View File

@ -1,19 +0,0 @@
##===- bindings/ocaml/executionengine/Makefile --------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_executionengine interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
LIBRARYNAME := llvm_executionengine
UsedComponents := executionengine jit interpreter native
UsedOcamlInterfaces := llvm llvm_target
include ../Makefile.ocaml

42
cpp/llvm/bindings/ocaml/llvm/Makefile
View File

@ -1,42 +0,0 @@
##===- bindings/ocaml/llvm/Makefile ------------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
LIBRARYNAME := llvm
UsedComponents := core
UsedOcamLibs := llvm
include ../Makefile.ocaml
all-local:: copy-meta
install-local:: install-meta
uninstall-local:: uninstall-meta
DestMETA := $(PROJ_libocamldir)/META.llvm
# Easy way of generating META in the objdir
copy-meta: $(OcamlDir)/META.llvm
$(OcamlDir)/META.llvm: META.llvm
$(Verb) $(CP) -f $< $@
install-meta:: $(OcamlDir)/META.llvm
$(Echo) "Install $(BuildMode) $(DestMETA)"
$(Verb) $(MKDIR) $(PROJ_libocamldir)
$(Verb) $(DataInstall) $< "$(DestMETA)"
uninstall-meta::
$(Echo) "Uninstalling $(DestMETA)"
-$(Verb) $(RM) -f "$(DestMETA)"
.PHONY: copy-meta install-meta uninstall-meta

19
cpp/llvm/bindings/ocaml/target/Makefile
View File

@ -1,19 +0,0 @@
##===- bindings/ocaml/target/Makefile ----------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_target interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
LIBRARYNAME := llvm_target
UsedComponents := target
UsedOcamlInterfaces := llvm
include ../Makefile.ocaml

18
cpp/llvm/bindings/ocaml/transforms/Makefile
View File

@ -1,18 +0,0 @@
##===- bindings/ocaml/transforms/Makefile ------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../..
DIRS = scalar ipo
ocamldoc:
$(Verb) for i in $(DIRS) ; do \
$(MAKE) -C $$i ocamldoc; \
done
include $(LEVEL)/Makefile.common

20
cpp/llvm/bindings/ocaml/transforms/ipo/Makefile
View File

@ -1,20 +0,0 @@
##===- bindings/ocaml/transforms/scalar/Makefile -----------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_scalar_opts interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../../..
LIBRARYNAME := llvm_ipo
DONT_BUILD_RELINKED := 1
UsedComponents := ipo
UsedOcamlInterfaces := llvm
include ../../Makefile.ocaml

20
cpp/llvm/bindings/ocaml/transforms/scalar/Makefile
View File

@ -1,20 +0,0 @@
##===- bindings/ocaml/transforms/scalar/Makefile -----------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
#
# This is the makefile for the Objective Caml Llvm_scalar_opts interface.
#
##===----------------------------------------------------------------------===##
LEVEL := ../../../..
LIBRARYNAME := llvm_scalar_opts
DONT_BUILD_RELINKED := 1
UsedComponents := scalaropts
UsedOcamlInterfaces := llvm
include ../../Makefile.ocaml

1067
cpp/llvm/docs/AliasAnalysis.html
View File

File diff suppressed because it is too large Load Diff

569
cpp/llvm/docs/Atomics.html
View File

@ -1,569 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LLVM Atomic Instructions and Concurrency Guide</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>
LLVM Atomic Instructions and Concurrency Guide
</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#outsideatomic">Optimization outside atomic</a></li>
<li><a href="#atomicinst">Atomic instructions</a></li>
<li><a href="#ordering">Atomic orderings</a></li>
<li><a href="#iropt">Atomics and IR optimization</a></li>
<li><a href="#codegen">Atomics and Codegen</a></li>
</ol>
<div class="doc_author">
<p>Written by Eli Friedman</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="introduction">Introduction</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Historically, LLVM has not had very strong support for concurrency; some
minimal intrinsics were provided, and <code>volatile</code> was used in some
cases to achieve rough semantics in the presence of concurrency. However, this
is changing; there are now new instructions which are well-defined in the
presence of threads and asynchronous signals, and the model for existing
instructions has been clarified in the IR.</p>
<p>The atomic instructions are designed specifically to provide readable IR and
optimized code generation for the following:</p>
<ul>
<li>The new C++0x <code>&lt;atomic&gt;</code> header.
(<a href="http://www.open-std.org/jtc1/sc22/wg21/">C++0x draft available here</a>.)
(<a href="http://www.open-std.org/jtc1/sc22/wg14/">C1x draft available here</a>)</li>
<li>Proper semantics for Java-style memory, for both <code>volatile</code> and
regular shared variables.
(<a href="http://java.sun.com/docs/books/jls/third_edition/html/memory.html">Java Specification</a>)</li>
<li>gcc-compatible <code>__sync_*</code> builtins.
(<a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Description</a>)</li>
<li>Other scenarios with atomic semantics, including <code>static</code>
variables with non-trivial constructors in C++.</li>
</ul>
<p>Atomic and volatile in the IR are orthogonal; "volatile" is the C/C++
volatile, which ensures that every volatile load and store happens and is
performed in the stated order. A couple examples: if a
SequentiallyConsistent store is immediately followed by another
SequentiallyConsistent store to the same address, the first store can
be erased. This transformation is not allowed for a pair of volatile
stores. On the other hand, a non-volatile non-atomic load can be moved
across a volatile load freely, but not an Acquire load.</p>
<p>This document is intended to provide a guide to anyone either writing a
frontend for LLVM or working on optimization passes for LLVM with a guide
for how to deal with instructions with special semantics in the presence of
concurrency. This is not intended to be a precise guide to the semantics;
the details can get extremely complicated and unreadable, and are not
usually necessary.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="outsideatomic">Optimization outside atomic</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>The basic <code>'load'</code> and <code>'store'</code> allow a variety of
optimizations, but can lead to undefined results in a concurrent environment;
see <a href="#o_nonatomic">NonAtomic</a>. This section specifically goes
into the one optimizer restriction which applies in concurrent environments,
which gets a bit more of an extended description because any optimization
dealing with stores needs to be aware of it.</p>
<p>From the optimizer's point of view, the rule is that if there
are not any instructions with atomic ordering involved, concurrency does
not matter, with one exception: if a variable might be visible to another
thread or signal handler, a store cannot be inserted along a path where it
might not execute otherwise. Take the following example:</p>
<pre>
/* C code, for readability; run through clang -O2 -S -emit-llvm to get
equivalent IR */
int x;
void f(int* a) {
for (int i = 0; i &lt; 100; i++) {
if (a[i])
x += 1;
}
}
</pre>
<p>The following is equivalent in non-concurrent situations:</p>
<pre>
int x;
void f(int* a) {
int xtemp = x;
for (int i = 0; i &lt; 100; i++) {
if (a[i])
xtemp += 1;
}
x = xtemp;
}
</pre>
<p>However, LLVM is not allowed to transform the former to the latter: it could
indirectly introduce undefined behavior if another thread can access x at
the same time. (This example is particularly of interest because before the
concurrency model was implemented, LLVM would perform this
transformation.)</p>
<p>Note that speculative loads are allowed; a load which
is part of a race returns <code>undef</code>, but does not have undefined
behavior.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="atomicinst">Atomic instructions</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>For cases where simple loads and stores are not sufficient, LLVM provides
various atomic instructions. The exact guarantees provided depend on the
ordering; see <a href="#ordering">Atomic orderings</a></p>
<p><code>load atomic</code> and <code>store atomic</code> provide the same
basic functionality as non-atomic loads and stores, but provide additional
guarantees in situations where threads and signals are involved.</p>
<p><code>cmpxchg</code> and <code>atomicrmw</code> are essentially like an
atomic load followed by an atomic store (where the store is conditional for
<code>cmpxchg</code>), but no other memory operation can happen on any thread
between the load and store. Note that LLVM's cmpxchg does not provide quite
as many options as the C++0x version.</p>
<p>A <code>fence</code> provides Acquire and/or Release ordering which is not
part of another operation; it is normally used along with Monotonic memory
operations. A Monotonic load followed by an Acquire fence is roughly
equivalent to an Acquire load.</p>
<p>Frontends generating atomic instructions generally need to be aware of the
target to some degree; atomic instructions are guaranteed to be lock-free,
and therefore an instruction which is wider than the target natively supports
can be impossible to generate.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="ordering">Atomic orderings</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>In order to achieve a balance between performance and necessary guarantees,
there are six levels of atomicity. They are listed in order of strength;
each level includes all the guarantees of the previous level except for
Acquire/Release. (See also <a href="LangRef.html#ordering">LangRef</a>.)</p>
<!-- ======================================================================= -->
<h3>
<a name="o_notatomic">NotAtomic</a>
</h3>
<div>
<p>NotAtomic is the obvious, a load or store which is not atomic. (This isn't
really a level of atomicity, but is listed here for comparison.) This is
essentially a regular load or store. If there is a race on a given memory
location, loads from that location return undef.</p>
<dl>
<dt>Relevant standard</dt>
<dd>This is intended to match shared variables in C/C++, and to be used
in any other context where memory access is necessary, and
a race is impossible. (The precise definition is in
<a href="LangRef.html#memmodel">LangRef</a>.)
<dt>Notes for frontends</dt>
<dd>The rule is essentially that all memory accessed with basic loads and
stores by multiple threads should be protected by a lock or other
synchronization; otherwise, you are likely to run into undefined
behavior. If your frontend is for a "safe" language like Java,
use Unordered to load and store any shared variable. Note that NotAtomic
volatile loads and stores are not properly atomic; do not try to use
them as a substitute. (Per the C/C++ standards, volatile does provide
some limited guarantees around asynchronous signals, but atomics are
generally a better solution.)
<dt>Notes for optimizers</dt>
<dd>Introducing loads to shared variables along a codepath where they would
not otherwise exist is allowed; introducing stores to shared variables
is not. See <a href="#outsideatomic">Optimization outside
atomic</a>.</dd>
<dt>Notes for code generation</dt>
<dd>The one interesting restriction here is that it is not allowed to write
to bytes outside of the bytes relevant to a store. This is mostly
relevant to unaligned stores: it is not allowed in general to convert
an unaligned store into two aligned stores of the same width as the
unaligned store. Backends are also expected to generate an i8 store
as an i8 store, and not an instruction which writes to surrounding
bytes. (If you are writing a backend for an architecture which cannot
satisfy these restrictions and cares about concurrency, please send an
email to llvmdev.)</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="o_unordered">Unordered</a>
</h3>
<div>
<p>Unordered is the lowest level of atomicity. It essentially guarantees that
races produce somewhat sane results instead of having undefined behavior.
It also guarantees the operation to be lock-free, so it do not depend on
the data being part of a special atomic structure or depend on a separate
per-process global lock. Note that code generation will fail for
unsupported atomic operations; if you need such an operation, use explicit
locking.</p>
<dl>
<dt>Relevant standard</dt>
<dd>This is intended to match the Java memory model for shared
variables.</dd>
<dt>Notes for frontends</dt>
<dd>This cannot be used for synchronization, but is useful for Java and
other "safe" languages which need to guarantee that the generated
code never exhibits undefined behavior. Note that this guarantee
is cheap on common platforms for loads of a native width, but can
be expensive or unavailable for wider loads, like a 64-bit store
on ARM. (A frontend for Java or other "safe" languages would normally
split a 64-bit store on ARM into two 32-bit unordered stores.)
<dt>Notes for optimizers</dt>
<dd>In terms of the optimizer, this prohibits any transformation that
transforms a single load into multiple loads, transforms a store
into multiple stores, narrows a store, or stores a value which
would not be stored otherwise. Some examples of unsafe optimizations
are narrowing an assignment into a bitfield, rematerializing
a load, and turning loads and stores into a memcpy call. Reordering
unordered operations is safe, though, and optimizers should take
advantage of that because unordered operations are common in
languages that need them.</dd>
<dt>Notes for code generation</dt>
<dd>These operations are required to be atomic in the sense that if you
use unordered loads and unordered stores, a load cannot see a value
which was never stored. A normal load or store instruction is usually
sufficient, but note that an unordered load or store cannot
be split into multiple instructions (or an instruction which
does multiple memory operations, like <code>LDRD</code> on ARM).</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="o_monotonic">Monotonic</a>
</h3>
<div>
<p>Monotonic is the weakest level of atomicity that can be used in
synchronization primitives, although it does not provide any general
synchronization. It essentially guarantees that if you take all the
operations affecting a specific address, a consistent ordering exists.
<dl>
<dt>Relevant standard</dt>
<dd>This corresponds to the C++0x/C1x <code>memory_order_relaxed</code>;
see those standards for the exact definition.
<dt>Notes for frontends</dt>
<dd>If you are writing a frontend which uses this directly, use with caution.
The guarantees in terms of synchronization are very weak, so make
sure these are only used in a pattern which you know is correct.
Generally, these would either be used for atomic operations which
do not protect other memory (like an atomic counter), or along with
a <code>fence</code>.</dd>
<dt>Notes for optimizers</dt>
<dd>In terms of the optimizer, this can be treated as a read+write on the
relevant memory location (and alias analysis will take advantage of
that). In addition, it is legal to reorder non-atomic and Unordered
loads around Monotonic loads. CSE/DSE and a few other optimizations
are allowed, but Monotonic operations are unlikely to be used in ways
which would make those optimizations useful.</dd>
<dt>Notes for code generation</dt>
<dd>Code generation is essentially the same as that for unordered for loads
and stores. No fences are required. <code>cmpxchg</code> and
<code>atomicrmw</code> are required to appear as a single operation.</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="o_acquire">Acquire</a>
</h3>
<div>
<p>Acquire provides a barrier of the sort necessary to acquire a lock to access
other memory with normal loads and stores.
<dl>
<dt>Relevant standard</dt>
<dd>This corresponds to the C++0x/C1x <code>memory_order_acquire</code>. It
should also be used for C++0x/C1x <code>memory_order_consume</code>.
<dt>Notes for frontends</dt>
<dd>If you are writing a frontend which uses this directly, use with caution.
Acquire only provides a semantic guarantee when paired with a Release
operation.</dd>
<dt>Notes for optimizers</dt>
<dd>Optimizers not aware of atomics can treat this like a nothrow call.
It is also possible to move stores from before an Acquire load
or read-modify-write operation to after it, and move non-Acquire
loads from before an Acquire operation to after it.</dd>
<dt>Notes for code generation</dt>
<dd>Architectures with weak memory ordering (essentially everything relevant
today except x86 and SPARC) require some sort of fence to maintain
the Acquire semantics. The precise fences required varies widely by
architecture, but for a simple implementation, most architectures provide
a barrier which is strong enough for everything (<code>dmb</code> on ARM,
<code>sync</code> on PowerPC, etc.). Putting such a fence after the
equivalent Monotonic operation is sufficient to maintain Acquire
semantics for a memory operation.</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="o_acquire">Release</a>
</h3>
<div>
<p>Release is similar to Acquire, but with a barrier of the sort necessary to
release a lock.
<dl>
<dt>Relevant standard</dt>
<dd>This corresponds to the C++0x/C1x <code>memory_order_release</code>.</dd>
<dt>Notes for frontends</dt>
<dd>If you are writing a frontend which uses this directly, use with caution.
Release only provides a semantic guarantee when paired with a Acquire
operation.</dd>
<dt>Notes for optimizers</dt>
<dd>Optimizers not aware of atomics can treat this like a nothrow call.
It is also possible to move loads from after a Release store
or read-modify-write operation to before it, and move non-Release
stores from after an Release operation to before it.</dd>
<dt>Notes for code generation</dt>
<dd>See the section on Acquire; a fence before the relevant operation is
usually sufficient for Release. Note that a store-store fence is not
sufficient to implement Release semantics; store-store fences are
generally not exposed to IR because they are extremely difficult to
use correctly.</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="o_acqrel">AcquireRelease</a>
</h3>
<div>
<p>AcquireRelease (<code>acq_rel</code> in IR) provides both an Acquire and a
Release barrier (for fences and operations which both read and write memory).
<dl>
<dt>Relevant standard</dt>
<dd>This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.
<dt>Notes for frontends</dt>
<dd>If you are writing a frontend which uses this directly, use with caution.
Acquire only provides a semantic guarantee when paired with a Release
operation, and vice versa.</dd>
<dt>Notes for optimizers</dt>
<dd>In general, optimizers should treat this like a nothrow call; the
the possible optimizations are usually not interesting.</dd>
<dt>Notes for code generation</dt>
<dd>This operation has Acquire and Release semantics; see the sections on
Acquire and Release.</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="o_seqcst">SequentiallyConsistent</a>
</h3>
<div>
<p>SequentiallyConsistent (<code>seq_cst</code> in IR) provides
Acquire semantics for loads and Release semantics for
stores. Additionally, it guarantees that a total ordering exists
between all SequentiallyConsistent operations.
<dl>
<dt>Relevant standard</dt>
<dd>This corresponds to the C++0x/C1x <code>memory_order_seq_cst</code>,
Java volatile, and the gcc-compatible <code>__sync_*</code> builtins
which do not specify otherwise.
<dt>Notes for frontends</dt>
<dd>If a frontend is exposing atomic operations, these are much easier to
reason about for the programmer than other kinds of operations, and using
them is generally a practical performance tradeoff.</dd>
<dt>Notes for optimizers</dt>
<dd>Optimizers not aware of atomics can treat this like a nothrow call.
For SequentiallyConsistent loads and stores, the same reorderings are
allowed as for Acquire loads and Release stores, except that
SequentiallyConsistent operations may not be reordered.</dd>
<dt>Notes for code generation</dt>
<dd>SequentiallyConsistent loads minimally require the same barriers
as Acquire operations and SequentiallyConsistent stores require
Release barriers. Additionally, the code generator must enforce
ordering between SequentiallyConsistent stores followed by
SequentiallyConsistent loads. This is usually done by emitting
either a full fence before the loads or a full fence after the
stores; which is preferred varies by architecture.</dd>
</dl>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="iropt">Atomics and IR optimization</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Predicates for optimizer writers to query:
<ul>
<li>isSimple(): A load or store which is not volatile or atomic. This is
what, for example, memcpyopt would check for operations it might
transform.</li>
<li>isUnordered(): A load or store which is not volatile and at most
Unordered. This would be checked, for example, by LICM before hoisting
an operation.</li>
<li>mayReadFromMemory()/mayWriteToMemory(): Existing predicate, but note
that they return true for any operation which is volatile or at least
Monotonic.</li>
<li>Alias analysis: Note that AA will return ModRef for anything Acquire or
Release, and for the address accessed by any Monotonic operation.</li>
</ul>
<p>To support optimizing around atomic operations, make sure you are using
the right predicates; everything should work if that is done. If your
pass should optimize some atomic operations (Unordered operations in
particular), make sure it doesn't replace an atomic load or store with
a non-atomic operation.</p>
<p>Some examples of how optimizations interact with various kinds of atomic
operations:
<ul>
<li>memcpyopt: An atomic operation cannot be optimized into part of a
memcpy/memset, including unordered loads/stores. It can pull operations
across some atomic operations.
<li>LICM: Unordered loads/stores can be moved out of a loop. It just treats
monotonic operations like a read+write to a memory location, and anything
stricter than that like a nothrow call.
<li>DSE: Unordered stores can be DSE'ed like normal stores. Monotonic stores
can be DSE'ed in some cases, but it's tricky to reason about, and not
especially important.
<li>Folding a load: Any atomic load from a constant global can be
constant-folded, because it cannot be observed. Similar reasoning allows
scalarrepl with atomic loads and stores.
</ul>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="codegen">Atomics and Codegen</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Atomic operations are represented in the SelectionDAG with
<code>ATOMIC_*</code> opcodes. On architectures which use barrier
instructions for all atomic ordering (like ARM), appropriate fences are
split out as the DAG is built.</p>
<p>The MachineMemOperand for all atomic operations is currently marked as
volatile; this is not correct in the IR sense of volatile, but CodeGen
handles anything marked volatile very conservatively. This should get
fixed at some point.</p>
<p>Common architectures have some way of representing at least a pointer-sized
lock-free <code>cmpxchg</code>; such an operation can be used to implement
all the other atomic operations which can be represented in IR up to that
size. Backends are expected to implement all those operations, but not
operations which cannot be implemented in a lock-free manner. It is
expected that backends will give an error when given an operation which
cannot be implemented. (The LLVM code generator is not very helpful here
at the moment, but hopefully that will change.)</p>
<p>The implementation of atomics on LL/SC architectures (like ARM) is currently
a bit of a mess; there is a lot of copy-pasted code across targets, and
the representation is relatively unsuited to optimization (it would be nice
to be able to optimize loops involving cmpxchg etc.).</p>
<p>On x86, all atomic loads generate a <code>MOV</code>.
SequentiallyConsistent stores generate an <code>XCHG</code>, other stores
generate a <code>MOV</code>. SequentiallyConsistent fences generate an
<code>MFENCE</code>, other fences do not cause any code to be generated.
cmpxchg uses the <code>LOCK CMPXCHG</code> instruction.
<code>atomicrmw xchg</code> uses <code>XCHG</code>,
<code>atomicrmw add</code> and <code>atomicrmw sub</code> use
<code>XADD</code>, and all other <code>atomicrmw</code> operations generate
a loop with <code>LOCK CMPXCHG</code>. Depending on the users of the
result, some <code>atomicrmw</code> operations can be translated into
operations like <code>LOCK AND</code>, but that does not work in
general.</p>
<p>On ARM, MIPS, and many other RISC architectures, Acquire, Release, and
SequentiallyConsistent semantics require barrier instructions
for every such operation. Loads and stores generate normal instructions.
<code>cmpxchg</code> and <code>atomicrmw</code> can be represented using
a loop with LL/SC-style instructions which take some sort of exclusive
lock on a cache line (<code>LDREX</code> and <code>STREX</code> on
ARM, etc.). At the moment, the IR does not provide any way to represent a
weak <code>cmpxchg</code> which would not require a loop.</p>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-08-09 02:07:00 -0700 (Tue, 09 Aug 2011) $
</address>
</body>
</html>

1470
cpp/llvm/docs/BitCodeFormat.html
View File

File diff suppressed because it is too large Load Diff

164
cpp/llvm/docs/BranchWeightMetadata.html
View File

@ -1,164 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM Branch Weight Metadata</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>
LLVM Branch Weight Metadata
</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#supported_instructions">Supported Instructions</a></li>
<li><a href="#builtin_expect">Built-in "expect" Instruction </a></li>
<li><a href="#cfg_modifications">CFG Modifications</a></li>
</ol>
<div class="doc_author">
<p>Written by <a href="mailto:jstaszak@apple.com">Jakub Staszak</a></p>
</div>
<h2>
<a name="introduction">Introduction</a>
</h2>
<div>
<p>Branch Weight Metadata represents branch weights as its likeliness to
be taken. Metadata is assigned to the <tt>TerminatorInst</tt> as a
<tt>MDNode</tt> of the <tt>MD_prof</tt> kind. The first operator is always a
<tt>MDString</tt> node with the string "branch_weights". Number of operators
depends on the terminator type.</p>
<p>Branch weights might be fetch from the profiling file, or generated based on
<a href="#builtin_expect"><tt>__builtin_expect</tt></a> instruction.
</p>
<p>All weights are represented as an unsigned 32-bit values, where higher value
indicates greater chance to be taken.</p>
</div>
<h2>
<a name="supported_instructions">Supported Instructions</a>
</h2>
<div>
<h4>BranchInst</h4>
<div>
<p>Metadata is only assign to the conditional branches. There are two extra
operarands, for the true and the false branch.</p>
</div>
<div class="doc_code">
<pre>
!0 = metadata !{
metadata !"branch_weights",
i32 &lt;TRUE_BRANCH_WEIGHT&gt;,
i32 &lt;FALSE_BRANCH_WEIGHT&gt;
}
</pre>
</div>
<h4>SwitchInst</h4>
<div>
<p>Branch weights are assign to every case (including <tt>default</tt> case
which is always case #0).</p>
</div>
<div class="doc_code">
<pre>
!0 = metadata !{
metadata !"branch_weights",
i32 &lt;DEFAULT_BRANCH_WEIGHT&gt;
[ , i32 &lt;CASE_BRANCH_WEIGHT&gt; ... ]
}
</pre>
</div>
<h4>IndirectBrInst</h4>
<div>
<p>Branch weights are assign to every destination.</p>
</div>
<div class="doc_code">
<pre>
!0 = metadata !{
metadata !"branch_weights",
i32 &lt;LABEL_BRANCH_WEIGHT&gt;
[ , i32 &lt;LABEL_BRANCH_WEIGHT&gt; ... ]
}
</pre>
</div>
<h4>Other</h4>
<div>
<p>Other terminator instructions are not allowed to contain Branch Weight
Metadata.</p>
</div>
</div>
<h2>
<a name="builtin_expect">Built-in "expect" Instructions</a>
</h2>
<div>
<p><tt>__builtin_expect(long exp, long c)</tt> instruction provides branch
prediction information. The return value is the value of <tt>exp</tt>.</p>
<p>It is especially useful in conditional statements. Currently Clang supports
two conditional statements:
</p>
<h4><tt>if</tt> statement</h4>
<div>
<p>The <tt>exp</tt> parameter is the condition. The <tt>c</tt> parameter is
the expected comparision value. If it is equal to 1 (true), the condition is
likely to be true, in other case condition is likely to be false. For example:
</p>
</div>
<div class="doc_code">
<pre>
if (__builtin_expect(x &gt; 0, 1)) {
// This block is likely to be taken.
}
</pre>
</div>
<h4><tt>switch</tt> statement</h4>
<div>
<p>The <tt>exp</tt> parameter is the value. The <tt>c</tt> parameter is the
expected value. If the expected value doesn't show on the cases list, the
<tt>default</tt> case is assumed to be likely taken.</p>
</div>
<div class="doc_code">
<pre>
switch (__builtin_expect(x, 5)) {
default: break;
case 0: // ...
case 3: // ...
case 5: // This case is likely to be taken.
}
</pre>
</div>
</div>
<h2>
<a name="cfg_modifications">CFG Modifications</a>
</h2>
<div>
<p>Branch Weight Metatada is not proof against CFG changes. If terminator
operands' are changed some action should be taken. In other case some
misoptimizations may occur due to incorrent branch prediction information.</p>
</div>
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:jstaszak@apple.com">Jakub Staszak</a><br>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
</address>
</body>
</html>

239
cpp/llvm/docs/Bugpoint.html
View File

@ -1,239 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM bugpoint tool: design and usage</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<h1>
LLVM bugpoint tool: design and usage
</h1>
<ul>
<li><a href="#desc">Description</a></li>
<li><a href="#design">Design Philosophy</a>
<ul>
<li><a href="#autoselect">Automatic Debugger Selection</a></li>
<li><a href="#crashdebug">Crash debugger</a></li>
<li><a href="#codegendebug">Code generator debugger</a></li>
<li><a href="#miscompilationdebug">Miscompilation debugger</a></li>
</ul></li>
<li><a href="#advice">Advice for using <tt>bugpoint</tt></a></li>
</ul>
<div class="doc_author">
<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="desc">Description</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and
passes. It can be used to debug three types of failures: optimizer crashes,
miscompilations by optimizers, or bad native code generation (including problems
in the static and JIT compilers). It aims to reduce large test cases to small,
useful ones. For example, if <tt>opt</tt> crashes while optimizing a
file, it will identify the optimization (or combination of optimizations) that
causes the crash, and reduce the file down to a small example which triggers the
crash.</p>
<p>For detailed case scenarios, such as debugging <tt>opt</tt>,
<tt>llvm-ld</tt>, or one of the LLVM code generators, see <a
href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="design">Design Philosophy</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p><tt>bugpoint</tt> is designed to be a useful tool without requiring any
hooks into the LLVM infrastructure at all. It works with any and all LLVM
passes and code generators, and does not need to "know" how they work. Because
of this, it may appear to do stupid things or miss obvious
simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
time for computer time in the compiler-debugging process; consequently, it may
take a long period of (unattended) time to reduce a test case, but we feel it
is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
debugging a miscompilation where each test of the program (which requires
executing it) takes a long time.</p>
<!-- ======================================================================= -->
<h3>
<a name="autoselect">Automatic Debugger Selection</a>
</h3>
<div>
<p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on
the command line and links them together into a single module, called the test
program. If any LLVM passes are specified on the command line, it runs these
passes on the test program. If any of the passes crash, or if they produce
malformed output (which causes the verifier to abort), <tt>bugpoint</tt> starts
the <a href="#crashdebug">crash debugger</a>.</p>
<p>Otherwise, if the <tt>-output</tt> option was not specified,
<tt>bugpoint</tt> runs the test program with the C backend (which is assumed to
generate good code) to generate a reference output. Once <tt>bugpoint</tt> has
a reference output for the test program, it tries executing it with the
selected code generator. If the selected code generator crashes,
<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a> on the
code generator. Otherwise, if the resulting output differs from the reference
output, it assumes the difference resulted from a code generator failure, and
starts the <a href="#codegendebug">code generator debugger</a>.</p>
<p>Finally, if the output of the selected code generator matches the reference
output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
have been applied to it. If its output differs from the reference output, it
assumes the difference resulted from a failure in one of the LLVM passes, and
enters the <a href="#miscompilationdebug">miscompilation debugger</a>.
Otherwise, there is no problem <tt>bugpoint</tt> can debug.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="crashdebug">Crash debugger</a>
</h3>
<div>
<p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard
as it can to reduce the list of passes (for optimizer crashes) and the size of
the test program. First, <tt>bugpoint</tt> figures out which combination of
optimizer passes triggers the bug. This is useful when debugging a problem
exposed by <tt>opt</tt>, for example, because it runs over 38 passes.</p>
<p>Next, <tt>bugpoint</tt> tries removing functions from the test program, to
reduce its size. Usually it is able to reduce a test program to a single
function, when debugging intraprocedural optimizations. Once the number of
functions has been reduced, it attempts to delete various edges in the control
flow graph, to reduce the size of the function as much as possible. Finally,
<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
passes crash, give you a bitcode file, and give you instructions on how to
reproduce the failure with <tt>opt</tt> or <tt>llc</tt>.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="codegendebug">Code generator debugger</a>
</h3>
<div>
<p>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
test program and partitions it into two pieces: one piece which it compiles
with the C backend (into a shared object), and one piece which it runs with
either the JIT or the static LLC compiler. It uses several techniques to
reduce the amount of code pushed through the LLVM code generator, to reduce the
potential scope of the problem. After it is finished, it emits two bitcode
files (called "test" [to be compiled with the code generator] and "safe" [to be
compiled with the C backend], respectively), and instructions for reproducing
the problem. The code generator debugger assumes that the C backend produces
good code.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="miscompilationdebug">Miscompilation debugger</a>
</h3>
<div>
<p>The miscompilation debugger works similarly to the code generator debugger.
It works by splitting the test program into two pieces, running the
optimizations specified on one piece, linking the two pieces back together, and
then executing the result. It attempts to narrow down the list of passes to
the one (or few) which are causing the miscompilation, then reduce the portion
of the test program which is being miscompiled. The miscompilation debugger
assumes that the selected code generator is working properly.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="advice">Advice for using bugpoint</a>
</h2>
<!-- *********************************************************************** -->
<div>
<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
non-obvious ways. Here are some hints and tips:<p>
<ol>
<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
works with programs that have deterministic output. Thus, if the program
outputs <tt>argv[0]</tt>, the date, time, or any other "random" data,
<tt>bugpoint</tt> may misinterpret differences in these data, when output,
as the result of a miscompilation. Programs should be temporarily modified
to disable outputs that are likely to vary from run to run.
<li>In the code generator and miscompilation debuggers, debugging will go
faster if you manually modify the program or its inputs to reduce the
runtime, but still exhibit the problem.
<li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
it helps track down regressions quickly. To avoid having to relink
<tt>bugpoint</tt> every time you change your optimization however, have
<tt>bugpoint</tt> dynamically load your optimization with the
<tt>-load</tt> option.
<li><p><tt>bugpoint</tt> can generate a lot of output and run for a long period
of time. It is often useful to capture the output of the program to file.
For example, in the C shell, you can run:</p>
<div class="doc_code">
<p><tt>bugpoint ... |&amp; tee bugpoint.log</tt></p>
</div>
<p>to get a copy of <tt>bugpoint</tt>'s output in the file
<tt>bugpoint.log</tt>, as well as on your terminal.</p>
<li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
<tt>bugpoint</tt> crashes before you see its "All input ok" message,
you might try <tt>llvm-link -v</tt> on the same set of input files. If
that also crashes, you may be experiencing a linker bug.
<li><tt>bugpoint</tt> is useful for proactively finding bugs in LLVM.
Invoking <tt>bugpoint</tt> with the <tt>-find-bugs</tt> option will cause
the list of specified optimizations to be randomized and applied to the
program. This process will repeat until a bug is found or the user
kills <tt>bugpoint</tt>.
</ol>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

584
cpp/llvm/docs/CMake.html
View File

@ -1,584 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Building LLVM with CMake</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<h1>
Building LLVM with CMake
</h1>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#quickstart">Quick start</a></li>
<li><a href="#usage">Basic CMake usage</a>
<li><a href="#options">Options and variables</a>
<ul>
<li><a href="#freccmake">Frequently-used CMake variables</a></li>
<li><a href="#llvmvars">LLVM-specific variables</a></li>
</ul></li>
<li><a href="#testing">Executing the test suite</a>
<li><a href="#cross">Cross compiling</a>
<li><a href="#embedding">Embedding LLVM in your project</a>
<ul>
<li><a href="#passdev">Developing LLVM pass out of source</a></li>
</ul></li>
<li><a href="#specifics">Compiler/Platform specific topics</a>
<ul>
<li><a href="#msvc">Microsoft Visual C++</a></li>
</ul></li>
</ul>
<div class="doc_author">
<p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="intro">Introduction</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p><a href="http://www.cmake.org/">CMake</a> is a cross-platform
build-generator tool. CMake does not build the project, it generates
the files needed by your build tool (GNU make, Visual Studio, etc) for
building LLVM.</p>
<p>If you are really anxious about getting a functional LLVM build,
go to the <a href="#quickstart">Quick start</a> section. If you
are a CMake novice, start on <a href="#usage">Basic CMake
usage</a> and then go back to the <a href="#quickstart">Quick
start</a> once you know what you are
doing. The <a href="#options">Options and variables</a> section
is a reference for customizing your build. If you already have
experience with CMake, this is the recommended starting point.
</div>
<!-- *********************************************************************** -->
<h2>
<a name="quickstart">Quick start</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p> We use here the command-line, non-interactive CMake interface </p>
<ol>
<li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a>
and install CMake. Version 2.8 is the minimum required.</p>
<li><p>Open a shell. Your development tools must be reachable from this
shell through the PATH environment variable.</p>
<li><p>Create a directory for containing the build. It is not
supported to build LLVM on the source directory. cd to this
directory:</p>
<div class="doc_code">
<p><tt>mkdir mybuilddir</tt></p>
<p><tt>cd mybuilddir</tt></p>
</div>
<li><p>Execute this command on the shell
replacing <i>path/to/llvm/source/root</i> with the path to the
root of your LLVM source tree:</p>
<div class="doc_code">
<p><tt>cmake path/to/llvm/source/root</tt></p>
</div>
<p>CMake will detect your development environment, perform a
series of test and generate the files required for building
LLVM. CMake will use default values for all build
parameters. See the <a href="#options">Options and variables</a>
section for fine-tuning your build</p>
<p>This can fail if CMake can't detect your toolset, or if it
thinks that the environment is not sane enough. On this case
make sure that the toolset that you intend to use is the only
one reachable from the shell and that the shell itself is the
correct one for you development environment. CMake will refuse
to build MinGW makefiles if you have a POSIX shell reachable
through the PATH environment variable, for instance. You can
force CMake to use a given build tool, see
the <a href="#usage">Usage</a> section.</p>
</ol>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="usage">Basic CMake usage</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>This section explains basic aspects of CMake, mostly for
explaining those options which you may need on your day-to-day
usage.</p>
<p>CMake comes with extensive documentation in the form of html
files and on the cmake executable itself. Execute <i>cmake
--help</i> for further help options.</p>
<p>CMake requires to know for which build tool it shall generate
files (GNU make, Visual Studio, Xcode, etc). If not specified on
the command line, it tries to guess it based on you
environment. Once identified the build tool, CMake uses the
corresponding <i>Generator</i> for creating files for your build
tool. You can explicitly specify the generator with the command
line option <i>-G "Name of the generator"</i>. For knowing the
available generators on your platform, execute</p>
<div class="doc_code">
<p><tt>cmake --help</tt></p>
</div>
<p>This will list the generator's names at the end of the help
text. Generator's names are case-sensitive. Example:</p>
<div class="doc_code">
<p><tt>cmake -G "Visual Studio 9 2008" path/to/llvm/source/root</tt></p>
</div>
<p>For a given development platform there can be more than one
adequate generator. If you use Visual Studio "NMake Makefiles"
is a generator you can use for building with NMake. By default,
CMake chooses the more specific generator supported by your
development environment. If you want an alternative generator,
you must tell this to CMake with the <i>-G</i> option.</p>
<p>TODO: explain variables and cache. Move explanation here from
#options section.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="options">Options and variables</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Variables customize how the build will be generated. Options are
boolean variables, with possible values ON/OFF. Options and
variables are defined on the CMake command line like this:</p>
<div class="doc_code">
<p><tt>cmake -DVARIABLE=value path/to/llvm/source</tt></p>
</div>
<p>You can set a variable after the initial CMake invocation for
changing its value. You can also undefine a variable:</p>
<div class="doc_code">
<p><tt>cmake -UVARIABLE path/to/llvm/source</tt></p>
</div>
<p>Variables are stored on the CMake cache. This is a file
named <tt>CMakeCache.txt</tt> on the root of the build
directory. Do not hand-edit it.</p>
<p>Variables are listed here appending its type after a colon. It is
correct to write the variable and the type on the CMake command
line:</p>
<div class="doc_code">
<p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="freccmake">Frequently-used CMake variables</a>
</h3>
<div>
<p>Here are listed some of the CMake variables that are used often,
along with a brief explanation and LLVM-specific notes. For full
documentation, check the CMake docs or execute <i>cmake
--help-variable VARIABLE_NAME</i>.</p>
<dl>
<dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt>
<dd>Sets the build type for <i>make</i> based generators. Possible
values are Release, Debug, RelWithDebInfo and MinSizeRel. On
systems like Visual Studio the user sets the build type with the IDE
settings.</dd>
<dt><b>CMAKE_INSTALL_PREFIX</b>:PATH</dt>
<dd>Path where LLVM will be installed if "make install" is invoked
or the "INSTALL" target is built.</dd>
<dt><b>LLVM_LIBDIR_SUFFIX</b>:STRING</dt>
<dd>Extra suffix to append to the directory where libraries are to
be installed. On a 64-bit architecture, one could use
-DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.</dd>
<dt><b>CMAKE_C_FLAGS</b>:STRING</dt>
<dd>Extra flags to use when compiling C source files.</dd>
<dt><b>CMAKE_CXX_FLAGS</b>:STRING</dt>
<dd>Extra flags to use when compiling C++ source files.</dd>
<dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt>
<dd>Flag indicating is shared libraries will be built. Its default
value is OFF. Shared libraries are not supported on Windows and
not recommended in the other OSes.</dd>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="llvmvars">LLVM-specific variables</a>
</h3>
<div>
<dl>
<dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
<dd>Semicolon-separated list of targets to build, or <i>all</i> for
building all targets. Case-sensitive. For Visual C++ defaults
to <i>X86</i>. On the other cases defaults to <i>all</i>. Example:
<i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"</i>.</dd>
<dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt>
<dd>Build LLVM tools. Defaults to ON. Targets for building each tool
are generated in any case. You can build an tool separately by
invoking its target. For example, you can build <i>llvm-as</i>
with a makefile-based system executing <i>make llvm-as</i> on the
root of your build directory.</dd>
<dt><b>LLVM_INCLUDE_TOOLS</b>:BOOL</dt>
<dd>Generate build targets for the LLVM tools. Defaults to
ON. You can use that option for disabling the generation of build
targets for the LLVM tools.</dd>
<dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt>
<dd>Build LLVM examples. Defaults to OFF. Targets for building each
example are generated in any case. See documentation
for <i>LLVM_BUILD_TOOLS</i> above for more details.</dd>
<dt><b>LLVM_INCLUDE_EXAMPLES</b>:BOOL</dt>
<dd>Generate build targets for the LLVM examples. Defaults to
ON. You can use that option for disabling the generation of build
targets for the LLVM examples.</dd>
<dt><b>LLVM_BUILD_TESTS</b>:BOOL</dt>
<dd>Build LLVM unit tests. Defaults to OFF. Targets for building
each unit test are generated in any case. You can build a specific
unit test with the target <i>UnitTestNameTests</i> (where at this
time <i>UnitTestName</i> can be ADT, Analysis, ExecutionEngine,
JIT, Support, Transform, VMCore; see the subdirectories
of <i>unittests</i> for an updated list.) It is possible to build
all unit tests with the target <i>UnitTests</i>.</dd>
<dt><b>LLVM_INCLUDE_TESTS</b>:BOOL</dt>
<dd>Generate build targets for the LLVM unit tests. Defaults to
ON. You can use that option for disabling the generation of build
targets for the LLVM unit tests.</dd>
<dt><b>LLVM_APPEND_VC_REV</b>:BOOL</dt>
<dd>Append version control revision info (svn revision number or git
revision id) to LLVM version string (stored in the PACKAGE_VERSION
macro). For this to work cmake must be invoked before the
build. Defaults to OFF.</dd>
<dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt>
<dd>Build with threads support, if available. Defaults to ON.</dd>
<dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt>
<dd>Enables code assertions. Defaults to OFF if and only if
CMAKE_BUILD_TYPE is <i>Release</i>.</dd>
<dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
<dd>Add the <i>-fPIC</i> flag for the compiler command-line, if the
compiler supports this flag. Some systems, like Windows, do not
need this flag. Defaults to ON.</dd>
<dt><b>LLVM_ENABLE_WARNINGS</b>:BOOL</dt>
<dd>Enable all compiler warnings. Defaults to ON.</dd>
<dt><b>LLVM_ENABLE_PEDANTIC</b>:BOOL</dt>
<dd>Enable pedantic mode. This disable compiler specific extensions, is
possible. Defaults to ON.</dd>
<dt><b>LLVM_ENABLE_WERROR</b>:BOOL</dt>
<dd>Stop and fail build, if a compiler warning is
triggered. Defaults to OFF.</dd>
<dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
<dd>Build 32-bits executables and libraries on 64-bits systems. This
option is available only on some 64-bits unix systems. Defaults to
OFF.</dd>
<dt><b>LLVM_TARGET_ARCH</b>:STRING</dt>
<dd>LLVM target to use for native code generation. This is required
for JIT generation. It defaults to "host", meaning that it shall
pick the architecture of the machine where LLVM is being built. If
you are cross-compiling, set it to the target architecture
name.</dd>
<dt><b>LLVM_TABLEGEN</b>:STRING</dt>
<dd>Full path to a native TableGen executable (usually
named <i>tblgen</i>). This is intented for cross-compiling: if the
user sets this variable, no native TableGen will be created.</dd>
<dt><b>LLVM_LIT_ARGS</b>:STRING</dt>
<dd>Arguments given to lit.
<tt>make check</tt> and <tt>make clang-test</tt> are affected.
By default, <tt>&quot;-sv --no-progress-bar&quot;</tt>
on Visual C++ and Xcode,
<tt>&quot;-sv&quot;</tt> on others.</dd>
<dt><b>LLVM_LIT_TOOLS_DIR</b>:PATH</dt>
<dd>The path to GnuWin32 tools for tests. Valid on Windows host.
Defaults to "", then Lit seeks tools according to %PATH%.
Lit can find tools(eg. grep, sort, &amp;c) on LLVM_LIT_TOOLS_DIR at first,
without specifying GnuWin32 to %PATH%.</dd>
<dt><b>LLVM_ENABLE_FFI</b>:BOOL</dt>
<dd>Indicates whether LLVM Interpreter will be linked with Foreign
Function Interface library. If the library or its headers are
installed on a custom location, you can set the variables
FFI_INCLUDE_DIR and FFI_LIBRARY_DIR. Defaults to OFF.</dd>
<dt><b>LLVM_CLANG_SOURCE_DIR</b>:PATH</dt>
<dd>Path to Clang's source directory. Defaults to tools/clang.
Clang will not be built when it is empty or it does not point valid
path.</dd>
<dt><b>LLVM_USE_OPROFILE</b>:BOOL</dt>
<dd> Enable building OProfile JIT support. Defaults to OFF</dd>
<dt><b>LLVM_USE_INTEL_JITEVENTS</b>:BOOL</dt>
<dd> Enable building support for Intel JIT Events API. Defaults to OFF</dd>
<dt><b>LLVM_INTEL_JITEVENTS_DIR</b>:PATH</dt>
<dd> Path to installation of Intel(R) VTune(TM) Amplifier XE 2011,
used to locate the <tt>jitprofiling</tt> library. Default =
<tt>%VTUNE_AMPLIFIER_XE_2011_DIR%</tt> (Windows)
| <tt>/opt/intel/vtune_amplifier_xe_2011</tt> (Linux) </dd>
</dl>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="testing">Executing the test suite</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Testing is performed when the <i>check</i> target is built. For
instance, if you are using makefiles, execute this command while on
the top level of your build directory:</p>
<div class="doc_code">
<p><tt>make check</tt></p>
</div>
<p>On Visual Studio, you may run tests to build the project "check".</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="cross">Cross compiling</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this
wiki page</a> for generic instructions on how to cross-compile
with CMake. It goes into detailed explanations and may seem
daunting, but it is not. On the wiki page there are several
examples including toolchain files. Go directly to
<a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains">this
section</a> for a quick solution.</p>
<p>Also see the <a href="#llvmvars">LLVM-specific variables</a>
section for variables used when cross-compiling.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="embedding">Embedding LLVM in your project</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
of required LLVM features. What follows is an example of how to
obtain this information:</p>
<div class="doc_code">
<pre>
<b># A convenience variable:</b>
set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
<b># A bit of a sanity check:</b>
if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
endif()
<b># We incorporate the CMake features provided by LLVM:</b>
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
include(LLVMConfig)
<b># Now set the header and library paths:</b>
include_directories( ${LLVM_INCLUDE_DIRS} )
link_directories( ${LLVM_LIBRARY_DIRS} )
add_definitions( ${LLVM_DEFINITIONS} )
<b># Let's suppose we want to build a JIT compiler with support for
# binary code (no interpreter):</b>
llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
<b># Finally, we link the LLVM libraries to our executable:</b>
target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
</pre>
</div>
<p>This assumes that LLVM_ROOT points to an install of LLVM. The
procedure works too for uninstalled builds although we need to take
care to add an <i>include_directories</i> for the location of the
headers on the LLVM source directory (if we are building
out-of-source.)</p>
<p>Alternativaly, you can utilize CMake's <i>find_package</i>
functionality. Here is an equivalent variant of snippet shown above:</p>
<div class="doc_code">
<pre>
find_package(LLVM)
if( NOT LLVM_FOUND )
message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
endif()
include_directories( ${LLVM_INCLUDE_DIRS} )
link_directories( ${LLVM_LIBRARY_DIRS} )
llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
</pre>
</div>
<!-- ======================================================================= -->
<h3>
<a name="passdev">Developing LLVM pass out of source</a>
</h3>
<div>
<p>It is possible to develop LLVM passes against installed LLVM.
An example of project layout provided below:</p>
<div class="doc_code">
<pre>
&lt;project dir&gt;/
|
CMakeLists.txt
&lt;pass name&gt;/
|
CMakeLists.txt
Pass.cpp
...
</pre>
</div>
<p>Contents of &lt;project dir&gt;/CMakeLists.txt:</p>
<div class="doc_code">
<pre>
find_package(LLVM)
<b># Define add_llvm_* macro's.</b>
include(AddLLVM)
add_definitions(${LLVM_DEFINITIONS})
include_directories(${LLVM_INCLUDE_DIRS})
link_directories(${LLVM_LIBRARY_DIRS})
add_subdirectory(&lt;pass name&gt;)
</pre>
</div>
<p>Contents of &lt;project dir&gt;/&lt;pass name&gt;/CMakeLists.txt:</p>
<div class="doc_code">
<pre>
add_llvm_loadable_module(LLVMPassname
Pass.cpp
)
</pre>
</div>
<p>When you are done developing your pass, you may wish to integrate it
into LLVM source tree. You can achieve it in two easy steps:<br>
1. Copying &lt;pass name&gt; folder into &lt;LLVM root&gt;/lib/Transform directory.<br>
2. Adding "add_subdirectory(&lt;pass name&gt;)" line into &lt;LLVM root&gt;/lib/Transform/CMakeLists.txt</p>
</div>
<!-- *********************************************************************** -->
</div>
<!-- *********************************************************************** -->
<h2>
<a name="specifics">Compiler/Platform specific topics</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Notes for specific compilers and/or platforms.</p>
<h3>
<a name="msvc">Microsoft Visual C++</a>
</h3>
<div>
<dl>
<dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
<dd>Specifies the maximum number of parallell compiler jobs to use
per project when building with msbuild or Visual Studio. Only supported for
Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all
processors. Default is 0.</dd>
</dl>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $
</address>
</body>
</html>

3189
cpp/llvm/docs/CodeGenerator.html
View File

File diff suppressed because it is too large Load Diff

1568
cpp/llvm/docs/CodingStandards.html
View File

File diff suppressed because it is too large Load Diff

245
cpp/llvm/docs/CommandGuide/FileCheck.pod
View File

@ -1,245 +0,0 @@
=pod
=head1 NAME
FileCheck - Flexible pattern matching file verifier
=head1 SYNOPSIS
B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>]
=head1 DESCRIPTION
B<FileCheck> reads two files (one from standard input, and one specified on the
command line) and uses one to verify the other. This behavior is particularly
useful for the testsuite, which wants to verify that the output of some tool
(e.g. llc) contains the expected information (for example, a movsd from esp or
whatever is interesting). This is similar to using grep, but it is optimized
for matching multiple different inputs in one file in a specific order.
The I<match-filename> file specifies the file that contains the patterns to
match. The file to verify is always read from standard input.
=head1 OPTIONS
=over
=item B<-help>
Print a summary of command line options.
=item B<--check-prefix> I<prefix>
FileCheck searches the contents of I<match-filename> for patterns to match. By
default, these patterns are prefixed with "CHECK:". If you'd like to use a
different prefix (e.g. because the same input file is checking multiple
different tool or options), the B<--check-prefix> argument allows you to specify
a specific prefix to match.
=item B<--strict-whitespace>
By default, FileCheck canonicalizes input horizontal whitespace (spaces and
tabs) which causes it to ignore these differences (a space will match a tab).
The --strict-whitespace argument disables this behavior.
=item B<-version>
Show the version number of this program.
=back
=head1 EXIT STATUS
If B<FileCheck> verifies that the file matches the expected contents, it exits
with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero
value.
=head1 TUTORIAL
FileCheck is typically used from LLVM regression tests, being invoked on the RUN
line of the test. A simple example of using FileCheck from a RUN line looks
like this:
; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
This syntax says to pipe the current file ("%s") into llvm-as, pipe that into
llc, then pipe the output of llc into FileCheck. This means that FileCheck will
be verifying its standard input (the llc output) against the filename argument
specified (the original .ll file specified by "%s"). To see how this works,
let's look at the rest of the .ll file (after the RUN line):
define void @sub1(i32* %p, i32 %v) {
entry:
; CHECK: sub1:
; CHECK: subl
%0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
ret void
}
define void @inc4(i64* %p) {
entry:
; CHECK: inc4:
; CHECK: incq
%0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
ret void
}
Here you can see some "CHECK:" lines specified in comments. Now you can see
how the file is piped into llvm-as, then llc, and the machine code output is
what we are verifying. FileCheck checks the machine code output to verify that
it matches what the "CHECK:" lines specify.
The syntax of the CHECK: lines is very simple: they are fixed strings that
must occur in order. FileCheck defaults to ignoring horizontal whitespace
differences (e.g. a space is allowed to match a tab) but otherwise, the contents
of the CHECK: line is required to match some thing in the test file exactly.
One nice thing about FileCheck (compared to grep) is that it allows merging
test cases together into logical groups. For example, because the test above
is checking for the "sub1:" and "inc4:" labels, it will not match unless there
is a "subl" in between those labels. If it existed somewhere else in the file,
that would not count: "grep subl" matches if subl exists anywhere in the
file.
=head2 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,
testing different architectural variants with llc. Here's a simple example:
; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
; RUN: | FileCheck %s -check-prefix=X32>
; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
; RUN: | FileCheck %s -check-prefix=X64>
define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
%tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
ret <4 x i32> %tmp1
; X32: pinsrd_1:
; X32: pinsrd $1, 4(%esp), %xmm0
; X64: pinsrd_1:
; X64: pinsrd $1, %edi, %xmm0
}
In this case, we're testing that we get the expected code generation with
both 32-bit and 64-bit code generation.
=head2 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
this case, you can use CHECK: and CHECK-NEXT: directives to specify this. If
you specified a custom check prefix, just use "<PREFIX>-NEXT:". For
example, something like this works as you'd expect:
define void @t2(<2 x double>* %r, <2 x double&gt;* %A, double %B) {
%tmp3 = load <2 x double&gt;* %A, align 16
%tmp7 = insertelement <2 x double&gt; undef, double %B, i32 0
%tmp9 = shufflevector <2 x double&gt; %tmp3,
<2 x double&gt; %tmp7,
<2 x i32&gt; < i32 0, i32 2 &gt;
store <2 x double&gt; %tmp9, <2 x double&gt;* %r, align 16
ret void
; CHECK: t2:
; CHECK: movl 8(%esp), %eax
; CHECK-NEXT: movapd (%eax), %xmm0
; CHECK-NEXT: movhpd 12(%esp), %xmm0
; CHECK-NEXT: movl 4(%esp), %eax
; CHECK-NEXT: movapd %xmm0, (%eax)
; CHECK-NEXT: ret
}
CHECK-NEXT: directives reject the input unless there is exactly one newline
between it an the previous directive. A CHECK-NEXT cannot be the first
directive in a file.
=head2 The "CHECK-NOT:" directive
The CHECK-NOT: directive is used to verify that a string doesn't occur
between two matches (or before the first match, or after the last match). For
example, to verify that a load is removed by a transformation, a test like this
can be used:
define i8 @coerce_offset0(i32 %V, i32* %P) {
store i32 %V, i32* %P
%P2 = bitcast i32* %P to i8*
%P3 = getelementptr i8* %P2, i32 2
%A = load i8* %P3
ret i8 %A
; CHECK: @coerce_offset0
; CHECK-NOT: load
; CHECK: ret i8
}
=head2 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
things, a more flexible form of matching is desired. To support this, FileCheck
allows you to specify regular expressions in matching strings, surrounded by
double braces: B<{{yourregex}}>. Because we want to use fixed string
matching for a majority of what we do, FileCheck has been designed to support
mixing and matching fixed string matching with regular expressions. This allows
you to write things like this:
; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}
In this case, any offset from the ESP register will be allowed, and any xmm
register will be allowed.
Because regular expressions are enclosed with double braces, they are
visually distinct, and you don't need to use escape characters within the double
braces like you would in C. In the rare case that you want to match double
braces explicitly from the input, you can use something ugly like
B<{{[{][{]}}> as your pattern.
=head2 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,
but verify that that register is used consistently later. To do this, FileCheck
allows named variables to be defined and substituted into patterns. Here is a
simple example:
; CHECK: test5:
; CHECK: notw [[REGISTER:%[a-z]+]]
; CHECK: andw {{.*}}[REGISTER]]
The first check line matches a regex (B<%[a-z]+>) and captures it into
the variable "REGISTER". The second line verifies that whatever is in REGISTER
occurs later in the file after an "andw". FileCheck variable references are
always contained in B<[[ ]]> pairs, are named, and their names can be
formed with the regex "B<[a-zA-Z_][a-zA-Z0-9_]*>". If a colon follows the
name, then it is a definition of the variable, if not, it is a use.
FileCheck variables can be defined multiple times, and uses always get the
latest value. Note that variables are all read at the start of a "CHECK" line
and are all defined at the end. This means that if you have something like
"B<CHECK: [[XYZ:.*]]x[[XYZ]]>", the check line will read the previous
value of the XYZ variable and define a new one after the match is performed. If
you need to do something like this you can probably take advantage of the fact
that FileCheck is not actually line-oriented when it matches, this allows you to
define two separate CHECK lines that match on the same line.
=head1 AUTHORS
Maintained by The LLVM Team (L<http://llvm.org/>).
=cut

103
cpp/llvm/docs/CommandGuide/Makefile
View File

@ -1,103 +0,0 @@
##===- docs/CommandGuide/Makefile --------------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
ifdef BUILD_FOR_WEBSITE
# This special case is for keeping the CommandGuide on the LLVM web site
# up to date automatically as the documents are checked in. It must build
# the POD files to HTML only and keep them in the src directories. It must also
# build in an unconfigured tree, hence the ifdef. To use this, run
# make -s BUILD_FOR_WEBSITE=1 inside the cvs commit script.
SRC_DOC_DIR=
DST_HTML_DIR=html/
DST_MAN_DIR=man/man1/
DST_PS_DIR=ps/
# If we are in BUILD_FOR_WEBSITE mode, default to the all target.
all:: html man ps
clean:
rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS)
# To create other directories, as needed, and timestamp their creation
%/.dir:
-mkdir $* > /dev/null
date > $@
else
# Otherwise, if not in BUILD_FOR_WEBSITE mode, use the project info.
LEVEL := ../..
include $(LEVEL)/Makefile.common
SRC_DOC_DIR=$(PROJ_SRC_DIR)/
DST_HTML_DIR=$(PROJ_OBJ_DIR)/
DST_MAN_DIR=$(PROJ_OBJ_DIR)/
DST_PS_DIR=$(PROJ_OBJ_DIR)/
endif
POD := $(wildcard $(SRC_DOC_DIR)*.pod)
HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD))
MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD))
PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD))
# The set of man pages we will not install
NO_INSTALL_MANS = $(DST_MAN_DIR)FileCheck.1 $(DST_MAN_DIR)llvm-build.1
# The set of man pages that we will install
INSTALL_MANS = $(filter-out $(NO_INSTALL_MANS), $(MAN))
.SUFFIXES:
.SUFFIXES: .html .pod .1 .ps
$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir
pod2html --css=manpage.css --htmlroot=. \
--podpath=. --noindex --infile=$< --outfile=$@ --title=$*
$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir
pod2man --release=CVS --center="LLVM Command Guide" $< $@
$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir
groff -Tps -man $< > $@
html: $(HTML)
man: $(MAN)
ps: $(PS)
EXTRA_DIST := $(POD) index.html
clean-local::
$(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS)
HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/CommandGuide
MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1
PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps
install-local:: $(HTML) $(INSTALL_MANS) $(PS)
$(Echo) Installing HTML CommandGuide Documentation
$(Verb) $(MKDIR) $(HTML_DIR)
$(Verb) $(DataInstall) $(HTML) $(HTML_DIR)
$(Verb) $(DataInstall) $(PROJ_SRC_DIR)/index.html $(HTML_DIR)
$(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR)
$(Echo) Installing MAN CommandGuide Documentation
$(Verb) $(MKDIR) $(MAN_DIR)
$(Verb) $(DataInstall) $(INSTALL_MANS) $(MAN_DIR)
$(Echo) Installing PS CommandGuide Documentation
$(Verb) $(MKDIR) $(PS_DIR)
$(Verb) $(DataInstall) $(PS) $(PS_DIR)
uninstall-local::
$(Echo) Uninstalling CommandGuide Documentation
$(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR)
printvars::
$(Echo) "POD : " '$(POD)'
$(Echo) "HTML : " '$(HTML)'

186
cpp/llvm/docs/CommandGuide/bugpoint.pod
View File

@ -1,186 +0,0 @@
=pod
=head1 NAME
bugpoint - automatic test case reduction tool
=head1 SYNOPSIS
B<bugpoint> [I<options>] [I<input LLVM ll/bc files>] [I<LLVM passes>] B<--args>
I<program arguments>
=head1 DESCRIPTION
B<bugpoint> narrows down the source of problems in LLVM tools and passes. It
can be used to debug three types of failures: optimizer crashes, miscompilations
by optimizers, or bad native code generation (including problems in the static
and JIT compilers). It aims to reduce large test cases to small, useful ones.
For more information on the design and inner workings of B<bugpoint>, as well as
advice for using bugpoint, see F<llvm/docs/Bugpoint.html> in the LLVM
distribution.
=head1 OPTIONS
=over
=item B<--additional-so> F<library>
Load the dynamic shared object F<library> into the test program whenever it is
run. This is useful if you are debugging programs which depend on non-LLVM
libraries (such as the X or curses libraries) to run.
=item B<--append-exit-code>=I<{true,false}>
Append the test programs exit code to the output file so that a change in exit
code is considered a test failure. Defaults to false.
=item B<--args> I<program args>
Pass all arguments specified after -args to the test program whenever it runs.
Note that if any of the I<program args> start with a '-', you should use:
bugpoint [bugpoint args] --args -- [program args]
The "--" right after the B<--args> option tells B<bugpoint> to consider any
options starting with C<-> to be part of the B<--args> option, not as options to
B<bugpoint> itself.
=item B<--tool-args> I<tool args>
Pass all arguments specified after --tool-args to the LLVM tool under test
(B<llc>, B<lli>, etc.) whenever it runs. You should use this option in the
following way:
bugpoint [bugpoint args] --tool-args -- [tool args]
The "--" right after the B<--tool-args> option tells B<bugpoint> to consider any
options starting with C<-> to be part of the B<--tool-args> option, not as
options to B<bugpoint> itself. (See B<--args>, above.)
=item B<--safe-tool-args> I<tool args>
Pass all arguments specified after B<--safe-tool-args> to the "safe" execution
tool.
=item B<--gcc-tool-args> I<gcc tool args>
Pass all arguments specified after B<--gcc-tool-args> to the invocation of
B<gcc>.
=item B<--opt-args> I<opt args>
Pass all arguments specified after B<--opt-args> to the invocation of B<opt>.
=item B<--disable-{dce,simplifycfg}>
Do not run the specified passes to clean up and reduce the size of the test
program. By default, B<bugpoint> uses these passes internally when attempting to
reduce test programs. If you're trying to find a bug in one of these passes,
B<bugpoint> may crash.
=item B<--enable-valgrind>
Use valgrind to find faults in the optimization phase. This will allow
bugpoint to find otherwise asymptomatic problems caused by memory
mis-management.
=item B<-find-bugs>
Continually randomize the specified passes and run them on the test program
until a bug is found or the user kills B<bugpoint>.
=item B<-help>
Print a summary of command line options.
=item B<--input> F<filename>
Open F<filename> and redirect the standard input of the test program, whenever
it runs, to come from that file.
=item B<--load> F<plugin>
Load the dynamic object F<plugin> into B<bugpoint> itself. This object should
register new optimization passes. Once loaded, the object will add new command
line options to enable various optimizations. To see the new complete list of
optimizations, use the B<-help> and B<--load> options together; for example:
bugpoint --load myNewPass.so -help
=item B<--mlimit> F<megabytes>
Specifies an upper limit on memory usage of the optimization and codegen. Set
to zero to disable the limit.
=item B<--output> F<filename>
Whenever the test program produces output on its standard output stream, it
should match the contents of F<filename> (the "reference output"). If you
do not use this option, B<bugpoint> will attempt to generate a reference output
by compiling the program with the "safe" backend and running it.
=item B<--profile-info-file> F<filename>
Profile file loaded by B<--profile-loader>.
=item B<--run-{int,jit,llc,cbe,custom}>
Whenever the test program is compiled, B<bugpoint> should generate code for it
using the specified code generator. These options allow you to choose the
interpreter, the JIT compiler, the static native code compiler, the C
backend, or a custom command (see B<--exec-command>) respectively.
=item B<--safe-{llc,cbe,custom}>
When debugging a code generator, B<bugpoint> should use the specified code
generator as the "safe" code generator. This is a known-good code generator
used to generate the "reference output" if it has not been provided, and to
compile portions of the program that as they are excluded from the testcase.
These options allow you to choose the
static native code compiler, the C backend, or a custom command,
(see B<--exec-command>) respectively. The interpreter and the JIT backends
cannot currently be used as the "safe" backends.
=item B<--exec-command> I<command>
This option defines the command to use with the B<--run-custom> and
B<--safe-custom> options to execute the bitcode testcase. This can
be useful for cross-compilation.
=item B<--compile-command> I<command>
This option defines the command to use with the B<--compile-custom>
option to compile the bitcode testcase. This can be useful for
testing compiler output without running any link or execute stages. To
generate a reduced unit test, you may add CHECK directives to the
testcase and pass the name of an executable compile-command script in this form:
#!/bin/sh
llc "$@"
not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
This script will "fail" as long as FileCheck passes. So the result
will be the minimum bitcode that passes FileCheck.
=item B<--safe-path> I<path>
This option defines the path to the command to execute with the
B<--safe-{int,jit,llc,cbe,custom}>
option.
=back
=head1 EXIT STATUS
If B<bugpoint> succeeds in finding a problem, it will exit with 0. Otherwise,
if an error occurs, it will exit with a non-zero value.
=head1 SEE ALSO
L<opt|opt>
=head1 AUTHOR
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

256
cpp/llvm/docs/CommandGuide/html/manpage.css
View File

@ -1,256 +0,0 @@
/* Based on http://www.perldoc.com/css/perldoc.css */
@import url("../llvm.css");
body { font-family: Arial,Helvetica; }
blockquote { margin: 10pt; }
h1, a { color: #336699; }
/*** Top menu style ****/
.mmenuon {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ff6600; font-size: 10pt;
}
.mmenuoff {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: 10pt;
}
.cpyright {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: xx-small;
}
.cpyrightText {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: xx-small;
}
.sections {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 11pt;
}
.dsections {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 12pt;
}
.slink {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #000000; font-size: 9pt;
}
.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; }
.maintitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 18pt;
}
.dblArrow {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
.menuSec {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
.newstext {
font-family: Arial,Helvetica; font-size: small;
}
.linkmenu {
font-family: Arial,Helvetica; color: #000000; font-weight: bold;
text-decoration: none;
}
P {
font-family: Arial,Helvetica;
}
PRE {
font-size: 10pt;
}
.quote {
font-family: Times; text-decoration: none;
color: #000000; font-size: 9pt; font-style: italic;
}
.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; }
.std { font-family: Arial,Helvetica; color: #000000; }
.meerkatTitle {
font-family: sans-serif; font-size: x-small; color: black; }
.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black }
.meerkatCategory {
font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic;
color: brown; }
.meerkatChannel {
font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; }
.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; }
.tocTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 10pt;
}
.toc-item {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt; text-decoration: underline;
}
.perlVersion {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt; text-decoration: none;
}
.podTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #000000;
}
.docTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #000000; font-size: 10pt;
}
.dotDot {
font-family: Arial,Helvetica; font-weight: bold;
color: #000000; font-size: 9pt;
}
.docSec {
font-family: Arial,Helvetica; font-weight: normal;
color: #333333; font-size: 9pt;
}
.docVersion {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 10pt;
}
.docSecs-on {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #ff0000; font-size: 10pt;
}
.docSecs-off {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #333333; font-size: 10pt;
}
h2 {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: medium;
}
h1 {
font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: large;
}
DL {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #333333; font-size: 10pt;
}
UL > LI > A {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt;
}
.moduleInfo {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 11pt;
}
.moduleInfoSec {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 10pt;
}
.moduleInfoVal {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline;
color: #000000; font-size: 10pt;
}
.cpanNavTitle {
font-family: Arial,Helvetica; font-weight: bold;
color: #ffffff; font-size: 10pt;
}
.cpanNavLetter {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 9pt;
}
.cpanCat {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 9pt;
}
.bttndrkblue-bkgd-top {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif);
}
.bttndrkblue-bkgd-left {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif);
}
.bttndrkblue-bkgd {
padding-top: 0px;
padding-bottom: 0px;
margin-bottom: 0px;
margin-top: 0px;
background-repeat: no-repeat;
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif);
vertical-align: top;
}
.bttndrkblue-bkgd-right {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif);
}
.bttndrkblue-bkgd-bottom {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif);
}
.bttndrkblue-text a {
color: #ffffff;
text-decoration: none;
}
a.bttndrkblue-text:hover {
color: #ffDD3C;
text-decoration: none;
}
.bg-ltblue {
background-color: #f0f5fa;
}
.border-left-b {
background: #f0f5fa url(/i/corner-leftline.gif) repeat-y;
}
.border-right-b {
background: #f0f5fa url(/i/corner-rightline.gif) repeat-y;
}
.border-top-b {
background: #f0f5fa url(/i/corner-topline.gif) repeat-x;
}
.border-bottom-b {
background: #f0f5fa url(/i/corner-botline.gif) repeat-x;
}
.border-right-w {
background: #ffffff url(/i/corner-rightline.gif) repeat-y;
}
.border-top-w {
background: #ffffff url(/i/corner-topline.gif) repeat-x;
}
.border-bottom-w {
background: #ffffff url(/i/corner-botline.gif) repeat-x;
}
.bg-white {
background-color: #ffffff;
}
.border-left-w {
background: #ffffff url(/i/corner-leftline.gif) repeat-y;
}

142
cpp/llvm/docs/CommandGuide/index.html
View File

@ -1,142 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LLVM Command Guide</title>
<link rel="stylesheet" href="../llvm.css" type="text/css">
</head>
<body>
<h1>
LLVM Command Guide
</h1>
<div>
<p>These documents are HTML versions of the <a href="man/man1/">man pages</a>
for all of the LLVM tools. These pages describe how to use the LLVM commands
and what their options are. Note that these pages do not describe all of the
options available for all tools. To get a complete listing, pass the
<tt>-help</tt> (general options) or <tt>-help-hidden</tt> (general+debugging
options) arguments to the tool you are interested in.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="basic">Basic Commands</a>
</h2>
<!-- *********************************************************************** -->
<div>
<ul>
<li><a href="/cmds/llvm-as.html"><b>llvm-as</b></a> -
assemble a human-readable .ll file into bytecode</li>
<li><a href="/cmds/llvm-dis.html"><b>llvm-dis</b></a> -
disassemble a bytecode file into a human-readable .ll file</li>
<li><a href="/cmds/opt.html"><b>opt</b></a> -
run a series of LLVM-to-LLVM optimizations on a bytecode file</li>
<li><a href="/cmds/llc.html"><b>llc</b></a> -
generate native machine code for a bytecode file</li>
<li><a href="/cmds/lli.html"><b>lli</b></a> -
directly run a program compiled to bytecode using a JIT compiler or
interpreter</li>
<li><a href="/cmds/llvm-link.html"><b>llvm-link</b></a> -
link several bytecode files into one</li>
<li><a href="/cmds/llvm-ar.html"><b>llvm-ar</b></a> -
archive bytecode files</li>
<li><a href="/cmds/llvm-ranlib.html"><b>llvm-ranlib</b></a> -
create an index for archives made with llvm-ar</li>
<li><a href="/cmds/llvm-nm.html"><b>llvm-nm</b></a> -
print out the names and types of symbols in a bytecode file</li>
<li><a href="/cmds/llvm-prof.html"><b>llvm-prof</b></a> -
format raw `<tt>llvmprof.out</tt>' data into a human-readable report</li>
<li><a href="/cmds/llvm-ld.html"><b>llvm-ld</b></a> -
general purpose linker with loadable runtime optimization support</li>
<li><a href="/cmds/llvm-config.html"><b>llvm-config</b></a> -
print out LLVM compilation options, libraries, etc. as configured</li>
<li><a href="/cmds/llvm-diff.html"><b>llvm-diff</b></a> -
structurally compare two modules</li>
<li><a href="/cmds/llvm-cov.html"><b>llvm-cov</b></a> -
emit coverage information</li>
<li><a href="/cmds/llvm-stress.html"><b>llvm-stress</b></a> -
generate random .ll files to fuzz different llvm components</li>
</ul>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="debug">Debugging Tools</a>
</h2>
<!-- *********************************************************************** -->
<div>
<ul>
<li><a href="/cmds/bugpoint.html"><b>bugpoint</b></a> -
automatic test-case reducer</li>
<li><a href="/cmds/llvm-extract.html"><b>llvm-extract</b></a> -
extract a function from an LLVM bytecode file</li>
<li><a href="/cmds/llvm-bcanalyzer.html"><b>llvm-bcanalyzer</b></a> -
bytecode analyzer (analyzes the binary encoding itself, not the program it
represents)</li>
</ul>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="internal">Internal Tools</a>
</h2>
<!-- *********************************************************************** -->
<div>
<ul>
<li><a href="/cmds/FileCheck.html"><b>FileCheck</b></a> -
Flexible file verifier used extensively by the testing harness</li>
<li><a href="/cmds/tblgen.html"><b>tblgen</b></a> -
target description reader and generator</li>
<li><a href="/cmds/lit.html"><b>lit</b></a> -
LLVM Integrated Tester, for running tests</li>
</ul>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-02-26 00:35:53 -0800 (Sun, 26 Feb 2012) $
</address>
</body>
</html>

404
cpp/llvm/docs/CommandGuide/lit.pod
View File

@ -1,404 +0,0 @@
=pod
=head1 NAME
lit - LLVM Integrated Tester
=head1 SYNOPSIS
B<lit> [I<options>] [I<tests>]
=head1 DESCRIPTION
B<lit> is a portable tool for executing LLVM and Clang style test suites,
summarizing their results, and providing indication of failures. B<lit> is
designed to be a lightweight testing tool with as simple a user interface as
possible.
B<lit> should be run with one or more I<tests> to run specified on the command
line. Tests can be either individual test files or directories to search for
tests (see L<"TEST DISCOVERY">).
Each specified test will be executed (potentially in parallel) and once all
tests have been run B<lit> will print summary information on the number of tests
which passed or failed (see L<"TEST STATUS RESULTS">). The B<lit> program will
execute with a non-zero exit code if any tests fail.
By default B<lit> will use a succinct progress display and will only print
summary information for test failures. See L<"OUTPUT OPTIONS"> for options
controlling the B<lit> progress display and output.
B<lit> also includes a number of options for controlling how tests are executed
(specific features may depend on the particular test format). See L<"EXECUTION
OPTIONS"> for more information.
Finally, B<lit> also supports additional options for only running a subset of
the options specified on the command line, see L<"SELECTION OPTIONS"> for
more information.
Users interested in the B<lit> architecture or designing a B<lit> testing
implementation should see L<"LIT INFRASTRUCTURE">
=head1 GENERAL OPTIONS
=over
=item B<-h>, B<--help>
Show the B<lit> help message.
=item B<-j> I<N>, B<--threads>=I<N>
Run I<N> tests in parallel. By default, this is automatically chosen to match
the number of detected available CPUs.
=item B<--config-prefix>=I<NAME>
Search for I<NAME.cfg> and I<NAME.site.cfg> when searching for test suites,
instead of I<lit.cfg> and I<lit.site.cfg>.
=item B<--param> I<NAME>, B<--param> I<NAME>=I<VALUE>
Add a user defined parameter I<NAME> with the given I<VALUE> (or the empty
string if not given). The meaning and use of these parameters is test suite
dependent.
=back
=head1 OUTPUT OPTIONS
=over
=item B<-q>, B<--quiet>
Suppress any output except for test failures.
=item B<-s>, B<--succinct>
Show less output, for example don't show information on tests that pass.
=item B<-v>, B<--verbose>
Show more information on test failures, for example the entire test output
instead of just the test result.
=item B<--no-progress-bar>
Do not use curses based progress bar.
=back
=head1 EXECUTION OPTIONS
=over
=item B<--path>=I<PATH>
Specify an addition I<PATH> to use when searching for executables in tests.
=item B<--vg>
Run individual tests under valgrind (using the memcheck tool). The
I<--error-exitcode> argument for valgrind is used so that valgrind failures will
cause the program to exit with a non-zero status.
=item B<--vg-arg>=I<ARG>
When I<--vg> is used, specify an additional argument to pass to valgrind itself.
=item B<--time-tests>
Track the wall time individual tests take to execute and includes the results in
the summary output. This is useful for determining which tests in a test suite
take the most time to execute. Note that this option is most useful with I<-j
1>.
=back
=head1 SELECTION OPTIONS
=over
=item B<--max-tests>=I<N>
Run at most I<N> tests and then terminate.
=item B<--max-time>=I<N>
Spend at most I<N> seconds (approximately) running tests and then terminate.
=item B<--shuffle>
Run the tests in a random order.
=back
=head1 ADDITIONAL OPTIONS
=over
=item B<--debug>
Run B<lit> in debug mode, for debugging configuration issues and B<lit> itself.
=item B<--show-suites>
List the discovered test suites as part of the standard output.
=item B<--no-tcl-as-sh>
Run Tcl scripts internally (instead of converting to shell scripts).
=item B<--repeat>=I<N>
Run each test I<N> times. Currently this is primarily useful for timing tests,
other results are not collated in any reasonable fashion.
=back
=head1 EXIT STATUS
B<lit> will exit with an exit code of 1 if there are any FAIL or XPASS
results. Otherwise, it will exit with the status 0. Other exit codes are used
for non-test related failures (for example a user error or an internal program
error).
=head1 TEST DISCOVERY
The inputs passed to B<lit> can be either individual tests, or entire
directories or hierarchies of tests to run. When B<lit> starts up, the first
thing it does is convert the inputs into a complete list of tests to run as part
of I<test discovery>.
In the B<lit> model, every test must exist inside some I<test suite>. B<lit>
resolves the inputs specified on the command line to test suites by searching
upwards from the input path until it finds a I<lit.cfg> or I<lit.site.cfg>
file. These files serve as both a marker of test suites and as configuration
files which B<lit> loads in order to understand how to find and run the tests
inside the test suite.
Once B<lit> has mapped the inputs into test suites it traverses the list of
inputs adding tests for individual files and recursively searching for tests in
directories.
This behavior makes it easy to specify a subset of tests to run, while still
allowing the test suite configuration to control exactly how tests are
interpreted. In addition, B<lit> always identifies tests by the test suite they
are in, and their relative path inside the test suite. For appropriately
configured projects, this allows B<lit> to provide convenient and flexible
support for out-of-tree builds.
=head1 TEST STATUS RESULTS
Each test ultimately produces one of the following six results:
=over
=item B<PASS>
The test succeeded.
=item B<XFAIL>
The test failed, but that is expected. This is used for test formats which allow
specifying that a test does not currently work, but wish to leave it in the test
suite.
=item B<XPASS>
The test succeeded, but it was expected to fail. This is used for tests which
were specified as expected to fail, but are now succeeding (generally because
the feature they test was broken and has been fixed).
=item B<FAIL>
The test failed.
=item B<UNRESOLVED>
The test result could not be determined. For example, this occurs when the test
could not be run, the test itself is invalid, or the test was interrupted.
=item B<UNSUPPORTED>
The test is not supported in this environment. This is used by test formats
which can report unsupported tests.
=back
Depending on the test format tests may produce additional information about
their status (generally only for failures). See the L<Output|"OUTPUT OPTIONS">
section for more information.
=head1 LIT INFRASTRUCTURE
This section describes the B<lit> testing architecture for users interested in
creating a new B<lit> testing implementation, or extending an existing one.
B<lit> proper is primarily an infrastructure for discovering and running
arbitrary tests, and to expose a single convenient interface to these
tests. B<lit> itself doesn't know how to run tests, rather this logic is
defined by I<test suites>.
=head2 TEST SUITES
As described in L<"TEST DISCOVERY">, tests are always located inside a I<test
suite>. Test suites serve to define the format of the tests they contain, the
logic for finding those tests, and any additional information to run the tests.
B<lit> identifies test suites as directories containing I<lit.cfg> or
I<lit.site.cfg> files (see also B<--config-prefix>). Test suites are initially
discovered by recursively searching up the directory hierarchy for all the input
files passed on the command line. You can use B<--show-suites> to display the
discovered test suites at startup.
Once a test suite is discovered, its config file is loaded. Config files
themselves are Python modules which will be executed. When the config file is
executed, two important global variables are predefined:
=over
=item B<lit>
The global B<lit> configuration object (a I<LitConfig> instance), which defines
the builtin test formats, global configuration parameters, and other helper
routines for implementing test configurations.
=item B<config>
This is the config object (a I<TestingConfig> instance) for the test suite,
which the config file is expected to populate. The following variables are also
available on the I<config> object, some of which must be set by the config and
others are optional or predefined:
B<name> I<[required]> The name of the test suite, for use in reports and
diagnostics.
B<test_format> I<[required]> The test format object which will be used to
discover and run tests in the test suite. Generally this will be a builtin test
format available from the I<lit.formats> module.
B<test_src_root> The filesystem path to the test suite root. For out-of-dir
builds this is the directory that will be scanned for tests.
B<test_exec_root> For out-of-dir builds, the path to the test suite root inside
the object directory. This is where tests will be run and temporary output files
placed.
B<environment> A dictionary representing the environment to use when executing
tests in the suite.
B<suffixes> For B<lit> test formats which scan directories for tests, this
variable is a list of suffixes to identify test files. Used by: I<ShTest>,
I<TclTest>.
B<substitutions> For B<lit> test formats which substitute variables into a test
script, the list of substitutions to perform. Used by: I<ShTest>, I<TclTest>.
B<unsupported> Mark an unsupported directory, all tests within it will be
reported as unsupported. Used by: I<ShTest>, I<TclTest>.
B<parent> The parent configuration, this is the config object for the directory
containing the test suite, or None.
B<root> The root configuration. This is the top-most B<lit> configuration in
the project.
B<on_clone> The config is actually cloned for every subdirectory inside a test
suite, to allow local configuration on a per-directory basis. The I<on_clone>
variable can be set to a Python function which will be called whenever a
configuration is cloned (for a subdirectory). The function should takes three
arguments: (1) the parent configuration, (2) the new configuration (which the
I<on_clone> function will generally modify), and (3) the test path to the new
directory being scanned.
=back
=head2 TEST DISCOVERY
Once test suites are located, B<lit> recursively traverses the source directory
(following I<test_src_root>) looking for tests. When B<lit> enters a
sub-directory, it first checks to see if a nested test suite is defined in that
directory. If so, it loads that test suite recursively, otherwise it
instantiates a local test config for the directory (see L<"LOCAL CONFIGURATION
FILES">).
Tests are identified by the test suite they are contained within, and the
relative path inside that suite. Note that the relative path may not refer to an
actual file on disk; some test formats (such as I<GoogleTest>) define "virtual
tests" which have a path that contains both the path to the actual test file and
a subpath to identify the virtual test.
=head2 LOCAL CONFIGURATION FILES
When B<lit> loads a subdirectory in a test suite, it instantiates a local test
configuration by cloning the configuration for the parent direction -- the root
of this configuration chain will always be a test suite. Once the test
configuration is cloned B<lit> checks for a I<lit.local.cfg> file in the
subdirectory. If present, this file will be loaded and can be used to specialize
the configuration for each individual directory. This facility can be used to
define subdirectories of optional tests, or to change other configuration
parameters -- for example, to change the test format, or the suffixes which
identify test files.
=head2 TEST RUN OUTPUT FORMAT
The b<lit> output for a test run conforms to the following schema, in both short
and verbose modes (although in short mode no PASS lines will be shown). This
schema has been chosen to be relatively easy to reliably parse by a machine (for
example in buildbot log scraping), and for other tools to generate.
Each test result is expected to appear on a line that matches:
<result code>: <test name> (<progress info>)
where <result-code> is a standard test result such as PASS, FAIL, XFAIL, XPASS,
UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and
REGRESSED are also allowed.
The <test name> field can consist of an arbitrary string containing no newline.
The <progress info> field can be used to report progress information such as
(1/300) or can be empty, but even when empty the parentheses are required.
Each test result may include additional (multiline) log information in the
following format.
<log delineator> TEST '(<test name>)' <trailing delineator>
... log message ...
<log delineator>
where <test name> should be the name of a preceeding reported test, <log
delineator> is a string of '*' characters I<at least> four characters long (the
recommended length is 20), and <trailing delineator> is an arbitrary (unparsed)
string.
The following is an example of a test run output which consists of four tests A,
B, C, and D, and a log message for the failing test C.
=head3 Example Test Run Output Listing
PASS: A (1 of 4)
PASS: B (2 of 4)
FAIL: C (3 of 4)
******************** TEST 'C' FAILED ********************
Test 'C' failed as a result of exit code 1.
********************
PASS: D (4 of 4)
=back
=head2 LIT EXAMPLE TESTS
The B<lit> distribution contains several example implementations of test suites
in the I<ExampleTests> directory.
=head1 SEE ALSO
L<valgrind(1)>
=head1 AUTHOR
Written by Daniel Dunbar and maintained by the LLVM Team (L<http://llvm.org/>).
=cut

201
cpp/llvm/docs/CommandGuide/llc.pod
View File

@ -1,201 +0,0 @@
=pod
=head1 NAME
llc - LLVM static compiler
=head1 SYNOPSIS
B<llc> [I<options>] [I<filename>]
=head1 DESCRIPTION
The B<llc> command compiles LLVM source inputs into assembly language for a
specified architecture. The assembly language output can then be passed through
a native assembler and linker to generate a native executable.
The choice of architecture for the output assembly code is automatically
determined from the input file, unless the B<-march> option is used to override
the default.
=head1 OPTIONS
If I<filename> is - or omitted, B<llc> reads from standard input. Otherwise, it
will from I<filename>. Inputs can be in either the LLVM assembly language
format (.ll) or the LLVM bitcode format (.bc).
If the B<-o> option is omitted, then B<llc> will send its output to standard
output if the input is from standard input. If the B<-o> option specifies -,
then the output will also be sent to standard output.
If no B<-o> option is specified and an input file other than - is specified,
then B<llc> creates the output filename by taking the input filename,
removing any existing F<.bc> extension, and adding a F<.s> suffix.
Other B<llc> options are as follows:
=head2 End-user Options
=over
=item B<-help>
Print a summary of command line options.
=item B<-O>=I<uint>
Generate code at different optimization levels. These correspond to the I<-O0>,
I<-O1>, I<-O2>, and I<-O3> optimization levels used by B<llvm-gcc> and
B<clang>.
=item B<-mtriple>=I<target triple>
Override the target triple specified in the input file with the specified
string.
=item B<-march>=I<arch>
Specify the architecture for which to generate assembly, overriding the target
encoded in the input file. See the output of B<llc -help> for a list of
valid architectures. By default this is inferred from the target triple or
autodetected to the current architecture.
=item B<-mcpu>=I<cpuname>
Specify a specific chip in the current architecture to generate code for.
By default this is inferred from the target triple and autodetected to
the current architecture. For a list of available CPUs, use:
B<llvm-as E<lt> /dev/null | llc -march=xyz -mcpu=help>
=item B<-mattr>=I<a1,+a2,-a3,...>
Override or control specific attributes of the target, such as whether SIMD
operations are enabled or not. The default set of attributes is set by the
current CPU. For a list of available attributes, use:
B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help>
=item B<--disable-fp-elim>
Disable frame pointer elimination optimization.
=item B<--disable-excess-fp-precision>
Disable optimizations that may produce excess precision for floating point.
Note that this option can dramatically slow down code on some systems
(e.g. X86).
=item B<--enable-no-infs-fp-math>
Enable optimizations that assume no Inf values.
=item B<--enable-no-nans-fp-math>
Enable optimizations that assume no NAN values.
=item B<--enable-unsafe-fp-math>
Enable optimizations that make unsafe assumptions about IEEE math (e.g. that
addition is associative) or may not work for all input ranges. These
optimizations allow the code generator to make use of some instructions which
would otherwise not be usable (such as fsin on X86).
=item B<--enable-correct-eh-support>
Instruct the B<lowerinvoke> pass to insert code for correct exception handling
support. This is expensive and is by default omitted for efficiency.
=item B<--stats>
Print statistics recorded by code-generation passes.
=item B<--time-passes>
Record the amount of time needed for each pass and print a report to standard
error.
=item B<--load>=F<dso_path>
Dynamically load F<dso_path> (a path to a dynamically shared object) that
implements an LLVM target. This will permit the target name to be used with the
B<-march> option so that code can be generated for that target.
=back
=head2 Tuning/Configuration Options
=over
=item B<--print-machineinstrs>
Print generated machine code between compilation phases (useful for debugging).
=item B<--regalloc>=I<allocator>
Specify the register allocator to use. The default I<allocator> is I<local>.
Valid register allocators are:
=over
=item I<simple>
Very simple "always spill" register allocator
=item I<local>
Local register allocator
=item I<linearscan>
Linear scan global register allocator
=item I<iterativescan>
Iterative scan global register allocator
=back
=item B<--spiller>=I<spiller>
Specify the spiller to use for register allocators that support it. Currently
this option is used only by the linear scan register allocator. The default
I<spiller> is I<local>. Valid spillers are:
=over
=item I<simple>
Simple spiller
=item I<local>
Local spiller
=back
=back
=head2 Intel IA-32-specific Options
=over
=item B<--x86-asm-syntax=att|intel>
Specify whether to emit assembly code in AT&T syntax (the default) or intel
syntax.
=back
=head1 EXIT STATUS
If B<llc> succeeds, it will exit with 0. Otherwise, if an error occurs,
it will exit with a non-zero value.
=head1 SEE ALSO
L<lli|lli>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

219
cpp/llvm/docs/CommandGuide/lli.pod
View File

@ -1,219 +0,0 @@
=pod
=head1 NAME
lli - directly execute programs from LLVM bitcode
=head1 SYNOPSIS
B<lli> [I<options>] [I<filename>] [I<program args>]
=head1 DESCRIPTION
B<lli> directly executes programs in LLVM bitcode format. It takes a program
in LLVM bitcode format and executes it using a just-in-time compiler, if one is
available for the current architecture, or an interpreter. B<lli> takes all of
the same code generator options as L<llc|llc>, but they are only effective when
B<lli> is using the just-in-time compiler.
If I<filename> is not specified, then B<lli> reads the LLVM bitcode for the
program from standard input.
The optional I<args> specified on the command line are passed to the program as
arguments.
=head1 GENERAL OPTIONS
=over
=item B<-fake-argv0>=I<executable>
Override the C<argv[0]> value passed into the executing program.
=item B<-force-interpreter>=I<{false,true}>
If set to true, use the interpreter even if a just-in-time compiler is available
for this architecture. Defaults to false.
=item B<-help>
Print a summary of command line options.
=item B<-load>=I<puginfilename>
Causes B<lli> to load the plugin (shared object) named I<pluginfilename> and use
it for optimization.
=item B<-stats>
Print statistics from the code-generation passes. This is only meaningful for
the just-in-time compiler, at present.
=item B<-time-passes>
Record the amount of time needed for each code-generation pass and print it to
standard error.
=item B<-version>
Print out the version of B<lli> and exit without doing anything else.
=back
=head1 TARGET OPTIONS
=over
=item B<-mtriple>=I<target triple>
Override the target triple specified in the input bitcode file with the
specified string. This may result in a crash if you pick an
architecture which is not compatible with the current system.
=item B<-march>=I<arch>
Specify the architecture for which to generate assembly, overriding the target
encoded in the bitcode file. See the output of B<llc -help> for a list of
valid architectures. By default this is inferred from the target triple or
autodetected to the current architecture.
=item B<-mcpu>=I<cpuname>
Specify a specific chip in the current architecture to generate code for.
By default this is inferred from the target triple and autodetected to
the current architecture. For a list of available CPUs, use:
B<llvm-as E<lt> /dev/null | llc -march=xyz -mcpu=help>
=item B<-mattr>=I<a1,+a2,-a3,...>
Override or control specific attributes of the target, such as whether SIMD
operations are enabled or not. The default set of attributes is set by the
current CPU. For a list of available attributes, use:
B<llvm-as E<lt> /dev/null | llc -march=xyz -mattr=help>
=back
=head1 FLOATING POINT OPTIONS
=over
=item B<-disable-excess-fp-precision>
Disable optimizations that may increase floating point precision.
=item B<-enable-no-infs-fp-math>
Enable optimizations that assume no Inf values.
=item B<-enable-no-nans-fp-math>
Enable optimizations that assume no NAN values.
=item B<-enable-unsafe-fp-math>
Causes B<lli> to enable optimizations that may decrease floating point
precision.
=item B<-soft-float>
Causes B<lli> to generate software floating point library calls instead of
equivalent hardware instructions.
=back
=head1 CODE GENERATION OPTIONS
=over
=item B<-code-model>=I<model>
Choose the code model from:
default: Target default code model
small: Small code model
kernel: Kernel code model
medium: Medium code model
large: Large code model
=item B<-disable-post-RA-scheduler>
Disable scheduling after register allocation.
=item B<-disable-spill-fusing>
Disable fusing of spill code into instructions.
=item B<-enable-correct-eh-support>
Make the -lowerinvoke pass insert expensive, but correct, EH code.
=item B<-jit-enable-eh>
Exception handling should be enabled in the just-in-time compiler.
=item B<-join-liveintervals>
Coalesce copies (default=true).
=item B<-nozero-initialized-in-bss>
Don't place zero-initialized symbols into the BSS section.
=item B<-pre-RA-sched>=I<scheduler>
Instruction schedulers available (before register allocation):
=default: Best scheduler for the target
=none: No scheduling: breadth first sequencing
=simple: Simple two pass scheduling: minimize critical path and maximize processor utilization
=simple-noitin: Simple two pass scheduling: Same as simple except using generic latency
=list-burr: Bottom-up register reduction list scheduling
=list-tdrr: Top-down register reduction list scheduling
=list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code
=item B<-regalloc>=I<allocator>
Register allocator to use (default=linearscan)
=bigblock: Big-block register allocator
=linearscan: linear scan register allocator =local - local register allocator
=simple: simple register allocator
=item B<-relocation-model>=I<model>
Choose relocation model from:
=default: Target default relocation model
=static: Non-relocatable code =pic - Fully relocatable, position independent code
=dynamic-no-pic: Relocatable external references, non-relocatable code
=item B<-spiller>
Spiller to use (default=local)
=simple: simple spiller
=local: local spiller
=item B<-x86-asm-syntax>=I<syntax>
Choose style of code to emit from X86 backend:
=att: Emit AT&T-style assembly
=intel: Emit Intel-style assembly
=back
=head1 EXIT STATUS
If B<lli> fails to load the program, it will exit with an exit code of 1.
Otherwise, it will return the exit code of the program it executes.
=head1 SEE ALSO
L<llc|llc>
=head1 AUTHOR
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

406
cpp/llvm/docs/CommandGuide/llvm-ar.pod
View File

@ -1,406 +0,0 @@
=pod
=head1 NAME
llvm-ar - LLVM archiver
=head1 SYNOPSIS
B<llvm-ar> [-]{dmpqrtx}[Rabfikouz] [relpos] [count] <archive> [files...]
=head1 DESCRIPTION
The B<llvm-ar> command is similar to the common Unix utility, C<ar>. It
archives several files together into a single file. The intent for this is
to produce archive libraries by LLVM bitcode that can be linked into an
LLVM program. However, the archive can contain any kind of file. By default,
B<llvm-ar> generates a symbol table that makes linking faster because
only the symbol table needs to be consulted, not each individual file member
of the archive.
The B<llvm-ar> command can be used to I<read> both SVR4 and BSD style archive
files. However, it cannot be used to write them. While the B<llvm-ar> command
produces files that are I<almost> identical to the format used by other C<ar>
implementations, it has two significant departures in order to make the
archive appropriate for LLVM. The first departure is that B<llvm-ar> only
uses BSD4.4 style long path names (stored immediately after the header) and
never contains a string table for long names. The second departure is that the
symbol table is formated for efficient construction of an in-memory data
structure that permits rapid (red-black tree) lookups. Consequently, archives
produced with B<llvm-ar> usually won't be readable or editable with any
C<ar> implementation or useful for linking. Using the C<f> modifier to flatten
file names will make the archive readable by other C<ar> implementations
but not for linking because the symbol table format for LLVM is unique. If an
SVR4 or BSD style archive is used with the C<r> (replace) or C<q> (quick
update) operations, the archive will be reconstructed in LLVM format. This
means that the string table will be dropped (in deference to BSD 4.4 long names)
and an LLVM symbol table will be added (by default). The system symbol table
will be retained.
Here's where B<llvm-ar> departs from previous C<ar> implementations:
=over
=item I<Symbol Table>
Since B<llvm-ar> is intended to archive bitcode files, the symbol table
won't make much sense to anything but LLVM. Consequently, the symbol table's
format has been simplified. It consists simply of a sequence of pairs
of a file member index number as an LSB 4byte integer and a null-terminated
string.
=item I<Long Paths>
Some C<ar> implementations (SVR4) use a separate file member to record long
path names (> 15 characters). B<llvm-ar> takes the BSD 4.4 and Mac OS X
approach which is to simply store the full path name immediately preceding
the data for the file. The path name is null terminated and may contain the
slash (/) character.
=item I<Compression>
B<llvm-ar> can compress the members of an archive to save space. The
compression used depends on what's available on the platform and what choices
the LLVM Compressor utility makes. It generally favors bzip2 but will select
between "no compression" or bzip2 depending on what makes sense for the
file's content.
=item I<Directory Recursion>
Most C<ar> implementations do not recurse through directories but simply
ignore directories if they are presented to the program in the F<files>
option. B<llvm-ar>, however, can recurse through directory structures and
add all the files under a directory, if requested.
=item I<TOC Verbose Output>
When B<llvm-ar> prints out the verbose table of contents (C<tv> option), it
precedes the usual output with a character indicating the basic kind of
content in the file. A blank means the file is a regular file. A 'Z' means
the file is compressed. A 'B' means the file is an LLVM bitcode file. An
'S' means the file is the symbol table.
=back
=head1 OPTIONS
The options to B<llvm-ar> are compatible with other C<ar> implementations.
However, there are a few modifiers (F<zR>) that are not found in other
C<ar>s. The options to B<llvm-ar> specify a single basic operation to
perform on the archive, a variety of modifiers for that operation, the
name of the archive file, and an optional list of file names. These options
are used to determine how B<llvm-ar> should process the archive file.
The Operations and Modifiers are explained in the sections below. The minimal
set of options is at least one operator and the name of the archive. Typically
archive files end with a C<.a> suffix, but this is not required. Following
the F<archive-name> comes a list of F<files> that indicate the specific members
of the archive to operate on. If the F<files> option is not specified, it
generally means either "none" or "all" members, depending on the operation.
=head2 Operations
=over
=item d
Delete files from the archive. No modifiers are applicable to this operation.
The F<files> options specify which members should be removed from the
archive. It is not an error if a specified file does not appear in the archive.
If no F<files> are specified, the archive is not modified.
=item m[abi]
Move files from one location in the archive to another. The F<a>, F<b>, and
F<i> modifiers apply to this operation. The F<files> will all be moved
to the location given by the modifiers. If no modifiers are used, the files
will be moved to the end of the archive. If no F<files> are specified, the
archive is not modified.
=item p[k]
Print files to the standard output. The F<k> modifier applies to this
operation. This operation simply prints the F<files> indicated to the
standard output. If no F<files> are specified, the entire archive is printed.
Printing bitcode files is ill-advised as they might confuse your terminal
settings. The F<p> operation never modifies the archive.
=item q[Rfz]
Quickly append files to the end of the archive. The F<R>, F<f>, and F<z>
modifiers apply to this operation. This operation quickly adds the
F<files> to the archive without checking for duplicates that should be
removed first. If no F<files> are specified, the archive is not modified.
Because of the way that B<llvm-ar> constructs the archive file, its dubious
whether the F<q> operation is any faster than the F<r> operation.
=item r[Rabfuz]
Replace or insert file members. The F<R>, F<a>, F<b>, F<f>, F<u>, and F<z>
modifiers apply to this operation. This operation will replace existing
F<files> or insert them at the end of the archive if they do not exist. If no
F<files> are specified, the archive is not modified.
=item t[v]
Print the table of contents. Without any modifiers, this operation just prints
the names of the members to the standard output. With the F<v> modifier,
B<llvm-ar> also prints out the file type (B=bitcode, Z=compressed, S=symbol
table, blank=regular file), the permission mode, the owner and group, the
size, and the date. If any F<files> are specified, the listing is only for
those files. If no F<files> are specified, the table of contents for the
whole archive is printed.
=item x[oP]
Extract archive members back to files. The F<o> modifier applies to this
operation. This operation retrieves the indicated F<files> from the archive
and writes them back to the operating system's file system. If no
F<files> are specified, the entire archive is extract.
=back
=head2 Modifiers (operation specific)
The modifiers below are specific to certain operations. See the Operations
section (above) to determine which modifiers are applicable to which operations.
=over
=item [a]
When inserting or moving member files, this option specifies the destination of
the new files as being C<a>fter the F<relpos> member. If F<relpos> is not found,
the files are placed at the end of the archive.
=item [b]
When inserting or moving member files, this option specifies the destination of
the new files as being C<b>efore the F<relpos> member. If F<relpos> is not
found, the files are placed at the end of the archive. This modifier is
identical to the the F<i> modifier.
=item [f]
Normally, B<llvm-ar> stores the full path name to a file as presented to it on
the command line. With this option, truncated (15 characters max) names are
used. This ensures name compatibility with older versions of C<ar> but may also
thwart correct extraction of the files (duplicates may overwrite). If used with
the F<R> option, the directory recursion will be performed but the file names
will all be C<f>lattened to simple file names.
=item [i]
A synonym for the F<b> option.
=item [k]
Normally, B<llvm-ar> will not print the contents of bitcode files when the
F<p> operation is used. This modifier defeats the default and allows the
bitcode members to be printed.
=item [N]
This option is ignored by B<llvm-ar> but provided for compatibility.
=item [o]
When extracting files, this option will cause B<llvm-ar> to preserve the
original modification times of the files it writes.
=item [P]
use full path names when matching
=item [R]
This modifier instructions the F<r> option to recursively process directories.
Without F<R>, directories are ignored and only those F<files> that refer to
files will be added to the archive. When F<R> is used, any directories specified
with F<files> will be scanned (recursively) to find files to be added to the
archive. Any file whose name begins with a dot will not be added.
=item [u]
When replacing existing files in the archive, only replace those files that have
a time stamp than the time stamp of the member in the archive.
=item [z]
When inserting or replacing any file in the archive, compress the file first.
This
modifier is safe to use when (previously) compressed bitcode files are added to
the archive; the compressed bitcode files will not be doubly compressed.
=back
=head2 Modifiers (generic)
The modifiers below may be applied to any operation.
=over
=item [c]
For all operations, B<llvm-ar> will always create the archive if it doesn't
exist. Normally, B<llvm-ar> will print a warning message indicating that the
archive is being created. Using this modifier turns off that warning.
=item [s]
This modifier requests that an archive index (or symbol table) be added to the
archive. This is the default mode of operation. The symbol table will contain
all the externally visible functions and global variables defined by all the
bitcode files in the archive. Using this modifier is more efficient that using
L<llvm-ranlib|llvm-ranlib> which also creates the symbol table.
=item [S]
This modifier is the opposite of the F<s> modifier. It instructs B<llvm-ar> to
not build the symbol table. If both F<s> and F<S> are used, the last modifier to
occur in the options will prevail.
=item [v]
This modifier instructs B<llvm-ar> to be verbose about what it is doing. Each
editing operation taken against the archive will produce a line of output saying
what is being done.
=back
=head1 STANDARDS
The B<llvm-ar> utility is intended to provide a superset of the IEEE Std 1003.2
(POSIX.2) functionality for C<ar>. B<llvm-ar> can read both SVR4 and BSD4.4 (or
Mac OS X) archives. If the C<f> modifier is given to the C<x> or C<r> operations
then B<llvm-ar> will write SVR4 compatible archives. Without this modifier,
B<llvm-ar> will write BSD4.4 compatible archives that have long names
immediately after the header and indicated using the "#1/ddd" notation for the
name in the header.
=head1 FILE FORMAT
The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
archive files. In fact, except for the symbol table, the C<ar> commands on those
operating systems should be able to read LLVM archive files. The details of the
file format follow.
Each archive begins with the archive magic number which is the eight printable
characters "!<arch>\n" where \n represents the newline character (0x0A).
Following the magic number, the file is composed of even length members that
begin with an archive header and end with a \n padding character if necessary
(to make the length even). Each file member is composed of a header (defined
below), an optional newline-terminated "long file name" and the contents of
the file.
The fields of the header are described in the items below. All fields of the
header contain only ASCII characters, are left justified and are right padded
with space characters.
=over
=item name - char[16]
This field of the header provides the name of the archive member. If the name is
longer than 15 characters or contains a slash (/) character, then this field
contains C<#1/nnn> where C<nnn> provides the length of the name and the C<#1/>
is literal. In this case, the actual name of the file is provided in the C<nnn>
bytes immediately following the header. If the name is 15 characters or less, it
is contained directly in this field and terminated with a slash (/) character.
=item date - char[12]
This field provides the date of modification of the file in the form of a
decimal encoded number that provides the number of seconds since the epoch
(since 00:00:00 Jan 1, 1970) per Posix specifications.
=item uid - char[6]
This field provides the user id of the file encoded as a decimal ASCII string.
This field might not make much sense on non-Unix systems. On Unix, it is the
same value as the st_uid field of the stat structure returned by the stat(2)
operating system call.
=item gid - char[6]
This field provides the group id of the file encoded as a decimal ASCII string.
This field might not make much sense on non-Unix systems. On Unix, it is the
same value as the st_gid field of the stat structure returned by the stat(2)
operating system call.
=item mode - char[8]
This field provides the access mode of the file encoded as an octal ASCII
string. This field might not make much sense on non-Unix systems. On Unix, it
is the same value as the st_mode field of the stat structure returned by the
stat(2) operating system call.
=item size - char[10]
This field provides the size of the file, in bytes, encoded as a decimal ASCII
string. If the size field is negative (starts with a minus sign, 0x02D), then
the archive member is stored in compressed form. The first byte of the archive
member's data indicates the compression type used. A value of 0 (0x30) indicates
that no compression was used. A value of 2 (0x32) indicates that bzip2
compression was used.
=item fmag - char[2]
This field is the archive file member magic number. Its content is always the
two characters back tick (0x60) and newline (0x0A). This provides some measure
utility in identifying archive files that have been corrupted.
=back
The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed
that no regular archive member file will want this name. The LLVM symbol table
is simply composed of a sequence of triplets: byte offset, length of symbol,
and the symbol itself. Symbols are not null or newline terminated. Here are
the details on each of these items:
=over
=item offset - vbr encoded 32-bit integer
The offset item provides the offset into the archive file where the bitcode
member is stored that is associated with the symbol. The offset value is 0
based at the start of the first "normal" file member. To derive the actual
file offset of the member, you must add the number of bytes occupied by the file
signature (8 bytes) and the symbol tables. The value of this item is encoded
using variable bit rate encoding to reduce the size of the symbol table.
Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
if there are more bytes to follow. The remaining 7 bits in each byte carry bits
from the value. The final byte does not have the high bit set.
=item length - vbr encoded 32-bit integer
The length item provides the length of the symbol that follows. Like this
I<offset> item, the length is variable bit rate encoded.
=item symbol - character array
The symbol item provides the text of the symbol that is associated with the
I<offset>. The symbol is not terminated by any character. Its length is provided
by the I<length> field. Note that is allowed (but unwise) to use non-printing
characters (even 0x00) in the symbol. This allows for multiple encodings of
symbol names.
=back
=head1 EXIT STATUS
If B<llvm-ar> succeeds, it will exit with 0. A usage error, results
in an exit code of 1. A hard (file system typically) error results in an
exit code of 2. Miscellaneous or unknown errors result in an
exit code of 3.
=head1 SEE ALSO
L<llvm-ranlib|llvm-ranlib>, ar(1)
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

77
cpp/llvm/docs/CommandGuide/llvm-as.pod
View File

@ -1,77 +0,0 @@
=pod
=head1 NAME
llvm-as - LLVM assembler
=head1 SYNOPSIS
B<llvm-as> [I<options>] [I<filename>]
=head1 DESCRIPTION
B<llvm-as> is the LLVM assembler. It reads a file containing human-readable
LLVM assembly language, translates it to LLVM bitcode, and writes the result
into a file or to standard output.
If F<filename> is omitted or is C<->, then B<llvm-as> reads its input from
standard input.
If an output file is not specified with the B<-o> option, then
B<llvm-as> sends its output to a file or standard output by following
these rules:
=over
=item *
If the input is standard input, then the output is standard output.
=item *
If the input is a file that ends with C<.ll>, then the output file is of
the same name, except that the suffix is changed to C<.bc>.
=item *
If the input is a file that does not end with the C<.ll> suffix, then the
output file has the same name as the input file, except that the C<.bc>
suffix is appended.
=back
=head1 OPTIONS
=over
=item B<-f>
Enable binary output on terminals. Normally, B<llvm-as> will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
B<llvm-as> will write raw bitcode regardless of the output device.
=item B<-help>
Print a summary of command line options.
=item B<-o> F<filename>
Specify the output file name. If F<filename> is C<->, then B<llvm-as>
sends its output to standard output.
=back
=head1 EXIT STATUS
If B<llvm-as> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 SEE ALSO
L<llvm-dis|llvm-dis>, L<gccas|gccas>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

315
cpp/llvm/docs/CommandGuide/llvm-bcanalyzer.pod
View File

@ -1,315 +0,0 @@
=pod
=head1 NAME
llvm-bcanalyzer - LLVM bitcode analyzer
=head1 SYNOPSIS
B<llvm-bcanalyzer> [I<options>] [F<filename>]
=head1 DESCRIPTION
The B<llvm-bcanalyzer> command is a small utility for analyzing bitcode files.
The tool reads a bitcode file (such as generated with the B<llvm-as> tool) and
produces a statistical report on the contents of the bitcode file. The tool
can also dump a low level but human readable version of the bitcode file.
This tool is probably not of much interest or utility except for those working
directly with the bitcode file format. Most LLVM users can just ignore
this tool.
If F<filename> is omitted or is C<->, then B<llvm-bcanalyzer> reads its input
from standard input. This is useful for combining the tool into a pipeline.
Output is written to the standard output.
=head1 OPTIONS
=over
=item B<-nodetails>
Causes B<llvm-bcanalyzer> to abbreviate its output by writing out only a module
level summary. The details for individual functions are not displayed.
=item B<-dump>
Causes B<llvm-bcanalyzer> to dump the bitcode in a human readable format. This
format is significantly different from LLVM assembly and provides details about
the encoding of the bitcode file.
=item B<-verify>
Causes B<llvm-bcanalyzer> to verify the module produced by reading the
bitcode. This ensures that the statistics generated are based on a consistent
module.
=item B<-help>
Print a summary of command line options.
=back
=head1 EXIT STATUS
If B<llvm-bcanalyzer> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value, usually 1.
=head1 SUMMARY OUTPUT DEFINITIONS
The following items are always printed by llvm-bcanalyzer. They comprize the
summary output.
=over
=item B<Bitcode Analysis Of Module>
This just provides the name of the module for which bitcode analysis is being
generated.
=item B<Bitcode Version Number>
The bitcode version (not LLVM version) of the file read by the analyzer.
=item B<File Size>
The size, in bytes, of the entire bitcode file.
=item B<Module Bytes>
The size, in bytes, of the module block. Percentage is relative to File Size.
=item B<Function Bytes>
The size, in bytes, of all the function blocks. Percentage is relative to File
Size.
=item B<Global Types Bytes>
The size, in bytes, of the Global Types Pool. Percentage is relative to File
Size. This is the size of the definitions of all types in the bitcode file.
=item B<Constant Pool Bytes>
The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
Size.
=item B<Module Globals Bytes>
Ths size, in bytes, of the Global Variable Definitions and their initializers.
Percentage is relative to File Size.
=item B<Instruction List Bytes>
The size, in bytes, of all the instruction lists in all the functions.
Percentage is relative to File Size. Note that this value is also included in
the Function Bytes.
=item B<Compaction Table Bytes>
The size, in bytes, of all the compaction tables in all the functions.
Percentage is relative to File Size. Note that this value is also included in
the Function Bytes.
=item B<Symbol Table Bytes>
The size, in bytes, of all the symbol tables in all the functions. Percentage is
relative to File Size. Note that this value is also included in the Function
Bytes.
=item B<Dependent Libraries Bytes>
The size, in bytes, of the list of dependent libraries in the module. Percentage
is relative to File Size. Note that this value is also included in the Module
Global Bytes.
=item B<Number Of Bitcode Blocks>
The total number of blocks of any kind in the bitcode file.
=item B<Number Of Functions>
The total number of function definitions in the bitcode file.
=item B<Number Of Types>
The total number of types defined in the Global Types Pool.
=item B<Number Of Constants>
The total number of constants (of any type) defined in the Constant Pool.
=item B<Number Of Basic Blocks>
The total number of basic blocks defined in all functions in the bitcode file.
=item B<Number Of Instructions>
The total number of instructions defined in all functions in the bitcode file.
=item B<Number Of Long Instructions>
The total number of long instructions defined in all functions in the bitcode
file. Long instructions are those taking greater than 4 bytes. Typically long
instructions are GetElementPtr with several indices, PHI nodes, and calls to
functions with large numbers of arguments.
=item B<Number Of Operands>
The total number of operands used in all instructions in the bitcode file.
=item B<Number Of Compaction Tables>
The total number of compaction tables in all functions in the bitcode file.
=item B<Number Of Symbol Tables>
The total number of symbol tables in all functions in the bitcode file.
=item B<Number Of Dependent Libs>
The total number of dependent libraries found in the bitcode file.
=item B<Total Instruction Size>
The total size of the instructions in all functions in the bitcode file.
=item B<Average Instruction Size>
The average number of bytes per instruction across all functions in the bitcode
file. This value is computed by dividing Total Instruction Size by Number Of
Instructions.
=item B<Maximum Type Slot Number>
The maximum value used for a type's slot number. Larger slot number values take
more bytes to encode.
=item B<Maximum Value Slot Number>
The maximum value used for a value's slot number. Larger slot number values take
more bytes to encode.
=item B<Bytes Per Value>
The average size of a Value definition (of any type). This is computed by
dividing File Size by the total number of values of any type.
=item B<Bytes Per Global>
The average size of a global definition (constants and global variables).
=item B<Bytes Per Function>
The average number of bytes per function definition. This is computed by
dividing Function Bytes by Number Of Functions.
=item B<# of VBR 32-bit Integers>
The total number of 32-bit integers encoded using the Variable Bit Rate
encoding scheme.
=item B<# of VBR 64-bit Integers>
The total number of 64-bit integers encoded using the Variable Bit Rate encoding
scheme.
=item B<# of VBR Compressed Bytes>
The total number of bytes consumed by the 32-bit and 64-bit integers that use
the Variable Bit Rate encoding scheme.
=item B<# of VBR Expanded Bytes>
The total number of bytes that would have been consumed by the 32-bit and 64-bit
integers had they not been compressed with the Variable Bit Rage encoding
scheme.
=item B<Bytes Saved With VBR>
The total number of bytes saved by using the Variable Bit Rate encoding scheme.
The percentage is relative to # of VBR Expanded Bytes.
=back
=head1 DETAILED OUTPUT DEFINITIONS
The following definitions occur only if the -nodetails option was not given.
The detailed output provides additional information on a per-function basis.
=over
=item B<Type>
The type signature of the function.
=item B<Byte Size>
The total number of bytes in the function's block.
=item B<Basic Blocks>
The number of basic blocks defined by the function.
=item B<Instructions>
The number of instructions defined by the function.
=item B<Long Instructions>
The number of instructions using the long instruction format in the function.
=item B<Operands>
The number of operands used by all instructions in the function.
=item B<Instruction Size>
The number of bytes consumed by instructions in the function.
=item B<Average Instruction Size>
The average number of bytes consumed by the instructions in the function. This
value is computed by dividing Instruction Size by Instructions.
=item B<Bytes Per Instruction>
The average number of bytes used by the function per instruction. This value is
computed by dividing Byte Size by Instructions. Note that this is not the same
as Average Instruction Size. It computes a number relative to the total function
size not just the size of the instruction list.
=item B<Number of VBR 32-bit Integers>
The total number of 32-bit integers found in this function (for any use).
=item B<Number of VBR 64-bit Integers>
The total number of 64-bit integers found in this function (for any use).
=item B<Number of VBR Compressed Bytes>
The total number of bytes in this function consumed by the 32-bit and 64-bit
integers that use the Variable Bit Rate encoding scheme.
=item B<Number of VBR Expanded Bytes>
The total number of bytes in this function that would have been consumed by
the 32-bit and 64-bit integers had they not been compressed with the Variable
Bit Rate encoding scheme.
=item B<Bytes Saved With VBR>
The total number of bytes saved in this function by using the Variable Bit
Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.
=back
=head1 SEE ALSO
L<llvm-dis|llvm-dis>, L<http://llvm.org/docs/BitCodeFormat.html>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

86
cpp/llvm/docs/CommandGuide/llvm-build.pod
View File

@ -1,86 +0,0 @@
=pod
=head1 NAME
llvm-build - LLVM Project Build Utility
=head1 SYNOPSIS
B<llvm-build> [I<options>]
=head1 DESCRIPTION
B<llvm-build> is a tool for working with LLVM projects that use the LLVMBuild
system for describing their components.
At heart, B<llvm-build> is responsible for loading, verifying, and manipulating
the project's component data. The tool is primarily designed for use in
implementing build systems and tools which need access to the project structure
information.
=head1 OPTIONS
=over
=item B<-h>, B<--help>
Print the builtin program help.
=item B<--source-root>=I<PATH>
If given, load the project at the given source root path. If this option is not
given, the location of the project sources will be inferred from the location of
the B<llvm-build> script itself.
=item B<--print-tree>
Print the component tree for the project.
=item B<--write-library-table>
Write out the C++ fragment which defines the components, library names, and
required libraries. This C++ fragment is built into L<llvm-config|llvm-config>
in order to provide clients with the list of required libraries for arbitrary
component combinations.
=item B<--write-llvmbuild>
Write out new I<LLVMBuild.txt> files based on the loaded components. This is
useful for auto-upgrading the schema of the files. B<llvm-build> will try to a
limited extent to preserve the comments which were written in the original
source file, although at this time it only preserves block comments that preceed
the section names in the I<LLVMBuild> files.
=item B<--write-cmake-fragment>
Write out the LLVMBuild in the form of a CMake fragment, so it can easily be
consumed by the CMake based build system. The exact contents and format of this
file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's
top-level CMakeLists.txt.
=item B<--write-make-fragment>
Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be
consumed by a Make based build system. The exact contents and format of this
file are closely tied to how LLVMBuild is integrated with the Makefiles, see
LLVM's Makefile.rules.
=item B<--llvmbuild-source-root>=I<PATH>
If given, expect the I<LLVMBuild> files for the project to be rooted at the
given path, instead of inside the source tree itself. This option is primarily
designed for use in conjunction with B<--write-llvmbuild> to test changes to
I<LLVMBuild> schema.
=back
=head1 EXIT STATUS
B<llvm-build> exits with 0 if operation was successful. Otherwise, it will exist
with a non-zero value.
=head1 AUTHOR
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

131
cpp/llvm/docs/CommandGuide/llvm-config.pod
View File

@ -1,131 +0,0 @@
=pod
=head1 NAME
llvm-config - Print LLVM compilation options
=head1 SYNOPSIS
B<llvm-config> I<option> [I<components>...]
=head1 DESCRIPTION
B<llvm-config> makes it easier to build applications that use LLVM. It can
print the compiler flags, linker flags and object libraries needed to link
against LLVM.
=head1 EXAMPLES
To link against the JIT:
g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
`llvm-config --libs engine bcreader scalaropts`
=head1 OPTIONS
=over
=item B<--version>
Print the version number of LLVM.
=item B<-help>
Print a summary of B<llvm-config> arguments.
=item B<--prefix>
Print the installation prefix for LLVM.
=item B<--src-root>
Print the source root from which LLVM was built.
=item B<--obj-root>
Print the object root used to build LLVM.
=item B<--bindir>
Print the installation directory for LLVM binaries.
=item B<--includedir>
Print the installation directory for LLVM headers.
=item B<--libdir>
Print the installation directory for LLVM libraries.
=item B<--cxxflags>
Print the C++ compiler flags needed to use LLVM headers.
=item B<--ldflags>
Print the flags needed to link against LLVM libraries.
=item B<--libs>
Print all the libraries needed to link against the specified LLVM
I<components>, including any dependencies.
=item B<--libnames>
Similar to B<--libs>, but prints the bare filenames of the libraries
without B<-l> or pathnames. Useful for linking against a not-yet-installed
copy of LLVM.
=item B<--libfiles>
Similar to B<--libs>, but print the full path to each library file. This is
useful when creating makefile dependencies, to ensure that a tool is relinked if
any library it uses changes.
=item B<--components>
Print all valid component names.
=item B<--targets-built>
Print the component names for all targets supported by this copy of LLVM.
=item B<--build-mode>
Print the build mode used when LLVM was built (e.g. Debug or Release)
=back
=head1 COMPONENTS
To print a list of all available components, run B<llvm-config
--components>. In most cases, components correspond directly to LLVM
libraries. Useful "virtual" components include:
=over
=item B<all>
Includes all LLVM libaries. The default if no components are specified.
=item B<backend>
Includes either a native backend or the C backend.
=item B<engine>
Includes either a native JIT or the bitcode interpreter.
=back
=head1 EXIT STATUS
If B<llvm-config> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

45
cpp/llvm/docs/CommandGuide/llvm-cov.pod
View File

@ -1,45 +0,0 @@
=pod
=head1 NAME
llvm-cov - emit coverage information
=head1 SYNOPSIS
B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump]
=head1 DESCRIPTION
The experimental B<llvm-cov> tool reads in description file generated by compiler
and coverage data file generated by instrumented program. This program assumes
that the description and data file uses same format as gcov files.
=head1 OPTIONS
=over
=item B<-gcno=filename]
This option selects input description file generated by compiler while instrumenting
program.
=item B<-gcda=filename]
This option selects coverage data file generated by instrumented compiler.
=item B<-dump>
This options enables output dump that is suitable for a developer to help debug
B<llvm-cov> itself.
=back
=head1 EXIT STATUS
B<llvm-cov> returns 1 if it cannot read input files. Otherwise, it exits with zero.
=head1 AUTHOR
B<llvm-cov> is maintained by the LLVM Team (L<http://llvm.org/>).
=cut

53
cpp/llvm/docs/CommandGuide/llvm-diff.pod
View File

@ -1,53 +0,0 @@
=pod
=head1 NAME
llvm-diff - LLVM structural 'diff'
=head1 SYNOPSIS
B<llvm-diff> [I<options>] I<module 1> I<module 2> [I<global name ...>]
=head1 DESCRIPTION
B<llvm-diff> compares the structure of two LLVM modules, primarily
focusing on differences in function definitions. Insignificant
differences, such as changes in the ordering of globals or in the
names of local values, are ignored.
An input module will be interpreted as an assembly file if its name
ends in '.ll'; otherwise it will be read in as a bitcode file.
If a list of global names is given, just the values with those names
are compared; otherwise, all global values are compared, and
diagnostics are produced for globals which only appear in one module
or the other.
B<llvm-diff> compares two functions by comparing their basic blocks,
beginning with the entry blocks. If the terminators seem to match,
then the corresponding successors are compared; otherwise they are
ignored. This algorithm is very sensitive to changes in control flow,
which tend to stop any downstream changes from being detected.
B<llvm-diff> is intended as a debugging tool for writers of LLVM
passes and frontends. It does not have a stable output format.
=head1 EXIT STATUS
If B<llvm-diff> finds no differences between the modules, it will exit
with 0 and produce no output. Otherwise it will exit with a non-zero
value.
=head1 BUGS
Many important differences, like changes in linkage or function
attributes, are not diagnosed.
Changes in memory behavior (for example, coalescing loads) can cause
massive detected differences in blocks.
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

60
cpp/llvm/docs/CommandGuide/llvm-dis.pod
View File

@ -1,60 +0,0 @@
=pod
=head1 NAME
llvm-dis - LLVM disassembler
=head1 SYNOPSIS
B<llvm-dis> [I<options>] [I<filename>]
=head1 DESCRIPTION
The B<llvm-dis> command is the LLVM disassembler. It takes an LLVM
bitcode file and converts it into human-readable LLVM assembly language.
If filename is omitted or specified as C<->, B<llvm-dis> reads its
input from standard input.
If the input is being read from standard input, then B<llvm-dis>
will send its output to standard output by default. Otherwise, the
output will be written to a file named after the input file, with
a C<.ll> suffix added (any existing C<.bc> suffix will first be
removed). You can override the choice of output file using the
B<-o> option.
=head1 OPTIONS
=over
=item B<-f>
Enable binary output on terminals. Normally, B<llvm-dis> will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
B<llvm-dis> will write raw bitcode regardless of the output device.
=item B<-help>
Print a summary of command line options.
=item B<-o> F<filename>
Specify the output file name. If F<filename> is -, then the output is sent
to standard output.
=back
=head1 EXIT STATUS
If B<llvm-dis> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 SEE ALSO
L<llvm-as|llvm-as>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

85
cpp/llvm/docs/CommandGuide/llvm-extract.pod
View File

@ -1,85 +0,0 @@
=pod
=head1 NAME
llvm-extract - extract a function from an LLVM module
=head1 SYNOPSIS
B<llvm-extract> [I<options>] B<--func> I<function-name> [I<filename>]
=head1 DESCRIPTION
The B<llvm-extract> command takes the name of a function and extracts it from
the specified LLVM bitcode file. It is primarily used as a debugging tool to
reduce test cases from larger programs that are triggering a bug.
In addition to extracting the bitcode of the specified function,
B<llvm-extract> will also remove unreachable global variables, prototypes, and
unused types.
The B<llvm-extract> command reads its input from standard input if filename is
omitted or if filename is -. The output is always written to standard output,
unless the B<-o> option is specified (see below).
=head1 OPTIONS
=over
=item B<-f>
Enable binary output on terminals. Normally, B<llvm-extract> will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
B<llvm-extract> will write raw bitcode regardless of the output device.
=item B<--func> I<function-name>
Extract the function named I<function-name> from the LLVM bitcode. May be
specified multiple times to extract multiple functions at once.
=item B<--rfunc> I<function-regular-expr>
Extract the function(s) matching I<function-regular-expr> from the LLVM bitcode.
All functions matching the regular expression will be extracted. May be
specified multiple times.
=item B<--glob> I<global-name>
Extract the global variable named I<global-name> from the LLVM bitcode. May be
specified multiple times to extract multiple global variables at once.
=item B<--rglob> I<glob-regular-expr>
Extract the global variable(s) matching I<global-regular-expr> from the LLVM
bitcode. All global variables matching the regular expression will be extracted.
May be specified multiple times.
=item B<-help>
Print a summary of command line options.
=item B<-o> I<filename>
Specify the output filename. If filename is "-" (the default), then
B<llvm-extract> sends its output to standard output.
=item B<-S>
Write output in LLVM intermediate language (instead of bitcode).
=back
=head1 EXIT STATUS
If B<llvm-extract> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 SEE ALSO
L<bugpoint|bugpoint>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

234
cpp/llvm/docs/CommandGuide/llvm-ld.pod
View File

@ -1,234 +0,0 @@
=pod
=head1 NAME
llvm-ld - LLVM linker
=head1 SYNOPSIS
B<llvm-ld> <options> <files>
=head1 DESCRIPTION
The B<llvm-ld> tool takes a set of LLVM bitcode files and links them
together into a single LLVM bitcode file. The output bitcode file can be
another bitcode file or an executable bitcode program. Using additional
options, B<llvm-ld> is able to produce native code executables.
The B<llvm-ld> tool is the main linker for LLVM. It is used to link together
the output of LLVM front-end compilers and run "link time" optimizations (mostly
the inter-procedural kind).
The B<llvm-ld> tools attempts to mimic the interface provided by the default
system linker so that it can act as a I<drop-in> replacement.
=head2 Search Order
When looking for objects specified on the command line, B<llvm-ld> will search
for the object first in the current directory and then in the directory
specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it cannot
find the object, it fails.
When looking for a library specified with the B<-l> option, B<llvm-ld> first
attempts to load a file with that name from the current directory. If that
fails, it looks for libI<library>.bc, libI<library>.a, or libI<library>.I<shared
library extension>, in that order, in each directory added to the library search
path with the B<-L> option. These directories are searched in the order they
are specified. If the library cannot be located, then B<llvm-ld> looks in the
directory specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it
does not find a library there, it fails.
The I<shared library extension> may be I<.so>, I<.dyld>, I<.dll>, or something
different, depending upon the system.
The B<-L> option is global. It does not matter where it is specified in the
list of command line arguments; the directory is simply added to the search path
and is applied to all libraries, preceding or succeeding, in the command line.
=head2 Link order
All object and bitcode files are linked first in the order they were
specified on the command line. All library files are linked next.
Some libraries may not be linked into the object program; see below.
=head2 Library Linkage
Object files and static bitcode objects are always linked into the output
file. Library archives (.a files) load only the objects within the archive
that define symbols needed by the output file. Hence, libraries should be
listed after the object files and libraries which need them; otherwise, the
library may not be linked in, and the dependent library will not have its
undefined symbols defined.
=head2 Native code generation
The B<llvm-ld> program has limited support for native code generation, when
using the B<-native> or B<-native-cbe> options. Native code generation is
performed by converting the linked bitcode into native assembly (.s) or C code
and running the system compiler (typically gcc) on the result.
=head1 OPTIONS
=head2 General Options
=over
=item B<-help>
Print a summary of command line options.
=item B<-v>
Specifies verbose mode. In this mode the linker will print additional
information about the actions it takes, programs it executes, etc.
=item B<-stats>
Print statistics.
=item B<-time-passes>
Record the amount of time needed for each pass and print it to standard
error.
=back
=head2 Input/Output Options
=over
=item B<-o> F<filename>
This overrides the default output file and specifies the name of the file that
should be generated by the linker. By default, B<llvm-ld> generates a file named
F<a.out> for compatibility with B<ld>. The output will be written to
F<filename>.
=item B<-b> F<filename>
This option can be used to override the output bitcode file name. By default,
the name of the bitcode output file is one more ".bc" suffix added to the name
specified by B<-o filename> option.
=item B<-l>F<name>
This option specifies the F<name> of a library to search when resolving symbols
for the program. Only the base name should be specified as F<name>, without a
F<lib> prefix or any suffix.
=item B<-L>F<Path>
This option tells B<llvm-ld> to look in F<Path> to find any library subsequently
specified with the B<-l> option. The paths will be searched in the order in
which they are specified on the command line. If the library is still not found,
a small set of system specific directories will also be searched. Note that
libraries specified with the B<-l> option that occur I<before> any B<-L> options
will not search the paths given by the B<-L> options following it.
=item B<-link-as-library>
Link the bitcode files together as a library, not an executable. In this mode,
undefined symbols will be permitted.
=item B<-r>
An alias for -link-as-library.
=item B<-native>
Generate a native machine code executable.
When generating native executables, B<llvm-ld> first checks for a bitcode
version of the library and links it in, if necessary. If the library is
missing, B<llvm-ld> skips it. Then, B<llvm-ld> links in the same
libraries as native code.
In this way, B<llvm-ld> should be able to link in optimized bitcode
subsets of common libraries and then link in any part of the library that
hasn't been converted to bitcode.
=item B<-native-cbe>
Generate a native machine code executable with the LLVM C backend.
This option is identical to the B<-native> option, but uses the
C backend to generate code for the program instead of an LLVM native
code generator.
=back
=head2 Optimization Options
=over
=item B<-disable-inlining>
Do not run the inlining pass. Functions will not be inlined into other
functions.
=item B<-disable-opt>
Completely disable optimization.
=item B<-disable-internalize>
Do not mark all symbols as internal.
=item B<-verify-each>
Run the verification pass after each of the passes to verify intermediate
results.
=item B<-strip-all>
Strip all debug and symbol information from the executable to make it smaller.
=item B<-strip-debug>
Strip all debug information from the executable to make it smaller.
=item B<-s>
An alias for B<-strip-all>.
=item B<-S>
An alias for B<-strip-debug>.
=item B<-export-dynamic>
An alias for B<-disable-internalize>
=item B<-post-link-opt>F<Path>
Run post-link optimization program. After linking is completed a bitcode file
will be generated. It will be passed to the program specified by F<Path> as the
first argument. The second argument to the program will be the name of a
temporary file into which the program should place its optimized output. For
example, the "no-op optimization" would be a simple shell script:
#!/bin/bash
cp $1 $2
=back
=head1 EXIT STATUS
If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs,
it will exit with a non-zero return code.
=head1 ENVIRONMENT
The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bitcode
libraries. Any paths specified in this variable will be searched after the C<-L>
options.
=head1 SEE ALSO
L<llvm-link|llvm-link>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

79
cpp/llvm/docs/CommandGuide/llvm-link.pod
View File

@ -1,79 +0,0 @@
=pod
=head1 NAME
llvm-link - LLVM linker
=head1 SYNOPSIS
B<llvm-link> [I<options>] I<filename ...>
=head1 DESCRIPTION
B<llvm-link> takes several LLVM bitcode files and links them together into a
single LLVM bitcode file. It writes the output file to standard output, unless
the B<-o> option is used to specify a filename.
B<llvm-link> attempts to load the input files from the current directory. If
that fails, it looks for each file in each of the directories specified by the
B<-L> options on the command line. The library search paths are global; each
one is searched for every input file if necessary. The directories are searched
in the order they were specified on the command line.
=head1 OPTIONS
=over
=item B<-L> F<directory>
Add the specified F<directory> to the library search path. When looking for
libraries, B<llvm-link> will look in path name for libraries. This option can be
specified multiple times; B<llvm-link> will search inside these directories in
the order in which they were specified on the command line.
=item B<-f>
Enable binary output on terminals. Normally, B<llvm-link> will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
B<llvm-link> will write raw bitcode regardless of the output device.
=item B<-o> F<filename>
Specify the output file name. If F<filename> is C<->, then B<llvm-link> will
write its output to standard output.
=item B<-S>
Write output in LLVM intermediate language (instead of bitcode).
=item B<-d>
If specified, B<llvm-link> prints a human-readable version of the output
bitcode file to standard error.
=item B<-help>
Print a summary of command line options.
=item B<-v>
Verbose mode. Print information about what B<llvm-link> is doing. This
typically includes a message for each bitcode file linked in and for each
library found.
=back
=head1 EXIT STATUS
If B<llvm-link> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 SEE ALSO
L<gccld|gccld>
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

122
cpp/llvm/docs/CommandGuide/llvm-nm.pod
View File

@ -1,122 +0,0 @@
=pod
=head1 NAME
llvm-nm - list LLVM bitcode file's symbol table
=head1 SYNOPSIS
B<llvm-nm> [I<options>] [I<filenames...>]
=head1 DESCRIPTION
The B<llvm-nm> utility lists the names of symbols from the LLVM bitcode files,
or B<ar> archives containing LLVM bitcode files, named on the command line.
Each symbol is listed along with some simple information about its provenance.
If no file name is specified, or I<-> is used as a file name, B<llvm-nm> will
process a bitcode file on its standard input stream.
B<llvm-nm>'s default output format is the traditional BSD B<nm> output format.
Each such output record consists of an (optional) 8-digit hexadecimal address,
followed by a type code character, followed by a name, for each symbol. One
record is printed per line; fields are separated by spaces. When the address is
omitted, it is replaced by 8 spaces.
Type code characters currently supported, and their meanings, are as follows:
=over
=item U
Named object is referenced but undefined in this bitcode file
=item C
Common (multiple definitions link together into one def)
=item W
Weak reference (multiple definitions link together into zero or one definitions)
=item t
Local function (text) object
=item T
Global function (text) object
=item d
Local data object
=item D
Global data object
=item ?
Something unrecognizable
=back
Because LLVM bitcode files typically contain objects that are not considered to
have addresses until they are linked into an executable image or dynamically
compiled "just-in-time", B<llvm-nm> does not print an address for any symbol,
even symbols which are defined in the bitcode file.
=head1 OPTIONS
=over
=item B<-P>
Use POSIX.2 output format. Alias for B<--format=posix>.
=item B<-B> (default)
Use BSD output format. Alias for B<--format=bsd>.
=item B<-help>
Print a summary of command-line options and their meanings.
=item B<--defined-only>
Print only symbols defined in this bitcode file (as opposed to
symbols which may be referenced by objects in this file, but not
defined in this file.)
=item B<--extern-only>, B<-g>
Print only symbols whose definitions are external; that is, accessible
from other bitcode files.
=item B<--undefined-only>, B<-u>
Print only symbols referenced but not defined in this bitcode file.
=item B<--format=>I<fmt>, B<-f>
Select an output format; I<fmt> may be I<sysv>, I<posix>, or I<bsd>. The
default is I<bsd>.
=back
=head1 BUGS
B<llvm-nm> cannot demangle C++ mangled names, like GNU B<nm> can.
=head1 EXIT STATUS
B<llvm-nm> exits with an exit code of zero.
=head1 SEE ALSO
L<llvm-dis|llvm-dis>, ar(1), nm(1)
=head1 AUTHOR
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

57
cpp/llvm/docs/CommandGuide/llvm-prof.pod
View File

@ -1,57 +0,0 @@
=pod
=head1 NAME
llvm-prof - print execution profile of LLVM program
=head1 SYNOPSIS
B<llvm-prof> [I<options>] [I<bitcode file>] [I<llvmprof.out>]
=head1 DESCRIPTION
The B<llvm-prof> tool reads in an F<llvmprof.out> file (which can
optionally use a specific file with the third program argument), a bitcode file
for the program, and produces a human readable report, suitable for determining
where the program hotspots are.
This program is often used in conjunction with the F<utils/profile.pl>
script. This script automatically instruments a program, runs it with the JIT,
then runs B<llvm-prof> to format a report. To get more information about
F<utils/profile.pl>, execute it with the B<-help> option.
=head1 OPTIONS
=over
=item B<--annotated-llvm> or B<-A>
In addition to the normal report printed, print out the code for the
program, annotated with execution frequency information. This can be
particularly useful when trying to visualize how frequently basic blocks
are executed. This is most useful with basic block profiling
information or better.
=item B<--print-all-code>
Using this option enables the B<--annotated-llvm> option, but it
prints the entire module, instead of just the most commonly executed
functions.
=item B<--time-passes>
Record the amount of time needed for each pass and print it to standard
error.
=back
=head1 EXIT STATUS
B<llvm-prof> returns 1 if it cannot load the bitcode file or the profile
information. Otherwise, it exits with zero.
=head1 AUTHOR
B<llvm-prof> is maintained by the LLVM Team (L<http://llvm.org/>).
=cut

52
cpp/llvm/docs/CommandGuide/llvm-ranlib.pod
View File

@ -1,52 +0,0 @@
=pod
=head1 NAME
llvm-ranlib - Generate index for LLVM archive
=head1 SYNOPSIS
B<llvm-ranlib> [--version] [-help] <archive-file>
=head1 DESCRIPTION
The B<llvm-ranlib> command is similar to the common Unix utility, C<ranlib>. It
adds or updates the symbol table in an LLVM archive file. Note that using the
B<llvm-ar> modifier F<s> is usually more efficient than running B<llvm-ranlib>
which is only provided only for completness and compatibility. Unlike other
implementations of C<ranlib>, B<llvm-ranlib> indexes LLVM bitcode files, not
native object modules. You can list the contents of the symbol table with the
C<llvm-nm -s> command.
=head1 OPTIONS
=over
=item F<archive-file>
Specifies the archive-file to which the symbol table is added or updated.
=item F<--version>
Print the version of B<llvm-ranlib> and exit without building a symbol table.
=item F<-help>
Print usage help for B<llvm-ranlib> and exit without building a symbol table.
=back
=head1 EXIT STATUS
If B<llvm-ranlib> succeeds, it will exit with 0. If an error occurs, a non-zero
exit code will be returned.
=head1 SEE ALSO
L<llvm-ar|llvm-ar>, ranlib(1)
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

42
cpp/llvm/docs/CommandGuide/llvm-stress.pod
View File

@ -1,42 +0,0 @@
=pod
=head1 NAME
llvm-stress - generate random .ll files
=head1 SYNOPSIS
B<llvm-cov> [-gcno=filename] [-gcda=filename] [dump]
=head1 DESCRIPTION
The B<llvm-stress> tool is used to generate random .ll files that can be used to
test different components of LLVM.
=head1 OPTIONS
=over
=item B<-o> I<filename>
Specify the output filename.
=item B<-size> I<size>
Specify the size of the generated .ll file.
=item B<-seed> I<seed>
Specify the seed to be used for the randomly generated instructions.
=back
=head1 EXIT STATUS
B<llvm-stress> returns 0.
=head1 AUTHOR
B<llvm-stress> is maintained by the LLVM Team (L<http://llvm.org/>).
=cut

256
cpp/llvm/docs/CommandGuide/manpage.css
View File

@ -1,256 +0,0 @@
/* Based on http://www.perldoc.com/css/perldoc.css */
@import url("../llvm.css");
body { font-family: Arial,Helvetica; }
blockquote { margin: 10pt; }
h1, a { color: #336699; }
/*** Top menu style ****/
.mmenuon {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ff6600; font-size: 10pt;
}
.mmenuoff {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: 10pt;
}
.cpyright {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: xx-small;
}
.cpyrightText {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: xx-small;
}
.sections {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 11pt;
}
.dsections {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 12pt;
}
.slink {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #000000; font-size: 9pt;
}
.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; }
.maintitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 18pt;
}
.dblArrow {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
.menuSec {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
.newstext {
font-family: Arial,Helvetica; font-size: small;
}
.linkmenu {
font-family: Arial,Helvetica; color: #000000; font-weight: bold;
text-decoration: none;
}
P {
font-family: Arial,Helvetica;
}
PRE {
font-size: 10pt;
}
.quote {
font-family: Times; text-decoration: none;
color: #000000; font-size: 9pt; font-style: italic;
}
.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; }
.std { font-family: Arial,Helvetica; color: #000000; }
.meerkatTitle {
font-family: sans-serif; font-size: x-small; color: black; }
.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black }
.meerkatCategory {
font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic;
color: brown; }
.meerkatChannel {
font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; }
.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; }
.tocTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 10pt;
}
.toc-item {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt; text-decoration: underline;
}
.perlVersion {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt; text-decoration: none;
}
.podTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #000000;
}
.docTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #000000; font-size: 10pt;
}
.dotDot {
font-family: Arial,Helvetica; font-weight: bold;
color: #000000; font-size: 9pt;
}
.docSec {
font-family: Arial,Helvetica; font-weight: normal;
color: #333333; font-size: 9pt;
}
.docVersion {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 10pt;
}
.docSecs-on {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #ff0000; font-size: 10pt;
}
.docSecs-off {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #333333; font-size: 10pt;
}
h2 {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: medium;
}
h1 {
font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: large;
}
DL {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #333333; font-size: 10pt;
}
UL > LI > A {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt;
}
.moduleInfo {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 11pt;
}
.moduleInfoSec {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 10pt;
}
.moduleInfoVal {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline;
color: #000000; font-size: 10pt;
}
.cpanNavTitle {
font-family: Arial,Helvetica; font-weight: bold;
color: #ffffff; font-size: 10pt;
}
.cpanNavLetter {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 9pt;
}
.cpanCat {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 9pt;
}
.bttndrkblue-bkgd-top {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif);
}
.bttndrkblue-bkgd-left {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif);
}
.bttndrkblue-bkgd {
padding-top: 0px;
padding-bottom: 0px;
margin-bottom: 0px;
margin-top: 0px;
background-repeat: no-repeat;
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif);
vertical-align: top;
}
.bttndrkblue-bkgd-right {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif);
}
.bttndrkblue-bkgd-bottom {
background-color: #225688;
background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif);
}
.bttndrkblue-text a {
color: #ffffff;
text-decoration: none;
}
a.bttndrkblue-text:hover {
color: #ffDD3C;
text-decoration: none;
}
.bg-ltblue {
background-color: #f0f5fa;
}
.border-left-b {
background: #f0f5fa url(/i/corner-leftline.gif) repeat-y;
}
.border-right-b {
background: #f0f5fa url(/i/corner-rightline.gif) repeat-y;
}
.border-top-b {
background: #f0f5fa url(/i/corner-topline.gif) repeat-x;
}
.border-bottom-b {
background: #f0f5fa url(/i/corner-botline.gif) repeat-x;
}
.border-right-w {
background: #ffffff url(/i/corner-rightline.gif) repeat-y;
}
.border-top-w {
background: #ffffff url(/i/corner-topline.gif) repeat-x;
}
.border-bottom-w {
background: #ffffff url(/i/corner-botline.gif) repeat-x;
}
.bg-white {
background-color: #ffffff;
}
.border-left-w {
background: #ffffff url(/i/corner-leftline.gif) repeat-y;
}

143
cpp/llvm/docs/CommandGuide/opt.pod
View File

@ -1,143 +0,0 @@
=pod
=head1 NAME
opt - LLVM optimizer
=head1 SYNOPSIS
B<opt> [I<options>] [I<filename>]
=head1 DESCRIPTION
The B<opt> command is the modular LLVM optimizer and analyzer. It takes LLVM
source files as input, runs the specified optimizations or analyses on it, and then
outputs the optimized file or the analysis results. The function of
B<opt> depends on whether the B<-analyze> option is given.
When B<-analyze> is specified, B<opt> performs various analyses of the input
source. It will usually print the results on standard output, but in a few
cases, it will print output to standard error or generate a file with the
analysis output, which is usually done when the output is meant for another
program.
While B<-analyze> is I<not> given, B<opt> attempts to produce an optimized
output file. The optimizations available via B<opt> depend upon what
libraries were linked into it as well as any additional libraries that have
been loaded with the B<-load> option. Use the B<-help> option to determine
what optimizations you can use.
If I<filename> is omitted from the command line or is I<->, B<opt> reads its
input from standard input. Inputs can be in either the LLVM assembly language
format (.ll) or the LLVM bitcode format (.bc).
If an output filename is not specified with the B<-o> option, B<opt>
writes its output to the standard output.
=head1 OPTIONS
=over
=item B<-f>
Enable binary output on terminals. Normally, B<opt> will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
B<opt> will write raw bitcode regardless of the output device.
=item B<-help>
Print a summary of command line options.
=item B<-o> I<filename>
Specify the output filename.
=item B<-S>
Write output in LLVM intermediate language (instead of bitcode).
=item B<-{passname}>
B<opt> provides the ability to run any of LLVM's optimization or analysis passes
in any order. The B<-help> option lists all the passes available. The order in
which the options occur on the command line are the order in which they are
executed (within pass constraints).
=item B<-std-compile-opts>
This is short hand for a standard list of I<compile time optimization> passes.
This is typically used to optimize the output from the llvm-gcc front end. It
might be useful for other front end compilers as well. To discover the full set
of options available, use the following command:
llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments
=item B<-disable-inlining>
This option is only meaningful when B<-std-compile-opts> is given. It simply
removes the inlining pass from the standard list.
=item B<-disable-opt>
This option is only meaningful when B<-std-compile-opts> is given. It disables
most, but not all, of the B<-std-compile-opts>. The ones that remain are
B<-verify>, B<-lower-setjmp>, and B<-funcresolve>.
=item B<-strip-debug>
This option causes opt to strip debug information from the module before
applying other optimizations. It is essentially the same as B<-strip> but it
ensures that stripping of debug information is done first.
=item B<-verify-each>
This option causes opt to add a verify pass after every pass otherwise specified
on the command line (including B<-verify>). This is useful for cases where it
is suspected that a pass is creating an invalid module but it is not clear which
pass is doing it. The combination of B<-std-compile-opts> and B<-verify-each>
can quickly track down this kind of problem.
=item B<-profile-info-file> I<filename>
Specify the name of the file loaded by the -profile-loader option.
=item B<-stats>
Print statistics.
=item B<-time-passes>
Record the amount of time needed for each pass and print it to standard
error.
=item B<-debug>
If this is a debug build, this option will enable debug printouts
from passes which use the I<DEBUG()> macro. See the B<LLVM Programmer's
Manual>, section I<#DEBUG> for more information.
=item B<-load>=I<plugin>
Load the dynamic object I<plugin>. This object should register new optimization
or analysis passes. Once loaded, the object will add new command line options to
enable various optimizations or analyses. To see the new complete list of
optimizations, use the B<-help> and B<-load> options together. For example:
opt -load=plugin.so -help
=item B<-p>
Print module after each transformation.
=back
=head1 EXIT STATUS
If B<opt> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 AUTHORS
Maintained by the LLVM Team (L<http://llvm.org/>).
=cut

139
cpp/llvm/docs/CommandGuide/tblgen.pod
View File

@ -1,139 +0,0 @@
=pod
=head1 NAME
tblgen - Target Description To C++ Code Generator
=head1 SYNOPSIS
B<tblgen> [I<options>] [I<filename>]
=head1 DESCRIPTION
B<tblgen> translates from target description (.td) files into C++ code that can
be included in the definition of an LLVM target library. Most users of LLVM will
not need to use this program. It is only for assisting with writing an LLVM
target backend.
The input and output of B<tblgen> is beyond the scope of this short
introduction. Please see the I<CodeGeneration> page in the LLVM documentation.
The F<filename> argument specifies the name of a Target Description (.td) file
to read as input.
=head1 OPTIONS
=over
=item B<-help>
Print a summary of command line options.
=item B<-o> F<filename>
Specify the output file name. If F<filename> is C<->, then B<tblgen>
sends its output to standard output.
=item B<-I> F<directory>
Specify where to find other target description files for inclusion. The
F<directory> value should be a full or partial path to a directory that contains
target description files.
=item B<-asmparsernum> F<N>
Make -gen-asm-parser emit assembly writer number F<N>.
=item B<-asmwriternum> F<N>
Make -gen-asm-writer emit assembly writer number F<N>.
=item B<-class> F<class Name>
Print the enumeration list for this class.
=item B<-print-records>
Print all records to standard output (default).
=item B<-print-enums>
Print enumeration values for a class
=item B<-print-sets>
Print expanded sets for testing DAG exprs.
=item B<-gen-emitter>
Generate machine code emitter.
=item B<-gen-register-info>
Generate registers and register classes info.
=item B<-gen-instr-info>
Generate instruction descriptions.
=item B<-gen-asm-writer>
Generate the assembly writer.
=item B<-gen-disassembler>
Generate disassembler.
=item B<-gen-pseudo-lowering>
Generate pseudo instruction lowering.
=item B<-gen-dag-isel>
Generate a DAG (Directed Acycle Graph) instruction selector.
=item B<-gen-asm-matcher>
Generate assembly instruction matcher.
=item B<-gen-dfa-packetizer>
Generate DFA Packetizer for VLIW targets.
=item B<-gen-fast-isel>
Generate a "fast" instruction selector.
=item B<-gen-subtarget>
Generate subtarget enumerations.
=item B<-gen-intrinsic>
Generate intrinsic information.
=item B<-gen-tgt-intrinsic>
Generate target intrinsic information.
=item B<-gen-enhanced-disassembly-info>
Generate enhanced disassembly info.
=item B<-version>
Show the version number of this program.
=back
=head1 EXIT STATUS
If B<tblgen> succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
=head1 AUTHORS
Maintained by The LLVM Team (L<http://llvm.org/>).
=cut

1976
cpp/llvm/docs/CommandLine.html
View File

File diff suppressed because it is too large Load Diff

267
cpp/llvm/docs/CompilerWriterInfo.html
View File

@ -1,267 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Architecture/platform information for compiler writers</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>
Architecture/platform information for compiler writers
</h1>
<div class="doc_warning">
<p>Note: This document is a work-in-progress. Additions and clarifications
are welcome.</p>
</div>
<ol>
<li><a href="#hw">Hardware</a>
<ol>
<li><a href="#arm">ARM</a></li>
<li><a href="#ia64">Itanium</a></li>
<li><a href="#mips">MIPS</a></li>
<li><a href="#ppc">PowerPC</a></li>
<li><a href="#sparc">SPARC</a></li>
<li><a href="#x86">X86</a></li>
<li><a href="#other">Other lists</a></li>
</ol></li>
<li><a href="#abi">Application Binary Interface (ABI)</a>
<ol>
<li><a href="#linux">Linux</a></li>
<li><a href="#osx">OS X</a></li>
</ol></li>
<li><a href="#misc">Miscellaneous resources</a></li>
</ol>
<div class="doc_author">
<p>Compiled by <a href="http://misha.brukman.net">Misha Brukman</a></p>
</div>
<!-- *********************************************************************** -->
<h2><a name="hw">Hardware</a></h2>
<!-- *********************************************************************** -->
<div>
<!-- ======================================================================= -->
<h3><a name="arm">ARM</a></h3>
<div>
<ul>
<li><a href="http://www.arm.com/documentation/">ARM documentation</a>
(<a href="http://www.arm.com/documentation/ARMProcessor_Cores/">Processor
Cores</a>)</li>
<li><a href="http://www.arm.com/products/DevTools/ABI.html">ABI</a></li>
</ul>
</div>
<!-- ======================================================================= -->
<h3><a name="ia64">Itanium (ia64)</a></h3>
<div>
<ul>
<li><a
href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a>
</li>
</ul>
</div>
<!-- ======================================================================= -->
<h3><a name="mips">MIPS</a></h3>
<div>
<ul>
<li><a
href="http://mips.com/content/Documentation/MIPSDocumentation/ProcessorArchitecture/doclibrary">MIPS
Processor Architecture</a></li>
</ul>
</div>
<!-- ======================================================================= -->
<h3><a name="ppc">PowerPC</a></h3>
<div>
<!-- _______________________________________________________________________ -->
<h4>IBM - Official manuals and docs</h4>
<div>
<ul>
<li><a
href="http://www-106.ibm.com/developerworks/eserver/articles/archguide.html">PowerPC
Architecture Book</a>
<ul>
<li>Book I: <a
href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub1.pdf">PowerPC
User Instruction Set Architecture</a></li>
<li>Book II: <a
href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub2.pdf">PowerPC
Virtual Environment Architecture</a></li>
<li>Book III: <a
href="http://www-106.ibm.com/developerworks/eserver/pdfs/archpub3.pdf">PowerPC
Operating Environment Architecture</a></li>
</ul></li>
<li><a
href="http://www-3.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6">PowerPC
Compiler Writer's Guide</a></li>
<li><A
href="http://www-3.ibm.com/chips/techlib/techlib.nsf/products/PowerPC">PowerPC
Processor Manuals</a></li>
<li><a
href="http://www-106.ibm.com/developerworks/linux/library/l-powarch/">Intro to
PowerPC architecture</a></li>
<li><a href="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm">IBM AIX/5L for POWER Assembly reference</a></li>
</ul>
</div>
<!-- _______________________________________________________________________ -->
<h4>Other documents, collections, notes</h4>
<div>
<ul>
<li><a href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
<li><a href="http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html">PowerPC64
alignment of long doubles (from GCC)</a></li>
<li><a href="http://sources.redhat.com/ml/binutils/2002-04/msg00573.html">Long
branch stubs for powerpc64-linux (from binutils)</a></li>
</ul>
</div>
</div>
<!-- ======================================================================= -->
<h3><a name="sparc">SPARC</a></h3>
<div>
<ul>
<li><a href="http://www.sparc.org/resource.htm">SPARC resources</a></li>
<li><a href="http://www.sparc.org/standards.html">SPARC standards</a></li>
</ul>
</div>
<!-- ======================================================================= -->
<h3><a name="x86">X86</a></h3>
<div>
<!-- _______________________________________________________________________ -->
<h4>AMD - Official manuals and docs</h4>
<div>
<ul>
<li><a
href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.html">AMD processor manuals</a></li>
<li><a href="http://www.x86-64.org/documentation">X86-64 ABI</a></li>
</ul>
</div>
<!-- _______________________________________________________________________ -->
<h4>Intel - Official manuals and docs</h4>
<div>
<ul>
<li><a
href="http://developer.intel.com/design/pentium4/manuals/index_new.htm">IA-32
manuals</a></li>
<li><a
href="http://www.intel.com/design/itanium/documentation.htm?iid=ipp_srvr_proc_itanium2+techdocs">Intel
Itanium documentation</a></li>
</ul>
</div>
<!-- _______________________________________________________________________ -->
<h4>Other x86-specific information</h4>
<div>
<ul>
<li><a href="http://www.agner.org/assem/calling_conventions.pdf">Calling
conventions for different C++ compilers and operating systems</a></li>
</ul>
</div>
</div>
<!-- ======================================================================= -->
<h3><a name="other">Other relevant lists</a></h3>
<div>
<ul>
<li><a href="http://gcc.gnu.org/readings.html">GCC reading list</a></li>
</ul>
</div>
</div>
<!-- *********************************************************************** -->
<h2><a name="abi">ABI</a></h2>
<!-- *********************************************************************** -->
<div>
<!-- ======================================================================= -->
<h3><a name="linux">Linux</a></h3>
<div>
<ol>
<li><a href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI
Supplement</a></li>
</ol>
</div>
<!-- ======================================================================= -->
<h3><a name="osx">OS X</a></h3>
<div>
<ol>
<li><a
href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O
Runtime Architecture</a></li>
<li><a href="http://www.unsanity.org/archives/000044.php">Notes on Mach-O
ABI</a></li>
</ol>
</div>
</div>
<!-- *********************************************************************** -->
<h2><a name="misc">Miscellaneous resources</a></h2>
<!-- *********************************************************************** -->
<ul>
<li><a
href="http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/">Executable
File Format library</a></li>
<li><a href="http://gcc.gnu.org/projects/prefetch.html">GCC prefetch project</a>
page has a good survey of the prefetching capabilities of a variety of modern
processors.</li>
</ul>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://misha.brukman.net">Misha Brukman</a><br>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-10-27 15:56:32 -0700 (Thu, 27 Oct 2011) $
</address>
</body>
</html>

184
cpp/llvm/docs/DebuggingJITedCode.html
View File

@ -1,184 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Debugging JITed Code With GDB</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>Debugging JIT-ed Code With GDB</h1>
<ol>
<li><a href="#background">Background</a></li>
<li><a href="#gdbversion">GDB Version</a></li>
<li><a href="#mcjitdebug">Debugging MCJIT-ed code</a></li>
<ul>
<li><a href="#mcjitdebug_example">Example</a></li>
</ul>
</ol>
<div class="doc_author">Written by Reid Kleckner and Eli Bendersky</div>
<!--=========================================================================-->
<h2><a name="background">Background</a></h2>
<!--=========================================================================-->
<div>
<p>Without special runtime support, debugging dynamically generated code with
GDB (as well as most debuggers) can be quite painful. Debuggers generally read
debug information from the object file of the code, but for JITed code, there is
no such file to look for.
</p>
<p>In order to communicate the necessary debug info to GDB, an interface for
registering JITed code with debuggers has been designed and implemented for
GDB and LLVM MCJIT. At a high level, whenever MCJIT generates new machine code,
it does so in an in-memory object file that contains the debug information in
DWARF format. MCJIT then adds this in-memory object file to a global list of
dynamically generated object files and calls a special function
(<tt>__jit_debug_register_code</tt>) marked noinline that GDB knows about. When
GDB attaches to a process, it puts a breakpoint in this function and loads all
of the object files in the global list. When MCJIT calls the registration
function, GDB catches the breakpoint signal, loads the new object file from
the inferior's memory, and resumes the execution. In this way, GDB can get the
necessary debug information.
</p>
</div>
<!--=========================================================================-->
<h2><a name="gdbversion">GDB Version</a></h2>
<!--=========================================================================-->
<p>In order to debug code JIT-ed by LLVM, you need GDB 7.0 or newer, which is
available on most modern distributions of Linux. The version of GDB that Apple
ships with XCode has been frozen at 6.3 for a while. LLDB may be a better
option for debugging JIT-ed code on Mac OS X.
</p>
<!--=========================================================================-->
<h2><a name="mcjitdebug">Debugging MCJIT-ed code</a></h2>
<!--=========================================================================-->
<div>
<p>The emerging MCJIT component of LLVM allows full debugging of JIT-ed code with
GDB. This is due to MCJIT's ability to use the MC emitter to provide full
DWARF debugging information to GDB.</p>
<p>Note that lli has to be passed the <tt>-use-mcjit</tt> flag to JIT the code
with MCJIT instead of the old JIT.</p>
<h3><a name="mcjitdebug_example">Example</a></h3>
<div>
<p>Consider the following C code (with line numbers added to make the example
easier to follow):</p>
<pre class="doc_code">
1 int compute_factorial(int n)
2 {
3 if (n <= 1)
4 return 1;
5
6 int f = n;
7 while (--n > 1)
8 f *= n;
9 return f;
10 }
11
12
13 int main(int argc, char** argv)
14 {
15 if (argc < 2)
16 return -1;
17 char firstletter = argv[1][0];
18 int result = compute_factorial(firstletter - '0');
19
20 // Returned result is clipped at 255...
21 return result;
22 }
</pre>
<p>Here is a sample command line session that shows how to build and run this
code via lli inside GDB:
</p>
<pre class="doc_code">
$ $BINPATH/clang -cc1 -O0 -g -emit-llvm showdebug.c
$ gdb --quiet --args $BINPATH/lli -use-mcjit showdebug.ll 5
Reading symbols from $BINPATH/lli...done.
(gdb) b showdebug.c:6
No source file named showdebug.c.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (showdebug.c:6) pending.
(gdb) r
Starting program: $BINPATH/lli -use-mcjit showdebug.ll 5
[Thread debugging using libthread_db enabled]
Breakpoint 1, compute_factorial (n=5) at showdebug.c:6
6 int f = n;
(gdb) p n
$1 = 5
(gdb) p f
$2 = 0
(gdb) n
7 while (--n > 1)
(gdb) p f
$3 = 5
(gdb) b showdebug.c:9
Breakpoint 2 at 0x7ffff7ed404c: file showdebug.c, line 9.
(gdb) c
Continuing.
Breakpoint 2, compute_factorial (n=1) at showdebug.c:9
9 return f;
(gdb) p f
$4 = 120
(gdb) bt
#0 compute_factorial (n=1) at showdebug.c:9
#1 0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18
#2 0x3500000001652748 in ?? ()
#3 0x00000000016677e0 in ?? ()
#4 0x0000000000000002 in ?? ()
#5 0x0000000000d953b3 in llvm::MCJIT::runFunction (this=0x16151f0, F=0x1603020, ArgValues=...) at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/MCJIT/MCJIT.cpp:161
#6 0x0000000000dc8872 in llvm::ExecutionEngine::runFunctionAsMain (this=0x16151f0, Fn=0x1603020, argv=..., envp=0x7fffffffe040)
at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/ExecutionEngine.cpp:397
#7 0x000000000059c583 in main (argc=4, argv=0x7fffffffe018, envp=0x7fffffffe040) at /home/ebenders_test/llvm_svn_rw/tools/lli/lli.cpp:324
(gdb) finish
Run till exit from #0 compute_factorial (n=1) at showdebug.c:9
0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18
18 int result = compute_factorial(firstletter - '0');
Value returned is $5 = 120
(gdb) p result
$6 = 23406408
(gdb) n
21 return result;
(gdb) p result
$7 = 120
(gdb) c
Continuing.
Program exited with code 0170.
(gdb)
</pre>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:reid.kleckner@gmail.com">Reid Kleckner</a>,
<a href="mailto:eliben@gmail.com">Eli Bendersky</a><br>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-05-01 00:58:54 -0700 (Tue, 01 May 2012) $
</address>
</body>
</html>

642
cpp/llvm/docs/DeveloperPolicy.html
View File

@ -1,642 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM Developer Policy</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>LLVM Developer Policy</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#policies">Developer Policies</a>
<ol>
<li><a href="#informed">Stay Informed</a></li>
<li><a href="#patches">Making a Patch</a></li>
<li><a href="#reviews">Code Reviews</a></li>
<li><a href="#owners">Code Owners</a></li>
<li><a href="#testcases">Test Cases</a></li>
<li><a href="#quality">Quality</a></li>
<li><a href="#commitaccess">Obtaining Commit Access</a></li>
<li><a href="#newwork">Making a Major Change</a></li>
<li><a href="#incremental">Incremental Development</a></li>
<li><a href="#attribution">Attribution of Changes</a></li>
</ol></li>
<li><a href="#clp">Copyright, License, and Patents</a>
<ol>
<li><a href="#copyright">Copyright</a></li>
<li><a href="#license">License</a></li>
<li><a href="#patents">Patents</a></li>
</ol></li>
</ol>
<div class="doc_author">Written by the LLVM Oversight Team</div>
<!--=========================================================================-->
<h2><a name="introduction">Introduction</a></h2>
<!--=========================================================================-->
<div>
<p>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
the distributed nature of LLVM's development. By stating the policy in clear
terms, we hope each developer can know ahead of time what to expect when
making LLVM contributions. This policy covers all llvm.org subprojects,
including Clang, LLDB, libc++, etc.</p>
<p>This policy is also designed to accomplish the following objectives:</p>
<ol>
<li>Attract both users and developers to the LLVM project.</li>
<li>Make life as simple and easy for contributors as possible.</li>
<li>Keep the top of Subversion trees as stable as possible.</li>
<li>Establish awareness of the project's <a href="#clp">copyright,
license, and patent policies</a> with contributors to the project.</li>
</ol>
<p>This policy is aimed at frequent contributors to LLVM. People interested in
contributing one-off patches can do so in an informal way by sending them to
the
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits
mailing list</a> and engaging another developer to see it through the
process.</p>
</div>
<!--=========================================================================-->
<h2><a name="policies">Developer Policies</a></h2>
<!--=========================================================================-->
<div>
<p>This section contains policies that pertain to frequent LLVM developers. We
always welcome <a href="#patches">one-off patches</a> 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.<p>
<!-- _______________________________________________________________________ -->
<h3><a name="informed">Stay Informed</a></h3>
<div>
<p>Developers should stay informed by reading at least the "dev" mailing list
for the projects you are interested in, such as
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> for
LLVM, <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a>
for Clang, or <a
href="http://lists.cs.uiuc.edu/mailman/listinfo/lldb-dev">lldb-dev</a>
for LLDB. If you are doing anything more than just casual work on LLVM, it
is suggested that you also subscribe to the "commits" mailing list for the
subproject you're interested in, such as
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>,
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>,
or <a href="http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits">lldb-commits</a>.
Reading the "commits" list and paying attention to changes being made by
others is a good way to see what other people are interested in and watching
the flow of the project as a whole.</p>
<p>We recommend that active developers register an email account with
<a href="http://llvm.org/bugs/">LLVM Bugzilla</a> and preferably subscribe to
the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmbugs">llvm-bugs</a>
email list to keep track of bugs and enhancements occurring in LLVM. We
really appreciate people who are proactive at catching incoming bugs in their
components and dealing with them promptly.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="patches">Making a Patch</a></h3>
<div>
<p>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:</p>
<ol>
<li>Make your patch against the Subversion trunk, not a branch, and not an old
version of LLVM. This makes it easy to apply the patch. For information
on how to check out SVN trunk, please see the <a
href="GettingStarted.html#checkout">Getting Started Guide</a>.</li>
<li>Similarly, patches should be submitted soon after they are generated. Old
patches may not apply correctly if the underlying code changes between the
time the patch was created and the time it is applied.</li>
<li>Patches should be made with <tt>svn diff</tt>, or similar. If you use
a different tool, make sure it uses the <tt>diff -u</tt> format and
that it doesn't contain clutter which makes it hard to read.</li>
<li>If you are modifying generated files, such as the top-level
<tt>configure</tt> script, please separate out those changes into
a separate patch from the rest of your changes.</li>
</ol>
<p>When sending a patch to a mailing list, it is a good idea to send it as an
<em>attachment</em> to the message, not embedded into the text of the
message. This ensures that your mailer will not mangle the patch when it
sends it (e.g. by making whitespace changes or by wrapping lines).</p>
<p><em>For Thunderbird users:</em> Before submitting a patch, please open
<em>Preferences &#8594; Advanced &#8594; General &#8594; Config Editor</em>,
find the key <tt>mail.content_disposition_type</tt>, and set its value to
<tt>1</tt>. Without this setting, Thunderbird sends your attachment using
<tt>Content-Disposition: inline</tt> rather than <tt>Content-Disposition:
attachment</tt>. Apple Mail gamely displays such a file inline, making it
difficult to work with for reviewers using that program.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="reviews">Code Reviews</a></h3>
<div>
<p>LLVM has a code review policy. Code review is one way to increase the quality
of software. We generally follow these policies:</p>
<ol>
<li>All developers are required to have significant changes reviewed before
they are committed to the repository.</li>
<li>Code reviews are conducted by email, usually on the llvm-commits
list.</li>
<li>Code can be reviewed either before it is committed or after. We expect
major changes to be reviewed before being committed, but smaller changes
(or changes where the developer owns the component) can be reviewed after
commit.</li>
<li>The developer responsible for a code change is also responsible for making
all necessary review-related changes.</li>
<li>Code review can be an iterative process, which continues until the patch
is ready to be committed.</li>
</ol>
<p>Developers should participate in code reviews as both reviewers and
reviewees. If someone is kind enough to review your code, you should return
the favor for someone else. Note that anyone is welcome to review and give
feedback on a patch, but only people with Subversion write access can approve
it.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="owners">Code Owners</a></h3>
<div>
<p>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
combination of code review plus post-commit review for trusted maintainers.
Having both is a great way for the project to take advantage of the fact that
most people do the right thing most of the time, and only commit patches
without pre-commit review when they are confident they are right.</p>
<p>The trick to this is that the project has to guarantee that all patches that
are committed are reviewed after they go in: you don't want everyone to
assume someone else will review it, allowing the patch to go unreviewed. To
solve this problem, we have a notion of an 'owner' for a piece of the code.
The sole responsibility of a code owner is to ensure that a commit to their
area of the code is appropriately reviewed, either by themself or by someone
else. The current code owners are:</p>
<ol>
<li><b>Evan Cheng</b>: Code generator and all targets.</li>
<li><b>Greg Clayton</b>: LLDB.</li>
<li><b>Doug Gregor</b>: Clang Frontend Libraries.</li>
<li><b>Howard Hinnant</b>: libc++.</li>
<li><b>Anton Korobeynikov</b>: Exception handling, debug information, and
Windows codegen.</li>
<li><b>Ted Kremenek</b>: Clang Static Analyzer.</li>
<li><b>Chris Lattner</b>: Everything not covered by someone else.</li>
<li><b>John McCall</b>: Clang LLVM IR generation.</li>
<li><b>Jakob Olesen</b>: Register allocators and TableGen.</li>
<li><b>Duncan Sands</b>: dragonegg and llvm-gcc 4.2.</li>
<li><b>Peter Collingbourne</b>: libclc.</li>
<li><b>Tobias Grosser</b>: polly.</li>
</ol>
<p>Note that code ownership is completely different than reviewers: anyone can
review a piece of code, and we welcome code review from anyone who is
interested. Code owners are the "last line of defense" to guarantee that all
patches that are committed are actually reviewed.</p>
<p>Being a code owner is a somewhat unglamorous position, but it is incredibly
important for the ongoing success of the project. Because people get busy,
interests change, and unexpected things happen, code ownership is purely
opt-in, and anyone can choose to resign their "title" at any time. For now,
we do not have an official policy on how one gets elected to be a code
owner.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="testcases">Test Cases</a></h3>
<div>
<p>Developers are required to create test cases for any bugs fixed and any new
features added. Some tips for getting your testcase approved:</p>
<ol>
<li>All feature and regression test cases are added to the
<tt>llvm/test</tt> directory. The appropriate sub-directory should be
selected (see the <a href="TestingGuide.html">Testing Guide</a> for
details).</li>
<li>Test cases should be written in <a href="LangRef.html">LLVM assembly
language</a> unless the feature or regression being tested requires
another language (e.g. the bug being fixed or feature being implemented is
in the llvm-gcc C++ front-end, in which case it must be written in
C++).</li>
<li>Test cases, especially for regressions, should be reduced as much as
possible, by <a href="Bugpoint.html">bugpoint</a> or manually. It is
unacceptable to place an entire failing program into <tt>llvm/test</tt> as
this creates a <i>time-to-test</i> burden on all developers. Please keep
them short.</li>
</ol>
<p>Note that llvm/test and clang/test are designed for regression and small
feature tests only. More extensive test cases (e.g., entire applications,
benchmarks, etc)
should be added to the <tt>llvm-test</tt> test suite. The llvm-test suite is
for coverage (correctness, performance, etc) testing, not feature or
regression testing.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="quality">Quality</a></h3>
<div>
<p>The minimum quality standards that any change must satisfy before being
committed to the main development branch are:</p>
<ol>
<li>Code must adhere to the <a href="CodingStandards.html">LLVM Coding
Standards</a>.</li>
<li>Code must compile cleanly (no errors, no warnings) on at least one
platform.</li>
<li>Bug fixes and new features should <a href="#testcases">include a
testcase</a> so we know if the fix/feature ever regresses in the
future.</li>
<li>Code must pass the <tt>llvm/test</tt> test suite.</li>
<li>The code must not cause regressions on a reasonable subset of llvm-test,
where "reasonable" depends on the contributor's judgement and the scope of
the change (more invasive changes require more testing). A reasonable
subset might be something like
"<tt>llvm-test/MultiSource/Benchmarks</tt>".</li>
</ol>
<p>Additionally, the committer is responsible for addressing any problems found
in the future that the change is responsible for. For example:</p>
<ul>
<li>The code should compile cleanly on all supported platforms.</li>
<li>The changes should not cause any correctness regressions in the
<tt>llvm-test</tt> suite and must not cause any major performance
regressions.</li>
<li>The change set should not cause performance or correctness regressions for
the LLVM tools.</li>
<li>The changes should not cause performance or correctness regressions in
code compiled by LLVM on all applicable targets.</li>
<li>You are expected to address any <a href="http://llvm.org/bugs/">bugzilla
bugs</a> that result from your change.</li>
</ul>
<p>We prefer for this to be handled before submission but understand that it
isn't possible to test all of this for every submission. Our build bots and
nightly testing infrastructure normally finds these problems. A good rule of
thumb is to check the nightly testers for regressions the day after your
change. Build bots will directly email you if a group of commits that
included yours caused a failure. You are expected to check the build bot
messages to see if they are your fault and, if so, fix the breakage.</p>
<p>Commits that violate these quality standards (e.g. are very broken) may be
reverted. This is necessary when the change blocks other developers from
making progress. The developer is welcome to re-commit the change after the
problem has been fixed.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="commitaccess">Obtaining Commit Access</a></h3>
<div>
<p>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
<a href="mailto:sabre@nondot.org">Chris</a> with the following
information:</p>
<ol>
<li>The user name you want to commit with, e.g. "hacker".</li>
<li>The full name and email address you want message to llvm-commits to come
from, e.g. "J. Random Hacker &lt;hacker@yoyodyne.com&gt;".</li>
<li>A "password hash" of the password you want to use, e.g. "2ACR96qjUqsyM".
Note that you don't ever tell us what your password is, you just give it
to us in an encrypted form. To get this, run "htpasswd" (a utility that
comes with apache) in crypt mode (often enabled with "-d"), or find a web
page that will do it for you.</li>
</ol>
<p>Once you've been granted commit access, you should be able to check out an
LLVM tree with an SVN URL of "https://username@llvm.org/..." instead of the
normal anonymous URL of "http://llvm.org/...". The first time you commit
you'll have to type in your password. Note that you may get a warning from
SVN about an untrusted key, you can ignore this. To verify that your commit
access works, please do a test commit (e.g. change a comment or add a blank
line). Your first commit to a repository may require the autogenerated email
to be approved by a mailing list. This is normal, and will be done when
the mailing list owner has time.</p>
<p>If you have recently been granted commit access, these policies apply:</p>
<ol>
<li>You are granted <i>commit-after-approval</i> to all parts of LLVM. To get
approval, submit a <a href="#patches">patch</a> to
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>.
When approved you may commit it yourself.</li>
<li>You are allowed to commit patches without approval which you think are
obvious. This is clearly a subjective decision &mdash; we simply expect
you to use good judgement. Examples include: fixing build breakage,
reverting obviously broken patches, documentation/comment changes, any
other minor changes.</li>
<li>You are allowed to commit patches without approval to those portions of
LLVM that you have contributed or maintain (i.e., have been assigned
responsibility for), with the proviso that such commits must not break the
build. This is a "trust but verify" policy and commits of this nature are
reviewed after they are committed.</li>
<li>Multiple violations of these policies or a single egregious violation may
cause commit access to be revoked.</li>
</ol>
<p>In any case, your changes are still subject to <a href="#reviews">code
review</a> (either before or after they are committed, depending on the
nature of the change). You are encouraged to review other peoples' patches
as well, but you aren't required to.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="newwork">Making a Major Change</a></h3>
<div>
<p>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 <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a>
email list, to the extent possible. The reason for this is to:
<ol>
<li>keep the community informed about future changes to LLVM, </li>
<li>avoid duplication of effort by preventing multiple parties working on the
same thing and not knowing about it, and</li>
<li>ensure that any technical issues around the proposed work are discussed
and resolved before any significant work is done.</li>
</ol>
<p>The design of LLVM is carefully controlled to ensure that all the pieces fit
together well and are as consistent as possible. If you plan to make a major
change to the way LLVM works or want to add a major new extension, it is a
good idea to get consensus with the development community before you start
working on it.</p>
<p>Once the design of the new feature is finalized, the work itself should be
done as a series of <a href="#incremental">incremental changes</a>, not as a
long-term development branch.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="incremental">Incremental Development</a></h3>
<div>
<p>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:</p>
<ol>
<li>Branches must have mainline merged into them periodically. If the branch
development and mainline development occur in the same pieces of code,
resolving merge conflicts can take a lot of time.</li>
<li>Other people in the community tend to ignore work on branches.</li>
<li>Huge changes (produced when a branch is merged back onto mainline) are
extremely difficult to <a href="#reviews">code review</a>.</li>
<li>Branches are not routinely tested by our nightly tester
infrastructure.</li>
<li>Changes developed as monolithic large changes often don't work until the
entire set of changes is done. Breaking it down into a set of smaller
changes increases the odds that any of the work will be committed to the
main repository.</li>
</ol>
<p>To address these problems, LLVM uses an incremental development style and we
require contributors to follow this practice when making a large/invasive
change. Some tips:</p>
<ul>
<li>Large/invasive changes usually have a number of secondary changes that are
required before the big change can be made (e.g. API cleanup, etc). These
sorts of changes can often be done before the major change is done,
independently of that work.</li>
<li>The remaining inter-related work should be decomposed into unrelated sets
of changes if possible. Once this is done, define the first increment and
get consensus on what the end goal of the change is.</li>
<li>Each change in the set can be stand alone (e.g. to fix a bug), or part of
a planned series of changes that works towards the development goal.</li>
<li>Each change should be kept as small as possible. This simplifies your work
(into a logical progression), simplifies code review and reduces the
chance that you will get negative feedback on the change. Small increments
also facilitate the maintenance of a high quality code base.</li>
<li>Often, an independent precursor to a big change is to add a new API and
slowly migrate clients to use the new API. Each change to use the new API
is often "obvious" and can be committed without review. Once the new API
is in place and used, it is much easier to replace the underlying
implementation of the API. This implementation change is logically
separate from the API change.</li>
</ul>
<p>If you are interested in making a large change, and this scares you, please
make sure to first <a href="#newwork">discuss the change/gather consensus</a>
then ask about the best way to go about making the change.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="attribution">Attribution of Changes</a></h3>
<div>
<p>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
distracting). In practice, the revision control system keeps a perfect
history of who changed what, and the CREDITS.txt file describes higher-level
contributions. If you commit a patch for someone else, please say "patch
contributed by J. Random Hacker!" in the commit message.</p>
<p>Overall, please do not add contributor names to the source code.</p>
</div>
</div>
<!--=========================================================================-->
<h2>
<a name="clp">Copyright, License, and Patents</a>
</h2>
<!--=========================================================================-->
<div>
<div class="doc_notes">
<p style="text-align:center;font-weight:bold">NOTE: This section deals with
legal matters but does not provide legal advice. We are not lawyers &mdash;
please seek legal counsel from an attorney.</p>
</div>
<div>
<p>This section addresses the issues of copyright, license and patents for the
LLVM project. The copyright for the code is held by the individual
contributors of the code and the terms of its license to LLVM users and
developers is the
<a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of
Illinois/NCSA Open Source License</a> (with portions dual licensed under the
<a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>,
see below). As contributor to the LLVM project, you agree to allow any
contributions to the project to licensed under these terms.</p>
<!-- _______________________________________________________________________ -->
<h3><a name="copyright">Copyright</a></h3>
<div>
<p>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
who have each agreed to release their contributed code under the terms of the
<a href="#license">LLVM License</a>.</p>
<p>An implication of this is that the LLVM license is unlikely to ever change:
changing it would require tracking down all the contributors to LLVM and
getting them to agree that a license change is acceptable for their
contribution. Since there are no plans to change the license, this is not a
cause for concern.</p>
<p>As a contributor to the project, this means that you (or your company) retain
ownership of the code you contribute, that it cannot be used in a way that
contradicts the license (which is a liberal BSD-style license), and that the
license for your contributions won't change without your approval in the
future.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="license">License</a></h3>
<div>
<p>We intend to keep LLVM perpetually open source and to use a liberal open
source license. <b>As a contributor to the project, you agree that any
contributions be licensed under the terms of the corresponding
subproject.</b>
All of the code in LLVM is available under the
<a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of
Illinois/NCSA Open Source License</a>, which boils down to this:</p>
<ul>
<li>You can freely distribute LLVM.</li>
<li>You must retain the copyright notice if you redistribute LLVM.</li>
<li>Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
included readme file).</li>
<li>You can't use our names to promote your LLVM derived products.</li>
<li>There's no warranty on LLVM at all.</li>
</ul>
<p>We believe this fosters the widest adoption of LLVM because it <b>allows
commercial products to be derived from LLVM</b> with few restrictions and
without a requirement for making any derived works also open source (i.e.
LLVM's license is not a "copyleft" license like the GPL). We suggest that you
read the <a href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a>
if further clarification is needed.</p>
<p>In addition to the UIUC license, the runtime library components of LLVM
(<b>compiler_rt, libc++, and libclc</b>) are also licensed under the <a
href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>,
which does not contain the binary redistribution clause. As a user of these
runtime libraries, it means that you can choose to use the code under either
license (and thus don't need the binary redistribution clause), and as a
contributor to the code that you agree that any contributions to these
libraries be licensed under both licenses. We feel that this is important
for runtime libraries, because they are implicitly linked into applications
and therefore should not subject those applications to the binary
redistribution clause. This also means that it is ok to move code from (e.g.)
libc++ to the LLVM core without concern, but that code cannot be moved from
the LLVM core to libc++ without the copyright owner's permission.
</p>
<p>Note that the LLVM Project does distribute llvm-gcc and dragonegg, <b>which
are GPL.</b>
This means that anything "linked" into llvm-gcc must itself be compatible
with the GPL, and must be releasable under the terms of the GPL. This
implies that <b>any code linked into llvm-gcc and distributed to others may
be subject to the viral aspects of the GPL</b> (for example, a proprietary
code generator linked into llvm-gcc must be made available under the GPL).
This is not a problem for code already distributed under a more liberal
license (like the UIUC license), and GPL-containing subprojects are kept
in separate SVN repositories whose LICENSE.txt files specifically indicate
that they contain GPL code.</p>
<p>We have no plans to change the license of LLVM. If you have questions or
comments about the license, please contact the
<a href="mailto:llvmdev@cs.uiuc.edu">LLVM Developer's Mailing List</a>.</p>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="patents">Patents</a></h3>
<div>
<p>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
of the project by making it hard or impossible to reuse the code for
arbitrary purposes (including commercial use).</p>
<p>When contributing code, we expect contributors to notify us of any potential
for patent-related trouble with their changes (including from third parties).
If you or your employer own
the rights to a patent and would like to contribute code to LLVM that relies
on it, we require that the copyright owner sign an agreement that allows any
other user of LLVM to freely use your patent. Please contact
the <a href="mailto:llvm-oversight@cs.uiuc.edu">oversight group</a> for more
details.</p>
</div>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Written by the
<a href="mailto:llvm-oversight@cs.uiuc.edu">LLVM Oversight Group</a><br>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $
</address>
</body>
</html>

563
cpp/llvm/docs/ExceptionHandling.html
View File

@ -1,563 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Exception Handling in LLVM</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description"
content="Exception Handling in LLVM.">
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>Exception Handling in LLVM</h1>
<table class="layout" style="width:100%">
<tr class="layout">
<td class="left">
<ul>
<li><a href="#introduction">Introduction</a>
<ol>
<li><a href="#itanium">Itanium ABI Zero-cost Exception Handling</a></li>
<li><a href="#sjlj">Setjmp/Longjmp Exception Handling</a></li>
<li><a href="#overview">Overview</a></li>
</ol></li>
<li><a href="#codegen">LLVM Code Generation</a>
<ol>
<li><a href="#throw">Throw</a></li>
<li><a href="#try_catch">Try/Catch</a></li>
<li><a href="#cleanups">Cleanups</a></li>
<li><a href="#throw_filters">Throw Filters</a></li>
<li><a href="#restrictions">Restrictions</a></li>
</ol></li>
<li><a href="#format_common_intrinsics">Exception Handling Intrinsics</a>
<ol>
<li><a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a></li>
<li><a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a></li>
<li><a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a></li>
<li><a href="#llvm_eh_sjlj_lsda"><tt>llvm.eh.sjlj.lsda</tt></a></li>
<li><a href="#llvm_eh_sjlj_callsite"><tt>llvm.eh.sjlj.callsite</tt></a></li>
</ol></li>
<li><a href="#asm">Asm Table Formats</a>
<ol>
<li><a href="#unwind_tables">Exception Handling Frame</a></li>
<li><a href="#exception_tables">Exception Tables</a></li>
</ol></li>
</ul>
</td>
</tr></table>
<div class="doc_author">
<p>Written by the <a href="http://llvm.org/">LLVM Team</a></p>
</div>
<!-- *********************************************************************** -->
<h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** -->
<div>
<p>This document is the central repository for all information pertaining to
exception handling in LLVM. It describes the format that LLVM exception
handling information takes, which is useful for those interested in creating
front-ends or dealing directly with the information. Further, this document
provides specific examples of what exception handling information is used for
in C and C++.</p>
<!-- ======================================================================= -->
<h3>
<a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
</h3>
<div>
<p>Exception handling for most programming languages is designed to recover from
conditions that rarely occur during general use of an application. To that
end, exception handling should not interfere with the main flow of an
application's algorithm by performing checkpointing tasks, such as saving the
current pc or register state.</p>
<p>The Itanium ABI Exception Handling Specification defines a methodology for
providing outlying data in the form of exception tables without inlining
speculative exception handling code in the flow of an application's main
algorithm. Thus, the specification is said to add "zero-cost" to the normal
execution of an application.</p>
<p>A more complete description of the Itanium ABI exception handling runtime
support of can be found at
<a href="http://www.codesourcery.com/cxx-abi/abi-eh.html">Itanium C++ ABI:
Exception Handling</a>. A description of the exception frame format can be
found at
<a href="http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception
Frames</a>, with details of the DWARF 4 specification at
<a href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>.
A description for the C++ exception table formats can be found at
<a href="http://www.codesourcery.com/cxx-abi/exceptions.pdf">Exception Handling
Tables</a>.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="sjlj">Setjmp/Longjmp Exception Handling</a>
</h3>
<div>
<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
<a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and
<a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> to
handle control flow for exception handling.</p>
<p>For each function which does exception processing &mdash; be
it <tt>try</tt>/<tt>catch</tt> blocks or cleanups &mdash; that function
registers itself on a global frame list. When exceptions are unwinding, the
runtime uses this list to identify which functions need processing.<p>
<p>Landing pad selection is encoded in the call site entry of the function
context. The runtime returns to the function via
<a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>, where
a switch table transfers control to the appropriate landing pad based on
the index stored in the function context.</p>
<p>In contrast to DWARF exception handling, which encodes exception regions
and frame information in out-of-line tables, SJLJ exception handling
builds and removes the unwind frame context at runtime. This results in
faster exception handling at the expense of slower execution when no
exceptions are thrown. As exceptions are, by their nature, intended for
uncommon code paths, DWARF exception handling is generally preferred to
SJLJ.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="overview">Overview</a>
</h3>
<div>
<p>When an exception is thrown in LLVM code, the runtime does its best to find a
handler suited to processing the circumstance.</p>
<p>The runtime first attempts to find an <i>exception frame</i> corresponding to
the function where the exception was thrown. If the programming language
supports exception handling (e.g. C++), the exception frame contains a
reference to an exception table describing how to process the exception. If
the language does not support exception handling (e.g. C), or if the
exception needs to be forwarded to a prior activation, the exception frame
contains information about how to unwind the current activation and restore
the state of the prior activation. This process is repeated until the
exception is handled. If the exception is not handled and no activations
remain, then the application is terminated with an appropriate error
message.</p>
<p>Because different programming languages have different behaviors when
handling exceptions, the exception handling ABI provides a mechanism for
supplying <i>personalities</i>. An exception handling personality is defined
by way of a <i>personality function</i> (e.g. <tt>__gxx_personality_v0</tt>
in C++), which receives the context of the exception, an <i>exception
structure</i> containing the exception object type and value, and a reference
to the exception table for the current function. The personality function
for the current compile unit is specified in a <i>common exception
frame</i>.</p>
<p>The organization of an exception table is language dependent. For C++, an
exception table is organized as a series of code ranges defining what to do
if an exception occurs in that range. Typically, the information associated
with a range defines which types of exception objects (using C++ <i>type
info</i>) that are handled in that range, and an associated action that
should take place. Actions typically pass control to a <i>landing
pad</i>.</p>
<p>A landing pad corresponds roughly to the code found in the <tt>catch</tt>
portion of a <tt>try</tt>/<tt>catch</tt> sequence. When execution resumes at
a landing pad, it receives an <i>exception structure</i> and a
<i>selector value</i> corresponding to the <i>type</i> of exception
thrown. The selector is then used to determine which <i>catch</i> should
actually process the exception.</p>
</div>
</div>
<!-- ======================================================================= -->
<h2>
<a name="codegen">LLVM Code Generation</a>
</h2>
<div>
<p>From a C++ developer's perspective, exceptions are defined in terms of the
<tt>throw</tt> and <tt>try</tt>/<tt>catch</tt> statements. In this section
we will describe the implementation of LLVM exception handling in terms of
C++ examples.</p>
<!-- ======================================================================= -->
<h3>
<a name="throw">Throw</a>
</h3>
<div>
<p>Languages that support exception handling typically provide a <tt>throw</tt>
operation to initiate the exception process. Internally, a <tt>throw</tt>
operation breaks down into two steps.</p>
<ol>
<li>A request is made to allocate exception space for an exception structure.
This structure needs to survive beyond the current activation. This
structure will contain the type and value of the object being thrown.</li>
<li>A call is made to the runtime to raise the exception, passing the
exception structure as an argument.</li>
</ol>
<p>In C++, the allocation of the exception structure is done by the
<tt>__cxa_allocate_exception</tt> runtime function. The exception raising is
handled by <tt>__cxa_throw</tt>. The type of the exception is represented
using a C++ RTTI structure.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="try_catch">Try/Catch</a>
</h3>
<div>
<p>A call within the scope of a <i>try</i> statement can potentially raise an
exception. In those circumstances, the LLVM C++ front-end replaces the call
with an <tt>invoke</tt> instruction. Unlike a call, the <tt>invoke</tt> has
two potential continuation points:</p>
<ol>
<li>where to continue when the call succeeds as per normal, and</li>
<li>where to continue if the call raises an exception, either by a throw or
the unwinding of a throw</li>
</ol>
<p>The term used to define a the place where an <tt>invoke</tt> continues after
an exception is called a <i>landing pad</i>. LLVM landing pads are
conceptually alternative function entry points where an exception structure
reference and a type info index are passed in as arguments. The landing pad
saves the exception structure reference and then proceeds to select the catch
block that corresponds to the type info of the exception object.</p>
<p>The LLVM <a href="LangRef.html#i_landingpad"><tt>landingpad</tt>
instruction</a> is used to convey information about the landing pad to the
back end. For C++, the <tt>landingpad</tt> instruction returns a pointer and
integer pair corresponding to the pointer to the <i>exception structure</i>
and the <i>selector value</i> respectively.</p>
<p>The <tt>landingpad</tt> instruction takes a reference to the personality
function to be used for this <tt>try</tt>/<tt>catch</tt> sequence. The
remainder of the instruction is a list of <i>cleanup</i>, <i>catch</i>,
and <i>filter</i> clauses. The exception is tested against the clauses
sequentially from first to last. The selector value is a positive number if
the exception matched a type info, a negative number if it matched a filter,
and zero if it matched a cleanup. If nothing is matched, the behavior of
the program is <a href="#restrictions">undefined</a>. If a type info matched,
then the selector value is the index of the type info in the exception table,
which can be obtained using the
<a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic.</p>
<p>Once the landing pad has the type info selector, the code branches to the
code for the first catch. The catch then checks the value of the type info
selector against the index of type info for that catch. Since the type info
index is not known until all the type infos have been gathered in the
backend, the catch code must call the
<a href="#llvm_eh_typeid_for"><tt>llvm.eh.typeid.for</tt></a> intrinsic to
determine the index for a given type info. If the catch fails to match the
selector then control is passed on to the next catch.</p>
<p>Finally, the entry and exit of catch code is bracketed with calls to
<tt>__cxa_begin_catch</tt> and <tt>__cxa_end_catch</tt>.</p>
<ul>
<li><tt>__cxa_begin_catch</tt> takes an exception structure reference as an
argument and returns the value of the exception object.</li>
<li><tt>__cxa_end_catch</tt> takes no arguments. This function:<br><br>
<ol>
<li>Locates the most recently caught exception and decrements its handler
count,</li>
<li>Removes the exception from the <i>caught</i> stack if the handler
count goes to zero, and</li>
<li>Destroys the exception if the handler count goes to zero and the
exception was not re-thrown by throw.</li>
</ol>
<p><b>Note:</b> a rethrow from within the catch may replace this call with
a <tt>__cxa_rethrow</tt>.</p></li>
</ul>
</div>
<!-- ======================================================================= -->
<h3>
<a name="cleanups">Cleanups</a>
</h3>
<div>
<p>A cleanup is extra code which needs to be run as part of unwinding a scope.
C++ destructors are a typical example, but other languages and language
extensions provide a variety of different kinds of cleanups. In general, a
landing pad may need to run arbitrary amounts of cleanup code before actually
entering a catch block. To indicate the presence of cleanups, a
<a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>
should have a <i>cleanup</i> clause. Otherwise, the unwinder will not stop at
the landing pad if there are no catches or filters that require it to.</p>
<p><b>Note:</b> Do not allow a new exception to propagate out of the execution
of a cleanup. This can corrupt the internal state of the unwinder.
Different languages describe different high-level semantics for these
situations: for example, C++ requires that the process be terminated, whereas
Ada cancels both exceptions and throws a third.</p>
<p>When all cleanups are finished, if the exception is not handled by the
current function, resume unwinding by calling the
<a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a>, passing in
the result of the <tt>landingpad</tt> instruction for the original landing
pad.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="throw_filters">Throw Filters</a>
</h3>
<div>
<p>C++ allows the specification of which exception types may be thrown from a
function. To represent this, a top level landing pad may exist to filter out
invalid types. To express this in LLVM code the
<a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> will
have a filter clause. The clause consists of an array of type infos.
<tt>landingpad</tt> will return a negative value if the exception does not
match any of the type infos. If no match is found then a call
to <tt>__cxa_call_unexpected</tt> should be made, otherwise
<tt>_Unwind_Resume</tt>. Each of these functions requires a reference to the
exception structure. Note that the most general form of a
<a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a> can
have any number of catch, cleanup, and filter clauses (though having more
than one cleanup is pointless). The LLVM C++ front-end can generate such
<a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instructions</a> due
to inlining creating nested exception handling scopes.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="restrictions">Restrictions</a>
</h3>
<div>
<p>The unwinder delegates the decision of whether to stop in a call frame to
that call frame's language-specific personality function. Not all unwinders
guarantee that they will stop to perform cleanups. For example, the GNU C++
unwinder doesn't do so unless the exception is actually caught somewhere
further up the stack.</p>
<p>In order for inlining to behave correctly, landing pads must be prepared to
handle selector results that they did not originally advertise. Suppose that
a function catches exceptions of type <tt>A</tt>, and it's inlined into a
function that catches exceptions of type <tt>B</tt>. The inliner will update
the <tt>landingpad</tt> instruction for the inlined landing pad to include
the fact that <tt>B</tt> is also caught. If that landing pad assumes that it
will only be entered to catch an <tt>A</tt>, it's in for a rude awakening.
Consequently, landing pads must test for the selector results they understand
and then resume exception propagation with the
<a href="LangRef.html#i_resume"><tt>resume</tt> instruction</a> if none of
the conditions match.</p>
</div>
</div>
<!-- ======================================================================= -->
<h2>
<a name="format_common_intrinsics">Exception Handling Intrinsics</a>
</h2>
<div>
<p>In addition to the
<a href="LangRef.html#i_landingpad"><tt>landingpad</tt></a> and
<a href="LangRef.html#i_resume"><tt>resume</tt></a> instructions, LLVM uses
several intrinsic functions (name prefixed with <i><tt>llvm.eh</tt></i>) to
provide exception handling information at various points in generated
code.</p>
<!-- ======================================================================= -->
<h4>
<a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
</h4>
<div>
<pre>
i32 @llvm.eh.typeid.for(i8* %type_info)
</pre>
<p>This intrinsic returns the type info index in the exception table of the
current function. This value can be used to compare against the result
of <a href="LangRef.html#i_landingpad"><tt>landingpad</tt> instruction</a>.
The single argument is a reference to a type info.</p>
</div>
<!-- ======================================================================= -->
<h4>
<a name="llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>
</h4>
<div>
<pre>
i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
</pre>
<p>For SJLJ based exception handling, this intrinsic forces register saving for
the current function and stores the address of the following instruction for
use as a destination address
by <a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a>. The
buffer format and the overall functioning of this intrinsic is compatible
with the GCC <tt>__builtin_setjmp</tt> implementation allowing code built
with the clang and GCC to interoperate.</p>
<p>The single parameter is a pointer to a five word buffer in which the calling
context is saved. The front end places the frame pointer in the first word,
and the target implementation of this intrinsic should place the destination
address for a
<a href="#llvm_eh_sjlj_longjmp"><tt>llvm.eh.sjlj.longjmp</tt></a> in the
second word. The following three words are available for use in a
target-specific manner.</p>
</div>
<!-- ======================================================================= -->
<h4>
<a name="llvm_eh_sjlj_longjmp">llvm.eh.sjlj.longjmp</a>
</h4>
<div>
<pre>
void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
</pre>
<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.longjmp</tt>
intrinsic is used to implement <tt>__builtin_longjmp()</tt>. The single
parameter is a pointer to a buffer populated
by <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a>. The frame
pointer and stack pointer are restored from the buffer, then control is
transferred to the destination address.</p>
</div>
<!-- ======================================================================= -->
<h4>
<a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>
</h4>
<div>
<pre>
i8* @llvm.eh.sjlj.lsda()
</pre>
<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.lsda</tt> intrinsic
returns the address of the Language Specific Data Area (LSDA) for the current
function. The SJLJ front-end code stores this address in the exception
handling function context for use by the runtime.</p>
</div>
<!-- ======================================================================= -->
<h4>
<a name="llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>
</h4>
<div>
<pre>
void @llvm.eh.sjlj.callsite(i32 %call_site_num)
</pre>
<p>For SJLJ based exception handling, the <tt>llvm.eh.sjlj.callsite</tt>
intrinsic identifies the callsite value associated with the
following <tt>invoke</tt> instruction. This is used to ensure that landing
pad entries in the LSDA are generated in matching order.</p>
</div>
</div>
<!-- ======================================================================= -->
<h2>
<a name="asm">Asm Table Formats</a>
</h2>
<div>
<p>There are two tables that are used by the exception handling runtime to
determine which actions should be taken when an exception is thrown.</p>
<!-- ======================================================================= -->
<h3>
<a name="unwind_tables">Exception Handling Frame</a>
</h3>
<div>
<p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind
frame used by DWARF debug info. The frame contains all the information
necessary to tear down the current frame and restore the state of the prior
frame. There is an exception handling frame for each function in a compile
unit, plus a common exception handling frame that defines information common
to all functions in the unit.</p>
<!-- Todo - Table details here. -->
</div>
<!-- ======================================================================= -->
<h3>
<a name="exception_tables">Exception Tables</a>
</h3>
<div>
<p>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
exception table per function, except leaf functions and functions that have
calls only to non-throwing functions. They do not need an exception
table.</p>
<!-- Todo - Table details here. -->
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $
</address>
</body>
</html>

133
cpp/llvm/docs/ExtendedIntegerResults.txt
View File

@ -1,133 +0,0 @@
//===----------------------------------------------------------------------===//
// Representing sign/zero extension of function results
//===----------------------------------------------------------------------===//
Mar 25, 2009 - Initial Revision
Most ABIs specify that functions which return small integers do so in a
specific integer GPR. This is an efficient way to go, but raises the question:
if the returned value is smaller than the register, what do the high bits hold?
There are three (interesting) possible answers: undefined, zero extended, or
sign extended. The number of bits in question depends on the data-type that
the front-end is referencing (typically i1/i8/i16/i32).
Knowing the answer to this is important for two reasons: 1) we want to be able
to implement the ABI correctly. If we need to sign extend the result according
to the ABI, we really really do need to do this to preserve correctness. 2)
this information is often useful for optimization purposes, and we want the
mid-level optimizers to be able to process this (e.g. eliminate redundant
extensions).
For example, lets pretend that X86 requires the caller to properly extend the
result of a return (I'm not sure this is the case, but the argument doesn't
depend on this). Given this, we should compile this:
int a();
short b() { return a(); }
into:
_b:
subl $12, %esp
call L_a$stub
addl $12, %esp
cwtl
ret
An optimization example is that we should be able to eliminate the explicit
sign extension in this example:
short y();
int z() {
return ((int)y() << 16) >> 16;
}
_z:
subl $12, %esp
call _y
;; movswl %ax, %eax -> not needed because eax is already sext'd
addl $12, %esp
ret
//===----------------------------------------------------------------------===//
// What we have right now.
//===----------------------------------------------------------------------===//
Currently, these sorts of things are modelled by compiling a function to return
the small type and a signext/zeroext marker is used. For example, we compile
Z into:
define i32 @z() nounwind {
entry:
%0 = tail call signext i16 (...)* @y() nounwind
%1 = sext i16 %0 to i32
ret i32 %1
}
and b into:
define signext i16 @b() nounwind {
entry:
%0 = tail call i32 (...)* @a() nounwind ; <i32> [#uses=1]
%retval12 = trunc i32 %0 to i16 ; <i16> [#uses=1]
ret i16 %retval12
}
This has some problems: 1) the actual precise semantics are really poorly
defined (see PR3779). 2) some targets might want the caller to extend, some
might want the callee to extend 3) the mid-level optimizer doesn't know the
size of the GPR, so it doesn't know that %0 is sign extended up to 32-bits
here, and even if it did, it could not eliminate the sext. 4) the code
generator has historically assumed that the result is extended to i32, which is
a problem on PIC16 (and is also probably wrong on alpha and other 64-bit
targets).
//===----------------------------------------------------------------------===//
// The proposal
//===----------------------------------------------------------------------===//
I suggest that we have the front-end fully lower out the ABI issues here to
LLVM IR. This makes it 100% explicit what is going on and means that there is
no cause for confusion. For example, the cases above should compile into:
define i32 @z() nounwind {
entry:
%0 = tail call i32 (...)* @y() nounwind
%1 = trunc i32 %0 to i16
%2 = sext i16 %1 to i32
ret i32 %2
}
define i32 @b() nounwind {
entry:
%0 = tail call i32 (...)* @a() nounwind
%retval12 = trunc i32 %0 to i16
%tmp = sext i16 %retval12 to i32
ret i32 %tmp
}
In this model, no functions will return an i1/i8/i16 (and on a x86-64 target
that extends results to i64, no i32). This solves the ambiguity issue, allows us
to fully describe all possible ABIs, and now allows the optimizers to reason
about and eliminate these extensions.
The one thing that is missing is the ability for the front-end and optimizer to
specify/infer the guarantees provided by the ABI to allow other optimizations.
For example, in the y/z case, since y is known to return a sign extended value,
the trunc/sext in z should be eliminable.
This can be done by introducing new sext/zext attributes which mean "I know
that the result of the function is sign extended at least N bits. Given this,
and given that it is stuck on the y function, the mid-level optimizer could
easily eliminate the extensions etc with existing functionality.
The major disadvantage of doing this sort of thing is that it makes the ABI
lowering stuff even more explicit in the front-end, and that we would like to
eventually move to having the code generator do more of this work. However,
the sad truth of the matter is that this is a) unlikely to happen anytime in
the near future, and b) this is no worse than we have now with the existing
attributes.
C compilers fundamentally have to reason about the target in many ways.
This is ugly and horrible, but a fact of life.

379
cpp/llvm/docs/ExtendingLLVM.html
View File

@ -1,379 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Extending LLVM: Adding instructions, intrinsics, types, etc.</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>
Extending LLVM: Adding instructions, intrinsics, types, etc.
</h1>
<ol>
<li><a href="#introduction">Introduction and Warning</a></li>
<li><a href="#intrinsic">Adding a new intrinsic function</a></li>
<li><a href="#instruction">Adding a new instruction</a></li>
<li><a href="#sdnode">Adding a new SelectionDAG node</a></li>
<li><a href="#type">Adding a new type</a>
<ol>
<li><a href="#fund_type">Adding a new fundamental type</a></li>
<li><a href="#derived_type">Adding a new derived type</a></li>
</ol></li>
</ol>
<div class="doc_author">
<p>Written by <a href="http://misha.brukman.net">Misha Brukman</a>,
Brad Jones, Nate Begeman,
and <a href="http://nondot.org/sabre">Chris Lattner</a></p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="introduction">Introduction and Warning</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
you need to add something to LLVM, whether it be a new fundamental type, a new
intrinsic function, or a whole new instruction.</p>
<p>When you come to this realization, stop and think. Do you really need to
extend LLVM? Is it a new fundamental capability that LLVM does not support at
its current incarnation or can it be synthesized from already pre-existing LLVM
elements? If you are not sure, ask on the <a
href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM-dev</a> list. The
reason is that extending LLVM will get involved as you need to update all the
different passes that you intend to use with your extension, and there are
<em>many</em> LLVM analyses and transformations, so it may be quite a bit of
work.</p>
<p>Adding an <a href="#intrinsic">intrinsic function</a> is far easier than
adding an instruction, and is transparent to optimization passes. If your added
functionality can be expressed as a
function call, an intrinsic function is the method of choice for LLVM
extension.</p>
<p>Before you invest a significant amount of effort into a non-trivial
extension, <span class="doc_warning">ask on the list</span> if what you are
looking to do can be done with already-existing infrastructure, or if maybe
someone else is already working on it. You will save yourself a lot of time and
effort by doing so.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="intrinsic">Adding a new intrinsic function</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
function and then be turned into an instruction if warranted.</p>
<ol>
<li><tt>llvm/docs/LangRef.html</tt>:
Document the intrinsic. Decide whether it is code generator specific and
what the restrictions are. Talk to other people about it so that you are
sure it's a good idea.</li>
<li><tt>llvm/include/llvm/Intrinsics*.td</tt>:
Add an entry for your intrinsic. Describe its memory access characteristics
for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note
that any intrinsic using the <tt>llvm_int_ty</tt> type for an argument will
be deemed by <tt>tblgen</tt> as overloaded and the corresponding suffix
will be required on the intrinsic's name.</li>
<li><tt>llvm/lib/Analysis/ConstantFolding.cpp</tt>: If it is possible to
constant fold your intrinsic, add support to it in the
<tt>canConstantFoldCallTo</tt> and <tt>ConstantFoldCall</tt> functions.</li>
<li><tt>llvm/test/Regression/*</tt>: Add test cases for your test cases to the
test suite</li>
</ol>
<p>Once the intrinsic has been added to the system, you must add code generator
support for it. Generally you must do the following steps:</p>
<dl>
<dt>Add support to the .td file for the target(s) of your choice in
<tt>lib/Target/*/*.td</tt>.</dt>
<dd>This is usually a matter of adding a pattern to the .td file that matches
the intrinsic, though it may obviously require adding the instructions you
want to generate as well. There are lots of examples in the PowerPC and X86
backend to follow.</dd>
</dl>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="sdnode">Adding a new SelectionDAG node</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
instructions common to many targets. These nodes often map to an LLVM
instruction (add, sub) or intrinsic (byteswap, population count). In other
cases, new nodes have been added to allow many targets to perform a common task
(converting between floating point and integer representation) or capture more
complicated behavior in a single node (rotate).</p>
<ol>
<li><tt>include/llvm/CodeGen/ISDOpcodes.h</tt>:
Add an enum value for the new SelectionDAG node.</li>
<li><tt>lib/CodeGen/SelectionDAG/SelectionDAG.cpp</tt>:
Add code to print the node to <tt>getOperationName</tt>. If your new node
can be evaluated at compile time when given constant arguments (such as an
add of a constant with another constant), find the <tt>getNode</tt> method
that takes the appropriate number of arguments, and add a case for your node
to the switch statement that performs constant folding for nodes that take
the same number of arguments as your new node.</li>
<li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
Add code to <a href="CodeGenerator.html#selectiondag_legalize">legalize,
promote, and expand</a> the node as necessary. At a minimum, you will need
to add a case statement for your node in <tt>LegalizeOp</tt> which calls
LegalizeOp on the node's operands, and returns a new node if any of the
operands changed as a result of being legalized. It is likely that not all
targets supported by the SelectionDAG framework will natively support the
new node. In this case, you must also add code in your node's case
statement in <tt>LegalizeOp</tt> to Expand your node into simpler, legal
operations. The case for <tt>ISD::UREM</tt> for expanding a remainder into
a divide, multiply, and a subtract is a good example.</li>
<li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
If targets may support the new node being added only at certain sizes, you
will also need to add code to your node's case statement in
<tt>LegalizeOp</tt> to Promote your node's operands to a larger size, and
perform the correct operation. You will also need to add code to
<tt>PromoteOp</tt> to do this as well. For a good example, see
<tt>ISD::BSWAP</tt>,
which promotes its operand to a wider size, performs the byteswap, and then
shifts the correct bytes right to emulate the narrower byteswap in the
wider type.</li>
<li><tt>lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</tt>:
Add a case for your node in <tt>ExpandOp</tt> to teach the legalizer how to
perform the action represented by the new node on a value that has been
split into high and low halves. This case will be used to support your
node with a 64 bit operand on a 32 bit target.</li>
<li><tt>lib/CodeGen/SelectionDAG/DAGCombiner.cpp</tt>:
If your node can be combined with itself, or other existing nodes in a
peephole-like fashion, add a visit function for it, and call that function
from <tt></tt>. There are several good examples for simple combines you
can do; <tt>visitFABS</tt> and <tt>visitSRL</tt> are good starting places.
</li>
<li><tt>lib/Target/PowerPC/PPCISelLowering.cpp</tt>:
Each target has an implementation of the <tt>TargetLowering</tt> class,
usually in its own file (although some targets include it in the same
file as the DAGToDAGISel). The default behavior for a target is to
assume that your new node is legal for all types that are legal for
that target. If this target does not natively support your node, then
tell the target to either Promote it (if it is supported at a larger
type) or Expand it. This will cause the code you wrote in
<tt>LegalizeOp</tt> above to decompose your new node into other legal
nodes for this target.</li>
<li><tt>lib/Target/TargetSelectionDAG.td</tt>:
Most current targets supported by LLVM generate code using the DAGToDAG
method, where SelectionDAG nodes are pattern matched to target-specific
nodes, which represent individual instructions. In order for the targets
to match an instruction to your new node, you must add a def for that node
to the list in this file, with the appropriate type constraints. Look at
<tt>add</tt>, <tt>bswap</tt>, and <tt>fadd</tt> for examples.</li>
<li><tt>lib/Target/PowerPC/PPCInstrInfo.td</tt>:
Each target has a tablegen file that describes the target's instruction
set. For targets that use the DAGToDAG instruction selection framework,
add a pattern for your new node that uses one or more target nodes.
Documentation for this is a bit sparse right now, but there are several
decent examples. See the patterns for <tt>rotl</tt> in
<tt>PPCInstrInfo.td</tt>.</li>
<li>TODO: document complex patterns.</li>
<li><tt>llvm/test/Regression/CodeGen/*</tt>: Add test cases for your new node
to the test suite. <tt>llvm/test/Regression/CodeGen/X86/bswap.ll</tt> is
a good example.</li>
</ol>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="instruction">Adding a new instruction</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p><span class="doc_warning">WARNING: adding instructions changes the bitcode
format, and it will take some effort to maintain compatibility with
the previous version.</span> Only add an instruction if it is absolutely
necessary.</p>
<ol>
<li><tt>llvm/include/llvm/Instruction.def</tt>:
add a number for your instruction and an enum name</li>
<li><tt>llvm/include/llvm/Instructions.h</tt>:
add a definition for the class that will represent your instruction</li>
<li><tt>llvm/include/llvm/Support/InstVisitor.h</tt>:
add a prototype for a visitor to your new instruction type</li>
<li><tt>llvm/lib/AsmParser/Lexer.l</tt>:
add a new token to parse your instruction from assembly text file</li>
<li><tt>llvm/lib/AsmParser/llvmAsmParser.y</tt>:
add the grammar on how your instruction can be read and what it will
construct as a result</li>
<li><tt>llvm/lib/Bitcode/Reader/Reader.cpp</tt>:
add a case for your instruction and how it will be parsed from bitcode</li>
<li><tt>llvm/lib/VMCore/Instruction.cpp</tt>:
add a case for how your instruction will be printed out to assembly</li>
<li><tt>llvm/lib/VMCore/Instructions.cpp</tt>:
implement the class you defined in
<tt>llvm/include/llvm/Instructions.h</tt></li>
<li>Test your instruction</li>
<li><tt>llvm/lib/Target/*</tt>:
Add support for your instruction to code generators, or add a lowering
pass.</li>
<li><tt>llvm/test/Regression/*</tt>: add your test cases to the test suite.</li>
</ol>
<p>Also, you need to implement (or modify) any analyses or passes that you want
to understand this new instruction.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="type">Adding a new type</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p><span class="doc_warning">WARNING: adding new types changes the bitcode
format, and will break compatibility with currently-existing LLVM
installations.</span> Only add new types if it is absolutely necessary.</p>
<!-- ======================================================================= -->
<h3>
<a name="fund_type">Adding a fundamental type</a>
</h3>
<div>
<ol>
<li><tt>llvm/include/llvm/Type.h</tt>:
add enum for the new type; add static <tt>Type*</tt> for this type</li>
<li><tt>llvm/lib/VMCore/Type.cpp</tt>:
add mapping from <tt>TypeID</tt> =&gt; <tt>Type*</tt>;
initialize the static <tt>Type*</tt></li>
<li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
add ability to parse in the type from text assembly</li>
<li><tt>llvm/lib/AsmReader/llvmAsmParser.y</tt>:
add a token for that type</li>
</ol>
</div>
<!-- ======================================================================= -->
<h3>
<a name="derived_type">Adding a derived type</a>
</h3>
<div>
<ol>
<li><tt>llvm/include/llvm/Type.h</tt>:
add enum for the new type; add a forward declaration of the type
also</li>
<li><tt>llvm/include/llvm/DerivedTypes.h</tt>:
add new class to represent new class in the hierarchy; add forward
declaration to the TypeMap value type</li>
<li><tt>llvm/lib/VMCore/Type.cpp</tt>:
add support for derived type to:
<div class="doc_code">
<pre>
std::string getTypeDescription(const Type &amp;Ty,
std::vector&lt;const Type*&gt; &amp;TypeStack)
bool TypesEqual(const Type *Ty, const Type *Ty2,
std::map&lt;const Type*, const Type*&gt; &amp; EqTypes)
</pre>
</div>
add necessary member functions for type, and factory methods</li>
<li><tt>llvm/lib/AsmReader/Lexer.l</tt>:
add ability to parse in the type from text assembly</li>
<li><tt>llvm/lib/BitCode/Writer/Writer.cpp</tt>:
modify <tt>void BitcodeWriter::outputType(const Type *T)</tt> to serialize
your type</li>
<li><tt>llvm/lib/BitCode/Reader/Reader.cpp</tt>:
modify <tt>const Type *BitcodeReader::ParseType()</tt> to read your data
type</li>
<li><tt>llvm/lib/VMCore/AsmWriter.cpp</tt>:
modify
<div class="doc_code">
<pre>
void calcTypeName(const Type *Ty,
std::vector&lt;const Type*&gt; &amp;TypeStack,
std::map&lt;const Type*,std::string&gt; &amp;TypeNames,
std::string &amp; Result)
</pre>
</div>
to output the new derived type
</li>
</ol>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date: 2012-03-22 22:50:46 -0700 (Thu, 22 Mar 2012) $
</address>
</body>
</html>

948
cpp/llvm/docs/FAQ.html
View File

@ -1,948 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM: Frequently Asked Questions</title>
<style type="text/css">
@import url("llvm.css");
.question { font-weight: bold }
.answer { margin-left: 2em }
</style>
</head>
<body>
<h1>
LLVM: Frequently Asked Questions
</h1>
<ol>
<li><a href="#license">License</a>
<ol>
<li>Why are the LLVM source code and the front-end distributed under
different licenses?</li>
<li>Does the University of Illinois Open Source License really qualify as an
"open source" license?</li>
<li>Can I modify LLVM source code and redistribute the modified source?</li>
<li>Can I modify LLVM source code and redistribute binaries or other tools
based on it, without redistributing the source?</li>
</ol></li>
<li><a href="#source">Source code</a>
<ol>
<li>In what language is LLVM written?</li>
<li>How portable is the LLVM source code?</li>
</ol></li>
<li><a href="#build">Build Problems</a>
<ol>
<li>When I run configure, it finds the wrong C compiler.</li>
<li>The <tt>configure</tt> script finds the right C compiler, but it uses
the LLVM linker from a previous build. What do I do?</li>
<li>When creating a dynamic library, I get a strange GLIBC error.</li>
<li>I've updated my source tree from Subversion, and now my build is trying
to use a file/directory that doesn't exist.</li>
<li>I've modified a Makefile in my source tree, but my build tree keeps
using the old version. What do I do?</li>
<li>I've upgraded to a new version of LLVM, and I get strange build
errors.</li>
<li>I've built LLVM and am testing it, but the tests freeze.</li>
<li>Why do test results differ when I perform different types of
builds?</li>
<li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
<li>Compiling LLVM with GCC succeeds, but the resulting tools do not work,
what can be wrong?</li>
<li>When I use the test suite, all of the C Backend tests fail. What is
wrong?</li>
<li>After Subversion update, rebuilding gives the error "No rule to make
target".</li>
<li><a href="#srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir,
it fails. Why?</a></li>
</ol></li>
<li><a href="#felangs">Source Languages</a>
<ol>
<li><a href="#langs">What source languages are supported?</a></li>
<li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
should I interface with the LLVM middle-end optimizers and back-end code
generators?</a></li>
<li><a href="#langhlsupp">What support is there for higher level source
language constructs for building a compiler?</a></li>
<li><a href="GetElementPtr.html">I don't understand the GetElementPtr
instruction. Help!</a></li>
</ol>
<li><a href="#cfe">Using the GCC Front End</a>
<ol>
<li>When I compile software that uses a configure script, the configure
script thinks my system has all of the header files and libraries it is
testing for. How do I get configure to work correctly?</li>
<li>When I compile code using the LLVM GCC front end, it complains that it
cannot find libcrtend.a?</li>
<li>How can I disable all optimizations when compiling code using the LLVM
GCC front end?</li>
<li><a href="#translatecxx">Can I use LLVM to convert C++ code to C
code?</a></li>
<li><a href="#platformindependent">Can I compile C or C++ code to
platform-independent LLVM bitcode?</a></li>
</ol>
</li>
<li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
<ol>
<li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
<tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
#include &lt;iostream&gt;?</a></li>
<li><a href="#codedce">Where did all of my code go??</a></li>
<li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in
my code?</a></li>
<li><a href="#callconvwrong">Why does instcombine + simplifycfg turn
a call to a function with a mismatched calling convention into "unreachable"?
Why not make the verifier reject it?</a></li>
</ol>
</li>
</ol>
<div class="doc_author">
<p>Written by <a href="http://llvm.org/">The LLVM Team</a></p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="license">License</a>
</h2>
<!-- *********************************************************************** -->
<div>
<div class="question">
<p>Why are the LLVM source code and the front-end distributed under different
licenses?</p>
</div>
<div class="answer">
<p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
Our aim is to distribute LLVM source code under a <em>much less
restrictive</em> license, in particular one that does not compel users who
distribute tools based on modifying the source to redistribute the modified
source code as well.</p>
</div>
<div class="question">
<p>Does the University of Illinois Open Source License really qualify as an
"open source" license?</p>
</div>
<div class="answer">
<p>Yes, the license
is <a href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by
the Open Source Initiative (OSI).</p>
</div>
<div class="question">
<p>Can I modify LLVM source code and redistribute the modified source?</p>
</div>
<div class="answer">
<p>Yes. The modified source distribution must retain the copyright notice and
follow the three bulletted conditions listed in
the <a href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM
license</a>.</p>
</div>
<div class="question">
<p>Can I modify LLVM source code and redistribute binaries or other tools based
on it, without redistributing the source?</p>
</div>
<div class="answer">
<p>Yes. This is why we distribute LLVM under a less restrictive license than
GPL, as explained in the first question above.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="source">Source Code</a>
</h2>
<!-- *********************************************************************** -->
<div>
<div class="question">
<p>In what language is LLVM written?</p>
</div>
<div class="answer">
<p>All of the LLVM tools and libraries are written in C++ with extensive use of
the STL.</p>
</div>
<div class="question">
<p>How portable is the LLVM source code?</p>
</div>
<div class="answer">
<p>The LLVM source code should be portable to most modern UNIX-like operating
systems. Most of the code is written in standard C++ with operating system
services abstracted to a support library. The tools required to build and test
LLVM have been ported to a plethora of platforms.</p>
<p>Some porting problems may exist in the following areas:</p>
<ul>
<li>The GCC front end code is not as portable as the LLVM suite, so it may not
compile as well on unsupported platforms.</li>
<li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
Shell and sed. Porting to systems without these tools (MacOS 9, Plan 9)
will require more effort.</li>
</ul>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="build">Build Problems</a>
</h2>
<!-- *********************************************************************** -->
<div>
<div class="question">
<p>When I run configure, it finds the wrong C compiler.</p>
</div>
<div class="answer">
<p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
<tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt>
and <tt>CXX</tt> for the C and C++ compiler, respectively.</p>
<p>If <tt>configure</tt> finds the wrong compiler, either adjust your
<tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
explicitly.</p>
</div>
<div class="question">
<p>The <tt>configure</tt> script finds the right C compiler, but it uses the
LLVM linker from a previous build. What do I do?</p>
</div>
<div class="answer">
<p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
it:</p>
<ol>
<li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
program appears first in the <tt>PATH</tt>. This may work, but may not be
convenient when you want them <i>first</i> in your path for other
work.</p></li>
<li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
correct. In a Borne compatible shell, the syntax would be:</p>
<pre class="doc_code">
% PATH=[the path without the bad program] ./configure ...
</pre>
<p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
to do its work without having to adjust your <tt>PATH</tt>
permanently.</p></li>
</ol>
</div>
<div class="question">
<p>When creating a dynamic library, I get a strange GLIBC error.</p>
</div>
<div class="answer">
<p>Under some operating systems (i.e. Linux), libtool does not work correctly if
GCC was compiled with the --disable-shared option. To work around this,
install your own version of GCC that has shared libraries enabled by
default.</p>
</div>
<div class="question">
<p>I've updated my source tree from Subversion, and now my build is trying to
use a file/directory that doesn't exist.</p>
</div>
<div class="answer">
<p>You need to re-run configure in your object directory. When new Makefiles
are added to the source tree, they have to be copied over to the object tree
in order to be used by the build.</p>
</div>
<div class="question">
<p>I've modified a Makefile in my source tree, but my build tree keeps using the
old version. What do I do?</p>
</div>
<div class="answer">
<p>If the Makefile already exists in your object tree, you can just run the
following command in the top level directory of your object tree:</p>
<pre class="doc_code">
% ./config.status &lt;relative path to Makefile&gt;
</pre>
<p>If the Makefile is new, you will have to modify the configure script to copy
it over.</p>
</div>
<div class="question">
<p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
</div>
<div class="answer">
<p>Sometimes, changes to the LLVM source code alters how the build system works.
Changes in libtool, autoconf, or header file dependencies are especially
prone to this sort of problem.</p>
<p>The best thing to try is to remove the old files and re-build. In most
cases, this takes care of the problem. To do this, just type <tt>make
clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
</div>
<div class="question">
<p>I've built LLVM and am testing it, but the tests freeze.</p>
</div>
<div class="answer">
<p>This is most likely occurring because you built a profile or release
(optimized) build of LLVM and have not specified the same information on the
<tt>gmake</tt> command line.</p>
<p>For example, if you built LLVM with the command:</p>
<pre class="doc_code">
% gmake ENABLE_PROFILING=1
</pre>
<p>...then you must run the tests with the following commands:</p>
<pre class="doc_code">
% cd llvm/test
% gmake ENABLE_PROFILING=1
</pre>
</div>
<div class="question">
<p>Why do test results differ when I perform different types of builds?</p>
</div>
<div class="answer">
<p>The LLVM test suite is dependent upon several features of the LLVM tools and
libraries.</p>
<p>First, the debugging assertions in code are not enabled in optimized or
profiling builds. Hence, tests that used to fail may pass.</p>
<p>Second, some tests may rely upon debugging options or behavior that is only
available in the debug build. These tests will fail in an optimized or
profile build.</p>
</div>
<div class="question">
<p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
</div>
<div class="answer">
<p>This is <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392">a bug in
GCC</a>, and affects projects other than LLVM. Try upgrading or downgrading
your GCC.</p>
</div>
<div class="question">
<p>Compiling LLVM with GCC succeeds, but the resulting tools do not work, what
can be wrong?</p>
</div>
<div class="answer">
<p>Several versions of GCC have shown a weakness in miscompiling the LLVM
codebase. Please consult your compiler version (<tt>gcc --version</tt>) to
find out whether it is <a href="GettingStarted.html#brokengcc">broken</a>.
If so, your only option is to upgrade GCC to a known good version.</p>
</div>
<div class="question">
<p>After Subversion update, rebuilding gives the error "No rule to make
target".</p>
</div>
<div class="answer">
<p>If the error is of the form:</p>
<pre class="doc_code">
gmake[2]: *** No rule to make target `/path/to/somefile', needed by
`/path/to/another/file.d'.<br>
Stop.
</pre>
<p>This may occur anytime files are moved within the Subversion repository or
removed entirely. In this case, the best solution is to erase all
<tt>.d</tt> files, which list dependencies for source files, and rebuild:</p>
<pre class="doc_code">
% cd $LLVM_OBJ_DIR
% rm -f `find . -name \*\.d`
% gmake
</pre>
<p>In other cases, it may be necessary to run <tt>make clean</tt> before
rebuilding.</p>
</div>
<div class="question">
<p><a name="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it
fails. Why?</a></p>
</div>
<div class="answer">
<p>The <tt>GNUmakefile</tt> in the top-level directory of LLVM-GCC is a special
<tt>Makefile</tt> used by Apple to invoke the <tt>build_gcc</tt> script after
setting up a special environment. This has the unfortunate side-effect that
trying to build LLVM-GCC with srcdir == objdir in a "non-Apple way" invokes
the <tt>GNUmakefile</tt> instead of <tt>Makefile</tt>. Because the
environment isn't set up correctly to do this, the build fails.</p>
<p>People not building LLVM-GCC the "Apple way" need to build LLVM-GCC with
srcdir != objdir, or simply remove the GNUmakefile entirely.</p>
<p>We regret the inconvenience.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="felangs">Source Languages</a>
</h2>
<div>
<div class="question">
<p><a name="langs">What source languages are supported?</a></p>
</div>
<div class="answer">
<p>LLVM currently has full support for C and C++ source languages. These are
available through a special version of GCC that LLVM calls the
<a href="#cfe">C Front End</a></p>
<p>There is an incomplete version of a Java front end available in the
<tt>java</tt> module. There is no documentation on this yet so you'll need to
download the code, compile it, and try it.</p>
<p>The PyPy developers are working on integrating LLVM into the PyPy backend so
that PyPy language can translate to LLVM.</p>
</div>
<div class="question">
<p><a name="langirgen">I'd like to write a self-hosting LLVM compiler. How
should I interface with the LLVM middle-end optimizers and back-end code
generators?</a></p>
</div>
<div class="answer">
<p>Your compiler front-end will communicate with LLVM by creating a module in
the LLVM intermediate representation (IR) format. Assuming you want to write
your language's compiler in the language itself (rather than C++), there are
3 major ways to tackle generating LLVM IR from a front-end:</p>
<ul>
<li><strong>Call into the LLVM libraries code using your language's FFI
(foreign function interface).</strong>
<ul>
<li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc
format</li>
<li><em>for:</em> enables running LLVM optimization passes without a
emit/parse overhead</li>
<li><em>for:</em> adapts well to a JIT context</li>
<li><em>against:</em> lots of ugly glue code to write</li>
</ul></li>
<li> <strong>Emit LLVM assembly from your compiler's native language.</strong>
<ul>
<li><em>for:</em> very straightforward to get started</li>
<li><em>against:</em> the .ll parser is slower than the bitcode reader
when interfacing to the middle end</li>
<li><em>against:</em> you'll have to re-engineer the LLVM IR object model
and asm writer in your language</li>
<li><em>against:</em> it may be harder to track changes to the IR</li>
</ul></li>
<li><strong>Emit LLVM bitcode from your compiler's native language.</strong>
<ul>
<li><em>for:</em> can use the more-efficient bitcode reader when
interfacing to the middle end</li>
<li><em>against:</em> you'll have to re-engineer the LLVM IR object
model and bitcode writer in your language</li>
<li><em>against:</em> it may be harder to track changes to the IR</li>
</ul></li>
</ul>
<p>If you go with the first option, the C bindings in include/llvm-c should help
a lot, since most languages have strong support for interfacing with C. The
most common hurdle with calling C from managed code is interfacing with the
garbage collector. The C interface was designed to require very little memory
management, and so is straightforward in this regard.</p>
</div>
<div class="question">
<p><a name="langhlsupp">What support is there for a higher level source language
constructs for building a compiler?</a></p>
</div>
<div class="answer">
<p>Currently, there isn't much. LLVM supports an intermediate representation
which is useful for code representation but will not support the high level
(abstract syntax tree) representation needed by most compilers. There are no
facilities for lexical nor semantic analysis.</p>
</div>
<div class="question">
<p><a name="getelementptr">I don't understand the GetElementPtr
instruction. Help!</a></p>
</div>
<div class="answer">
<p>See <a href="GetElementPtr.html">The Often Misunderstood GEP
Instruction</a>.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="cfe">Using the GCC Front End</a>
</h2>
<div>
<div class="question">
<p>When I compile software that uses a configure script, the configure script
thinks my system has all of the header files and libraries it is testing for.
How do I get configure to work correctly?</p>
</div>
<div class="answer">
<p>The configure script is getting things wrong because the LLVM linker allows
symbols to be undefined at link time (so that they can be resolved during JIT
or translation to the C back end). That is why configure thinks your system
"has everything."</p>
<p>To work around this, perform the following steps:</p>
<ol>
<li>Make sure the CC and CXX environment variables contains the full path to
the LLVM GCC front end.</li>
<li>Make sure that the regular C compiler is first in your PATH. </li>
<li>Add the string "-Wl,-native" to your CFLAGS environment variable.</li>
</ol>
<p>This will allow the <tt>llvm-ld</tt> linker to create a native code
executable instead of shell script that runs the JIT. Creating native code
requires standard linkage, which in turn will allow the configure script to
find out if code is not linking on your system because the feature isn't
available on your system.</p>
</div>
<div class="question">
<p>When I compile code using the LLVM GCC front end, it complains that it cannot
find libcrtend.a.
</p>
</div>
<div class="answer">
<p>The only way this can happen is if you haven't installed the runtime
library. To correct this, do:</p>
<pre class="doc_code">
% cd llvm/runtime
% make clean ; make install-bytecode
</pre>
</div>
<div class="question">
<p>How can I disable all optimizations when compiling code using the LLVM GCC
front end?</p>
</div>
<div class="answer">
<p>Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and
optimizations done at the llvm level, leaving you with the truly horrible
code that you desire.</p>
</div>
<div class="question">
<p><a name="translatecxx">Can I use LLVM to convert C++ code to C code?</a></p>
</div>
<div class="answer">
<p>Yes, you can use LLVM to convert code from any language LLVM supports to C.
Note that the generated C code will be very low level (all loops are lowered
to gotos, etc) and not very pretty (comments are stripped, original source
formatting is totally lost, variables are renamed, expressions are
regrouped), so this may not be what you're looking for. Also, there are
several limitations noted below.<p>
<p>Use commands like this:</p>
<ol>
<li><p>Compile your program with llvm-g++:</p>
<pre class="doc_code">
% llvm-g++ -emit-llvm x.cpp -o program.bc -c
</pre>
<p>or:</p>
<pre class="doc_code">
% llvm-g++ a.cpp -c -emit-llvm
% llvm-g++ b.cpp -c -emit-llvm
% llvm-ld a.o b.o -o program
</pre>
<p>This will generate program and program.bc. The .bc
file is the LLVM version of the program all linked together.</p></li>
<li><p>Convert the LLVM code to C code, using the LLC tool with the C
backend:</p>
<pre class="doc_code">
% llc -march=c program.bc -o program.c
</pre></li>
<li><p>Finally, compile the C file:</p>
<pre class="doc_code">
% cc x.c -lstdc++
</pre></li>
</ol>
<p>Using LLVM does not eliminate the need for C++ library support. If you use
the llvm-g++ front-end, the generated code will depend on g++'s C++ support
libraries in the same way that code generated from g++ would. If you use
another C++ front-end, the generated code will depend on whatever library
that front-end would normally require.</p>
<p>If you are working on a platform that does not provide any C++ libraries, you
may be able to manually compile libstdc++ to LLVM bitcode, statically link it
into your program, then use the commands above to convert the whole result
into C code. Alternatively, you might compile the libraries and your
application into two different chunks of C code and link them.</p>
<p>Note that, by default, the C back end does not support exception handling.
If you want/need it for a certain program, you can enable it by passing
"-enable-correct-eh-support" to the llc program. The resultant code will use
setjmp/longjmp to implement exception support that is relatively slow, and
not C++-ABI-conforming on most platforms, but otherwise correct.</p>
<p>Also, there are a number of other limitations of the C backend that cause it
to produce code that does not fully conform to the C++ ABI on most
platforms. Some of the C++ programs in LLVM's test suite are known to fail
when compiled with the C back end because of ABI incompatibilities with
standard C++ libraries.</p>
</div>
<div class="question">
<p><a name="platformindependent">Can I compile C or C++ code to
platform-independent LLVM bitcode?</a></p>
</div>
<div class="answer">
<p>No. C and C++ are inherently platform-dependent languages. The most obvious
example of this is the preprocessor. A very common way that C code is made
portable is by using the preprocessor to include platform-specific code. In
practice, information about other platforms is lost after preprocessing, so
the result is inherently dependent on the platform that the preprocessing was
targeting.</p>
<p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to
vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to
a constant immediately, thus hard-wiring a platform-specific detail.</p>
<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
lower-level than C, front-ends currently must emit platform-specific IR in
order to have the result conform to the platform ABI.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="cfe_code">Questions about code generated by the GCC front-end</a>
</h2>
<div>
<div class="question">
<p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and
<tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I <tt>#include
&lt;iostream&gt;</tt>?</a></p>
</div>
<div class="answer">
<p>If you <tt>#include</tt> the <tt>&lt;iostream&gt;</tt> header into a C++
translation unit, the file will probably use
the <tt>std::cin</tt>/<tt>std::cout</tt>/... global objects. However, C++
does not guarantee an order of initialization between static objects in
different translation units, so if a static ctor/dtor in your .cpp file
used <tt>std::cout</tt>, for example, the object would not necessarily be
automatically initialized before your use.</p>
<p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
STL that we use declares a static object that gets created in every
translation unit that includes <tt>&lt;iostream&gt;</tt>. This object has a
static constructor and destructor that initializes and destroys the global
iostream objects before they could possibly be used in the file. The code
that you see in the .ll file corresponds to the constructor and destructor
registration code.
</p>
<p>If you would like to make it easier to <b>understand</b> the LLVM code
generated by the compiler in the demo page, consider using <tt>printf()</tt>
instead of <tt>iostream</tt>s to print values.</p>
</div>
<!--=========================================================================-->
<div class="question">
<p><a name="codedce">Where did all of my code go??</a></p>
</div>
<div class="answer">
<p>If you are using the LLVM demo page, you may often wonder what happened to
all of the code that you typed in. Remember that the demo script is running
the code through the LLVM optimizers, so if your code doesn't actually do
anything useful, it might all be deleted.</p>
<p>To prevent this, make sure that the code is actually needed. For example, if
you are computing some expression, return the value from the function instead
of leaving it in a local variable. If you really want to constrain the
optimizer, you can read from and assign to <tt>volatile</tt> global
variables.</p>
</div>
<!--=========================================================================-->
<div class="question">
<p><a name="undef">What is this "<tt>undef</tt>" thing that shows up in my
code?</a></p>
</div>
<div class="answer">
<p><a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of
representing a value that is not defined. You can get these if you do not
initialize a variable before you use it. For example, the C function:</p>
<pre class="doc_code">
int X() { int i; return i; }
</pre>
<p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has a
value specified for it.</p>
</div>
<!--=========================================================================-->
<div class="question">
<p><a name="callconvwrong">Why does instcombine + simplifycfg turn
a call to a function with a mismatched calling convention into "unreachable"?
Why not make the verifier reject it?</a></p>
</div>
<div class="answer">
<p>This is a common problem run into by authors of front-ends that are using
custom calling conventions: you need to make sure to set the right calling
convention on both the function and on each call to the function. For example,
this code:</p>
<pre class="doc_code">
define fastcc void @foo() {
ret void
}
define void @bar() {
call void @foo()
ret void
}
</pre>
<p>Is optimized to:</p>
<pre class="doc_code">
define fastcc void @foo() {
ret void
}
define void @bar() {
unreachable
}
</pre>
<p>... with "opt -instcombine -simplifycfg". This often bites people because
"all their code disappears". Setting the calling convention on the caller and
callee is required for indirect calls to work, so people often ask why not make
the verifier reject this sort of thing.</p>
<p>The answer is that this code has undefined behavior, but it is not illegal.
If we made it illegal, then every transformation that could potentially create
this would have to ensure that it doesn't, and there is valid code that can
create this sort of construct (in dead code). The sorts of things that can
cause this to happen are fairly contrived, but we still need to accept them.
Here's an example:</p>
<pre class="doc_code">
define fastcc void @foo() {
ret void
}
define internal void @bar(void()* %FP, i1 %cond) {
br i1 %cond, label %T, label %F
T:
call void %FP()
ret void
F:
call fastcc void %FP()
ret void
}
define void @test() {
%X = or i1 false, false
call void @bar(void()* @foo, i1 %X)
ret void
}
</pre>
<p>In this example, "test" always passes @foo/false into bar, which ensures that
it is dynamically called with the right calling conv (thus, the code is
perfectly well defined). If you run this through the inliner, you get this
(the explicit "or" is there so that the inliner doesn't dead code eliminate
a bunch of stuff):
</p>
<pre class="doc_code">
define fastcc void @foo() {
ret void
}
define void @test() {
%X = or i1 false, false
br i1 %X, label %T.i, label %F.i
T.i:
call void @foo()
br label %bar.exit
F.i:
call fastcc void @foo()
br label %bar.exit
bar.exit:
ret void
}
</pre>
<p>Here you can see that the inlining pass made an undefined call to @foo with
the wrong calling convention. We really don't want to make the inliner have
to know about this sort of thing, so it needs to be valid code. In this case,
dead code elimination can trivially remove the undefined code. However, if %X
was an input argument to @test, the inliner would produce this:
</p>
<pre class="doc_code">
define fastcc void @foo() {
ret void
}
define void @test(i1 %X) {
br i1 %X, label %T.i, label %F.i
T.i:
call void @foo()
br label %bar.exit
F.i:
call fastcc void @foo()
br label %bar.exit
bar.exit:
ret void
}
</pre>
<p>The interesting thing about this is that %X <em>must</em> be false for the
code to be well-defined, but no amount of dead code elimination will be able to
delete the broken call as unreachable. However, since instcombine/simplifycfg
turns the undefined call into unreachable, we end up with a branch on a
condition that goes to unreachable: a branch to unreachable can never happen, so
"-inline -instcombine -simplifycfg" is able to produce:</p>
<pre class="doc_code">
define fastcc void @foo() {
ret void
}
define void @test(i1 %X) {
F.i:
call fastcc void @foo()
ret void
}
</pre>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-03-27 04:25:16 -0700 (Tue, 27 Mar 2012) $
</address>
</body>
</html>

279
cpp/llvm/docs/GCCFEBuildInstrs.html
View File

@ -1,279 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="llvm.css" type="text/css" media="screen">
<title>Building the LLVM GCC Front-End</title>
</head>
<body>
<h1>
Building the LLVM GCC Front-End
</h1>
<ol>
<li><a href="#instructions">Building llvm-gcc from Source</a></li>
<li><a href="#ada">Building the Ada front-end</a></li>
<li><a href="#fortran">Building the Fortran front-end</a></li>
<li><a href="#license">License Information</a></li>
</ol>
<div class="doc_author">
<p>Written by the LLVM Team</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="instructions">Building llvm-gcc from Source</a></h2>
<!-- *********************************************************************** -->
<div>
<p>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,
Objective-C and Objective-C++. Note that the instructions for building these
front-ends are completely different (and much easier!) than those for building
llvm-gcc3 in the past.</p>
<ol>
<li><p>Retrieve the appropriate llvm-gcc-4.2-<i>version</i>.source.tar.gz
archive from the <a href="http://llvm.org/releases/">LLVM web
site</a>.</p>
<p>It is also possible to download the sources of the llvm-gcc front end
from a read-only mirror using subversion. To check out the 4.2 code
for first time use:</p>
<div class="doc_code">
<pre>
svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk <i>dst-directory</i>
</pre>
</div>
<p>After that, the code can be be updated in the destination directory
using:</p>
<div class="doc_code">
<pre>svn update</pre>
</div>
<p>The mirror is brought up to date every evening.</p></li>
<li>Follow the directions in the top-level <tt>README.LLVM</tt> file for
up-to-date instructions on how to build llvm-gcc. See below for building
with support for Ada or Fortran.
</ol>
</div>
<!-- *********************************************************************** -->
<h2><a name="ada">Building the Ada front-end</a></h2>
<!-- *********************************************************************** -->
<div>
<p>Building with support for Ada amounts to following the directions in the
top-level <tt>README.LLVM</tt> file, adding ",ada" to EXTRALANGS, for example:
<tt>EXTRALANGS=,ada</tt></p>
<p>There are some complications however:</p>
<ol>
<li><p>The only platform for which the Ada front-end is known to build is
32 bit intel x86 running linux. It is unlikely to build for other
systems without some work.</p></li>
<li><p>The build requires having a compiler that supports Ada, C and C++.
The Ada front-end is written in Ada so an Ada compiler is needed to
build it. Compilers known to work with the
<a href="http://llvm.org/releases/download.html">LLVM 2.7 release</a>
are <a href="http://gcc.gnu.org/releases.html">gcc-4.2</a> and the
2005, 2006 and 2007 versions of the
<a href="http://libre.adacore.com/">GNAT GPL Edition</a>.
<b>GNAT GPL 2008, gcc-4.3 and later will not work</b>.
The LLVM parts of llvm-gcc are written in C++ so a C++ compiler is
needed to build them. The rest of gcc is written in C.
Some linux distributions provide a version of gcc that supports all
three languages (the Ada part often comes as an add-on package to
the rest of gcc). Otherwise it is possible to combine two versions
of gcc, one that supports Ada and C (such as the
<a href="http://libre.adacore.com/">2007 GNAT GPL Edition</a>)
and another which supports C++, see below.</p></li>
<li><p>Because the Ada front-end is experimental, it is wise to build the
compiler with checking enabled. This causes it to run much slower, but
helps catch mistakes in the compiler (please report any problems using
<a href="http://llvm.org/bugs/">LLVM bugzilla</a>).</p></li>
<li><p>The Ada front-end <a href="http://llvm.org/PR2007">fails to
bootstrap</a>, due to lack of LLVM support for
<tt>setjmp</tt>/<tt>longjmp</tt> style exception handling (used
internally by the compiler), so you must specify
<tt>--disable-bootstrap</tt>.</p></li>
</ol>
<p>Supposing appropriate compilers are available, llvm-gcc with Ada support can
be built on an x86-32 linux box using the following recipe:</p>
<ol>
<li><p>Download the <a href="http://llvm.org/releases/download.html">LLVM source</a>
and unpack it:</p>
<pre class="doc_code">
wget http://llvm.org/releases/2.7/llvm-2.7.tgz
tar xzf llvm-2.7.tgz
mv llvm-2.7 llvm
</pre>
<p>or <a href="GettingStarted.html#checkout">check out the
latest version from subversion</a>:</p>
<pre class="doc_code">svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</pre>
</li>
<li><p>Download the
<a href="http://llvm.org/releases/download.html">llvm-gcc-4.2 source</a>
and unpack it:</p>
<pre class="doc_code">
wget http://llvm.org/releases/2.7/llvm-gcc-4.2-2.7.source.tgz
tar xzf llvm-gcc-4.2-2.7.source.tgz
mv llvm-gcc-4.2-2.7.source llvm-gcc-4.2
</pre>
<p>or <a href="GettingStarted.html#checkout">check out the
latest version from subversion</a>:</p>
<pre class="doc_code">
svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk llvm-gcc-4.2
</pre>
</li>
<li><p>Make a build directory <tt>llvm-objects</tt> for llvm and make it the
current directory:</p>
<pre class="doc_code">
mkdir llvm-objects
cd llvm-objects
</pre>
</li>
<li><p>Configure LLVM (here it is configured to install into <tt>/usr/local</tt>):</p>
<pre class="doc_code">
../llvm/configure --prefix=<b>/usr/local</b> --enable-optimized --enable-assertions
</pre>
<p>If you have a multi-compiler setup and the C++ compiler is not the
default, then you can configure like this:</p>
<pre class="doc_code">
CXX=<b>PATH_TO_C++_COMPILER</b> ../llvm/configure --prefix=<b>/usr/local</b> --enable-optimized --enable-assertions
</pre>
<p>To compile without checking (not recommended), replace
<tt>--enable-assertions</tt> with <tt>--disable-assertions</tt>.</p>
</li>
<li><p>Build LLVM:</p>
<pre class="doc_code">
make
</pre>
</li>
<li><p>Install LLVM (optional):</p>
<pre class="doc_code">
make install
</pre>
</li>
<li><p>Make a build directory <tt>llvm-gcc-4.2-objects</tt> for llvm-gcc and make it the
current directory:</p>
<pre class="doc_code">
cd ..
mkdir llvm-gcc-4.2-objects
cd llvm-gcc-4.2-objects
</pre>
</li>
<li><p>Configure llvm-gcc (here it is configured to install into <tt>/usr/local</tt>).
The <tt>--enable-checking</tt> flag turns on sanity checks inside the compiler.
To turn off these checks (not recommended), replace <tt>--enable-checking</tt>
with <tt>--disable-checking</tt>.
Additional languages can be appended to the <tt>--enable-languages</tt> switch,
for example <tt>--enable-languages=ada,c,c++</tt>.</p>
<pre class="doc_code">
../llvm-gcc-4.2/configure --prefix=<b>/usr/local</b> --enable-languages=ada,c \
--enable-checking --enable-llvm=$PWD/../llvm-objects \
--disable-bootstrap --disable-multilib
</pre>
<p>If you have a multi-compiler setup, then you can configure like this:</p>
<pre class="doc_code">
export CC=<b>PATH_TO_C_AND_ADA_COMPILER</b>
export CXX=<b>PATH_TO_C++_COMPILER</b>
../llvm-gcc-4.2/configure --prefix=<b>/usr/local</b> --enable-languages=ada,c \
--enable-checking --enable-llvm=$PWD/../llvm-objects \
--disable-bootstrap --disable-multilib
</pre>
</li>
<li><p>Build and install the compiler:</p>
<pre class="doc_code">
make
make install
</pre>
</li>
</ol>
</div>
<!-- *********************************************************************** -->
<h2><a name="fortran">Building the Fortran front-end</a></h2>
<!-- *********************************************************************** -->
<div>
<p>To build with support for Fortran, follow the directions in the top-level
<tt>README.LLVM</tt> file, adding ",fortran" to EXTRALANGS, for example:</p>
<pre class="doc_code">
EXTRALANGS=,fortran
</pre>
</div>
<!-- *********************************************************************** -->
<h2><a name="license">License Information</a></h2>
<!-- *********************************************************************** -->
<div>
<p>
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
COPYING.LIB for more details.
</p>
<p>
More information is <a href="FAQ.html#license">available in the FAQ</a>.
</p>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-04-22 17:30:22 -0700 (Fri, 22 Apr 2011) $
</address>
</body>
</html>

1389
cpp/llvm/docs/GarbageCollection.html
View File

File diff suppressed because it is too large Load Diff

753
cpp/llvm/docs/GetElementPtr.html
View File

@ -1,753 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>The Often Misunderstood GEP Instruction</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
<style type="text/css">
TABLE { text-align: left; border: 1px solid black; border-collapse: collapse; margin: 0 0 0 0; }
</style>
</head>
<body>
<h1>
The Often Misunderstood GEP Instruction
</h1>
<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#addresses">Address Computation</a>
<ol>
<li><a href="#extra_index">Why is the extra 0 index required?</a></li>
<li><a href="#deref">What is dereferenced by GEP?</a></li>
<li><a href="#firstptr">Why can you index through the first pointer but not
subsequent ones?</a></li>
<li><a href="#lead0">Why don't GEP x,0,0,1 and GEP x,1 alias? </a></li>
<li><a href="#trail0">Why do GEP x,1,0,0 and GEP x,1 alias? </a></li>
<li><a href="#vectors">Can GEP index into vector elements?</a>
<li><a href="#addrspace">What effect do address spaces have on GEPs?</a>
<li><a href="#int">How is GEP different from ptrtoint, arithmetic, and inttoptr?</a></li>
<li><a href="#be">I'm writing a backend for a target which needs custom lowering for GEP. How do I do this?</a>
<li><a href="#vla">How does VLA addressing work with GEPs?</a>
</ol></li>
<li><a href="#rules">Rules</a>
<ol>
<li><a href="#bounds">What happens if an array index is out of bounds?</a>
<li><a href="#negative">Can array indices be negative?</a>
<li><a href="#compare">Can I compare two values computed with GEPs?</a>
<li><a href="#types">Can I do GEP with a different pointer type than the type of the underlying object?</a>
<li><a href="#null">Can I cast an object's address to integer and add it to null?</a>
<li><a href="#ptrdiff">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a>
<li><a href="#tbaa">Can I do type-based alias analysis on LLVM IR?</a>
<li><a href="#overflow">What happens if a GEP computation overflows?</a>
<li><a href="#check">How can I tell if my front-end is following the rules?</a>
</ol></li>
<li><a href="#rationale">Rationale</a>
<ol>
<li><a href="#goals">Why is GEP designed this way?</a></li>
<li><a href="#i32">Why do struct member indices always use i32?</a></li>
<li><a href="#uglygep">What's an uglygep?</a>
</ol></li>
<li><a href="#summary">Summary</a></li>
</ol>
<div class="doc_author">
<p>Written by: <a href="mailto:rspencer@reidspencer.com">Reid Spencer</a>.</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="intro">Introduction</a></h2>
<!-- *********************************************************************** -->
<div>
<p>This document seeks to dispel the mystery and confusion surrounding LLVM's
<a href="LangRef.html#i_getelementptr">GetElementPtr</a> (GEP) instruction.
Questions about the wily GEP instruction are
probably the most frequently occurring questions once a developer gets down to
coding with LLVM. Here we lay out the sources of confusion and show that the
GEP instruction is really quite simple.
</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="addresses">Address Computation</a></h2>
<!-- *********************************************************************** -->
<div>
<p>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.</p>
<!-- *********************************************************************** -->
<h3>
<a name="firstptr">What is the first index of the GEP instruction?</a>
</h3>
<div>
<p>Quick answer: The index stepping through the first operand.</p>
<p>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
same. For example, when we write, in "C":</p>
<div class="doc_code">
<pre>
AType *Foo;
...
X = &amp;Foo-&gt;F;
</pre>
</div>
<p>it is natural to think that there is only one index, the selection of the
field <tt>F</tt>. However, in this example, <tt>Foo</tt> is a pointer. That
pointer must be indexed explicitly in LLVM. C, on the other hand, indices
through it transparently. To arrive at the same address location as the C
code, you would provide the GEP instruction with two index operands. The
first operand indexes through the pointer; the second operand indexes the
field <tt>F</tt> of the structure, just as if you wrote:</p>
<div class="doc_code">
<pre>
X = &amp;Foo[0].F;
</pre>
</div>
<p>Sometimes this question gets rephrased as:</p>
<blockquote><p><i>Why is it okay to index through the first pointer, but
subsequent pointers won't be dereferenced?</i></p></blockquote>
<p>The answer is simply because memory does not have to be accessed to
perform the computation. The first operand to the GEP instruction must be a
value of a pointer type. The value of the pointer is provided directly to
the GEP instruction as an operand without any need for accessing memory. It
must, therefore be indexed and requires an index operand. Consider this
example:</p>
<div class="doc_code">
<pre>
struct munger_struct {
int f1;
int f2;
};
void munge(struct munger_struct *P) {
P[0].f1 = P[1].f1 + P[2].f2;
}
...
munger_struct Array[3];
...
munge(Array);
</pre>
</div>
<p>In this "C" example, the front end compiler (llvm-gcc) will generate three
GEP instructions for the three indices through "P" in the assignment
statement. The function argument <tt>P</tt> will be the first operand of each
of these GEP instructions. The second operand indexes through that pointer.
The third operand will be the field offset into the
<tt>struct munger_struct</tt> type, for either the <tt>f1</tt> or
<tt>f2</tt> field. So, in LLVM assembly the <tt>munge</tt> function looks
like:</p>
<div class="doc_code">
<pre>
void %munge(%struct.munger_struct* %P) {
entry:
%tmp = getelementptr %struct.munger_struct* %P, i32 1, i32 0
%tmp = load i32* %tmp
%tmp6 = getelementptr %struct.munger_struct* %P, i32 2, i32 1
%tmp7 = load i32* %tmp6
%tmp8 = add i32 %tmp7, %tmp
%tmp9 = getelementptr %struct.munger_struct* %P, i32 0, i32 0
store i32 %tmp8, i32* %tmp9
ret void
}
</pre>
</div>
<p>In each case the first operand is the pointer through which the GEP
instruction starts. The same is true whether the first operand is an
argument, allocated memory, or a global variable. </p>
<p>To make this clear, let's consider a more obtuse example:</p>
<div class="doc_code">
<pre>
%MyVar = uninitialized global i32
...
%idx1 = getelementptr i32* %MyVar, i64 0
%idx2 = getelementptr i32* %MyVar, i64 1
%idx3 = getelementptr i32* %MyVar, i64 2
</pre>
</div>
<p>These GEP instructions are simply making address computations from the
base address of <tt>MyVar</tt>. They compute, as follows (using C syntax):
</p>
<div class="doc_code">
<pre>
idx1 = (char*) &amp;MyVar + 0
idx2 = (char*) &amp;MyVar + 4
idx3 = (char*) &amp;MyVar + 8
</pre>
</div>
<p>Since the type <tt>i32</tt> is known to be four bytes long, the indices
0, 1 and 2 translate into memory offsets of 0, 4, and 8, respectively. No
memory is accessed to make these computations because the address of
<tt>%MyVar</tt> is passed directly to the GEP instructions.</p>
<p>The obtuse part of this example is in the cases of <tt>%idx2</tt> and
<tt>%idx3</tt>. They result in the computation of addresses that point to
memory past the end of the <tt>%MyVar</tt> global, which is only one
<tt>i32</tt> long, not three <tt>i32</tt>s long. While this is legal in LLVM,
it is inadvisable because any load or store with the pointer that results
from these GEP instructions would produce undefined results.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="extra_index">Why is the extra 0 index required?</a>
</h3>
<!-- *********************************************************************** -->
<div>
<p>Quick answer: there are no superfluous indices.</p>
<p>This question arises most often when the GEP instruction is applied to a
global variable which is always a pointer type. For example, consider
this:</p>
<div class="doc_code">
<pre>
%MyStruct = uninitialized global { float*, i32 }
...
%idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
</pre>
</div>
<p>The GEP above yields an <tt>i32*</tt> by indexing the <tt>i32</tt> typed
field of the structure <tt>%MyStruct</tt>. When people first look at it, they
wonder why the <tt>i64 0</tt> index is needed. However, a closer inspection
of how globals and GEPs work reveals the need. Becoming aware of the following
facts will dispel the confusion:</p>
<ol>
<li>The type of <tt>%MyStruct</tt> is <i>not</i> <tt>{ float*, i32 }</tt>
but rather <tt>{ float*, i32 }*</tt>. That is, <tt>%MyStruct</tt> is a
pointer to a structure containing a pointer to a <tt>float</tt> and an
<tt>i32</tt>.</li>
<li>Point #1 is evidenced by noticing the type of the first operand of
the GEP instruction (<tt>%MyStruct</tt>) which is
<tt>{ float*, i32 }*</tt>.</li>
<li>The first index, <tt>i64 0</tt> is required to step over the global
variable <tt>%MyStruct</tt>. Since the first argument to the GEP
instruction must always be a value of pointer type, the first index
steps through that pointer. A value of 0 means 0 elements offset from that
pointer.</li>
<li>The second index, <tt>i32 1</tt> selects the second field of the
structure (the <tt>i32</tt>). </li>
</ol>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="deref">What is dereferenced by GEP?</a>
</h3>
<div>
<p>Quick answer: nothing.</p>
<p>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.
GEP is only involved in the computation of addresses. For example, consider
this:</p>
<div class="doc_code">
<pre>
%MyVar = uninitialized global { [40 x i32 ]* }
...
%idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
</pre>
</div>
<p>In this example, we have a global variable, <tt>%MyVar</tt> that is a
pointer to a structure containing a pointer to an array of 40 ints. The
GEP instruction seems to be accessing the 18th integer of the structure's
array of ints. However, this is actually an illegal GEP instruction. It
won't compile. The reason is that the pointer in the structure <i>must</i>
be dereferenced in order to index into the array of 40 ints. Since the
GEP instruction never accesses memory, it is illegal.</p>
<p>In order to access the 18th integer in the array, you would need to do the
following:</p>
<div class="doc_code">
<pre>
%idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
%arr = load [40 x i32]** %idx
%idx = getelementptr [40 x i32]* %arr, i64 0, i64 17
</pre>
</div>
<p>In this case, we have to load the pointer in the structure with a load
instruction before we can index into the array. If the example was changed
to:</p>
<div class="doc_code">
<pre>
%MyVar = uninitialized global { [40 x i32 ] }
...
%idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
</pre>
</div>
<p>then everything works fine. In this case, the structure does not contain a
pointer and the GEP instruction can index through the global variable,
into the first field of the structure and access the 18th <tt>i32</tt> in the
array there.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="lead0">Why don't GEP x,0,0,1 and GEP x,1 alias?</a>
</h3>
<div>
<p>Quick Answer: They compute different address locations.</p>
<p>If you look at the first indices in these GEP
instructions you find that they are different (0 and 1), therefore the address
computation diverges with that index. Consider this example:</p>
<div class="doc_code">
<pre>
%MyVar = global { [10 x i32 ] }
%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
</pre>
</div>
<p>In this example, <tt>idx1</tt> computes the address of the second integer
in the array that is in the structure in <tt>%MyVar</tt>, that is
<tt>MyVar+4</tt>. The type of <tt>idx1</tt> is <tt>i32*</tt>. However,
<tt>idx2</tt> computes the address of <i>the next</i> structure after
<tt>%MyVar</tt>. The type of <tt>idx2</tt> is <tt>{ [10 x i32] }*</tt> and its
value is equivalent to <tt>MyVar + 40</tt> because it indexes past the ten
4-byte integers in <tt>MyVar</tt>. Obviously, in such a situation, the
pointers don't alias.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="trail0">Why do GEP x,1,0,0 and GEP x,1 alias?</a>
</h3>
<div>
<p>Quick Answer: They compute the same address location.</p>
<p>These two GEP instructions will compute the same address because indexing
through the 0th element does not change the address. However, it does change
the type. Consider this example:</p>
<div class="doc_code">
<pre>
%MyVar = global { [10 x i32 ] }
%idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
%idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
</pre>
</div>
<p>In this example, the value of <tt>%idx1</tt> is <tt>%MyVar+40</tt> and
its type is <tt>i32*</tt>. The value of <tt>%idx2</tt> is also
<tt>MyVar+40</tt> but its type is <tt>{ [10 x i32] }*</tt>.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="vectors">Can GEP index into vector elements?</a>
</h3>
<div>
<p>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
disallowed.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="addrspace">What effect do address spaces have on GEPs?</a>
</h3>
<div>
<p>None, except that the address space qualifier on the first operand pointer
type always matches the address space qualifier on the result type.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="int">
How is GEP different from ptrtoint, arithmetic, and inttoptr?
</a>
</h3>
<div>
<p>It's very similar; there are only subtle differences.</p>
<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
this is safe on everything LLVM supports (LLVM internally assumes pointers
are never wider than 64 bits in many places), and the optimizer will actually
narrow the i64 arithmetic down to the actual pointer size on targets which
don't support 64-bit arithmetic in most cases. However, there are some cases
where it doesn't do this. With GEP you can avoid this problem.
<p>Also, GEP carries additional pointer aliasing rules. It's invalid to take a
GEP from one object, address into a different separately allocated
object, and dereference it. IR producers (front-ends) must follow this rule,
and consumers (optimizers, specifically alias analysis) benefit from being
able to rely on it. See the <a href="#rules">Rules</a> section for more
information.</p>
<p>And, GEP is more concise in common cases.</p>
<p>However, for the underlying integer computation implied, there
is no difference.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="be">
I'm writing a backend for a target which needs custom lowering for GEP.
How do I do this?
</a>
</h3>
<div>
<p>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
into. This has the advantage of letting your code work correctly in more
cases.</p>
<p>GEP does use target-dependent parameters for the size and layout of data
types, which targets can customize.</p>
<p>If you require support for addressing units which are not 8 bits, you'll
need to fix a lot of code in the backend, with GEP lowering being only a
small piece of the overall picture.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="vla">How does VLA addressing work with GEPs?</a>
</h3>
<div>
<p>GEPs don't natively support VLAs. LLVM's type system is entirely static,
and GEP address computations are guided by an LLVM type.</p>
<p>VLA indices can be implemented as linearized indices. For example, an
expression like X[a][b][c], must be effectively lowered into a form
like X[a*m+b*n+c], so that it appears to the GEP as a single-dimensional
array reference.</p>
<p>This means if you want to write an analysis which understands array
indices and you want to support VLAs, your code will have to be
prepared to reverse-engineer the linearization. One way to solve this
problem is to use the ScalarEvolution library, which always presents
VLA and non-VLA indexing in the same manner.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2><a name="rules">Rules</a></h2>
<!-- *********************************************************************** -->
<div>
<!-- *********************************************************************** -->
<h3>
<a name="bounds">What happens if an array index is out of bounds?</a>
</h3>
<div>
<p>There are two senses in which an array index can be out of bounds.</p>
<p>First, there's the array type which comes from the (static) type of
the first operand to the GEP. Indices greater than the number of elements
in the corresponding static array type are valid. There is no problem with
out of bounds indices in this sense. Indexing into an array only depends
on the size of the array element, not the number of elements.</p>
<p>A common example of how this is used is arrays where the size is not known.
It's common to use array types with zero length to represent these. The
fact that the static type says there are zero elements is irrelevant; it's
perfectly valid to compute arbitrary element indices, as the computation
only depends on the size of the array element, not the number of
elements. Note that zero-sized arrays are not a special case here.</p>
<p>This sense is unconnected with <tt>inbounds</tt> keyword. The
<tt>inbounds</tt> keyword is designed to describe low-level pointer
arithmetic overflow conditions, rather than high-level array
indexing rules.
<p>Analysis passes which wish to understand array indexing should not
assume that the static array type bounds are respected.</p>
<p>The second sense of being out of bounds is computing an address that's
beyond the actual underlying allocated object.</p>
<p>With the <tt>inbounds</tt> keyword, the result value of the GEP is
undefined if the address is outside the actual underlying allocated
object and not the address one-past-the-end.</p>
<p>Without the <tt>inbounds</tt> keyword, there are no restrictions
on computing out-of-bounds addresses. Obviously, performing a load or
a store requires an address of allocated and sufficiently aligned
memory. But the GEP itself is only concerned with computing addresses.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="negative">Can array indices be negative?</a>
</h3>
<div>
<p>Yes. This is basically a special case of array indices being out
of bounds.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="compare">Can I compare two values computed with GEPs?</a>
</h3>
<div>
<p>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
comparison may not be meaningful.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="types">
Can I do GEP with a different pointer type than the type of
the underlying object?
</a>
</h3>
<div>
<p>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
type of the underlying object.</p>
<p>Furthermore, loads and stores don't have to use the same types as the type
of the underlying object. Types in this context serve only to specify
memory size and alignment. Beyond that there are merely a hint to the
optimizer indicating how the value will likely be used.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="null">
Can I cast an object's address to integer and add it to null?
</a>
</h3>
<div>
<p>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.</p>
<p>The underlying integer computation is sufficiently defined; null has a
defined value -- zero -- and you can add whatever value you want to it.</p>
<p>However, it's invalid to access (load from or store to) an LLVM-aware
object with such a pointer. This includes GlobalVariables, Allocas, and
objects pointed to by noalias pointers.</p>
<p>If you really need this functionality, you can do the arithmetic with
explicit integer instructions, and use inttoptr to convert the result to
an address. Most of GEP's special aliasing rules do not apply to pointers
computed from ptrtoint, arithmetic, and inttoptr sequences.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="ptrdiff">
Can I compute the distance between two objects, and add
that value to one address to compute the other address?
</a>
</h3>
<div>
<p>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.</p>
<p>Also as above, ptrtoint and inttoptr provide an alternative way to do this
which do not have this restriction.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="tbaa">Can I do type-based alias analysis on LLVM IR?</a>
</h3>
<div>
<p>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.</p>
<p>LLVM's type-based alias analysis pass uses metadata to describe a different
type system (such as the C type system), and performs type-based aliasing
on top of that. Further details are in the
<a href="LangRef.html#tbaa">language reference</a>.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="overflow">What happens if a GEP computation overflows?</a>
</h3>
<div>
<p>If the GEP lacks the <tt>inbounds</tt> 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
address space, such values have limited meaning.</p>
<p>If the GEP has the <tt>inbounds</tt> keyword, the result value is
undefined (a "<a href="LangRef.html#trapvalues">trap value</a>") if the GEP
overflows (i.e. wraps around the end of the address space).</p>
<p>As such, there are some ramifications of this for inbounds GEPs: scales
implied by array/vector/pointer indices are always known to be "nsw" since
they are signed values that are scaled by the element size. These values
are also allowed to be negative (e.g. "gep i32 *%P, i32 -1") but the
pointer itself is logically treated as an unsigned value. This means that
GEPs have an asymmetric relation between the pointer base (which is treated
as unsigned) and the offset applied to it (which is treated as signed). The
result of the additions within the offset calculation cannot have signed
overflow, but when applied to the base pointer, there can be signed
overflow.
</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="check">
How can I tell if my front-end is following the rules?
</a>
</h3>
<div>
<p>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.</p>
<p>It's not possible to write a checker which could find all rule
violations statically. It would be possible to write a checker which
works by instrumenting the code with dynamic checks though. Alternatively,
it would be possible to write a static checker which catches a subset of
possible problems. However, no such checker exists today.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2><a name="rationale">Rationale</a></h2>
<!-- *********************************************************************** -->
<div>
<!-- *********************************************************************** -->
<h3>
<a name="goals">Why is GEP designed this way?</a>
</h3>
<div>
<p>The design of GEP has the following goals, in rough unofficial
order of priority:</p>
<ul>
<li>Support C, C-like languages, and languages which can be
conceptually lowered into C (this covers a lot).</li>
<li>Support optimizations such as those that are common in
C compilers. In particular, GEP is a cornerstone of LLVM's
<a href="LangRef.html#pointeraliasing">pointer aliasing model</a>.</li>
<li>Provide a consistent method for computing addresses so that
address computations don't need to be a part of load and
store instructions in the IR.</li>
<li>Support non-C-like languages, to the extent that it doesn't
interfere with other goals.</li>
<li>Minimize target-specific information in the IR.</li>
</ul>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="i32">Why do struct member indices always use i32?</a>
</h3>
<div>
<p>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
which identifies a field in a struct. Requiring that all struct indices be
the same reduces the range of possibilities for cases where two GEPs are
effectively the same but have distinct operand types.</p>
</div>
<!-- *********************************************************************** -->
<h3>
<a name="uglygep">What's an uglygep?</a>
</h3>
<div>
<p>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
integer expressions. If they've made non-trivial changes, translating
back into LLVM IR can involve reverse-engineering the structure of
the addressing in order to fit it into the static type of the original
first operand. It isn't always possibly to fully reconstruct this
structure; sometimes the underlying addressing doesn't correspond with
the static type at all. In such cases the optimizer instead will emit
a GEP with the base pointer casted to a simple address-unit pointer,
using the name "uglygep". This isn't pretty, but it's just as
valid, and it's sufficient to preserve the pointer aliasing guarantees
that GEP provides.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2><a name="summary">Summary</a></h2>
<!-- *********************************************************************** -->
<div>
<p>In summary, here's some things to always remember about the GetElementPtr
instruction:</p>
<ol>
<li>The GEP instruction never accesses memory, it only provides pointer
computations.</li>
<li>The first operand to the GEP instruction is always a pointer and it must
be indexed.</li>
<li>There are no superfluous indices for the GEP instruction.</li>
<li>Trailing zero indices are superfluous for pointer aliasing, but not for
the types of the pointers.</li>
<li>Leading zero indices are not superfluous for pointer aliasing nor the
types of the pointers.</li>
</ol>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-10-31 06:04:26 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

1763
cpp/llvm/docs/GettingStarted.html
View File

File diff suppressed because it is too large Load Diff

368
cpp/llvm/docs/GettingStartedVS.html
View File

@ -1,368 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Getting Started with LLVM System for Microsoft Visual Studio</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>
Getting Started with the LLVM System using Microsoft Visual Studio
</h1>
<ul>
<li><a href="#overview">Overview</a>
<li><a href="#requirements">Requirements</a>
<ol>
<li><a href="#hardware">Hardware</a>
<li><a href="#software">Software</a>
</ol></li>
<li><a href="#quickstart">Getting Started</a>
<li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
<li><a href="#problems">Common Problems</a>
<li><a href="#links">Links</a>
</ul>
<div class="doc_author">
<p>Written by: <a href="http://llvm.org/">The LLVM Team</a></p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="overview"><b>Overview</b></a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
know some basic information.</p>
<p>There are many different projects that compose LLVM. The first is the LLVM
suite. This contains all of the tools, libraries, and header files needed to
use LLVM. It contains an assembler, disassembler,
bitcode analyzer and bitcode optimizer. It also contains a test suite that can
be used to test the LLVM tools.</p>
<p>Another useful project on Windows is
<a href="http://clang.llvm.org/">clang</a>. Clang is a C family
([Objective]C/C++) compiler. Clang mostly works on Windows, but does not
currently understand all of the Microsoft extensions to C and C++. Because of
this, clang cannot parse the C++ standard library included with Visual Studio,
nor parts of the Windows Platform SDK. However, most standard C programs do
compile. Clang can be used to emit bitcode, directly emit object files or
even linked executables using Visual Studio's <tt>link.exe</tt></p>
<p>The large LLVM test suite cannot be run on the Visual Studio port at this
time.</p>
<p>Most of the tools build and work. <tt>bugpoint</tt> does build, but does
not work.</p>
<p>Additional information about the LLVM directory structure and tool chain
can be found on the main <a href="GettingStarted.html">Getting Started</a>
page.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="requirements"><b>Requirements</b></a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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.</p>
<!-- ======================================================================= -->
<h3>
<a name="hardware"><b>Hardware</b></a>
</h3>
<div>
<p>Any system that can adequately run Visual Studio 2008 is fine. The LLVM
source tree and object files, libraries and executables will consume
approximately 3GB.</p>
</div>
<!-- ======================================================================= -->
<h3><a name="software"><b>Software</b></a></h3>
<div>
<p>You will need Visual Studio 2008 or higher. Earlier versions of Visual
Studio have bugs, are not completely compatible, or do not support the C++
standard well enough.</p>
<p>You will also need the <a href="http://www.cmake.org/">CMake</a> build
system since it generates the project files you will use to build with.</p>
<p>If you would like to run the LLVM tests you will need
<a href="http://www.python.org/">Python</a>. Versions 2.4-2.7 are known to
work. You will need <a href="http://gnuwin32.sourceforge.net/">"GnuWin32"</a>
tools, too.</p>
<p>Do not install the LLVM directory tree into a path containing spaces (e.g.
C:\Documents and Settings\...) as the configure step will fail.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="quickstart"><b>Getting Started</b></a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Here's the short story for getting up and running quickly with LLVM:</p>
<ol>
<li>Read the documentation.</li>
<li>Seriously, read the documentation.</li>
<li>Remember that you were warned twice about reading the documentation.</li>
<li>Get the Source Code
<ul>
<li>With the distributed files:
<ol>
<li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
<li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
<i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;or use WinZip</i>
<li><tt>cd llvm</tt></li>
</ol></li>
<li>With anonymous Subversion access:
<ol>
<li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
<li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
<li><tt>cd llvm</tt></li>
</ol></li>
</ul></li>
<li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date
project files:
<ul>
<li>Once CMake is installed then the simplest way is to just start the
CMake GUI, select the directory where you have LLVM extracted to, and the
default options should all be fine. One option you may really want to
change, regardless of anything else, might be the CMAKE_INSTALL_PREFIX
setting to select a directory to INSTALL to once compiling is complete,
although installation is not mandatory for using LLVM. Another important
option is LLVM_TARGETS_TO_BUILD, which controls the LLVM target
architectures that are included on the build.
<li>See the <a href="CMake.html">LLVM CMake guide</a> for
detailed information about how to configure the LLVM
build.</li>
</ul>
</li>
<li>Start Visual Studio
<ul>
<li>In the directory you created the project files will have
an <tt>llvm.sln</tt> file, just double-click on that to open
Visual Studio.</li>
</ul></li>
<li>Build the LLVM Suite:
<ul>
<li>The projects may still be built individually, but
to build them all do not just select all of them in batch build (as some
are meant as configuration projects), but rather select and build just
the ALL_BUILD project to build everything, or the INSTALL project, which
first builds the ALL_BUILD project, then installs the LLVM headers, libs,
and other useful things to the directory set by the CMAKE_INSTALL_PREFIX
setting when you first configured CMake.</li>
<li>The Fibonacci project is a sample program that uses the JIT.
Modify the project's debugging properties to provide a numeric
command line argument or run it from the command line. The
program will print the corresponding fibonacci value.</li>
</ul></li>
<li>Test LLVM on Visual Studio:
<ul>
<li>If %PATH% does not contain GnuWin32, you may specify LLVM_LIT_TOOLS_DIR
on CMake for the path to GnuWin32.</li>
<li>You can run LLVM tests by merely building the project
"check". The test results will be shown in the VS output
window.</li>
</ul>
</li>
<!-- FIXME: Is it up-to-date? -->
<li>Test LLVM:
<ul>
<li>The LLVM tests can be run by <tt>cd</tt>ing to the llvm source directory
and running:
<div class="doc_code">
<pre>
% llvm-lit test
</pre>
</div>
<p>Note that quite a few of these test will fail.</p>
</li>
<li>A specific test or test directory can be run with:
<div class="doc_code">
<pre>
% llvm-lit test/path/to/test
</pre>
</div>
</li>
</ul>
</ol>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="tutorial">An Example Using the LLVM Tool Chain</a>
</h2>
<!-- *********************************************************************** -->
<div>
<ol>
<li><p>First, create a simple C file, name it 'hello.c':</p>
<div class="doc_code">
<pre>
#include &lt;stdio.h&gt;
int main() {
printf("hello world\n");
return 0;
}
</pre></div></li>
<li><p>Next, compile the C file into a LLVM bitcode file:</p>
<div class="doc_code">
<pre>
% clang -c hello.c -emit-llvm -o hello.bc
</pre>
</div>
<p>This will create the result file <tt>hello.bc</tt> which is the LLVM
bitcode that corresponds the the compiled program and the library
facilities that it required. You can execute this file directly using
<tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>,
optimize or analyze it further with the <tt>opt</tt> tool, etc.</p>
<p>Alternatively you can directly output an executable with clang with:
</p>
<div class="doc_code">
<pre>
% clang hello.c -o hello.exe
</pre>
</div>
<p>The <tt>-o hello.exe</tt> is required because clang currently outputs
<tt>a.out</tt> when neither <tt>-o</tt> nor <tt>-c</tt> are given.</p>
<li><p>Run the program using the just-in-time compiler:</p>
<div class="doc_code">
<pre>
% lli hello.bc
</pre>
</div>
<li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
code:</p>
<div class="doc_code">
<pre>
% llvm-dis &lt; hello.bc | more
</pre>
</div></li>
<li><p>Compile the program to object code using the LLC code generator:</p>
<div class="doc_code">
<pre>
% llc -filetype=obj hello.bc
</pre>
</div></li>
<li><p>Link to binary using Microsoft link:</p>
<div class="doc_code">
<pre>
% link hello.obj -defaultlib:libcmt
</pre>
</div>
<li><p>Execute the native code program:</p>
<div class="doc_code">
<pre>
% hello.exe
</pre>
</div></li>
</ol>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="problems">Common Problems</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>If you are having problems building or using LLVM, or if you have any other
general questions about LLVM, please consult the <a href="FAQ.html">Frequently
Asked Questions</a> page.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="links">Links</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>This document is just an <b>introduction</b> to how to use LLVM to do
some simple things... there are many more interesting and complicated things
that you can do that aren't documented here (but we'll gladly accept a patch
if you want to write something up!). For more information about LLVM, check
out:</p>
<ul>
<li><a href="http://llvm.org/">LLVM homepage</a></li>
<li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
</ul>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-01-25 14:00:23 -0800 (Wed, 25 Jan 2012) $
</address>
</body>
</html>

227
cpp/llvm/docs/GoldPlugin.html
View File

@ -1,227 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM gold plugin</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>LLVM gold plugin</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#build">How to build it</a></li>
<li><a href="#usage">Usage</a>
<ul>
<li><a href="#example1">Example of link time optimization</a></li>
<li><a href="#lto_autotools">Quickstart for using LTO with autotooled projects</a></li>
</ul></li>
<li><a href="#licensing">Licensing</a></li>
</ol>
<div class="doc_author">Written by Nick Lewycky</div>
<!--=========================================================================-->
<h2><a name="introduction">Introduction</a></h2>
<!--=========================================================================-->
<div>
<p>Building with link time optimization requires cooperation from the
system linker. LTO support on Linux systems requires that you use
the <a href="http://sourceware.org/binutils">gold linker</a> which supports
LTO via plugins. This is the same mechanism used by the
<a href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a>
project.</p>
<p>The LLVM gold plugin implements the
<a href="http://gcc.gnu.org/wiki/whopr/driver">gold plugin interface</a>
on top of
<a href="LinkTimeOptimization.html#lto">libLTO</a>.
The same plugin can also be used by other tools such as <tt>ar</tt> and
<tt>nm</tt>.
</div>
<!--=========================================================================-->
<h2><a name="build">How to build it</a></h2>
<!--=========================================================================-->
<div>
<p>You need to have gold with plugin support and build the LLVMgold
plugin. Check whether you have gold running <tt>/usr/bin/ld -v</tt>. It will
report &#8220;GNU gold&#8221; or else &#8220GNU ld&#8221; if not. If you have
gold, check for plugin support by running <tt>/usr/bin/ld -plugin</tt>. If it
complains &#8220missing argument&#8221 then you have plugin support. If not,
such as an &#8220;unknown option&#8221; error then you will either need to
build gold or install a version with plugin support.</p>
<ul>
<li>To build gold with plugin support:
<pre class="doc_code">
mkdir binutils
cd binutils
cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
<em>{enter "anoncvs" as the password}</em>
cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
mkdir build
cd build
../src/configure --enable-gold --enable-plugins
make all-gold
</pre>
That should leave you with <tt>binutils/build/gold/ld-new</tt> which supports the <tt>-plugin</tt> option. It also built would have
<tt>binutils/build/binutils/ar</tt> and <tt>nm-new</tt> which support plugins
but don't have a visible -plugin option, instead relying on the gold plugin
being present in <tt>../lib/bfd-plugins</tt> relative to where the binaries are
placed.
<li>Build the LLVMgold plugin: Configure LLVM with
<tt>--with-binutils-include=/path/to/binutils/src/include</tt> and run
<tt>make</tt>.
</ul>
</div>
<!--=========================================================================-->
<h2><a name="usage">Usage</a></h2>
<!--=========================================================================-->
<div>
<p>The linker takes a <tt>-plugin</tt> option that points to the path of
the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt>
would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look
for the line where it runs <tt>collect2</tt>. Replace that with
<tt>ld-new -plugin /path/to/LLVMgold.so</tt> to test it out. Once you're
ready to switch to using gold, backup your existing <tt>/usr/bin/ld</tt>
then replace it with <tt>ld-new</tt>.</p>
<p>You can produce bitcode files from <tt>clang</tt> using
<tt>-emit-llvm</tt> or <tt>-flto</tt>, or the <tt>-O4</tt> flag which is
synonymous with <tt>-O3 -flto</tt>.</p>
<p>Any of these flags will also cause <tt>clang</tt> to look for the
gold plugin in the <tt>lib</tt> directory under its prefix and pass the
<tt>-plugin</tt> option to <tt>ld</tt>. It will not look for an alternate
linker, which is why you need gold to be the installed system linker in
your path.</p>
<p>If you want <tt>ar</tt> and <tt>nm</tt> to work seamlessly as well, install
<tt>LLVMgold.so</tt> to <tt>/usr/lib/bfd-plugins</tt>. If you built your
own gold, be sure to install the <tt>ar</tt> and <tt>nm-new</tt> you built to
<tt>/usr/bin</tt>.<p>
<!-- ======================================================================= -->
<h3>
<a name="example1">Example of link time optimization</a>
</h3>
<div>
<p>The following example shows a worked example of the gold plugin mixing
LLVM bitcode and native code.
<pre class="doc_code">
--- a.c ---
#include &lt;stdio.h&gt;
extern void foo1(void);
extern void foo4(void);
void foo2(void) {
printf("Foo2\n");
}
void foo3(void) {
foo4();
}
int main(void) {
foo1();
}
--- b.c ---
#include &lt;stdio.h&gt;
extern void foo2(void);
void foo1(void) {
foo2();
}
void foo4(void) {
printf("Foo4");
}
--- command lines ---
$ clang -flto a.c -c -o a.o # &lt;-- a.o is LLVM bitcode file
$ ar q a.a a.o # &lt;-- a.a is an archive with LLVM bitcode
$ clang b.c -c -o b.o # &lt;-- b.o is native object file
$ clang -flto a.a b.o -o main # &lt;-- link with LLVMgold plugin
</pre>
<p>Gold informs the plugin that foo3 is never referenced outside the IR,
leading LLVM to delete that function. However, unlike in the
<a href="LinkTimeOptimization.html#example1">libLTO
example</a> gold does not currently eliminate foo4.</p>
</div>
</div>
<!--=========================================================================-->
<h2>
<a name="lto_autotools">
Quickstart for using LTO with autotooled projects
</a>
</h2>
<!--=========================================================================-->
<div>
<p>Once your system <tt>ld</tt>, <tt>ar</tt>, and <tt>nm</tt> all support LLVM
bitcode, everything is in place for an easy to use LTO build of autotooled
projects:</p>
<ul>
<li>Follow the instructions <a href="#build">on how to build LLVMgold.so</a>.</li>
<li>Install the newly built binutils to <tt>$PREFIX</tt></li>
<li>Copy <tt>Release/lib/LLVMgold.so</tt> to
<tt>$PREFIX/lib/bfd-plugins/</tt></li>
<li>Set environment variables (<tt>$PREFIX</tt> is where you installed clang and
binutils):
<pre class="doc_code">
export CC="$PREFIX/bin/clang -flto"
export CXX="$PREFIX/bin/clang++ -flto"
export AR="$PREFIX/bin/ar"
export NM="$PREFIX/bin/nm"
export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
export CFLAGS="-O4"
</pre>
</li>
<li>Or you can just set your path:
<pre class="doc_code">
export PATH="$PREFIX/bin:$PATH"
export CC="clang -flto"
export CXX="clang++ -flto"
export RANLIB=/bin/true
export CFLAGS="-O4"
</pre></li>
<li>Configure &amp; build the project as usual:
<pre class="doc_code">
% ./configure &amp;&amp; make &amp;&amp; make check
</pre></li>
</ul>
<p>The environment variable settings may work for non-autotooled projects
too, but you may need to set the <tt>LD</tt> environment variable as
well.</p>
</div>
<!--=========================================================================-->
<h2><a name="licensing">Licensing</a></h2>
<!--=========================================================================-->
<div>
<p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
<tt>plugin-api.h</tt> from gold which means that the resulting LLVMgold.so
binary is also GPLv3. This can still be used to link non-GPLv3 programs just
as much as gold could without the plugin.</p>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:nicholas@metrix.on.ca">Nick Lewycky</a><br>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2010-04-16 23:58:21 -0800 (Fri, 16 Apr 2010) $
</address>
</body>
</html>

74
cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt
View File

@ -1,74 +0,0 @@
Date: Sat, 18 Nov 2000 09:19:35 -0600 (CST)
From: Vikram Adve <vadve@cs.uiuc.edu>
To: Chris Lattner <lattner@cs.uiuc.edu>
Subject: a few thoughts
I've been mulling over the virtual machine problem and I had some
thoughts about some things for us to think about discuss:
1. We need to be clear on our goals for the VM. Do we want to emphasize
portability and safety like the Java VM? Or shall we focus on the
architecture interface first (i.e., consider the code generation and
processor issues), since the architecture interface question is also
important for portable Java-type VMs?
This is important because the audiences for these two goals are very
different. Architects and many compiler people care much more about
the second question. The Java compiler and OS community care much more
about the first one.
Also, while the architecture interface question is important for
Java-type VMs, the design constraints are very different.
2. Design issues to consider (an initial list that we should continue
to modify). Note that I'm not trying to suggest actual solutions here,
but just various directions we can pursue:
a. A single-assignment VM, which we've both already been thinking about.
b. A strongly-typed VM. One question is do we need the types to be
explicitly declared or should they be inferred by the dynamic compiler?
c. How do we get more high-level information into the VM while keeping
to a low-level VM design?
o Explicit array references as operands? An alternative is
to have just an array type, and let the index computations be
separate 3-operand instructions.
o Explicit instructions to handle aliasing, e.g.s:
-- an instruction to say "I speculate that these two values are not
aliased, but check at runtime", like speculative execution in
EPIC?
-- or an instruction to check whether two values are aliased and
execute different code depending on the answer, somewhat like
predicated code in EPIC
o (This one is a difficult but powerful idea.)
A "thread-id" field on every instruction that allows the static
compiler to generate a set of parallel threads, and then have
the runtime compiler and hardware do what they please with it.
This has very powerful uses, but thread-id on every instruction
is expensive in terms of instruction size and code size.
We would need to compactly encode it somehow.
Also, this will require some reading on at least two other
projects:
-- Multiscalar architecture from Wisconsin
-- Simultaneous multithreading architecture from Washington
o Or forget all this and stick to a traditional instruction set?
BTW, on an unrelated note, after the meeting yesterday, I did remember
that you had suggested doing instruction scheduling on SSA form instead
of a dependence DAG earlier in the semester. When we talked about
it yesterday, I didn't remember where the idea had come from but I
remembered later. Just giving credit where its due...
Perhaps you can save the above as a file under RCS so you and I can
continue to expand on this.
--Vikram

199
cpp/llvm/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt
View File

@ -1,199 +0,0 @@
Date: Sun, 19 Nov 2000 16:23:57 -0600 (CST)
From: Chris Lattner <sabre@nondot.org>
To: Vikram Adve <vadve@cs.uiuc.edu>
Subject: Re: a few thoughts
Okay... here are a few of my thoughts on this (it's good to know that we
think so alike!):
> 1. We need to be clear on our goals for the VM. Do we want to emphasize
> portability and safety like the Java VM? Or shall we focus on the
> architecture interface first (i.e., consider the code generation and
> processor issues), since the architecture interface question is also
> important for portable Java-type VMs?
I forsee the architecture looking kinda like this: (which is completely
subject to change)
1. The VM code is NOT guaranteed safe in a java sense. Doing so makes it
basically impossible to support C like languages. Besides that,
certifying a register based language as safe at run time would be a
pretty expensive operation to have to do. Additionally, we would like
to be able to statically eliminate many bounds checks in Java
programs... for example.
2. Instead, we can do the following (eventually):
* Java bytecode is used as our "safe" representation (to avoid
reinventing something that we don't add much value to). When the
user chooses to execute Java bytecodes directly (ie, not
precompiled) the runtime compiler can do some very simple
transformations (JIT style) to convert it into valid input for our
VM. Performance is not wonderful, but it works right.
* The file is scheduled to be compiled (rigorously) at a later
time. This could be done by some background process or by a second
processor in the system during idle time or something...
* To keep things "safe" ie to enforce a sandbox on Java/foreign code,
we could sign the generated VM code with a host specific private
key. Then before the code is executed/loaded, we can check to see if
the trusted compiler generated the code. This would be much quicker
than having to validate consistency (especially if bounds checks have
been removed, for example)
> This is important because the audiences for these two goals are very
> different. Architects and many compiler people care much more about
> the second question. The Java compiler and OS community care much more
> about the first one.
3. By focusing on a more low level virtual machine, we have much more room
for value add. The nice safe "sandbox" VM can be provided as a layer
on top of it. It also lets us focus on the more interesting compilers
related projects.
> 2. Design issues to consider (an initial list that we should continue
> to modify). Note that I'm not trying to suggest actual solutions here,
> but just various directions we can pursue:
Understood. :)
> a. A single-assignment VM, which we've both already been thinking
> about.
Yup, I think that this makes a lot of sense. I am still intrigued,
however, by the prospect of a minimally allocated VM representation... I
think that it could have definite advantages for certain applications
(think very small machines, like PDAs). I don't, however, think that our
initial implementations should focus on this. :)
Here are some other auxiliary goals that I think we should consider:
1. Primary goal: Support a high performance dynamic compilation
system. This means that we have an "ideal" division of labor between
the runtime and static compilers. Of course, the other goals of the
system somewhat reduce the importance of this point (f.e. portability
reduces performance, but hopefully not much)
2. Portability to different processors. Since we are most familiar with
x86 and solaris, I think that these two are excellent candidates when
we get that far...
3. Support for all languages & styles of programming (general purpose
VM). This is the point that disallows java style bytecodes, where all
array refs are checked for bounds, etc...
4. Support linking between different language families. For example, call
C functions directly from Java without using the nasty/slow/gross JNI
layer. This involves several subpoints:
A. Support for languages that require garbage collectors and integration
with languages that don't. As a base point, we could insist on
always using a conservative GC, but implement free as a noop, f.e.
> b. A strongly-typed VM. One question is do we need the types to be
> explicitly declared or should they be inferred by the dynamic
> compiler?
B. This is kind of similar to another idea that I have: make OOP
constructs (virtual function tables, class heirarchies, etc) explicit
in the VM representation. I believe that the number of additional
constructs would be fairly low, but would give us lots of important
information... something else that would/could be important is to
have exceptions as first class types so that they would be handled in
a uniform way for the entire VM... so that C functions can call Java
functions for example...
> c. How do we get more high-level information into the VM while keeping
> to a low-level VM design?
> o Explicit array references as operands? An alternative is
> to have just an array type, and let the index computations be
> separate 3-operand instructions.
C. In the model I was thinking of (subject to change of course), we
would just have an array type (distinct from the pointer
types). This would allow us to have arbitrarily complex index
expressions, while still distinguishing "load" from "Array load",
for example. Perhaps also, switch jump tables would be first class
types as well? This would allow better reasoning about the program.
5. Support dynamic loading of code from various sources. Already
mentioned above was the example of loading java bytecodes, but we want
to support dynamic loading of VM code as well. This makes the job of
the runtime compiler much more interesting: it can do interprocedural
optimizations that the static compiler can't do, because it doesn't
have all of the required information (for example, inlining from
shared libraries, etc...)
6. Define a set of generally useful annotations to add to the VM
representation. For example, a function can be analysed to see if it
has any sideeffects when run... also, the MOD/REF sets could be
calculated, etc... we would have to determine what is reasonable. This
would generally be used to make IP optimizations cheaper for the
runtime compiler...
> o Explicit instructions to handle aliasing, e.g.s:
> -- an instruction to say "I speculate that these two values are not
> aliased, but check at runtime", like speculative execution in
> EPIC?
> -- or an instruction to check whether two values are aliased and
> execute different code depending on the answer, somewhat like
> predicated code in EPIC
These are also very good points... if this can be determined at compile
time. I think that an epic style of representation (not the instruction
packing, just the information presented) could be a very interesting model
to use... more later...
> o (This one is a difficult but powerful idea.)
> A "thread-id" field on every instruction that allows the static
> compiler to generate a set of parallel threads, and then have
> the runtime compiler and hardware do what they please with it.
> This has very powerful uses, but thread-id on every instruction
> is expensive in terms of instruction size and code size.
> We would need to compactly encode it somehow.
Yes yes yes! :) I think it would be *VERY* useful to include this kind
of information (which EPIC architectures *implicitly* encode. The trend
that we are seeing supports this greatly:
1. Commodity processors are getting massive SIMD support:
* Intel/Amd MMX/MMX2
* AMD's 3Dnow!
* Intel's SSE/SSE2
* Sun's VIS
2. SMP is becoming much more common, especially in the server space.
3. Multiple processors on a die are right around the corner.
If nothing else, not designing this in would severely limit our future
expansion of the project...
> Also, this will require some reading on at least two other
> projects:
> -- Multiscalar architecture from Wisconsin
> -- Simultaneous multithreading architecture from Washington
>
> o Or forget all this and stick to a traditional instruction set?
Heh... :) Well, from a pure research point of view, it is almost more
attactive to go with the most extreme/different ISA possible. On one axis
you get safety and conservatism, and on the other you get degree of
influence that the results have. Of course the problem with pure research
is that often times there is no concrete product of the research... :)
> BTW, on an unrelated note, after the meeting yesterday, I did remember
> that you had suggested doing instruction scheduling on SSA form instead
> of a dependence DAG earlier in the semester. When we talked about
> it yesterday, I didn't remember where the idea had come from but I
> remembered later. Just giving credit where its due...
:) Thanks.
> Perhaps you can save the above as a file under RCS so you and I can
> continue to expand on this.
I think it makes sense to do so when we get our ideas more formalized and
bounce it back and forth a couple of times... then I'll do a more formal
writeup of our goals and ideas. Obviously our first implementation will
not want to do all of the stuff that I pointed out above... be we will
want to design the project so that we do not artificially limit ourselves
at sometime in the future...
Anyways, let me know what you think about these ideas... and if they sound
reasonable...
-Chris

30
cpp/llvm/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt
View File

@ -1,30 +0,0 @@
From: Chris Lattner [mailto:sabre@nondot.org]
Sent: Wednesday, December 06, 2000 6:41 PM
To: Vikram S. Adve
Subject: Additional idea with respect to encoding
Here's another idea with respect to keeping the common case instruction
size down (less than 32 bits ideally):
Instead of encoding an instruction to operate on two register numbers,
have it operate on two negative offsets based on the current register
number. Therefore, instead of using:
r57 = add r55, r56 (r57 is the implicit dest register, of course)
We could use:
r57 = add -2, -1
My guess is that most SSA references are to recent values (especially if
they correspond to expressions like (x+y*z+p*q/ ...), so the negative
numbers would tend to stay small, even at the end of the procedure (where
the implicit register destination number could be quite large). Of course
the negative sign is reduntant, so you would be storing small integers
almost all of the time, and 5-6 bits worth of register number would be
plenty for most cases...
What do you think?
-Chris

83
cpp/llvm/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt
View File

@ -1,83 +0,0 @@
SUMMARY
-------
We met to discuss the LLVM instruction format and bytecode representation:
ISSUES RESOLVED
---------------
1. We decided that we shall use a flat namespace to represent our
variables in SSA form, as opposed to having a two dimensional namespace
of the original variable and the SSA instance subscript.
ARGUMENT AGAINST:
* A two dimensional namespace would be valuable when doing alias
analysis because the extra information can help limit the scope of
analysis.
ARGUMENT FOR:
* Including this information would require that all users of the LLVM
bytecode would have to parse and handle it. This would slow down the
common case and inflate the instruction representation with another
infinite variable space.
REASONING:
* It was decided that because original variable sources could be
reconstructed from SSA form in linear time, that it would be an
unjustified expense for the common case to include the extra
information for one optimization. Alias analysis itself is typically
greater than linear in asymptotic complexity, so this extra analaysis
would not affect the runtime of the optimization in a significant
way. Additionally, this would be an unlikely optimization to do at
runtime.
IDEAS TO CONSIDER
-----------------
1. Including dominator information in the LLVM bytecode
representation. This is one example of an analysis result that may be
packaged with the bytecodes themselves. As a conceptual implementation
idea, we could include an immediate dominator number for each basic block
in the LLVM bytecode program. Basic blocks could be numbered according
to the order of occurrence in the bytecode representation.
2. Including loop header and body information. This would facilitate
detection of intervals and natural loops.
UNRESOLVED ISSUES
-----------------
1. Will oSUIF provide enough of an infrastructure to support the research
that we will be doing? We know that it has less than stellar
performance, but hope that this will be of little importance for our
static compiler. This could affect us if we decided to do some IP
research. Also we do not yet understand the level of exception support
currently implemented.
2. Should we consider the requirements of a direct hardware implementation
of the LLVM when we design it? If so, several design issues should
have their priorities shifted. The other option is to focus on a
software layer interpreting the LLVM in all cases.
3. Should we use some form of packetized format to improve forward
compatibility? For example, we could design the system to encode a
packet type and length field before analysis information, to allow a
runtime to skip information that it didn't understand in a bytecode
stream. The obvious benefit would be for compatibility, the drawback
is that it would tend to splinter that 'standard' LLVM definition.
4. Should we use fixed length instructions or variable length
instructions? Fetching variable length instructions is expensive (for
either hardware or software based LLVM runtimes), but we have several
'infinite' spaces that instructions operate in (SSA register numbers,
type spaces, or packet length [if packets were implemented]). Several
options were mentioned including:
A. Using 16 or 32 bit numbers, which would be 'big enough'
B. A scheme similar to how UTF-8 works, to encode infinite numbers
while keeping small number small.
C. Use something similar to Huffman encoding, so that the most common
numbers are the smallest.
-Chris

39
cpp/llvm/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt
View File

@ -1,39 +0,0 @@
Date: Wed, 31 Jan 2001 12:04:33 -0600
From: Vikram S. Adve <vadve@cs.uiuc.edu>
To: Chris Lattner <lattner@cs.uiuc.edu>
Subject: another thought
I have a budding idea about making LLVM a little more ambitious: a
customizable runtime system that can be used to implement language-specific
virtual machines for many different languages. E.g., a C vm, a C++ vm, a
Java vm, a Lisp vm, ..
The idea would be that LLVM would provide a standard set of runtime features
(some low-level like standard assembly instructions with code generation and
static and runtime optimization; some higher-level like type-safety and
perhaps a garbage collection library). Each language vm would select the
runtime features needed for that language, extending or customizing them as
needed. Most of the machine-dependent code-generation and optimization
features as well as low-level machine-independent optimizations (like PRE)
could be provided by LLVM and should be sufficient for any language,
simplifying the language compiler. (This would also help interoperability
between languages.) Also, some or most of the higher-level
machine-independent features like type-safety and access safety should be
reusable by different languages, with minor extensions. The language
compiler could then focus on language-specific analyses and optimizations.
The risk is that this sounds like a universal IR -- something that the
compiler community has tried and failed to develop for decades, and is
universally skeptical about. No matter what we say, we won't be able to
convince anyone that we have a universal IR that will work. We need to
think about whether LLVM is different or if has something novel that might
convince people. E.g., the idea of providing a package of separable
features that different languages select from. Also, using SSA with or
without type-safety as the intermediate representation.
One interesting starting point would be to discuss how a JVM would be
implemented on top of LLVM a bit more. That might give us clues on how to
structure LLVM to support one or more language VMs.
--Vikram

67
cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt
View File

@ -1,67 +0,0 @@
Date: Tue, 6 Feb 2001 20:27:37 -0600 (CST)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: Type notation debate...
This is the way that I am currently planning on implementing types:
Primitive Types:
type ::= void|bool|sbyte|ubyte|short|ushort|int|uint|long|ulong
Method:
typelist ::= typelisth | /*empty*/
typelisth ::= type | typelisth ',' type
type ::= type (typelist)
Arrays (without and with size):
type ::= '[' type ']' | '[' INT ',' type ']'
Pointer:
type ::= type '*'
Structure:
type ::= '{' typelist '}'
Packed:
type ::= '<' INT ',' type '>'
Simple examples:
[[ %4, int ]] - array of (array of 4 (int))
[ { int, int } ] - Array of structure
[ < %4, int > ] - Array of 128 bit SIMD packets
int (int, [[int, %4]]) - Method taking a 2d array and int, returning int
Okay before you comment, please look at:
http://www.research.att.com/~bs/devXinterview.html
Search for "In another interview, you defined the C declarator syntax as
an experiment that failed. However, this syntactic construct has been
around for 27 years and perhaps more; why do you consider it problematic
(except for its cumbersome syntax)?" and read that response for me. :)
Now with this syntax, his example would be represented as:
[ %10, bool (int, int) * ] *
vs
bool (*(*)[10])(int, int)
in C.
Basically, my argument for this type construction system is that it is
VERY simple to use and understand (although it IS different than C, it is
very simple and straightforward, which C is NOT). In fact, I would assert
that most programmers TODAY do not understand pointers to member
functions, and have to look up an example when they have to write them.
In my opinion, it is critically important to have clear and concise type
specifications, because types are going to be all over the programs.
Let me know your thoughts on this. :)
-Chris

75
cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt
View File

@ -1,75 +0,0 @@
Date: Thu, 8 Feb 2001 08:42:04 -0600
From: Vikram S. Adve <vadve@cs.uiuc.edu>
To: Chris Lattner <sabre@nondot.org>
Subject: RE: Type notation debate...
Chris,
> Okay before you comment, please look at:
>
> http://www.research.att.com/~bs/devXinterview.html
I read this argument. Even before that, I was already in agreement with you
and him that the C declarator syntax is difficult and confusing.
But in fact, if you read the entire answer carefully, he came to the same
conclusion I do: that you have to go with familiar syntax over logical
syntax because familiarity is such a strong force:
"However, familiarity is a strong force. To compare, in English, we
live
more or less happily with the absurd rules for "to be" (am, are, is, been,
was, were, ...) and all attempts to simplify are treated with contempt or
(preferably) humor. It be a curious world and it always beed."
> Basically, my argument for this type construction system is that it is
> VERY simple to use and understand (although it IS different than C, it is
> very simple and straightforward, which C is NOT). In fact, I would assert
> that most programmers TODAY do not understand pointers to member
> functions, and have to look up an example when they have to write them.
Again, I don't disagree with this at all. But to some extent this
particular problem is inherently difficult. Your syntax for the above
example may be easier for you to read because this is the way you have been
thinking about it. Honestly, I don't find it much easier than the C syntax.
In either case, I would have to look up an example to write pointers to
member functions.
But pointers to member functions are nowhere near as common as arrays. And
the old array syntax:
type [ int, int, ...]
is just much more familiar and clear to people than anything new you
introduce, no matter how logical it is. Introducing a new syntax that may
make function pointers easier but makes arrays much more difficult seems
very risky to me.
> In my opinion, it is critically important to have clear and concise type
> specifications, because types are going to be all over the programs.
I absolutely agree. But the question is, what is more clear and concise?
The syntax programmers are used to out of years of experience or a new
syntax that they have never seen that has a more logical structure. I think
the answer is the former. Sometimes, you have to give up a better idea
because you can't overcome sociological barriers to it. Qwerty keyboards
and Windows are two classic examples of bad technology that are difficult to
root out.
P.S. Also, while I agree that most your syntax is more logical, there is
one part that isn't:
Arrays (without and with size):
type ::= '[' type ']' | '[' INT ',' type ']'.
The arrays with size lists the dimensions and the type in a single list.
That is just too confusing:
[10, 40, int]
This seems to be a 3-D array where the third dimension is something strange.
It is too confusing to have a list of 3 things, some of which are dimensions
and one is a type. Either of the following would be better:
array [10, 40] of int
or
int [10, 40]
--Vikram

53
cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt
View File

@ -1,53 +0,0 @@
Date: Thu, 8 Feb 2001 14:31:05 -0600 (CST)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: RE: Type notation debate...
> Arrays (without and with size):
> type ::= '[' type ']' | '[' INT ',' type ']'.
>
> The arrays with size lists the dimensions and the type in a single list.
> That is just too confusing:
> [10, 40, int]
> This seems to be a 3-D array where the third dimension is something strange.
> It is too confusing to have a list of 3 things, some of which are dimensions
> and one is a type.
The above grammar indicates that there is only one integer parameter, ie
the upper bound. The lower bound is always implied to be zero, for
several reasons:
* As a low level VM, we want to expose addressing computations
explicitly. Since the lower bound must always be known in a high level
language statically, the language front end can do the translation
automatically.
* This fits more closely with what Java needs, ie what we need in the
short term. Java arrays are always zero based.
If a two element list is too confusing, I would recommend an alternate
syntax of:
type ::= '[' type ']' | '[' INT 'x' type ']'.
For example:
[12 x int]
[12x int]
[ 12 x [ 4x int ]]
Which is syntactically nicer, and more explicit.
> Either of the following would be better:
> array [10, 40] of int
I considered this approach for arrays in general (ie array of int/ array
of 12 int), but found that it made declarations WAY too long. Remember
that because of the nature of llvm, you get a lot of types strewn all over
the program, and using the 'typedef' like facility is not a wonderful
option, because then types aren't explicit anymore.
I find this email interesting, because you contradict the previous email
you sent, where you recommend that we stick to C syntax....
-Chris

89
cpp/llvm/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt
View File

@ -1,89 +0,0 @@
> But in fact, if you read the entire answer carefully, he came to the same
> conclusion I do: that you have to go with familiar syntax over logical
> syntax because familiarity is such a strong force:
> "However, familiarity is a strong force. To compare, in English, we
live
> more or less happily with the absurd rules for "to be" (am, are, is, been,
> was, were, ...) and all attempts to simplify are treated with contempt or
> (preferably) humor. It be a curious world and it always beed."
Although you have to remember that his situation was considerably
different than ours. He was in a position where he was designing a high
level language that had to be COMPATIBLE with C. Our language is such
that a new person would have to learn the new, different, syntax
anyways. Making them learn about the type system does not seem like much
of a stretch from learning the opcodes and how SSA form works, and how
everything ties together...
> > Basically, my argument for this type construction system is that it is
> > VERY simple to use and understand (although it IS different than C, it is
> > very simple and straightforward, which C is NOT). In fact, I would assert
> > that most programmers TODAY do not understand pointers to member
> > functions, and have to look up an example when they have to write them.
> Again, I don't disagree with this at all. But to some extent this
> particular problem is inherently difficult. Your syntax for the above
> example may be easier for you to read because this is the way you have been
> thinking about it. Honestly, I don't find it much easier than the C syntax.
> In either case, I would have to look up an example to write pointers to
> member functions.
I would argue that because the lexical structure of the language is self
consistent, any person who spent a significant amount of time programming
in LLVM directly would understand how to do it without looking it up in a
manual. The reason this does not work for C is because you rarely have to
declare these pointers, and the syntax is inconsistent with the method
declaration and calling syntax.
> But pointers to member functions are nowhere near as common as arrays.
Very true. If you're implementing an object oriented language, however,
remember that you have to do all the pointer to member function stuff
yourself.... so every time you invoke a virtual method one is involved
(instead of having C++ hide it for you behind "syntactic sugar").
> And the old array syntax:
> type [ int, int, ...]
> is just much more familiar and clear to people than anything new you
> introduce, no matter how logical it is.
Erm... excuse me but how is this the "old array syntax"? If you are
arguing for consistency with C, you should be asking for 'type int []',
which is significantly different than the above (beside the above
introduces a new operator and duplicates information
needlessly). Basically what I am suggesting is exactly the above without
the fluff. So instead of:
type [ int, int, ...]
you use:
type [ int ]
> Introducing a new syntax that may
> make function pointers easier but makes arrays much more difficult seems
> very risky to me.
This is not about function pointers. This is about consistency in the
type system, and consistency with the rest of the language. The point
above does not make arrays any more difficult to use, and makes the
structure of types much more obvious than the "c way".
> > In my opinion, it is critically important to have clear and concise type
> > specifications, because types are going to be all over the programs.
>
> I absolutely agree. But the question is, what is more clear and concise?
> The syntax programmers are used to out of years of experience or a new
> syntax that they have never seen that has a more logical structure. I think
> the answer is the former. Sometimes, you have to give up a better idea
> because you can't overcome sociological barriers to it. Qwerty keyboards
> and Windows are two classic examples of bad technology that are difficult to
> root out.
Very true, but you seem to be advocating a completely different Type
system than C has, in addition to it not offering the advantages of clear
structure that the system I recommended does... so you seem to not have a
problem with changing this, just with what I change it to. :)
-Chris

120
cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveComments.txt
View File

@ -1,120 +0,0 @@
Ok, here are my comments and suggestions about the LLVM instruction set.
We should discuss some now, but can discuss many of them later, when we
revisit synchronization, type inference, and other issues.
(We have discussed some of the comments already.)
o We should consider eliminating the type annotation in cases where it is
essentially obvious from the instruction type, e.g., in br, it is obvious
that the first arg. should be a bool and the other args should be labels:
br bool <cond>, label <iftrue>, label <iffalse>
I think your point was that making all types explicit improves clarity
and readability. I agree to some extent, but it also comes at the cost
of verbosity. And when the types are obvious from people's experience
(e.g., in the br instruction), it doesn't seem to help as much.
o On reflection, I really like your idea of having the two different switch
types (even though they encode implementation techniques rather than
semantics). It should simplify building the CFG and my guess is it could
enable some significant optimizations, though we should think about which.
o In the lookup-indirect form of the switch, is there a reason not to make
the val-type uint? Most HLL switch statements (including Java and C++)
require that anyway. And it would also make the val-type uniform
in the two forms of the switch.
I did see the switch-on-bool examples and, while cute, we can just use
the branch instructions in that particular case.
o I agree with your comment that we don't need 'neg'.
o There's a trade-off with the cast instruction:
+ it avoids having to define all the upcasts and downcasts that are
valid for the operands of each instruction (you probably have thought
of other benefits also)
- it could make the bytecode significantly larger because there could
be a lot of cast operations
o Making the second arg. to 'shl' a ubyte seems good enough to me.
255 positions seems adequate for several generations of machines
and is more compact than uint.
o I still have some major concerns about including malloc and free in the
language (either as builtin functions or instructions). LLVM must be
able to represent code from many different languages. Languages such as
C, C++ Java and Fortran 90 would not be able to use our malloc anyway
because each of them will want to provide a library implementation of it.
This gets even worse when code from different languages is linked
into a single executable (which is fairly common in large apps).
Having a single malloc would just not suffice, and instead would simply
complicate the picture further because it adds an extra variant in
addition to the one each language provides.
Instead, providing a default library version of malloc and free
(and perhaps a malloc_gc with garbage collection instead of free)
would make a good implementation available to anyone who wants it.
I don't recall all your arguments in favor so let's discuss this again,
and soon.
o 'alloca' on the other hand sounds like a good idea, and the
implementation seems fairly language-independent so it doesn't have the
problems with malloc listed above.
o About indirect call:
Your option #2 sounded good to me. I'm not sure I understand your
concern about an explicit 'icall' instruction?
o A pair of important synchronization instr'ns to think about:
load-linked
store-conditional
o Other classes of instructions that are valuable for pipeline performance:
conditional-move
predicated instructions
o I believe tail calls are relatively easy to identify; do you know why
.NET has a tailcall instruction?
o I agree that we need a static data space. Otherwise, emulating global
data gets unnecessarily complex.
o About explicit parallelism:
We once talked about adding a symbolic thread-id field to each
instruction. (It could be optional so single-threaded codes are
not penalized.) This could map well to multi-threaded architectures
while providing easy ILP for single-threaded onces. But it is probably
too radical an idea to include in a base version of LLVM. Instead, it
could a great topic for a separate study.
What is the semantics of the IA64 stop bit?
o And finally, another thought about the syntax for arrays :-)
Although this syntax:
array <dimension-list> of <type>
is verbose, it will be used only in the human-readable assembly code so
size should not matter. I think we should consider it because I find it
to be the clearest syntax. It could even make arrays of function
pointers somewhat readable.

245
cpp/llvm/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt
View File

@ -1,245 +0,0 @@
From: Chris Lattner <sabre@nondot.org>
To: "Vikram S. Adve" <vadve@cs.uiuc.edu>
Subject: Re: LLVM Feedback
I've included your feedback in the /home/vadve/lattner/llvm/docs directory
so that it will live in CVS eventually with the rest of LLVM. I've
significantly updated the documentation to reflect the changes you
suggested, as specified below:
> We should consider eliminating the type annotation in cases where it is
> essentially obvious from the instruction type:
> br bool <cond>, label <iftrue>, label <iffalse>
> I think your point was that making all types explicit improves clarity
> and readability. I agree to some extent, but it also comes at the
> cost of verbosity. And when the types are obvious from people's
> experience (e.g., in the br instruction), it doesn't seem to help as
> much.
Very true. We should discuss this more, but my reasoning is more of a
consistency argument. There are VERY few instructions that can have all
of the types eliminated, and doing so when available unnecessarily makes
the language more difficult to handle. Especially when you see 'int
%this' and 'bool %that' all over the place, I think it would be
disorienting to see:
br %predicate, %iftrue, %iffalse
for branches. Even just typing that once gives me the creeps. ;) Like I
said, we should probably discuss this further in person...
> On reflection, I really like your idea of having the two different
> switch types (even though they encode implementation techniques rather
> than semantics). It should simplify building the CFG and my guess is it
> could enable some significant optimizations, though we should think
> about which.
Great. I added a note to the switch section commenting on how the VM
should just use the instruction type as a hint, and that the
implementation may choose altermate representations (such as predicated
branches).
> In the lookup-indirect form of the switch, is there a reason not to
> make the val-type uint?
No. This was something I was debating for a while, and didn't really feel
strongly about either way. It is common to switch on other types in HLL's
(for example signed int's are particularly common), but in this case, all
that will be added is an additional 'cast' instruction. I removed that
from the spec.
> I agree with your comment that we don't need 'neg'
Removed.
> There's a trade-off with the cast instruction:
> + it avoids having to define all the upcasts and downcasts that are
> valid for the operands of each instruction (you probably have
> thought of other benefits also)
> - it could make the bytecode significantly larger because there could
> be a lot of cast operations
+ You NEED casts to represent things like:
void foo(float);
...
int x;
...
foo(x);
in a language like C. Even in a Java like language, you need upcasts
and some way to implement dynamic downcasts.
+ Not all forms of instructions take every type (for example you can't
shift by a floating point number of bits), thus SOME programs will need
implicit casts.
To be efficient and to avoid your '-' point above, we just have to be
careful to specify that the instructions shall operate on all common
types, therefore casting should be relatively uncommon. For example all
of the arithmetic operations work on almost all data types.
> Making the second arg. to 'shl' a ubyte seems good enough to me.
> 255 positions seems adequate for several generations of machines
Okay, that comment is removed.
> and is more compact than uint.
No, it isn't. Remember that the bytecode encoding saves value slots into
the bytecode instructions themselves, not constant values. This is
another case where we may introduce more cast instructions (but we will
also reduce the number of opcode variants that must be supported by a
virtual machine). Because most shifts are by constant values, I don't
think that we'll have to cast many shifts. :)
> I still have some major concerns about including malloc and free in the
> language (either as builtin functions or instructions).
Agreed. How about this proposal:
malloc/free are either built in functions or actual opcodes. They provide
all of the type safety that the document would indicate, blah blah
blah. :)
Now, because of all of the excellent points that you raised, an
implementation may want to override the default malloc/free behavior of
the program. To do this, they simply implement a "malloc" and
"free" function. The virtual machine will then be defined to use the user
defined malloc/free function (which return/take void*'s, not type'd
pointers like the builtin function would) if one is available, otherwise
fall back on a system malloc/free.
Does this sound like a good compromise? It would give us all of the
typesafety/elegance in the language while still allowing the user to do
all the cool stuff they want to...
> 'alloca' on the other hand sounds like a good idea, and the
> implementation seems fairly language-independent so it doesn't have the
> problems with malloc listed above.
Okay, once we get the above stuff figured out, I'll put it all in the
spec.
> About indirect call:
> Your option #2 sounded good to me. I'm not sure I understand your
> concern about an explicit 'icall' instruction?
I worry too much. :) The other alternative has been removed. 'icall' is
now up in the instruction list next to 'call'.
> I believe tail calls are relatively easy to identify; do you know why
> .NET has a tailcall instruction?
Although I am just guessing, I believe it probably has to do with the fact
that they want languages like Haskell and lisp to be efficiently runnable
on their VM. Of course this means that the VM MUST implement tail calls
'correctly', or else life will suck. :) I would put this into a future
feature bin, because it could be pretty handy...
> A pair of important synchronization instr'ns to think about:
> load-linked
> store-conditional
What is 'load-linked'? I think that (at least for now) I should add these
to the 'possible extensions' section, because they are not immediately
needed...
> Other classes of instructions that are valuable for pipeline
> performance:
> conditional-move
> predicated instructions
Conditional move is effectly a special case of a predicated
instruction... and I think that all predicated instructions can possibly
be implemented later in LLVM. It would significantly change things, and
it doesn't seem to be very necessary right now. It would seem to
complicate flow control analysis a LOT in the virtual machine. I would
tend to prefer that a predicated architecture like IA64 convert from a
"basic block" representation to a predicated rep as part of it's dynamic
complication phase. Also, if a basic block contains ONLY a move, then
that can be trivally translated into a conditional move...
> I agree that we need a static data space. Otherwise, emulating global
> data gets unnecessarily complex.
Definitely. Also a later item though. :)
> We once talked about adding a symbolic thread-id field to each
> ..
> Instead, it could a great topic for a separate study.
Agreed. :)
> What is the semantics of the IA64 stop bit?
Basically, the IA64 writes instructions like this:
mov ...
add ...
sub ...
op xxx
op xxx
;;
mov ...
add ...
sub ...
op xxx
op xxx
;;
Where the ;; delimits a group of instruction with no dependencies between
them, which can all be executed concurrently (to the limits of the
available functional units). The ;; gets translated into a bit set in one
of the opcodes.
The advantages of this representation is that you don't have to do some
kind of 'thread id scheduling' pass by having to specify ahead of time how
many threads to use, and the representation doesn't have a per instruction
overhead...
> And finally, another thought about the syntax for arrays :-)
> Although this syntax:
> array <dimension-list> of <type>
> is verbose, it will be used only in the human-readable assembly code so
> size should not matter. I think we should consider it because I find it
> to be the clearest syntax. It could even make arrays of function
> pointers somewhat readable.
My only comment will be to give you an example of why this is a bad
idea. :)
Here is an example of using the switch statement (with my recommended
syntax):
switch uint %val, label %otherwise,
[%3 x {uint, label}] [ { uint %57, label %l1 },
{ uint %20, label %l2 },
{ uint %14, label %l3 } ]
Here it is with the syntax you are proposing:
switch uint %val, label %otherwise,
array %3 of {uint, label}
array of {uint, label}
{ uint %57, label %l1 },
{ uint %20, label %l2 },
{ uint %14, label %l3 }
Which is ambiguous and very verbose. It would be possible to specify
constants with [] brackets as in my syntax, which would look like this:
switch uint %val, label %otherwise,
array %3 of {uint, label} [ { uint %57, label %l1 },
{ uint %20, label %l2 },
{ uint %14, label %l3 } ]
But then the syntax is inconsistent between type definition and constant
definition (why do []'s enclose the constants but not the types??).
Anyways, I'm sure that there is much debate still to be had over
this... :)
-Chris
http://www.nondot.org/~sabre/os/
http://www.nondot.org/MagicStats/
http://korbit.sourceforge.net/

39
cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt
View File

@ -1,39 +0,0 @@
Date: Tue, 13 Feb 2001 13:29:52 -0600 (CST)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: LLVM Concerns...
I've updated the documentation to include load store and allocation
instructions (please take a look and let me know if I'm on the right
track):
file:/home/vadve/lattner/llvm/docs/LangRef.html#memoryops
I have a couple of concerns I would like to bring up:
1. Reference types
Right now, I've spec'd out the language to have a pointer type, which
works fine for lots of stuff... except that Java really has
references: constrained pointers that cannot be manipulated: added and
subtracted, moved, etc... Do we want to have a type like this? It
could be very nice for analysis (pointer always points to the start of
an object, etc...) and more closely matches Java semantics. The
pointer type would be kept for C++ like semantics. Through analysis,
C++ pointers could be promoted to references in the LLVM
representation.
2. Our "implicit" memory references in assembly language:
After thinking about it, this model has two problems:
A. If you do pointer analysis and realize that two stores are
independent and can share the same memory source object, there is
no way to represent this in either the bytecode or assembly.
B. When parsing assembly/bytecode, we effectively have to do a full
SSA generation/PHI node insertion pass to build the dependencies
when we don't want the "pinned" representation. This is not
cool.
I'm tempted to make memory references explicit in both the assembly and
bytecode to get around this... what do you think?
-Chris

47
cpp/llvm/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt
View File

@ -1,47 +0,0 @@
Date: Tue, 13 Feb 2001 18:25:42 -0600
From: Vikram S. Adve <vadve@cs.uiuc.edu>
To: Chris Lattner <sabre@nondot.org>
Subject: RE: LLVM Concerns...
> 1. Reference types
> Right now, I've spec'd out the language to have a pointer type, which
> works fine for lots of stuff... except that Java really has
> references: constrained pointers that cannot be manipulated: added and
> subtracted, moved, etc... Do we want to have a type like this? It
> could be very nice for analysis (pointer always points to the start of
> an object, etc...) and more closely matches Java semantics. The
> pointer type would be kept for C++ like semantics. Through analysis,
> C++ pointers could be promoted to references in the LLVM
> representation.
You're right, having references would be useful. Even for C++ the *static*
compiler could generate references instead of pointers with fairly
straightforward analysis. Let's include a reference type for now. But I'm
also really concerned that LLVM is becoming big and complex and (perhaps)
too high-level. After we get some initial performance results, we may have
a clearer idea of what our goals should be and we should revisit this
question then.
> 2. Our "implicit" memory references in assembly language:
> After thinking about it, this model has two problems:
> A. If you do pointer analysis and realize that two stores are
> independent and can share the same memory source object,
not sure what you meant by "share the same memory source object"
> there is
> no way to represent this in either the bytecode or assembly.
> B. When parsing assembly/bytecode, we effectively have to do a full
> SSA generation/PHI node insertion pass to build the dependencies
> when we don't want the "pinned" representation. This is not
> cool.
I understand the concern. But again, let's focus on the performance first
and then look at the language design issues. E.g., it would be good to know
how big the bytecode files are before expanding them further. I am pretty
keen to explore the implications of LLVM for mobile devices. Both bytecode
size and power consumption are important to consider there.
--Vikram

49
cpp/llvm/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt
View File

@ -1,49 +0,0 @@
By Chris:
LLVM has been designed with two primary goals in mind. First we strive to
enable the best possible division of labor between static and dynamic
compilers, and second, we need a flexible and powerful interface
between these two complementary stages of compilation. We feel that
providing a solution to these two goals will yield an excellent solution
to the performance problem faced by modern architectures and programming
languages.
A key insight into current compiler and runtime systems is that a
compiler may fall in anywhere in a "continuum of compilation" to do its
job. On one side, scripting languages statically compile nothing and
dynamically compile (or equivalently, interpret) everything. On the far
other side, traditional static compilers process everything statically and
nothing dynamically. These approaches have typically been seen as a
tradeoff between performance and portability. On a deeper level, however,
there are two reasons that optimal system performance may be obtained by a
system somewhere in between these two extremes: Dynamic application
behavior and social constraints.
From a technical perspective, pure static compilation cannot ever give
optimal performance in all cases, because applications have varying dynamic
behavior that the static compiler cannot take into consideration. Even
compilers that support profile guided optimization generate poor code in
the real world, because using such optimization tunes that application
to one particular usage pattern, whereas real programs (as opposed to
benchmarks) often have several different usage patterns.
On a social level, static compilation is a very shortsighted solution to
the performance problem. Instruction set architectures (ISAs) continuously
evolve, and each implementation of an ISA (a processor) must choose a set
of tradeoffs that make sense in the market context that it is designed for.
With every new processor introduced, the vendor faces two fundamental
problems: First, there is a lag time between when a processor is introduced
to when compilers generate quality code for the architecture. Secondly,
even when compilers catch up to the new architecture there is often a large
body of legacy code that was compiled for previous generations and will
not or can not be upgraded. Thus a large percentage of code running on a
processor may be compiled quite sub-optimally for the current
characteristics of the dynamic execution environment.
For these reasons, LLVM has been designed from the beginning as a long-term
solution to these problems. Its design allows the large body of platform
independent, static, program optimizations currently in compilers to be
reused unchanged in their current form. It also provides important static
type information to enable powerful dynamic and link time optimizations
to be performed quickly and efficiently. This combination enables an
increase in effective system performance for real world environments.

202
cpp/llvm/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt
View File

@ -1,202 +0,0 @@
Meeting notes: Implementation idea: Exception Handling in C++/Java
The 5/18/01 meeting discussed ideas for implementing exceptions in LLVM.
We decided that the best solution requires a set of library calls provided by
the VM, as well as an extension to the LLVM function invocation syntax.
The LLVM function invocation instruction previously looks like this (ignoring
types):
call func(arg1, arg2, arg3)
The extension discussed today adds an optional "with" clause that
associates a label with the call site. The new syntax looks like this:
call func(arg1, arg2, arg3) with funcCleanup
This funcHandler always stays tightly associated with the call site (being
encoded directly into the call opcode itself), and should be used whenever
there is cleanup work that needs to be done for the current function if
an exception is thrown by func (or if we are in a try block).
To support this, the VM/Runtime provide the following simple library
functions (all syntax in this document is very abstract):
typedef struct { something } %frame;
The VM must export a "frame type", that is an opaque structure used to
implement different types of stack walking that may be used by various
language runtime libraries. We imagine that it would be typical to
represent a frame with a PC and frame pointer pair, although that is not
required.
%frame getStackCurrentFrame();
Get a frame object for the current function. Note that if the current
function was inlined into its caller, the "current" frame will belong to
the "caller".
bool isFirstFrame(%frame f);
Returns true if the specified frame is the top level (first activated) frame
for this thread. For the main thread, this corresponds to the main()
function, for a spawned thread, it corresponds to the thread function.
%frame getNextFrame(%frame f);
Return the previous frame on the stack. This function is undefined if f
satisfies the predicate isFirstFrame(f).
Label *getFrameLabel(%frame f);
If a label was associated with f (as discussed below), this function returns
it. Otherwise, it returns a null pointer.
doNonLocalBranch(Label *L);
At this point, it is not clear whether this should be a function or
intrinsic. It should probably be an intrinsic in LLVM, but we'll deal with
this issue later.
Here is a motivating example that illustrates how these facilities could be
used to implement the C++ exception model:
void TestFunction(...) {
A a; B b;
foo(); // Any function call may throw
bar();
C c;
try {
D d;
baz();
} catch (int) {
...int Stuff...
// execution continues after the try block: the exception is consumed
} catch (double) {
...double stuff...
throw; // Exception is propogated
}
}
This function would compile to approximately the following code (heavy
pseudo code follows):
Func:
%a = alloca A
A::A(%a) // These ctors & dtors could throw, but we ignore this
%b = alloca B // minor detail for this example
B::B(%b)
call foo() with fooCleanup // An exception in foo is propogated to fooCleanup
call bar() with barCleanup // An exception in bar is propogated to barCleanup
%c = alloca C
C::C(c)
%d = alloca D
D::D(d)
call baz() with bazCleanup // An exception in baz is propogated to bazCleanup
d->~D();
EndTry: // This label corresponds to the end of the try block
c->~C() // These could also throw, these are also ignored
b->~B()
a->~A()
return
Note that this is a very straight forward and literal translation: exactly
what we want for zero cost (when unused) exception handling. Especially on
platforms with many registers (ie, the IA64) setjmp/longjmp style exception
handling is *very* impractical. Also, the "with" clauses describe the
control flow paths explicitly so that analysis is not adversly effected.
The foo/barCleanup labels are implemented as:
TryCleanup: // Executed if an exception escapes the try block
c->~C()
barCleanup: // Executed if an exception escapes from bar()
// fall through
fooCleanup: // Executed if an exception escapes from foo()
b->~B()
a->~A()
Exception *E = getThreadLocalException()
call throw(E) // Implemented by the C++ runtime, described below
Which does the work one would expect. getThreadLocalException is a function
implemented by the C++ support library. It returns the current exception
object for the current thread. Note that we do not attempt to recycle the
shutdown code from before, because performance of the mainline code is
critically important. Also, obviously fooCleanup and barCleanup may be
merged and one of them eliminated. This just shows how the code generator
would most likely emit code.
The bazCleanup label is more interesting. Because the exception may be caught
by the try block, we must dispatch to its handler... but it does not exist
on the call stack (it does not have a VM Call->Label mapping installed), so
we must dispatch statically with a goto. The bazHandler thus appears as:
bazHandler:
d->~D(); // destruct D as it goes out of scope when entering catch clauses
goto TryHandler
In general, TryHandler is not the same as bazHandler, because multiple
function calls could be made from the try block. In this case, trivial
optimization could merge the two basic blocks. TryHandler is the code
that actually determines the type of exception, based on the Exception object
itself. For this discussion, assume that the exception object contains *at
least*:
1. A pointer to the RTTI info for the contained object
2. A pointer to the dtor for the contained object
3. The contained object itself
Note that it is necessary to maintain #1 & #2 in the exception object itself
because objects without virtual function tables may be thrown (as in this
example). Assuming this, TryHandler would look something like this:
TryHandler:
Exception *E = getThreadLocalException();
switch (E->RTTIType) {
case IntRTTIInfo:
...int Stuff... // The action to perform from the catch block
break;
case DoubleRTTIInfo:
...double Stuff... // The action to perform from the catch block
goto TryCleanup // This catch block rethrows the exception
break; // Redundant, eliminated by the optimizer
default:
goto TryCleanup // Exception not caught, rethrow
}
// Exception was consumed
if (E->dtor)
E->dtor(E->object) // Invoke the dtor on the object if it exists
goto EndTry // Continue mainline code...
And that is all there is to it.
The throw(E) function would then be implemented like this (which may be
inlined into the caller through standard optimization):
function throw(Exception *E) {
// Get the start of the stack trace...
%frame %f = call getStackCurrentFrame()
// Get the label information that corresponds to it
label * %L = call getFrameLabel(%f)
while (%L == 0 && !isFirstFrame(%f)) {
// Loop until a cleanup handler is found
%f = call getNextFrame(%f)
%L = call getFrameLabel(%f)
}
if (%L != 0) {
call setThreadLocalException(E) // Allow handlers access to this...
call doNonLocalBranch(%L)
}
// No handler found!
call BlowUp() // Ends up calling the terminate() method in use
}
That's a brief rundown of how C++ exception handling could be implemented in
llvm. Java would be very similar, except it only uses destructors to unlock
synchronized blocks, not to destroy data. Also, it uses two stack walks: a
nondestructive walk that builds a stack trace, then a destructive walk that
unwinds the stack as shown here.
It would be trivial to get exception interoperability between C++ and Java.

45
cpp/llvm/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt
View File

@ -1,45 +0,0 @@
Date: Sat, 19 May 2001 19:09:13 -0500 (CDT)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: RE: Meeting writeup
> I read it through and it looks great!
Thanks!
> The finally clause in Java may need more thought. The code for this clause
> is like a subroutine because it needs to be entered from many points (end of
> try block and beginning of each catch block), and then needs to *return to
> the place from where the code was entered*. That's why JVM has the
> jsr/jsr_w instruction.
Hrm... I guess that is an implementation decision. It can either be
modelled as a subroutine (as java bytecodes do), which is really
gross... or it can be modelled as code duplication (emitted once inline,
then once in the exception path). Because this could, at worst,
slightly less than double the amount of code in a function (it is
bounded) I don't think this is a big deal. One of the really nice things
about the LLVM representation is that it still allows for runtime code
generation for exception paths (exceptions paths are not compiled until
needed). Obviously a static compiler couldn't do this though. :)
In this case, only one copy of the code would be compiled... until the
other one is needed on demand. Also this strategy fits with the "zero
cost" exception model... the standard case is not burdened with extra
branches or "call"s.
> I suppose you could save the return address in a particular register
> (specific to this finally block), jump to the finally block, and then at the
> end of the finally block, jump back indirectly through this register. It
> will complicate building the CFG but I suppose that can be handled. It is
> also unsafe in terms of checking where control returns (which is I suppose
> why the JVM doesn't use this).
I think that a code duplication method would be cleaner, and would avoid
the caveats that you mention. Also, it does not slow down the normal case
with an indirect branch...
Like everything, we can probably defer a final decision until later. :)
-Chris

63
cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt
View File

@ -1,63 +0,0 @@
Date: Fri, 1 Jun 2001 16:38:17 -0500 (CDT)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: Interesting: GCC passes
Take a look at this document (which describes the order of optimizations
that GCC performs):
http://gcc.gnu.org/onlinedocs/gcc_17.html
The rundown is that after RTL generation, the following happens:
1 . [t] jump optimization (jumps to jumps, etc)
2 . [t] Delete unreachable code
3 . Compute live ranges for CSE
4 . [t] Jump threading (jumps to jumps with identical or inverse conditions)
5 . [t] CSE
6 . *** Conversion to SSA
7 . [t] SSA Based DCE
8 . *** Conversion to LLVM
9 . UnSSA
10. GCSE
11. LICM
12. Strength Reduction
13. Loop unrolling
14. [t] CSE
15. [t] DCE
16. Instruction combination, register movement, scheduling... etc.
I've marked optimizations with a [t] to indicate things that I believe to
be relatively trivial to implement in LLVM itself. The time consuming
things to reimplement would be SSA based PRE, Strength reduction & loop
unrolling... these would be the major things we would miss out on if we
did LLVM creation from tree code [inlining and other high level
optimizations are done on the tree representation].
Given the lack of "strong" optimizations that would take a long time to
reimplement, I am leaning a bit more towards creating LLVM from the tree
code. Especially given that SGI has GPL'd their compiler, including many
SSA based optimizations that could be adapted (besides the fact that their
code looks MUCH nicer than GCC :)
Even if we choose to do LLVM code emission from RTL, we will almost
certainly want to move LLVM emission from step 8 down until at least CSE
has been rerun... which causes me to wonder if the SSA generation code
will still work (due to global variable dependencies and stuff). I assume
that it can be made to work, but might be a little more involved than we
would like.
I'm continuing to look at the Tree -> RTL code. It is pretty gross
because they do some of the translation a statement at a time, and some
of it a function at a time... I'm not quite clear why and how the
distinction is drawn, but it does not appear that there is a wonderful
place to attach extra info.
Anyways, I'm proceeding with the RTL -> LLVM conversion phase for now. We
can talk about this more on Monday.
Wouldn't it be nice if there were a obvious decision to be made? :)
-Chris

71
cpp/llvm/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt
View File

@ -1,71 +0,0 @@
Date: Fri, 1 Jun 2001 17:08:44 -0500 (CDT)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: RE: Interesting: GCC passes
> That is very interesting. I agree that some of these could be done on LLVM
> at link-time, but it is the extra time required that concerns me. Link-time
> optimization is severely time-constrained.
If we were to reimplement any of these optimizations, I assume that we
could do them a translation unit at a time, just as GCC does now. This
would lead to a pipeline like this:
Static optimizations, xlation unit at a time:
.c --GCC--> .llvm --llvmopt--> .llvm
Link time optimizations:
.llvm --llvm-ld--> .llvm --llvm-link-opt--> .llvm
Of course, many optimizations could be shared between llvmopt and
llvm-link-opt, but the wouldn't need to be shared... Thus compile time
could be faster, because we are using a "smarter" IR (SSA based).
> BTW, about SGI, "borrowing" SSA-based optimizations from one compiler and
> putting it into another is not necessarily easier than re-doing it.
> Optimization code is usually heavily tied in to the specific IR they use.
Understood. The only reason that I brought this up is because SGI's IR is
more similar to LLVM than it is different in many respects (SSA based,
relatively low level, etc), and could be easily adapted. Also their
optimizations are written in C++ and are actually somewhat
structured... of course it would be no walk in the park, but it would be
much less time consuming to adapt, say, SSA-PRE than to rewrite it.
> But your larger point is valid that adding SSA based optimizations is
> feasible and should be fun. (Again, link time cost is the issue.)
Assuming linktime cost wasn't an issue, the question is:
Does using GCC's backend buy us anything?
> It also occurs to me that GCC is probably doing quite a bit of back-end
> optimization (step 16 in your list). Do you have a breakdown of that?
Not really. The irritating part of GCC is that it mixes it all up and
doesn't have a clean separation of concerns. A lot of the "back end
optimization" happens right along with other data optimizations (ie, CSE
of machine specific things).
As far as REAL back end optimizations go, it looks something like this:
1. Instruction combination: try to make CISCy instructions, if available
2. Register movement: try to get registers in the right places for the
architecture to avoid register to register moves. For example, try to get
the first argument of a function to naturally land in %o0 for sparc.
3. Instruction scheduling: 'nuff said :)
4. Register class preferencing: ??
5. Local register allocation
6. global register allocation
7. Spilling
8. Local regalloc
9. Jump optimization
10. Delay slot scheduling
11. Branch shorting for CISC machines
12. Instruction selection & peephole optimization
13. Debug info output
But none of this would be usable for LLVM anyways, unless we were using
GCC as a static compiler.
-Chris

30
cpp/llvm/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt
View File

@ -1,30 +0,0 @@
Date: Wed, 20 Jun 2001 12:32:22 -0500
From: Vikram Adve <vadve@cs.uiuc.edu>
To: Chris Lattner <lattner@cs.uiuc.edu>
Subject: .NET vs. our VM
One significant difference between .NET CLR and our VM is that the CLR
includes full information about classes and inheritance. In fact, I just
sat through the paper on adding templates to .NET CLR, and the speaker
indicated that the goal seems to be to do simple static compilation (very
little lowering or optimization). Also, the templates implementation in CLR
"relies on dynamic class loading and JIT compilation".
This is an important difference because I think there are some significant
advantages to have a much lower level VM layer, and do significant static
analysis and optimization.
I also talked to the lead guy for KAI's C++ compiler (Arch Robison) and he
said that SGI and other commercial compilers have included options to export
their *IR* next to the object code (i.e., .il files) and use them for
link-time code generation. In fact, he said that the .o file was nearly
empty and was entirely generated from the .il at link-time. But he agreed
that this limited the link-time interprocedural optimization to modules
compiled by the same compiler, whereas our approach allows us to link and
optimize modules from multiple different compilers. (Also, of course, they
don't do anything for runtime optimization).
All issues to bring up in Related Work.
--Vikram

31
cpp/llvm/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt
View File

@ -1,31 +0,0 @@
Date: Fri, 6 Jul 2001 16:56:56 -0500
From: Vikram S. Adve <vadve@cs.uiuc.edu>
To: Chris Lattner <lattner@cs.uiuc.edu>
Subject: lowering the IR
BTW, I do think that we should consider lowering the IR as you said. I
didn't get time to raise it today, but it comes up with the SPARC
move-conditional instruction. I don't think we want to put that in the core
VM -- it is a little too specialized. But without a corresponding
conditional move instruction in the VM, it is pretty difficult to maintain a
close mapping between VM and machine code. Other architectures may have
other such instructions.
What I was going to suggest was that for a particular processor, we define
additional VM instructions that match some of the unusual opcodes on the
processor but have VM semantics otherwise, i.e., all operands are in SSA
form and typed. This means that we can re-generate core VM code from the
more specialized code any time we want (so that portability is not lost).
Typically, a static compiler like gcc would generate just the core VM, which
is relatively portable. Anyone (an offline tool, the linker, etc., or even
the static compiler itself if it chooses) can transform that into more
specialized target-specific VM code for a particular architecture. If the
linker does it, it can do it after all machine-independent optimizations.
This would be the most convenient, but not necessary.
The main benefit of lowering will be that we will be able to retain a close
mapping between VM and machine code.
--Vikram

56
cpp/llvm/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt
View File

@ -1,56 +0,0 @@
Date: Tue, 18 Sep 2001 00:38:37 -0500 (CDT)
From: Chris Lattner <sabre@nondot.org>
To: Vikram S. Adve <vadve@cs.uiuc.edu>
Subject: Idea for a simple, useful link time optimization
In C++ programs, exceptions suck, and here's why:
1. In virtually all function calls, you must assume that the function
throws an exception, unless it is defined as 'nothrow'. This means
that every function call has to have code to invoke dtors on objects
locally if one is thrown by the function. Most functions don't throw
exceptions, so this code is dead [with all the bad effects of dead
code, including icache pollution].
2. Declaring a function nothrow causes catch blocks to be added to every
call that isnot provably nothrow. This makes them very slow.
3. Extra extraneous exception edges reduce the opportunity for code
motion.
4. EH is typically implemented with large lookup tables. Ours is going to
be much smaller (than the "standard" way of doing it) to start with,
but eliminating it entirely would be nice. :)
5. It is physically impossible to correctly put (accurate, correct)
exception specifications on generic, templated code. But it is trivial
to analyze instantiations of said code.
6. Most large C++ programs throw few exceptions. Most well designed
programs only throw exceptions in specific planned portions of the
code.
Given our _planned_ model of handling exceptions, all of this would be
pretty trivial to eliminate through some pretty simplistic interprocedural
analysis. The DCE factor alone could probably be pretty significant. The
extra code motion opportunities could also be exploited though...
Additionally, this optimization can be implemented in a straight forward
conservative manner, allowing libraries to be optimized or individual
files even (if there are leaf functions visible in the translation unit
that are called).
I think it's a reasonable optimization that hasn't really been addressed
(because assembly is way too low level for this), and could have decent
payoffs... without being a overly complex optimization.
After I wrote all of that, I found this page that is talking about
basically the same thing I just wrote, except that it is translation unit
at a time, tree based approach:
http://www.ocston.org/~jls/ehopt.html
but is very useful from "expected gain" and references perspective. Note
that their compiler is apparently unable to inline functions that use
exceptions, so there numbers are pretty worthless... also our results
would (hopefully) be better because it's interprocedural...
What do you think?
-Chris

55
cpp/llvm/docs/HistoricalNotes/2002-05-12-InstListChange.txt
View File

@ -1,55 +0,0 @@
Date: Sun, 12 May 2002 17:12:53 -0500 (CDT)
From: Chris Lattner <sabre@nondot.org>
To: "Vikram S. Adve" <vadve@cs.uiuc.edu>
Subject: LLVM change
There is a fairly fundemental change that I would like to make to the LLVM
infrastructure, but I'd like to know if you see any drawbacks that I
don't...
Basically right now at the basic block level, each basic block contains an
instruction list (returned by getInstList()) that is a ValueHolder of
instructions. To iterate over instructions, we must actually iterate over
the instlist, and access the instructions through the instlist.
To add or remove an instruction from a basic block, we need to get an
iterator to an instruction, which, given just an Instruction*, requires a
linear search of the basic block the instruction is contained in... just
to insert an instruction before another instruction, or to delete an
instruction! This complicates algorithms that should be very simple (like
simple constant propagation), because they aren't actually sparse anymore,
they have to traverse basic blocks to remove constant propogated
instructions.
Additionally, adding or removing instructions to a basic block
_invalidates all iterators_ pointing into that block, which is really
irritating.
To fix these problems (and others), I would like to make the ordering of
the instructions be represented with a doubly linked list in the
instructions themselves, instead of an external data structure. This is
how many other representations do it, and frankly I can't remember why I
originally implemented it the way I did.
Long term, all of the code that depends on the nasty features in the
instruction list (which can be found by grep'ing for getInstList()) will
be changed to do nice local transformations. In the short term, I'll
change the representation, but preserve the interface (including
getInstList()) so that all of the code doesn't have to change.
Iteration over the instructions in a basic block remains the simple:
for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I) ...
But we will also support:
for (Instruction *I = BB->front(); I; I = I->getNext()) ...
After converting instructions over, I'll convert basic blocks and
functions to have a similar interface.
The only negative aspect of this change that I see is that it increases
the amount of memory consumed by one pointer per instruction. Given the
benefits, I think this is a very reasonable tradeoff.
What do you think?
-Chris

72
cpp/llvm/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt
View File

@ -1,72 +0,0 @@
Changes:
* Change the casting code to be const correct. Now, doing this is invalid:
const Value *V = ...;
Instruction *I = dyn_cast<Instruction>(V);
instead, the second line should be:
const Instruction *I = dyn_cast<Instruction>(V);
* Change the casting code to allow casting a reference value thus:
const Value &V = ...;
Instruction &I = cast<Instruction>(V);
dyn_cast does not work with references, because it must return a null pointer
on failure.
* Fundamentally change how instructions and other values are represented.
Before, every llvm container was an instance of the ValueHolder template,
instantiated for each container type. This ValueHolder was effectively a
wrapper around a vector of pointers to the sub-objects.
Now, instead of having a vector to pointers of objects, the objects are
maintained in a doubly linked list of values (ie each Instruction now has
Next & Previous fields). The containers are now instances of ilist (intrusive
linked list class), which use the next and previous fields to chain them
together. The advantage of this implementation is that iterators can be
formed directly from pointers to the LLVM value, and invalidation is much
easier to handle.
* As part of the above change, dereferencing an iterator (for example:
BasicBlock::iterator) now produces a reference to the underlying type (same
example: Instruction&) instead of a pointer to the underlying object. This
makes it much easier to write nested loops that iterator over things, changing
this:
for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI)
for (BasicBlock::iterator II = (*BI)->begin(); II != (*BI)->end(); ++II)
(*II)->dump();
into:
for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI)
for (BasicBlock::iterator II = BI->begin(); II != BI->end(); ++II)
II->dump();
which is much more natural and what users expect.
* Simplification of #include's: Before, it was necessary for a .cpp file to
include every .h file that it used. Now things are batched a little bit more
to make it easier to use. Specifically, the include graph now includes these
edges:
Module.h -> Function.h, GlobalVariable.h
Function.h -> BasicBlock.h, Argument.h
BasicBlock.h -> Instruction.h
Which means that #including Function.h is usually sufficient for getting the
lower level #includes.
* Printing out a Value* has now changed: Printing a Value* will soon print out
the address of the value instead of the contents of the Value. To print out
the contents, you must convert it to a reference with (for example)
'cout << *I' instead of 'cout << I;'. This conversion is not yet complete,
but will be eventually. In the mean time, both forms print out the contents.
* References are used much more throughout the code base. In general, if a
pointer is known to never be null, it is passed in as a reference instead of a
pointer. For example, the instruction visitor class uses references instead
of pointers, and that Pass subclasses now all receive references to Values
instead of pointers, because they may never be null.
* The Function class now has helper functions for accessing the Arguments list.
Instead of having to go through getArgumentList for simple things like
iterator over the arguments, now the a*() methods can be used to access them.

28
cpp/llvm/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt
View File

@ -1,28 +0,0 @@
Date: Mon, 20 Jan 2003 00:00:28 -0600
From: Brian R. Gaeke <gaeke@uiuc.edu>
Subject: windows vs. llvm
If you're interested, here are some of the major problems compiling LLVM
under Cygwin and/or Mingw.
1. Cygwin doesn't have <inttypes.h> or <stdint.h>, so all the INT*_MAX
symbols and standard int*_t types are off in limbo somewhere. Mingw has
<stdint.h>, but Cygwin doesn't like it.
2. Mingw doesn't have <dlfcn.h> (because Windows doesn't have it.)
3. SA_SIGINFO and friends are not around; only signal() seems to work.
4. Relink, aka ld -r, doesn't work (probably an ld bug); you need
DONT_BUILD_RELINKED. This breaks all the tools makefiles; you just need to
change them to have .a's.
5. There isn't a <values.h>.
6. There isn't a mallinfo() (or, at least, it's documented, but it doesn't seem
to link).
7. The version of Bison that cygwin (and newer Linux versions) comes with
does not like = signs in rules. Burg's gram.yc source file uses them. I think
you can just take them out.

137
cpp/llvm/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt
View File

@ -1,137 +0,0 @@
Wed Jun 25 15:13:51 CDT 2003
First-level instrumentation
---------------------------
We use opt to do Bytecode-to-bytecode instrumentation. Look at
back-edges and insert llvm_first_trigger() function call which takes
no arguments and no return value. This instrumentation is designed to
be easy to remove, for instance by writing a NOP over the function
call instruction.
Keep count of every call to llvm_first_trigger(), and maintain
counters in a map indexed by return address. If the trigger count
exceeds a threshold, we identify a hot loop and perform second-level
instrumentation on the hot loop region (the instructions between the
target of the back-edge and the branch that causes the back-edge). We
do not move code across basic-block boundaries.
Second-level instrumentation
---------------------------
We remove the first-level instrumentation by overwriting the CALL to
llvm_first_trigger() with a NOP.
The reoptimizer maintains a map between machine-code basic blocks and
LLVM BasicBlock*s. We only keep track of paths that start at the
first machine-code basic block of the hot loop region.
How do we keep track of which edges to instrument, and which edges are
exits from the hot region? 3 step process.
1) Do a DFS from the first machine-code basic block of the hot loop
region and mark reachable edges.
2) Do a DFS from the last machine-code basic block of the hot loop
region IGNORING back edges, and mark the edges which are reachable in
1) and also in 2) (i.e., must be reachable from both the start BB and
the end BB of the hot region).
3) Mark BBs which end in edges that exit the hot region; we need to
instrument these differently.
Assume that there is 1 free register. On SPARC we use %g1, which LLC
has agreed not to use. Shift a 1 into it at the beginning. At every
edge which corresponds to a conditional branch, we shift 0 for not
taken and 1 for taken into a register. This uniquely numbers the paths
through the hot region. Silently fail if we need more than 64 bits.
At the end BB we call countPath and increment the counter based on %g1
and the return address of the countPath call. We keep track of the
number of iterations and the number of paths. We only run this
version 30 or 40 times.
Find the BBs that total 90% or more of execution, and aggregate them
together to form our trace. But we do not allow more than 5 paths; if
we have more than 5 we take the ones that are executed the most. We
verify our assumption that we picked a hot back-edge in first-level
instrumentation, by making sure that the number of times we took an
exit edge from the hot trace is less than 10% of the number of
iterations.
LLC has been taught to recognize llvm_first_trigger() calls and NOT
generate saves and restores of caller-saved registers around these
calls.
Phase behavior
--------------
We turn off llvm_first_trigger() calls with NOPs, but this would hide
phase behavior from us (when some funcs/traces stop being hot and
others become hot.)
We have a SIGALRM timer that counts time for us. Every time we get a
SIGALRM we look at our priority queue of locations where we have
removed llvm_first_trigger() calls. Each location is inserted along
with a time when we will next turn instrumentation back on for that
call site. If the time has arrived for a particular call site, we pop
that off the prio. queue and turn instrumentation back on for that
call site.
Generating traces
-----------------
When we finally generate an optimized trace we first copy the code
into the trace cache. This leaves us with 3 copies of the code: the
original code, the instrumented code, and the optimized trace. The
optimized trace does not have instrumentation. The original code and
the instrumented code are modified to have a branch to the trace
cache, where the optimized traces are kept.
We copy the code from the original to the instrumentation version
by tracing the LLVM-to-Machine code basic block map and then copying
each machine code basic block we think is in the hot region into the
trace cache. Then we instrument that code. The process is similar for
generating the final optimized trace; we copy the same basic blocks
because we might need to put in fixup code for exit BBs.
LLVM basic blocks are not typically used in the Reoptimizer except
for the mapping information.
We are restricted to using single instructions to branch between the
original code, trace, and instrumented code. So we have to keep the
code copies in memory near the original code (they can't be far enough
away that a single pc-relative branch would not work.) Malloc() or
data region space is too far away. this impacts the design of the
trace cache.
We use a dummy function that is full of a bunch of for loops which we
overwrite with trace-cache code. The trace manager keeps track of
whether or not we have enough space in the trace cache, etc.
The trace insertion routine takes an original start address, a vector
of machine instructions representing the trace, index of branches and
their corresponding absolute targets, and index of calls and their
corresponding absolute targets.
The trace insertion routine is responsible for inserting branches from
the beginning of the original code to the beginning of the optimized
trace. This is because at some point the trace cache may run out of
space and it may have to evict a trace, at which point the branch to
the trace would also have to be removed. It uses a round-robin
replacement policy; we have found that this is almost as good as LRU
and better than random (especially because of problems fitting the new
trace in.)
We cannot deal with discontiguous trace cache areas. The trace cache
is supposed to be cache-line-aligned, but it is not page-aligned.
We generate instrumentation traces and optimized traces into separate
trace caches. We keep the instrumented code around because you don't
want to delete a trace when you still might have to return to it
(i.e., return from a llvm_first_trigger() or countPath() call.)

110
cpp/llvm/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt
View File

@ -1,110 +0,0 @@
Thu Jun 26 14:43:04 CDT 2003
Information about BinInterface
------------------------------
Take in a set of instructions with some particular register
allocation. It allows you to add, modify, or delete some instructions,
in SSA form (kind of like LLVM's MachineInstrs.) Then re-allocate
registers. It assumes that the transformations you are doing are safe.
It does not update the mapping information or the LLVM representation
for the modified trace (so it would not, for instance, support
multiple optimization passes; passes have to be aware of and update
manually the mapping information.)
The way you use it is you take the original code and provide it to
BinInterface; then you do optimizations to it, then you put it in the
trace cache.
The BinInterface tries to find live-outs for traces so that it can do
register allocation on just the trace, and stitch the trace back into
the original code. It has to preserve the live-ins and live-outs when
it does its register allocation. (On exits from the trace we have
epilogues that copy live-outs back into the right registers, but
live-ins have to be in the right registers.)
Limitations of BinInterface
---------------------------
It does copy insertions for PHIs, which it infers from the machine
code. The mapping info inserted by LLC is not sufficient to determine
the PHIs.
It does not handle integer or floating-point condition codes and it
does not handle floating-point register allocation.
It is not aggressively able to use lots of registers.
There is a problem with alloca: we cannot find our spill space for
spilling registers, normally allocated on the stack, if the trace
follows an alloca(). What might be an acceptable solution would be to
disable trace generation on functions that have variable-sized
alloca()s. Variable-sized allocas in the trace would also probably
screw things up.
Because of the FP and alloca limitations, the BinInterface is
completely disabled right now.
Demo
----
This is a demo of the Ball & Larus version that does NOT use 2-level
profiling.
1. Compile program with llvm-gcc.
2. Run opt -lowerswitch -paths -emitfuncs on the bytecode.
-lowerswitch change switch statements to branches
-paths Ball & Larus path-profiling algorithm
-emitfuncs emit the table of functions
3. Run llc to generate SPARC assembly code for the result of step 2.
4. Use g++ to link the (instrumented) assembly code.
We use a script to do all this:
------------------------------------------------------------------------------
#!/bin/sh
llvm-gcc $1.c -o $1
opt -lowerswitch -paths -emitfuncs $1.bc > $1.run.bc
llc -f $1.run.bc
LIBS=$HOME/llvm_sparc/lib/Debug
GXX=/usr/dcs/software/evaluation/bin/g++
$GXX -g -L $LIBS $1.run.s -o $1.run.llc \
$LIBS/tracecache.o \
$LIBS/mapinfo.o \
$LIBS/trigger.o \
$LIBS/profpaths.o \
$LIBS/bininterface.o \
$LIBS/support.o \
$LIBS/vmcore.o \
$LIBS/transformutils.o \
$LIBS/bcreader.o \
-lscalaropts -lscalaropts -lanalysis \
-lmalloc -lcpc -lm -ldl
------------------------------------------------------------------------------
5. Run the resulting binary. You will see output from BinInterface
(described below) intermixed with the output from the program.
Output from BinInterface
------------------------
BinInterface's debugging code prints out the following stuff in order:
1. Initial code provided to BinInterface with original register
allocation.
2. Section 0 is the trace prolog, consisting mainly of live-ins and
register saves which will be restored in epilogs.
3. Section 1 is the trace itself, in SSA form used by BinInterface,
along with the PHIs that are inserted.
PHIs are followed by the copies that implement them.
Each branch (i.e., out of the trace) is annotated with the
section number that represents the epilog it branches to.
4. All the other sections starting with Section 2 are trace epilogs.
Every branch from the trace has to go to some epilog.
5. After the last section is the register allocation output.

178
cpp/llvm/docs/HistoricalNotes/2007-OriginalClangReadme.txt
View File

@ -1,178 +0,0 @@
//===----------------------------------------------------------------------===//
// C Language Family Front-end
//===----------------------------------------------------------------------===//
Chris Lattner
I. Introduction:
clang: noun
1. A loud, resonant, metallic sound.
2. The strident call of a crane or goose.
3. C-language family front-end toolkit.
The world needs better compiler tools, tools which are built as libraries. This
design point allows reuse of the tools in new and novel ways. However, building
the tools as libraries isn't enough: they must have clean APIs, be as
decoupled from each other as possible, and be easy to modify/extend. This
requires clean layering, decent design, and avoiding tying the libraries to a
specific use. Oh yeah, did I mention that we want the resultant libraries to
be as fast as possible? :)
This front-end is built as a component of the LLVM toolkit that can be used
with the LLVM backend or independently of it. In this spirit, the API has been
carefully designed as the following components:
libsupport - Basic support library, reused from LLVM.
libsystem - System abstraction library, reused from LLVM.
libbasic - Diagnostics, SourceLocations, SourceBuffer abstraction,
file system caching for input source files. This depends on
libsupport and libsystem.
libast - Provides classes to represent the C AST, the C type system,
builtin functions, and various helpers for analyzing and
manipulating the AST (visitors, pretty printers, etc). This
library depends on libbasic.
liblex - C/C++/ObjC lexing and preprocessing, identifier hash table,
pragma handling, tokens, and macros. This depends on libbasic.
libparse - C (for now) parsing and local semantic analysis. This library
invokes coarse-grained 'Actions' provided by the client to do
stuff (e.g. libsema builds ASTs). This depends on liblex.
libsema - Provides a set of parser actions to build a standardized AST
for programs. AST's are 'streamed' out a top-level declaration
at a time, allowing clients to use decl-at-a-time processing,
build up entire translation units, or even build 'whole
program' ASTs depending on how they use the APIs. This depends
on libast and libparse.
librewrite - Fast, scalable rewriting of source code. This operates on
the raw syntactic text of source code, allowing a client
to insert and delete text in very large source files using
the same source location information embedded in ASTs. This
is intended to be a low-level API that is useful for
higher-level clients and libraries such as code refactoring.
libanalysis - Source-level dataflow analysis useful for performing analyses
such as computing live variables. It also includes a
path-sensitive "graph-reachability" engine for writing
analyses that reason about different possible paths of
execution through source code. This is currently being
employed to write a set of checks for finding bugs in software.
libcodegen - Lower the AST to LLVM IR for optimization & codegen. Depends
on libast.
clang - An example driver, client of the libraries at various levels.
This depends on all these libraries, and on LLVM VMCore.
This front-end has been intentionally built as a DAG of libraries, making it
easy to reuse individual parts or replace pieces if desired. For example, to
build a preprocessor, you take the Basic and Lexer libraries. If you want an
indexer, you take those plus the Parser library and provide some actions for
indexing. If you want a refactoring, static analysis, or source-to-source
compiler tool, it makes sense to take those plus the AST building and semantic
analyzer library. Finally, if you want to use this with the LLVM backend,
you'd take these components plus the AST to LLVM lowering code.
In the future I hope this toolkit will grow to include new and interesting
components, including a C++ front-end, ObjC support, and a whole lot of other
things.
Finally, it should be pointed out that the goal here is to build something that
is high-quality and industrial-strength: all the obnoxious features of the C
family must be correctly supported (trigraphs, preprocessor arcana, K&R-style
prototypes, GCC/MS extensions, etc). It cannot be used if it is not 'real'.
II. Usage of clang driver:
* Basic Command-Line Options:
- Help: clang --help
- Standard GCC options accepted: -E, -I*, -i*, -pedantic, -std=c90, etc.
- To make diagnostics more gcc-like: -fno-caret-diagnostics -fno-show-column
- Enable metric printing: -stats
* -fsyntax-only is currently the default mode.
* -E mode works the same way as GCC.
* -Eonly mode does all preprocessing, but does not print the output,
useful for timing the preprocessor.
* -fsyntax-only is currently partially implemented, lacking some
semantic analysis (some errors and warnings are not produced).
* -parse-noop parses code without building an AST. This is useful
for timing the cost of the parser without including AST building
time.
* -parse-ast builds ASTs, but doesn't print them. This is most
useful for timing AST building vs -parse-noop.
* -parse-ast-print pretty prints most expression and statements nodes.
* -parse-ast-check checks that diagnostic messages that are expected
are reported and that those which are reported are expected.
* -dump-cfg builds ASTs and then CFGs. CFGs are then pretty-printed.
* -view-cfg builds ASTs and then CFGs. CFGs are then visualized by
invoking Graphviz.
For more information on getting Graphviz to work with clang/LLVM,
see: http://llvm.org/docs/ProgrammersManual.html#ViewGraph
III. Current advantages over GCC:
* Column numbers are fully tracked (no 256 col limit, no GCC-style pruning).
* All diagnostics have column numbers, includes 'caret diagnostics', and they
highlight regions of interesting code (e.g. the LHS and RHS of a binop).
* Full diagnostic customization by client (can format diagnostics however they
like, e.g. in an IDE or refactoring tool) through DiagnosticClient interface.
* Built as a framework, can be reused by multiple tools.
* All languages supported linked into same library (no cc1,cc1obj, ...).
* mmap's code in read-only, does not dirty the pages like GCC (mem footprint).
* LLVM License, can be linked into non-GPL projects.
* Full diagnostic control, per diagnostic. Diagnostics are identified by ID.
* Significantly faster than GCC at semantic analysis, parsing, preprocessing
and lexing.
* Defers exposing platform-specific stuff to as late as possible, tracks use of
platform-specific features (e.g. #ifdef PPC) to allow 'portable bytecodes'.
* The lexer doesn't rely on the "lexer hack": it has no notion of scope and
does not categorize identifiers as types or variables -- this is up to the
parser to decide.
Potential Future Features:
* Fine grained diag control within the source (#pragma enable/disable warning).
* Better token tracking within macros? (Token came from this line, which is
a macro argument instantiated here, recursively instantiated here).
* Fast #import with a module system.
* Dependency tracking: change to header file doesn't recompile every function
that texually depends on it: recompile only those functions that need it.
This is aka 'incremental parsing'.
IV. Missing Functionality / Improvements
Lexer:
* Source character mapping. GCC supports ASCII and UTF-8.
See GCC options: -ftarget-charset and -ftarget-wide-charset.
* Universal character support. Experimental in GCC, enabled with
-fextended-identifiers.
* -fpreprocessed mode.
Preprocessor:
* #assert/#unassert
* MSExtension: "L#param" stringizes to a wide string literal.
* Add support for -M*
Traditional Preprocessor:
* Currently, we have none. :)

142
cpp/llvm/docs/HowToAddABuilder.html
View File

@ -1,142 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>
How To Add Your Build Configuration To LLVM Buildbot Infrastructure
</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>How To Add Your Build Configuration To LLVM Buildbot Infrastructure</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#steps">Steps To Add Builder To LLVM Buildbot</a></li>
</ol>
<div class="doc_author">
<p>Written by <a href="mailto:gkistanova@gmail.com">Galina Kistanova</a></p>
</div>
<!-- *********************************************************************** -->
<h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** -->
<div>
<p>This document contains information about adding a build configuration and
buildslave to private slave builder to LLVM Buildbot Infrastructure
<a href="http://lab.llvm.org:8011">http://lab.llvm.org:8011</a></p>
</div>
<!-- *********************************************************************** -->
<h2><a name="steps">Steps To Add Builder To LLVM Buildbot</a></h2>
<!-- *********************************************************************** -->
<div>
<p>Volunteers can provide their build machines to work as build slaves to
public LLVM Buildbot.</p>
<p>Here are the steps you can follow to do so:</p>
<ol>
<li><p>Check the existing build configurations to make sure the one you are
interested in is not covered yet or gets built on your computer much
faster than on the existing one. We prefer faster builds so developers
will get feedback sooner after changes get committed.</p></li>
<li><p>The computer you will be registering with the LLVM buildbot
infrastructure should have all dependencies installed and you can
actually build your configuration successfully. Please check what degree
of parallelism (-j param) would give the fastest build.
You can build multiple configurations on one computer.</p></li>
<li><p>Install buildslave (currently we are using buildbot version 0.8.5).
Depending on the platform, buildslave could be available to download and
install with your packet manager, or you can download it directly from
<a href="http://trac.buildbot.net">http://trac.buildbot.net</a> and
install it manually.</p></li>
<li><p>Create a designated user account, your buildslave will be running
under, and set appropriate permissions.</p></li>
<li><p>Choose the buildslave root directory (all builds will be placed under
it), buildslave access name and password the build master will be using
to authenticate your buildslave.</p></li>
<li><p>Create a buildslave in context of that buildslave account.
Point it to the <b>lab.llvm.org</b> port <b>9990</b> (see
<a href="http://buildbot.net/buildbot/docs/current/full.html#creating-a-slave">
Buildbot documentation, Creating a slave</a>
for more details) by running the following command:</p>
<div class="doc_code">
<pre>
$ buildslave create-slave <i>buildslave-root-directory</i> \
lab.llvm.org:9990 \
<i>buildslave-access-name buildslave-access-password</i>
</pre>
</div></li>
<li><p>Fill the buildslave description and admin name/e-mail.
Here is an example of the buildslave description:</p>
<div class="doc_code">
<pre>
Windows 7 x64
Core i7 (2.66GHz), 16GB of RAM
g++.exe (TDM-1 mingw32) 4.4.0
GNU Binutils 2.19.1
cmake version 2.8.4
Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
</pre>
</div></li>
<li><p>Make sure you can actually start the buildslave successfully. Then set
up your buildslave to start automatically at the start up time.
See the buildbot documentation for help.
You may want to restart your computer to see if it works.</p></li>
<li><p>Send a patch which adds your build slave and your builder to zorg.</p>
<ul>
<li>slaves are added to
<tt>buildbot/osuosl/master/config/slaves.py</tt></li>
<li>builders are added to
<tt>buildbot/osuosl/master/config/builders.py</tt></li>
</ul></li>
<li><p>Send the buildslave access name and the access password directly
to <a href="mailto:gkistanova@gmail.com">Galina Kistanova</a>, and wait
till she will let you know that your changes are applied and buildmaster
is reconfigured.</p>
<li><p>Check the status of your buildslave on the
<a href="http://lab.llvm.org:8011/waterfall">Waterfall Display</a>
to make sure it is connected, and
<a href="http://lab.llvm.org:8011/buildslaves/your-buildslave-name">
http://lab.llvm.org:8011/buildslaves/&lt;your-buildslave-name&gt;</a>
to see if administrator contact and slave information are correct.</p>
</li>
<li><p>Wait for the first build to succeed and enjoy.</p></li>
</ol>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date: 2011-10-31 12:50:0 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

581
cpp/llvm/docs/HowToReleaseLLVM.html
View File

@ -1,581 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>How To Release LLVM To The Public</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>How To Release LLVM To The Public</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#criteria">Qualification Criteria</a></li>
<li><a href="#introduction">Release Timeline</a></li>
<li><a href="#process">Release Process</a></li>
</ol>
<div class="doc_author">
<p>Written by <a href="mailto:tonic@nondot.org">Tanya Lattner</a>,
<a href="mailto:rspencer@x10sys.com">Reid Spencer</a>,
<a href="mailto:criswell@cs.uiuc.edu">John Criswell</a>, &amp;
<a href="mailto:wendling@apple.com">Bill Wendling</a>
</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** -->
<div>
<p>This document contains information about successfully releasing LLVM &mdash;
including subprojects: e.g., <tt>clang</tt> and <tt>dragonegg</tt> &mdash; to
the public. It is the Release Manager's responsibility to ensure that a high
quality build of LLVM is released.</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="process">Release Timeline</a></h2>
<!-- *********************************************************************** -->
<div>
<p>LLVM is released on a time based schedule &mdash; roughly every 6 months. We
do not normally have dot releases because of the nature of LLVM's incremental
development philosophy. That said, the only thing preventing dot releases for
critical bug fixes from happening is a lack of resources &mdash; testers,
machines, time, etc. And, because of the high quality we desire for LLVM
releases, we cannot allow for a truncated form of release qualification.</p>
<p>The release process is roughly as follows:</p>
<ul>
<li><p>Set code freeze and branch creation date for 6 months after last code
freeze date. Announce release schedule to the LLVM community and update
the website.</p></li>
<li><p>Create release branch and begin release process.</p></li>
<li><p>Send out release candidate sources for first round of testing. Testing
lasts 7-10 days. During the first round of testing, any regressions found
should be fixed. Patches are merged from mainline into the release
branch. Also, all features need to be completed during this time. Any
features not completed at the end of the first round of testing will be
removed or disabled for the release.</p></li>
<li><p>Generate and send out the second release candidate sources. Only
<em>critial</em> bugs found during this testing phase will be fixed. Any
bugs introduced by merged patches will be fixed. If so a third round of
testing is needed.</p></li>
<li><p>The release notes are updated.</p></li>
<li><p>Finally, release!</p></li>
</ul>
</div>
<!-- *********************************************************************** -->
<h2><a name="process">Release Process</a></h2>
<!-- *********************************************************************** -->
<div>
<ol>
<li><a href="#release-admin">Release Administrative Tasks</a>
<ol>
<li><a href="#branch">Create Release Branch</a></li>
<li><a href="#verchanges">Update Version Numbers</a></li>
</ol>
</li>
<li><a href="#release-build">Building the Release</a>
<ol>
<li><a href="#dist">Build the LLVM Source Distributions</a></li>
<li><a href="#build">Build LLVM</a></li>
<li><a href="#clangbin">Build the Clang Binary Distribution</a></li>
<li><a href="#target-build">Target Specific Build Details</a></li>
</ol>
</li>
<li><a href="#release-qualify">Release Qualification Criteria</a>
<ol>
<li><a href="#llvm-qualify">Qualify LLVM</a></li>
<li><a href="#clang-qualify">Qualify Clang</a></li>
<li><a href="#targets">Specific Target Qualification Details</a></li>
</ol>
</li>
<li><a href="#commTest">Community Testing</a></li>
<li><a href="#release-patch">Release Patch Rules</a></li>
<li><a href="#release-final">Release final tasks</a>
<ol>
<li><a href="#updocs">Update Documentation</a></li>
<li><a href="#tag">Tag the LLVM Final Release</a></li>
<li><a href="#updemo">Update the LLVM Demo Page</a></li>
<li><a href="#webupdates">Update the LLVM Website</a></li>
<li><a href="#announce">Announce the Release</a></li>
</ol>
</li>
</ol>
<!-- ======================================================================= -->
<h3><a name="release-admin">Release Administrative Tasks</a></h3>
<div>
<p>This section describes a few administrative tasks that need to be done for
the release process to begin. Specifically, it involves:</p>
<ul>
<li>Creating the release branch,</li>
<li>Setting version numbers, and</li>
<li>Tagging release candidates for the release team to begin testing</li>
</ul>
<!-- ======================================================================= -->
<h4><a name="branch">Create Release Branch</a></h4>
<div>
<p>Branch the Subversion trunk using the following procedure:</p>
<ol>
<li><p>Remind developers that the release branching is imminent and to refrain
from committing patches that might break the build. E.g., new features,
large patches for works in progress, an overhaul of the type system, an
exciting new TableGen feature, etc.</p></li>
<li><p>Verify that the current Subversion trunk is in decent shape by
examining nightly tester and buildbot results.</p></li>
<li><p>Create the release branch for <tt>llvm</tt>, <tt>clang</tt>,
the <tt>test-suite</tt>, and <tt>dragonegg</tt> from the last known good
revision. The branch's name is <tt>release_<i>XY</i></tt>,
where <tt>X</tt> is the major and <tt>Y</tt> the minor release
numbers. The branches should be created using the following commands:</p>
<div class="doc_code">
<pre>
$ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i>
</pre>
</div></li>
<li><p>Advise developers that they may now check their patches into the
Subversion tree again.</p></li>
<li><p>The Release Manager should switch to the release branch, because all
changes to the release will now be done in the branch. The easiest way to
do this is to grab a working copy using the following commands:</p>
<div class="doc_code">
<pre>
$ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> llvm-<i>X.Y</i>
$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-<i>X.Y</i>
$ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> dragonegg-<i>X.Y</i>
$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> test-suite-<i>X.Y</i>
</pre>
</div></li>
</ol>
</div>
<!-- ======================================================================= -->
<h4><a name="verchanges">Update LLVM Version</a></h4>
<div>
<p>After creating the LLVM release branch, update the release branches'
<tt>autoconf</tt> and <tt>configure.ac</tt> versions from '<tt>X.Ysvn</tt>'
to '<tt>X.Y</tt>'. Update it on mainline as well to be the next version
('<tt>X.Y+1svn</tt>'). Regenerate the configure scripts for both
<tt>llvm</tt> and the <tt>test-suite</tt>.</p>
<p>In addition, the version numbers of all the Bugzilla components must be
updated for the next release.</p>
</div>
<!-- ======================================================================= -->
<h4><a name="dist">Build the LLVM Release Candidates</a></h4>
<div>
<p>Create release candidates for <tt>llvm</tt>, <tt>clang</tt>,
<tt>dragonegg</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch
with the respective release candidate number. For instance, to
create <b>Release Candidate 1</b> you would issue the following commands:</p>
<div class="doc_code">
<pre>
$ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> \
https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1
$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> \
https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1
$ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> \
https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1
$ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>
$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> \
https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1
</pre>
</div>
<p>Similarly, <b>Release Candidate 2</b> would be named <tt>RC2</tt> and so
on. This keeps a permanent copy of the release candidate around for people to
export and build as they wish. The final released sources will be tagged in
the <tt>RELEASE_<i>XY</i></tt> directory as <tt>Final</tt>
(c.f. <a href="#tag">Tag the LLVM Final Release</a>).</p>
<p>The Release Manager may supply pre-packaged source tarballs for users. This
can be done with the following commands:</p>
<div class="doc_code">
<pre>
$ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1 llvm-<i>X.Y</i>rc1
$ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1 clang-<i>X.Y</i>rc1
$ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1 dragonegg-<i>X.Y</i>rc1
$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1 llvm-test-<i>X.Y</i>rc1
$ tar -cvf - llvm-<i>X.Y</i>rc1 | gzip &gt; llvm-<i>X.Y</i>rc1.src.tar.gz
$ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.gz
$ tar -cvf - dragonegg-<i>X.Y</i>rc1 | gzip &gt; dragonegg-<i>X.Y</i>rc1.src.tar.gz
$ tar -cvf - llvm-test-<i>X.Y</i>rc1 | gzip &gt; llvm-test-<i>X.Y</i>rc1.src.tar.gz
</pre>
</div>
</div>
</div>
<!-- ======================================================================= -->
<h3><a name="release-build">Building the Release</a></h3>
<div>
<p>The builds of <tt>llvm</tt>, <tt>clang</tt>, and <tt>dragonegg</tt>
<em>must</em> be free of errors and warnings in Debug, Release+Asserts, and
Release builds. If all builds are clean, then the release passes Build
Qualification.</p>
<p>The <tt>make</tt> options for building the different modes:</p>
<table>
<tr><th>Mode</th><th>Options</th></tr>
<tr align="left"><td>Debug</td><td><tt>ENABLE_OPTIMIZED=0</tt></td></tr>
<tr align="left"><td>Release+Asserts</td><td><tt>ENABLE_OPTIMIZED=1</tt></td></tr>
<tr align="left"><td>Release</td><td><tt>ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt></td></tr>
</table>
<!-- ======================================================================= -->
<h4><a name="build">Build LLVM</a></h4>
<div>
<p>Build <tt>Debug</tt>, <tt>Release+Asserts</tt>, and <tt>Release</tt> versions
of <tt>llvm</tt> on all supported platforms. Directions to build
<tt>llvm</tt> are <a href="GettingStarted.html#quickstart">here</a>.</p>
</div>
<!-- ======================================================================= -->
<h4><a name="clangbin">Build Clang Binary Distribution</a></h4>
<div>
<p>Creating the <tt>clang</tt> binary distribution
(Debug/Release+Asserts/Release) requires performing the following steps for
each supported platform:</p>
<ol>
<li>Build clang according to the directions
<a href="http://clang.llvm.org/get_started.html">here</a>.</li>
<li>Build both a Debug and Release version of clang. The binary will be the
Release build.</lI>
<li>Package <tt>clang</tt> (details to follow).</li>
</ol>
</div>
<!-- ======================================================================= -->
<h4><a name="target-build">Target Specific Build Details</a></h4>
<div>
<p>The table below specifies which compilers are used for each Arch/OS
combination when qualifying the build of <tt>llvm</tt>, <tt>clang</tt>,
and <tt>dragonegg</tt>.</p>
<table>
<tr><th>Architecture</th> <th>OS</th> <th>compiler</th></tr>
<tr><td>x86-32</td> <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr>
<tr><td>x86-32</td> <td>Linux</td> <td>gcc 4.2.X, gcc 4.3.X</td></tr>
<tr><td>x86-32</td> <td>FreeBSD</td> <td>gcc 4.2.X</td></tr>
<tr><td>x86-32</td> <td>mingw</td> <td>gcc 3.4.5</td></tr>
<tr><td>x86-64</td> <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr>
<tr><td>x86-64</td> <td>Linux</td> <td>gcc 4.2.X, gcc 4.3.X</td></tr>
<tr><td>x86-64</td> <td>FreeBSD</td> <td>gcc 4.2.X</td></tr>
</table>
</div>
</div>
<!-- ======================================================================= -->
<h3><a name="release-qualify">Building the Release</a></h3>
<div>
<p>A release is qualified when it has no regressions from the previous release
(or baseline). Regressions are related to correctness first and performance
second. (We may tolerate some minor performance regressions if they are
deemed necessary for the general quality of the compiler.)</p>
<p><b>Regressions are new failures in the set of tests that are used to qualify
each product and only include things on the list. Every release will have
some bugs in it. It is the reality of developing a complex piece of
software. We need a very concrete and definitive release criteria that
ensures we have monotonically improving quality on some metric. The metric we
use is described below. This doesn't mean that we don't care about other
criteria, but these are the criteria which we found to be most important and
which must be satisfied before a release can go out</b></p>
<!-- ======================================================================= -->
<h4><a name="llvm-qualify">Qualify LLVM</a></h4>
<div>
<p>LLVM is qualified when it has a clean test run without a front-end. And it
has no regressions when using either <tt>clang</tt> or <tt>dragonegg</tt>
with the <tt>test-suite</tt> from the previous release.</p>
</div>
<!-- ======================================================================= -->
<h4><a name="clang-qualify">Qualify Clang</a></h4>
<div>
<p><tt>Clang</tt> is qualified when front-end specific tests in the
<tt>llvm</tt> dejagnu test suite all pass, clang's own test suite passes
cleanly, and there are no regressions in the <tt>test-suite</tt>.</p>
</div>
<!-- ======================================================================= -->
<h4><a name="targets">Specific Target Qualification Details</a></h4>
<div>
<table>
<tr><th>Architecture</th> <th>OS</th> <th>clang baseline</th> <th>tests</th></tr>
<tr><td>x86-32</td> <td>Linux</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
<tr><td>x86-32</td> <td>FreeBSD</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite</td></tr>
<tr><td>x86-32</td> <td>mingw</td> <td>none</td> <td>QT</td></tr>
<tr><td>x86-64</td> <td>Mac OS 10.X</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
<tr><td>x86-64</td> <td>Linux</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
<tr><td>x86-64</td> <td>FreeBSD</td> <td>last release</td> <td>llvm dejagnu, clang tests, test-suite</td></tr>
</table>
</div>
</div>
<!-- ======================================================================= -->
<h3><a name="commTest">Community Testing</a></h3>
<div>
<p>Once all testing has been completed and appropriate bugs filed, the release
candidate tarballs are put on the website and the LLVM community is
notified. Ask that all LLVM developers test the release in 2 ways:</p>
<ol>
<li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the
appropriate <tt>clang</tt> binary. Build LLVM. Run <tt>make check</tt> and
the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li>
<li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the
<tt>clang</tt> sources. Compile everything. Run <tt>make check</tt> and
the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li>
</ol>
<p>Ask LLVM developers to submit the test suite report and <tt>make check</tt>
results to the list. Verify that there are no regressions from the previous
release. The results are not used to qualify a release, but to spot other
potential problems. For unsupported targets, verify that <tt>make check</tt>
is at least clean.</p>
<p>During the first round of testing, all regressions must be fixed before the
second release candidate is tagged.</p>
<p>If this is the second round of testing, the testing is only to ensure that
bug fixes previously merged in have not created new major problems. <i>This
is not the time to solve additional and unrelated bugs!</i> If no patches are
merged in, the release is determined to be ready and the release manager may
move onto the next stage.</p>
</div>
<!-- ======================================================================= -->
<h3><a name="release-patch">Release Patch Rules</a></h3>
<div>
<p>Below are the rules regarding patching the release branch:</p>
<ol>
<li><p>Patches applied to the release branch may only be applied by the
release manager.</p></li>
<li><p>During the first round of testing, patches that fix regressions or that
are small and relatively risk free (verified by the appropriate code
owner) are applied to the branch. Code owners are asked to be very
conservative in approving patches for the branch. We reserve the right to
reject any patch that does not fix a regression as previously
defined.</p></li>
<li><p>During the remaining rounds of testing, only patches that fix critical
regressions may be applied.</p></li>
</ol>
</div>
<!-- ======================================================================= -->
<h3><a name="release-final">Release Final Tasks</a></h3>
<div>
<p>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.</p>
<!-- ======================================================================= -->
<h4><a name="updocs">Update Documentation</a></h4>
<div>
<p>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,
and changes in the list of supported platforms. The "Getting Started Guide"
should be updated to reflect the new release version number tag avaiable from
Subversion and changes in basic system requirements. Merge both changes from
mainline into the release branch.</p>
</div>
<!-- ======================================================================= -->
<h4><a name="tag">Tag the LLVM Final Release</a></h4>
<div>
<p>Tag the final release sources using the following procedure:</p>
<div class="doc_code">
<pre>
$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/Final
$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/Final
$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/Final
$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/Final
</pre>
</div>
</div>
</div>
<!-- ======================================================================= -->
<h3><a name="updemo">Update the LLVM Demo Page</a></h3>
<div>
<p>The LLVM demo page must be updated to use the new release. This consists of
using the new <tt>clang</tt> binary and building LLVM.</p>
<!-- ======================================================================= -->
<h4><a name="webupdates">Update the LLVM Website</a></h4>
<div>
<p>The website must be updated before the release announcement is sent out. Here
is what to do:</p>
<ol>
<li>Check out the <tt>www</tt> module from Subversion.</li>
<li>Create a new subdirectory <tt>X.Y</tt> in the releases directory.</li>
<li>Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>clang</tt> source,
<tt>clang binaries</tt>, <tt>dragonegg</tt> source, and <tt>dragonegg</tt>
binaries in this new directory.</li>
<li>Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt> files
into this new directory. The docs should be built with
<tt>BUILD_FOR_WEBSITE=1</tt>.</li>
<li>Commit the <tt>index.html</tt> to the <tt>release/X.Y</tt> directory to
redirect (use from previous release.</li>
<li>Update the <tt>releases/download.html</tt> file with the new release.</li>
<li>Update the <tt>releases/index.html</tt> with the new release and link to
release documentation.</li>
<li>Finally, update the main page (<tt>index.html</tt> and sidebar) to point
to the new release and release announcement. Make sure this all gets
committed back into Subversion.</li>
</ol>
</div>
<!-- ======================================================================= -->
<h4><a name="announce">Announce the Release</a></h4>
<div>
<p>Have Chris send out the release announcement when everything is finished.</p>
</div>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

348
cpp/llvm/docs/HowToSubmitABug.html
View File

@ -1,348 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>How to submit an LLVM bug report</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>
How to submit an LLVM bug report
</h1>
<table class="layout" style="width: 90%" >
<tr class="layout">
<td class="left">
<ol>
<li><a href="#introduction">Introduction - Got bugs?</a></li>
<li><a href="#crashers">Crashing Bugs</a>
<ul>
<li><a href="#front-end">Front-end bugs</a>
<li><a href="#ct_optimizer">Compile-time optimization bugs</a>
<li><a href="#ct_codegen">Code generator bugs</a>
</ul></li>
<li><a href="#miscompilations">Miscompilations</a></li>
<li><a href="#codegen">Incorrect code generation (JIT and LLC)</a></li>
</ol>
<div class="doc_author">
<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
<a href="http://misha.brukman.net">Misha Brukman</a></p>
</div>
</td>
<td class="right">
<img src="img/Debugging.gif" alt="Debugging" width="444" height="314">
</td>
</tr>
</table>
<!-- *********************************************************************** -->
<h2>
<a name="introduction">Introduction - Got bugs?</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
getting it fixed quickly.</p>
<p>Basically you have to do two things at a minimum. First, decide whether the
bug <a href="#crashers">crashes the compiler</a> (or an LLVM pass), or if the
compiler is <a href="#miscompilations">miscompiling</a> the program (i.e., the
compiler successfully produces an executable, but it doesn't run right). Based
on
what type of bug it is, follow the instructions in the linked section to narrow
down the bug so that the person who fixes it will be able to find the problem
more easily.</p>
<p>Once you have a reduced test-case, go to <a
href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking
System</a> and fill out the form with the necessary details (note that you don't
need to pick a category, just use the "new-bugs" category if you're not sure).
The bug description should contain the following
information:</p>
<ul>
<li>All information necessary to reproduce the problem.</li>
<li>The reduced test-case that triggers the bug.</li>
<li>The location where you obtained LLVM (if not from our Subversion
repository).</li>
</ul>
<p>Thanks for helping us make LLVM better!</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="crashers">Crashing Bugs</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>More often than not, bugs in the compiler cause it to crash&mdash;often due
to an assertion failure of some sort. The most important
piece of the puzzle is to figure out if it is crashing in the GCC front-end
or if it is one of the LLVM libraries (e.g. the optimizer or code generator)
that has problems.</p>
<p>To figure out which component is crashing (the front-end,
optimizer or code generator), run the
<tt><b>llvm-gcc</b></tt> command line as you were when the crash occurred, but
with the following extra command line options:</p>
<ul>
<li><tt><b>-O0 -emit-llvm</b></tt>: If <tt>llvm-gcc</tt> still crashes when
passed these options (which disable the optimizer and code generator), then
the crash is in the front-end. Jump ahead to the section on <a
href="#front-end">front-end bugs</a>.</li>
<li><tt><b>-emit-llvm</b></tt>: If <tt>llvm-gcc</tt> crashes with this option
(which disables the code generator), you found an optimizer bug. Jump ahead
to <a href="#ct_optimizer"> compile-time optimization bugs</a>.</li>
<li>Otherwise, you have a code generator crash. Jump ahead to <a
href="#ct_codegen">code generator bugs</a>.</li>
</ul>
<!-- ======================================================================= -->
<h3>
<a name="front-end">Front-end bugs</a>
</h3>
<div>
<p>If the problem is in the front-end, you should re-run the same
<tt>llvm-gcc</tt> command that resulted in the crash, but add the
<tt>-save-temps</tt> option. The compiler will crash again, but it will leave
behind a <tt><i>foo</i>.i</tt> file (containing preprocessed C source code) and
possibly <tt><i>foo</i>.s</tt> for each
compiled <tt><i>foo</i>.c</tt> file. Send us the <tt><i>foo</i>.i</tt> file,
along with the options you passed to llvm-gcc, and a brief description of the
error it caused.</p>
<p>The <a href="http://delta.tigris.org/">delta</a> tool helps to reduce the
preprocessed file down to the smallest amount of code that still replicates the
problem. You're encouraged to use delta to reduce the code to make the
developers' lives easier. <a
href="http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction">This website</a>
has instructions on the best way to use delta.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="ct_optimizer">Compile-time optimization bugs</a>
</h3>
<div>
<p>If you find that a bug crashes in the optimizer, compile your test-case to a
<tt>.bc</tt> file by passing "<tt><b>-emit-llvm -O0 -c -o foo.bc</b></tt>".
Then run:</p>
<div class="doc_code">
<p><tt><b>opt</b> -std-compile-opts -debug-pass=Arguments foo.bc
-disable-output</tt></p>
</div>
<p>This command should do two things: it should print out a list of passes, and
then it should crash in the same way as llvm-gcc. If it doesn't crash, please
follow the instructions for a <a href="#front-end">front-end bug</a>.</p>
<p>If this does crash, then you should be able to debug this with the following
bugpoint command:</p>
<div class="doc_code">
<p><tt><b>bugpoint</b> foo.bc &lt;list of passes printed by
<b>opt</b>&gt;</tt></p>
</div>
<p>Please run this, then file a bug with the instructions and reduced .bc files
that bugpoint emits. If something goes wrong with bugpoint, please submit the
"foo.bc" file and the list of passes printed by <b>opt</b>.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="ct_codegen">Code generator bugs</a>
</h3>
<div>
<p>If you find a bug that crashes llvm-gcc in the code generator, compile your
source file to a .bc file by passing "<tt><b>-emit-llvm -c -o foo.bc</b></tt>"
to llvm-gcc (in addition to the options you already pass). Once your have
foo.bc, one of the following commands should fail:</p>
<ol>
<li><tt><b>llc</b> foo.bc</tt></li>
<li><tt><b>llc</b> foo.bc -relocation-model=pic</tt></li>
<li><tt><b>llc</b> foo.bc -relocation-model=static</tt></li>
</ol>
<p>If none of these crash, please follow the instructions for a
<a href="#front-end">front-end bug</a>. If one of these do crash, you should
be able to reduce this with one of the following bugpoint command lines (use
the one corresponding to the command above that failed):</p>
<ol>
<li><tt><b>bugpoint</b> -run-llc foo.bc</tt></li>
<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args
-relocation-model=pic</tt></li>
<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args
-relocation-model=static</tt></li>
</ol>
<p>Please run this, then file a bug with the instructions and reduced .bc file
that bugpoint emits. If something goes wrong with bugpoint, please submit the
"foo.bc" file and the option that llc crashes with.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="miscompilations">Miscompilations</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
compiler. The first thing to check is to make sure it is not using undefined
behavior (e.g. reading a variable before it is defined). In particular, check
to see if the program <a href="http://valgrind.org/">valgrind</a>s clean,
passes purify, or some other memory checker tool. Many of the "LLVM bugs" that
we have chased down ended up being bugs in the program being compiled, not
LLVM.</p>
<p>Once you determine that the program itself is not buggy, you should choose
which code generator you wish to compile the program with (e.g. C backend, the
JIT, or LLC) and optionally a series of LLVM passes to run. For example:</p>
<div class="doc_code">
<p><tt>
<b>bugpoint</b> -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]</tt></p>
</div>
<p><tt>bugpoint</tt> will try to narrow down your list of passes to the one pass
that causes an error, and simplify the bitcode file as much as it can to assist
you. It will print a message letting you know how to reproduce the resulting
error.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="codegen">Incorrect code generation</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Similarly to debugging incorrect compilation by mis-behaving passes, you can
debug incorrect code generation by either LLC or the JIT, using
<tt>bugpoint</tt>. The process <tt>bugpoint</tt> follows in this case is to try
to narrow the code down to a function that is miscompiled by one or the other
method, but since for correctness, the entire program must be run,
<tt>bugpoint</tt> will compile the code it deems to not be affected with the C
Backend, and then link in the shared object it generates.</p>
<p>To debug the JIT:</p>
<div class="doc_code">
<pre>
bugpoint -run-jit -output=[correct output file] [bitcode file] \
--tool-args -- [arguments to pass to lli] \
--args -- [program arguments]
</pre>
</div>
<p>Similarly, to debug the LLC, one would run:</p>
<div class="doc_code">
<pre>
bugpoint -run-llc -output=[correct output file] [bitcode file] \
--tool-args -- [arguments to pass to llc] \
--args -- [program arguments]
</pre>
</div>
<p><b>Special note:</b> if you are debugging MultiSource or SPEC tests that
already exist in the <tt>llvm/test</tt> hierarchy, there is an easier way to
debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
will pass the program options specified in the Makefiles:</p>
<div class="doc_code">
<p><tt>
cd llvm/test/../../program<br>
make bugpoint-jit
</tt></p>
</div>
<p>At the end of a successful <tt>bugpoint</tt> run, you will be presented
with two bitcode files: a <em>safe</em> file which can be compiled with the C
backend and the <em>test</em> file which either LLC or the JIT
mis-codegenerates, and thus causes the error.</p>
<p>To reproduce the error that <tt>bugpoint</tt> found, it is sufficient to do
the following:</p>
<ol>
<li><p>Regenerate the shared object from the safe bitcode file:</p>
<div class="doc_code">
<p><tt>
<b>llc</b> -march=c safe.bc -o safe.c<br>
<b>gcc</b> -shared safe.c -o safe.so
</tt></p>
</div></li>
<li><p>If debugging LLC, compile test bitcode native and link with the shared
object:</p>
<div class="doc_code">
<p><tt>
<b>llc</b> test.bc -o test.s<br>
<b>gcc</b> test.s safe.so -o test.llc<br>
./test.llc [program options]
</tt></p>
</div></li>
<li><p>If debugging the JIT, load the shared object and supply the test
bitcode:</p>
<div class="doc_code">
<p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p>
</div></li>
</ol>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

368
cpp/llvm/docs/LLVMBuild.html
View File

@ -1,368 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVMBuild Documentation</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>LLVMBuild Guide</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#projectorg">Project Organization</a></li>
<li><a href="#buildintegration">Build Integration</a></li>
<li><a href="#componentoverview">Component Overview</a></li>
<li><a href="#formatreference">Format Reference</a></li>
</ol>
<!-- *********************************************************************** -->
<h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** -->
<div>
<p>This document describes the <tt>LLVMBuild</tt> organization and files which
we use to describe parts of the LLVM ecosystem. For description of specific
LLVMBuild related tools, please see the command guide.</p>
<p>LLVM is designed to be a modular set of libraries which can be flexibly
mixed together in order to build a variety of tools, like compilers, JITs,
custom code generators, optimization passes, interpreters, and so on. Related
projects in the LLVM system like Clang and LLDB also tend to follow this
philosophy.</p>
<p>In order to support this usage style, LLVM has a fairly strict structure as
to how the source code and various components are organized. The
<tt>LLVMBuild.txt</tt> files are the explicit specification of that structure,
and are used by the build systems and other tools in order to develop the LLVM
project.</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="projectorg">Project Organization</a></h2>
<!-- *********************************************************************** -->
<!-- FIXME: We should probably have an explicit top level project object. Good
place to hang project level data, name, etc. Also useful for serving as the
$ROOT of project trees for things which can be checked out separately. -->
<div>
<p>The source code for LLVM projects using the LLVMBuild system (LLVM, Clang,
and LLDB) is organized into <em>components</em>, which define the separate
pieces of functionality that make up the project. These projects may consist
of many libraries, associated tools, build tools, or other utility tools (for
example, testing tools).</p>
<p>For the most part, the project contents are organized around defining one
main component per each subdirectory. Each such directory contains
an <tt>LLVMBuild.txt</tt> which contains the component definitions.</p>
<p>The component descriptions for the project as a whole are automatically
gathered by the LLVMBuild tools. The tools automatically traverse the source
directory structure to find all of the component description files. NOTE: For
performance/sanity reasons, we only traverse into subdirectories when the
parent itself contains an <tt>LLVMBuild.txt</tt> description file.</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="buildintegration">Build Integration</a></h2>
<!-- *********************************************************************** -->
<div>
<p>The LLVMBuild files themselves are just a declarative way to describe the
project structure. The actual building of the LLVM project is handled by
another build system (currently we support
both <a href="MakefileGuide.html">Makefiles</a>
and <a href="CMake.html">CMake</a>.</p>
<p>The build system implementation will load the relevant contents of the
LLVMBuild files and use that to drive the actual project build. Typically, the
build system will only need to load this information at "configure" time, and
use it to generative native information. Build systems will also handle
automatically reconfiguring their information when the contents of
the <i>LLVMBuild.txt</i> files change.</p>
<p>Developers generally are not expected to need to be aware of the details of
how the LLVMBuild system is integrated into their build. Ideally, LLVM
developers who are not working on the build system would only ever need to
modify the contents of the <i>LLVMBuild.txt</i> description files (although we
have not reached this goal yet).</p>
<p>For more information on the utility tool we provide to help interfacing
with the build system, please see
the <a href="CommandGuide/html/llvm-build.html">llvm-build</a>
documentation.</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="componentoverview">Component Overview</a></h2>
<!-- *********************************************************************** -->
<div>
<p>As mentioned earlier, LLVM projects are organized into
logical <em>components</em>. Every component is typically grouped into its
own subdirectory. Generally, a component is organized around a coherent group
of sources which have some kind of clear API separation from other parts of
the code.</p>
<p>LLVM primarily uses the following types of components:</p>
<ul>
<li><em>Libraries</em> - Library components define a distinct API which can
be independently linked into LLVM client applications. Libraries typically
have private and public header files, and may specify a link of required
libraries that they build on top of.</li>
<li><em>Build Tools</em> - Build tools are applications which are designed
to be run as part of the build process (typically to generate other source
files). Currently, LLVM uses one main build tool
called <a href="TableGenFundamentals.html">TableGen</a> to generate a
variety of source files.</li>
<li><em>Tools</em> - Command line applications which are built using the
LLVM component libraries. Most LLVM tools are small and are primarily
frontends to the library interfaces.</li>
<!-- FIXME: We also need shared libraries as a first class component, but this
is not yet implemented. -->
</ul>
<p>Components are described using <em>LLVMBuild.txt</em> files in the
directories that define the component. See
the <a href="#formatreference">Format Reference</a> section for information on
the exact format of these files.</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="formatreference">LLVMBuild Format Reference</a></h2>
<!-- *********************************************************************** -->
<div>
<p>LLVMBuild files are written in a simple variant of the INI or configuration
file format (<a href="http://en.wikipedia.org/wiki/INI_file">Wikipedia
entry</a>). The format defines a list of sections each of which may contain
some number of properties. A simple example of the file format is below:</p>
<div class="doc_code">
<pre>
<i>; Comments start with a semi-colon.</i>
<i>; Sections are declared using square brackets.</i>
[component_0]
<i>; Properties are declared using '=' and are contained in the previous section.
;
; We support simple string and boolean scalar values and list values, where
; items are separated by spaces. There is no support for quoting, and so
; property values may not contain spaces.</i>
property_name = property_value
list_property_name = value_1 value_2 <em>...</em> value_n
boolean_property_name = 1 <em>(or 0)</em>
</pre>
</div>
<p>LLVMBuild files are expected to define a strict set of sections and
properties. An typical component description file for a library
component would look typically look like the following example:</p>
<div class="doc_code">
<pre>
[component_0]
type = Library
name = Linker
parent = Libraries
required_libraries = Archive BitReader Core Support TransformUtils
</pre>
</div>
<p>A full description of the exact sections and properties which are allowed
follows.</p>
<p>Each file may define exactly one common component, named "common". The
common component may define the following properties:</p>
<ul>
<li><i>subdirectories</i> <b>[optional]</b>
<p>If given, a list of the names of the subdirectories from the current
subpath to search for additional LLVMBuild files.</p></li>
</ul>
<p>Each file may define multiple components. Each component is described by a
section who name starts with "component". The remainder of the section name is
ignored, but each section name must be unique. Typically components are just
number in order for files with multiple components ("component_0",
"component_1", and so on).<p>
<p><b>Section names not matching this format (or the "common" section) are
currently unused and are disallowed.</b></p>
<p>Every component is defined by the properties in the section. The exact list
of properties that are allowed depends on the component
type. Components <b>may not</b> define any properties other than those
expected by the component type.</p>
<p>Every component must define the following properties:</p>
<ul>
<li><i>type</i> <b>[required]</b>
<p>The type of the component. Supported component types are
detailed below. Most components will define additional properties which
may be required or optional.</p></li>
<li><i>name</i> <b>[required]</b>
<p>The name of the component. Names are required to be unique
across the entire project.</p></li>
<li><i>parent</i> <b>[required]</b>
<p>The name of the logical parent of the component. Components are
organized into a logical tree to make it easier to navigate and organize
groups of components. The parents have no semantics as far as the project
build is concerned, however. Typically, the parent will be the main
component of the parent directory.</p>
<!-- FIXME: Should we make the parent optional, and default to parent
directories component? -->
<p>Components may reference the root pseudo component using '$ROOT' to
indicate they should logically be grouped at the top-level.</p>
</li>
</ul>
<p>Components may define the following properties:</p>
<ul>
<li><i>dependencies</i> <b>[optional]</b>
<p>If specified, a list of names of components which <i>must</i> be built
prior to this one. This should only be exactly those components which
produce some tool or source code required for building the
component.</p>
<p><em>NOTE:</em> Group and LibraryGroup components have no semantics for
the actual build, and are not allowed to specify dependencies.</p></li>
</ul>
<p>The following section lists the available component types, as well as the
properties which are associated with that component.</p>
<ul>
<li><i>type = Group</i>
<p>Group components exist purely to allow additional arbitrary structuring
of the logical components tree. For example, one might define a
"Libraries" group to hold all of the root library components.</p>
<p>Group components have no additionally properties.</p>
</li>
<li><i>type = Library</i>
<p>Library components define an individual library which should be built
from the source code in the component directory.</p>
<p>Components with this type use the following properties:</p>
<ul>
<li><i>library_name</i> <b>[optional]</b>
<p>If given, the name to use for the actual library file on disk. If
not given, the name is derived from the component name
itself.</p></li>
<li><i>required_libraries</i> <b>[optional]</b>
<p>If given, a list of the names of Library or LibraryGroup components
which must also be linked in whenever this library is used. That is,
the link time dependencies for this component. When tools are built,
the build system will include the transitive closure of
all <i>required_libraries</i> for the components the tool needs.</p></li>
<li><i>add_to_library_groups</i> <b>[optional]</b>
<p>If given, a list of the names of LibraryGroup components which this
component is also part of. This allows nesting groups of
components. For example, the <i>X86</i> target might define a library
group for all of the <i>X86</i> components. That library group might
then be included in the <i>all-targets</i> library group.</p></li>
<li><i>installed</i> <b>[optional]</b> <b>[boolean]</b>
<p>Whether this library is installed. Libraries that are not installed
are only reported by <tt>llvm-config</tt> when it is run as part of a
development directory.</p></li>
</ul>
</li>
<li><i>type = LibraryGroup</i>
<p>LibraryGroup components are a mechanism to allow easy definition of
useful sets of related components. In particular, we use them to easily
specify things like "all targets", or "all assembly printers".</p>
<p>Components with this type use the following properties:</p>
<ul>
<li><i>required_libraries</i> <b>[optional]</b>
<p>See the Library type for a description of this property.</p></li>
<li><i>add_to_library_groups</i> <b>[optional]</b>
<p>See the Library type for a description of this property.</p></li>
</ul>
</li>
<li><i>type = TargetGroup</i>
<p>TargetGroup components are an extension of LibraryGroups, specifically
for defining LLVM targets (which are handled specially in a few
places).</p>
<p>The name of the component should always be the name of the target.</p>
<p>Components with this type use the LibraryGroup properties in addition
to:</p>
<ul>
<li><i>has_asmparser</i> <b>[optional]</b> <b>[boolean]</b>
<p>Whether this target defines an assembly parser.</p></li>
<li><i>has_asmprinter</i> <b>[optional]</b> <b>[boolean]</b>
<p>Whether this target defines an assembly printer.</p></li>
<li><i>has_disassembler</i> <b>[optional]</b> <b>[boolean]</b>
<p>Whether this target defines a disassembler.</p></li>
<li><i>has_jit</i> <b>[optional]</b> <b>[boolean]</b>
<p>Whether this target supports JIT compilation.</p></li>
</ul>
</li>
<li><i>type = Tool</i>
<p>Tool components define standalone command line tools which should be
built from the source code in the component directory and linked.</p>
<p>Components with this type use the following properties:</p>
<ul>
<li><i>required_libraries</i> <b>[optional]</b>
<p>If given, a list of the names of Library or LibraryGroup components
which this tool is required to be linked with. <b>NOTE:</b> The values
should be the component names, which may not always match up with the
actual library names on disk.</p>
<p>Build systems are expected to properly include all of the libraries
required by the linked components (i.e., the transitive closer
of <em>required_libraries</em>).</p>
<p>Build systems are also expected to understand that those library
components must be built prior to linking -- they do not also need to
be listed under <i>dependencies</i>.</p></li>
</ul>
</li>
<li><i>type = BuildTool</i>
<p>BuildTool components are like Tool components, except that the tool is
supposed to be built for the platform where the build is running (instead
of that platform being targetted). Build systems are expected to handle
the fact that required libraries may need to be built for multiple
platforms in order to be able to link this tool.</p>
<p>BuildTool components currently use the exact same properties as Tool
components, the type distinction is only used to differentiate what the
tool is built for.</p>
</li>
</ul>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
</body>
</html>

8512
cpp/llvm/docs/LangRef.html
View File

File diff suppressed because it is too large Load Diff

292
cpp/llvm/docs/Lexicon.html
View File

@ -1,292 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>The LLVM Lexicon</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
<meta name="author" content="Various">
<meta name="description"
content="A glossary of terms used with the LLVM project.">
</head>
<body>
<h1>The LLVM Lexicon</h1>
<p class="doc_warning">NOTE: This document is a work in progress!</p>
<!-- *********************************************************************** -->
<h2>Table Of Contents</h2>
<!-- *********************************************************************** -->
<div>
<table>
<tr><th colspan="8"><b>- <a href="#A">A</a> -</b></th></tr>
<tr>
<td><a href="#ADCE">ADCE</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#B">B</a> -</b></th></tr>
<tr>
<td><a href="#BURS">BURS</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#C">C</a> -</b></th></tr>
<tr>
<td><a href="#CSE">CSE</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#D">D</a> -</b></th></tr>
<tr>
<td><a href="#DAG">DAG</a></td>
<td><a href="#Derived_Pointer">Derived Pointer</a></td>
<td><a href="#DSA">DSA</a></td>
<td><a href="#DSE">DSE</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#F">F</a> -</b></th></tr>
<tr>
<td><a href="#FCA">FCA</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#G">G</a> -</b></th></tr>
<tr>
<td><a href="#GC">GC</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#I">I</a> -</b></th></tr>
<tr>
<td><a href="#IPA">IPA</a></td>
<td><a href="#IPO">IPO</a></td>
<td><a href="#ISel">ISel</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#L">L</a> -</b></th></tr>
<tr>
<td><a href="#LCSSA">LCSSA</a></td>
<td><a href="#LICM">LICM</a></td>
<td><a href="#Load-VN">Load-VN</a></td>
<td><a href="#LTO">LTO</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#M">M</a> -</b></th></tr>
<tr>
<td><a href="#MC">MC</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#O">O</a> -</b></th></tr>
<tr>
<td><a href="#Object_Pointer">Object Pointer</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#P">P</a> -</b></th></tr>
<tr>
<td><a href="#PRE">PRE</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#R">R</a> -</b></th></tr>
<tr>
<td><a href="#RAUW">RAUW</a></td>
<td><a href="#Reassociation">Reassociation</a></td>
<td><a href="#Root">Root</a></td>
</tr>
<tr><th colspan="8"><b>- <a href="#S">S</a> -</b></th></tr>
<tr>
<td><a href="#Safe_Point">Safe Point</a></td>
<td><a href="#SCC">SCC</a></td>
<td><a href="#SCCP">SCCP</a></td>
<td><a href="#SDISel">SDISel</a></td>
<td><a href="#SRoA">SRoA</a></td>
<td><a href="#Stack_Map">Stack Map</a></td>
</tr>
</table>
</div>
<!-- *********************************************************************** -->
<h2>Definitions</h2>
<!-- *********************************************************************** -->
<div>
<!-- _______________________________________________________________________ -->
<h3><a name="A">- A -</a></h3>
<div>
<dl>
<dt><a name="ADCE"><b>ADCE</b></a></dt>
<dd>Aggressive Dead Code Elimination</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="B">- B -</a></h3>
<div>
<dl>
<dt><a name="BURS"><b>BURS</b></a></dt>
<dd>Bottom Up Rewriting System&mdash;A method of instruction selection for
code generation. An example is the <a
href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="C">- C -</a></h3>
<div>
<dl>
<dt><a name="CSE"><b>CSE</b></a></dt>
<dd>Common Subexpression Elimination. An optimization that removes common
subexpression compuation. For example <tt>(a+b)*(a+b)</tt> has two
subexpressions that are the same: <tt>(a+b)</tt>. This optimization would
perform the addition only once and then perform the multiply (but only if
it's compulationally correct/safe).
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="D">- D -</a></h3>
<div>
<dl>
<dt><a name="DAG"><b>DAG</b></a></dt>
<dd>Directed Acyclic Graph</dd>
<dt><a name="Derived_Pointer"><b>Derived Pointer</b></a></dt>
<dd>A pointer to the interior of an object, such that a garbage collector
is unable to use the pointer for reachability analysis. While a derived
pointer is live, the corresponding object pointer must be kept in a root,
otherwise the collector might free the referenced object. With copying
collectors, derived pointers pose an additional hazard that they may be
invalidated at any <a href="Safe_Point">safe point</a>. This term is used in
opposition to <a href="#Object_Pointer">object pointer</a>.</dd>
<dt><a name="DSA"><b>DSA</b></a></dt>
<dd>Data Structure Analysis</dd>
<dt><a name="DSE"><b>DSE</b></a></dt>
<dd>Dead Store Elimination</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="F">- F -</a></h3>
<div>
<dl>
<dt><a name="FCA"><b>FCA</b></a></dt>
<dd>First Class Aggregate</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="G">- G -</a></h3>
<div>
<dl>
<dt><a name="GC"><b>GC</b></a></dt>
<dd>Garbage Collection. The practice of using reachability analysis instead
of explicit memory management to reclaim unused memory.</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="H">- H -</a></h3>
<div>
<dl>
<dt><a name="Heap"><b>Heap</b></a></dt>
<dd>In garbage collection, the region of memory which is managed using
reachability analysis.</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="I">- I -</a></h3>
<div>
<dl>
<dt><a name="IPA"><b>IPA</b></a></dt>
<dd>Inter-Procedural Analysis. Refers to any variety of code analysis that
occurs between procedures, functions or compilation units (modules).</dd>
<dt><a name="IPO"><b>IPO</b></a></dt>
<dd>Inter-Procedural Optimization. Refers to any variety of code
optimization that occurs between procedures, functions or compilation units
(modules).</dd>
<dt><a name="ISel"><b>ISel</b></a></dt>
<dd>Instruction Selection.</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="L">- L -</a></h3>
<div>
<dl>
<dt><a name="LCSSA"><b>LCSSA</b></a></dt>
<dd>Loop-Closed Static Single Assignment Form</dd>
<dt><a name="LICM"><b>LICM</b></a></dt>
<dd>Loop Invariant Code Motion</dd>
<dt><a name="Load-VN"><b>Load-VN</b></a></dt>
<dd>Load Value Numbering</dd>
<dt><a name="LTO"><b>LTO</b></a></dt>
<dd>Link-Time Optimization</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="M">- M -</a></h3>
<div>
<dl>
<dt><a name="MC"><b>MC</b></a></dt>
<dd>Machine Code</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="O">- O -</a></h3>
<div>
<dl>
<dt><a name="Object_Pointer"><b>Object Pointer</b></a></dt>
<dd>A pointer to an object such that the garbage collector is able to trace
references contained within the object. This term is used in opposition to
<a href="#Derived_Pointer">derived pointer</a>.</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="P">- P -</a></h3>
<div>
<dl>
<dt><a name="PRE"><b>PRE</b></a></dt>
<dd>Partial Redundancy Elimination</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="R">- R -</a></h3>
<div>
<dl>
<dt><a name="RAUW"><b>RAUW</b></a></dt> <dd>An abbreviation for Replace
All Uses With. The functions User::replaceUsesOfWith(),
Value::replaceAllUsesWith(), and Constant::replaceUsesOfWithOnConstant()
implement the replacement of one Value with another by iterating over its
def/use chain and fixing up all of the pointers to point to the new value.
See also <a href="ProgrammersManual.html#iterate_chains">def/use chains</a>.
</dd>
<dt><a name="Reassociation"><b>Reassociation</b></a></dt> <dd>Rearranging
associative expressions to promote better redundancy elimination and other
optimization. For example, changing (A+B-A) into (B+A-A), permitting it to
be optimized into (B+0) then (B).</dd>
<dt><a name="Root"><b>Root</b></a></dt> <dd>In garbage collection, a
pointer variable lying outside of the <a href="#Heap">heap</a> from which
the collector begins its reachability analysis. In the context of code
generation, "root" almost always refers to a "stack root" -- a local or
temporary variable within an executing function.</dd>
</dl>
</div>
<!-- _______________________________________________________________________ -->
<h3><a name="S">- S -</a></h3>
<div>
<dl>
<dt><a name="Safe_Point"><b>Safe Point</b></a></dt>
<dd>In garbage collection, it is necessary to identify <a href="#Root">stack
roots</a> so that reachability analysis may proceed. It may be infeasible to
provide this information for every instruction, so instead the information
may is calculated only at designated safe points. With a copying collector,
<a href="#Derived_Pointers">derived pointers</a> must not be retained across
safe points and <a href="#Object_Pointers">object pointers</a> must be
reloaded from stack roots.</dd>
<dt><a name="SDISel"><b>SDISel</b></a></dt>
<dd>Selection DAG Instruction Selection.</dd>
<dt><a name="SCC"><b>SCC</b></a></dt>
<dd>Strongly Connected Component</dd>
<dt><a name="SCCP"><b>SCCP</b></a></dt>
<dd>Sparse Conditional Constant Propagation</dd>
<dt><a name="SRoA"><b>SRoA</b></a></dt>
<dd>Scalar Replacement of Aggregates</dd>
<dt><a name="SSA"><b>SSA</b></a></dt>
<dd>Static Single Assignment</dd>
<dt><a name="Stack_Map"><b>Stack Map</b></a></dt>
<dd>In garbage collection, metadata emitted by the code generator which
identifies <a href="#Root">roots</a> within the stack frame of an executing
function.</dd>
</dl>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a><a
href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a><a
href="http://llvm.org/">The LLVM Team</a><br>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-01-05 00:18:41 -0800 (Thu, 05 Jan 2012) $
</address>
<!-- vim: sw=2
-->
</body>
</html>

401
cpp/llvm/docs/LinkTimeOptimization.html
View File

@ -1,401 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM Link Time Optimization: Design and Implementation</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<h1>
LLVM Link Time Optimization: Design and Implementation
</h1>
<ul>
<li><a href="#desc">Description</a></li>
<li><a href="#design">Design Philosophy</a>
<ul>
<li><a href="#example1">Example of link time optimization</a></li>
<li><a href="#alternative_approaches">Alternative Approaches</a></li>
</ul></li>
<li><a href="#multiphase">Multi-phase communication between LLVM and linker</a>
<ul>
<li><a href="#phase1">Phase 1 : Read LLVM Bitcode Files</a></li>
<li><a href="#phase2">Phase 2 : Symbol Resolution</a></li>
<li><a href="#phase3">Phase 3 : Optimize Bitcode Files</a></li>
<li><a href="#phase4">Phase 4 : Symbol Resolution after optimization</a></li>
</ul></li>
<li><a href="#lto">libLTO</a>
<ul>
<li><a href="#lto_module_t">lto_module_t</a></li>
<li><a href="#lto_code_gen_t">lto_code_gen_t</a></li>
</ul>
</ul>
<div class="doc_author">
<p>Written by Devang Patel and Nick Kledzik</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="desc">Description</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>
LLVM features powerful intermodular optimizations which can be used at link
time. Link Time Optimization (LTO) is another name for intermodular optimization
when performed during the link stage. This document describes the interface
and design between the LTO optimizer and the linker.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="design">Design Philosophy</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>
The LLVM Link Time Optimizer provides complete transparency, while doing
intermodular optimization, in the compiler tool chain. Its main goal is to let
the developer take advantage of intermodular optimizations without making any
significant changes to the developer's makefiles or build system. This is
achieved through tight integration with the linker. In this model, the linker
treates LLVM bitcode files like native object files and allows mixing and
matching among them. The linker uses <a href="#lto">libLTO</a>, a shared
object, to handle LLVM bitcode files. This tight integration between
the linker and LLVM optimizer helps to do optimizations that are not possible
in other models. The linker input allows the optimizer to avoid relying on
conservative escape analysis.
</p>
<!-- ======================================================================= -->
<h3>
<a name="example1">Example of link time optimization</a>
</h3>
<div>
<p>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,
clang transparently invokes system linker. </p>
<ul>
<li> Input source file <tt>a.c</tt> is compiled into LLVM bitcode form.
<li> Input source file <tt>main.c</tt> is compiled into native object code.
</ul>
<pre class="doc_code">
--- a.h ---
extern int foo1(void);
extern void foo2(void);
extern void foo4(void);
--- a.c ---
#include "a.h"
static signed int i = 0;
void foo2(void) {
i = -1;
}
static int foo3() {
foo4();
return 10;
}
int foo1(void) {
int data = 0;
if (i &lt; 0)
data = foo3();
data = data + 42;
return data;
}
--- main.c ---
#include &lt;stdio.h&gt;
#include "a.h"
void foo4(void) {
printf("Hi\n");
}
int main() {
return foo1();
}
--- command lines ---
$ clang -emit-llvm -c a.c -o a.o # &lt;-- a.o is LLVM bitcode file
$ clang -c main.c -o main.o # &lt;-- main.o is native object file
$ clang a.o main.o -o main # &lt;-- standard link command without any modifications
</pre>
<ul>
<li>In this example, the linker recognizes that <tt>foo2()</tt> is an
externally visible symbol defined in LLVM bitcode file. The linker
completes its usual symbol resolution pass and finds that <tt>foo2()</tt>
is not used anywhere. This information is used by the LLVM optimizer and
it removes <tt>foo2()</tt>.</li>
<li>As soon as <tt>foo2()</tt> is removed, the optimizer recognizes that condition
<tt>i &lt; 0</tt> is always false, which means <tt>foo3()</tt> is never
used. Hence, the optimizer also removes <tt>foo3()</tt>.</li>
<li>And this in turn, enables linker to remove <tt>foo4()</tt>.</li>
</ul>
<p>This example illustrates the advantage of tight integration with the
linker. Here, the optimizer can not remove <tt>foo3()</tt> without the
linker's input.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="alternative_approaches">Alternative Approaches</a>
</h3>
<div>
<dl>
<dt><b>Compiler driver invokes link time optimizer separately.</b></dt>
<dd>In this model the link time optimizer is not able to take advantage of
information collected during the linker's normal symbol resolution phase.
In the above example, the optimizer can not remove <tt>foo2()</tt> without
the linker's input because it is externally visible. This in turn prohibits
the optimizer from removing <tt>foo3()</tt>.</dd>
<dt><b>Use separate tool to collect symbol information from all object
files.</b></dt>
<dd>In this model, a new, separate, tool or library replicates the linker's
capability to collect information for link time optimization. Not only is
this code duplication difficult to justify, but it also has several other
disadvantages. For example, the linking semantics and the features
provided by the linker on various platform are not unique. This means,
this new tool needs to support all such features and platforms in one
super tool or a separate tool per platform is required. This increases
maintenance cost for link time optimizer significantly, which is not
necessary. This approach also requires staying synchronized with linker
developements on various platforms, which is not the main focus of the link
time optimizer. Finally, this approach increases end user's build time due
to the duplication of work done by this separate tool and the linker itself.
</dd>
</dl>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="multiphase">Multi-phase communication between libLTO and linker</a>
</h2>
<div>
<p>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
information by looking at the definitions and uses of symbols in native .o
files and using symbol visibility information. The linker also uses
user-supplied information, such as a list of exported symbols. LLVM
optimizer collects control flow information, data flow information and knows
much more about program structure from the optimizer's point of view.
Our goal is to take advantage of tight integration between the linker and
the optimizer by sharing this information during various linking phases.
</p>
<!-- ======================================================================= -->
<h3>
<a name="phase1">Phase 1 : Read LLVM Bitcode Files</a>
</h3>
<div>
<p>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
are native object files, the linker only calls <tt>lto_module_create()</tt>
when a supplied object file is found to not be a native object file. If
<tt>lto_module_create()</tt> returns that the file is an LLVM bitcode file,
the linker
then iterates over the module using <tt>lto_module_get_symbol_name()</tt> and
<tt>lto_module_get_symbol_attribute()</tt> to get all symbols defined and
referenced.
This information is added to the linker's global symbol table.
</p>
<p>The lto* functions are all implemented in a shared object libLTO. This
allows the LLVM LTO code to be updated independently of the linker tool.
On platforms that support it, the shared object is lazily loaded.
</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="phase2">Phase 2 : Symbol Resolution</a>
</h3>
<div>
<p>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
does not know the exact content of input LLVM bitcode files. If dead code
stripping is enabled then the linker collects the list of live symbols.
</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="phase3">Phase 3 : Optimize Bitcode Files</a>
</h3>
<div>
<p>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 <tt>foo1()</tt> is used by native object files using
<tt>lto_codegen_add_must_preserve_symbol()</tt>. Next the linker invokes
the LLVM optimizer and code generators using <tt>lto_codegen_compile()</tt>
which returns a native object file creating by merging the LLVM bitcode files
and applying various optimization passes.
</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="phase4">Phase 4 : Symbol Resolution after optimization</a>
</h3>
<div>
<p>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
LLVM bitcode files. In the example above, the linker notes that
<tt>foo4()</tt> is not used any more. If dead code stripping is enabled then
the linker refreshes the live symbol information appropriately and performs
dead code stripping.</p>
<p>After this phase, the linker continues linking as if it never saw LLVM
bitcode files.</p>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="lto">libLTO</a>
</h2>
<div>
<p><tt>libLTO</tt> is a shared object that is part of the LLVM tools, and
is intended for use by a linker. <tt>libLTO</tt> provides an abstract C
interface to use the LLVM interprocedural optimizer without exposing details
of LLVM's internals. The intention is to keep the interface as stable as
possible even when the LLVM optimizer continues to evolve. It should even
be possible for a completely different compilation technology to provide
a different libLTO that works with their object files and the standard
linker tool.</p>
<!-- ======================================================================= -->
<h3>
<a name="lto_module_t">lto_module_t</a>
</h3>
<div>
<p>A non-native object file is handled via an <tt>lto_module_t</tt>.
The following functions allow the linker to check if a file (on disk
or in a memory buffer) is a file which libLTO can process:</p>
<pre class="doc_code">
lto_module_is_object_file(const char*)
lto_module_is_object_file_for_target(const char*, const char*)
lto_module_is_object_file_in_memory(const void*, size_t)
lto_module_is_object_file_in_memory_for_target(const void*, size_t, const char*)
</pre>
<p>If the object file can be processed by libLTO, the linker creates a
<tt>lto_module_t</tt> by using one of</p>
<pre class="doc_code">
lto_module_create(const char*)
lto_module_create_from_memory(const void*, size_t)
</pre>
<p>and when done, the handle is released via</p>
<pre class="doc_code">
lto_module_dispose(lto_module_t)
</pre>
<p>The linker can introspect the non-native object file by getting the number of
symbols and getting the name and attributes of each symbol via:</p>
<pre class="doc_code">
lto_module_get_num_symbols(lto_module_t)
lto_module_get_symbol_name(lto_module_t, unsigned int)
lto_module_get_symbol_attribute(lto_module_t, unsigned int)
</pre>
<p>The attributes of a symbol include the alignment, visibility, and kind.</p>
</div>
<!-- ======================================================================= -->
<h3>
<a name="lto_code_gen_t">lto_code_gen_t</a>
</h3>
<div>
<p>Once the linker has loaded each non-native object files into an
<tt>lto_module_t</tt>, it can request libLTO to process them all and
generate a native object file. This is done in a couple of steps.
First, a code generator is created with:</p>
<pre class="doc_code">lto_codegen_create()</pre>
<p>Then, each non-native object file is added to the code generator with:</p>
<pre class="doc_code">
lto_codegen_add_module(lto_code_gen_t, lto_module_t)
</pre>
<p>The linker then has the option of setting some codegen options. Whether or
not to generate DWARF debug info is set with:</p>
<pre class="doc_code">lto_codegen_set_debug_model(lto_code_gen_t)</pre>
<p>Which kind of position independence is set with:</p>
<pre class="doc_code">lto_codegen_set_pic_model(lto_code_gen_t) </pre>
<p>And each symbol that is referenced by a native object file or otherwise must
not be optimized away is set with:</p>
<pre class="doc_code">
lto_codegen_add_must_preserve_symbol(lto_code_gen_t, const char*)
</pre>
<p>After all these settings are done, the linker requests that a native object
file be created from the modules with the settings using:</p>
<pre class="doc_code">lto_codegen_compile(lto_code_gen_t, size*)</pre>
<p>which returns a pointer to a buffer containing the generated native
object file. The linker then parses that and links it with the rest
of the native object files.</p>
</div>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Devang Patel and Nick Kledzik<br>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

130
cpp/llvm/docs/Makefile
View File

@ -1,130 +0,0 @@
##===- docs/Makefile ---------------------------------------*- Makefile -*-===##
#
# The LLVM Compiler Infrastructure
#
# This file is distributed under the University of Illinois Open Source
# License. See LICENSE.TXT for details.
#
##===----------------------------------------------------------------------===##
LEVEL := ..
DIRS := CommandGuide tutorial
ifdef BUILD_FOR_WEBSITE
PROJ_OBJ_DIR = .
DOXYGEN = doxygen
$(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in
cat $< | sed \
-e 's/@abs_top_srcdir@/../g' \
-e 's/@DOT@/dot/g' \
-e 's/@PACKAGE_VERSION@/mainline/' \
-e 's/@abs_top_builddir@/../g' > $@
endif
include $(LEVEL)/Makefile.common
HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \
$(wildcard $(PROJ_SRC_DIR)/*.css)
IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*)
DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \
doxygen.intro
EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img
.PHONY: install-html install-doxygen doxygen install-ocamldoc ocamldoc generated
install_targets := install-html
ifeq ($(ENABLE_DOXYGEN),1)
install_targets += install-doxygen
endif
ifdef OCAMLDOC
ifneq (,$(filter ocaml,$(BINDINGS_TO_BUILD)))
install_targets += install-ocamldoc
endif
endif
install-local:: $(install_targets)
generated_targets := doxygen
ifdef OCAMLDOC
generated_targets += ocamldoc
endif
# Live documentation is generated for the web site using this target:
# 'make generated BUILD_FOR_WEBSITE=1'
generated:: $(generated_targets)
install-html: $(PROJ_OBJ_DIR)/html.tar.gz
$(Echo) Installing HTML documentation
$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html
$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/img
$(Verb) $(DataInstall) $(HTML) $(DESTDIR)$(PROJ_docsdir)/html
$(Verb) $(DataInstall) $(IMAGES) $(DESTDIR)$(PROJ_docsdir)/html/img
$(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(DESTDIR)$(PROJ_docsdir)
$(PROJ_OBJ_DIR)/html.tar.gz: $(HTML)
$(Echo) Packaging HTML documentation
$(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar
$(Verb) cd $(PROJ_SRC_DIR) && \
$(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html
$(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar
install-doxygen: doxygen
$(Echo) Installing doxygen documentation
$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/doxygen
$(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(DESTDIR)$(PROJ_docsdir)
$(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \
$(FIND) . -type f -exec \
$(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/html/doxygen \;
doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz
regendoc:
$(Echo) Building doxygen documentation
$(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \
$(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \
fi
$(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg
$(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg
$(Echo) Packaging doxygen documentation
$(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar
$(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen
$(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/doxygen.tar
$(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/
userloc: $(LLVM_SRC_ROOT)/docs/userloc.html
$(LLVM_SRC_ROOT)/docs/userloc.html:
$(Echo) Making User LOC Table
$(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \
-html lib include tools runtime utils examples autoconf test > docs/userloc.html
install-ocamldoc: ocamldoc
$(Echo) Installing ocamldoc documentation
$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/ocamldoc/html
$(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(DESTDIR)$(PROJ_docsdir)
$(Verb) cd $(PROJ_OBJ_DIR)/ocamldoc && \
$(FIND) . -type f -exec \
$(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/ocamldoc/html \;
ocamldoc: regen-ocamldoc
$(Echo) Packaging ocamldoc documentation
$(Verb) $(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc.tar*
$(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/ocamldoc.tar ocamldoc
$(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/ocamldoc.tar
$(Verb) $(CP) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(PROJ_OBJ_DIR)/ocamldoc/html/
regen-ocamldoc:
$(Echo) Building ocamldoc documentation
$(Verb) if test -e $(PROJ_OBJ_DIR)/ocamldoc ; then \
$(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc ; \
fi
$(Verb) $(MAKE) -C $(LEVEL)/bindings/ocaml ocamldoc
$(Verb) $(MKDIR) $(PROJ_OBJ_DIR)/ocamldoc/html
$(Verb) \
$(OCAMLDOC) -d $(PROJ_OBJ_DIR)/ocamldoc/html -sort -colorize-code -html \
`$(FIND) $(LEVEL)/bindings/ocaml -name "*.odoc" -exec echo -load '{}' ';'`
uninstall-local::
$(Echo) Uninstalling Documentation
$(Verb) $(RM) -rf $(DESTDIR)$(PROJ_docsdir)

1039
cpp/llvm/docs/MakefileGuide.html
View File

File diff suppressed because it is too large Load Diff

119
cpp/llvm/docs/Packaging.html
View File

@ -1,119 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Advice on Packaging LLVM</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>Advice on Packaging LLVM</h1>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#compilation">Compile Flags</a></li>
<li><a href="#cxx-features">C++ Features</a></li>
<li><a href="#shared-library">Shared Library</a></li>
<li><a href="#deps">Dependencies</a></li>
</ol>
<!--=========================================================================-->
<h2><a name="overview">Overview</a></h2>
<!--=========================================================================-->
<div>
<p>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
desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
etc.) will tweak them. This document lists settings we suggest you tweak.
</p>
<p>LLVM's API changes with each release, so users are likely to want, for
example, both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps
developed against each.
</p>
</div>
<!--=========================================================================-->
<h2><a name="compilation">Compile Flags</a></h2>
<!--=========================================================================-->
<div>
<p>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
defining NDEBUG, and the lack of assertions makes it hard to debug problems in
user code. We recommend allowing users to install both optimized and debug
versions of LLVM in parallel. The following configure flags are relevant:
</p>
<dl>
<dt><tt>--disable-assertions</tt></dt><dd>Builds LLVM with <tt>NDEBUG</tt>
defined. Changes the LLVM ABI. Also available by setting
<tt>DISABLE_ASSERTIONS=0|1</tt> in <tt>make</tt>'s environment. This defaults
to enabled regardless of the optimization setting, but it slows things
down.</dd>
<dt><tt>--enable-debug-symbols</tt></dt><dd>Builds LLVM with <tt>-g</tt>.
Also available by setting <tt>DEBUG_SYMBOLS=0|1</tt> in <tt>make</tt>'s
environment. This defaults to disabled when optimizing, so you should turn it
back on to let users debug their programs.</dd>
<dt><tt>--enable-optimized</tt></dt><dd>(For svn checkouts) Builds LLVM with
<tt>-O2</tt> and, by default, turns off debug symbols. Also available by
setting <tt>ENABLE_OPTIMIZED=0|1</tt> in <tt>make</tt>'s environment. This
defaults to enabled when not in a checkout.</dd>
</dl>
</div>
<!--=========================================================================-->
<h2><a name="cxx-features">C++ Features</a></h2>
<!--=========================================================================-->
<div>
<dl>
<dt>RTTI</dt><dd>LLVM disables RTTI by default. Add <tt>REQUIRES_RTTI=1</tt>
to your environment while running <tt>make</tt> to re-enable it. This will
allow users to build with RTTI enabled and still inherit from LLVM
classes.</dd>
</dl>
</div>
<!--=========================================================================-->
<h2><a name="shared-library">Shared Library</a></h2>
<!--=========================================================================-->
<div>
<p>Configure with <tt>--enable-shared</tt> to build
<tt>libLLVM-<var>major</var>.<var>minor</var>.(so|dylib)</tt> and link the tools
against it. This saves lots of binary size at the cost of some startup time.
</p>
</div>
<!--=========================================================================-->
<h2><a name="deps">Dependencies</a></h2>
<!--=========================================================================-->
<div>
<dl>
<dt><tt>--enable-libffi</tt></dt><dd>Depend on <a
href="http://sources.redhat.com/libffi/">libffi</a> to allow the LLVM
interpreter to call external functions.</dd>
<dt><tt>--with-oprofile</tt></dt><dd>Depend on <a
href="http://oprofile.sourceforge.net/doc/devel/index.html">libopagent</a>
(>=version 0.9.4) to let the LLVM JIT tell oprofile about function addresses and
line numbers.</dd>
</dl>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

2067
cpp/llvm/docs/Passes.html
View File

File diff suppressed because it is too large Load Diff

4135
cpp/llvm/docs/ProgrammersManual.html
View File

File diff suppressed because it is too large Load Diff

489
cpp/llvm/docs/Projects.html
View File

@ -1,489 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Creating an LLVM Project</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
<h1>Creating an LLVM Project</h1>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#create">Create a project from the Sample Project</a></li>
<li><a href="#source">Source tree layout</a></li>
<li><a href="#makefiles">Writing LLVM-style Makefiles</a>
<ol>
<li><a href="#reqVars">Required Variables</a></li>
<li><a href="#varsBuildDir">Variables for Building Subdirectories</a></li>
<li><a href="#varsBuildLib">Variables for Building Libraries</a></li>
<li><a href="#varsBuildProg">Variables for Building Programs</a></li>
<li><a href="#miscVars">Miscellaneous Variables</a></li>
</ol></li>
<li><a href="#objcode">Placement of object code</a></li>
<li><a href="#help">Further help</a></li>
</ol>
<div class="doc_author">
<p>Written by John Criswell</p>
</div>
<!-- *********************************************************************** -->
<h2><a name="overview">Overview</a></h2>
<!-- *********************************************************************** -->
<div>
<p>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
these facilities, a Makefile from a project must do the following things:</p>
<ol>
<li>Set <tt>make</tt> variables. There are several variables that a Makefile
needs to set to use the LLVM build system:
<ul>
<li><tt>PROJECT_NAME</tt> - The name by which your project is known.</li>
<li><tt>LLVM_SRC_ROOT</tt> - The root of the LLVM source tree.</li>
<li><tt>LLVM_OBJ_ROOT</tt> - The root of the LLVM object tree.</li>
<li><tt>PROJ_SRC_ROOT</tt> - The root of the project's source tree.</li>
<li><tt>PROJ_OBJ_ROOT</tt> - The root of the project's object tree.</li>
<li><tt>PROJ_INSTALL_ROOT</tt> - The root installation directory.</li>
<li><tt>LEVEL</tt> - The relative path from the current directory to the
project's root ($PROJ_OBJ_ROOT).</li>
</ul></li>
<li>Include <tt>Makefile.config</tt> from <tt>$(LLVM_OBJ_ROOT)</tt>.</li>
<li>Include <tt>Makefile.rules</tt> from <tt>$(LLVM_SRC_ROOT)</tt>.</li>
</ol>
<p>There are two ways that you can set all of these variables:</p>
<ol>
<li>You can write your own Makefiles which hard-code these values.</li>
<li>You can use the pre-made LLVM sample project. This sample project
includes Makefiles, a configure script that can be used to configure the
location of LLVM, and the ability to support multiple object directories
from a single source directory.</li>
</ol>
<p>This document assumes that you will base your project on the LLVM sample
project found in <tt>llvm/projects/sample</tt>. If you want to devise your own
build system, studying the sample project and LLVM Makefiles will probably
provide enough information on how to write your own Makefiles.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="create">Create a Project from the Sample Project</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>Follow these simple steps to start your project:</p>
<ol>
<li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
choosing. You can place it anywhere you like. Rename the directory to match
the name of your project.</li>
<li>
If you downloaded LLVM using Subversion, remove all the directories named .svn
(and all the files therein) from your project's new source tree. This will
keep Subversion from thinking that your project is inside
<tt>llvm/trunk/projects/sample</tt>.</li>
<li>Add your source code and Makefiles to your source tree.</li>
<li>If you want your project to be configured with the <tt>configure</tt> script
then you need to edit <tt>autoconf/configure.ac</tt> as follows:
<ul>
<li><b>AC_INIT</b>. Place the name of your project, its version number and
a contact email address for your project as the arguments to this macro</li>
<li><b>AC_CONFIG_AUX_DIR</b>. If your project isn't in the
<tt>llvm/projects</tt> directory then you might need to adjust this so that
it specifies a relative path to the <tt>llvm/autoconf</tt> directory.</li>
<li><b>LLVM_CONFIG_PROJECT</b>. Just leave this alone.</li>
<li><b>AC_CONFIG_SRCDIR</b>. Specify a path to a file name that identifies
your project; or just leave it at <tt>Makefile.common.in</tt></li>
<li><b>AC_CONFIG_FILES</b>. Do not change.</li>
<li><b>AC_CONFIG_MAKEFILE</b>. Use one of these macros for each Makefile
that your project uses. This macro arranges for your makefiles to be copied
from the source directory, unmodified, to the build directory.</li>
</ul>
</li>
<li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
configure script with these commands:
<div class="doc_code">
<p><tt>% cd autoconf<br>
% ./AutoRegen.sh</tt></p>
</div>
<p>You must be using Autoconf version 2.59 or later and your aclocal version
should be 1.9 or later.</p></li>
<li>Run <tt>configure</tt> in the directory in which you want to place
object code. Use the following options to tell your project where it
can find LLVM:
<dl>
<dt><tt>--with-llvmsrc=&lt;directory&gt;</tt></dt>
<dd>Tell your project where the LLVM source tree is located.</dd>
<dt><br><tt>--with-llvmobj=&lt;directory&gt;</tt></dt>
<dd>Tell your project where the LLVM object tree is located.</dd>
<dt><br><tt>--prefix=&lt;directory&gt;</tt></dt>
<dd>Tell your project where it should get installed.</dd>
</dl>
</ol>
<p>That's it! Now all you have to do is type <tt>gmake</tt> (or <tt>make</tt>
if your on a GNU/Linux system) in the root of your object directory, and your
project should build.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="source">Source Tree Layout</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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.
Mainly, you want your source tree layout to look similar to the LLVM
source tree layout. The best way to do this is to just copy the
project tree from <tt>llvm/projects/sample</tt> and modify it to meet
your needs, but you can certainly add to it if you want.</p>
<p>Underneath your top level directory, you should have the following
directories:</p>
<dl>
<dt><b>lib</b>
<dd>
This subdirectory should contain all of your library source
code. For each library that you build, you will have one
directory in <b>lib</b> that will contain that library's source
code.
<p>
Libraries can be object files, archives, or dynamic libraries.
The <b>lib</b> directory is just a convenient place for libraries
as it places them all in a directory from which they can be linked
later.
<dt><b>include</b>
<dd>
This subdirectory should contain any header files that are
global to your project. By global, we mean that they are used
by more than one library or executable of your project.
<p>
By placing your header files in <b>include</b>, they will be
found automatically by the LLVM build system. For example, if
you have a file <b>include/jazz/note.h</b>, then your source
files can include it simply with <b>#include "jazz/note.h"</b>.
<dt><b>tools</b>
<dd>
This subdirectory should contain all of your source
code for executables. For each program that you build, you
will have one directory in <b>tools</b> that will contain that
program's source code.
<p>
<dt><b>test</b>
<dd>
This subdirectory should contain tests that verify that your code
works correctly. Automated tests are especially useful.
<p>
Currently, the LLVM build system provides basic support for tests.
The LLVM system provides the following:
<ul>
<li>
LLVM provides a tcl procedure that is used by Dejagnu to run
tests. It can be found in <tt>llvm/lib/llvm-dg.exp</tt>. This
test procedure uses RUN lines in the actual test case to determine
how to run the test. See the <a
href="TestingGuide.html">TestingGuide</a> for more details. You
can easily write Makefile support similar to the Makefiles in
<tt>llvm/test</tt> to use Dejagnu to run your project's tests.<br></li>
<li>
LLVM contains an optional package called <tt>llvm-test</tt>
which provides benchmarks and programs that are known to compile with the
LLVM GCC front ends. You can use these
programs to test your code, gather statistics information, and
compare it to the current LLVM performance statistics.
<br>Currently, there is no way to hook your tests directly into the
<tt>llvm/test</tt> testing harness. You will simply
need to find a way to use the source provided within that directory
on your own.
</ul>
</dl>
<p>Typically, you will want to build your <b>lib</b> directory first followed by
your <b>tools</b> directory.</p>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="makefiles">Writing LLVM Style Makefiles</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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:</p>
<!-- ======================================================================= -->
<h3>
<a name="reqVars">Required Variables</a>
</h3>
<div>
<dl>
<dt>LEVEL
<dd>
This variable is the relative path from this Makefile to the
top directory of your project's source code. For example, if
your source code is in <tt>/tmp/src</tt>, then the Makefile in
<tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="varsBuildDir">Variables for Building Subdirectories</a>
</h3>
<div>
<dl>
<dt>DIRS
<dd>
This is a space separated list of subdirectories that should be
built. They will be built, one at a time, in the order
specified.
<p>
<dt>PARALLEL_DIRS
<dd>
This is a list of directories that can be built in parallel.
These will be built after the directories in DIRS have been
built.
<p>
<dt>OPTIONAL_DIRS
<dd>
This is a list of directories that can be built if they exist,
but will not cause an error if they do not exist. They are
built serially in the order in which they are listed.
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="varsBuildLib">Variables for Building Libraries</a>
</h3>
<div>
<dl>
<dt>LIBRARYNAME
<dd>
This variable contains the base name of the library that will
be built. For example, to build a library named
<tt>libsample.a</tt>, LIBRARYNAME should be set to
<tt>sample</tt>.
<p>
<dt>BUILD_ARCHIVE
<dd>
By default, a library is a <tt>.o</tt> file that is linked
directly into a program. To build an archive (also known as
a static library), set the BUILD_ARCHIVE variable.
<p>
<dt>SHARED_LIBRARY
<dd>
If SHARED_LIBRARY is defined in your Makefile, a shared
(or dynamic) library will be built.
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="varsBuildProg">Variables for Building Programs</a>
</h3>
<div>
<dl>
<dt>TOOLNAME
<dd>
This variable contains the name of the program that will
be built. For example, to build an executable named
<tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
<p>
<dt>USEDLIBS
<dd>
This variable holds a space separated list of libraries that should
be linked into the program. These libraries must be libraries that
come from your <b>lib</b> directory. The libraries must be
specified without their "lib" prefix. For example, to link
libsample.a, you would set USEDLIBS to
<tt>sample.a</tt>.
<p>
Note that this works only for statically linked libraries.
<p>
<dt>LLVMLIBS
<dd>
This variable holds a space separated list of libraries that should
be linked into the program. These libraries must be LLVM libraries.
The libraries must be specified without their "lib" prefix. For
example, to link with a driver that performs an IR transformation
you might set LLVMLIBS to this minimal set of libraries
<tt>LLVMSupport.a LLVMCore.a LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a LLVMScalarOpts.a LLVMTarget.a</tt>.
<p>
Note that this works only for statically linked libraries. LLVM is
split into a large number of static libraries, and the list of libraries you
require may be much longer than the list above. To see a full list
of libraries use:
<tt>llvm-config --libs all</tt>.
Using LINK_COMPONENTS as described below, obviates the need to set LLVMLIBS.
<p>
<dt>LINK_COMPONENTS
<dd>This variable holds a space separated list of components that
the LLVM Makefiles pass to the <tt>llvm-config</tt> tool to generate
a link line for the program. For example, to link with all LLVM
libraries use
<tt>LINK_COMPONENTS = all</tt>.
<p>
<dt>LIBS
<dd>
To link dynamic libraries, add <tt>-l&lt;library base name&gt;</tt> to
the LIBS variable. The LLVM build system will look in the same places
for dynamic libraries as it does for static libraries.
<p>
For example, to link <tt>libsample.so</tt>, you would have the
following line in your <tt>Makefile</tt>:
<p>
<tt>
LIBS += -lsample
</tt>
<p>
Note that LIBS must occur in the Makefile after the inclusion of Makefile.common.
<p>
</dl>
</div>
<!-- ======================================================================= -->
<h3>
<a name="miscVars">Miscellaneous Variables</a>
</h3>
<div>
<dl>
<dt>ExtraSource
<dd>
This variable contains a space separated list of extra source
files that need to be built. It is useful for including the
output of Lex and Yacc programs.
<p>
<dt>CFLAGS
<dt>CPPFLAGS
<dd>
This variable can be used to add options to the C and C++
compiler, respectively. It is typically used to add options
that tell the compiler the location of additional directories
to search for header files.
<p>
It is highly suggested that you append to CFLAGS and CPPFLAGS as
opposed to overwriting them. The master Makefiles may already
have useful options in them that you may not want to overwrite.
<p>
</dl>
</div>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="objcode">Placement of Object Code</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>The final location of built libraries and executables will depend upon
whether you do a Debug, Release, or Profile build.</p>
<dl>
<dt>Libraries
<dd>
All libraries (static and dynamic) will be stored in
<tt>PROJ_OBJ_ROOT/&lt;type&gt;/lib</tt>, where type is <tt>Debug</tt>,
<tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or
profiled build, respectively.<p>
<dt>Executables
<dd>All executables will be stored in
<tt>PROJ_OBJ_ROOT/&lt;type&gt;/bin</tt>, where type is <tt>Debug</tt>,
<tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
build, respectively.
</dl>
</div>
<!-- *********************************************************************** -->
<h2>
<a name="help">Further Help</a>
</h2>
<!-- *********************************************************************** -->
<div>
<p>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
questions to the <a
href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
Mailing List</a>.</p>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date: 2011-10-31 04:21:59 -0700 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

Some files were not shown because too many files have changed in this diff Show More