diff options
author | Dan Gohman <djg@cray.com> | 2007-07-18 16:29:46 +0000 |
---|---|---|
committer | Dan Gohman <djg@cray.com> | 2007-07-18 16:29:46 +0000 |
commit | f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc (patch) | |
tree | ebb79ea1ee5e3bc1fdf38541a811a8b804f0679a /docs/CommandGuide | |
download | external_llvm-f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc.zip external_llvm-f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc.tar.gz external_llvm-f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc.tar.bz2 |
It's not necessary to do rounding for alloca operations when the requested
alignment is equal to the stack alignment.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@40004 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/CommandGuide')
27 files changed, 4070 insertions, 0 deletions
diff --git a/docs/CommandGuide/Makefile b/docs/CommandGuide/Makefile new file mode 100644 index 0000000..440d538 --- /dev/null +++ b/docs/CommandGuide/Makefile @@ -0,0 +1,101 @@ +##===- docs/CommandGuide/Makefile --------------------------*- Makefile -*-===## +# +# The LLVM Compiler Infrastructure +# +# This file was developed by the LLVM research group and 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. + +POD := $(wildcard *.pod) +HTML := $(patsubst %.pod, html/%.html, $(POD)) +MAN := $(patsubst %.pod, man/man1/%.1, $(POD)) +PS := $(patsubst %.pod, ps/%.ps, $(POD)) + +all: $(HTML) $(MAN) $(PS) + +.SUFFIXES: +.SUFFIXES: .html .pod .1 .ps + +html/%.html: %.pod + pod2html --css=manpage.css --htmlroot=. \ + --podpath=. --noindex --infile=$< --outfile=$@ --title=$* + +man/man1/%.1: %.pod + pod2man --release=CVS --center="LLVM Command Guide" $< $@ + +ps/%.ps: man/man1/%.1 + groff -Tps -man $< > $@ + +clean: + rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) + +else + +LEVEL := ../.. + +include $(LEVEL)/Makefile.common + +POD := $(wildcard $(PROJ_SRC_DIR)/*.pod) + +EXTRA_DIST := $(POD) index.html + +HTML = $(patsubst $(PROJ_SRC_DIR)/%.pod, $(PROJ_OBJ_DIR)/%.html, $(POD)) +MAN = $(patsubst $(PROJ_SRC_DIR)/%.pod, $(PROJ_OBJ_DIR)/%.1, $(POD)) +PS = $(patsubst $(PROJ_SRC_DIR)/%.pod, $(PROJ_OBJ_DIR)/%.ps, $(POD)) + +.SUFFIXES: +.SUFFIXES: .html .pod .1 .ps + +$(HTML) : html/.dir man/.dir man/man1/.dir ps/.dir + +html: $(HTML) + +$(PROJ_OBJ_DIR)/%.html: %.pod + $(POD2HTML) --css=manpage.css --htmlroot=. --podpath=. \ + --noindex --infile=$< --outfile=$@ --title=$* + +$(PROJ_OBJ_DIR)/%.1: %.pod + $(POD2MAN) --release=$(LLVMVersion) \ + --center="LLVM Command Guide" $< $@ + +$(PROJ_OBJ_DIR)/%.ps: $(PROJ_OBJ_DIR)/%.1 + $(GROFF) -Tps -man $< > $@ + +clean-local:: + $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) + +HTML_DIR := $(PROJ_docsdir)/html/CommandGuide +MAN_DIR := $(PROJ_mandir)/man1 +PS_DIR := $(PROJ_docsdir)/ps + +install-local:: $(HTML) $(MAN) $(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) $(MAN) $(MAN_DIR) + $(Echo) Installing PS CommandGuide Documentation + $(Verb) $(MKDIR) $(PS_DIR) + $(Verb) $(DataInstall) $(PS) $(PS_DIR) + +uninstall-local:: + $(Echo) Uninstalling Documentation + $(Verb) $(RM) -rf $(LLVM_DOCSDIR) + +printvars:: + $(Echo) "POD : " '$(POD)' + $(Echo) "HTML : " '$(HTML)' + +endif diff --git a/docs/CommandGuide/bugpoint.pod b/docs/CommandGuide/bugpoint.pod new file mode 100644 index 0000000..12e32fb --- /dev/null +++ b/docs/CommandGuide/bugpoint.pod @@ -0,0 +1,134 @@ +=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<--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<--check-exit-code>=I<{true,false}> + +Assume a non-zero exit code or core dump from the test program is a failure. +Defaults to true. + +=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 C 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}> + +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, or the C +backend, respectively. + +=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 diff --git a/docs/CommandGuide/html/manpage.css b/docs/CommandGuide/html/manpage.css new file mode 100644 index 0000000..b200343 --- /dev/null +++ b/docs/CommandGuide/html/manpage.css @@ -0,0 +1,256 @@ +/* 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; +} diff --git a/docs/CommandGuide/index.html b/docs/CommandGuide/index.html new file mode 100644 index 0000000..bc18161 --- /dev/null +++ b/docs/CommandGuide/index.html @@ -0,0 +1,160 @@ +<!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="/docs/llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title"> + LLVM Command Guide +</div> + +<div class="doc_text"> + +<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> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="basic">Basic Commands</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<ul> + +<li><a href="html/llvm-as.html"><b>llvm-as</b></a> - + assemble a human-readable .ll file into bytecode</li> + +<li><a href="html/llvm-dis.html"><b>llvm-dis</b></a> - + disassemble a bytecode file into a human-readable .ll file</li> + +<li><a href="html/llvm-upgrade.html"><b>llvm-upgrade</b></a> - + upgrade LLVM assembly from previous version</li> + +<li><a href="html/opt.html"><b>opt</b></a> - + run a series of LLVM-to-LLVM optimizations on a bytecode file</li> + +<li><a href="html/llc.html"><b>llc</b></a> - + generate native machine code for a bytecode file</li> + +<li><a href="html/lli.html"><b>lli</b></a> - + directly run a program compiled to bytecode using a JIT compiler or + interpreter</li> + +<li><a href="html/llvm-link.html"><b>llvm-link</b></a> - + link several bytecode files into one</li> + +<li><a href="html/llvm-ar.html"><b>llvm-ar</b></a> - + archive bytecode files</li> + +<li><a href="html/llvm-ranlib.html"><b>llvm-ranlib</b></a> - + create an index for archives made with llvm-ar</li> + +<li><a href="html/llvm-nm.html"><b>llvm-nm</b></a> - + print out the names and types of symbols in a bytecode file</li> + +<li><a href="html/llvm-prof.html"><b>llvm-prof</b></a> - + format raw `<tt>llvmprof.out</tt>' data into a human-readable report</li> + +<li><a href="html/llvmc.html"><b>llvmc</b></a> - + generic and configurable compiler driver</li> + +<li><a href="html/llvm-ld.html"><b>llvm-ld</b></a> - + general purpose linker with loadable runtime optimization support</li> + +<li><a href="html/llvm-config.html"><b>llvm-config</b></a> - + print out LLVM compilation options, libraries, etc. as configured.</li> + + <li><a href="html/llvm2cpp.html"><b>llvm2cpp</b></a> - convert LLVM assembly + into the corresponding LLVM C++ API calls to produce it</li> +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="frontend">C, C++, and Stacker Front-end Commands</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> +<ul> + +<li><a href="html/llvmgcc.html"><b>llvmgcc</b></a> - + GCC-based C front-end for LLVM + +<li><a href="html/llvmgxx.html"><b>llvmg++</b></a> - + GCC-based C++ front-end for LLVM</li> + +<li><a href="html/stkrc.html"><b>stkrc</b></a> - + front-end compiler for the <a href="../Stacker.html">Stacker</a> + language</li> + +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="debug">Debugging Tools</a> +</div> +<!-- *********************************************************************** --> + + +<div class="doc_text"> + +<ul> + +<li><a href="html/bugpoint.html"><b>bugpoint</b></a> - + automatic test-case reducer</li> + +<li><a href="html/llvm-extract.html"><b>llvm-extract</b></a> - + extract a function from an LLVM bytecode file</li> + +<li><a href="html/llvm-bcanalyzer.html"><b>llvm-bcanalyzer</b></a> - + bytecode analyzer (analyzes the binary encoding itself, not the program it + represents)</li> + +</ul> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="internal">Internal Tools</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> +<ul> + +<li><a href="html/tblgen.html"><b>tblgen</b></a> - + target description reader and generator</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" alt="Valid CSS!"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a> + + <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> + +</body> +</html> diff --git a/docs/CommandGuide/llc.pod b/docs/CommandGuide/llc.pod new file mode 100644 index 0000000..f5fd34f --- /dev/null +++ b/docs/CommandGuide/llc.pod @@ -0,0 +1,191 @@ +=pod + +=head1 NAME + +llc - LLVM static compiler + +=head1 SYNOPSIS + +B<llc> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +The B<llc> command compiles LLVM bitcode 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 bitcode file, unless the B<-march> option is used to +override the default. + +=head1 OPTIONS + +If I<filename> is - or omitted, B<llc> reads LLVM bitcode from standard input. +Otherwise, it will read LLVM bitcode from I<filename>. + +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<-f> + +Overwrite output files. By default, B<llc> will refuse to overwrite +an output file which already exists. + +=item B<-mtriple>=I<target triple> + +Override the target triple specified in the input bitcode file with the +specified string. + +=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> + +=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-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 diff --git a/docs/CommandGuide/lli.pod b/docs/CommandGuide/lli.pod new file mode 100644 index 0000000..1db47b7 --- /dev/null +++ b/docs/CommandGuide/lli.pod @@ -0,0 +1,97 @@ +=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 OPTIONS + +=over + +=item B<-help> + +Print a summary of command line options. + +=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<-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> + +=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<-f>=I<name> + +Call the function named I<name> to start the program. Note: The +function is assumed to have the C signature C<int> I<name> C<(int, +char **, char **)>. If you try to use this option to call a function of +incompatible type, undefined behavior may result. Defaults to C<main>. + +=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 diff --git a/docs/CommandGuide/llvm-ar.pod b/docs/CommandGuide/llvm-ar.pod new file mode 100644 index 0000000..63ba43f --- /dev/null +++ b/docs/CommandGuide/llvm-ar.pod @@ -0,0 +1,406 @@ +=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 diff --git a/docs/CommandGuide/llvm-as.pod b/docs/CommandGuide/llvm-as.pod new file mode 100644 index 0000000..2befed1 --- /dev/null +++ b/docs/CommandGuide/llvm-as.pod @@ -0,0 +1,77 @@ +=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> + +Force overwrite. Normally, B<llvm-as> will refuse to overwrite an +output file that already exists. With this option, B<llvm-as> +will overwrite the output file and replace it with new bitcode. + +=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 diff --git a/docs/CommandGuide/llvm-bcanalyzer.pod b/docs/CommandGuide/llvm-bcanalyzer.pod new file mode 100644 index 0000000..e789c98 --- /dev/null +++ b/docs/CommandGuide/llvm-bcanalyzer.pod @@ -0,0 +1,315 @@ +=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 funtion. 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 diff --git a/docs/CommandGuide/llvm-config.pod b/docs/CommandGuide/llvm-config.pod new file mode 100644 index 0000000..06f10de --- /dev/null +++ b/docs/CommandGuide/llvm-config.pod @@ -0,0 +1,131 @@ +=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 diff --git a/docs/CommandGuide/llvm-db.pod b/docs/CommandGuide/llvm-db.pod new file mode 100644 index 0000000..1324176 --- /dev/null +++ b/docs/CommandGuide/llvm-db.pod @@ -0,0 +1,16 @@ +=pod + +=head1 NAME + +llvm-db - LLVM debugger (alpha) + +=head1 SYNOPSIS + +Details coming soon. Please see +L<http://llvm.org/docs/SourceLevelDebugging.html> in the meantime. + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/llvm-dis.pod b/docs/CommandGuide/llvm-dis.pod new file mode 100644 index 0000000..8df382d --- /dev/null +++ b/docs/CommandGuide/llvm-dis.pod @@ -0,0 +1,60 @@ +=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> + +Force overwrite. Normally, B<llvm-dis> will refuse to overwrite +an output file that already exists. With this option, B<llvm-dis> +will overwrite the output file. + +=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 diff --git a/docs/CommandGuide/llvm-extract.pod b/docs/CommandGuide/llvm-extract.pod new file mode 100644 index 0000000..d916612 --- /dev/null +++ b/docs/CommandGuide/llvm-extract.pod @@ -0,0 +1,63 @@ +=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> + +Force overwrite. Normally, B<llvm-extract> will refuse to overwrite an +output file that already exists. With this option, B<llvm-extract> +will overwrite the output file and replace it with new bitcode. + +=item B<--func> I<function-name> + +Extract the function named I<function-name> from the LLVM bitcode. + +=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. + +=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 diff --git a/docs/CommandGuide/llvm-ld.pod b/docs/CommandGuide/llvm-ld.pod new file mode 100644 index 0000000..d655737 --- /dev/null +++ b/docs/CommandGuide/llvm-ld.pod @@ -0,0 +1,269 @@ +=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<-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<-march=>C<target> + +Specifies the kind of machine for which code or assembly should be generated. + +=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<-O0> + +An alias for the -O1 option. + +=item B<-O1> + +Optimize for linking speed, not execution speed. The optimizer will attempt to +reduce the size of the linked program to reduce I/O but will not otherwise +perform any link-time optimizations. + +=item B<-O2> + +Perform only the minimal or required set of scalar optimizations. + +=item B<-03> + +An alias for the -O2 option. + +=item B<-04> + +Perform the standard link time inter-procedural optimizations. This will +attempt to optimize the program taking the entire program into consideration. + +=item B<-O5> + +Perform aggressive link time optimizations. This is the same as -O4 but works +more aggressively to optimize the program. + +=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. The various B<-On> options will be ignored and +no link time optimization passes will be run. + +=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<-load> F<module> + +Load an optimization module, F<module>, which is expected to be a dynamic +library that provides the function name C<RunOptimizations>. This function will +be passed the PassManager, and the optimization level (values 0-5 based on the +B<-On> option). This function may add passes to the PassManager that should be +run. This feature allows the optimization passes of B<llvm-ld> to be extended. + +=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 diff --git a/docs/CommandGuide/llvm-link.pod b/docs/CommandGuide/llvm-link.pod new file mode 100644 index 0000000..5f4dcb6 --- /dev/null +++ b/docs/CommandGuide/llvm-link.pod @@ -0,0 +1,74 @@ +=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> + +Overwrite output files. By default, B<llvm-link> will not overwrite an output +file if it already exists. + +=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<-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 diff --git a/docs/CommandGuide/llvm-nm.pod b/docs/CommandGuide/llvm-nm.pod new file mode 100644 index 0000000..995ac08 --- /dev/null +++ b/docs/CommandGuide/llvm-nm.pod @@ -0,0 +1,122 @@ +=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 diff --git a/docs/CommandGuide/llvm-prof.pod b/docs/CommandGuide/llvm-prof.pod new file mode 100644 index 0000000..381387d --- /dev/null +++ b/docs/CommandGuide/llvm-prof.pod @@ -0,0 +1,57 @@ +=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 diff --git a/docs/CommandGuide/llvm-ranlib.pod b/docs/CommandGuide/llvm-ranlib.pod new file mode 100644 index 0000000..130edb0 --- /dev/null +++ b/docs/CommandGuide/llvm-ranlib.pod @@ -0,0 +1,52 @@ +=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 diff --git a/docs/CommandGuide/llvm-upgrade.pod b/docs/CommandGuide/llvm-upgrade.pod new file mode 100644 index 0000000..fd84eb4 --- /dev/null +++ b/docs/CommandGuide/llvm-upgrade.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +llvm-upgrade - LLVM assembly upgrade tool + +=head1 SYNOPSIS + +B<llvm-upgrade> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +B<llvm-upgrade> is the LLVM assembly upgrade tool. It reads a file containing +human-readable LLVM assembly language, and upgrades that assembly to the current +version of LLVM. If the input is in the form currently accepted by LLVM, then +no upgrades are performed. + +The expected usage of this tool is as a filter, like this: + +=over + +B<llvm-1.9/bin/llvm-dis < 1.9.bc | llvm-upgrade | llvm-2.0/bin/llvm-as -o 2.0.bc> + +=back + +If F<filename> is omitted or is C<->, then B<llvm-upgrade> reads its input from +standard input. + +If an output file is not specified with the B<-o> option, then +B<llvm-upgrade> sends its output to standard output. + +=head1 OPTIONS + +=over + +=item B<-f> + +Force overwrite. Normally, B<llvm-upgrade> will refuse to overwrite an +output file that already exists. With this option, B<llvm-upgrade> +will overwrite the output file. + +=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-upgrade> +sends its output to standard output. + +=back + +=head1 EXIT STATUS + +If B<llvm-upgrade> 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>, L<llvm-dis|llvm-dis> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/llvm2cpp.pod b/docs/CommandGuide/llvm2cpp.pod new file mode 100644 index 0000000..4b86ae0 --- /dev/null +++ b/docs/CommandGuide/llvm2cpp.pod @@ -0,0 +1,217 @@ +=pod + +=head1 NAME + +llvm2xpp - LLVM bitcode to LLVM C++ IR translator + +=head1 SYNOPSIS + +B<llvm2cpp> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +B<llvm2cpp> translates from LLVM bitcode (.bc files) to a +corresponding C++ source file that will make calls against the LLVM C++ API to +build the same module as the input. By default, the C++ output is a complete +program that builds the module, verifies it and then emits the module as +LLVM assembly. This technique assists with testing because the input to +B<llvm2cpp> and the output of the generated C++ program should be identical. + +If F<filename> is omitted or is C<->, then B<llvm2cpp> reads its input from +standard input. + +If an output file is not specified with the B<-o> option, then +B<llvm2cpp> 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<.bc>, then the output file is of +the same name, except that the suffix is changed to C<.cpp>. + +=item * + +If the input is a file that does not end with the C<.bc> suffix, then the +output file has the same name as the input file, except that the C<.cpp> +suffix is appended. + +=back + +=head1 OPTIONS + +=over + +=item B<-f> + +Force overwrite. Normally, B<llvm2cpp> will refuse to overwrite an +output file that already exists. With this option, B<llvm2cpp> +will overwrite the output file and replace it with new C++ source code. + +=item B<--help> + +Print a summary of command line options. + +=item B<-f> + +Normally, B<llvm2cpp> will not overwrite an existing output file. With this +option, that default behavior is changed and the program will overwrite existing +output files. + +=item B<-o> F<filename> + +Specify the output file name. If F<filename> is C<->, then B<llvm2cpp> +sends its output to standard output. + +=item B<-funcname> F<functionName> + +Specify the name of the function to be generated. The generated code contains a +single function that produces the input module. By default its name is +I<makeLLVMModule>. The B<-funcname> option overrides this default and allows +you to control the name of the generated function. This is handy in conjunction +with the B<-fragment> option when you only want B<llvm2cpp> to generate a +single function that produces the module. With both options, such generated code +could be I<#included> into another program. + +=item B<-for> + +Specify the name of the thing for which C++ code should be generated. By default +the entire input module is re-generated. However, use of the various B<-gen-*> +options can restrict what is produced. This option indicates what that +restriction is. + +=item B<-gen-program> + +Specify that the output should be a complete program. Such program will recreate +B<llvm2cpp>'s input as an LLVM module, verify that module, and then write out +the module in LLVM assembly format. This is useful for doing identity tests +where the output of the generated program is identical to the input to +B<llvm2cpp>. The LLVM DejaGnu test suite can make use of this fact. This is the +default form of generated output. + +If the B<-for> option is given with this option, it specifies the module +identifier to use for the module created. + +=item B<-gen-module> + +Specify that the output should be a function that regenerates the module. It is +assumed that this output will be #included into another program that has already +arranged for the correct header files to be #included. The function generated +takes no arguments and returns a I<Module*>. + +If the B<-for> option is given with this option, it specifies the module +identifier to use in creating the module returned by the generated function. + +=item B<-gen-contents> + +Specify that the output should be a function that adds the contents of the input +module to another module. It is assumed that the output will be #included into +another program that has already arranged for the correct header files to be +#included. The function generated takes a single argument of type I<Module*> and +returns that argument. Note that Module level attributes such as endianess, +pointer size, target triple and inline asm are not passed on from the input +module to the destination module. Only the sub-elements of the module (types, +constants, functions, global variables) will be added to the input module. + +If the B<-for> option is given with this option, it specifies the module +identifier to set in the input module by the generated function. + +=item B<-gen-function> + +Specify that the output should be a function that produces the definitions +necessary for a specific function to be added to a module. It is assumed that +the output will be #included into another program that has already arranged +for the correct header files to be #included. The function generated takes a +single argument of type I<Module*> and returns the I<Function*> that it added to +the module. Note that only those things (types, constants, etc.) directly +needed in the definition of the function will be placed in the generated +function. + +The B<-for> option must be given with this option or an error will be produced. +The value of the option must be the name of a function in the input module for +which code should be generated. If the named function does not exist an error +will be produced. + +=item B<-gen-inline> + +This option is very analagous to B<-gen-function> except that the generated +function will not re-produce the target function's definition. Instead, the body +of the target function is inserted into some other function passed as an +argument to the generated function. Similarly any arguments to the function must +be passed to the generated function. The result of the generated function is the +first basic block of the target function. + +The B<-for> option works the same way as it does for B<-gen-function>. + +=item B<-gen-variable> + +Specify that the output should be a function that produces the definitions +necessary for a specific global variable to be added to a module. It is assumed +that the output will be #included into another program that has already arranged +for the correct header files to be #included. The function generated takes a +single argument of type I<Module*> and returns the I<GlobalVariable*> that it +added to the module. Note that only those things (types, constants, etc.) +directly needed in the definition of the global variable will be placed in the +generated function. + +The B<-for> option must be given with this option or an error will be produced. +THe value of the option must be the name of a global variable in the input +module for which code should be generated. If the named global variable does not +exist an error will be produced. + +=item B<-gen-type> + +Specify that the output should be a function that produces the definitions +necessary for specific type to be added to a module. It is assumed that the +otuput will be #included into another program that has already arranged for the +correct header files to be #included. The function generated take a single +argument of type I<Module*> and returns the I<Type*> that it added to the +module. Note that the generated function will only add the necessary type +definitions to (possibly recursively) define the requested type. + +The B<-for> option must be given with this option or an error will be produced. +The value of the option must be the name of a global type in the input module +for which code should be generated. If the named type does not exist an error +will be produced. + +=item B<-stats> + +Show pass statistics (not interesting in this program). + +=item B<-time-passes> + +Show pass timing statistics (not interesting in this program). + +=item B<-version> + +Show the version number of this program. + +=back + + +=head1 EXIT STATUS + +If B<llvm2cpp> 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> L<tblgen|tblgen> + +=head1 NOTES + +This tool may be removed from a future version of LLVM. Instead, its +functionality may be incorporated into the llc tool. It would then act similarly +to other targets except its output would be C++ source that could be compiled to +construct the input program. + +=head1 AUTHORS + +Written by Reid Spencer (L<http://hlvm.org>). + +=cut diff --git a/docs/CommandGuide/llvmc.pod b/docs/CommandGuide/llvmc.pod new file mode 100644 index 0000000..5e6cc95 --- /dev/null +++ b/docs/CommandGuide/llvmc.pod @@ -0,0 +1,431 @@ +=pod + +=head1 NAME + +llvmc - The LLVM Compiler Driver (experimental) + +=head1 SYNOPSIS + +B<llvmc> [I<options>] [I<filenames>...] + +=head1 DESCRIPTION + +B<llvmc> is a configurable driver for invoking other LLVM (and non-LLVM) tools +in order to compile, optimize and link software for multiple languages. For +those familiar with FSF's B<gcc> tool, it is very similar. Please note that +B<llvmc> is considered an experimental tool. B<llvmc> has the following goals: + +=over + +=item * provide a single point of access to the LLVM tool set, + +=item * hide the complexities of the LLVM tools through a single interface, + +=item * make integration of existing non-LLVM tools simple, + +=item * extend the capabilities of minimal front ends, and + +=item * make the interface for compiling consistent for all languages. + +=back + +The tool itself does nothing with a user's program. It merely invokes other +tools to get the compilation tasks done. + +The options supported by B<llvmc> generalize the compilation process and +provide a consistent and simple interface for multiple programming languages. +This makes it easier for developers to get their software compiled with LLVM. +Without B<llvmc>, developers would need to understand how to invoke the +front-end compiler, optimizer, assembler, and linker in order to compile their +programs. B<llvmc>'s sole mission is to trivialize that process. + +=head2 Basic Operation + +B<llvmc> always takes the following basic actions: + +=over + +=item * Command line options and filenames are collected. + +The command line options provide the marching orders to B<llvmc> on what actions +it should perform. This is the I<request> the user is making of B<llvmc> and it +is interpreted first. + +=item * Configuration files are read. + +Based on the options and the suffixes of the filenames presented, a set of +configuration files are read to configure the actions B<llvmc> will take. +Configuration files are provided by either LLVM or the front end compiler tools +that B<llvmc> invokes. Users generally don't need to be concerned with the +contents of the configuration files. + +=item * Determine actions to take. + +The tool chain needed to complete the task is determined. This is the primary +work of B<llvmc>. It breaks the request specified by the command line options +into a set of basic actions to be done: + +=over + +=item * Pre-processing: gathering/filtering compiler input (optional). + +=item * Translation: source language to bitcode conversion. + +=item * Assembly: bitcode to native code conversion. + +=item * Optimization: conversion of bitcode to something that runs faster. + +=item * Linking: combining multiple bitcode files to produce executable program. + +=back + +=item * Execute actions. + +The actions determined previously are executed sequentially and then +B<llvmc> terminates. + +=back + +=head1 OPTIONS + +=head2 Control Options + +Control options tell B<llvmc> what to do at a high level. The +following control options are defined: + +=over + +=item B<-c> or B<--compile> + +This option specifies that the linking phase is not to be run. All +previous phases, if applicable will run. This is generally how a given +bitcode file is compiled and optimized for a source language module. + +=item B<-k> or B<--link> or default + +This option (or the lack of any control option) specifies that all stages +of compilation, optimization, and linking should be attempted. Source files +specified on the command line will be compiled and linked with objects and +libraries also specified. + +=item B<-S> + +This option specifies that compilation should end in the creation of +an LLVM assembly file that can be later converted to an LLVM object +file. + +=item B<-E> + +This option specifies that no compilation or linking should be +performed. Only pre-processing, if applicable to the language being +compiled, is performed. For languages that support it, this will +result in the output containing the raw input to the compiler. + +=back + +=head2 Optimization Options + +Optimization with B<llvmc> is based on goals and specified with +the following -O options. The specific details of which +optimizations run is controlled by the configuration files because +each source language will have different needs. + +=over + +=item B<-O1> or B<-O0> (default, fast compilation) + +Only those optimizations that will hasten the compilation (mostly by reducing +the output) are applied. In general these are extremely fast and simple +optimizations that reduce emitted code size. The goal here is not to make the +resulting program fast but to make the compilation fast. If not specified, +this is the default level of optimization. + +=item B<-O2> (basic optimization) + +This level of optimization specifies a balance between generating good code +that will execute reasonably quickly and not spending too much time optimizing +the code to get there. For example, this level of optimization may include +things like global common sub-expression elimination, aggressive dead code +elimination, and scalar replication. + +=item B<-O3> (aggressive optimization) + +This level of optimization aggressively optimizes each set of files compiled +together. However, no link-time inter-procedural optimization is performed. +This level implies all the optimizations of the B<-O1> and B<-O2> optimization +levels, and should also provide loop optimizations and compile time +inter-procedural optimizations. Essentially, this level tries to do as much +as it can with the input it is given but doesn't do any link time IPO. + +=item B<-O4> (link time optimization) + +In addition to the previous three levels of optimization, this level of +optimization aggressively optimizes each program at link time. It employs +basic analysis and basic link-time inter-procedural optimizations, +considering the program as a whole. + +=item B<-O5> (aggressive link time optimization) + +This is the same as B<-O4> except it employs aggressive analyses and +aggressive inter-procedural optimization. + +=item B<-O6> (profile guided optimization: not implemented) + +This is the same as B<-O5> except that it employs profile-guided +re-optimization of the program after it has executed. Note that this implies +a single level of re-optimization based on run time profile analysis. Once +the re-optimization has completed, the profiling instrumentation is +removed and final optimizations are employed. + +=item B<-O7> (lifelong optimization: not implemented) + +This is the same as B<-O5> and similar to B<-O6> except that re-optimization +is performed through the life of the program. That is, each run will update +the profile by which future re-optimizations are directed. + +=back + +=head2 Input Options + +=over + +=item B<-l> I<LIBRARY> + +This option instructs B<llvmc> to locate a library named I<LIBRARY> and search +it for unresolved symbols when linking the program. + +=item B<-L> F<path> + +This option instructs B<llvmc> to add F<path> to the list of places in which +the linker will + +=item B<-x> I<LANGUAGE> + +This option instructs B<llvmc> to regard the following input files as +containing programs in the language I<LANGUAGE>. Normally, input file languages +are identified by their suffix but this option will override that default +behavior. The B<-x> option stays in effect until the end of the options or +a new B<-x> option is encountered. + +=back + +=head2 Output Options + +=over + +=item B<-m>I<arch> + +This option selects the back end code generator to use. The I<arch> portion +of the option names the back end to use. + +=item B<--native> + +Normally, B<llvmc> produces bitcode files at most stages of compilation. +With this option, B<llvmc> will arrange for native object files to be +generated with the B<-c> option, native assembly files to be generated +with the B<-S> option, and native executables to be generated with the +B<--link> option. In the case of the B<-E> option, the output will not +differ as there is no I<native> version of pre-processed output. + +=item B<-o> F<filename> + +Specify the output file name. The contents of the file depend on other +options. + +=back + +=head2 Information Options + +=over + +=item B<-n> or B<--no-op> + +This option tells B<llvmc> to do everything but actually execute the +resulting tools. In combination with the B<-v> option, this causes B<llvmc> +to merely print out what it would have done. + +=item B<-v> or B<--verbose> + +This option will cause B<llvmc> to print out (on standard output) each of the +actions it takes to accomplish the objective. The output will immediately +precede the invocation of other tools. + +=item B<--stats> + +Print all statistics gathered during the compilation to the standard error. +Note that this option is merely passed through to the sub-tools to do with +as they please. + +=item B<--time-passes> + +Record the amount of time needed for each optimization pass and print it +to standard error. Like B<--stats> this option is just passed through to +the sub-tools to do with as they please. + +=item B<--time-programs> + +Record the amount of time each program (compilation tool) takes and print +it to the standard error. + +=back + +=head2 Language Specific Options + +=over + +=item B<-T,pre>=I<options> + +Pass an arbitrary option to the pre-processor. + +=item B<-T,opt>=I<options> + +Pass an arbitrary option to the optimizer. + +=item B<-T,lnk>=I<options> + +Pass an arbitrary option to the linker. + +=item B<-T,asm>=I<options> + +Pass an arbitrary option to the code generator. + +=back + +=head2 C/C++ Specific Options + +=over + +=item B<-I>F<path> + +This option is just passed through to a C or C++ front end compiler to tell it +where include files can be found. + +=item B<-D>F<symbol> + +This option is just passed through to a C or C++ front end compiler to tell it +to define a symbol. + +=back + +=head2 Miscellaneous Options + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<--version> + +This option will cause B<llvmc> to print out its version number and terminate. + +=back + +=head2 Advanced Options + +You better know what you're doing if you use these options. Improper use +of these options can produce drastically wrong results. + +=over + +=item B<--config-dir> F<dirname> + +This option tells B<llvmc> to read configuration data from the I<directory> +named F<dirname>. Data from such directories will be read in the order +specified on the command line after all other standard configuration files have +been read. This allows users or groups of users to conveniently create +their own configuration directories in addition to the standard ones to which +they may not have write access. + +=back + + +=head2 Unimplemented Options + +The options below are not currently implemented in B<llvmc> but will be +eventually. They are documented here as "future design". + +=over + +=item B<--show-config> I<[suffixes...]> + +When this option is given, the only action taken by B<llvmc> is to show its +final configuration state in the form of a configuration file. No compilation +tasks will be conducted when this option is given; processing will stop once +the configuration has been printed. The optional (comma separated) list of +suffixes controls what is printed. Without any suffixes, the configuration +for all languages is printed. With suffixes, only the languages pertaining +to those file suffixes will be printed. The configuration information is +printed after all command line options and configuration files have been +read and processed. This allows the user to verify that the correct +configuration data has been read by B<llvmc>. + +=item B<--config> :I<section>:I<name>=I<value> + +This option instructs B<llvmc> to accept I<value> as the value for configuration +item I<name> in the section named I<section>. This is a quick way to override +a configuration item on the command line without resorting to changing the +configuration files. + +=item B<--config-only-from> F<dirname> + +This option tells B<llvmc> to skip the normal processing of configuration +files and only configure from the contents of the F<dirname> directory. Multiple +B<--config-only-from> options may be given in which case the directories are +read in the order given on the command line. + +=item B<--emit-raw-code> + +No optimization is done whatsoever. The compilers invoked by B<llvmc> with +this option given will be instructed to produce raw, unoptimized code. This +option is useful only to front end language developers and therefore does not +participate in the list of B<-O> options. This is distinctly different from +the B<-O0> option (a synonym for B<-O1>) because those optimizations will +reduce code size to make compilation faster. With B<--emit-raw-code>, only +the full raw code produced by the compiler will be generated. + +=back + + +=head1 EXIT STATUS + +If B<llvmc> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value and no compilation actions +will be taken. If one of the compilation tools returns a non-zero +status, pending actions will be discarded and B<llvmc> will return the +same result code as the failing compilation tool. + +=head1 DEFICIENCIES + +B<llvmc> is considered an experimental LLVM tool because it has these +deficiencies: + +=over + +=item Insufficient support for native linking + +Because B<llvm-ld> doesn't handle native linking, neither can B<llvmc> + +=item Poor configuration support + +The support for configuring new languages, etc. is weak. There are many +command line configurations that cannot be achieved with the current +support. Furthermore the grammar is cumbersome for configuration files. +Please see L<http://llvm.org/PR686> for further details. + +=item Does not handle target specific configurations + +This is one of the major deficiencies, also addressed in +L<http://llvm.org/PR686> + +=back + +=head1 SEE ALSO + +L<llvm-as|llvm-as>, L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/llvmgcc.pod b/docs/CommandGuide/llvmgcc.pod new file mode 100644 index 0000000..0b2b156 --- /dev/null +++ b/docs/CommandGuide/llvmgcc.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +llvm-gcc - LLVM C front-end + +=head1 SYNOPSIS + +B<llvm-gcc> [I<options>] I<filename> + +=head1 DESCRIPTION + +The B<llvm-gcc> command is the LLVM C front end. It is a modified +version of gcc that compiles C/ObjC programs into native objects, LLVM +bitcode or LLVM assembly language, depending upon the options. + +By default, B<llvm-gcc> compiles to native objects just like GCC does. If the +B<-emit-llvm> option is given then it will generate LLVM bitcode files instead. +If B<-S> (assembly) is also given, then it will generate LLVM assembly. + +Being derived from the GNU Compiler Collection, B<llvm-gcc> has many +of gcc's features and accepts most of gcc's options. It handles a +number of gcc's extensions to the C programming language. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<-S> + +Do not generate an LLVM bitcode file. Rather, compile the source +file into an LLVM assembly language file. + +=item B<-c> + +Do not generate a linked executable. Rather, compile the source +file into an LLVM bitcode file. This bitcode file can then be +linked with other bitcode files later on to generate a full LLVM +executable. + +=item B<-o> I<filename> + +Specify the output file to be I<filename>. + +=item B<-I> I<directory> + +Add a directory to the header file search path. This option can be +repeated. + +=item B<-L> I<directory> + +Add I<directory> to the library search path. This option can be +repeated. + +=item B<-l>I<name> + +Link in the library libI<name>.[bc | a | so]. This library should +be a bitcode library. + +=item B<-emit-llvm> + +Make the output be LLVM bitcode (or assembly) instead of native object (or +assembly). + +=back + +=head1 EXIT STATUS + +If B<llvm-gcc> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<llvm-g++|llvmgxx> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut + diff --git a/docs/CommandGuide/llvmgxx.pod b/docs/CommandGuide/llvmgxx.pod new file mode 100644 index 0000000..64b670e --- /dev/null +++ b/docs/CommandGuide/llvmgxx.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +llvm-g++ - LLVM C++ front-end + +=head1 SYNOPSIS + +B<llvm-g++> [I<options>] I<filename> + +=head1 DESCRIPTION + +The B<llvm-g++> command is the LLVM C++ front end. It is a modified +version of g++ that compiles C++/ObjC++ programs into native code, +LLVM bitcode or assembly language, depending upon the options. + +By default, B<llvm-g++> compiles to native objects just like GCC does. If the +B<-emit-llvm> option is given then it will generate LLVM bitcode files instead. +If B<-S> (assembly) is also given, then it will generate LLVM assembly. + +Being derived from the GNU Compiler Collection, B<llvm-g++> has many +of g++'s features and accepts most of g++'s options. It handles a +number of g++'s extensions to the C++ programming language. + +=head1 OPTIONS + +=over + +=item B<--help> + +Print a summary of command line options. + +=item B<-S> + +Do not generate an LLVM bitcode file. Rather, compile the source +file into an LLVM assembly language file. + +=item B<-c> + +Do not generate a linked executable. Rather, compile the source +file into an LLVM bitcode file. This bitcode file can then be +linked with other bitcode files later on to generate a full LLVM +executable. + +=item B<-o> I<filename> + +Specify the output file to be I<filename>. + +=item B<-I> I<directory> + +Add a directory to the header file search path. This option can be +repeated. + +=item B<-L> I<directory> + +Add I<directory> to the library search path. This option can be +repeated. + +=item B<-l>I<name> + +Link in the library libI<name>.[bc | a | so]. This library should +be a bitcode library. + +=item B<-emit-llvm> + +Make the output be LLVM bitcode (or assembly) instead of native object (or +assembly). + +=back + +=head1 EXIT STATUS + +If B<llvm-g++> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L<llvm-gcc|llvmgcc> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut + diff --git a/docs/CommandGuide/manpage.css b/docs/CommandGuide/manpage.css new file mode 100644 index 0000000..c922564 --- /dev/null +++ b/docs/CommandGuide/manpage.css @@ -0,0 +1,256 @@ +/* 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; +} diff --git a/docs/CommandGuide/opt.pod b/docs/CommandGuide/opt.pod new file mode 100644 index 0000000..75b7edd --- /dev/null +++ b/docs/CommandGuide/opt.pod @@ -0,0 +1,138 @@ +=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 +bitcode as input, runs the specified optimizations or analyses on it, and then +outputs the optimized LLVM bitcode 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 LLVM +bitcode. 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 +bitcode 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. The input must be an LLVM bitcode file. + +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> + +Force overwrite. Normally, B<opt> will refuse to overwrite an +output file that already exists. With this option, B<opt> will +overwrite the output file and replace it with new bitcode. + +=item B<-help> + +Print a summary of command line options. + +=item B<-o> I<filename> + +Specify the output filename. + +=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 diff --git a/docs/CommandGuide/stkrc.pod b/docs/CommandGuide/stkrc.pod new file mode 100644 index 0000000..4d8b4c9 --- /dev/null +++ b/docs/CommandGuide/stkrc.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +stkrc - Stacker Compiler + +=head1 SYNOPSIS + +B<stkrc> [I<options>] [I<filename>] + +=head1 DESCRIPTION + +The B<stkrc> command is the compiler for the Stacker language. Stacker is a +simple stack based, Forth-like language that was written as a demonstration +language for LLVM. For details on the language, please see +L<http://llvm.org/docs/Stacker.html> . The B<stkrc> compiler is fairly +minimal. It compiles to bitcode only and doesn't perform any optimizations. +The output of stkrc (a bitcode file) can be piped through other LLVM tools +for optimization and linking. + +If F<filename> is omitted or is C<->, then B<stkrc> reads its input +from standard input. This is useful for combining the tool into a pipeline. + +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<.st>, 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<.st> 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<-o> F<filename> + +Specify the output file name. If F<filename> is C<->, then B<llvm-as> +sends its output to standard output. + +=item B<-stats> + +Print statistics acquired during compilation. + +=item B<-time-passes> + +Record the amount of time needed for each pass and print it to standard +error. + +=item B<-f> + +Force the output to be written. Normally, B<stkrc> won't overwrite an existing +bitcode file. This option overrides that behavior. + +=item B<-s> F<stacksize> + +Specify the stack size for the program. The default stack size, 1024, should be +sufficient for most programs. For very large programs, especially those that +recurse a lot, you might want to provide a larger value. Each unit of this +value consumes 8 bytes of memory. + +=item B<-help> + +Print a summary of command line options. + +=back + +=head1 EXIT STATUS + +If B<stkrc> succeeds, it will exit with 0. Otherwise, if an error +occurs, it will exit with a non-zero value, usually 1. + +=head1 SEE ALSO + +L<llvm-as>, L<http://llvm.org/docs/Stacker.html> + +=head1 AUTHORS + +Maintained by the LLVM Team (L<http://llvm.org>). + +=cut diff --git a/docs/CommandGuide/tblgen.pod b/docs/CommandGuide/tblgen.pod new file mode 100644 index 0000000..c8244af --- /dev/null +++ b/docs/CommandGuide/tblgen.pod @@ -0,0 +1,115 @@ + +=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<-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<-gen-emitter> + +Generate machine code emitter. + +=item B<-gen-register-enums> + +Generate the enumeration values for all registers. + +=item B<-gen-register-desc> + +Generate a register info description for each register. + +=item B<-gen-register-desc-header> + +Generate a register info description header for each register. + +=item B<-gen-instr-enums> + +Generate enumeration values for instructions. + +=item B<-gen-instr-desc> + +Generate instruction descriptions. + +=item B<-gen-asm-writer> + +Generate the assembly writer. + +=item B<-gen-dag-isel> + +Generate a DAG (Directed Acycle Graph) instruction selector. + +=item B<-gen-subtarget> + +Generate subtarget enumerations. + +=item B<-gen-intrinsic> + +Generate intrinsic information. + +=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 |