d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Vendor import of llvm trunk r161861:

Browse Source 
http://llvm.org/svn/llvm-project/llvm/trunk@161861
This commit is contained in:
Dimitry Andric 2012-08-15 19:34:23 +00:00
parent 0378662f5b
commit 58b69754af
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/vendor/llvm/dist/; revision=239310
svn path=/vendor/llvm/llvm-trunk-r161861/; revision=239311; tag=vendor/llvm/llvm-trunk-r161861
2874 changed files with 137453 additions and 73078 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -40,3 +40,7 @@ projects/*
tools/clang
# LLDB, which is tracked independently.
tools/lldb
# lld, which is tracked independently.
tools/lld
# Sphinx build tree, if building in-source dir.
docs/_build

33
CMakeLists.txt
View File

@ -11,11 +11,14 @@ set(CMAKE_MODULE_PATH
)
set(LLVM_VERSION_MAJOR 3)
set(LLVM_VERSION_MINOR 1)
set(LLVM_VERSION_MINOR 2)
set(PACKAGE_VERSION "${LLVM_VERSION_MAJOR}.${LLVM_VERSION_MINOR}svn")
set_property(GLOBAL PROPERTY USE_FOLDERS ON)
option(LLVM_USE_FOLDERS "Enable solution folders in Visual Studio. Disable for Express versions." ON)
if ( LLVM_USE_FOLDERS )
set_property(GLOBAL PROPERTY USE_FOLDERS ON)
endif()
include(VersionFromVCS)
@ -78,8 +81,8 @@ set(LLVM_ALL_TARGETS
Mips
MBlaze
MSP430
NVPTX
PowerPC
PTX
Sparc
X86
XCore
@ -96,6 +99,9 @@ else( MSVC )
CACHE STRING "Semicolon-separated list of targets to build, or \"all\".")
endif( MSVC )
set(LLVM_EXPERIMENTAL_TARGETS_TO_BUILD ""
CACHE STRING "Semicolon-separated list of experimental targets to build.")
option(BUILD_SHARED_LIBS
"Build all libraries as shared libraries instead of static" OFF)
@ -133,6 +139,11 @@ foreach(c ${LLVM_TARGETS_TO_BUILD})
endif()
endforeach(c)
set(LLVM_TARGETS_TO_BUILD
${LLVM_TARGETS_TO_BUILD}
${LLVM_EXPERIMENTAL_TARGETS_TO_BUILD}
)
set(llvm_builded_incs_dir ${LLVM_BINARY_DIR}/include/llvm)
include(AddLLVMDefinitions)
@ -398,6 +409,8 @@ add_subdirectory(utils/count)
add_subdirectory(utils/not)
add_subdirectory(utils/llvm-lit)
add_subdirectory(utils/yaml-bench)
add_subdirectory(utils/obj2yaml)
add_subdirectory(utils/yaml2obj)
add_subdirectory(projects)
@ -422,6 +435,20 @@ if( LLVM_INCLUDE_TESTS )
# Windows.
add_subdirectory(utils/KillTheDoctor)
endif()
# Add a global check rule now that all subdirectories have been traversed
# and we know the total set of lit testsuites.
get_property(LLVM_LIT_TESTSUITES GLOBAL PROPERTY LLVM_LIT_TESTSUITES)
get_property(LLVM_LIT_PARAMS GLOBAL PROPERTY LLVM_LIT_PARAMS)
get_property(LLVM_LIT_DEPENDS GLOBAL PROPERTY LLVM_LIT_DEPENDS)
get_property(LLVM_LIT_EXTRA_ARGS GLOBAL PROPERTY LLVM_LIT_EXTRA_ARGS)
add_lit_target(check-all
"Running all regression tests"
${LLVM_LIT_TESTSUITES}
PARAMS ${LLVM_LIT_PARAMS}
DEPENDS ${LLVM_LIT_DEPENDS}
ARGS ${LLVM_LIT_EXTRA_ARGS}
)
endif()
add_subdirectory(cmake/modules)

51
CODE_OWNERS.TXT Normal file
View File

@ -0,0 +1,51 @@
This file is a list of the people responsible for ensuring that patches for a
particular part of LLVM are reviewed, either by themself or by someone else.
They are also the gatekeepers for their part of LLVM, with the final word on
what goes in or not.
The list is sorted by surname and formatted to allow easy grepping and
beautification by scripts. The fields are: name (N), email (E), web-address
(W), PGP key ID and fingerprint (P), description (D), and snail-mail address
(S).
N: Evan Cheng
E: evan.cheng@apple.com
D: Code generator and all targets
N: Greg Clayton
D: LLDB
N: Peter Collingbourne
D: libclc
N: Doug Gregor
D: Clang Frontend Libraries
N: Tobias Grosser
D: Polly
N: Howard Hinnant
D: libc++
N: Anton Korobeynikov
E: asl@math.spbu.ru
D: Exception handling, debug information, and Windows codegen
N: Ted Kremenek
D: Clang Static Analyzer
N: Chris Lattner
E: sabre@nondot.org
W: http://nondot.org/~sabre/
D: Everything not covered by someone else
N: John McCall
E: rjmccall@apple.com
D: Clang LLVM IR generation
N: Jakob Olesen
D: Register allocators and TableGen
N: Duncan Sands
E: baldrick@free.fr
D: DragonEgg

8
CREDITS.TXT
View File

@ -22,6 +22,10 @@ D: GVNPRE pass, TargetData refactoring, random improvements
N: Henrik Bach
D: MingW Win32 API portability layer
N: Aaron Ballman
E: aaron@aaronballman.com
D: __declspec attributes, Windows support, general bug fixing
N: Nate Begeman
E: natebegeman@mac.com
D: PowerPC backend developer
@ -342,6 +346,10 @@ W: http://vladimir_prus.blogspot.com
E: ghost@cs.msu.su
D: Made inst_iterator behave like a proper iterator, LowerConstantExprs pass
N: Kalle Raiskila
E: kalle.rasikila@nokia.com
D: Some bugfixes to CellSPU
N: Xerxes Ranby
E: xerxes@zafena.se
D: Cmake dependency chain and various bug fixes

3
Makefile.common
View File

@ -30,8 +30,7 @@
#
# 4. Source - If specified, this sets the source code filenames. If this
# is not set, it defaults to be all of the .cpp, .c, .y, and .l files
# in the current directory. Also, if you want to build files in addition
# to the local files, you can use the ExtraSource variable
# in the current directory.
#
# 5. SourceDir - If specified, this specifies a directory that the source files
# are in, if they are not in the current directory. This should include a

14
Makefile.config.in
View File

@ -112,6 +112,8 @@ HOST_OS=@HOST_OS@
# Target operating system for which LLVM will compile for.
TARGET_OS=@TARGET_OS@
# Host hardware architecture
HOST_ARCH=@HOST_ARCH@
# Target hardware architecture
ARCH=@ARCH@
TARGET_NATIVE_ARCH := $(ARCH)
@ -189,8 +191,6 @@ GAS := @GAS@
POD2HTML := @POD2HTML@
POD2MAN := @POD2MAN@
PDFROFF := @PDFROFF@
RUNTEST := @RUNTEST@
TCLSH := @TCLSH@
ZIP := @ZIP@
HAVE_PTHREAD := @HAVE_PTHREAD@
@ -218,6 +218,12 @@ RDYNAMIC := @RDYNAMIC@
#ENABLE_LIBCPP = 0
ENABLE_LIBCPP = @ENABLE_LIBCPP@
# When ENABLE_CXX11 is enabled, LLVM uses c++11 mode by default to build.
ENABLE_CXX11 = @ENABLE_CXX11@
# When ENABLE_WERROR is enabled, we'll pass -Werror on the command line
ENABLE_WERROR = @ENABLE_WERROR@
# When ENABLE_OPTIMIZED is enabled, LLVM code is optimized and output is put
# into the "Release" directories. Otherwise, LLVM code is not optimized and
# output is put in the "Debug" directories.
@ -344,6 +350,10 @@ LLVM_HAS_POLLY = @LLVM_HAS_POLLY@
# bfd ld / gold --version-script=file
HAVE_LINK_VERSION_SCRIPT = @HAVE_LINK_VERSION_SCRIPT@
# Flags to control using libxml2
LIBXML2_LIBS := @LIBXML2_LIBS@
LIBXML2_INC := @LIBXML2_INC@
# Flags to control building support for Intel JIT Events API
USE_INTEL_JITEVENTS := @USE_INTEL_JITEVENTS@
INTEL_JITEVENTS_INCDIR := @INTEL_JITEVENTS_INCDIR@

36
Makefile.rules
View File

@ -317,6 +317,15 @@ ifeq ($(ENABLE_LIBCPP),1)
LD.Flags += -stdlib=libc++
endif
ifeq ($(ENABLE_CXX11),1)
CXX.Flags += -std=c++11
endif
ifeq ($(ENABLE_WERROR),1)
CXX.Flags += -Werror
C.Flags += -Werror
endif
ifeq ($(ENABLE_PROFILING),1)
BuildMode := $(BuildMode)+Profile
CXX.Flags := $(filter-out -fomit-frame-pointer,$(CXX.Flags)) -pg -g
@ -538,9 +547,6 @@ ifeq ($(LLVM_CROSS_COMPILING),1)
else
LLVM_CONFIG := $(LLVMToolDir)/llvm-config$(EXEEXT)
endif
ifndef LLVMLD
LLVMLD := $(LLVMToolDir)/llvm-ld$(EXEEXT)
endif
ifndef LLVMDIS
LLVMDIS := $(LLVMToolDir)/llvm-dis$(EXEEXT)
endif
@ -556,6 +562,9 @@ endif
ifndef LBUGPOINT
LBUGPOINT := $(LLVMToolDir)/bugpoint$(EXEEXT)
endif
ifndef LLVMLINK
LLVMLINK := $(LLVMToolDir)/llvm-link$(EXEEXT)
endif
#--------------------------------------------------------------------
# Adjust to user's request
@ -1134,14 +1143,14 @@ $(warning Modules require LLVM capable compiler but none is available ****)
else
Module := $(LibDir)/$(MODULE_NAME).bc
LinkModule := $(LLVMLD) -r
LinkModule := $(LLVMLINK)
ifdef EXPORTED_SYMBOL_FILE
LinkModule += -internalize-public-api-file=$(EXPORTED_SYMBOL_FILE)
endif
$(Module): $(BUILT_SOURCES) $(ObjectsBC) $(LibDir)/.dir $(LLVMLD)
$(Module): $(BUILT_SOURCES) $(ObjectsBC) $(LibDir)/.dir $(LLVMLINK)
$(Echo) Building $(BuildMode) Bytecode Module $(notdir $@)
$(Verb) $(LinkModule) -o $@ $(ObjectsBC)
@ -1276,9 +1285,9 @@ else
all-local:: $(LibName.BCA)
ifdef EXPORTED_SYMBOL_FILE
BCLinkLib = $(LLVMLD) -internalize-public-api-file=$(EXPORTED_SYMBOL_FILE)
BCLinkLib = $(LLVMLINK) -internalize-public-api-file=$(EXPORTED_SYMBOL_FILE)
$(LibName.BCA): $(ObjectsBC) $(LibDir)/.dir $(LLVMLD) \
$(LibName.BCA): $(ObjectsBC) $(LibDir)/.dir $(LLVMLINK) \
$(LLVMToolDir)/llvm-ar
$(Echo) Building $(BuildMode) Bytecode Archive $(notdir $@) \
"(internalize)"
@ -1964,20 +1973,9 @@ check::
$(EchoCmd) No test directory ; \
fi
# An alias dating from when both lit and DejaGNU test runners were used.
check-lit:: check
check-dg::
$(Verb) if test -d "$(PROJ_OBJ_ROOT)/test" ; then \
if test -f "$(PROJ_OBJ_ROOT)/test/Makefile" ; then \
$(EchoCmd) Running test suite ; \
$(MAKE) -C $(PROJ_OBJ_ROOT)/test check-local-dg ; \
else \
$(EchoCmd) No Makefile in test directory ; \
fi ; \
else \
$(EchoCmd) No test directory ; \
fi
check-all::
$(Verb) if test -d "$(PROJ_OBJ_ROOT)/test" ; then \
if test -f "$(PROJ_OBJ_ROOT)/test/Makefile" ; then \

1
README.txt
View File

@ -1,4 +1,3 @@
Low Level Virtual Machine (LLVM)
================================

4
autoconf/config.guess vendored
View File

@ -206,6 +206,10 @@ case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in
UNAME_MACHINE_ARCH=`arch | sed 's/OpenBSD.//'`
echo ${UNAME_MACHINE_ARCH}-unknown-openbsd${UNAME_RELEASE}
exit ;;
*:Bitrig:*:*)
UNAME_MACHINE_ARCH=`arch | sed 's/Bitrig.//'`
echo ${UNAME_MACHINE_ARCH}-unknown-bitrig${UNAME_RELEASE}
exit ;;
*:ekkoBSD:*:*)
echo ${UNAME_MACHINE}-unknown-ekkobsd${UNAME_RELEASE}
exit ;;

100
autoconf/configure.ac
View File

@ -31,9 +31,9 @@ dnl===
dnl===-----------------------------------------------------------------------===
dnl Initialize autoconf and define the package name, version number and
dnl address for reporting bugs.
AC_INIT([LLVM],[3.1],[http://llvm.org/bugs/])
AC_INIT([LLVM],[3.2svn],[http://llvm.org/bugs/])
AC_DEFINE([LLVM_VERSION_MAJOR], [3], [Major version of the LLVM API])
AC_DEFINE([LLVM_VERSION_MINOR], [1], [Minor version of the LLVM API])
AC_DEFINE([LLVM_VERSION_MINOR], [2], [Minor version of the LLVM API])
dnl Provide a copyright substitution and ensure the copyright notice is included
dnl in the output of --version option of the generated configure script.
@ -369,7 +369,7 @@ AC_CACHE_CHECK([target architecture],[llvm_cv_target_arch],
msp430-*) llvm_cv_target_arch="MSP430" ;;
hexagon-*) llvm_cv_target_arch="Hexagon" ;;
mblaze-*) llvm_cv_target_arch="MBlaze" ;;
ptx-*) llvm_cv_target_arch="PTX" ;;
nvptx-*) llvm_cv_target_arch="NVPTX" ;;
*) llvm_cv_target_arch="Unknown" ;;
esac])
@ -387,6 +387,30 @@ esac
dnl Define a substitution, ARCH, for the target architecture
AC_SUBST(ARCH,$llvm_cv_target_arch)
dnl Determine what our host architecture.
dnl This will allow MCJIT regress tests runs only for supported
dnl platforms.
case $host in
i?86-*) host_arch="x86" ;;
amd64-* | x86_64-*) host_arch="x86_64" ;;
sparc*-*) host_arch="Sparc" ;;
powerpc*-*) host_arch="PowerPC" ;;
arm*-*) host_arch="ARM" ;;
mips-*) host_arch="Mips" ;;
mipsel-*) host_arch="Mips" ;;
xcore-*) host_arch="XCore" ;;
msp430-*) host_arch="MSP430" ;;
hexagon-*) host_arch="Hexagon" ;;
mblaze-*) host_arch="MBlaze" ;;
*) host_arch="Unknown" ;;
esac
if test "$host_arch" = "Unknown" ; then
AC_MSG_WARN([Configuring LLVM for an unknown host archicture])
fi
AC_SUBST(HOST_ARCH,$host_arch)
dnl Check for the endianness of the target
AC_C_BIGENDIAN(AC_SUBST([ENDIAN],[big]),AC_SUBST([ENDIAN],[little]))
@ -439,6 +463,18 @@ case "$enableval" in
*) AC_MSG_ERROR([Invalid setting for --enable-libcpp. Use "yes" or "no"]) ;;
esac
dnl --enable-cxx11 : check whether or not to use -std=c++11 on the command line
AC_ARG_ENABLE(cxx11,
AS_HELP_STRING([--enable-cxx11],
[Use c++11 if available (default is NO)]),,
enableval=default)
case "$enableval" in
yes) AC_SUBST(ENABLE_CXX11,[1]) ;;
no) AC_SUBST(ENABLE_CXX11,[0]) ;;
default) AC_SUBST(ENABLE_CXX11,[0]);;
*) AC_MSG_ERROR([Invalid setting for --enable-cxx11. Use "yes" or "no"]) ;;
esac
dnl --enable-optimized : check whether they want to do an optimized build:
AC_ARG_ENABLE(optimized, AS_HELP_STRING(
--enable-optimized,[Compile with optimizations enabled (default is NO)]),,enableval=$optimize)
@ -466,6 +502,16 @@ else
AC_SUBST(DISABLE_ASSERTIONS,[[DISABLE_ASSERTIONS=1]])
fi
dnl --enable-werror : check whether we want Werror on by default
AC_ARG_ENABLE(werror,AS_HELP_STRING(
--enable-werror,[Compile with -Werror enabled (default is NO)]),, enableval="no")
case "$enableval" in
yes) AC_SUBST(ENABLE_WERROR,[1]) ;;
no) AC_SUBST(ENABLE_WERROR,[0]) ;;
default) AC_SUBST(ENABLE_WERROR,[0]);;
*) AC_MSG_ERROR([Invalid setting for --enable-werror. Use "yes" or "no"]) ;;
esac
dnl --enable-expensive-checks : check whether they want to turn on expensive debug checks:
AC_ARG_ENABLE(expensive-checks,AS_HELP_STRING(
--enable-expensive-checks,[Compile with expensive debug checks enabled (default is NO)]),, enableval="no")
@ -516,7 +562,7 @@ else
MSP430) AC_SUBST(TARGET_HAS_JIT,0) ;;
Hexagon) AC_SUBST(TARGET_HAS_JIT,0) ;;
MBlaze) AC_SUBST(TARGET_HAS_JIT,0) ;;
PTX) AC_SUBST(TARGET_HAS_JIT,0) ;;
NVPTX) AC_SUBST(TARGET_HAS_JIT,0) ;;
*) AC_SUBST(TARGET_HAS_JIT,0) ;;
esac
fi
@ -621,20 +667,20 @@ case "$enableval" in
*) AC_MSG_ERROR([Invalid setting for --enable-timestamps. Use "yes" or "no"]) ;;
esac
AC_DEFINE_UNQUOTED([ENABLE_TIMESTAMPS],$ENABLE_TIMESTAMPS,
[Define if timestamp information (e.g., __DATE___) is allowed])
[Define if timestamp information (e.g., __DATE__) is allowed])
dnl Allow specific targets to be specified for building (or not)
TARGETS_TO_BUILD=""
AC_ARG_ENABLE([targets],AS_HELP_STRING([--enable-targets],
[Build specific host targets: all or target1,target2,... Valid targets are:
host, x86, x86_64, sparc, powerpc, arm, mips, spu, hexagon,
xcore, msp430, ptx, and cpp (default=all)]),,
xcore, msp430, nvptx, and cpp (default=all)]),,
enableval=all)
if test "$enableval" = host-only ; then
enableval=host
fi
case "$enableval" in
all) TARGETS_TO_BUILD="X86 Sparc PowerPC ARM Mips CellSPU XCore MSP430 CppBackend MBlaze PTX Hexagon" ;;
all) TARGETS_TO_BUILD="X86 Sparc PowerPC ARM Mips CellSPU XCore MSP430 CppBackend MBlaze NVPTX Hexagon" ;;
*)for a_target in `echo $enableval|sed -e 's/,/ /g' ` ; do
case "$a_target" in
x86) TARGETS_TO_BUILD="X86 $TARGETS_TO_BUILD" ;;
@ -650,7 +696,7 @@ case "$enableval" in
cpp) TARGETS_TO_BUILD="CppBackend $TARGETS_TO_BUILD" ;;
hexagon) TARGETS_TO_BUILD="Hexagon $TARGETS_TO_BUILD" ;;
mblaze) TARGETS_TO_BUILD="MBlaze $TARGETS_TO_BUILD" ;;
ptx) TARGETS_TO_BUILD="PTX $TARGETS_TO_BUILD" ;;
nvptx) TARGETS_TO_BUILD="NVPTX $TARGETS_TO_BUILD" ;;
host) case "$llvm_cv_target_arch" in
x86) TARGETS_TO_BUILD="X86 $TARGETS_TO_BUILD" ;;
x86_64) TARGETS_TO_BUILD="X86 $TARGETS_TO_BUILD" ;;
@ -663,7 +709,7 @@ case "$enableval" in
XCore) TARGETS_TO_BUILD="XCore $TARGETS_TO_BUILD" ;;
MSP430) TARGETS_TO_BUILD="MSP430 $TARGETS_TO_BUILD" ;;
Hexagon) TARGETS_TO_BUILD="Hexagon $TARGETS_TO_BUILD" ;;
PTX) TARGETS_TO_BUILD="PTX $TARGETS_TO_BUILD" ;;
NVPTX) TARGETS_TO_BUILD="NVPTX $TARGETS_TO_BUILD" ;;
*) AC_MSG_ERROR([Can not set target to build]) ;;
esac ;;
*) AC_MSG_ERROR([Unrecognized target $a_target]) ;;
@ -671,6 +717,17 @@ case "$enableval" in
done
;;
esac
AC_ARG_ENABLE([experimental-targets],AS_HELP_STRING([--enable-experimental-targets],
[Build experimental host targets: disable or target1,target2,...
(default=disable)]),,
enableval=disable)
if test ${enableval} != "disable"
then
TARGETS_TO_BUILD="$enableval $TARGETS_TO_BUILD"
fi
AC_SUBST(TARGETS_TO_BUILD,$TARGETS_TO_BUILD)
dnl Determine whether we are building LLVM support for the native architecture.
@ -1024,11 +1081,7 @@ AC_PATH_PROG(CAT, [cat])
AC_PATH_PROG(DOXYGEN, [doxygen])
AC_PATH_PROG(GROFF, [groff])
AC_PATH_PROG(GZIPBIN, [gzip])
AC_PATH_PROG(POD2HTML, [pod2html])
AC_PATH_PROG(POD2MAN, [pod2man])
AC_PATH_PROG(PDFROFF, [pdfroff])
AC_PATH_PROG(RUNTEST, [runtest])
DJ_AC_PATH_TCLSH
AC_PATH_PROG(ZIP, [zip])
AC_PATH_PROGS(OCAMLC, [ocamlc])
AC_PATH_PROGS(OCAMLOPT, [ocamlopt])
@ -1260,6 +1313,23 @@ AC_ARG_WITH(intel-jitevents,
AC_DEFINE_UNQUOTED([LLVM_USE_INTEL_JITEVENTS],$USE_INTEL_JITEVENTS,
[Define if we have the Intel JIT API runtime support library])
dnl Check for libxml2
dnl Right now we're just checking for the existence, we could also check for a
dnl particular version via --version on xml2-config
AC_CHECK_PROGS(XML2CONFIG, xml2-config)
AC_MSG_CHECKING(for libxml2 includes)
if test "x$XML2CONFIG" = "x"; then
AC_MSG_RESULT(xml2-config not found)
else
LIBXML2_INC=`$XML2CONFIG --cflags`
AC_MSG_RESULT($LIBXML2_INC)
AC_CHECK_LIB(xml2, xmlReadFile,[AC_DEFINE([CLANG_HAVE_LIBXML],1,[Define if we have libxml2])
LIBXML2_LIBS="-lxml2"])
fi
AC_SUBST(LIBXML2_LIBS)
AC_SUBST(LIBXML2_INC)
dnl===-----------------------------------------------------------------------===
dnl===
dnl=== SECTION 6: Check for header files
@ -1342,7 +1412,7 @@ AC_CHECK_FUNCS([powf fmodf strtof round ])
AC_CHECK_FUNCS([getpagesize getrusage getrlimit setrlimit gettimeofday ])
AC_CHECK_FUNCS([isatty mkdtemp mkstemp ])
AC_CHECK_FUNCS([mktemp posix_spawn pread realpath sbrk setrlimit strdup ])
AC_CHECK_FUNCS([strerror strerror_r setenv ])
AC_CHECK_FUNCS([strerror strerror_r setenv arc4random ])
AC_CHECK_FUNCS([strtoll strtoq sysconf malloc_zone_statistics ])
AC_CHECK_FUNCS([setjmp longjmp sigsetjmp siglongjmp writev])
AC_C_PRINTF_A
@ -1518,6 +1588,8 @@ AC_DEFINE_UNQUOTED(LLVM_MANDIR, "$LLVM_MANDIR",
[Installation directory for man pages])
AC_DEFINE_UNQUOTED(LLVM_CONFIGTIME, "$LLVM_CONFIGTIME",
[Time at which LLVM was configured])
AC_DEFINE_UNQUOTED(LLVM_HOSTTRIPLE, "$host",
[Host triple LLVM will be executed on])
AC_DEFINE_UNQUOTED(LLVM_DEFAULT_TARGET_TRIPLE, "$target",
[Target triple LLVM will generate code for by default])

6
autoconf/ltmain.sh
View File

@ -1560,7 +1560,7 @@ EOF
# These systems don't actually have a C library (as such)
test "X$arg" = "X-lc" && continue
;;
*-*-openbsd* | *-*-freebsd* | *-*-dragonfly*)
*-*-openbsd* | *-*-freebsd* | *-*-dragonfly* | *-*-bitrig*)
# Do not include libc due to us having libc/libc_r.
test "X$arg" = "X-lc" && continue
;;
@ -1580,7 +1580,7 @@ EOF
esac
elif test "X$arg" = "X-lc_r"; then
case $host in
*-*-openbsd* | *-*-freebsd* | *-*-dragonfly*)
*-*-openbsd* | *-*-freebsd* | *-*-dragonfly* | -*-*-bitrig*)
# Do not include libc_r directly, use -pthread flag.
continue
;;
@ -3464,7 +3464,7 @@ EOF
*-*-netbsd*)
# Don't link with libc until the a.out ld.so is fixed.
;;
*-*-openbsd* | *-*-freebsd* | *-*-dragonfly*)
*-*-openbsd* | *-*-freebsd* | *-*-dragonfly* | *-*-bitrig*)
# Do not include libc due to us having libc/libc_r.
;;
*-*-sco3.2v5* | *-*-sco5v6*)

2
autoconf/m4/func_isinf.m4
View File

@ -1,5 +1,5 @@
#
# This function determins if the the isinf function isavailable on this
# This function determins if the isinf function isavailable on this
# platform.
#
AC_DEFUN([AC_FUNC_ISINF],[

2
autoconf/m4/huge_val.m4
View File

@ -1,5 +1,5 @@
#
# This function determins if the the HUGE_VAL macro is compilable with the
# This function determins if the HUGE_VAL macro is compilable with the
# -pedantic switch or not. XCode < 2.4.1 doesn't get it right.
#
AC_DEFUN([AC_HUGE_VAL_CHECK],[

10
autoconf/m4/libtool.m4 vendored
View File

@ -176,7 +176,7 @@ old_postuninstall_cmds=
if test -n "$RANLIB"; then
case $host_os in
openbsd*)
openbsd* | bitrig*)
old_postinstall_cmds="$old_postinstall_cmds~\$RANLIB -t \$oldlib"
;;
*)
@ -729,7 +729,7 @@ AC_CACHE_VAL([lt_cv_sys_max_cmd_len], [dnl
lt_cv_sys_max_cmd_len=8192;
;;
netbsd* | freebsd* | openbsd* | darwin* | dragonfly*)
netbsd* | freebsd* | openbsd* | darwin* | dragonfly* | bitrig*)
# This has been around since 386BSD, at least. Likely further.
if test -x /sbin/sysctl; then
lt_cv_sys_max_cmd_len=`/sbin/sysctl -n kern.argmax`
@ -1631,7 +1631,7 @@ nto-qnx*)
shlibpath_overrides_runpath=yes
;;
openbsd*)
openbsd* | bitrig*)
version_type=sunos
sys_lib_dlsearch_path_spec="/usr/lib"
need_lib_prefix=no
@ -3382,7 +3382,7 @@ case $host_os in
# C++ shared libraries are fairly broken
_LT_AC_TAGVAR(ld_shlibs, $1)=no
;;
openbsd*)
openbsd* | bitrig*)
_LT_AC_TAGVAR(hardcode_direct, $1)=yes
_LT_AC_TAGVAR(hardcode_shlibpath_var, $1)=no
_LT_AC_TAGVAR(archive_cmds, $1)='$CC -shared $pic_flag $predep_objects $libobjs $deplibs $postdep_objects $compiler_flags -o $lib'
@ -6003,7 +6003,7 @@ _LT_EOF
_LT_AC_TAGVAR(hardcode_shlibpath_var, $1)=no
;;
openbsd*)
openbsd* | bitrig*)
_LT_AC_TAGVAR(hardcode_direct, $1)=yes
_LT_AC_TAGVAR(hardcode_shlibpath_var, $1)=no
if test -z "`echo __ELF__ | $CC -E - | grep __ELF__`" || test "$host_os-$host_cpu" = "openbsd2.8-powerpc"; then

2
autoconf/m4/rand48.m4
View File

@ -1,5 +1,5 @@
#
# This function determins if the the srand48,drand48,lrand48 functions are
# This function determins if the srand48,drand48,lrand48 functions are
# available on this platform.
#
AC_DEFUN([AC_FUNC_RAND48],[

5
bindings/ocaml/bitreader/llvm_bitreader.mli
View File

@ -23,7 +23,6 @@ val get_module : Llvm.llcontext -> Llvm.llmemorybuffer -> Llvm.llmodule
(** [parse_bitcode context mb] parses the bitcode for a new module [m] from the
memory buffer [mb] in the context [context]. Returns [m] if successful, or
raises [Error msg] otherwise, where [msg] is a description of the error
encountered. See the function [llvm::ParseBitcodeFile]. *)
raises [Error msg] otherwise, where [msg] is a description of the error
encountered. See the function [llvm::ParseBitcodeFile]. *)
val parse_bitcode : Llvm.llcontext -> Llvm.llmemorybuffer -> Llvm.llmodule

2
bindings/ocaml/transforms/scalar/scalar_opts_ocaml.c
View File

@ -57,7 +57,7 @@ CAMLprim value llvm_add_scalar_repl_aggregation_ssa(LLVMPassManagerRef PM) {
/* [<Llvm.PassManager.any] Llvm.PassManager.t -> int -> unit */
CAMLprim value llvm_add_scalar_repl_aggregation_with_threshold(value threshold,
LLVMPassManagerRef PM) {
LLVMPassManagerRef PM) {
LLVMAddScalarReplAggregatesPassWithThreshold(PM, Int_val(threshold));
return Val_unit;
}

3
cmake/config-ix.cmake
View File

@ -91,6 +91,7 @@ if( NOT PURE_WINDOWS )
endif()
# function checks
check_symbol_exists(arc4random "stdlib.h" HAVE_ARC4RANDOM)
check_symbol_exists(getpagesize unistd.h HAVE_GETPAGESIZE)
check_symbol_exists(getrusage sys/resource.h HAVE_GETRUSAGE)
check_symbol_exists(setrlimit sys/resource.h HAVE_SETRLIMIT)
@ -240,6 +241,7 @@ llvm_find_program(fdp)
llvm_find_program(dot)
llvm_find_program(dotty)
llvm_find_program(xdot.py)
llvm_find_program(Graphviz)
if( LLVM_ENABLE_FFI )
find_path(FFI_INCLUDE_PATH ffi.h PATHS ${FFI_INCLUDE_DIR})
@ -293,6 +295,7 @@ get_host_triple(LLVM_HOST_TRIPLE)
# By default, we target the host, but this can be overridden at CMake
# invocation time.
set(LLVM_DEFAULT_TARGET_TRIPLE "${LLVM_HOST_TRIPLE}")
set(LLVM_HOSTTRIPLE "${LLVM_HOST_TRIPLE}")
set(TARGET_TRIPLE "${LLVM_DEFAULT_TARGET_TRIPLE}")
# Determine the native architecture.

168
cmake/modules/AddLLVM.cmake
View File

@ -1,3 +1,4 @@
include(LLVMParseArguments)
include(LLVMProcessSources)
include(LLVM-Config)
@ -65,8 +66,8 @@ ${name} ignored.")
set_target_properties( ${name} PROPERTIES EXCLUDE_FROM_ALL ON)
else()
install(TARGETS ${name}
LIBRARY DESTINATION lib${LLVM_LIBDIR_SUFFIX}
ARCHIVE DESTINATION lib${LLVM_LIBDIR_SUFFIX})
LIBRARY DESTINATION lib${LLVM_LIBDIR_SUFFIX}
ARCHIVE DESTINATION lib${LLVM_LIBDIR_SUFFIX})
endif()
endif()
@ -82,7 +83,6 @@ macro(add_llvm_executable name)
add_executable(${name} ${ALL_FILES})
endif()
set(EXCLUDE_FROM_ALL OFF)
target_link_libraries( ${name} ${LLVM_USED_LIBS} )
llvm_config( ${name} ${LLVM_LINK_COMPONENTS} )
if( LLVM_COMMON_DEPENDS )
add_dependencies( ${name} ${LLVM_COMMON_DEPENDS} )
@ -130,3 +130,165 @@ macro(add_llvm_target target_name)
add_llvm_library(LLVM${target_name} ${ARGN} ${TABLEGEN_OUTPUT})
set( CURRENT_LLVM_TARGET LLVM${target_name} )
endmacro(add_llvm_target)
# Add external project that may want to be built as part of llvm such as Clang,
# lld, and Polly. This adds two options. One for the source directory of the
# project, which defaults to ${CMAKE_CURRENT_SOURCE_DIR}/${name}. Another to
# enable or disable building it with everthing else.
macro(add_llvm_external_project name)
string(TOUPPER ${name} nameUPPER)
set(LLVM_EXTERNAL_${nameUPPER}_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${name}"
CACHE PATH "Path to ${name} source directory")
if (NOT ${LLVM_EXTERNAL_${nameUPPER}_SOURCE_DIR} STREQUAL ""
AND EXISTS ${LLVM_EXTERNAL_${nameUPPER}_SOURCE_DIR}/CMakeLists.txt)
option(LLVM_EXTERNAL_${nameUPPER}_BUILD
"Whether to build ${name} as part of LLVM" ON)
if (LLVM_EXTERNAL_${nameUPPER}_BUILD)
add_subdirectory(${LLVM_EXTERNAL_${nameUPPER}_SOURCE_DIR} ${name})
endif()
endif()
endmacro(add_llvm_external_project)
# Generic support for adding a unittest.
function(add_unittest test_suite test_name)
if (CMAKE_BUILD_TYPE)
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_BUILD_TYPE})
else()
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
endif()
if( NOT LLVM_BUILD_TESTS )
set(EXCLUDE_FROM_ALL ON)
endif()
add_llvm_executable(${test_name} ${ARGN})
target_link_libraries(${test_name}
gtest
gtest_main
LLVMSupport # gtest needs it for raw_ostream.
)
add_dependencies(${test_suite} ${test_name})
get_target_property(test_suite_folder ${test_suite} FOLDER)
if (NOT ${test_suite_folder} STREQUAL "NOTFOUND")
set_property(TARGET ${test_name} PROPERTY FOLDER "${test_suite_folder}")
endif ()
# Visual Studio 2012 only supports up to 8 template parameters in
# std::tr1::tuple by default, but gtest requires 10
if (MSVC AND MSVC_VERSION EQUAL 1700)
set_property(TARGET ${test_name} APPEND PROPERTY COMPILE_DEFINITIONS _VARIADIC_MAX=10)
endif ()
include_directories(${LLVM_MAIN_SRC_DIR}/utils/unittest/googletest/include)
set_property(TARGET ${test_name} APPEND PROPERTY COMPILE_DEFINITIONS GTEST_HAS_RTTI=0)
if (NOT LLVM_ENABLE_THREADS)
set_property(TARGET ${test_name} APPEND PROPERTY COMPILE_DEFINITIONS GTEST_HAS_PTHREAD=0)
endif ()
get_property(target_compile_flags TARGET ${test_name} PROPERTY COMPILE_FLAGS)
if (LLVM_COMPILER_IS_GCC_COMPATIBLE)
set(target_compile_flags "${target_compile_flags} -fno-rtti")
elseif (MSVC)
set(target_compile_flags "${target_compile_flags} /GR-")
endif ()
if (SUPPORTS_NO_VARIADIC_MACROS_FLAG)
set(target_compile_flags "${target_compile_flags} -Wno-variadic-macros")
endif ()
set_property(TARGET ${test_name} PROPERTY COMPILE_FLAGS "${target_compile_flags}")
endfunction()
# This function provides an automatic way to 'configure'-like generate a file
# based on a set of common and custom variables, specifically targetting the
# variables needed for the 'lit.site.cfg' files. This function bundles the
# common variables that any Lit instance is likely to need, and custom
# variables can be passed in.
function(configure_lit_site_cfg input output)
foreach(c ${LLVM_TARGETS_TO_BUILD})
set(TARGETS_BUILT "${TARGETS_BUILT} ${c}")
endforeach(c)
set(TARGETS_TO_BUILD ${TARGETS_BUILT})
set(SHLIBEXT "${LTDL_SHLIB_EXT}")
set(SHLIBDIR "${LLVM_BINARY_DIR}/lib/${CMAKE_CFG_INTDIR}")
if(BUILD_SHARED_LIBS)
set(LLVM_SHARED_LIBS_ENABLED "1")
else()
set(LLVM_SHARED_LIBS_ENABLED "0")
endif(BUILD_SHARED_LIBS)
if(${CMAKE_SYSTEM_NAME} MATCHES "Darwin")
set(SHLIBPATH_VAR "DYLD_LIBRARY_PATH")
else() # Default for all other unix like systems.
# CMake hardcodes the library locaction using rpath.
# Therefore LD_LIBRARY_PATH is not required to run binaries in the
# build dir. We pass it anyways.
set(SHLIBPATH_VAR "LD_LIBRARY_PATH")
endif()
# Configuration-time: See Unit/lit.site.cfg.in
set(LLVM_BUILD_MODE "%(build_mode)s")
set(LLVM_SOURCE_DIR ${LLVM_MAIN_SRC_DIR})
set(LLVM_BINARY_DIR ${LLVM_BINARY_DIR})
set(LLVM_TOOLS_DIR "${LLVM_TOOLS_BINARY_DIR}/%(build_config)s")
set(LLVM_LIBS_DIR "${LLVM_BINARY_DIR}/lib/%(build_config)s")
set(PYTHON_EXECUTABLE ${PYTHON_EXECUTABLE})
set(ENABLE_SHARED ${LLVM_SHARED_LIBS_ENABLED})
set(SHLIBPATH_VAR ${SHLIBPATH_VAR})
if(LLVM_ENABLE_ASSERTIONS AND NOT MSVC_IDE)
set(ENABLE_ASSERTIONS "1")
else()
set(ENABLE_ASSERTIONS "0")
endif()
set(HOST_OS ${CMAKE_HOST_SYSTEM_NAME})
set(HOST_ARCH ${CMAKE_HOST_SYSTEM_PROCESSOR})
configure_file(${input} ${output} @ONLY)
endfunction()
# A raw function to create a lit target. This is used to implement the testuite
# management functions.
function(add_lit_target target comment)
parse_arguments(ARG "PARAMS;DEPENDS;ARGS" "" ${ARGN})
set(LIT_ARGS "${ARG_ARGS} ${LLVM_LIT_ARGS}")
separate_arguments(LIT_ARGS)
set(LIT_COMMAND
${PYTHON_EXECUTABLE}
${LLVM_MAIN_SRC_DIR}/utils/lit/lit.py
--param build_config=${CMAKE_CFG_INTDIR}
--param build_mode=${RUNTIME_BUILD_MODE}
${LIT_ARGS}
)
foreach(param ${ARG_PARAMS})
list(APPEND LIT_COMMAND --param ${param})
endforeach()
add_custom_target(${target}
COMMAND ${LIT_COMMAND} ${ARG_DEFAULT_ARGS}
COMMENT "${comment}"
)
add_dependencies(${target} ${ARG_DEPENDS})
endfunction()
# A function to add a set of lit test suites to be driven through 'check-*' targets.
function(add_lit_testsuite target comment)
parse_arguments(ARG "PARAMS;DEPENDS;ARGS" "" ${ARGN})
# Register the testsuites, params and depends for the global check rule.
set_property(GLOBAL APPEND PROPERTY LLVM_LIT_TESTSUITES ${ARG_DEFAULT_ARGS})
set_property(GLOBAL APPEND PROPERTY LLVM_LIT_PARAMS ${ARG_PARAMS})
set_property(GLOBAL APPEND PROPERTY LLVM_LIT_DEPENDS ${ARG_DEPENDS})
set_property(GLOBAL APPEND PROPERTY LLVM_LIT_EXTRA_ARGS ${ARG_ARGS})
# Produce a specific suffixed check rule.
add_lit_target(${target} ${comment}
${ARG_DEFAULT_ARGS}
PARAMS ${ARG_PARAMS}
DEPENDS ${ARG_DEPENDS}
ARGS ${ARG_ARGS}
)
endfunction()

20
cmake/modules/HandleLLVMOptions.cmake
View File

@ -105,8 +105,9 @@ if( CMAKE_SIZEOF_VOID_P EQUAL 8 AND NOT WIN32 )
if( LLVM_BUILD_32_BITS )
message(STATUS "Building 32 bits executables and libraries.")
add_llvm_definitions( -m32 )
list(APPEND CMAKE_EXE_LINKER_FLAGS -m32)
list(APPEND CMAKE_SHARED_LINKER_FLAGS -m32)
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -m32")
set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -m32")
set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} -m32")
endif( LLVM_BUILD_32_BITS )
endif( CMAKE_SIZEOF_VOID_P EQUAL 8 AND NOT WIN32 )
@ -150,8 +151,11 @@ if( MSVC )
-D_SCL_SECURE_NO_DEPRECATE
-D_SCL_SECURE_NO_WARNINGS
# Disabled warnings.
-wd4065 # Suppress 'switch statement contains 'default' but no 'case' labels'
-wd4146 # Suppress 'unary minus operator applied to unsigned type, result still unsigned'
-wd4180 # Suppress 'qualifier applied to function type has no meaning; ignored'
-wd4181 # Suppress 'qualifier applied to reference type; ignored'
-wd4224 # Suppress 'nonstandard extension used : formal parameter 'identifier' was previously defined as a type'
-wd4244 # Suppress ''argument' : conversion from 'type1' to 'type2', possible loss of data'
-wd4267 # Suppress ''var' : conversion from 'size_t' to 'type', possible loss of data'
@ -165,14 +169,18 @@ if( MSVC )
-wd4624 # Suppress ''derived class' : destructor could not be generated because a base class destructor is inaccessible'
-wd4715 # Suppress ''function' : not all control paths return a value'
-wd4800 # Suppress ''type' : forcing value to bool 'true' or 'false' (performance warning)'
-wd4065 # Suppress 'switch statement contains 'default' but no 'case' labels'
-wd4181 # Suppress 'qualifier applied to reference type; ignored'
-w14062 # Promote "enumerator in switch of enum is not handled" to level 1 warning.
# Promoted warnings.
-w14062 # Promote 'enumerator in switch of enum is not handled' to level 1 warning.
# Promoted warnings to errors.
-we4238 # Promote 'nonstandard extension used : class rvalue used as lvalue' to error.
-we4239 # Promote 'nonstandard extension used : 'token' : conversion from 'type' to 'type'' to error.
)
# Enable warnings
if (LLVM_ENABLE_WARNINGS)
add_llvm_definitions( /W4 /Wall )
add_llvm_definitions( /W4 )
if (LLVM_ENABLE_PEDANTIC)
# No MSVC equivalent available
endif (LLVM_ENABLE_PEDANTIC)

2
cmake/modules/LLVMConfig.cmake.in
View File

@ -31,7 +31,7 @@ set(HAVE_LIBPTHREAD @HAVE_LIBPTHREAD@)
set(LLVM_ON_UNIX @LLVM_ON_UNIX@)
set(LLVM_ON_WIN32 @LLVM_ON_WIN32@)
set(LLVM_INSTALL_PREFIX @LLVM_INSTALL_PREFIX@)
set(LLVM_INSTALL_PREFIX "@LLVM_INSTALL_PREFIX@")
set(LLVM_INCLUDE_DIRS ${LLVM_INSTALL_PREFIX}/include)
set(LLVM_LIBRARY_DIRS ${LLVM_INSTALL_PREFIX}/lib)
set(LLVM_DEFINITIONS "-D__STDC_LIMIT_MACROS" "-D__STDC_CONSTANT_MACROS")

10
cmake/modules/LLVMProcessSources.cmake
View File

@ -29,7 +29,7 @@ endmacro(add_td_sources)
macro(add_header_files srcs)
file(GLOB hds *.h *.def)
file(GLOB hds *.h)
if( hds )
set_source_files_properties(${hds} PROPERTIES HEADER_FILE_ONLY ON)
list(APPEND ${srcs} ${hds})
@ -50,6 +50,7 @@ function(llvm_process_sources OUT_VAR)
endforeach(s)
if( MSVC_IDE )
# This adds .td and .h files to the Visual Studio solution:
# FIXME: Shall we handle *.def here?
add_td_sources(sources)
add_header_files(sources)
endif()
@ -81,10 +82,13 @@ function(llvm_check_source_file_list)
file(GLOB globbed *.cpp)
foreach(g ${globbed})
get_filename_component(fn ${g} NAME)
list(FIND listed ${fn} idx)
list(FIND LLVM_OPTIONAL_SOURCES ${fn} idx)
if( idx LESS 0 )
message(SEND_ERROR "Found unknown source file ${g}
list(FIND listed ${fn} idx)
if( idx LESS 0 )
message(SEND_ERROR "Found unknown source file ${g}
Please update ${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt\n")
endif()
endif()
endforeach()
endfunction(llvm_check_source_file_list)

4
cmake/modules/TableGen.cmake
View File

@ -50,7 +50,9 @@ function(add_public_tablegen_target target)
if( TABLEGEN_OUTPUT )
add_custom_target(${target}
DEPENDS ${TABLEGEN_OUTPUT})
add_dependencies(${target} ${LLVM_COMMON_DEPENDS})
if (LLVM_COMMON_DEPENDS)
add_dependencies(${target} ${LLVM_COMMON_DEPENDS})
endif ()
set_target_properties(${target} PROPERTIES FOLDER "Tablegenning")
endif( TABLEGEN_OUTPUT )
endfunction()

505
configure vendored
View File

@ -1,6 +1,6 @@
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
# Generated by GNU Autoconf 2.60 for LLVM 3.1.
# Generated by GNU Autoconf 2.60 for LLVM 3.2svn.
#
# Report bugs to <http://llvm.org/bugs/>.
#
@ -561,8 +561,8 @@ SHELL=${CONFIG_SHELL-/bin/sh}
# Identity of this package.
PACKAGE_NAME='LLVM'
PACKAGE_TARNAME='llvm'
PACKAGE_VERSION='3.1'
PACKAGE_STRING='LLVM 3.1'
PACKAGE_VERSION='3.2svn'
PACKAGE_STRING='LLVM 3.2svn'
PACKAGE_BUGREPORT='http://llvm.org/bugs/'
ac_unique_file="lib/VMCore/Module.cpp"
@ -674,6 +674,7 @@ NOLINKALL
LLVM_ON_UNIX
LLVM_ON_WIN32
ARCH
HOST_ARCH
ENDIAN
GREP
EGREP
@ -683,9 +684,11 @@ BUILD_EXEEXT
BUILD_CXX
CVSBUILD
ENABLE_LIBCPP
ENABLE_CXX11
ENABLE_OPTIMIZED
ENABLE_PROFILING
DISABLE_ASSERTIONS
ENABLE_WERROR
ENABLE_EXPENSIVE_CHECKS
EXPENSIVE_CHECKS
DEBUG_RUNTIME
@ -743,11 +746,7 @@ CAT
DOXYGEN
GROFF
GZIPBIN
POD2HTML
POD2MAN
PDFROFF
RUNTEST
TCLSH
ZIP
OCAMLC
OCAMLOPT
@ -768,6 +767,9 @@ USE_OPROFILE
USE_INTEL_JITEVENTS
INTEL_JITEVENTS_INCDIR
INTEL_JITEVENTS_LIBDIR
XML2CONFIG
LIBXML2_LIBS
LIBXML2_INC
HAVE_PTHREAD
HUGE_VAL_SANITY
MMAP_FILE
@ -1318,7 +1320,7 @@ if test "$ac_init_help" = "long"; then
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat <<_ACEOF
\`configure' configures LLVM 3.1 to adapt to many kinds of systems.
\`configure' configures LLVM 3.2svn to adapt to many kinds of systems.
Usage: $0 [OPTION]... [VAR=VALUE]...
@ -1384,7 +1386,7 @@ fi
if test -n "$ac_init_help"; then
case $ac_init_help in
short | recursive ) echo "Configuration of LLVM 3.1:";;
short | recursive ) echo "Configuration of LLVM 3.2svn:";;
esac
cat <<\_ACEOF
@ -1393,10 +1395,12 @@ Optional Features:
--enable-FEATURE[=ARG] include FEATURE [ARG=yes]
--enable-polly Use polly if available (default is YES)
--enable-libcpp Use libc++ if available (default is NO)
--enable-cxx11 Use c++11 if available (default is NO)
--enable-optimized Compile with optimizations enabled (default is NO)
--enable-profiling Compile with profiling enabled (default is NO)
--enable-assertions Compile with assertion checks enabled (default is
YES)
--enable-werror Compile with -Werror enabled (default is NO)
--enable-expensive-checks
Compile with expensive debug checks enabled (default
is NO)
@ -1420,7 +1424,10 @@ Optional Features:
--enable-targets Build specific host targets: all or
target1,target2,... Valid targets are: host, x86,
x86_64, sparc, powerpc, arm, mips, spu, hexagon,
xcore, msp430, ptx, and cpp (default=all)
xcore, msp430, nvptx, and cpp (default=all)
--enable-experimental-targets
Build experimental host targets: disable or
target1,target2,... (default=disable)
--enable-bindings Build specific language bindings:
all,auto,none,{binding-name} (default=auto)
--enable-libffi Check for the presence of libffi (default is NO)
@ -1448,7 +1455,6 @@ Optional Packages:
--with-bug-report-url Specify the URL where bug reports should be
submitted (default=http://llvm.org/bugs/)
--with-internal-prefix Installation directory for internal files
--with-tclinclude directory where tcl headers are
--with-udis86=<path> Use udis86 external x86 disassembler library
--with-oprofile=<prefix>
Tell OProfile >= 0.9.4 how to symbolize JIT output
@ -1532,7 +1538,7 @@ fi
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
LLVM configure 3.1
LLVM configure 3.2svn
generated by GNU Autoconf 2.60
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
@ -1548,7 +1554,7 @@ cat >config.log <<_ACEOF
This file contains any messages produced by compilers while
running configure, to aid debugging if configure makes a mistake.
It was created by LLVM $as_me 3.1, which was
It was created by LLVM $as_me 3.2svn, which was
generated by GNU Autoconf 2.60. Invocation command line was
$ $0 $@
@ -1908,7 +1914,7 @@ _ACEOF
cat >>confdefs.h <<\_ACEOF
#define LLVM_VERSION_MINOR 1
#define LLVM_VERSION_MINOR 2
_ACEOF
@ -3902,7 +3908,7 @@ else
msp430-*) llvm_cv_target_arch="MSP430" ;;
hexagon-*) llvm_cv_target_arch="Hexagon" ;;
mblaze-*) llvm_cv_target_arch="MBlaze" ;;
ptx-*) llvm_cv_target_arch="PTX" ;;
nvptx-*) llvm_cv_target_arch="NVPTX" ;;
*) llvm_cv_target_arch="Unknown" ;;
esac
fi
@ -3923,6 +3929,29 @@ esac
ARCH=$llvm_cv_target_arch
case $host in
i?86-*) host_arch="x86" ;;
amd64-* | x86_64-*) host_arch="x86_64" ;;
sparc*-*) host_arch="Sparc" ;;
powerpc*-*) host_arch="PowerPC" ;;
arm*-*) host_arch="ARM" ;;
mips-*) host_arch="Mips" ;;
mipsel-*) host_arch="Mips" ;;
xcore-*) host_arch="XCore" ;;
msp430-*) host_arch="MSP430" ;;
hexagon-*) host_arch="Hexagon" ;;
mblaze-*) host_arch="MBlaze" ;;
*) host_arch="Unknown" ;;
esac
if test "$host_arch" = "Unknown" ; then
{ echo "$as_me:$LINENO: WARNING: Configuring LLVM for an unknown host archicture" >&5
echo "$as_me: WARNING: Configuring LLVM for an unknown host archicture" >&2;}
fi
HOST_ARCH=$host_arch
{ echo "$as_me:$LINENO: checking for grep that handles long lines and -e" >&5
@ -4997,6 +5026,25 @@ echo "$as_me: error: Invalid setting for --enable-libcpp. Use \"yes\" or \"no\""
{ (exit 1); exit 1; }; } ;;
esac
# Check whether --enable-cxx11 was given.
if test "${enable_cxx11+set}" = set; then
enableval=$enable_cxx11;
else
enableval=default
fi
case "$enableval" in
yes) ENABLE_CXX11=1
;;
no) ENABLE_CXX11=0
;;
default) ENABLE_CXX11=0
;;
*) { { echo "$as_me:$LINENO: error: Invalid setting for --enable-cxx11. Use \"yes\" or \"no\"" >&5
echo "$as_me: error: Invalid setting for --enable-cxx11. Use \"yes\" or \"no\"" >&2;}
{ (exit 1); exit 1; }; } ;;
esac
# Check whether --enable-optimized was given.
if test "${enable_optimized+set}" = set; then
enableval=$enable_optimized;
@ -5042,6 +5090,25 @@ else
fi
# Check whether --enable-werror was given.
if test "${enable_werror+set}" = set; then
enableval=$enable_werror;
else
enableval="no"
fi
case "$enableval" in
yes) ENABLE_WERROR=1
;;
no) ENABLE_WERROR=0
;;
default) ENABLE_WERROR=0
;;
*) { { echo "$as_me:$LINENO: error: Invalid setting for --enable-werror. Use \"yes\" or \"no\"" >&5
echo "$as_me: error: Invalid setting for --enable-werror. Use \"yes\" or \"no\"" >&2;}
{ (exit 1); exit 1; }; } ;;
esac
# Check whether --enable-expensive-checks was given.
if test "${enable_expensive_checks+set}" = set; then
enableval=$enable_expensive_checks;
@ -5124,7 +5191,7 @@ else
;;
MBlaze) TARGET_HAS_JIT=0
;;
PTX) TARGET_HAS_JIT=0
NVPTX) TARGET_HAS_JIT=0
;;
*) TARGET_HAS_JIT=0
;;
@ -5310,7 +5377,7 @@ if test "$enableval" = host-only ; then
enableval=host
fi
case "$enableval" in
all) TARGETS_TO_BUILD="X86 Sparc PowerPC ARM Mips CellSPU XCore MSP430 CppBackend MBlaze PTX Hexagon" ;;
all) TARGETS_TO_BUILD="X86 Sparc PowerPC ARM Mips CellSPU XCore MSP430 CppBackend MBlaze NVPTX Hexagon" ;;
*)for a_target in `echo $enableval|sed -e 's/,/ /g' ` ; do
case "$a_target" in
x86) TARGETS_TO_BUILD="X86 $TARGETS_TO_BUILD" ;;
@ -5326,7 +5393,7 @@ case "$enableval" in
cpp) TARGETS_TO_BUILD="CppBackend $TARGETS_TO_BUILD" ;;
hexagon) TARGETS_TO_BUILD="Hexagon $TARGETS_TO_BUILD" ;;
mblaze) TARGETS_TO_BUILD="MBlaze $TARGETS_TO_BUILD" ;;
ptx) TARGETS_TO_BUILD="PTX $TARGETS_TO_BUILD" ;;
nvptx) TARGETS_TO_BUILD="NVPTX $TARGETS_TO_BUILD" ;;
host) case "$llvm_cv_target_arch" in
x86) TARGETS_TO_BUILD="X86 $TARGETS_TO_BUILD" ;;
x86_64) TARGETS_TO_BUILD="X86 $TARGETS_TO_BUILD" ;;
@ -5339,7 +5406,7 @@ case "$enableval" in
XCore) TARGETS_TO_BUILD="XCore $TARGETS_TO_BUILD" ;;
MSP430) TARGETS_TO_BUILD="MSP430 $TARGETS_TO_BUILD" ;;
Hexagon) TARGETS_TO_BUILD="Hexagon $TARGETS_TO_BUILD" ;;
PTX) TARGETS_TO_BUILD="PTX $TARGETS_TO_BUILD" ;;
NVPTX) TARGETS_TO_BUILD="NVPTX $TARGETS_TO_BUILD" ;;
*) { { echo "$as_me:$LINENO: error: Can not set target to build" >&5
echo "$as_me: error: Can not set target to build" >&2;}
{ (exit 1); exit 1; }; } ;;
@ -5351,6 +5418,20 @@ echo "$as_me: error: Unrecognized target $a_target" >&2;}
done
;;
esac
# Check whether --enable-experimental-targets was given.
if test "${enable_experimental_targets+set}" = set; then
enableval=$enable_experimental_targets;
else
enableval=disable
fi
if test ${enableval} != "disable"
then
TARGETS_TO_BUILD="$enableval $TARGETS_TO_BUILD"
fi
TARGETS_TO_BUILD=$TARGETS_TO_BUILD
@ -7194,86 +7275,6 @@ echo "${ECHO_T}no" >&6; }
fi
# Extract the first word of "pod2html", so it can be a program name with args.
set dummy pod2html; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; }
if test "${ac_cv_path_POD2HTML+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
case $POD2HTML in
[\\/]* | ?:[\\/]*)
ac_cv_path_POD2HTML="$POD2HTML" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then
ac_cv_path_POD2HTML="$as_dir/$ac_word$ac_exec_ext"
echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
POD2HTML=$ac_cv_path_POD2HTML
if test -n "$POD2HTML"; then
{ echo "$as_me:$LINENO: result: $POD2HTML" >&5
echo "${ECHO_T}$POD2HTML" >&6; }
else
{ echo "$as_me:$LINENO: result: no" >&5
echo "${ECHO_T}no" >&6; }
fi
# Extract the first word of "pod2man", so it can be a program name with args.
set dummy pod2man; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; }
if test "${ac_cv_path_POD2MAN+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
case $POD2MAN in
[\\/]* | ?:[\\/]*)
ac_cv_path_POD2MAN="$POD2MAN" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then
ac_cv_path_POD2MAN="$as_dir/$ac_word$ac_exec_ext"
echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
POD2MAN=$ac_cv_path_POD2MAN
if test -n "$POD2MAN"; then
{ echo "$as_me:$LINENO: result: $POD2MAN" >&5
echo "${ECHO_T}$POD2MAN" >&6; }
else
{ echo "$as_me:$LINENO: result: no" >&5
echo "${ECHO_T}no" >&6; }
fi
# Extract the first word of "pdfroff", so it can be a program name with args.
set dummy pdfroff; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
@ -7314,136 +7315,6 @@ echo "${ECHO_T}no" >&6; }
fi
# Extract the first word of "runtest", so it can be a program name with args.
set dummy runtest; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; }
if test "${ac_cv_path_RUNTEST+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
case $RUNTEST in
[\\/]* | ?:[\\/]*)
ac_cv_path_RUNTEST="$RUNTEST" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then
ac_cv_path_RUNTEST="$as_dir/$ac_word$ac_exec_ext"
echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
RUNTEST=$ac_cv_path_RUNTEST
if test -n "$RUNTEST"; then
{ echo "$as_me:$LINENO: result: $RUNTEST" >&5
echo "${ECHO_T}$RUNTEST" >&6; }
else
{ echo "$as_me:$LINENO: result: no" >&5
echo "${ECHO_T}no" >&6; }
fi
no_itcl=true
{ echo "$as_me:$LINENO: checking for the tclsh program in tclinclude directory" >&5
echo $ECHO_N "checking for the tclsh program in tclinclude directory... $ECHO_C" >&6; }
# Check whether --with-tclinclude was given.
if test "${with_tclinclude+set}" = set; then
withval=$with_tclinclude; with_tclinclude=${withval}
else
with_tclinclude=''
fi
if test "${ac_cv_path_tclsh+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
if test x"${with_tclinclude}" != x ; then
if test -f ${with_tclinclude}/tclsh ; then
ac_cv_path_tclsh=`(cd ${with_tclinclude}; pwd)`
elif test -f ${with_tclinclude}/src/tclsh ; then
ac_cv_path_tclsh=`(cd ${with_tclinclude}/src; pwd)`
else
{ { echo "$as_me:$LINENO: error: ${with_tclinclude} directory doesn't contain tclsh" >&5
echo "$as_me: error: ${with_tclinclude} directory doesn't contain tclsh" >&2;}
{ (exit 1); exit 1; }; }
fi
fi
fi
if test x"${ac_cv_path_tclsh}" = x ; then
{ echo "$as_me:$LINENO: result: none" >&5
echo "${ECHO_T}none" >&6; }
for ac_prog in tclsh8.4 tclsh8.4.8 tclsh8.4.7 tclsh8.4.6 tclsh8.4.5 tclsh8.4.4 tclsh8.4.3 tclsh8.4.2 tclsh8.4.1 tclsh8.4.0 tclsh8.3 tclsh8.3.5 tclsh8.3.4 tclsh8.3.3 tclsh8.3.2 tclsh8.3.1 tclsh8.3.0 tclsh
do
# Extract the first word of "$ac_prog", so it can be a program name with args.
set dummy $ac_prog; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; }
if test "${ac_cv_path_TCLSH+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
case $TCLSH in
[\\/]* | ?:[\\/]*)
ac_cv_path_TCLSH="$TCLSH" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then
ac_cv_path_TCLSH="$as_dir/$ac_word$ac_exec_ext"
echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
TCLSH=$ac_cv_path_TCLSH
if test -n "$TCLSH"; then
{ echo "$as_me:$LINENO: result: $TCLSH" >&5
echo "${ECHO_T}$TCLSH" >&6; }
else
{ echo "$as_me:$LINENO: result: no" >&5
echo "${ECHO_T}no" >&6; }
fi
test -n "$TCLSH" && break
done
if test x"${TCLSH}" = x ; then
ac_cv_path_tclsh='';
else
ac_cv_path_tclsh="${TCLSH}";
fi
else
{ echo "$as_me:$LINENO: result: ${ac_cv_path_tclsh}" >&5
echo "${ECHO_T}${ac_cv_path_tclsh}" >&6; }
TCLSH="${ac_cv_path_tclsh}"
fi
# Extract the first word of "zip", so it can be a program name with args.
set dummy zip; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
@ -9093,7 +8964,7 @@ nto-qnx*)
shlibpath_overrides_runpath=yes
;;
openbsd*)
openbsd* | bitrig*)
version_type=sunos
sys_lib_dlsearch_path_spec="/usr/lib"
need_lib_prefix=no
@ -10401,7 +10272,7 @@ else
lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
lt_status=$lt_dlunknown
cat > conftest.$ac_ext <<EOF
#line 10404 "configure"
#line 10275 "configure"
#include "confdefs.h"
#if HAVE_DLFCN_H
@ -13976,6 +13847,148 @@ cat >>confdefs.h <<_ACEOF
_ACEOF
for ac_prog in xml2-config
do
# Extract the first word of "$ac_prog", so it can be a program name with args.
set dummy $ac_prog; ac_word=$2
{ echo "$as_me:$LINENO: checking for $ac_word" >&5
echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; }
if test "${ac_cv_prog_XML2CONFIG+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
if test -n "$XML2CONFIG"; then
ac_cv_prog_XML2CONFIG="$XML2CONFIG" # Let the user override the test.
else
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then
ac_cv_prog_XML2CONFIG="$ac_prog"
echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
fi
fi
XML2CONFIG=$ac_cv_prog_XML2CONFIG
if test -n "$XML2CONFIG"; then
{ echo "$as_me:$LINENO: result: $XML2CONFIG" >&5
echo "${ECHO_T}$XML2CONFIG" >&6; }
else
{ echo "$as_me:$LINENO: result: no" >&5
echo "${ECHO_T}no" >&6; }
fi
test -n "$XML2CONFIG" && break
done
{ echo "$as_me:$LINENO: checking for libxml2 includes" >&5
echo $ECHO_N "checking for libxml2 includes... $ECHO_C" >&6; }
if test "x$XML2CONFIG" = "x"; then
{ echo "$as_me:$LINENO: result: xml2-config not found" >&5
echo "${ECHO_T}xml2-config not found" >&6; }
else
LIBXML2_INC=`$XML2CONFIG --cflags`
{ echo "$as_me:$LINENO: result: $LIBXML2_INC" >&5
echo "${ECHO_T}$LIBXML2_INC" >&6; }
{ echo "$as_me:$LINENO: checking for xmlReadFile in -lxml2" >&5
echo $ECHO_N "checking for xmlReadFile in -lxml2... $ECHO_C" >&6; }
if test "${ac_cv_lib_xml2_xmlReadFile+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
else
ac_check_lib_save_LIBS=$LIBS
LIBS="-lxml2 $LIBS"
cat >conftest.$ac_ext <<_ACEOF
/* confdefs.h. */
_ACEOF
cat confdefs.h >>conftest.$ac_ext
cat >>conftest.$ac_ext <<_ACEOF
/* end confdefs.h. */
/* Override any GCC internal prototype to avoid an error.
Use char because int might match the return type of a GCC
builtin and then its argument prototype would still apply. */
#ifdef __cplusplus
extern "C"
#endif
char xmlReadFile ();
int
main ()
{
return xmlReadFile ();
;
return 0;
}
_ACEOF
rm -f conftest.$ac_objext conftest$ac_exeext
if { (ac_try="$ac_link"
case "(($ac_try" in
*\"* | *\`* | *\\*) ac_try_echo=\$ac_try;;
*) ac_try_echo=$ac_try;;
esac
eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5
(eval "$ac_link") 2>conftest.er1
ac_status=$?
grep -v '^ *+' conftest.er1 >conftest.err
rm -f conftest.er1
cat conftest.err >&5
echo "$as_me:$LINENO: \$? = $ac_status" >&5
(exit $ac_status); } &&
{ ac_try='test -z "$ac_c_werror_flag" || test ! -s conftest.err'
{ (case "(($ac_try" in
*\"* | *\`* | *\\*) ac_try_echo=\$ac_try;;
*) ac_try_echo=$ac_try;;
esac
eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5
(eval "$ac_try") 2>&5
ac_status=$?
echo "$as_me:$LINENO: \$? = $ac_status" >&5
(exit $ac_status); }; } &&
{ ac_try='test -s conftest$ac_exeext'
{ (case "(($ac_try" in
*\"* | *\`* | *\\*) ac_try_echo=\$ac_try;;
*) ac_try_echo=$ac_try;;
esac
eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5
(eval "$ac_try") 2>&5
ac_status=$?
echo "$as_me:$LINENO: \$? = $ac_status" >&5
(exit $ac_status); }; }; then
ac_cv_lib_xml2_xmlReadFile=yes
else
echo "$as_me: failed program was:" >&5
sed 's/^/| /' conftest.$ac_ext >&5
ac_cv_lib_xml2_xmlReadFile=no
fi
rm -f core conftest.err conftest.$ac_objext \
conftest$ac_exeext conftest.$ac_ext
LIBS=$ac_check_lib_save_LIBS
fi
{ echo "$as_me:$LINENO: result: $ac_cv_lib_xml2_xmlReadFile" >&5
echo "${ECHO_T}$ac_cv_lib_xml2_xmlReadFile" >&6; }
if test $ac_cv_lib_xml2_xmlReadFile = yes; then
cat >>confdefs.h <<\_ACEOF
#define CLANG_HAVE_LIBXML 1
_ACEOF
LIBXML2_LIBS="-lxml2"
fi
fi
@ -17517,7 +17530,8 @@ done
for ac_func in strerror strerror_r setenv
for ac_func in strerror strerror_r setenv arc4random
do
as_ac_var=`echo "ac_cv_func_$ac_func" | $as_tr_sh`
{ echo "$as_me:$LINENO: checking for $ac_func" >&5
@ -21138,6 +21152,11 @@ cat >>confdefs.h <<_ACEOF
_ACEOF
cat >>confdefs.h <<_ACEOF
#define LLVM_HOSTTRIPLE "$host"
_ACEOF
cat >>confdefs.h <<_ACEOF
#define LLVM_DEFAULT_TARGET_TRIPLE "$target"
_ACEOF
@ -21785,7 +21804,7 @@ exec 6>&1
# report actual input values of CONFIG_FILES etc. instead of their
# values after options handling.
ac_log="
This file was extended by LLVM $as_me 3.1, which was
This file was extended by LLVM $as_me 3.2svn, which was
generated by GNU Autoconf 2.60. Invocation command line was
CONFIG_FILES = $CONFIG_FILES
@ -21838,7 +21857,7 @@ Report bugs to <bug-autoconf@gnu.org>."
_ACEOF
cat >>$CONFIG_STATUS <<_ACEOF
ac_cs_version="\\
LLVM config.status 3.1
LLVM config.status 3.2svn
configured by $0, generated by GNU Autoconf 2.60,
with options \\"`echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`\\"
@ -22112,6 +22131,7 @@ NOLINKALL!$NOLINKALL$ac_delim
LLVM_ON_UNIX!$LLVM_ON_UNIX$ac_delim
LLVM_ON_WIN32!$LLVM_ON_WIN32$ac_delim
ARCH!$ARCH$ac_delim
HOST_ARCH!$HOST_ARCH$ac_delim
ENDIAN!$ENDIAN$ac_delim
GREP!$GREP$ac_delim
EGREP!$EGREP$ac_delim
@ -22121,9 +22141,11 @@ BUILD_EXEEXT!$BUILD_EXEEXT$ac_delim
BUILD_CXX!$BUILD_CXX$ac_delim
CVSBUILD!$CVSBUILD$ac_delim
ENABLE_LIBCPP!$ENABLE_LIBCPP$ac_delim
ENABLE_CXX11!$ENABLE_CXX11$ac_delim
ENABLE_OPTIMIZED!$ENABLE_OPTIMIZED$ac_delim
ENABLE_PROFILING!$ENABLE_PROFILING$ac_delim
DISABLE_ASSERTIONS!$DISABLE_ASSERTIONS$ac_delim
ENABLE_WERROR!$ENABLE_WERROR$ac_delim
ENABLE_EXPENSIVE_CHECKS!$ENABLE_EXPENSIVE_CHECKS$ac_delim
EXPENSIVE_CHECKS!$EXPENSIVE_CHECKS$ac_delim
DEBUG_RUNTIME!$DEBUG_RUNTIME$ac_delim
@ -22134,9 +22156,6 @@ ENABLE_DOCS!$ENABLE_DOCS$ac_delim
ENABLE_DOXYGEN!$ENABLE_DOXYGEN$ac_delim
LLVM_ENABLE_THREADS!$LLVM_ENABLE_THREADS$ac_delim
ENABLE_PTHREADS!$ENABLE_PTHREADS$ac_delim
ENABLE_PIC!$ENABLE_PIC$ac_delim
ENABLE_SHARED!$ENABLE_SHARED$ac_delim
ENABLE_EMBED_STDCXX!$ENABLE_EMBED_STDCXX$ac_delim
_ACEOF
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then
@ -22178,6 +22197,9 @@ _ACEOF
ac_delim='%!_!# '
for ac_last_try in false false false false false :; do
cat >conf$$subs.sed <<_ACEOF
ENABLE_PIC!$ENABLE_PIC$ac_delim
ENABLE_SHARED!$ENABLE_SHARED$ac_delim
ENABLE_EMBED_STDCXX!$ENABLE_EMBED_STDCXX$ac_delim
ENABLE_TIMESTAMPS!$ENABLE_TIMESTAMPS$ac_delim
TARGETS_TO_BUILD!$TARGETS_TO_BUILD$ac_delim
LLVM_ENUM_TARGETS!$LLVM_ENUM_TARGETS$ac_delim
@ -22222,11 +22244,7 @@ CAT!$CAT$ac_delim
DOXYGEN!$DOXYGEN$ac_delim
GROFF!$GROFF$ac_delim
GZIPBIN!$GZIPBIN$ac_delim
POD2HTML!$POD2HTML$ac_delim
POD2MAN!$POD2MAN$ac_delim
PDFROFF!$PDFROFF$ac_delim
RUNTEST!$RUNTEST$ac_delim
TCLSH!$TCLSH$ac_delim
ZIP!$ZIP$ac_delim
OCAMLC!$OCAMLC$ac_delim
OCAMLOPT!$OCAMLOPT$ac_delim
@ -22247,6 +22265,9 @@ USE_OPROFILE!$USE_OPROFILE$ac_delim
USE_INTEL_JITEVENTS!$USE_INTEL_JITEVENTS$ac_delim
INTEL_JITEVENTS_INCDIR!$INTEL_JITEVENTS_INCDIR$ac_delim
INTEL_JITEVENTS_LIBDIR!$INTEL_JITEVENTS_LIBDIR$ac_delim
XML2CONFIG!$XML2CONFIG$ac_delim
LIBXML2_LIBS!$LIBXML2_LIBS$ac_delim
LIBXML2_INC!$LIBXML2_INC$ac_delim
HAVE_PTHREAD!$HAVE_PTHREAD$ac_delim
HUGE_VAL_SANITY!$HUGE_VAL_SANITY$ac_delim
MMAP_FILE!$MMAP_FILE$ac_delim
@ -22272,7 +22293,7 @@ LIBOBJS!$LIBOBJS$ac_delim
LTLIBOBJS!$LTLIBOBJS$ac_delim
_ACEOF
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 92; then
if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 94; then
break
elif $ac_last_try; then
{ { echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5

1067
docs/AliasAnalysis.html
View File

File diff suppressed because it is too large Load Diff

702
docs/AliasAnalysis.rst Normal file
View File

@ -0,0 +1,702 @@
.. _alias_analysis:
==================================
LLVM Alias Analysis Infrastructure
==================================
.. contents::
:local:
Introduction
============
Alias Analysis (aka Pointer Analysis) is a class of techniques which attempt to
determine whether or not two pointers ever can point to the same object in
memory. There are many different algorithms for alias analysis and many
different ways of classifying them: flow-sensitive vs. flow-insensitive,
context-sensitive vs. context-insensitive, field-sensitive
vs. field-insensitive, unification-based vs. subset-based, etc. Traditionally,
alias analyses respond to a query with a `Must, May, or No`_ alias response,
indicating that two pointers always point to the same object, might point to the
same object, or are known to never point to the same object.
The LLVM `AliasAnalysis
<http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ class is the
primary interface used by clients and implementations of alias analyses in the
LLVM system. This class is the common interface between clients of alias
analysis information and the implementations providing it, and is designed to
support a wide range of implementations and clients (but currently all clients
are assumed to be flow-insensitive). In addition to simple alias analysis
information, this class exposes Mod/Ref information from those implementations
which can provide it, allowing for powerful analyses and transformations to work
well together.
This document contains information necessary to successfully implement this
interface, use it, and to test both sides. It also explains some of the finer
points about what exactly results mean. If you feel that something is unclear
or should be added, please `let me know <mailto:sabre@nondot.org>`_.
``AliasAnalysis`` Class Overview
================================
The `AliasAnalysis <http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__
class defines the interface that the various alias analysis implementations
should support. This class exports two important enums: ``AliasResult`` and
``ModRefResult`` which represent the result of an alias query or a mod/ref
query, respectively.
The ``AliasAnalysis`` interface exposes information about memory, represented in
several different ways. In particular, memory objects are represented as a
starting address and size, and function calls are represented as the actual
``call`` or ``invoke`` instructions that performs the call. The
``AliasAnalysis`` interface also exposes some helper methods which allow you to
get mod/ref information for arbitrary instructions.
All ``AliasAnalysis`` interfaces require that in queries involving multiple
values, values which are not `constants <LangRef.html#constants>`_ are all
defined within the same function.
Representation of Pointers
--------------------------
Most importantly, the ``AliasAnalysis`` class provides several methods which are
used to query whether or not two memory objects alias, whether function calls
can modify or read a memory object, etc. For all of these queries, memory
objects are represented as a pair of their starting address (a symbolic LLVM
``Value*``) and a static size.
Representing memory objects as a starting address and a size is critically
important for correct Alias Analyses. For example, consider this (silly, but
possible) C code:
.. code-block:: c++
int i;
char C[2];
char A[10];
/* ... */
for (i = 0; i != 10; ++i) {
C[0] = A[i]; /* One byte store */
C[1] = A[9-i]; /* One byte store */
}
In this case, the ``basicaa`` pass will disambiguate the stores to ``C[0]`` and
``C[1]`` because they are accesses to two distinct locations one byte apart, and
the accesses are each one byte. In this case, the Loop Invariant Code Motion
(LICM) pass can use store motion to remove the stores from the loop. In
constrast, the following code:
.. code-block:: c++
int i;
char C[2];
char A[10];
/* ... */
for (i = 0; i != 10; ++i) {
((short*)C)[0] = A[i]; /* Two byte store! */
C[1] = A[9-i]; /* One byte store */
}
In this case, the two stores to C do alias each other, because the access to the
``&C[0]`` element is a two byte access. If size information wasn't available in
the query, even the first case would have to conservatively assume that the
accesses alias.
.. _alias:
The ``alias`` method
--------------------
The ``alias`` method is the primary interface used to determine whether or not
two memory objects alias each other. It takes two memory objects as input and
returns MustAlias, PartialAlias, MayAlias, or NoAlias as appropriate.
Like all ``AliasAnalysis`` interfaces, the ``alias`` method requires that either
the two pointer values be defined within the same function, or at least one of
the values is a `constant <LangRef.html#constants>`_.
.. _Must, May, or No:
Must, May, and No Alias Responses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``NoAlias`` response may be used when there is never an immediate dependence
between any memory reference *based* on one pointer and any memory reference
*based* the other. The most obvious example is when the two pointers point to
non-overlapping memory ranges. Another is when the two pointers are only ever
used for reading memory. Another is when the memory is freed and reallocated
between accesses through one pointer and accesses through the other --- in this
case, there is a dependence, but it's mediated by the free and reallocation.
As an exception to this is with the `noalias <LangRef.html#noalias>`_ keyword;
the "irrelevant" dependencies are ignored.
The ``MayAlias`` response is used whenever the two pointers might refer to the
same object.
The ``PartialAlias`` response is used when the two memory objects are known to
be overlapping in some way, but do not start at the same address.
The ``MustAlias`` response may only be returned if the two memory objects are
guaranteed to always start at exactly the same location. A ``MustAlias``
response implies that the pointers compare equal.
The ``getModRefInfo`` methods
-----------------------------
The ``getModRefInfo`` methods return information about whether the execution of
an instruction can read or modify a memory location. Mod/Ref information is
always conservative: if an instruction **might** read or write a location,
``ModRef`` is returned.
The ``AliasAnalysis`` class also provides a ``getModRefInfo`` method for testing
dependencies between function calls. This method takes two call sites (``CS1``
& ``CS2``), returns ``NoModRef`` if neither call writes to memory read or
written by the other, ``Ref`` if ``CS1`` reads memory written by ``CS2``,
``Mod`` if ``CS1`` writes to memory read or written by ``CS2``, or ``ModRef`` if
``CS1`` might read or write memory written to by ``CS2``. Note that this
relation is not commutative.
Other useful ``AliasAnalysis`` methods
--------------------------------------
Several other tidbits of information are often collected by various alias
analysis implementations and can be put to good use by various clients.
The ``pointsToConstantMemory`` method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``pointsToConstantMemory`` method returns true if and only if the analysis
can prove that the pointer only points to unchanging memory locations
(functions, constant global variables, and the null pointer). This information
can be used to refine mod/ref information: it is impossible for an unchanging
memory location to be modified.
.. _never access memory or only read memory:
The ``doesNotAccessMemory`` and ``onlyReadsMemory`` methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These methods are used to provide very simple mod/ref information for function
calls. The ``doesNotAccessMemory`` method returns true for a function if the
analysis can prove that the function never reads or writes to memory, or if the
function only reads from constant memory. Functions with this property are
side-effect free and only depend on their input arguments, allowing them to be
eliminated if they form common subexpressions or be hoisted out of loops. Many
common functions behave this way (e.g., ``sin`` and ``cos``) but many others do
not (e.g., ``acos``, which modifies the ``errno`` variable).
The ``onlyReadsMemory`` method returns true for a function if analysis can prove
that (at most) the function only reads from non-volatile memory. Functions with
this property are side-effect free, only depending on their input arguments and
the state of memory when they are called. This property allows calls to these
functions to be eliminated and moved around, as long as there is no store
instruction that changes the contents of memory. Note that all functions that
satisfy the ``doesNotAccessMemory`` method also satisfies ``onlyReadsMemory``.
Writing a new ``AliasAnalysis`` Implementation
==============================================
Writing a new alias analysis implementation for LLVM is quite straight-forward.
There are already several implementations that you can use for examples, and the
following information should help fill in any details. For a examples, take a
look at the `various alias analysis implementations`_ included with LLVM.
Different Pass styles
---------------------
The first step to determining what type of `LLVM pass <WritingAnLLVMPass.html>`_
you need to use for your Alias Analysis. As is the case with most other
analyses and transformations, the answer should be fairly obvious from what type
of problem you are trying to solve:
#. If you require interprocedural analysis, it should be a ``Pass``.
#. If you are a function-local analysis, subclass ``FunctionPass``.
#. If you don't need to look at the program at all, subclass ``ImmutablePass``.
In addition to the pass that you subclass, you should also inherit from the
``AliasAnalysis`` interface, of course, and use the ``RegisterAnalysisGroup``
template to register as an implementation of ``AliasAnalysis``.
Required initialization calls
-----------------------------
Your subclass of ``AliasAnalysis`` is required to invoke two methods on the
``AliasAnalysis`` base class: ``getAnalysisUsage`` and
``InitializeAliasAnalysis``. In particular, your implementation of
``getAnalysisUsage`` should explicitly call into the
``AliasAnalysis::getAnalysisUsage`` method in addition to doing any declaring
any pass dependencies your pass has. Thus you should have something like this:
.. code-block:: c++
void getAnalysisUsage(AnalysisUsage &amp;AU) const {
AliasAnalysis::getAnalysisUsage(AU);
// declare your dependencies here.
}
Additionally, your must invoke the ``InitializeAliasAnalysis`` method from your
analysis run method (``run`` for a ``Pass``, ``runOnFunction`` for a
``FunctionPass``, or ``InitializePass`` for an ``ImmutablePass``). For example
(as part of a ``Pass``):
.. code-block:: c++
bool run(Module &M) {
InitializeAliasAnalysis(this);
// Perform analysis here...
return false;
}
Interfaces which may be specified
---------------------------------
All of the `AliasAnalysis
<http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html>`__ virtual methods
default to providing `chaining`_ to another alias analysis implementation, which
ends up returning conservatively correct information (returning "May" Alias and
"Mod/Ref" for alias and mod/ref queries respectively). Depending on the
capabilities of the analysis you are implementing, you just override the
interfaces you can improve.
.. _chaining:
.. _chain:
``AliasAnalysis`` chaining behavior
-----------------------------------
With only one special exception (the `no-aa`_ pass) every alias analysis pass
chains to another alias analysis implementation (for example, the user can
specify "``-basicaa -ds-aa -licm``" to get the maximum benefit from both alias
analyses). The alias analysis class automatically takes care of most of this
for methods that you don't override. For methods that you do override, in code
paths that return a conservative MayAlias or Mod/Ref result, simply return
whatever the superclass computes. For example:
.. code-block:: c++
AliasAnalysis::AliasResult alias(const Value *V1, unsigned V1Size,
const Value *V2, unsigned V2Size) {
if (...)
return NoAlias;
...
// Couldn't determine a must or no-alias result.
return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
}
In addition to analysis queries, you must make sure to unconditionally pass LLVM
`update notification`_ methods to the superclass as well if you override them,
which allows all alias analyses in a change to be updated.
.. _update notification:
Updating analysis results for transformations
---------------------------------------------
Alias analysis information is initially computed for a static snapshot of the
program, but clients will use this information to make transformations to the
code. All but the most trivial forms of alias analysis will need to have their
analysis results updated to reflect the changes made by these transformations.
The ``AliasAnalysis`` interface exposes four methods which are used to
communicate program changes from the clients to the analysis implementations.
Various alias analysis implementations should use these methods to ensure that
their internal data structures are kept up-to-date as the program changes (for
example, when an instruction is deleted), and clients of alias analysis must be
sure to call these interfaces appropriately.
The ``deleteValue`` method
^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``deleteValue`` method is called by transformations when they remove an
instruction or any other value from the program (including values that do not
use pointers). Typically alias analyses keep data structures that have entries
for each value in the program. When this method is called, they should remove
any entries for the specified value, if they exist.
The ``copyValue`` method
^^^^^^^^^^^^^^^^^^^^^^^^
The ``copyValue`` method is used when a new value is introduced into the
program. There is no way to introduce a value into the program that did not
exist before (this doesn't make sense for a safe compiler transformation), so
this is the only way to introduce a new value. This method indicates that the
new value has exactly the same properties as the value being copied.
The ``replaceWithNewValue`` method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This method is a simple helper method that is provided to make clients easier to
use. It is implemented by copying the old analysis information to the new
value, then deleting the old value. This method cannot be overridden by alias
analysis implementations.
The ``addEscapingUse`` method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``addEscapingUse`` method is used when the uses of a pointer value have
changed in ways that may invalidate precomputed analysis information.
Implementations may either use this callback to provide conservative responses
for points whose uses have change since analysis time, or may recompute some or
all of their internal state to continue providing accurate responses.
In general, any new use of a pointer value is considered an escaping use, and
must be reported through this callback, *except* for the uses below:
* A ``bitcast`` or ``getelementptr`` of the pointer
* A ``store`` through the pointer (but not a ``store`` *of* the pointer)
* A ``load`` through the pointer
Efficiency Issues
-----------------
From the LLVM perspective, the only thing you need to do to provide an efficient
alias analysis is to make sure that alias analysis **queries** are serviced
quickly. The actual calculation of the alias analysis results (the "run"
method) is only performed once, but many (perhaps duplicate) queries may be
performed. Because of this, try to move as much computation to the run method
as possible (within reason).
Limitations
-----------
The AliasAnalysis infrastructure has several limitations which make writing a
new ``AliasAnalysis`` implementation difficult.
There is no way to override the default alias analysis. It would be very useful
to be able to do something like "``opt -my-aa -O2``" and have it use ``-my-aa``
for all passes which need AliasAnalysis, but there is currently no support for
that, short of changing the source code and recompiling. Similarly, there is
also no way of setting a chain of analyses as the default.
There is no way for transform passes to declare that they preserve
``AliasAnalysis`` implementations. The ``AliasAnalysis`` interface includes
``deleteValue`` and ``copyValue`` methods which are intended to allow a pass to
keep an AliasAnalysis consistent, however there's no way for a pass to declare
in its ``getAnalysisUsage`` that it does so. Some passes attempt to use
``AU.addPreserved<AliasAnalysis>``, however this doesn't actually have any
effect.
``AliasAnalysisCounter`` (``-count-aa``) and ``AliasDebugger`` (``-debug-aa``)
are implemented as ``ModulePass`` classes, so if your alias analysis uses
``FunctionPass``, it won't be able to use these utilities. If you try to use
them, the pass manager will silently route alias analysis queries directly to
``BasicAliasAnalysis`` instead.
Similarly, the ``opt -p`` option introduces ``ModulePass`` passes between each
pass, which prevents the use of ``FunctionPass`` alias analysis passes.
The ``AliasAnalysis`` API does have functions for notifying implementations when
values are deleted or copied, however these aren't sufficient. There are many
other ways that LLVM IR can be modified which could be relevant to
``AliasAnalysis`` implementations which can not be expressed.
The ``AliasAnalysisDebugger`` utility seems to suggest that ``AliasAnalysis``
implementations can expect that they will be informed of any relevant ``Value``
before it appears in an alias query. However, popular clients such as ``GVN``
don't support this, and are known to trigger errors when run with the
``AliasAnalysisDebugger``.
Due to several of the above limitations, the most obvious use for the
``AliasAnalysisCounter`` utility, collecting stats on all alias queries in a
compilation, doesn't work, even if the ``AliasAnalysis`` implementations don't
use ``FunctionPass``. There's no way to set a default, much less a default
sequence, and there's no way to preserve it.
The ``AliasSetTracker`` class (which is used by ``LICM``) makes a
non-deterministic number of alias queries. This can cause stats collected by
``AliasAnalysisCounter`` to have fluctuations among identical runs, for
example. Another consequence is that debugging techniques involving pausing
execution after a predetermined number of queries can be unreliable.
Many alias queries can be reformulated in terms of other alias queries. When
multiple ``AliasAnalysis`` queries are chained together, it would make sense to
start those queries from the beginning of the chain, with care taken to avoid
infinite looping, however currently an implementation which wants to do this can
only start such queries from itself.
Using alias analysis results
============================
There are several different ways to use alias analysis results. In order of
preference, these are:
Using the ``MemoryDependenceAnalysis`` Pass
-------------------------------------------
The ``memdep`` pass uses alias analysis to provide high-level dependence
information about memory-using instructions. This will tell you which store
feeds into a load, for example. It uses caching and other techniques to be
efficient, and is used by Dead Store Elimination, GVN, and memcpy optimizations.
.. _AliasSetTracker:
Using the ``AliasSetTracker`` class
-----------------------------------
Many transformations need information about alias **sets** that are active in
some scope, rather than information about pairwise aliasing. The
`AliasSetTracker <http://llvm.org/doxygen/classllvm_1_1AliasSetTracker.html>`__
class is used to efficiently build these Alias Sets from the pairwise alias
analysis information provided by the ``AliasAnalysis`` interface.
First you initialize the AliasSetTracker by using the "``add``" methods to add
information about various potentially aliasing instructions in the scope you are
interested in. Once all of the alias sets are completed, your pass should
simply iterate through the constructed alias sets, using the ``AliasSetTracker``
``begin()``/``end()`` methods.
The ``AliasSet``\s formed by the ``AliasSetTracker`` are guaranteed to be
disjoint, calculate mod/ref information and volatility for the set, and keep
track of whether or not all of the pointers in the set are Must aliases. The
AliasSetTracker also makes sure that sets are properly folded due to call
instructions, and can provide a list of pointers in each set.
As an example user of this, the `Loop Invariant Code Motion
<doxygen/structLICM.html>`_ pass uses ``AliasSetTracker``\s to calculate alias
sets for each loop nest. If an ``AliasSet`` in a loop is not modified, then all
load instructions from that set may be hoisted out of the loop. If any alias
sets are stored to **and** are must alias sets, then the stores may be sunk
to outside of the loop, promoting the memory location to a register for the
duration of the loop nest. Both of these transformations only apply if the
pointer argument is loop-invariant.
The AliasSetTracker implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The AliasSetTracker class is implemented to be as efficient as possible. It
uses the union-find algorithm to efficiently merge AliasSets when a pointer is
inserted into the AliasSetTracker that aliases multiple sets. The primary data
structure is a hash table mapping pointers to the AliasSet they are in.
The AliasSetTracker class must maintain a list of all of the LLVM ``Value*``\s
that are in each AliasSet. Since the hash table already has entries for each
LLVM ``Value*`` of interest, the AliasesSets thread the linked list through
these hash-table nodes to avoid having to allocate memory unnecessarily, and to
make merging alias sets extremely efficient (the linked list merge is constant
time).
You shouldn't need to understand these details if you are just a client of the
AliasSetTracker, but if you look at the code, hopefully this brief description
will help make sense of why things are designed the way they are.
Using the ``AliasAnalysis`` interface directly
----------------------------------------------
If neither of these utility class are what your pass needs, you should use the
interfaces exposed by the ``AliasAnalysis`` class directly. Try to use the
higher-level methods when possible (e.g., use mod/ref information instead of the
`alias`_ method directly if possible) to get the best precision and efficiency.
Existing alias analysis implementations and clients
===================================================
If you're going to be working with the LLVM alias analysis infrastructure, you
should know what clients and implementations of alias analysis are available.
In particular, if you are implementing an alias analysis, you should be aware of
the `the clients`_ that are useful for monitoring and evaluating different
implementations.
.. _various alias analysis implementations:
Available ``AliasAnalysis`` implementations
-------------------------------------------
This section lists the various implementations of the ``AliasAnalysis``
interface. With the exception of the `-no-aa`_ implementation, all of these
`chain`_ to other alias analysis implementations.
.. _no-aa:
.. _-no-aa:
The ``-no-aa`` pass
^^^^^^^^^^^^^^^^^^^
The ``-no-aa`` pass is just like what it sounds: an alias analysis that never
returns any useful information. This pass can be useful if you think that alias
analysis is doing something wrong and are trying to narrow down a problem.
The ``-basicaa`` pass
^^^^^^^^^^^^^^^^^^^^^
The ``-basicaa`` pass is an aggressive local analysis that *knows* many
important facts:
* Distinct globals, stack allocations, and heap allocations can never alias.
* Globals, stack allocations, and heap allocations never alias the null pointer.
* Different fields of a structure do not alias.
* Indexes into arrays with statically differing subscripts cannot alias.
* Many common standard C library functions `never access memory or only read
memory`_.
* Pointers that obviously point to constant globals "``pointToConstantMemory``".
* Function calls can not modify or references stack allocations if they never
escape from the function that allocates them (a common case for automatic
arrays).
The ``-globalsmodref-aa`` pass
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This pass implements a simple context-sensitive mod/ref and alias analysis for
internal global variables that don't "have their address taken". If a global
does not have its address taken, the pass knows that no pointers alias the
global. This pass also keeps track of functions that it knows never access
memory or never read memory. This allows certain optimizations (e.g. GVN) to
eliminate call instructions entirely.
The real power of this pass is that it provides context-sensitive mod/ref
information for call instructions. This allows the optimizer to know that calls
to a function do not clobber or read the value of the global, allowing loads and
stores to be eliminated.
.. note::
This pass is somewhat limited in its scope (only support non-address taken
globals), but is very quick analysis.
The ``-steens-aa`` pass
^^^^^^^^^^^^^^^^^^^^^^^
The ``-steens-aa`` pass implements a variation on the well-known "Steensgaard's
algorithm" for interprocedural alias analysis. Steensgaard's algorithm is a
unification-based, flow-insensitive, context-insensitive, and field-insensitive
alias analysis that is also very scalable (effectively linear time).
The LLVM ``-steens-aa`` pass implements a "speculatively field-**sensitive**"
version of Steensgaard's algorithm using the Data Structure Analysis framework.
This gives it substantially more precision than the standard algorithm while
maintaining excellent analysis scalability.
.. note::
``-steens-aa`` is available in the optional "poolalloc" module. It is not part
of the LLVM core.
The ``-ds-aa`` pass
^^^^^^^^^^^^^^^^^^^
The ``-ds-aa`` pass implements the full Data Structure Analysis algorithm. Data
Structure Analysis is a modular unification-based, flow-insensitive,
context-**sensitive**, and speculatively field-**sensitive** alias
analysis that is also quite scalable, usually at ``O(n * log(n))``.
This algorithm is capable of responding to a full variety of alias analysis
queries, and can provide context-sensitive mod/ref information as well. The
only major facility not implemented so far is support for must-alias
information.
.. note::
``-ds-aa`` is available in the optional "poolalloc" module. It is not part of
the LLVM core.
The ``-scev-aa`` pass
^^^^^^^^^^^^^^^^^^^^^
The ``-scev-aa`` pass implements AliasAnalysis queries by translating them into
ScalarEvolution queries. This gives it a more complete understanding of
``getelementptr`` instructions and loop induction variables than other alias
analyses have.
Alias analysis driven transformations
-------------------------------------
LLVM includes several alias-analysis driven transformations which can be used
with any of the implementations above.
The ``-adce`` pass
^^^^^^^^^^^^^^^^^^
The ``-adce`` pass, which implements Aggressive Dead Code Elimination uses the
``AliasAnalysis`` interface to delete calls to functions that do not have
side-effects and are not used.
The ``-licm`` pass
^^^^^^^^^^^^^^^^^^
The ``-licm`` pass implements various Loop Invariant Code Motion related
transformations. It uses the ``AliasAnalysis`` interface for several different
transformations:
* It uses mod/ref information to hoist or sink load instructions out of loops if
there are no instructions in the loop that modifies the memory loaded.
* It uses mod/ref information to hoist function calls out of loops that do not
write to memory and are loop-invariant.
* If uses alias information to promote memory objects that are loaded and stored
to in loops to live in a register instead. It can do this if there are no may
aliases to the loaded/stored memory location.
The ``-argpromotion`` pass
^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``-argpromotion`` pass promotes by-reference arguments to be passed in
by-value instead. In particular, if pointer arguments are only loaded from it
passes in the value loaded instead of the address to the function. This pass
uses alias information to make sure that the value loaded from the argument
pointer is not modified between the entry of the function and any load of the
pointer.
The ``-gvn``, ``-memcpyopt``, and ``-dse`` passes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These passes use AliasAnalysis information to reason about loads and stores.
.. _the clients:
Clients for debugging and evaluation of implementations
-------------------------------------------------------
These passes are useful for evaluating the various alias analysis
implementations. You can use them with commands like:
.. code-block:: bash
% opt -ds-aa -aa-eval foo.bc -disable-output -stats
The ``-print-alias-sets`` pass
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``-print-alias-sets`` pass is exposed as part of the ``opt`` tool to print
out the Alias Sets formed by the `AliasSetTracker`_ class. This is useful if
you're using the ``AliasSetTracker`` class. To use it, use something like:
.. code-block:: bash
% opt -ds-aa -print-alias-sets -disable-output
The ``-count-aa`` pass
^^^^^^^^^^^^^^^^^^^^^^
The ``-count-aa`` pass is useful to see how many queries a particular pass is
making and what responses are returned by the alias analysis. As an example:
.. code-block:: bash
% opt -basicaa -count-aa -ds-aa -count-aa -licm
will print out how many queries (and what responses are returned) by the
``-licm`` pass (of the ``-ds-aa`` pass) and how many queries are made of the
``-basicaa`` pass by the ``-ds-aa`` pass. This can be useful when debugging a
transformation or an alias analysis implementation.
The ``-aa-eval`` pass
^^^^^^^^^^^^^^^^^^^^^
The ``-aa-eval`` pass simply iterates through all pairs of pointers in a
function and asks an alias analysis whether or not the pointers alias. This
gives an indication of the precision of the alias analysis. Statistics are
printed indicating the percent of no/may/must aliases found (a more precise
algorithm will have a lower number of may aliases).
Memory Dependence Analysis
==========================
If you're just looking to be a client of alias analysis information, consider
using the Memory Dependence Analysis interface instead. MemDep is a lazy,
caching layer on top of alias analysis that is able to answer the question of
what preceding memory operations a given instruction depends on, either at an
intra- or inter-block level. Because of its laziness and caching policy, using
MemDep can be a significant performance win over accessing alias analysis
directly.

569
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>

441
docs/Atomics.rst Normal file
View File

@ -0,0 +1,441 @@
.. _atomics:
==============================================
LLVM Atomic Instructions and Concurrency Guide
==============================================
.. contents::
:local:
Introduction
============
Historically, LLVM has not had very strong support for concurrency; some minimal
intrinsics were provided, and ``volatile`` 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.
The atomic instructions are designed specifically to provide readable IR and
optimized code generation for the following:
* The new C++0x ``<atomic>`` header. (`C++0x draft available here
<http://www.open-std.org/jtc1/sc22/wg21/>`_.) (`C1x draft available here
<http://www.open-std.org/jtc1/sc22/wg14/>`_.)
* Proper semantics for Java-style memory, for both ``volatile`` and regular
shared variables. (`Java Specification
<http://java.sun.com/docs/books/jls/third_edition/html/memory.html>`_)
* gcc-compatible ``__sync_*`` builtins. (`Description
<http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html>`_)
* Other scenarios with atomic semantics, including ``static`` variables with
non-trivial constructors in C++.
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.
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.
.. _Optimization outside atomic:
Optimization outside atomic
===========================
The basic ``'load'`` and ``'store'`` allow a variety of optimizations, but can
lead to undefined results in a concurrent environment; see `NotAtomic`_. 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.
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:
.. code-block:: c
/* 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 < 100; i++) {
if (a[i])
x += 1;
}
}
The following is equivalent in non-concurrent situations:
.. code-block:: c
int x;
void f(int* a) {
int xtemp = x;
for (int i = 0; i < 100; i++) {
if (a[i])
xtemp += 1;
}
x = xtemp;
}
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.)
Note that speculative loads are allowed; a load which is part of a race returns
``undef``, but does not have undefined behavior.
Atomic instructions
===================
For cases where simple loads and stores are not sufficient, LLVM provides
various atomic instructions. The exact guarantees provided depend on the
ordering; see `Atomic orderings`_.
``load atomic`` and ``store atomic`` provide the same basic functionality as
non-atomic loads and stores, but provide additional guarantees in situations
where threads and signals are involved.
``cmpxchg`` and ``atomicrmw`` are essentially like an atomic load followed by an
atomic store (where the store is conditional for ``cmpxchg``), 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.
A ``fence`` 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.
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.
.. _Atomic orderings:
Atomic orderings
================
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 `LangRef Ordering <LangRef.html#ordering>`_.)
.. _NotAtomic:
NotAtomic
---------
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.
Relevant standard
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 `LangRef Memory Model <LangRef.html#memmodel>`_.)
Notes for frontends
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.)
Notes for optimizers
Introducing loads to shared variables along a codepath where they would not
otherwise exist is allowed; introducing stores to shared variables is not. See
`Optimization outside atomic`_.
Notes for code generation
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.)
Unordered
---------
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.
Relevant standard
This is intended to match the Java memory model for shared variables.
Notes for frontends
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.)
Notes for optimizers
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.
Notes for code generation
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
``LDRD`` on ARM).
Monotonic
---------
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.
Relevant standard
This corresponds to the C++0x/C1x ``memory_order_relaxed``; see those
standards for the exact definition.
Notes for frontends
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 ``fence``.
Notes for optimizers
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.
Notes for code generation
Code generation is essentially the same as that for unordered for loads and
stores. No fences are required. ``cmpxchg`` and ``atomicrmw`` are required
to appear as a single operation.
Acquire
-------
Acquire provides a barrier of the sort necessary to acquire a lock to access
other memory with normal loads and stores.
Relevant standard
This corresponds to the C++0x/C1x ``memory_order_acquire``. It should also be
used for C++0x/C1x ``memory_order_consume``.
Notes for frontends
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.
Notes for optimizers
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.
Notes for code generation
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 (``dmb`` on ARM, ``sync`` on PowerPC, etc.). Putting
such a fence after the equivalent Monotonic operation is sufficient to
maintain Acquire semantics for a memory operation.
Release
-------
Release is similar to Acquire, but with a barrier of the sort necessary to
release a lock.
Relevant standard
This corresponds to the C++0x/C1x ``memory_order_release``.
Notes for frontends
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.
Notes for optimizers
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.
Notes for code generation
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.
AcquireRelease
--------------
AcquireRelease (``acq_rel`` in IR) provides both an Acquire and a Release
barrier (for fences and operations which both read and write memory).
Relevant standard
This corresponds to the C++0x/C1x ``memory_order_acq_rel``.
Notes for frontends
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.
Notes for optimizers
In general, optimizers should treat this like a nothrow call; the possible
optimizations are usually not interesting.
Notes for code generation
This operation has Acquire and Release semantics; see the sections on Acquire
and Release.
SequentiallyConsistent
----------------------
SequentiallyConsistent (``seq_cst`` in IR) provides Acquire semantics for loads
and Release semantics for stores. Additionally, it guarantees that a total
ordering exists between all SequentiallyConsistent operations.
Relevant standard
This corresponds to the C++0x/C1x ``memory_order_seq_cst``, Java volatile, and
the gcc-compatible ``__sync_*`` builtins which do not specify otherwise.
Notes for frontends
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.
Notes for optimizers
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.
Notes for code generation
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.
Atomics and IR optimization
===========================
Predicates for optimizer writers to query:
* ``isSimple()``: A load or store which is not volatile or atomic. This is
what, for example, memcpyopt would check for operations it might transform.
* ``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.
* ``mayReadFromMemory()``/``mayWriteToMemory()``: Existing predicate, but note
that they return true for any operation which is volatile or at least
Monotonic.
* Alias analysis: Note that AA will return ModRef for anything Acquire or
Release, and for the address accessed by any Monotonic operation.
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.
Some examples of how optimizations interact with various kinds of atomic
operations:
* ``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.
* 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.
* 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.
* 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.
Atomics and Codegen
===================
Atomic operations are represented in the SelectionDAG with ``ATOMIC_*`` opcodes.
On architectures which use barrier instructions for all atomic ordering (like
ARM), appropriate fences are split out as the DAG is built.
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.
Common architectures have some way of representing at least a pointer-sized
lock-free ``cmpxchg``; 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.)
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.).
On x86, all atomic loads generate a ``MOV``. SequentiallyConsistent stores
generate an ``XCHG``, other stores generate a ``MOV``. SequentiallyConsistent
fences generate an ``MFENCE``, other fences do not cause any code to be
generated. cmpxchg uses the ``LOCK CMPXCHG`` instruction. ``atomicrmw xchg``
uses ``XCHG``, ``atomicrmw add`` and ``atomicrmw sub`` use ``XADD``, and all
other ``atomicrmw`` operations generate a loop with ``LOCK CMPXCHG``. Depending
on the users of the result, some ``atomicrmw`` operations can be translated into
operations like ``LOCK AND``, but that does not work in general.
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. ``cmpxchg`` and
``atomicrmw`` can be represented using a loop with LL/SC-style instructions
which take some sort of exclusive lock on a cache line (``LDREX`` and ``STREX``
on ARM, etc.). At the moment, the IR does not provide any way to represent a
weak ``cmpxchg`` which would not require a loop.

1470
docs/BitCodeFormat.html
View File

File diff suppressed because it is too large Load Diff

1045
docs/BitCodeFormat.rst Normal file
View File

File diff suppressed because it is too large Load Diff

164
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>

118
docs/BranchWeightMetadata.rst Normal file
View File

@ -0,0 +1,118 @@
.. _branch_weight:
===========================
LLVM Branch Weight Metadata
===========================
.. contents::
:local:
Introduction
============
Branch Weight Metadata represents branch weights as its likeliness to be
taken. Metadata is assigned to the ``TerminatorInst`` as a ``MDNode`` of the
``MD_prof`` kind. The first operator is always a ``MDString`` node with the
string "branch_weights". Number of operators depends on the terminator type.
Branch weights might be fetch from the profiling file, or generated based on
`__builtin_expect`_ instruction.
All weights are represented as an unsigned 32-bit values, where higher value
indicates greater chance to be taken.
Supported Instructions
======================
``BranchInst``
^^^^^^^^^^^^^^
Metadata is only assign to the conditional branches. There are two extra
operarands, for the true and the false branch.
.. code-block:: llvm
!0 = metadata !{
metadata !"branch_weights",
i32 <TRUE_BRANCH_WEIGHT>,
i32 <FALSE_BRANCH_WEIGHT>
}
``SwitchInst``
^^^^^^^^^^^^^^
Branch weights are assign to every case (including ``default`` case which is
always case #0).
.. code-block:: llvm
!0 = metadata !{
metadata !"branch_weights",
i32 <DEFAULT_BRANCH_WEIGHT>
[ , i32 <CASE_BRANCH_WEIGHT> ... ]
}
``IndirectBrInst``
^^^^^^^^^^^^^^^^^^
Branch weights are assign to every destination.
.. code-block:: llvm
!0 = metadata !{
metadata !"branch_weights",
i32 <LABEL_BRANCH_WEIGHT>
[ , i32 <LABEL_BRANCH_WEIGHT> ... ]
}
Other
^^^^^
Other terminator instructions are not allowed to contain Branch Weight Metadata.
.. _\__builtin_expect:
Built-in ``expect`` Instructions
================================
``__builtin_expect(long exp, long c)`` instruction provides branch prediction
information. The return value is the value of ``exp``.
It is especially useful in conditional statements. Currently Clang supports two
conditional statements:
``if`` statement
^^^^^^^^^^^^^^^^
The ``exp`` parameter is the condition. The ``c`` parameter is the expected
comparison 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:
.. code-block:: c++
if (__builtin_expect(x > 0, 1)) {
// This block is likely to be taken.
}
``switch`` statement
^^^^^^^^^^^^^^^^^^^^
The ``exp`` parameter is the value. The ``c`` parameter is the expected
value. If the expected value doesn't show on the cases list, the ``default``
case is assumed to be likely taken.
.. code-block:: c++
switch (__builtin_expect(x, 5)) {
default: break;
case 0: // ...
case 3: // ...
case 5: // This case is likely to be taken.
}
CFG Modifications
=================
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.

239
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 12:21:59 +0100 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

218
docs/Bugpoint.rst Normal file
View File

@ -0,0 +1,218 @@
.. _bugpoint:
====================================
LLVM bugpoint tool: design and usage
====================================
.. contents::
:local:
Description
===========
``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 example, if ``opt`` 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.
For detailed case scenarios, such as debugging ``opt``, or one of the LLVM code
generators, see `How To Submit a Bug Report document <HowToSubmitABug.html>`_.
Design Philosophy
=================
``bugpoint`` is designed to be a useful tool without requiring any hooks into
the LLVM infrastructure at all. It works with any and all LLVM 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. ``bugpoint`` 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 ``bugpoint`` is generally very quick unless debugging a miscompilation
where each test of the program (which requires executing it) takes a long time.
Automatic Debugger Selection
----------------------------
``bugpoint`` reads each ``.bc`` or ``.ll`` file specified on the command line
and links them together into a single module, called the test 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), ``bugpoint`` starts the `crash debugger`_.
Otherwise, if the ``-output`` option was not specified, ``bugpoint`` runs the
test program with the "safe" backend (which is assumed to generate good code) to
generate a reference output. Once ``bugpoint`` has a reference output for the
test program, it tries executing it with the selected code generator. If the
selected code generator crashes, ``bugpoint`` starts the `crash debugger`_ 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 `code generator debugger`_.
Finally, if the output of the selected code generator matches the reference
output, ``bugpoint`` 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
`miscompilation debugger`_. Otherwise, there is no problem ``bugpoint`` can
debug.
.. _crash debugger:
Crash debugger
--------------
If an optimizer or code generator crashes, ``bugpoint`` will try as hard as it
can to reduce the list of passes (for optimizer crashes) and the size of the
test program. First, ``bugpoint`` figures out which combination of optimizer
passes triggers the bug. This is useful when debugging a problem exposed by
``opt``, for example, because it runs over 38 passes.
Next, ``bugpoint`` 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, ``bugpoint``
deletes any individual LLVM instructions whose absence does not eliminate the
failure. At the end, ``bugpoint`` should tell you what passes crash, give you a
bitcode file, and give you instructions on how to reproduce the failure with
``opt`` or ``llc``.
.. _code generator debugger:
Code generator debugger
-----------------------
The code generator debugger attempts to narrow down the amount of code that is
being miscompiled by the selected code generator. To do this, it takes the test
program and partitions it into two pieces: one piece which it compiles with the
"safe" 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 "safe" backend], respectively), and instructions for reproducing the
problem. The code generator debugger assumes that the "safe" backend produces
good code.
.. _miscompilation debugger:
Miscompilation debugger
-----------------------
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.
Advice for using bugpoint
=========================
``bugpoint`` can be a remarkably useful tool, but it sometimes works in
non-obvious ways. Here are some hints and tips:
* In the code generator and miscompilation debuggers, ``bugpoint`` only works
with programs that have deterministic output. Thus, if the program outputs
``argv[0]``, the date, time, or any other "random" data, ``bugpoint`` 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.
* 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.
* ``bugpoint`` is extremely useful when working on a new optimization: it helps
track down regressions quickly. To avoid having to relink ``bugpoint`` every
time you change your optimization however, have ``bugpoint`` dynamically load
your optimization with the ``-load`` option.
* ``bugpoint`` 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:
.. code-block:: bash
bugpoint ... |& tee bugpoint.log
to get a copy of ``bugpoint``'s output in the file ``bugpoint.log``, as well
as on your terminal.
* ``bugpoint`` cannot debug problems with the LLVM linker. If ``bugpoint``
crashes before you see its "All input ok" message, you might try ``llvm-link
-v`` on the same set of input files. If that also crashes, you may be
experiencing a linker bug.
* ``bugpoint`` is useful for proactively finding bugs in LLVM. Invoking
``bugpoint`` with the ``-find-bugs`` 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 ``bugpoint``.
What to do when bugpoint isn't enough
=====================================
Sometimes, ``bugpoint`` is not enough. In particular, InstCombine and
TargetLowering both have visitor structured code with lots of potential
transformations. If the process of using bugpoint has left you with still too
much code to figure out and the problem seems to be in instcombine, the
following steps may help. These same techniques are useful with TargetLowering
as well.
Turn on ``-debug-only=instcombine`` and see which transformations within
instcombine are firing by selecting out lines with "``IC``" in them.
At this point, you have a decision to make. Is the number of transformations
small enough to step through them using a debugger? If so, then try that.
If there are too many transformations, then a source modification approach may
be helpful. In this approach, you can modify the source code of instcombine to
disable just those transformations that are being performed on your test input
and perform a binary search over the set of transformations. One set of places
to modify are the "``visit*``" methods of ``InstCombiner`` (*e.g.*
``visitICmpInst``) by adding a "``return false``" as the first line of the
method.
If that still doesn't remove enough, then change the caller of
``InstCombiner::DoOneIteration``, ``InstCombiner::runOnFunction`` to limit the
number of iterations.
You may also find it useful to use "``-stats``" now to see what parts of
instcombine are firing. This can guide where to put additional reporting code.
At this point, if the amount of transformations is still too large, then
inserting code to limit whether or not to execute the body of the code in the
visit function can be helpful. Add a static counter which is incremented on
every invocation of the function. Then add code which simply returns false on
desired ranges. For example:
.. code-block:: c++
static int calledCount = 0;
calledCount++;
DEBUG(if (calledCount < 212) return false);
DEBUG(if (calledCount > 217) return false);
DEBUG(if (calledCount == 213) return false);
DEBUG(if (calledCount == 214) return false);
DEBUG(if (calledCount == 215) return false);
DEBUG(if (calledCount == 216) return false);
DEBUG(dbgs() << "visitXOR calledCount: " << calledCount << "\n");
DEBUG(dbgs() << "I: "; I->dump());
could be added to ``visitXOR`` to limit ``visitXor`` to being applied only to
calls 212 and 217. This is from an actual test case and raises an important
point---a simple binary search may not be sufficient, as transformations that
interact may require isolating more than one call. In TargetLowering, use
``return SDNode();`` instead of ``return false;``.
Now that that the number of transformations is down to a manageable number, try
examining the output to see if you can figure out which transformations are
being done. If that can be figured out, then do the usual debugging. If which
code corresponds to the transformation being performed isn't obvious, set a
breakpoint after the call count based disabling and step through the code.
Alternatively, you can use "``printf``" style debugging to report waypoints.

584
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>

423
docs/CMake.rst Normal file
View File

@ -0,0 +1,423 @@
.. _building-with-cmake:
========================
Building LLVM with CMake
========================
.. contents::
:local:
Introduction
============
`CMake <http://www.cmake.org/>`_ 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.
If you are really anxious about getting a functional LLVM build, go to the
`Quick start`_ section. If you are a CMake novice, start on `Basic CMake usage`_
and then go back to the `Quick start`_ once you know what you are doing. The
`Options and variables`_ section is a reference for customizing your build. If
you already have experience with CMake, this is the recommended starting point.
.. _Quick start:
Quick start
===========
We use here the command-line, non-interactive CMake interface.
#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
CMake. Version 2.8 is the minimum required.
#. Open a shell. Your development tools must be reachable from this shell
through the PATH environment variable.
#. Create a directory for containing the build. It is not supported to build
LLVM on the source directory. cd to this directory:
.. code-block:: bash
$ mkdir mybuilddir
$ cd mybuilddir
#. Execute this command on the shell replacing `path/to/llvm/source/root` with
the path to the root of your LLVM source tree:
.. code-block:: bash
$ cmake path/to/llvm/source/root
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 `Options and variables`_ section for
fine-tuning your build
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 `Usage`_ section.
.. _Basic CMake usage:
.. _Usage:
Basic CMake usage
=================
This section explains basic aspects of CMake, mostly for explaining those
options which you may need on your day-to-day usage.
CMake comes with extensive documentation in the form of html files and on the
cmake executable itself. Execute ``cmake --help`` for further help options.
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 *Generator* for creating files for your build tool. You can
explicitly specify the generator with the command line option ``-G "Name of the
generator"``. For knowing the available generators on your platform, execute
.. code-block:: bash
$ cmake --help
This will list the generator's names at the end of the help text. Generator's
names are case-sensitive. Example:
.. code-block:: bash
$ cmake -G "Visual Studio 9 2008" path/to/llvm/source/root
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 ``-G`` option.
.. todo::
Explain variables and cache. Move explanation here from #options section.
.. _Options and variables:
Options and variables
=====================
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:
.. code-block:: bash
$ cmake -DVARIABLE=value path/to/llvm/source
You can set a variable after the initial CMake invocation for changing its
value. You can also undefine a variable:
.. code-block:: bash
$ cmake -UVARIABLE path/to/llvm/source
Variables are stored on the CMake cache. This is a file named ``CMakeCache.txt``
on the root of the build directory. Do not hand-edit it.
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:
.. code-block:: bash
$ cmake -DVARIABLE:TYPE=value path/to/llvm/source
Frequently-used CMake variables
-------------------------------
Here are listed some of the CMake variables that are used often, along with a
brief explanation and LLVM-specific notes. For full documentation, check the
CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
**CMAKE_BUILD_TYPE**:STRING
Sets the build type for ``make`` 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.
**CMAKE_INSTALL_PREFIX**:PATH
Path where LLVM will be installed if "make install" is invoked or the
"INSTALL" target is built.
**LLVM_LIBDIR_SUFFIX**:STRING
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``.
**CMAKE_C_FLAGS**:STRING
Extra flags to use when compiling C source files.
**CMAKE_CXX_FLAGS**:STRING
Extra flags to use when compiling C++ source files.
**BUILD_SHARED_LIBS**:BOOL
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.
.. _LLVM-specific variables:
LLVM-specific variables
-----------------------
**LLVM_TARGETS_TO_BUILD**:STRING
Semicolon-separated list of targets to build, or *all* for building all
targets. Case-sensitive. For Visual C++ defaults to *X86*. On the other cases
defaults to *all*. Example: ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
**LLVM_BUILD_TOOLS**:BOOL
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 *llvm-as* with a makefile-based system executing *make
llvm-as* on the root of your build directory.
**LLVM_INCLUDE_TOOLS**:BOOL
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.
**LLVM_BUILD_EXAMPLES**:BOOL
Build LLVM examples. Defaults to OFF. Targets for building each example are
generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
details.
**LLVM_INCLUDE_EXAMPLES**:BOOL
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.
**LLVM_BUILD_TESTS**:BOOL
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
*UnitTestNameTests* (where at this time *UnitTestName* can be ADT, Analysis,
ExecutionEngine, JIT, Support, Transform, VMCore; see the subdirectories of
*unittests* for an updated list.) It is possible to build all unit tests with
the target *UnitTests*.
**LLVM_INCLUDE_TESTS**:BOOL
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.
**LLVM_APPEND_VC_REV**:BOOL
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.
**LLVM_ENABLE_THREADS**:BOOL
Build with threads support, if available. Defaults to ON.
**LLVM_ENABLE_ASSERTIONS**:BOOL
Enables code assertions. Defaults to OFF if and only if ``CMAKE_BUILD_TYPE``
is *Release*.
**LLVM_ENABLE_PIC**:BOOL
Add the ``-fPIC`` flag for the compiler command-line, if the compiler supports
this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
**LLVM_ENABLE_WARNINGS**:BOOL
Enable all compiler warnings. Defaults to ON.
**LLVM_ENABLE_PEDANTIC**:BOOL
Enable pedantic mode. This disable compiler specific extensions, is
possible. Defaults to ON.
**LLVM_ENABLE_WERROR**:BOOL
Stop and fail build, if a compiler warning is triggered. Defaults to OFF.
**LLVM_BUILD_32_BITS**:BOOL
Build 32-bits executables and libraries on 64-bits systems. This option is
available only on some 64-bits unix systems. Defaults to OFF.
**LLVM_TARGET_ARCH**:STRING
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.
**LLVM_TABLEGEN**:STRING
Full path to a native TableGen executable (usually named ``tblgen``). This is
intended for cross-compiling: if the user sets this variable, no native
TableGen will be created.
**LLVM_LIT_ARGS**:STRING
Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
others.
**LLVM_LIT_TOOLS_DIR**:PATH
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,
&c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to %PATH%.
**LLVM_ENABLE_FFI**:BOOL
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.
**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to
``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built when it
is empty or it does not point valid path.
**LLVM_USE_OPROFILE**:BOOL
Enable building OProfile JIT support. Defaults to OFF
**LLVM_USE_INTEL_JITEVENTS**:BOOL
Enable building support for Intel JIT Events API. Defaults to OFF
**LLVM_INTEL_JITEVENTS_DIR**:PATH
Path to installation of Intel(R) VTune(TM) Amplifier XE 2011, used to locate
the ``jitprofiling`` library. Default = ``%VTUNE_AMPLIFIER_XE_2011_DIR%``
(Windows) | ``/opt/intel/vtune_amplifier_xe_2011`` (Linux)
Executing the test suite
========================
Testing is performed when the *check* target is built. For instance, if you are
using makefiles, execute this command while on the top level of your build
directory:
.. code-block:: bash
$ make check
On Visual Studio, you may run tests to build the project "check".
Cross compiling
===============
See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ 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 `this section
<http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
for a quick solution.
Also see the `LLVM-specific variables`_ section for variables used when
cross-compiling.
Embedding LLVM in your project
==============================
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:
.. code-block:: cmake
# A convenience variable:
set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
# A bit of a sanity check:
if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
endif()
# We incorporate the CMake features provided by LLVM:
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
include(LLVMConfig)
# Now set the header and library paths:
include_directories( ${LLVM_INCLUDE_DIRS} )
link_directories( ${LLVM_LIBRARY_DIRS} )
add_definitions( ${LLVM_DEFINITIONS} )
# Let's suppose we want to build a JIT compiler with support for
# binary code (no interpreter):
llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
# Finally, we link the LLVM libraries to our executable:
target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
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
`include_directories` for the location of the headers on the LLVM source
directory (if we are building out-of-source.)
Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is
an equivalent variant of snippet shown above:
.. code-block:: cmake
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})
Developing LLVM pass out of source
----------------------------------
It is possible to develop LLVM passes against installed LLVM. An example of
project layout provided below:
.. code-block:: bash
<project dir>/
|
CMakeLists.txt
<pass name>/
|
CMakeLists.txt
Pass.cpp
...
Contents of ``<project dir>/CMakeLists.txt``:
.. code-block:: cmake
find_package(LLVM)
# Define add_llvm_* macro's.
include(AddLLVM)
add_definitions(${LLVM_DEFINITIONS})
include_directories(${LLVM_INCLUDE_DIRS})
link_directories(${LLVM_LIBRARY_DIRS})
add_subdirectory(<pass name>)
Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
.. code-block:: cmake
add_llvm_loadable_module(LLVMPassname
Pass.cpp
)
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:
#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
#. Adding ``add_subdirectory(<pass name>)`` line into
``<LLVM root>/lib/Transform/CMakeLists.txt``.
Compiler/Platform specific topics
=================================
Notes for specific compilers and/or platforms.
Microsoft Visual C++
--------------------
**LLVM_COMPILER_JOBS**:STRING
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.

3189
docs/CodeGenerator.html
View File

File diff suppressed because it is too large Load Diff

2428
docs/CodeGenerator.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1568
docs/CodingStandards.html
View File

File diff suppressed because it is too large Load Diff

1147
docs/CodingStandards.rst Normal file
View File

File diff suppressed because it is too large Load Diff

261
docs/CommandGuide/FileCheck.pod → docs/CommandGuide/FileCheck.rst
View File

@ -1,67 +1,87 @@
=pod
=head1 NAME
FileCheck - Flexible pattern matching file verifier
===================================================
=head1 SYNOPSIS
B<FileCheck> I<match-filename> [I<--check-prefix=XXX>] [I<--strict-whitespace>]
SYNOPSIS
--------
=head1 DESCRIPTION
B<FileCheck> reads two files (one from standard input, and one specified on the
**FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
DESCRIPTION
-----------
**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
The *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
OPTIONS
-------
=item B<-help>
Print a summary of command line options.
=item B<--check-prefix> I<prefix>
**-help**
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.
Print a summary of command line options.
=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>
**--check-prefix** *prefix*
Show the version number of this program.
FileCheck searches the contents of *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 **--check-prefix** argument allows you to specify
a specific prefix to match.
=back
=head1 EXIT STATUS
If B<FileCheck> verifies that the file matches the expected contents, it exits
**--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.
**-version**
Show the version number of this program.
EXIT STATUS
-----------
If **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
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
.. code-block:: llvm
; 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
@ -69,21 +89,25 @@ 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
}
.. code-block:: llvm
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
@ -102,35 +126,40 @@ 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.
The FileCheck -check-prefix option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=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
}
.. code-block:: llvm
; 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.
The "CHECK-NEXT:" directive
~~~~~~~~~~~~~~~~~~~~~~~~~~~
=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
@ -138,64 +167,78 @@ 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
}
.. code-block:: llvm
define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
%tmp3 = load <2 x double>* %A, align 16
%tmp7 = insertelement <2 x double> undef, double %B, i32 0
%tmp9 = shufflevector <2 x double> %tmp3,
<2 x double> %tmp7,
<2 x i32> < i32 0, i32 2 >
store <2 x double> %tmp9, <2 x double>* %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.
The "CHECK-NOT:" directive
~~~~~~~~~~~~~~~~~~~~~~~~~~
=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
}
.. code-block:: llvm
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
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
double braces: **{{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]}}
.. code-block:: llvm
; 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.
@ -204,11 +247,12 @@ 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.
**{{[{][{]}}** as your pattern.
FileCheck Variables
~~~~~~~~~~~~~~~~~~~
=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,
@ -216,30 +260,25 @@ 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
.. code-block:: llvm
; CHECK: test5:
; CHECK: notw [[REGISTER:%[a-z]+]]
; CHECK: andw {{.*}}[[REGISTER]]
The first check line matches a regex (**%[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
always contained in **[[ ]]** pairs, are named, and their names can be
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
"**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
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
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

247
docs/CommandGuide/bugpoint.rst Normal file
View File

@ -0,0 +1,247 @@
bugpoint - automatic test case reduction tool
=============================================
SYNOPSIS
--------
**bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
*program arguments*
DESCRIPTION
-----------
**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 **bugpoint**, as well as
advice for using bugpoint, see *llvm/docs/Bugpoint.html* in the LLVM
distribution.
OPTIONS
-------
**--additional-so** *library*
Load the dynamic shared object *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.
**--append-exit-code**\ =\ *{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.
**--args** *program args*
Pass all arguments specified after -args to the test program whenever it runs.
Note that if any of the *program args* start with a '-', you should use:
.. code-block:: perl
bugpoint [bugpoint args] --args -- [program args]
The "--" right after the **--args** option tells **bugpoint** to consider any
options starting with ``-`` to be part of the **--args** option, not as options to
**bugpoint** itself.
**--tool-args** *tool args*
Pass all arguments specified after --tool-args to the LLVM tool under test
(**llc**, **lli**, etc.) whenever it runs. You should use this option in the
following way:
.. code-block:: perl
bugpoint [bugpoint args] --tool-args -- [tool args]
The "--" right after the **--tool-args** option tells **bugpoint** to consider any
options starting with ``-`` to be part of the **--tool-args** option, not as
options to **bugpoint** itself. (See **--args**, above.)
**--safe-tool-args** *tool args*
Pass all arguments specified after **--safe-tool-args** to the "safe" execution
tool.
**--gcc-tool-args** *gcc tool args*
Pass all arguments specified after **--gcc-tool-args** to the invocation of
**gcc**.
**--opt-args** *opt args*
Pass all arguments specified after **--opt-args** to the invocation of **opt**.
**--disable-{dce,simplifycfg}**
Do not run the specified passes to clean up and reduce the size of the test
program. By default, **bugpoint** uses these passes internally when attempting to
reduce test programs. If you're trying to find a bug in one of these passes,
**bugpoint** may crash.
**--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.
**-find-bugs**
Continually randomize the specified passes and run them on the test program
until a bug is found or the user kills **bugpoint**.
**-help**
Print a summary of command line options.
**--input** *filename*
Open *filename* and redirect the standard input of the test program, whenever
it runs, to come from that file.
**--load** *plugin*
Load the dynamic object *plugin* into **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 **-help** and **--load** options together; for example:
.. code-block:: perl
bugpoint --load myNewPass.so -help
**--mlimit** *megabytes*
Specifies an upper limit on memory usage of the optimization and codegen. Set
to zero to disable the limit.
**--output** *filename*
Whenever the test program produces output on its standard output stream, it
should match the contents of *filename* (the "reference output"). If you
do not use this option, **bugpoint** will attempt to generate a reference output
by compiling the program with the "safe" backend and running it.
**--profile-info-file** *filename*
Profile file loaded by **--profile-loader**.
**--run-{int,jit,llc,custom}**
Whenever the test program is compiled, **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, or a
custom command (see **--exec-command**) respectively.
**--safe-{llc,custom}**
When debugging a code generator, **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, or a custom command, (see **--exec-command**)
respectively. The interpreter and the JIT backends cannot currently
be used as the "safe" backends.
**--exec-command** *command*
This option defines the command to use with the **--run-custom** and
**--safe-custom** options to execute the bitcode testcase. This can
be useful for cross-compilation.
**--compile-command** *command*
This option defines the command to use with the **--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:
.. code-block:: sh
#!/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.
**--safe-path** *path*
This option defines the path to the command to execute with the
**--safe-{int,jit,llc,custom}**
option.
EXIT STATUS
-----------
If **bugpoint** succeeds in finding a problem, it will exit with 0. Otherwise,
if an error occurs, it will exit with a non-zero value.
SEE ALSO
--------
opt|opt

256
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
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 09:35:53 +0100 (Sun, 26 Feb 2012) $
</address>
</body>
</html>

53
docs/CommandGuide/index.rst Normal file
View File

@ -0,0 +1,53 @@
.. _commands:
LLVM Command Guide
------------------
The following documents are command descriptions 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 ``--help`` (general options) or
``--help-hidden`` (general and debugging options) arguments to the tool you are
interested in.
Basic Commands
~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
llvm-as
llvm-dis
opt
llc
lli
llvm-link
llvm-ar
llvm-ranlib
llvm-nm
llvm-prof
llvm-config
llvm-diff
llvm-cov
llvm-stress
Debugging Tools
~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
bugpoint
llvm-extract
llvm-bcanalyzer
Developer Tools
~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
FileCheck
tblgen
lit
llvm-build

404
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

474
docs/CommandGuide/lit.rst Normal file
View File

@ -0,0 +1,474 @@
lit - LLVM Integrated Tester
============================
SYNOPSIS
--------
**lit** [*options*] [*tests*]
DESCRIPTION
-----------
**lit** is a portable tool for executing LLVM and Clang style test suites,
summarizing their results, and providing indication of failures. **lit** is
designed to be a lightweight testing tool with as simple a user interface as
possible.
**lit** should be run with one or more *tests* to run specified on the command
line. Tests can be either individual test files or directories to search for
tests (see "TEST DISCOVERY").
Each specified test will be executed (potentially in parallel) and once all
tests have been run **lit** will print summary information on the number of tests
which passed or failed (see "TEST STATUS RESULTS"). The **lit** program will
execute with a non-zero exit code if any tests fail.
By default **lit** will use a succinct progress display and will only print
summary information for test failures. See "OUTPUT OPTIONS" for options
controlling the **lit** progress display and output.
**lit** also includes a number of options for controlling how tests are executed
(specific features may depend on the particular test format). See "EXECUTION
OPTIONS" for more information.
Finally, **lit** also supports additional options for only running a subset of
the options specified on the command line, see "SELECTION OPTIONS" for
more information.
Users interested in the **lit** architecture or designing a **lit** testing
implementation should see "LIT INFRASTRUCTURE"
GENERAL OPTIONS
---------------
**-h**, **--help**
Show the **lit** help message.
**-j** *N*, **--threads**\ =\ *N*
Run *N* tests in parallel. By default, this is automatically chosen to match
the number of detected available CPUs.
**--config-prefix**\ =\ *NAME*
Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites,
instead of *lit.cfg* and *lit.site.cfg*.
**--param** *NAME*, **--param** *NAME*\ =\ *VALUE*
Add a user defined parameter *NAME* with the given *VALUE* (or the empty
string if not given). The meaning and use of these parameters is test suite
dependent.
OUTPUT OPTIONS
--------------
**-q**, **--quiet**
Suppress any output except for test failures.
**-s**, **--succinct**
Show less output, for example don't show information on tests that pass.
**-v**, **--verbose**
Show more information on test failures, for example the entire test output
instead of just the test result.
**--no-progress-bar**
Do not use curses based progress bar.
EXECUTION OPTIONS
-----------------
**--path**\ =\ *PATH*
Specify an addition *PATH* to use when searching for executables in tests.
**--vg**
Run individual tests under valgrind (using the memcheck tool). The
*--error-exitcode* argument for valgrind is used so that valgrind failures will
cause the program to exit with a non-zero status.
**--vg-arg**\ =\ *ARG*
When *--vg* is used, specify an additional argument to pass to valgrind itself.
**--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 *-j
1*.
SELECTION OPTIONS
-----------------
**--max-tests**\ =\ *N*
Run at most *N* tests and then terminate.
**--max-time**\ =\ *N*
Spend at most *N* seconds (approximately) running tests and then terminate.
**--shuffle**
Run the tests in a random order.
ADDITIONAL OPTIONS
------------------
**--debug**
Run **lit** in debug mode, for debugging configuration issues and **lit** itself.
**--show-suites**
List the discovered test suites as part of the standard output.
**--no-tcl-as-sh**
Run Tcl scripts internally (instead of converting to shell scripts).
**--repeat**\ =\ *N*
Run each test *N* times. Currently this is primarily useful for timing tests,
other results are not collated in any reasonable fashion.
EXIT STATUS
-----------
**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).
TEST DISCOVERY
--------------
The inputs passed to **lit** can be either individual tests, or entire
directories or hierarchies of tests to run. When **lit** starts up, the first
thing it does is convert the inputs into a complete list of tests to run as part
of *test discovery*.
In the **lit** model, every test must exist inside some *test suite*. **lit**
resolves the inputs specified on the command line to test suites by searching
upwards from the input path until it finds a *lit.cfg* or *lit.site.cfg*
file. These files serve as both a marker of test suites and as configuration
files which **lit** loads in order to understand how to find and run the tests
inside the test suite.
Once **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, **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 **lit** to provide convenient and flexible
support for out-of-tree builds.
TEST STATUS RESULTS
-------------------
Each test ultimately produces one of the following six results:
**PASS**
The test succeeded.
**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.
**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).
**FAIL**
The test failed.
**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.
**UNSUPPORTED**
The test is not supported in this environment. This is used by test formats
which can report unsupported tests.
Depending on the test format tests may produce additional information about
their status (generally only for failures). See the Output|"OUTPUT OPTIONS"
section for more information.
LIT INFRASTRUCTURE
------------------
This section describes the **lit** testing architecture for users interested in
creating a new **lit** testing implementation, or extending an existing one.
**lit** proper is primarily an infrastructure for discovering and running
arbitrary tests, and to expose a single convenient interface to these
tests. **lit** itself doesn't know how to run tests, rather this logic is
defined by *test suites*.
TEST SUITES
~~~~~~~~~~~
As described in "TEST DISCOVERY", tests are always located inside a *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.
**lit** identifies test suites as directories containing *lit.cfg* or
*lit.site.cfg* files (see also **--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 **--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:
**lit**
The global **lit** configuration object (a *LitConfig* instance), which defines
the builtin test formats, global configuration parameters, and other helper
routines for implementing test configurations.
**config**
This is the config object (a *TestingConfig* instance) for the test suite,
which the config file is expected to populate. The following variables are also
available on the *config* object, some of which must be set by the config and
others are optional or predefined:
**name** *[required]* The name of the test suite, for use in reports and
diagnostics.
**test_format** *[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 *lit.formats* module.
**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.
**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.
**environment** A dictionary representing the environment to use when executing
tests in the suite.
**suffixes** For **lit** test formats which scan directories for tests, this
variable is a list of suffixes to identify test files. Used by: *ShTest*,
*TclTest*.
**substitutions** For **lit** test formats which substitute variables into a test
script, the list of substitutions to perform. Used by: *ShTest*, *TclTest*.
**unsupported** Mark an unsupported directory, all tests within it will be
reported as unsupported. Used by: *ShTest*, *TclTest*.
**parent** The parent configuration, this is the config object for the directory
containing the test suite, or None.
**root** The root configuration. This is the top-most **lit** configuration in
the project.
**on_clone** The config is actually cloned for every subdirectory inside a test
suite, to allow local configuration on a per-directory basis. The *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
*on_clone* function will generally modify), and (3) the test path to the new
directory being scanned.
TEST DISCOVERY
~~~~~~~~~~~~~~
Once test suites are located, **lit** recursively traverses the source directory
(following *test_src_root*) looking for tests. When **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 "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 *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.
LOCAL CONFIGURATION FILES
~~~~~~~~~~~~~~~~~~~~~~~~~
When **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 **lit** checks for a *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.
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 preceding reported test, <log
delineator> is a string of '\*' characters *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::
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)
LIT EXAMPLE TESTS
~~~~~~~~~~~~~~~~~
The **lit** distribution contains several example implementations of test suites
in the *ExampleTests* directory.
SEE ALSO
--------
valgrind(1)

201
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

251
docs/CommandGuide/llc.rst Normal file
View File

@ -0,0 +1,251 @@
llc - LLVM static compiler
==========================
SYNOPSIS
--------
**llc** [*options*] [*filename*]
DESCRIPTION
-----------
The **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 **-march** option is used to override
the default.
OPTIONS
-------
If *filename* is - or omitted, **llc** reads from standard input. Otherwise, it
will from *filename*. Inputs can be in either the LLVM assembly language
format (.ll) or the LLVM bitcode format (.bc).
If the **-o** option is omitted, then **llc** will send its output to standard
output if the input is from standard input. If the **-o** option specifies -,
then the output will also be sent to standard output.
If no **-o** option is specified and an input file other than - is specified,
then **llc** creates the output filename by taking the input filename,
removing any existing *.bc* extension, and adding a *.s* suffix.
Other **llc** options are as follows:
End-user Options
~~~~~~~~~~~~~~~~
**-help**
Print a summary of command line options.
**-O**\ =\ *uint*
Generate code at different optimization levels. These correspond to the *-O0*,
*-O1*, *-O2*, and *-O3* optimization levels used by **llvm-gcc** and
**clang**.
**-mtriple**\ =\ *target triple*
Override the target triple specified in the input file with the specified
string.
**-march**\ =\ *arch*
Specify the architecture for which to generate assembly, overriding the target
encoded in the input file. See the output of **llc -help** for a list of
valid architectures. By default this is inferred from the target triple or
autodetected to the current architecture.
**-mcpu**\ =\ *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:
**llvm-as < /dev/null | llc -march=xyz -mcpu=help**
**-mattr**\ =\ *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:
**llvm-as < /dev/null | llc -march=xyz -mattr=help**
**--disable-fp-elim**
Disable frame pointer elimination optimization.
**--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).
**--enable-no-infs-fp-math**
Enable optimizations that assume no Inf values.
**--enable-no-nans-fp-math**
Enable optimizations that assume no NAN values.
**--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).
**--enable-correct-eh-support**
Instruct the **lowerinvoke** pass to insert code for correct exception handling
support. This is expensive and is by default omitted for efficiency.
**--stats**
Print statistics recorded by code-generation passes.
**--time-passes**
Record the amount of time needed for each pass and print a report to standard
error.
**--load**\ =\ *dso_path*
Dynamically load *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
**-march** option so that code can be generated for that target.
Tuning/Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**--print-machineinstrs**
Print generated machine code between compilation phases (useful for debugging).
**--regalloc**\ =\ *allocator*
Specify the register allocator to use. The default *allocator* is *local*.
Valid register allocators are:
*simple*
Very simple "always spill" register allocator
*local*
Local register allocator
*linearscan*
Linear scan global register allocator
*iterativescan*
Iterative scan global register allocator
**--spiller**\ =\ *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
*spiller* is *local*. Valid spillers are:
*simple*
Simple spiller
*local*
Local spiller
Intel IA-32-specific Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**--x86-asm-syntax=att|intel**
Specify whether to emit assembly code in AT&T syntax (the default) or intel
syntax.
EXIT STATUS
-----------
If **llc** succeeds, it will exit with 0. Otherwise, if an error occurs,
it will exit with a non-zero value.
SEE ALSO
--------
lli|lli

219
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

300
docs/CommandGuide/lli.rst Normal file
View File

@ -0,0 +1,300 @@
lli - directly execute programs from LLVM bitcode
=================================================
SYNOPSIS
--------
**lli** [*options*] [*filename*] [*program args*]
DESCRIPTION
-----------
**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. **lli** takes all of
the same code generator options as llc|llc, but they are only effective when
**lli** is using the just-in-time compiler.
If *filename* is not specified, then **lli** reads the LLVM bitcode for the
program from standard input.
The optional *args* specified on the command line are passed to the program as
arguments.
GENERAL OPTIONS
---------------
**-fake-argv0**\ =\ *executable*
Override the ``argv[0]`` value passed into the executing program.
**-force-interpreter**\ =\ *{false,true}*
If set to true, use the interpreter even if a just-in-time compiler is available
for this architecture. Defaults to false.
**-help**
Print a summary of command line options.
**-load**\ =\ *puginfilename*
Causes **lli** to load the plugin (shared object) named *pluginfilename* and use
it for optimization.
**-stats**
Print statistics from the code-generation passes. This is only meaningful for
the just-in-time compiler, at present.
**-time-passes**
Record the amount of time needed for each code-generation pass and print it to
standard error.
**-version**
Print out the version of **lli** and exit without doing anything else.
TARGET OPTIONS
--------------
**-mtriple**\ =\ *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.
**-march**\ =\ *arch*
Specify the architecture for which to generate assembly, overriding the target
encoded in the bitcode file. See the output of **llc -help** for a list of
valid architectures. By default this is inferred from the target triple or
autodetected to the current architecture.
**-mcpu**\ =\ *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:
**llvm-as < /dev/null | llc -march=xyz -mcpu=help**
**-mattr**\ =\ *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:
**llvm-as < /dev/null | llc -march=xyz -mattr=help**
FLOATING POINT OPTIONS
----------------------
**-disable-excess-fp-precision**
Disable optimizations that may increase floating point precision.
**-enable-no-infs-fp-math**
Enable optimizations that assume no Inf values.
**-enable-no-nans-fp-math**
Enable optimizations that assume no NAN values.
**-enable-unsafe-fp-math**
Causes **lli** to enable optimizations that may decrease floating point
precision.
**-soft-float**
Causes **lli** to generate software floating point library calls instead of
equivalent hardware instructions.
CODE GENERATION OPTIONS
-----------------------
**-code-model**\ =\ *model*
Choose the code model from:
.. code-block:: perl
default: Target default code model
small: Small code model
kernel: Kernel code model
medium: Medium code model
large: Large code model
**-disable-post-RA-scheduler**
Disable scheduling after register allocation.
**-disable-spill-fusing**
Disable fusing of spill code into instructions.
**-enable-correct-eh-support**
Make the -lowerinvoke pass insert expensive, but correct, EH code.
**-jit-enable-eh**
Exception handling should be enabled in the just-in-time compiler.
**-join-liveintervals**
Coalesce copies (default=true).
**-nozero-initialized-in-bss** Don't place zero-initialized symbols into the BSS section.
**-pre-RA-sched**\ =\ *scheduler*
Instruction schedulers available (before register allocation):
.. code-block:: perl
=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
**-regalloc**\ =\ *allocator*
Register allocator to use (default=linearscan)
.. code-block:: perl
=bigblock: Big-block register allocator
=linearscan: linear scan register allocator =local - local register allocator
=simple: simple register allocator
**-relocation-model**\ =\ *model*
Choose relocation model from:
.. code-block:: perl
=default: Target default relocation model
=static: Non-relocatable code =pic - Fully relocatable, position independent code
=dynamic-no-pic: Relocatable external references, non-relocatable code
**-spiller**
Spiller to use (default=local)
.. code-block:: perl
=simple: simple spiller
=local: local spiller
**-x86-asm-syntax**\ =\ *syntax*
Choose style of code to emit from X86 backend:
.. code-block:: perl
=att: Emit AT&T-style assembly
=intel: Emit Intel-style assembly
EXIT STATUS
-----------
If **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.
SEE ALSO
--------
llc|llc

406
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

458
docs/CommandGuide/llvm-ar.rst Normal file
View File

@ -0,0 +1,458 @@
llvm-ar - LLVM archiver
=======================
SYNOPSIS
--------
**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
DESCRIPTION
-----------
The **llvm-ar** command is similar to the common Unix utility, ``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,
**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 **llvm-ar** command can be used to *read* both SVR4 and BSD style archive
files. However, it cannot be used to write them. While the **llvm-ar** command
produces files that are *almost* identical to the format used by other ``ar``
implementations, it has two significant departures in order to make the
archive appropriate for LLVM. The first departure is that **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 **llvm-ar** usually won't be readable or editable with any
``ar`` implementation or useful for linking. Using the ``f`` modifier to flatten
file names will make the archive readable by other ``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 ``r`` (replace) or ``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 **llvm-ar** departs from previous ``ar`` implementations:
*Symbol Table*
Since **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.
*Long Paths*
Some ``ar`` implementations (SVR4) use a separate file member to record long
path names (> 15 characters). **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.
*Directory Recursion*
Most ``ar`` implementations do not recurse through directories but simply
ignore directories if they are presented to the program in the *files*
option. **llvm-ar**, however, can recurse through directory structures and
add all the files under a directory, if requested.
*TOC Verbose Output*
When **llvm-ar** prints out the verbose table of contents (``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 'B' means
the file is an LLVM bitcode file. An 'S' means the file is the symbol table.
OPTIONS
-------
The options to **llvm-ar** are compatible with other ``ar`` implementations.
However, there are a few modifiers (*R*) that are not found in other ``ar``
implementations. The options to **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 **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 ``.a`` suffix, but this is not required. Following
the *archive-name* comes a list of *files* that indicate the specific members
of the archive to operate on. If the *files* option is not specified, it
generally means either "none" or "all" members, depending on the operation.
Operations
~~~~~~~~~~
d
Delete files from the archive. No modifiers are applicable to this operation.
The *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 *files* are specified, the archive is not modified.
m[abi]
Move files from one location in the archive to another. The *a*, *b*, and
*i* modifiers apply to this operation. The *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 *files* are specified, the
archive is not modified.
p[k]
Print files to the standard output. The *k* modifier applies to this
operation. This operation simply prints the *files* indicated to the
standard output. If no *files* are specified, the entire archive is printed.
Printing bitcode files is ill-advised as they might confuse your terminal
settings. The *p* operation never modifies the archive.
q[Rf]
Quickly append files to the end of the archive. The *R*, and *f*
modifiers apply to this operation. This operation quickly adds the
*files* to the archive without checking for duplicates that should be
removed first. If no *files* are specified, the archive is not modified.
Because of the way that **llvm-ar** constructs the archive file, its dubious
whether the *q* operation is any faster than the *r* operation.
r[Rabfu]
Replace or insert file members. The *R*, *a*, *b*, *f*, and *u*
modifiers apply to this operation. This operation will replace existing
*files* or insert them at the end of the archive if they do not exist. If no
*files* are specified, the archive is not modified.
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 *v* modifier,
**llvm-ar** also prints out the file type (B=bitcode, S=symbol
table, blank=regular file), the permission mode, the owner and group, the
size, and the date. If any *files* are specified, the listing is only for
those files. If no *files* are specified, the table of contents for the
whole archive is printed.
x[oP]
Extract archive members back to files. The *o* modifier applies to this
operation. This operation retrieves the indicated *files* from the archive
and writes them back to the operating system's file system. If no
*files* are specified, the entire archive is extract.
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.
[a]
When inserting or moving member files, this option specifies the destination of
the new files as being after the *relpos* member. If *relpos* is not found,
the files are placed at the end of the archive.
[b]
When inserting or moving member files, this option specifies the destination of
the new files as being before the *relpos* member. If *relpos* is not
found, the files are placed at the end of the archive. This modifier is
identical to the *i* modifier.
[f]
Normally, **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 ``ar`` but may also
thwart correct extraction of the files (duplicates may overwrite). If used with
the *R* option, the directory recursion will be performed but the file names
will all be flattened to simple file names.
[i]
A synonym for the *b* option.
[k]
Normally, **llvm-ar** will not print the contents of bitcode files when the
*p* operation is used. This modifier defeats the default and allows the
bitcode members to be printed.
[N]
This option is ignored by **llvm-ar** but provided for compatibility.
[o]
When extracting files, this option will cause **llvm-ar** to preserve the
original modification times of the files it writes.
[P]
use full path names when matching
[R]
This modifier instructions the *r* option to recursively process directories.
Without *R*, directories are ignored and only those *files* that refer to
files will be added to the archive. When *R* is used, any directories specified
with *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.
[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.
Modifiers (generic)
~~~~~~~~~~~~~~~~~~~
The modifiers below may be applied to any operation.
[c]
For all operations, **llvm-ar** will always create the archive if it doesn't
exist. Normally, **llvm-ar** will print a warning message indicating that the
archive is being created. Using this modifier turns off that warning.
[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
llvm-ranlib|llvm-ranlib which also creates the symbol table.
[S]
This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to
not build the symbol table. If both *s* and *S* are used, the last modifier to
occur in the options will prevail.
[v]
This modifier instructs **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.
STANDARDS
---------
The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2
(POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or
Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations
then **llvm-ar** will write SVR4 compatible archives. Without this modifier,
**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.
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 ``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.
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 ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/``
is literal. In this case, the actual name of the file is provided in the ``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.
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.
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.
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.
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.
size - char[10]
This field provides the size of the file, in bytes, encoded as a decimal ASCII
string.
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.
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:
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.
length - vbr encoded 32-bit integer
The length item provides the length of the symbol that follows. Like this
*offset* item, the length is variable bit rate encoded.
symbol - character array
The symbol item provides the text of the symbol that is associated with the
*offset*. The symbol is not terminated by any character. Its length is provided
by the *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.
EXIT STATUS
-----------
If **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.
SEE ALSO
--------
llvm-ranlib|llvm-ranlib, ar(1)

77
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

56
docs/CommandGuide/llvm-as.rst Normal file
View File

@ -0,0 +1,56 @@
llvm-as - LLVM assembler
========================
SYNOPSIS
--------
**llvm-as** [*options*] [*filename*]
DESCRIPTION
-----------
**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 *filename* is omitted or is ``-``, then **llvm-as** reads its input from
standard input.
If an output file is not specified with the **-o** option, then
**llvm-as** sends its output to a file or standard output by following
these rules:
* If the input is standard input, then the output is standard output.
* If the input is a file that ends with ``.ll``, then the output file is of the
same name, except that the suffix is changed to ``.bc``.
* If the input is a file that does not end with the ``.ll`` suffix, then the
output file has the same name as the input file, except that the ``.bc``
suffix is appended.
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, **llvm-as** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**llvm-as** will write raw bitcode regardless of the output device.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output file name. If *filename* is ``-``, then **llvm-as**
sends its output to standard output.
EXIT STATUS
-----------
If **llvm-as** succeeds, it will exit with 0. Otherwise, if an error occurs, it
will exit with a non-zero value.
SEE ALSO
--------
llvm-dis|llvm-dis, gccas|gccas

315
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

424
docs/CommandGuide/llvm-bcanalyzer.rst Normal file
View File

@ -0,0 +1,424 @@
llvm-bcanalyzer - LLVM bitcode analyzer
=======================================
SYNOPSIS
--------
**llvm-bcanalyzer** [*options*] [*filename*]
DESCRIPTION
-----------
The **llvm-bcanalyzer** command is a small utility for analyzing bitcode files.
The tool reads a bitcode file (such as generated with the **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 *filename* is omitted or is ``-``, then **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.
OPTIONS
-------
**-nodetails**
Causes **llvm-bcanalyzer** to abbreviate its output by writing out only a module
level summary. The details for individual functions are not displayed.
**-dump**
Causes **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.
**-verify**
Causes **llvm-bcanalyzer** to verify the module produced by reading the
bitcode. This ensures that the statistics generated are based on a consistent
module.
**-help**
Print a summary of command line options.
EXIT STATUS
-----------
If **llvm-bcanalyzer** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value, usually 1.
SUMMARY OUTPUT DEFINITIONS
--------------------------
The following items are always printed by llvm-bcanalyzer. They comprize the
summary output.
**Bitcode Analysis Of Module**
This just provides the name of the module for which bitcode analysis is being
generated.
**Bitcode Version Number**
The bitcode version (not LLVM version) of the file read by the analyzer.
**File Size**
The size, in bytes, of the entire bitcode file.
**Module Bytes**
The size, in bytes, of the module block. Percentage is relative to File Size.
**Function Bytes**
The size, in bytes, of all the function blocks. Percentage is relative to File
Size.
**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.
**Constant Pool Bytes**
The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
Size.
**Module Globals Bytes**
Ths size, in bytes, of the Global Variable Definitions and their initializers.
Percentage is relative to File Size.
**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.
**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.
**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.
**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.
**Number Of Bitcode Blocks**
The total number of blocks of any kind in the bitcode file.
**Number Of Functions**
The total number of function definitions in the bitcode file.
**Number Of Types**
The total number of types defined in the Global Types Pool.
**Number Of Constants**
The total number of constants (of any type) defined in the Constant Pool.
**Number Of Basic Blocks**
The total number of basic blocks defined in all functions in the bitcode file.
**Number Of Instructions**
The total number of instructions defined in all functions in the bitcode file.
**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.
**Number Of Operands**
The total number of operands used in all instructions in the bitcode file.
**Number Of Compaction Tables**
The total number of compaction tables in all functions in the bitcode file.
**Number Of Symbol Tables**
The total number of symbol tables in all functions in the bitcode file.
**Number Of Dependent Libs**
The total number of dependent libraries found in the bitcode file.
**Total Instruction Size**
The total size of the instructions in all functions in the bitcode file.
**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.
**Maximum Type Slot Number**
The maximum value used for a type's slot number. Larger slot number values take
more bytes to encode.
**Maximum Value Slot Number**
The maximum value used for a value's slot number. Larger slot number values take
more bytes to encode.
**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.
**Bytes Per Global**
The average size of a global definition (constants and global variables).
**Bytes Per Function**
The average number of bytes per function definition. This is computed by
dividing Function Bytes by Number Of Functions.
**# of VBR 32-bit Integers**
The total number of 32-bit integers encoded using the Variable Bit Rate
encoding scheme.
**# of VBR 64-bit Integers**
The total number of 64-bit integers encoded using the Variable Bit Rate encoding
scheme.
**# 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.
**# 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.
**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.
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.
**Type**
The type signature of the function.
**Byte Size**
The total number of bytes in the function's block.
**Basic Blocks**
The number of basic blocks defined by the function.
**Instructions**
The number of instructions defined by the function.
**Long Instructions**
The number of instructions using the long instruction format in the function.
**Operands**
The number of operands used by all instructions in the function.
**Instruction Size**
The number of bytes consumed by instructions in the function.
**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.
**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.
**Number of VBR 32-bit Integers**
The total number of 32-bit integers found in this function (for any use).
**Number of VBR 64-bit Integers**
The total number of 64-bit integers found in this function (for any use).
**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.
**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.
**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.
SEE ALSO
--------
llvm-dis|llvm-dis, `http://llvm.org/docs/BitCodeFormat.html <http://llvm.org/docs/BitCodeFormat.html>`_

86
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

102
docs/CommandGuide/llvm-build.rst Normal file
View File

@ -0,0 +1,102 @@
llvm-build - LLVM Project Build Utility
=======================================
SYNOPSIS
--------
**llvm-build** [*options*]
DESCRIPTION
-----------
**llvm-build** is a tool for working with LLVM projects that use the LLVMBuild
system for describing their components.
At heart, **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.
OPTIONS
-------
**-h**, **--help**
Print the builtin program help.
**--source-root**\ =\ *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 **llvm-build** script itself.
**--print-tree**
Print the component tree for the project.
**--write-library-table**
Write out the C++ fragment which defines the components, library names, and
required libraries. This C++ fragment is built into llvm-config|llvm-config
in order to provide clients with the list of required libraries for arbitrary
component combinations.
**--write-llvmbuild**
Write out new *LLVMBuild.txt* files based on the loaded components. This is
useful for auto-upgrading the schema of the files. **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 precede
the section names in the *LLVMBuild* files.
**--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.
**--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.
**--llvmbuild-source-root**\ =\ *PATH*
If given, expect the *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 **--write-llvmbuild** to test changes to
*LLVMBuild* schema.
EXIT STATUS
-----------
**llvm-build** exits with 0 if operation was successful. Otherwise, it will exist
with a non-zero value.

131
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

176
docs/CommandGuide/llvm-config.rst Normal file
View File

@ -0,0 +1,176 @@
llvm-config - Print LLVM compilation options
============================================
SYNOPSIS
--------
**llvm-config** *option* [*components*...]
DESCRIPTION
-----------
**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.
EXAMPLES
--------
To link against the JIT:
.. code-block:: sh
g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
`llvm-config --libs engine bcreader scalaropts`
OPTIONS
-------
**--version**
Print the version number of LLVM.
**-help**
Print a summary of **llvm-config** arguments.
**--prefix**
Print the installation prefix for LLVM.
**--src-root**
Print the source root from which LLVM was built.
**--obj-root**
Print the object root used to build LLVM.
**--bindir**
Print the installation directory for LLVM binaries.
**--includedir**
Print the installation directory for LLVM headers.
**--libdir**
Print the installation directory for LLVM libraries.
**--cxxflags**
Print the C++ compiler flags needed to use LLVM headers.
**--ldflags**
Print the flags needed to link against LLVM libraries.
**--libs**
Print all the libraries needed to link against the specified LLVM
*components*, including any dependencies.
**--libnames**
Similar to **--libs**, but prints the bare filenames of the libraries
without **-l** or pathnames. Useful for linking against a not-yet-installed
copy of LLVM.
**--libfiles**
Similar to **--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.
**--components**
Print all valid component names.
**--targets-built**
Print the component names for all targets supported by this copy of LLVM.
**--build-mode**
Print the build mode used when LLVM was built (e.g. Debug or Release)
COMPONENTS
----------
To print a list of all available components, run **llvm-config
--components**. In most cases, components correspond directly to LLVM
libraries. Useful "virtual" components include:
**all**
Includes all LLVM libaries. The default if no components are specified.
**backend**
Includes either a native backend or the C backend.
**engine**
Includes either a native JIT or the bitcode interpreter.
EXIT STATUS
-----------
If **llvm-config** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.

45
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

51
docs/CommandGuide/llvm-cov.rst Normal file
View File

@ -0,0 +1,51 @@
llvm-cov - emit coverage information
====================================
SYNOPSIS
--------
**llvm-cov** [-gcno=filename] [-gcda=filename] [dump]
DESCRIPTION
-----------
The experimental **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.
OPTIONS
-------
**-gcno=filename]**
This option selects input description file generated by compiler while instrumenting
program.
**-gcda=filename]**
This option selects coverage data file generated by instrumented compiler.
**-dump**
This options enables output dump that is suitable for a developer to help debug
**llvm-cov** itself.
EXIT STATUS
-----------
**llvm-cov** returns 1 if it cannot read input files. Otherwise, it exits with zero.

41
docs/CommandGuide/llvm-diff.pod → docs/CommandGuide/llvm-diff.rst
View File

@ -1,16 +1,19 @@
=pod
=head1 NAME
llvm-diff - LLVM structural 'diff'
==================================
=head1 SYNOPSIS
B<llvm-diff> [I<options>] I<module 1> I<module 2> [I<global name ...>]
SYNOPSIS
--------
=head1 DESCRIPTION
B<llvm-diff> compares the structure of two LLVM modules, primarily
**llvm-diff** [*options*] *module 1* *module 2* [*global name ...*]
DESCRIPTION
-----------
**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.
@ -23,31 +26,31 @@ 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,
**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
**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
EXIT STATUS
-----------
If **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
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
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

69
docs/CommandGuide/llvm-dis.rst Normal file
View File

@ -0,0 +1,69 @@
llvm-dis - LLVM disassembler
============================
SYNOPSIS
--------
**llvm-dis** [*options*] [*filename*]
DESCRIPTION
-----------
The **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 ``-``, **llvm-dis** reads its
input from standard input.
If the input is being read from standard input, then **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 ``.ll`` suffix added (any existing ``.bc`` suffix will first be
removed). You can override the choice of output file using the
**-o** option.
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, **llvm-dis** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**llvm-dis** will write raw bitcode regardless of the output device.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output file name. If *filename* is -, then the output is sent
to standard output.
EXIT STATUS
-----------
If **llvm-dis** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
SEE ALSO
--------
llvm-as|llvm-as

85
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

104
docs/CommandGuide/llvm-extract.rst Normal file
View File

@ -0,0 +1,104 @@
llvm-extract - extract a function from an LLVM module
=====================================================
SYNOPSIS
--------
**llvm-extract** [*options*] **--func** *function-name* [*filename*]
DESCRIPTION
-----------
The **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,
**llvm-extract** will also remove unreachable global variables, prototypes, and
unused types.
The **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 **-o** option is specified (see below).
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, **llvm-extract** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**llvm-extract** will write raw bitcode regardless of the output device.
**--func** *function-name*
Extract the function named *function-name* from the LLVM bitcode. May be
specified multiple times to extract multiple functions at once.
**--rfunc** *function-regular-expr*
Extract the function(s) matching *function-regular-expr* from the LLVM bitcode.
All functions matching the regular expression will be extracted. May be
specified multiple times.
**--glob** *global-name*
Extract the global variable named *global-name* from the LLVM bitcode. May be
specified multiple times to extract multiple global variables at once.
**--rglob** *glob-regular-expr*
Extract the global variable(s) matching *global-regular-expr* from the LLVM
bitcode. All global variables matching the regular expression will be extracted.
May be specified multiple times.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output filename. If filename is "-" (the default), then
**llvm-extract** sends its output to standard output.
**-S**
Write output in LLVM intermediate language (instead of bitcode).
EXIT STATUS
-----------
If **llvm-extract** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
SEE ALSO
--------
bugpoint|bugpoint

234
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
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

96
docs/CommandGuide/llvm-link.rst Normal file
View File

@ -0,0 +1,96 @@
llvm-link - LLVM linker
=======================
SYNOPSIS
--------
**llvm-link** [*options*] *filename ...*
DESCRIPTION
-----------
**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 **-o** option is used to specify a filename.
**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
**-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.
OPTIONS
-------
**-L** *directory*
Add the specified *directory* to the library search path. When looking for
libraries, **llvm-link** will look in path name for libraries. This option can be
specified multiple times; **llvm-link** will search inside these directories in
the order in which they were specified on the command line.
**-f**
Enable binary output on terminals. Normally, **llvm-link** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**llvm-link** will write raw bitcode regardless of the output device.
**-o** *filename*
Specify the output file name. If *filename* is ``-``, then **llvm-link** will
write its output to standard output.
**-S**
Write output in LLVM intermediate language (instead of bitcode).
**-d**
If specified, **llvm-link** prints a human-readable version of the output
bitcode file to standard error.
**-help**
Print a summary of command line options.
**-v**
Verbose mode. Print information about what **llvm-link** is doing. This
typically includes a message for each bitcode file linked in and for each
library found.
EXIT STATUS
-----------
If **llvm-link** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.
SEE ALSO
--------
gccld|gccld

122
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

189
docs/CommandGuide/llvm-nm.rst Normal file
View File

@ -0,0 +1,189 @@
llvm-nm - list LLVM bitcode and object file's symbol table
==========================================================
SYNOPSIS
--------
:program:`llvm-nm` [*options*] [*filenames...*]
DESCRIPTION
-----------
The :program:`llvm-nm` utility lists the names of symbols from the LLVM bitcode
files, object files, or :program:`ar` archives containing them, named on the
command line. Each symbol is listed along with some simple information about its
provenance. If no file name is specified, or *-* is used as a file name,
:program:`llvm-nm` will process a file on its standard input stream.
:program:`llvm-nm`'s default output format is the traditional BSD :program:`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:
U
Named object is referenced but undefined in this bitcode file
C
Common (multiple definitions link together into one def)
W
Weak reference (multiple definitions link together into zero or one definitions)
t
Local function (text) object
T
Global function (text) object
d
Local data object
D
Global data object
?
Something unrecognizable
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", :program:`llvm-nm` does not print an address for any
symbol in a LLVM bitcode file, even symbols which are defined in the bitcode
file.
OPTIONS
-------
.. program:: llvm-nm
.. option:: -B (default)
Use BSD output format. Alias for :option:`--format=bsd`.
.. option:: -P
Use POSIX.2 output format. Alias for :option:`--format=posix`.
.. option:: --debug-syms, -a
Show all symbols, even debugger only.
.. option:: --defined-only
Print only symbols defined in this file (as opposed to
symbols which may be referenced by objects in this file, but not
defined in this file.)
.. option:: --dynamic, -D
Display dynamic symbols instead of normal symbols.
.. option:: --extern-only, -g
Print only symbols whose definitions are external; that is, accessible
from other files.
.. option:: --format=format, -f format
Select an output format; *format* may be *sysv*, *posix*, or *bsd*. The default
is *bsd*.
.. option:: -help
Print a summary of command-line options and their meanings.
.. option:: --no-sort, -p
Shows symbols in order encountered.
.. option:: --numeric-sort, -n, -v
Sort symbols by address.
.. option:: --print-file-name, -A, -o
Precede each symbol with the file it came from.
.. option:: --print-size, -S
Show symbol size instead of address.
.. option:: --size-sort
Sort symbols by size.
.. option:: --undefined-only, -u
Print only symbols referenced but not defined in this file.
BUGS
----
* :program:`llvm-nm` cannot demangle C++ mangled names, like GNU :program:`nm`
can.
* :program:`llvm-nm` does not support the full set of arguments that GNU
:program:`nm` does.
EXIT STATUS
-----------
:program:`llvm-nm` exits with an exit code of zero.
SEE ALSO
--------
llvm-dis|llvm-dis, ar(1), nm(1)

57
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

63
docs/CommandGuide/llvm-prof.rst Normal file
View File

@ -0,0 +1,63 @@
llvm-prof - print execution profile of LLVM program
===================================================
SYNOPSIS
--------
**llvm-prof** [*options*] [*bitcode file*] [*llvmprof.out*]
DESCRIPTION
-----------
The **llvm-prof** tool reads in an *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 *utils/profile.pl*
script. This script automatically instruments a program, runs it with the JIT,
then runs **llvm-prof** to format a report. To get more information about
*utils/profile.pl*, execute it with the **-help** option.
OPTIONS
-------
**--annotated-llvm** or **-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.
**--print-all-code**
Using this option enables the **--annotated-llvm** option, but it
prints the entire module, instead of just the most commonly executed
functions.
**--time-passes**
Record the amount of time needed for each pass and print it to standard
error.
EXIT STATUS
-----------
**llvm-prof** returns 1 if it cannot load the bitcode file or the profile
information. Otherwise, it exits with zero.

52
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

61
docs/CommandGuide/llvm-ranlib.rst Normal file
View File

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

42
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

48
docs/CommandGuide/llvm-stress.rst Normal file
View File

@ -0,0 +1,48 @@
llvm-stress - generate random .ll files
=======================================
SYNOPSIS
--------
**llvm-stress** [-size=filesize] [-seed=initialseed] [-o=outfile]
DESCRIPTION
-----------
The **llvm-stress** tool is used to generate random .ll files that can be used to
test different components of LLVM.
OPTIONS
-------
**-o** *filename*
Specify the output filename.
**-size** *size*
Specify the size of the generated .ll file.
**-seed** *seed*
Specify the seed to be used for the randomly generated instructions.
EXIT STATUS
-----------
**llvm-stress** returns 0.

256
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
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

183
docs/CommandGuide/opt.rst Normal file
View File

@ -0,0 +1,183 @@
opt - LLVM optimizer
====================
SYNOPSIS
--------
**opt** [*options*] [*filename*]
DESCRIPTION
-----------
The **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
**opt** depends on whether the **-analyze** option is given.
When **-analyze** is specified, **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 **-analyze** is *not* given, **opt** attempts to produce an optimized
output file. The optimizations available via **opt** depend upon what
libraries were linked into it as well as any additional libraries that have
been loaded with the **-load** option. Use the **-help** option to determine
what optimizations you can use.
If *filename* is omitted from the command line or is *-*, **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 **-o** option, **opt**
writes its output to the standard output.
OPTIONS
-------
**-f**
Enable binary output on terminals. Normally, **opt** will refuse to
write raw bitcode output if the output stream is a terminal. With this option,
**opt** will write raw bitcode regardless of the output device.
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output filename.
**-S**
Write output in LLVM intermediate language (instead of bitcode).
**-{passname}**
**opt** provides the ability to run any of LLVM's optimization or analysis passes
in any order. The **-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).
**-std-compile-opts**
This is short hand for a standard list of *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:
.. code-block:: sh
llvm-as < /dev/null | opt -std-compile-opts -disable-output -debug-pass=Arguments
**-disable-inlining**
This option is only meaningful when **-std-compile-opts** is given. It simply
removes the inlining pass from the standard list.
**-disable-opt**
This option is only meaningful when **-std-compile-opts** is given. It disables
most, but not all, of the **-std-compile-opts**. The ones that remain are
**-verify**, **-lower-setjmp**, and **-funcresolve**.
**-strip-debug**
This option causes opt to strip debug information from the module before
applying other optimizations. It is essentially the same as **-strip** but it
ensures that stripping of debug information is done first.
**-verify-each**
This option causes opt to add a verify pass after every pass otherwise specified
on the command line (including **-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 **-std-compile-opts** and **-verify-each**
can quickly track down this kind of problem.
**-profile-info-file** *filename*
Specify the name of the file loaded by the -profile-loader option.
**-stats**
Print statistics.
**-time-passes**
Record the amount of time needed for each pass and print it to standard
error.
**-debug**
If this is a debug build, this option will enable debug printouts
from passes which use the *DEBUG()* macro. See the **LLVM Programmer's
Manual**, section *#DEBUG* for more information.
**-load**\ =\ *plugin*
Load the dynamic object *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 **-help** and **-load** options together. For example:
.. code-block:: sh
opt -load=plugin.so -help
**-p**
Print module after each transformation.
EXIT STATUS
-----------
If **opt** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.

139
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

186
docs/CommandGuide/tblgen.rst Normal file
View File

@ -0,0 +1,186 @@
tblgen - Target Description To C++ Code Generator
=================================================
SYNOPSIS
--------
**tblgen** [*options*] [*filename*]
DESCRIPTION
-----------
**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 **tblgen** is beyond the scope of this short
introduction. Please see the *CodeGeneration* page in the LLVM documentation.
The *filename* argument specifies the name of a Target Description (.td) file
to read as input.
OPTIONS
-------
**-help**
Print a summary of command line options.
**-o** *filename*
Specify the output file name. If *filename* is ``-``, then **tblgen**
sends its output to standard output.
**-I** *directory*
Specify where to find other target description files for inclusion. The
*directory* value should be a full or partial path to a directory that contains
target description files.
**-asmparsernum** *N*
Make -gen-asm-parser emit assembly writer number *N*.
**-asmwriternum** *N*
Make -gen-asm-writer emit assembly writer number *N*.
**-class** *class Name*
Print the enumeration list for this class.
**-print-records**
Print all records to standard output (default).
**-print-enums**
Print enumeration values for a class
**-print-sets**
Print expanded sets for testing DAG exprs.
**-gen-emitter**
Generate machine code emitter.
**-gen-register-info**
Generate registers and register classes info.
**-gen-instr-info**
Generate instruction descriptions.
**-gen-asm-writer**
Generate the assembly writer.
**-gen-disassembler**
Generate disassembler.
**-gen-pseudo-lowering**
Generate pseudo instruction lowering.
**-gen-dag-isel**
Generate a DAG (Directed Acycle Graph) instruction selector.
**-gen-asm-matcher**
Generate assembly instruction matcher.
**-gen-dfa-packetizer**
Generate DFA Packetizer for VLIW targets.
**-gen-fast-isel**
Generate a "fast" instruction selector.
**-gen-subtarget**
Generate subtarget enumerations.
**-gen-intrinsic**
Generate intrinsic information.
**-gen-tgt-intrinsic**
Generate target intrinsic information.
**-gen-enhanced-disassembly-info**
Generate enhanced disassembly info.
**-version**
Show the version number of this program.
EXIT STATUS
-----------
If **tblgen** succeeds, it will exit with 0. Otherwise, if an error
occurs, it will exit with a non-zero value.

1976
docs/CommandLine.html
View File

File diff suppressed because it is too large Load Diff

1615
docs/CommandLine.rst Normal file
View File

File diff suppressed because it is too large Load Diff

4
docs/CompilerWriterInfo.html
View File

@ -4,7 +4,7 @@
<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">
<link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
@ -260,7 +260,7 @@ processors.</li>
<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-28 00:56:32 +0200 (Fri, 28 Oct 2011) $
Last modified: $Date: 2012-04-19 22:20:34 +0200 (Thu, 19 Apr 2012) $
</address>
</body>

6
docs/DebuggingJITedCode.html
View File

@ -4,7 +4,7 @@
<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">
<link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
@ -51,7 +51,7 @@ necessary debug information.
<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
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>
@ -178,7 +178,7 @@ Program exited with code 0170.
<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 09:58:54 +0200 (Tue, 01 May 2012) $
Last modified: $Date: 2012-05-13 16:36:15 +0200 (Sun, 13 May 2012) $
</address>
</body>
</html>

642
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 13:25:16 +0200 (Tue, 27 Mar 2012) $
</address>
</body>
</html>

508
docs/DeveloperPolicy.rst Normal file
View File

@ -0,0 +1,508 @@
.. _developer_policy:
=====================
LLVM Developer Policy
=====================
.. contents::
:local:
Introduction
============
This document contains the LLVM Developer Policy which defines the project's
policy towards developers and their contributions. The intent of this policy is
to eliminate miscommunication, rework, and confusion that might arise from 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.
This policy is also designed to accomplish the following objectives:
#. Attract both users and developers to the LLVM project.
#. Make life as simple and easy for contributors as possible.
#. Keep the top of Subversion trees as stable as possible.
#. Establish awareness of the project's `copyright, license, and patent
policies`_ with contributors to the project.
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
`llvm-commits mailing list
<http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_ and engaging another
developer to see it through the process.
Developer Policies
==================
This section contains policies that pertain to frequent LLVM developers. We
always welcome `one-off patches`_ from people who do not routinely contribute to
LLVM, but we expect more from frequent contributors to keep the system as
efficient as possible for everyone. Frequent LLVM contributors are expected to
meet the following requirements in order for LLVM to maintain a high standard of
quality.
Stay Informed
-------------
Developers should stay informed by reading at least the "dev" mailing list for
the projects you are interested in, such as `llvmdev
<http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_ for LLVM, `cfe-dev
<http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev>`_ for Clang, or `lldb-dev
<http://lists.cs.uiuc.edu/mailman/listinfo/lldb-dev>`_ 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 `llvm-commits
<http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_, `cfe-commits
<http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits>`_, or `lldb-commits
<http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits>`_. 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.
We recommend that active developers register an email account with `LLVM
Bugzilla <http://llvm.org/bugs/>`_ and preferably subscribe to the `llvm-bugs
<http://lists.cs.uiuc.edu/mailman/listinfo/llvmbugs>`_ 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.
.. _patch:
.. _one-off patches:
Making a Patch
--------------
When making a patch for review, the goal is to make it as easy for the reviewer
to read it as possible. As such, we recommend that you:
#. 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 `Getting Started
Guide <GettingStarted.html#checkout>`_.
#. 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.
#. Patches should be made with ``svn diff``, or similar. If you use a
different tool, make sure it uses the ``diff -u`` format and that it
doesn't contain clutter which makes it hard to read.
#. If you are modifying generated files, such as the top-level ``configure``
script, please separate out those changes into a separate patch from the rest
of your changes.
When sending a patch to a mailing list, it is a good idea to send it as an
*attachment* 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).
*For Thunderbird users:* Before submitting a patch, please open *Preferences >
Advanced > General > Config Editor*, find the key
``mail.content_disposition_type``, and set its value to ``1``. Without this
setting, Thunderbird sends your attachment using ``Content-Disposition: inline``
rather than ``Content-Disposition: attachment``. Apple Mail gamely displays such
a file inline, making it difficult to work with for reviewers using that
program.
.. _code review:
Code Reviews
------------
LLVM has a code review policy. Code review is one way to increase the quality of
software. We generally follow these policies:
#. All developers are required to have significant changes reviewed before they
are committed to the repository.
#. Code reviews are conducted by email, usually on the llvm-commits list.
#. 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.
#. The developer responsible for a code change is also responsible for making
all necessary review-related changes.
#. Code review can be an iterative process, which continues until the patch is
ready to be committed.
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.
Code Owners
-----------
The LLVM Project relies on two features of its process to maintain rapid
development in addition to the high quality of its source base: the 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.
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 list
of current code owners can be found in the file
`CODE_OWNERS.TXT <http://llvm.org/viewvc/llvm-project/llvm/trunk/CODE_OWNERS.TXT?view=markup>`_
in the root of the LLVM source tree.
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.
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.
.. _include a testcase:
Test Cases
----------
Developers are required to create test cases for any bugs fixed and any new
features added. Some tips for getting your testcase approved:
* All feature and regression test cases are added to the ``llvm/test``
directory. The appropriate sub-directory should be selected (see the `Testing
Guide <TestingGuide.html>`_ for details).
* Test cases should be written in `LLVM assembly language <LangRef.html>`_
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++).
* Test cases, especially for regressions, should be reduced as much as possible,
by `bugpoint <Bugpoint.html>`_ or manually. It is unacceptable to place an
entire failing program into ``llvm/test`` as this creates a *time-to-test*
burden on all developers. Please keep them short.
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 ``llvm-test`` test suite. The llvm-test suite is
for coverage (correctness, performance, etc) testing, not feature or regression
testing.
Quality
-------
The minimum quality standards that any change must satisfy before being
committed to the main development branch are:
#. Code must adhere to the `LLVM Coding Standards <CodingStandards.html>`_.
#. Code must compile cleanly (no errors, no warnings) on at least one platform.
#. Bug fixes and new features should `include a testcase`_ so we know if the
fix/feature ever regresses in the future.
#. Code must pass the ``llvm/test`` test suite.
#. 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 "``llvm-test/MultiSource/Benchmarks``".
Additionally, the committer is responsible for addressing any problems found in
the future that the change is responsible for. For example:
* The code should compile cleanly on all supported platforms.
* The changes should not cause any correctness regressions in the ``llvm-test``
suite and must not cause any major performance regressions.
* The change set should not cause performance or correctness regressions for the
LLVM tools.
* The changes should not cause performance or correctness regressions in code
compiled by LLVM on all applicable targets.
* You are expected to address any `Bugzilla bugs <http://llvm.org/bugs/>`_ that
result from your change.
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.
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.
Obtaining Commit Access
-----------------------
We grant commit access to contributors with a track record of submitting high
quality patches. If you would like commit access, please send an email to
`Chris <mailto:sabre@nondot.org>`_ with the following information:
#. The user name you want to commit with, e.g. "hacker".
#. The full name and email address you want message to llvm-commits to come
from, e.g. "J. Random Hacker <hacker@yoyodyne.com>".
#. 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.
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.
If you have recently been granted commit access, these policies apply:
#. You are granted *commit-after-approval* to all parts of LLVM. To get
approval, submit a `patch`_ to `llvm-commits
<http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_. When approved
you may commit it yourself.</li>
#. You are allowed to commit patches without approval which you think are
obvious. This is clearly a subjective decision --- we simply expect you to
use good judgement. Examples include: fixing build breakage, reverting
obviously broken patches, documentation/comment changes, any other minor
changes.
#. 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.
#. Multiple violations of these policies or a single egregious violation may
cause commit access to be revoked.
In any case, your changes are still subject to `code review`_ (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.
.. _discuss the change/gather consensus:
Making a Major Change
---------------------
When a developer begins a major new project with the aim of contributing it back
to LLVM, s/he should inform the community with an email to the `llvmdev
<http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_ email list, to the extent
possible. The reason for this is to:
#. keep the community informed about future changes to LLVM,
#. avoid duplication of effort by preventing multiple parties working on the
same thing and not knowing about it, and
#. ensure that any technical issues around the proposed work are discussed and
resolved before any significant work is done.
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.
Once the design of the new feature is finalized, the work itself should be done
as a series of `incremental changes`_, not as a long-term development branch.
.. _incremental changes:
Incremental Development
-----------------------
In the LLVM project, we do all significant changes as a series of incremental
patches. We have a strong dislike for huge changes or long-term development
branches. Long-term development branches have a number of drawbacks:
#. 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.
#. Other people in the community tend to ignore work on branches.
#. Huge changes (produced when a branch is merged back onto mainline) are
extremely difficult to `code review`_.
#. Branches are not routinely tested by our nightly tester infrastructure.
#. 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.
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:
* 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.
* 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.
* 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.
* 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.
* 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.
If you are interested in making a large change, and this scares you, please make
sure to first `discuss the change/gather consensus`_ then ask about the best way
to go about making the change.
Attribution of Changes
----------------------
We believe in correct attribution of contributions to their contributors.
However, we do not want the source code to be littered with random attributions
"this code written by J. Random Hacker" (this is noisy and 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.
Overall, please do not add contributor names to the source code.
.. _copyright, license, and patent policies:
Copyright, License, and Patents
===============================
.. note::
This section deals with legal matters but does not provide legal advice. We
are not lawyers --- please seek legal counsel from an attorney.
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
`University of Illinois/NCSA Open Source License
<http://www.opensource.org/licenses/UoI-NCSA.php>`_ (with portions dual licensed
under the `MIT License <http://www.opensource.org/licenses/mit-license.php>`_,
see below). As contributor to the LLVM project, you agree to allow any
contributions to the project to licensed under these terms.
Copyright
---------
The LLVM project does not require copyright assignments, which means that the
copyright for the code in the project is held by its respective contributors who
have each agreed to release their contributed code under the terms of the `LLVM
License`_.
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.
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.
.. _LLVM License:
License
-------
We intend to keep LLVM perpetually open source and to use a liberal open source
license. **As a contributor to the project, you agree that any contributions be
licensed under the terms of the corresponding subproject.** All of the code in
LLVM is available under the `University of Illinois/NCSA Open Source License
<http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to
this:
* You can freely distribute LLVM.
* You must retain the copyright notice if you redistribute LLVM.
* Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
included readme file).
* You can't use our names to promote your LLVM derived products.
* There's no warranty on LLVM at all.
We believe this fosters the widest adoption of LLVM because it **allows
commercial products to be derived from LLVM** 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
`License <http://www.opensource.org/licenses/UoI-NCSA.php>`_ if further
clarification is needed.
In addition to the UIUC license, the runtime library components of LLVM
(**compiler_rt, libc++, and libclc**) are also licensed under the `MIT License
<http://www.opensource.org/licenses/mit-license.php>`_, 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.
Note that the LLVM Project does distribute llvm-gcc and dragonegg, **which are
GPL.** 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 **any code linked into llvm-gcc and distributed to others may be subject to
the viral aspects of the GPL** (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.
We have no plans to change the license of LLVM. If you have questions or
comments about the license, please contact the `LLVM Developer's Mailing
List <mailto:llvmdev@cs.uiuc.edu>`_.
Patents
-------
To the best of our knowledge, LLVM does not infringe on any patents (we have
actually removed code from LLVM in the past that was found to infringe). Having
code in LLVM that infringes on patents would violate an important goal of the
project by making it hard or impossible to reuse the code for arbitrary purposes
(including commercial use).
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 `oversight group <mailto:llvm-oversight@cs.uiuc.edu>`_ for more
details.

563
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 13:25:16 +0200 (Tue, 27 Mar 2012) $
</address>
</body>
</html>

367
docs/ExceptionHandling.rst Normal file
View File

@ -0,0 +1,367 @@
.. _exception_handling:
==========================
Exception Handling in LLVM
==========================
.. contents::
:local:
Introduction
============
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++.
Itanium ABI Zero-cost Exception Handling
----------------------------------------
Exception handling for most programming languages is designed to recover from
conditions that rarely occur during general use of an application. To that 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.
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.
A more complete description of the Itanium ABI exception handling runtime
support of can be found at `Itanium C++ ABI: Exception Handling
<http://www.codesourcery.com/cxx-abi/abi-eh.html>`_. A description of the
exception frame format can be found at `Exception Frames
<http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html>`_,
with details of the DWARF 4 specification at `DWARF 4 Standard
<http://dwarfstd.org/Dwarf4Std.php>`_. A description for the C++ exception
table formats can be found at `Exception Handling Tables
<http://www.codesourcery.com/cxx-abi/exceptions.pdf>`_.
Setjmp/Longjmp Exception Handling
---------------------------------
Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
`llvm.eh.sjlj.setjmp`_ and `llvm.eh.sjlj.longjmp`_ to handle control flow for
exception handling.
For each function which does exception processing --- be it ``try``/``catch``
blocks or cleanups --- that function registers itself on a global frame
list. When exceptions are unwinding, the runtime uses this list to identify
which functions need processing.
Landing pad selection is encoded in the call site entry of the function
context. The runtime returns to the function via `llvm.eh.sjlj.longjmp`_, where
a switch table transfers control to the appropriate landing pad based on the
index stored in the function context.
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.
Overview
--------
When an exception is thrown in LLVM code, the runtime does its best to find a
handler suited to processing the circumstance.
The runtime first attempts to find an *exception frame* 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.
Because different programming languages have different behaviors when handling
exceptions, the exception handling ABI provides a mechanism for
supplying *personalities*. An exception handling personality is defined by
way of a *personality function* (e.g. ``__gxx_personality_v0`` in C++),
which receives the context of the exception, an *exception structure*
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 *common exception frame*.
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++ *type info*) that are
handled in that range, and an associated action that should take place. Actions
typically pass control to a *landing pad*.
A landing pad corresponds roughly to the code found in the ``catch`` portion of
a ``try``/``catch`` sequence. When execution resumes at a landing pad, it
receives an *exception structure* and a *selector value* corresponding to the
*type* of exception thrown. The selector is then used to determine which *catch*
should actually process the exception.
LLVM Code Generation
====================
From a C++ developer's perspective, exceptions are defined in terms of the
``throw`` and ``try``/``catch`` statements. In this section we will describe the
implementation of LLVM exception handling in terms of C++ examples.
Throw
-----
Languages that support exception handling typically provide a ``throw``
operation to initiate the exception process. Internally, a ``throw`` operation
breaks down into two steps.
#. 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.
#. A call is made to the runtime to raise the exception, passing the exception
structure as an argument.
In C++, the allocation of the exception structure is done by the
``__cxa_allocate_exception`` runtime function. The exception raising is handled
by ``__cxa_throw``. The type of the exception is represented using a C++ RTTI
structure.
Try/Catch
---------
A call within the scope of a *try* statement can potentially raise an
exception. In those circumstances, the LLVM C++ front-end replaces the call with
an ``invoke`` instruction. Unlike a call, the ``invoke`` has two potential
continuation points:
#. where to continue when the call succeeds as per normal, and
#. where to continue if the call raises an exception, either by a throw or the
unwinding of a throw
The term used to define a the place where an ``invoke`` continues after an
exception is called a *landing pad*. 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.
The LLVM `landingpad instruction <LangRef.html#i_landingpad>`_ is used to convey
information about the landing pad to the back end. For C++, the ``landingpad``
instruction returns a pointer and integer pair corresponding to the pointer to
the *exception structure* and the *selector value* respectively.
The ``landingpad`` instruction takes a reference to the personality function to
be used for this ``try``/``catch`` sequence. The remainder of the instruction is
a list of *cleanup*, *catch*, and *filter* 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 `undefined`_. 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 `llvm.eh.typeid.for`_ intrinsic.
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 `llvm.eh.typeid.for`_ 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.
Finally, the entry and exit of catch code is bracketed with calls to
``__cxa_begin_catch`` and ``__cxa_end_catch``.
* ``__cxa_begin_catch`` takes an exception structure reference as an argument
and returns the value of the exception object.
* ``__cxa_end_catch`` takes no arguments. This function:
#. Locates the most recently caught exception and decrements its handler
count,
#. Removes the exception from the *caught* stack if the handler count goes to
zero, and
#. Destroys the exception if the handler count goes to zero and the exception
was not re-thrown by throw.
.. note::
a rethrow from within the catch may replace this call with a
``__cxa_rethrow``.
Cleanups
--------
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 `landingpad
instruction <LangRef.html#i_landingpad>`_ should have a *cleanup*
clause. Otherwise, the unwinder will not stop at the landing pad if there are no
catches or filters that require it to.
.. note::
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.
When all cleanups are finished, if the exception is not handled by the current
function, resume unwinding by calling the `resume
instruction <LangRef.html#i_resume>`_, passing in the result of the
``landingpad`` instruction for the original landing pad.
Throw Filters
-------------
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 `landingpad
instruction <LangRef.html#i_landingpad>`_ will have a filter clause. The clause
consists of an array of type infos. ``landingpad`` 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 ``__cxa_call_unexpected`` should be made, otherwise
``_Unwind_Resume``. Each of these functions requires a reference to the
exception structure. Note that the most general form of a ``landingpad``
instruction 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 ``landingpad`` instructions due to inlining creating nested exception
handling scopes.
.. _undefined:
Restrictions
------------
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.
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 ``A``, and it's inlined into a function that
catches exceptions of type ``B``. The inliner will update the ``landingpad``
instruction for the inlined landing pad to include the fact that ``B`` is also
caught. If that landing pad assumes that it will only be entered to catch an
``A``, 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 `resume instruction <LangRef.html#i_resume>`_ if none of the conditions
match.
Exception Handling Intrinsics
=============================
In addition to the ``landingpad`` and ``resume`` instructions, LLVM uses several
intrinsic functions (name prefixed with ``llvm.eh``) to provide exception
handling information at various points in generated code.
.. _llvm.eh.typeid.for:
llvm.eh.typeid.for
------------------
.. code-block:: llvm
i32 @llvm.eh.typeid.for(i8* %type_info)
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
``landingpad`` instruction. The single argument is a reference to a type info.
.. _llvm.eh.sjlj.setjmp:
llvm.eh.sjlj.setjmp
-------------------
.. code-block:: llvm
i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
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 `llvm.eh.sjlj.longjmp`_. The buffer format and the
overall functioning of this intrinsic is compatible with the GCC
``__builtin_setjmp`` implementation allowing code built with the clang and GCC
to interoperate.
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 `llvm.eh.sjlj.longjmp`_ in the second word. The following three words are
available for use in a target-specific manner.
.. _llvm.eh.sjlj.longjmp:
llvm.eh.sjlj.longjmp
--------------------
.. code-block:: llvm
void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
For SJLJ based exception handling, the ``llvm.eh.sjlj.longjmp`` intrinsic is
used to implement ``__builtin_longjmp()``. The single parameter is a pointer to
a buffer populated by `llvm.eh.sjlj.setjmp`_. The frame pointer and stack
pointer are restored from the buffer, then control is transferred to the
destination address.
llvm.eh.sjlj.lsda
-----------------
.. code-block:: llvm
i8* @llvm.eh.sjlj.lsda()
For SJLJ based exception handling, the ``llvm.eh.sjlj.lsda`` 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.
llvm.eh.sjlj.callsite
---------------------
.. code-block:: llvm
void @llvm.eh.sjlj.callsite(i32 %call_site_num)
For SJLJ based exception handling, the ``llvm.eh.sjlj.callsite`` intrinsic
identifies the callsite value associated with the following ``invoke``
instruction. This is used to ensure that landing pad entries in the LSDA are
generated in matching order.
Asm Table Formats
=================
There are two tables that are used by the exception handling runtime to
determine which actions should be taken when an exception is thrown.
Exception Handling Frame
------------------------
An exception handling frame ``eh_frame`` is very similar to the unwind frame
used by DWARF debug info. The frame contains all the information 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.
Exception Tables
----------------
An exception table contains information about what actions to take when an
exception is thrown in a particular part of a function's code. There is one
exception table per function, except leaf functions and functions that have
calls only to non-throwing functions. They do not need an exception table.

4
docs/ExtendingLLVM.html
View File

@ -4,7 +4,7 @@
<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">
<link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
@ -372,7 +372,7 @@ void calcTypeName(const Type *Ty,
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date: 2012-03-23 06:50:46 +0100 (Fri, 23 Mar 2012) $
Last modified: $Date: 2012-04-19 22:20:34 +0200 (Thu, 19 Apr 2012) $
</address>
</body>

948
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 13:25:16 +0200 (Tue, 27 Mar 2012) $
</address>
</body>
</html>

464
docs/FAQ.rst Normal file
View File

@ -0,0 +1,464 @@
.. _faq:
================================
Frequently Asked Questions (FAQ)
================================
.. contents::
:local:
License
=======
Does the University of Illinois Open Source License really qualify as an "open source" license?
-----------------------------------------------------------------------------------------------
Yes, the license is `certified
<http://www.opensource.org/licenses/UoI-NCSA.php>`_ by the Open Source
Initiative (OSI).
Can I modify LLVM source code and redistribute the modified source?
-------------------------------------------------------------------
Yes. The modified source distribution must retain the copyright notice and
follow the three bulletted conditions listed in the `LLVM license
<http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT>`_.
Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?
--------------------------------------------------------------------------------------------------------------------------
Yes. This is why we distribute LLVM under a less restrictive license than GPL,
as explained in the first question above.
Source Code
===========
In what language is LLVM written?
---------------------------------
All of the LLVM tools and libraries are written in C++ with extensive use of
the STL.
How portable is the LLVM source code?
-------------------------------------
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.
Some porting problems may exist in the following areas:
* The autoconf/makefile 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.
Build Problems
==============
When I run configure, it finds the wrong C compiler.
----------------------------------------------------
The ``configure`` script attempts to locate first ``gcc`` and then ``cc``,
unless it finds compiler paths set in ``CC`` and ``CXX`` for the C and C++
compiler, respectively.
If ``configure`` finds the wrong compiler, either adjust your ``PATH``
environment variable or set ``CC`` and ``CXX`` explicitly.
The ``configure`` script finds the right C compiler, but it uses the LLVM tools from a previous build. What do I do?
---------------------------------------------------------------------------------------------------------------------
The ``configure`` script uses the ``PATH`` to find executables, so if it's
grabbing the wrong linker/assembler/etc, there are two ways to fix it:
#. Adjust your ``PATH`` environment variable so that the correct program
appears first in the ``PATH``. This may work, but may not be convenient
when you want them *first* in your path for other work.
#. Run ``configure`` with an alternative ``PATH`` that is correct. In a
Bourne compatible shell, the syntax would be:
.. code-block:: bash
% PATH=[the path without the bad program] ./configure ...
This is still somewhat inconvenient, but it allows ``configure`` to do its
work without having to adjust your ``PATH`` permanently.
When creating a dynamic library, I get a strange GLIBC error.
-------------------------------------------------------------
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.
I've updated my source tree from Subversion, and now my build is trying to use a file/directory that doesn't exist.
-------------------------------------------------------------------------------------------------------------------
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.
I've modified a Makefile in my source tree, but my build tree keeps using the old version. What do I do?
---------------------------------------------------------------------------------------------------------
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:
.. code-block:: bash
% ./config.status <relative path to Makefile>;
If the Makefile is new, you will have to modify the configure script to copy
it over.
I've upgraded to a new version of LLVM, and I get strange build errors.
-----------------------------------------------------------------------
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.
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 ``make clean`` and then
``make`` in the directory that fails to build.
I've built LLVM and am testing it, but the tests freeze.
--------------------------------------------------------
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
``gmake`` command line.
For example, if you built LLVM with the command:
.. code-block:: bash
% gmake ENABLE_PROFILING=1
...then you must run the tests with the following commands:
.. code-block:: bash
% cd llvm/test
% gmake ENABLE_PROFILING=1
Why do test results differ when I perform different types of builds?
--------------------------------------------------------------------
The LLVM test suite is dependent upon several features of the LLVM tools and
libraries.
First, the debugging assertions in code are not enabled in optimized or
profiling builds. Hence, tests that used to fail may pass.
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.
Compiling LLVM with GCC 3.3.2 fails, what should I do?
------------------------------------------------------
This is `a bug in GCC <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392>`_,
and affects projects other than LLVM. Try upgrading or downgrading your GCC.
Compiling LLVM with GCC succeeds, but the resulting tools do not work, what can be wrong?
-----------------------------------------------------------------------------------------
Several versions of GCC have shown a weakness in miscompiling the LLVM
codebase. Please consult your compiler version (``gcc --version``) to find
out whether it is `broken <GettingStarted.html#brokengcc>`_. If so, your only
option is to upgrade GCC to a known good version.
After Subversion update, rebuilding gives the error "No rule to make target".
-----------------------------------------------------------------------------
If the error is of the form:
.. code-block:: bash
gmake[2]: *** No rule to make target `/path/to/somefile',
needed by `/path/to/another/file.d'.
Stop.
This may occur anytime files are moved within the Subversion repository or
removed entirely. In this case, the best solution is to erase all ``.d``
files, which list dependencies for source files, and rebuild:
.. code-block:: bash
% cd $LLVM_OBJ_DIR
% rm -f `find . -name \*\.d`
% gmake
In other cases, it may be necessary to run ``make clean`` before rebuilding.
Source Languages
================
What source languages are supported?
------------------------------------
LLVM currently has full support for C and C++ source languages. These are
available through both `Clang <http://clang.llvm.org/>`_ and `DragonEgg
<http://dragonegg.llvm.org/>`_.
The PyPy developers are working on integrating LLVM into the PyPy backend so
that PyPy language can translate to LLVM.
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?
----------------------------------------------------------------------------------------------------------------------------------------
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:
1. **Call into the LLVM libraries code using your language's FFI (foreign
function interface).**
* *for:* best tracks changes to the LLVM IR, .ll syntax, and .bc format
* *for:* enables running LLVM optimization passes without a emit/parse
overhead
* *for:* adapts well to a JIT context
* *against:* lots of ugly glue code to write
2. **Emit LLVM assembly from your compiler's native language.**
* *for:* very straightforward to get started
* *against:* the .ll parser is slower than the bitcode reader when
interfacing to the middle end
* *against:* it may be harder to track changes to the IR
3. **Emit LLVM bitcode from your compiler's native language.**
* *for:* can use the more-efficient bitcode reader when interfacing to the
middle end
* *against:* you'll have to re-engineer the LLVM IR object model and bitcode
writer in your language
* *against:* it may be harder to track changes to the IR
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.
What support is there for a higher level source language constructs for building a compiler?
--------------------------------------------------------------------------------------------
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.
I don't understand the ``GetElementPtr`` instruction. Help!
-----------------------------------------------------------
See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_.
Using the C and C++ Front Ends
==============================
Can I compile C or C++ code to platform-independent LLVM bitcode?
-----------------------------------------------------------------
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.
Another example is ``sizeof``. It's common for ``sizeof(long)`` to vary
between platforms. In most C front-ends, ``sizeof`` is expanded to a
constant immediately, thus hard-wiring a platform-specific detail.
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.
Questions about code generated by the demo page
===============================================
What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``?
-------------------------------------------------------------------------------------------------------------
If you ``#include`` the ``<iostream>`` header into a C++ translation unit,
the file will probably use the ``std::cin``/``std::cout``/... 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 ``std::cout``, for example, the object would not necessarily be
automatically initialized before your use.
To make ``std::cout`` 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 ``<iostream>``. 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.
If you would like to make it easier to *understand* the LLVM code generated
by the compiler in the demo page, consider using ``printf()`` instead of
``iostream``\s to print values.
Where did all of my code go??
-----------------------------
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.
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 ``volatile`` global variables.
What is this "``undef``" thing that shows up in my code?
--------------------------------------------------------
``undef`` 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:
.. code-block:: c
int X() { int i; return i; }
Is compiled to "``ret i32 undef``" because "``i``" never has a value specified
for it.
Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into "unreachable"? Why not make the verifier reject it?
----------------------------------------------------------------------------------------------------------------------------------------------------------
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:
.. code-block:: llvm
define fastcc void @foo() {
ret void
}
define void @bar() {
call void @foo()
ret void
}
Is optimized to:
.. code-block:: llvm
define fastcc void @foo() {
ret void
}
define void @bar() {
unreachable
}
... 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.
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:
.. code-block:: llvm
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
}
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):
.. code-block:: llvm
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
}
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:
.. code-block:: llvm
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
}
The interesting thing about this is that ``%X`` *must* 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:
.. code-block:: llvm
define fastcc void @foo() {
ret void
}
define void @test(i1 %X) {
F.i:
call fastcc void @foo()
ret void
}

4
docs/GCCFEBuildInstrs.html
View File

@ -3,7 +3,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="llvm.css" type="text/css" media="screen">
<link rel="stylesheet" href="_static/llvm.css" type="text/css" media="screen">
<title>Building the LLVM GCC Front-End</title>
</head>
<body>
@ -272,7 +272,7 @@ More information is <a href="FAQ.html#license">available in the FAQ</a>.
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-23 02:30:22 +0200 (Sat, 23 Apr 2011) $
Last modified: $Date: 2012-04-19 22:20:34 +0200 (Thu, 19 Apr 2012) $
</address>
</body>

6
docs/GarbageCollection.html
View File

@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" Content="text/html; charset=UTF-8" >
<title>Accurate Garbage Collection with LLVM</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
<link rel="stylesheet" href="_static/llvm.css" type="text/css">
<style type="text/css">
.rowhead { text-align: left; background: inherit; }
.indent { padding-left: 1em; }
@ -475,7 +475,7 @@ Entry:
;; Tell LLVM that the stack space is a stack root.
;; Java has type-tags on objects, so we pass null as metadata.
%tmp = bitcast %Object** %X to i8**
call void @llvm.gcroot(i8** %X, i8* null)
call void @llvm.gcroot(i8** %tmp, i8* null)
...
;; "CodeBlock" is the block corresponding to the start
@ -1382,7 +1382,7 @@ Fergus Henderson. International Symposium on Memory Management 2002.</p>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date: 2012-03-03 05:32:33 +0100 (Sat, 03 Mar 2012) $
Last modified: $Date: 2012-05-03 17:25:19 +0200 (Thu, 03 May 2012) $
</address>
</body>

753
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 14:04:26 +0100 (Mon, 31 Oct 2011) $
</address>
</body>
</html>

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