RPCS3/llvm-mirror
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2025-01-31 12:41:49 +01:00
Code Issues Projects Releases Wiki Activity

docs: Introduce cascading style <div> and <p> continued on <h[2-5]>.

Browse Source 
<h2>Section Example</h2>
<div> <!-- h2+div is applied -->
<p>Section preamble.</p>

<h3>Subsection Example</h3>
<p> <!-- h3+p is applied -->
Subsection body
</p>

<!-- End of section body -->
</div>

FIXME: Care H5 better.
llvm-svn: 130040
This commit is contained in:
NAKAMURA Takumi 2011-04-23 00:30:22 +00:00
parent 6efe7518bf
commit ada5cc7c01
52 changed files with 1632 additions and 1569 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
docs/BitCodeFormat.html
View File

@ -50,7 +50,7 @@
<h2><a name="abstract">Abstract</a></h2> <h2><a name="abstract">Abstract</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document describes the LLVM bitstream file format and the encoding of <p>This document describes the LLVM bitstream file format and the encoding of
the LLVM IR into it.</p> the LLVM IR into it.</p>
@ -61,7 +61,7 @@ the LLVM IR into it.</p>
<h2><a name="overview">Overview</a></h2> <h2><a name="overview">Overview</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
What is commonly known as the LLVM bitcode file format (also, sometimes What is commonly known as the LLVM bitcode file format (also, sometimes
@ -91,7 +91,7 @@ wrapper format, then describes the record structure used by LLVM IR files.
<h2><a name="bitstream">Bitstream Format</a></h2> <h2><a name="bitstream">Bitstream Format</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The bitstream format is literally a stream of bits, with a very simple The bitstream format is literally a stream of bits, with a very simple
@ -114,14 +114,12 @@ href="CommandGuide/html/llvm-bcanalyzer.html">llvm-bcanalyzer</a> tool can be
used to dump and inspect arbitrary bitstreams, which is very useful for used to dump and inspect arbitrary bitstreams, which is very useful for
understanding the encoding.</p> understanding the encoding.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="magic">Magic Numbers</a> <a name="magic">Magic Numbers</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The first two bytes of a bitcode file are 'BC' (0x42, 0x43). <p>The first two bytes of a bitcode file are 'BC' (0x42, 0x43).
The second two bytes are an application-specific magic number. Generic The second two bytes are an application-specific magic number. Generic
@ -135,7 +133,7 @@ bitcode, while application-specific programs will want to look at all four.</p>
<a name="primitives">Primitives</a> <a name="primitives">Primitives</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
A bitstream literally consists of a stream of bits, which are read in order A bitstream literally consists of a stream of bits, which are read in order
@ -146,14 +144,12 @@ Width Integers</a> or as <a href="#variablewidth">Variable Width
Integers</a>. Integers</a>.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="fixedwidth">Fixed Width Integers</a> <a name="fixedwidth">Fixed Width Integers</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Fixed-width integer values have their low bits emitted directly to the file. <p>Fixed-width integer values have their low bits emitted directly to the file.
For example, a 3-bit integer value encodes 1 as 001. Fixed width integers For example, a 3-bit integer value encodes 1 as 001. Fixed width integers
@ -168,7 +164,7 @@ Integers</a>.
<a name="variablewidth">Variable Width Integers</a> <a name="variablewidth">Variable Width Integers</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Variable-width integer (VBR) values encode values of arbitrary size, <p>Variable-width integer (VBR) values encode values of arbitrary size,
optimizing for the case where the values are small. Given a 4-bit VBR field, optimizing for the case where the values are small. Given a 4-bit VBR field,
@ -188,7 +184,7 @@ value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="char6">6-bit characters</a></h4> <h4><a name="char6">6-bit characters</a></h4>
<div class="doc_text"> <div>
<p>6-bit characters encode common characters into a fixed 6-bit field. They <p>6-bit characters encode common characters into a fixed 6-bit field. They
represent the following characters with the following 6-bit values:</p> represent the following characters with the following 6-bit values:</p>
@ -212,7 +208,7 @@ characters not in the set.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="wordalign">Word Alignment</a></h4> <h4><a name="wordalign">Word Alignment</a></h4>
<div class="doc_text"> <div>
<p>Occasionally, it is useful to emit zero bits until the bitstream is a <p>Occasionally, it is useful to emit zero bits until the bitstream is a
multiple of 32 bits. This ensures that the bit position in the stream can be multiple of 32 bits. This ensures that the bit position in the stream can be
@ -220,13 +216,14 @@ represented as a multiple of 32-bit words.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="abbrevid">Abbreviation IDs</a> <a name="abbrevid">Abbreviation IDs</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
A bitstream is a sequential series of <a href="#blocks">Blocks</a> and A bitstream is a sequential series of <a href="#blocks">Blocks</a> and
@ -262,7 +259,7 @@ an <a href="#abbrev_records">abbreviated record encoding</a>.</p>
<a name="blocks">Blocks</a> <a name="blocks">Blocks</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
Blocks in a bitstream denote nested regions of the stream, and are identified by Blocks in a bitstream denote nested regions of the stream, and are identified by
@ -303,12 +300,10 @@ its own set of abbreviations, and its own abbrev id width. When a sub-block is
popped, the saved values are restored. popped, the saved values are restored.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="ENTER_SUBBLOCK">ENTER_SUBBLOCK Encoding</a></h4> <h4><a name="ENTER_SUBBLOCK">ENTER_SUBBLOCK Encoding</a></h4>
<div class="doc_text"> <div>
<p><tt>[ENTER_SUBBLOCK, blockid<sub>vbr8</sub>, newabbrevlen<sub>vbr4</sub>, <p><tt>[ENTER_SUBBLOCK, blockid<sub>vbr8</sub>, newabbrevlen<sub>vbr4</sub>,
&lt;align32bits&gt;, blocklen<sub>32</sub>]</tt></p> &lt;align32bits&gt;, blocklen<sub>32</sub>]</tt></p>
@ -329,7 +324,7 @@ reader to skip over the entire block in one jump.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="END_BLOCK">END_BLOCK Encoding</a></h4> <h4><a name="END_BLOCK">END_BLOCK Encoding</a></h4>
<div class="doc_text"> <div>
<p><tt>[END_BLOCK, &lt;align32bits&gt;]</tt></p> <p><tt>[END_BLOCK, &lt;align32bits&gt;]</tt></p>
@ -341,14 +336,14 @@ an even multiple of 32-bits.
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="datarecord">Data Records</a> <a name="datarecord">Data Records</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
Data records consist of a record code and a number of (up to) 64-bit Data records consist of a record code and a number of (up to) 64-bit
integer values. The interpretation of the code and values is integer values. The interpretation of the code and values is
@ -360,12 +355,10 @@ which encodes the target triple of a module. The code is
ASCII codes for the characters in the string. ASCII codes for the characters in the string.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="UNABBREV_RECORD">UNABBREV_RECORD Encoding</a></h4> <h4><a name="UNABBREV_RECORD">UNABBREV_RECORD Encoding</a></h4>
<div class="doc_text"> <div>
<p><tt>[UNABBREV_RECORD, code<sub>vbr6</sub>, numops<sub>vbr6</sub>, <p><tt>[UNABBREV_RECORD, code<sub>vbr6</sub>, numops<sub>vbr6</sub>,
op0<sub>vbr6</sub>, op1<sub>vbr6</sub>, ...]</tt></p> op0<sub>vbr6</sub>, op1<sub>vbr6</sub>, ...]</tt></p>
@ -391,7 +384,7 @@ bits. This is not an efficient encoding, but it is fully general.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="abbrev_records">Abbreviated Record Encoding</a></h4> <h4><a name="abbrev_records">Abbreviated Record Encoding</a></h4>
<div class="doc_text"> <div>
<p><tt>[&lt;abbrevid&gt;, fields...]</tt></p> <p><tt>[&lt;abbrevid&gt;, fields...]</tt></p>
@ -412,12 +405,14 @@ operand value).</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="abbreviations">Abbreviations</a> <a name="abbreviations">Abbreviations</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
Abbreviations are an important form of compression for bitstreams. The idea is Abbreviations are an important form of compression for bitstreams. The idea is
to specify a dense encoding for a class of records once, then use that encoding to specify a dense encoding for a class of records once, then use that encoding
@ -435,12 +430,11 @@ As a concrete example, LLVM IR files usually emit an abbreviation
for binary operators. If a specific LLVM module contained no or few binary for binary operators. If a specific LLVM module contained no or few binary
operators, the abbreviation does not need to be emitted. operators, the abbreviation does not need to be emitted.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="DEFINE_ABBREV">DEFINE_ABBREV Encoding</a></h4> <h4><a name="DEFINE_ABBREV">DEFINE_ABBREV Encoding</a></h4>
<div class="doc_text"> <div>
<p><tt>[DEFINE_ABBREV, numabbrevops<sub>vbr5</sub>, abbrevop0, abbrevop1, <p><tt>[DEFINE_ABBREV, numabbrevops<sub>vbr5</sub>, abbrevop0, abbrevop1,
...]</tt></p> ...]</tt></p>
@ -555,12 +549,14 @@ used for any other string value.
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="stdblocks">Standard Blocks</a> <a name="stdblocks">Standard Blocks</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
In addition to the basic block structure and record encodings, the bitstream In addition to the basic block structure and record encodings, the bitstream
@ -569,12 +565,10 @@ stream is to be decoded or other metadata. In the future, new standard blocks
may be added. Block IDs 0-7 are reserved for standard blocks. may be added. Block IDs 0-7 are reserved for standard blocks.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="BLOCKINFO">#0 - BLOCKINFO Block</a></h4> <h4><a name="BLOCKINFO">#0 - BLOCKINFO Block</a></h4>
<div class="doc_text"> <div>
<p> <p>
The <tt>BLOCKINFO</tt> block allows the description of metadata for other The <tt>BLOCKINFO</tt> block allows the description of metadata for other
@ -623,11 +617,15 @@ from the corresponding blocks. It is not safe to skip them.
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="wrapper">Bitcode Wrapper Format</a></h2> <h2><a name="wrapper">Bitcode Wrapper Format</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper
@ -658,7 +656,7 @@ value that can be used to encode the CPU of the target.
<h2><a name="llvmir">LLVM IR Encoding</a></h2> <h2><a name="llvmir">LLVM IR Encoding</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
LLVM IR is encoded into a bitstream by defining blocks and records. It uses LLVM IR is encoded into a bitstream by defining blocks and records. It uses
@ -669,17 +667,17 @@ that the writer uses, as these are fully self-described in the file, and the
reader is not allowed to build in any knowledge of this. reader is not allowed to build in any knowledge of this.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="basics">Basics</a> <a name="basics">Basics</a>
</h3> </h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="ir_magic">LLVM IR Magic Number</a></h4> <h4><a name="ir_magic">LLVM IR Magic Number</a></h4>
<div class="doc_text"> <div>
<p> <p>
The magic number for LLVM IR files is: The magic number for LLVM IR files is:
@ -701,7 +699,7 @@ When combined with the bitcode magic number and viewed as bytes, this is
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="ir_signed_vbr">Signed VBRs</a></h4> <h4><a name="ir_signed_vbr">Signed VBRs</a></h4>
<div class="doc_text"> <div>
<p> <p>
<a href="#variablewidth">Variable Width Integer</a> encoding is an efficient way to <a href="#variablewidth">Variable Width Integer</a> encoding is an efficient way to
@ -734,7 +732,7 @@ within <tt>CONSTANTS_BLOCK</tt> blocks.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="ir_blocks">LLVM IR Blocks</a></h4> <h4><a name="ir_blocks">LLVM IR Blocks</a></h4>
<div class="doc_text"> <div>
<p> <p>
LLVM IR is defined with the following blocks: LLVM IR is defined with the following blocks:
@ -762,12 +760,14 @@ LLVM IR is defined with the following blocks:
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="MODULE_BLOCK">MODULE_BLOCK Contents</a> <a name="MODULE_BLOCK">MODULE_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>MODULE_BLOCK</tt> block (id 8) is the top-level block for LLVM <p>The <tt>MODULE_BLOCK</tt> block (id 8) is the top-level block for LLVM
bitcode files, and each bitcode file must contain exactly one. In bitcode files, and each bitcode file must contain exactly one. In
@ -787,12 +787,10 @@ following sub-blocks:
<li><a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a></li> <li><a href="#METADATA_BLOCK"><tt>METADATA_BLOCK</tt></a></li>
</ul> </ul>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_VERSION">MODULE_CODE_VERSION Record</a></h4> <h4><a name="MODULE_CODE_VERSION">MODULE_CODE_VERSION Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[VERSION, version#]</tt></p> <p><tt>[VERSION, version#]</tt></p>
@ -804,7 +802,7 @@ time.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_TRIPLE">MODULE_CODE_TRIPLE Record</a></h4> <h4><a name="MODULE_CODE_TRIPLE">MODULE_CODE_TRIPLE Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[TRIPLE, ...string...]</tt></p> <p><tt>[TRIPLE, ...string...]</tt></p>
<p>The <tt>TRIPLE</tt> record (code 2) contains a variable number of <p>The <tt>TRIPLE</tt> record (code 2) contains a variable number of
@ -815,7 +813,7 @@ specification string.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_DATALAYOUT">MODULE_CODE_DATALAYOUT Record</a></h4> <h4><a name="MODULE_CODE_DATALAYOUT">MODULE_CODE_DATALAYOUT Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[DATALAYOUT, ...string...]</tt></p> <p><tt>[DATALAYOUT, ...string...]</tt></p>
<p>The <tt>DATALAYOUT</tt> record (code 3) contains a variable number of <p>The <tt>DATALAYOUT</tt> record (code 3) contains a variable number of
@ -826,7 +824,7 @@ specification string.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_ASM">MODULE_CODE_ASM Record</a></h4> <h4><a name="MODULE_CODE_ASM">MODULE_CODE_ASM Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[ASM, ...string...]</tt></p> <p><tt>[ASM, ...string...]</tt></p>
<p>The <tt>ASM</tt> record (code 4) contains a variable number of <p>The <tt>ASM</tt> record (code 4) contains a variable number of
@ -837,7 +835,7 @@ individual assembly blocks separated by newline (ASCII 10) characters.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME Record</a></h4> <h4><a name="MODULE_CODE_SECTIONNAME">MODULE_CODE_SECTIONNAME Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[SECTIONNAME, ...string...]</tt></p> <p><tt>[SECTIONNAME, ...string...]</tt></p>
<p>The <tt>SECTIONNAME</tt> record (code 5) contains a variable number <p>The <tt>SECTIONNAME</tt> record (code 5) contains a variable number
@ -852,7 +850,7 @@ referenced by the 1-based index in the <i>section</i> fields of
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_DEPLIB">MODULE_CODE_DEPLIB Record</a></h4> <h4><a name="MODULE_CODE_DEPLIB">MODULE_CODE_DEPLIB Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[DEPLIB, ...string...]</tt></p> <p><tt>[DEPLIB, ...string...]</tt></p>
<p>The <tt>DEPLIB</tt> record (code 6) contains a variable number of <p>The <tt>DEPLIB</tt> record (code 6) contains a variable number of
@ -865,7 +863,7 @@ library name referenced.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_GLOBALVAR">MODULE_CODE_GLOBALVAR Record</a></h4> <h4><a name="MODULE_CODE_GLOBALVAR">MODULE_CODE_GLOBALVAR Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]</tt></p> <p><tt>[GLOBALVAR, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal]</tt></p>
<p>The <tt>GLOBALVAR</tt> record (code 7) marks the declaration or <p>The <tt>GLOBALVAR</tt> record (code 7) marks the declaration or
@ -929,7 +927,7 @@ has <tt>unnamed_addr</tt></li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_FUNCTION">MODULE_CODE_FUNCTION Record</a></h4> <h4><a name="MODULE_CODE_FUNCTION">MODULE_CODE_FUNCTION Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]</tt></p> <p><tt>[FUNCTION, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc]</tt></p>
@ -985,7 +983,7 @@ has <tt>unnamed_addr</tt></li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_ALIAS">MODULE_CODE_ALIAS Record</a></h4> <h4><a name="MODULE_CODE_ALIAS">MODULE_CODE_ALIAS Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[ALIAS, alias type, aliasee val#, linkage, visibility]</tt></p> <p><tt>[ALIAS, alias type, aliasee val#, linkage, visibility]</tt></p>
@ -1009,7 +1007,7 @@ for this alias</li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_PURGEVALS">MODULE_CODE_PURGEVALS Record</a></h4> <h4><a name="MODULE_CODE_PURGEVALS">MODULE_CODE_PURGEVALS Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[PURGEVALS, numvals]</tt></p> <p><tt>[PURGEVALS, numvals]</tt></p>
<p>The <tt>PURGEVALS</tt> record (code 10) resets the module-level <p>The <tt>PURGEVALS</tt> record (code 10) resets the module-level
@ -1022,7 +1020,7 @@ new value indices will start from the given <i>numvals</i> value.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="MODULE_CODE_GCNAME">MODULE_CODE_GCNAME Record</a></h4> <h4><a name="MODULE_CODE_GCNAME">MODULE_CODE_GCNAME Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[GCNAME, ...string...]</tt></p> <p><tt>[GCNAME, ...string...]</tt></p>
<p>The <tt>GCNAME</tt> record (code 11) contains a variable number of <p>The <tt>GCNAME</tt> record (code 11) contains a variable number of
@ -1033,12 +1031,14 @@ the module. These records can be referenced by 1-based index in the <i>gc</i>
fields of <tt>FUNCTION</tt> records.</p> fields of <tt>FUNCTION</tt> records.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a> <a name="PARAMATTR_BLOCK">PARAMATTR_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>PARAMATTR_BLOCK</tt> block (id 9) contains a table of <p>The <tt>PARAMATTR_BLOCK</tt> block (id 9) contains a table of
entries describing the attributes of function parameters. These entries describing the attributes of function parameters. These
@ -1052,13 +1052,10 @@ href="#FUNC_CODE_INST_CALL"><tt>INST_CALL</tt></a> records.</p>
that each is unique (i.e., no two indicies represent equivalent that each is unique (i.e., no two indicies represent equivalent
attribute lists). </p> attribute lists). </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY Record</a></h4> <h4><a name="PARAMATTR_CODE_ENTRY">PARAMATTR_CODE_ENTRY Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[ENTRY, paramidx0, attr0, paramidx1, attr1...]</tt></p> <p><tt>[ENTRY, paramidx0, attr0, paramidx1, attr1...]</tt></p>
@ -1099,12 +1096,14 @@ the logarithm base 2 of the requested alignment, plus 1</li>
</ul> </ul>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="TYPE_BLOCK">TYPE_BLOCK Contents</a> <a name="TYPE_BLOCK">TYPE_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TYPE_BLOCK</tt> block (id 10) contains records which <p>The <tt>TYPE_BLOCK</tt> block (id 10) contains records which
constitute a table of type operator entries used to represent types constitute a table of type operator entries used to represent types
@ -1119,12 +1118,10 @@ type operator records.
each entry is unique (i.e., no two indicies represent structurally each entry is unique (i.e., no two indicies represent structurally
equivalent types). </p> equivalent types). </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_NUMENTRY">TYPE_CODE_NUMENTRY Record</a></h4> <h4><a name="TYPE_CODE_NUMENTRY">TYPE_CODE_NUMENTRY Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[NUMENTRY, numentries]</tt></p> <p><tt>[NUMENTRY, numentries]</tt></p>
@ -1138,7 +1135,7 @@ in the block.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_VOID">TYPE_CODE_VOID Record</a></h4> <h4><a name="TYPE_CODE_VOID">TYPE_CODE_VOID Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[VOID]</tt></p> <p><tt>[VOID]</tt></p>
@ -1150,7 +1147,7 @@ type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_FLOAT">TYPE_CODE_FLOAT Record</a></h4> <h4><a name="TYPE_CODE_FLOAT">TYPE_CODE_FLOAT Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[FLOAT]</tt></p> <p><tt>[FLOAT]</tt></p>
@ -1162,7 +1159,7 @@ floating point) type to the type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_DOUBLE">TYPE_CODE_DOUBLE Record</a></h4> <h4><a name="TYPE_CODE_DOUBLE">TYPE_CODE_DOUBLE Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[DOUBLE]</tt></p> <p><tt>[DOUBLE]</tt></p>
@ -1174,7 +1171,7 @@ floating point) type to the type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_LABEL">TYPE_CODE_LABEL Record</a></h4> <h4><a name="TYPE_CODE_LABEL">TYPE_CODE_LABEL Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[LABEL]</tt></p> <p><tt>[LABEL]</tt></p>
@ -1186,7 +1183,7 @@ the type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_OPAQUE">TYPE_CODE_OPAQUE Record</a></h4> <h4><a name="TYPE_CODE_OPAQUE">TYPE_CODE_OPAQUE Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[OPAQUE]</tt></p> <p><tt>[OPAQUE]</tt></p>
@ -1199,7 +1196,7 @@ unified.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_INTEGER">TYPE_CODE_INTEGER Record</a></h4> <h4><a name="TYPE_CODE_INTEGER">TYPE_CODE_INTEGER Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[INTEGER, width]</tt></p> <p><tt>[INTEGER, width]</tt></p>
@ -1212,7 +1209,7 @@ integer type.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_POINTER">TYPE_CODE_POINTER Record</a></h4> <h4><a name="TYPE_CODE_POINTER">TYPE_CODE_POINTER Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[POINTER, pointee type, address space]</tt></p> <p><tt>[POINTER, pointee type, address space]</tt></p>
@ -1232,7 +1229,7 @@ default address space is zero.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_FUNCTION">TYPE_CODE_FUNCTION Record</a></h4> <h4><a name="TYPE_CODE_FUNCTION">TYPE_CODE_FUNCTION Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[FUNCTION, vararg, ignored, retty, ...paramty... ]</tt></p> <p><tt>[FUNCTION, vararg, ignored, retty, ...paramty... ]</tt></p>
@ -1256,7 +1253,7 @@ parameter types of the function</li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_STRUCT">TYPE_CODE_STRUCT Record</a></h4> <h4><a name="TYPE_CODE_STRUCT">TYPE_CODE_STRUCT Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[STRUCT, ispacked, ...eltty...]</tt></p> <p><tt>[STRUCT, ispacked, ...eltty...]</tt></p>
@ -1274,7 +1271,7 @@ types of the structure</li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_ARRAY">TYPE_CODE_ARRAY Record</a></h4> <h4><a name="TYPE_CODE_ARRAY">TYPE_CODE_ARRAY Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[ARRAY, numelts, eltty]</tt></p> <p><tt>[ARRAY, numelts, eltty]</tt></p>
@ -1291,7 +1288,7 @@ table. The operand fields are</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_VECTOR">TYPE_CODE_VECTOR Record</a></h4> <h4><a name="TYPE_CODE_VECTOR">TYPE_CODE_VECTOR Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[VECTOR, numelts, eltty]</tt></p> <p><tt>[VECTOR, numelts, eltty]</tt></p>
@ -1308,7 +1305,7 @@ table. The operand fields are</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_X86_FP80">TYPE_CODE_X86_FP80 Record</a></h4> <h4><a name="TYPE_CODE_X86_FP80">TYPE_CODE_X86_FP80 Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[X86_FP80]</tt></p> <p><tt>[X86_FP80]</tt></p>
@ -1320,7 +1317,7 @@ floating point) type to the type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_FP128">TYPE_CODE_FP128 Record</a></h4> <h4><a name="TYPE_CODE_FP128">TYPE_CODE_FP128 Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[FP128]</tt></p> <p><tt>[FP128]</tt></p>
@ -1332,7 +1329,7 @@ floating point) type to the type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_PPC_FP128">TYPE_CODE_PPC_FP128 Record</a></h4> <h4><a name="TYPE_CODE_PPC_FP128">TYPE_CODE_PPC_FP128 Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[PPC_FP128]</tt></p> <p><tt>[PPC_FP128]</tt></p>
@ -1344,7 +1341,7 @@ floating point) type to the type table.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TYPE_CODE_METADATA">TYPE_CODE_METADATA Record</a></h4> <h4><a name="TYPE_CODE_METADATA">TYPE_CODE_METADATA Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[METADATA]</tt></p> <p><tt>[METADATA]</tt></p>
@ -1353,12 +1350,14 @@ type to the type table.
</p> </p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a> <a name="CONSTANTS_BLOCK">CONSTANTS_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>CONSTANTS_BLOCK</tt> block (id 11) ... <p>The <tt>CONSTANTS_BLOCK</tt> block (id 11) ...
</p> </p>
@ -1371,7 +1370,7 @@ type to the type table.
<a name="FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a> <a name="FUNCTION_BLOCK">FUNCTION_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>FUNCTION_BLOCK</tt> block (id 12) ... <p>The <tt>FUNCTION_BLOCK</tt> block (id 12) ...
</p> </p>
@ -1394,19 +1393,17 @@ type to the type table.
<a name="TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a> <a name="TYPE_SYMTAB_BLOCK">TYPE_SYMTAB_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TYPE_SYMTAB_BLOCK</tt> block (id 13) contains entries which <p>The <tt>TYPE_SYMTAB_BLOCK</tt> block (id 13) contains entries which
map between module-level named types and their corresponding type map between module-level named types and their corresponding type
indices. indices.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4><a name="TST_CODE_ENTRY">TST_CODE_ENTRY Record</a></h4> <h4><a name="TST_CODE_ENTRY">TST_CODE_ENTRY Record</a></h4>
<div class="doc_text"> <div>
<p><tt>[ENTRY, typeid, ...string...]</tt></p> <p><tt>[ENTRY, typeid, ...string...]</tt></p>
@ -1417,13 +1414,14 @@ name. Each entry corresponds to a single named type.
</p> </p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a> <a name="VALUE_SYMTAB_BLOCK">VALUE_SYMTAB_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>VALUE_SYMTAB_BLOCK</tt> block (id 14) ... <p>The <tt>VALUE_SYMTAB_BLOCK</tt> block (id 14) ...
</p> </p>
@ -1436,7 +1434,7 @@ name. Each entry corresponds to a single named type.
<a name="METADATA_BLOCK">METADATA_BLOCK Contents</a> <a name="METADATA_BLOCK">METADATA_BLOCK Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>METADATA_BLOCK</tt> block (id 15) ... <p>The <tt>METADATA_BLOCK</tt> block (id 15) ...
</p> </p>
@ -1449,13 +1447,14 @@ name. Each entry corresponds to a single named type.
<a name="METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a> <a name="METADATA_ATTACHMENT">METADATA_ATTACHMENT Contents</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>METADATA_ATTACHMENT</tt> block (id 16) ... <p>The <tt>METADATA_ATTACHMENT</tt> block (id 16) ...
</p> </p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

18
docs/Bugpoint.html
View File

@ -32,7 +32,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and <p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and
passes. It can be used to debug three types of failures: optimizer crashes, passes. It can be used to debug three types of failures: optimizer crashes,
@ -55,7 +55,7 @@ href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><tt>bugpoint</tt> is designed to be a useful tool without requiring any <p><tt>bugpoint</tt> is designed to be a useful tool without requiring any
hooks into the LLVM infrastructure at all. It works with any and all LLVM hooks into the LLVM infrastructure at all. It works with any and all LLVM
@ -68,14 +68,12 @@ is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
debugging a miscompilation where each test of the program (which requires debugging a miscompilation where each test of the program (which requires
executing it) takes a long time.</p> executing it) takes a long time.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="autoselect">Automatic Debugger Selection</a> <a name="autoselect">Automatic Debugger Selection</a>
</h3> </h3>
<div class="doc_text"> <div>
<p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on <p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on
the command line and links them together into a single module, called the test the command line and links them together into a single module, called the test
@ -108,7 +106,7 @@ Otherwise, there is no problem <tt>bugpoint</tt> can debug.</p>
<a name="crashdebug">Crash debugger</a> <a name="crashdebug">Crash debugger</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard <p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard
as it can to reduce the list of passes (for optimizer crashes) and the size of as it can to reduce the list of passes (for optimizer crashes) and the size of
@ -133,7 +131,7 @@ reproduce the failure with <tt>opt</tt> or <tt>llc</tt>.</p>
<a name="codegendebug">Code generator debugger</a> <a name="codegendebug">Code generator debugger</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The code generator debugger attempts to narrow down the amount of code that <p>The code generator debugger attempts to narrow down the amount of code that
is being miscompiled by the selected code generator. To do this, it takes the is being miscompiled by the selected code generator. To do this, it takes the
@ -154,7 +152,7 @@ good code.</p>
<a name="miscompilationdebug">Miscompilation debugger</a> <a name="miscompilationdebug">Miscompilation debugger</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The miscompilation debugger works similarly to the code generator debugger. <p>The miscompilation debugger works similarly to the code generator debugger.
It works by splitting the test program into two pieces, running the It works by splitting the test program into two pieces, running the
@ -166,13 +164,15 @@ assumes that the selected code generator is working properly.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="advice">Advice for using bugpoint</a> <a name="advice">Advice for using bugpoint</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in <tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
non-obvious ways. Here are some hints and tips:<p> non-obvious ways. Here are some hints and tips:<p>

36
docs/CMake.html
View File

@ -41,7 +41,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><a href="http://www.cmake.org/">CMake</a> is a cross-platform <p><a href="http://www.cmake.org/">CMake</a> is a cross-platform
build-generator tool. CMake does not build the project, it generates build-generator tool. CMake does not build the project, it generates
@ -64,7 +64,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> We use here the command-line, non-interactive CMake interface </p> <p> We use here the command-line, non-interactive CMake interface </p>
@ -117,7 +117,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section explains basic aspects of CMake, mostly for <p>This section explains basic aspects of CMake, mostly for
explaining those options which you may need on your day-to-day explaining those options which you may need on your day-to-day
@ -165,7 +165,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Variables customize how the build will be generated. Options are <p>Variables customize how the build will be generated. Options are
boolean variables, with possible values ON/OFF. Options and boolean variables, with possible values ON/OFF. Options and
@ -194,14 +194,12 @@
<p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p> <p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="freccmake">Frequently-used CMake variables</a> <a name="freccmake">Frequently-used CMake variables</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Here are listed some of the CMake variables that are used often, <p>Here are listed some of the CMake variables that are used often,
along with a brief explanation and LLVM-specific notes. For full along with a brief explanation and LLVM-specific notes. For full
@ -244,7 +242,7 @@
<a name="llvmvars">LLVM-specific variables</a> <a name="llvmvars">LLVM-specific variables</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt> <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
@ -357,13 +355,15 @@
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="testing">Executing the test suite</a> <a name="testing">Executing the test suite</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Testing is performed when the <i>check</i> target is built. For <p>Testing is performed when the <i>check</i> target is built. For
instance, if you are using makefiles, execute this command while on instance, if you are using makefiles, execute this command while on
@ -383,7 +383,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this <p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this
wiki page</a> for generic instructions on how to cross-compile wiki page</a> for generic instructions on how to cross-compile
@ -404,7 +404,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The most difficult part of adding LLVM to the build of a project <p>The most difficult part of adding LLVM to the build of a project
is to determine the set of LLVM libraries corresponding to the set is to determine the set of LLVM libraries corresponding to the set
@ -459,14 +459,12 @@
</pre> </pre>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="passdev">Developing LLVM pass out of source</a> <a name="passdev">Developing LLVM pass out of source</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>It is possible to develop LLVM passes against installed LLVM. <p>It is possible to develop LLVM passes against installed LLVM.
An example of project layout provided below:</p> An example of project layout provided below:</p>
@ -518,23 +516,23 @@
</div> </div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="specifics">Compiler/Platform specific topics</a> <a name="specifics">Compiler/Platform specific topics</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Notes for specific compilers and/or platforms.</p> <p>Notes for specific compilers and/or platforms.</p>
</div>
<h3> <h3>
<a name="msvc">Microsoft Visual C++</a> <a name="msvc">Microsoft Visual C++</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt> <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
@ -546,6 +544,8 @@
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

217
docs/CodeGenerator.html
View File

@ -132,7 +132,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The LLVM target-independent code generator is a framework that provides a <p>The LLVM target-independent code generator is a framework that provides a
suite of reusable components for translating the LLVM internal representation suite of reusable components for translating the LLVM internal representation
@ -188,14 +188,12 @@
depend on the target-description and machine code representation classes, depend on the target-description and machine code representation classes,
ensuring that it is portable.</p> ensuring that it is portable.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="required">Required components in the code generator</a> <a name="required">Required components in the code generator</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The two pieces of the LLVM code generator are the high-level interface to the <p>The two pieces of the LLVM code generator are the high-level interface to the
code generator and the set of reusable components that can be used to build code generator and the set of reusable components that can be used to build
@ -227,7 +225,7 @@
<a name="high-level-design">The high-level design of the code generator</a> <a name="high-level-design">The high-level design of the code generator</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The LLVM target-independent code generator is designed to support efficient <p>The LLVM target-independent code generator is designed to support efficient
and quality code generation for standard register-based microprocessors. and quality code generation for standard register-based microprocessors.
@ -301,7 +299,7 @@
<a name="tablegen">Using TableGen for target description</a> <a name="tablegen">Using TableGen for target description</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The target description classes require a detailed description of the target <p>The target description classes require a detailed description of the target
architecture. These target descriptions often have a large amount of common architecture. These target descriptions often have a large amount of common
@ -324,13 +322,15 @@
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="targetdesc">Target description classes</a> <a name="targetdesc">Target description classes</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The LLVM target description classes (located in the <p>The LLVM target description classes (located in the
<tt>include/llvm/Target</tt> directory) provide an abstract description of <tt>include/llvm/Target</tt> directory) provide an abstract description of
@ -346,14 +346,12 @@
<tt><a href="#targetmachine">TargetMachine</a></tt> class provides accessors <tt><a href="#targetmachine">TargetMachine</a></tt> class provides accessors
that should be implemented by the target.</p> that should be implemented by the target.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="targetmachine">The <tt>TargetMachine</tt> class</a> <a name="targetmachine">The <tt>TargetMachine</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetMachine</tt> class provides virtual methods that are used to <p>The <tt>TargetMachine</tt> class provides virtual methods that are used to
access the target-specific implementations of the various target description access the target-specific implementations of the various target description
@ -373,7 +371,7 @@
<a name="targetdata">The <tt>TargetData</tt> class</a> <a name="targetdata">The <tt>TargetData</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetData</tt> class is the only required target description class, <p>The <tt>TargetData</tt> class is the only required target description class,
and it is the only class that is not extensible (you cannot derived a new and it is the only class that is not extensible (you cannot derived a new
@ -389,7 +387,7 @@
<a name="targetlowering">The <tt>TargetLowering</tt> class</a> <a name="targetlowering">The <tt>TargetLowering</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetLowering</tt> class is used by SelectionDAG based instruction <p>The <tt>TargetLowering</tt> class is used by SelectionDAG based instruction
selectors primarily to describe how LLVM code should be lowered to selectors primarily to describe how LLVM code should be lowered to
@ -415,7 +413,7 @@
<a name="targetregisterinfo">The <tt>TargetRegisterInfo</tt> class</a> <a name="targetregisterinfo">The <tt>TargetRegisterInfo</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetRegisterInfo</tt> class is used to describe the register file <p>The <tt>TargetRegisterInfo</tt> class is used to describe the register file
of the target and any interactions between the registers.</p> of the target and any interactions between the registers.</p>
@ -449,7 +447,7 @@
<a name="targetinstrinfo">The <tt>TargetInstrInfo</tt> class</a> <a name="targetinstrinfo">The <tt>TargetInstrInfo</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetInstrInfo</tt> class is used to describe the machine <p>The <tt>TargetInstrInfo</tt> class is used to describe the machine
instructions supported by the target. It is essentially an array of instructions supported by the target. It is essentially an array of
@ -467,7 +465,7 @@
<a name="targetframeinfo">The <tt>TargetFrameInfo</tt> class</a> <a name="targetframeinfo">The <tt>TargetFrameInfo</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetFrameInfo</tt> class is used to provide information about the <p>The <tt>TargetFrameInfo</tt> class is used to provide information about the
stack frame layout of the target. It holds the direction of stack growth, the stack frame layout of the target. It holds the direction of stack growth, the
@ -483,7 +481,7 @@
<a name="targetsubtarget">The <tt>TargetSubtarget</tt> class</a> <a name="targetsubtarget">The <tt>TargetSubtarget</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetSubtarget</tt> class is used to provide information about the <p>The <tt>TargetSubtarget</tt> class is used to provide information about the
specific chip set being targeted. A sub-target informs code generation of specific chip set being targeted. A sub-target informs code generation of
@ -499,7 +497,7 @@
<a name="targetjitinfo">The <tt>TargetJITInfo</tt> class</a> <a name="targetjitinfo">The <tt>TargetJITInfo</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>TargetJITInfo</tt> class exposes an abstract interface used by the <p>The <tt>TargetJITInfo</tt> class exposes an abstract interface used by the
Just-In-Time code generator to perform target-specific activities, such as Just-In-Time code generator to perform target-specific activities, such as
@ -509,13 +507,15 @@
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="codegendesc">Machine code description classes</a> <a name="codegendesc">Machine code description classes</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>At the high-level, LLVM code is translated to a machine specific <p>At the high-level, LLVM code is translated to a machine specific
representation formed out of representation formed out of
@ -528,14 +528,12 @@
SSA representation for machine code, as well as a register allocated, non-SSA SSA representation for machine code, as well as a register allocated, non-SSA
form.</p> form.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="machineinstr">The <tt>MachineInstr</tt> class</a> <a name="machineinstr">The <tt>MachineInstr</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Target machine instructions are represented as instances of the <p>Target machine instructions are represented as instances of the
<tt>MachineInstr</tt> class. This class is an extremely abstract way of <tt>MachineInstr</tt> class. This class is an extremely abstract way of
@ -576,14 +574,12 @@
<p>Also if the first operand is a def, it is easier to <a href="#buildmi">create <p>Also if the first operand is a def, it is easier to <a href="#buildmi">create
instructions</a> whose only def is the first operand.</p> instructions</a> whose only def is the first operand.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="buildmi">Using the <tt>MachineInstrBuilder.h</tt> functions</a> <a name="buildmi">Using the <tt>MachineInstrBuilder.h</tt> functions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Machine instructions are created by using the <tt>BuildMI</tt> functions, <p>Machine instructions are created by using the <tt>BuildMI</tt> functions,
located in the <tt>include/llvm/CodeGen/MachineInstrBuilder.h</tt> file. The located in the <tt>include/llvm/CodeGen/MachineInstrBuilder.h</tt> file. The
@ -634,7 +630,7 @@ MI.addReg(Reg, RegState::Define);
<a name="fixedregs">Fixed (preassigned) registers</a> <a name="fixedregs">Fixed (preassigned) registers</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>One important issue that the code generator needs to be aware of is the <p>One important issue that the code generator needs to be aware of is the
presence of fixed registers. In particular, there are often places in the presence of fixed registers. In particular, there are often places in the
@ -706,7 +702,7 @@ ret
<a name="ssa">Machine code in SSA form</a> <a name="ssa">Machine code in SSA form</a>
</h4> </h4>
<div class="doc_text"> <div>
<p><tt>MachineInstr</tt>'s are initially selected in SSA-form, and are <p><tt>MachineInstr</tt>'s are initially selected in SSA-form, and are
maintained in SSA-form until register allocation happens. For the most part, maintained in SSA-form until register allocation happens. For the most part,
@ -719,12 +715,14 @@ ret
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="machinebasicblock">The <tt>MachineBasicBlock</tt> class</a> <a name="machinebasicblock">The <tt>MachineBasicBlock</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>MachineBasicBlock</tt> class contains a list of machine instructions <p>The <tt>MachineBasicBlock</tt> class contains a list of machine instructions
(<tt><a href="#machineinstr">MachineInstr</a></tt> instances). It roughly (<tt><a href="#machineinstr">MachineInstr</a></tt> instances). It roughly
@ -741,7 +739,7 @@ ret
<a name="machinefunction">The <tt>MachineFunction</tt> class</a> <a name="machinefunction">The <tt>MachineFunction</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <tt>MachineFunction</tt> class contains a list of machine basic blocks <p>The <tt>MachineFunction</tt> class contains a list of machine basic blocks
(<tt><a href="#machinebasicblock">MachineBasicBlock</a></tt> instances). It (<tt><a href="#machinebasicblock">MachineBasicBlock</a></tt> instances). It
@ -754,6 +752,7 @@ ret
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -761,7 +760,7 @@ ret
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The MC Layer is used to represent and process code at the raw machine code The MC Layer is used to represent and process code at the raw machine code
@ -779,15 +778,12 @@ of important subsystems that interact at this layer, they are described later
in this manual. in this manual.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="mcstreamer">The <tt>MCStreamer</tt> API</a> <a name="mcstreamer">The <tt>MCStreamer</tt> API</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
MCStreamer is best thought of as an assembler API. It is an abstract API which MCStreamer is best thought of as an assembler API. It is an abstract API which
@ -821,7 +817,7 @@ MCObjectStreamer implements a full assembler.
<a name="mccontext">The <tt>MCContext</tt> class</a> <a name="mccontext">The <tt>MCContext</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The MCContext class is the owner of a variety of uniqued data structures at the The MCContext class is the owner of a variety of uniqued data structures at the
@ -836,7 +832,7 @@ interact with to create symbols and sections. This class can not be subclassed.
<a name="mcsymbol">The <tt>MCSymbol</tt> class</a> <a name="mcsymbol">The <tt>MCSymbol</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The MCSymbol class represents a symbol (aka label) in the assembly file. There The MCSymbol class represents a symbol (aka label) in the assembly file. There
@ -868,7 +864,7 @@ like this to the .s file:<p>
<a name="mcsection">The <tt>MCSection</tt> class</a> <a name="mcsection">The <tt>MCSection</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The MCSection class represents an object-file specific section. It is subclassed The MCSection class represents an object-file specific section. It is subclassed
@ -886,7 +882,7 @@ directive in a .s file).
<a name="mcinst">The <tt>MCInst</tt> class</a> <a name="mcinst">The <tt>MCInst</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The MCInst class is a target-independent representation of an instruction. It The MCInst class is a target-independent representation of an instruction. It
@ -904,6 +900,7 @@ printer, and the type generated by the assembly parser and disassembler.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -911,20 +908,18 @@ printer, and the type generated by the assembly parser and disassembler.
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section documents the phases described in the <p>This section documents the phases described in the
<a href="#high-level-design">high-level design of the code generator</a>. <a href="#high-level-design">high-level design of the code generator</a>.
It explains how they work and some of the rationale behind their design.</p> It explains how they work and some of the rationale behind their design.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="instselect">Instruction Selection</a> <a name="instselect">Instruction Selection</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Instruction Selection is the process of translating LLVM code presented to <p>Instruction Selection is the process of translating LLVM code presented to
the code generator into target-specific machine instructions. There are the code generator into target-specific machine instructions. There are
@ -936,14 +931,12 @@ printer, and the type generated by the assembly parser and disassembler.
selector to be generated from these <tt>.td</tt> files, though currently selector to be generated from these <tt>.td</tt> files, though currently
there are still things that require custom C++ code.</p> there are still things that require custom C++ code.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="selectiondag_intro">Introduction to SelectionDAGs</a> <a name="selectiondag_intro">Introduction to SelectionDAGs</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The SelectionDAG provides an abstraction for code representation in a way <p>The SelectionDAG provides an abstraction for code representation in a way
that is amenable to instruction selection using automatic techniques that is amenable to instruction selection using automatic techniques
@ -1005,7 +998,7 @@ printer, and the type generated by the assembly parser and disassembler.
<a name="selectiondag_process">SelectionDAG Instruction Selection Process</a> <a name="selectiondag_process">SelectionDAG Instruction Selection Process</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>SelectionDAG-based instruction selection consists of the following steps:</p> <p>SelectionDAG-based instruction selection consists of the following steps:</p>
@ -1086,7 +1079,7 @@ printer, and the type generated by the assembly parser and disassembler.
<a name="selectiondag_build">Initial SelectionDAG Construction</a> <a name="selectiondag_build">Initial SelectionDAG Construction</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The initial SelectionDAG is na&iuml;vely peephole expanded from the LLVM <p>The initial SelectionDAG is na&iuml;vely peephole expanded from the LLVM
input by the <tt>SelectionDAGLowering</tt> class in the input by the <tt>SelectionDAGLowering</tt> class in the
@ -1106,7 +1099,7 @@ printer, and the type generated by the assembly parser and disassembler.
<a name="selectiondag_legalize_types">SelectionDAG LegalizeTypes Phase</a> <a name="selectiondag_legalize_types">SelectionDAG LegalizeTypes Phase</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The Legalize phase is in charge of converting a DAG to only use the types <p>The Legalize phase is in charge of converting a DAG to only use the types
that are natively supported by the target.</p> that are natively supported by the target.</p>
@ -1139,7 +1132,7 @@ printer, and the type generated by the assembly parser and disassembler.
<a name="selectiondag_legalize">SelectionDAG Legalize Phase</a> <a name="selectiondag_legalize">SelectionDAG Legalize Phase</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The Legalize phase is in charge of converting a DAG to only use the <p>The Legalize phase is in charge of converting a DAG to only use the
operations that are natively supported by the target.</p> operations that are natively supported by the target.</p>
@ -1173,7 +1166,7 @@ printer, and the type generated by the assembly parser and disassembler.
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The SelectionDAG optimization phase is run multiple times for code <p>The SelectionDAG optimization phase is run multiple times for code
generation, immediately after the DAG is built and once after each generation, immediately after the DAG is built and once after each
@ -1207,7 +1200,7 @@ printer, and the type generated by the assembly parser and disassembler.
<a name="selectiondag_select">SelectionDAG Select Phase</a> <a name="selectiondag_select">SelectionDAG Select Phase</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The Select phase is the bulk of the target-specific code for instruction <p>The Select phase is the bulk of the target-specific code for instruction
selection. This phase takes a legal SelectionDAG as input, pattern matches selection. This phase takes a legal SelectionDAG as input, pattern matches
@ -1368,7 +1361,7 @@ def : Pat&lt;(i32 imm:$imm),
<a name="selectiondag_sched">SelectionDAG Scheduling and Formation Phase</a> <a name="selectiondag_sched">SelectionDAG Scheduling and Formation Phase</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The scheduling phase takes the DAG of target instructions from the selection <p>The scheduling phase takes the DAG of target instructions from the selection
phase and assigns an order. The scheduler can pick an order depending on phase and assigns an order. The scheduler can pick an order depending on
@ -1389,7 +1382,7 @@ def : Pat&lt;(i32 imm:$imm),
<a name="selectiondag_future">Future directions for the SelectionDAG</a> <a name="selectiondag_future">Future directions for the SelectionDAG</a>
</h4> </h4>
<div class="doc_text"> <div>
<ol> <ol>
<li>Optional function-at-a-time selection.</li> <li>Optional function-at-a-time selection.</li>
@ -1399,18 +1392,20 @@ def : Pat&lt;(i32 imm:$imm),
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="ssamco">SSA-based Machine Code Optimizations</a> <a name="ssamco">SSA-based Machine Code Optimizations</a>
</h3> </h3>
<div class="doc_text"><p>To Be Written</p></div> <div><p>To Be Written</p></div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="liveintervals">Live Intervals</a> <a name="liveintervals">Live Intervals</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Live Intervals are the ranges (intervals) where a variable is <i>live</i>. <p>Live Intervals are the ranges (intervals) where a variable is <i>live</i>.
They are used by some <a href="#regalloc">register allocator</a> passes to They are used by some <a href="#regalloc">register allocator</a> passes to
@ -1418,14 +1413,12 @@ def : Pat&lt;(i32 imm:$imm),
register are live at the same point in the program (i.e., they conflict). register are live at the same point in the program (i.e., they conflict).
When this situation occurs, one virtual register must be <i>spilled</i>.</p> When this situation occurs, one virtual register must be <i>spilled</i>.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="livevariable_analysis">Live Variable Analysis</a> <a name="livevariable_analysis">Live Variable Analysis</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The first step in determining the live intervals of variables is to calculate <p>The first step in determining the live intervals of variables is to calculate
the set of registers that are immediately dead after the instruction (i.e., the set of registers that are immediately dead after the instruction (i.e.,
@ -1471,7 +1464,7 @@ def : Pat&lt;(i32 imm:$imm),
<a name="liveintervals_analysis">Live Intervals Analysis</a> <a name="liveintervals_analysis">Live Intervals Analysis</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>We now have the information available to perform the live intervals analysis <p>We now have the information available to perform the live intervals analysis
and build the live intervals themselves. We start off by numbering the basic and build the live intervals themselves. We start off by numbering the basic
@ -1486,12 +1479,14 @@ def : Pat&lt;(i32 imm:$imm),
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="regalloc">Register Allocation</a> <a name="regalloc">Register Allocation</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <i>Register Allocation problem</i> consists in mapping a program <p>The <i>Register Allocation problem</i> consists in mapping a program
<i>P<sub>v</sub></i>, that can use an unbounded number of virtual registers, <i>P<sub>v</sub></i>, that can use an unbounded number of virtual registers,
@ -1501,15 +1496,13 @@ def : Pat&lt;(i32 imm:$imm),
accommodate all the virtual registers, some of them will have to be mapped accommodate all the virtual registers, some of them will have to be mapped
into memory. These virtuals are called <i>spilled virtuals</i>.</p> into memory. These virtuals are called <i>spilled virtuals</i>.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="regAlloc_represent">How registers are represented in LLVM</a> <a name="regAlloc_represent">How registers are represented in LLVM</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In LLVM, physical registers are denoted by integer numbers that normally <p>In LLVM, physical registers are denoted by integer numbers that normally
range from 1 to 1023. To see how this numbering is defined for a particular range from 1 to 1023. To see how this numbering is defined for a particular
@ -1622,7 +1615,7 @@ bool RegMapping_Fer::compatible_class(MachineFunction &amp;mf,
<a name="regAlloc_howTo">Mapping virtual registers to physical registers</a> <a name="regAlloc_howTo">Mapping virtual registers to physical registers</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>There are two ways to map virtual registers to physical registers (or to <p>There are two ways to map virtual registers to physical registers (or to
memory slots). The first way, that we will call <i>direct mapping</i>, is memory slots). The first way, that we will call <i>direct mapping</i>, is
@ -1672,7 +1665,7 @@ bool RegMapping_Fer::compatible_class(MachineFunction &amp;mf,
<a name="regAlloc_twoAddr">Handling two address instructions</a> <a name="regAlloc_twoAddr">Handling two address instructions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>With very rare exceptions (e.g., function calls), the LLVM machine code <p>With very rare exceptions (e.g., function calls), the LLVM machine code
instructions are three address instructions. That is, each instruction is instructions are three address instructions. That is, each instruction is
@ -1708,7 +1701,7 @@ bool RegMapping_Fer::compatible_class(MachineFunction &amp;mf,
<a name="regAlloc_ssaDecon">The SSA deconstruction phase</a> <a name="regAlloc_ssaDecon">The SSA deconstruction phase</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>An important transformation that happens during register allocation is called <p>An important transformation that happens during register allocation is called
the <i>SSA Deconstruction Phase</i>. The SSA form simplifies many analyses the <i>SSA Deconstruction Phase</i>. The SSA form simplifies many analyses
@ -1732,7 +1725,7 @@ bool RegMapping_Fer::compatible_class(MachineFunction &amp;mf,
<a name="regAlloc_fold">Instruction folding</a> <a name="regAlloc_fold">Instruction folding</a>
</h4> </h4>
<div class="doc_text"> <div>
<p><i>Instruction folding</i> is an optimization performed during register <p><i>Instruction folding</i> is an optimization performed during register
allocation that removes unnecessary copy instructions. For instance, a allocation that removes unnecessary copy instructions. For instance, a
@ -1769,7 +1762,7 @@ bool RegMapping_Fer::compatible_class(MachineFunction &amp;mf,
<a name="regAlloc_builtIn">Built in register allocators</a> <a name="regAlloc_builtIn">Built in register allocators</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The LLVM infrastructure provides the application developer with three <p>The LLVM infrastructure provides the application developer with three
different register allocators:</p> different register allocators:</p>
@ -1806,23 +1799,25 @@ $ llc -regalloc=pbqp file.bc -o pbqp.s;
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="proepicode">Prolog/Epilog Code Insertion</a> <a name="proepicode">Prolog/Epilog Code Insertion</a>
</h3> </h3>
<div class="doc_text"><p>To Be Written</p></div> <div><p>To Be Written</p></div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="latemco">Late Machine Code Optimizations</a> <a name="latemco">Late Machine Code Optimizations</a>
</h3> </h3>
<div class="doc_text"><p>To Be Written</p></div> <div><p>To Be Written</p></div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="codeemit">Code Emission</a> <a name="codeemit">Code Emission</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The code emission step of code generation is responsible for lowering from <p>The code emission step of code generation is responsible for lowering from
the code generator abstractions (like <a the code generator abstractions (like <a
@ -1881,6 +1876,7 @@ to implement an assembler for your target.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -1888,7 +1884,7 @@ to implement an assembler for your target.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Though you're probably reading this because you want to write or maintain a <p>Though you're probably reading this because you want to write or maintain a
compiler backend, LLVM also fully supports building a native assemblers too. compiler backend, LLVM also fully supports building a native assemblers too.
@ -1897,12 +1893,10 @@ We've tried hard to automate the generation of the assembler from the .td files
part of the manual and repetitive data entry can be factored and shared with the part of the manual and repetitive data entry can be factored and shared with the
compiler.</p> compiler.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3 id="na_instparsing">Instruction Parsing</h3> <h3 id="na_instparsing">Instruction Parsing</h3>
<div class="doc_text"><p>To Be Written</p></div> <div><p>To Be Written</p></div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
@ -1910,7 +1904,7 @@ compiler.</p>
Instruction Alias Processing Instruction Alias Processing
</h3> </h3>
<div class="doc_text"> <div>
<p>Once the instruction is parsed, it enters the MatchInstructionImpl function. <p>Once the instruction is parsed, it enters the MatchInstructionImpl function.
The MatchInstructionImpl function performs alias processing and then does The MatchInstructionImpl function performs alias processing and then does
actual matching.</p> actual matching.</p>
@ -1923,12 +1917,10 @@ complex/powerful). Generally you want to use the first alias mechanism that
meets the needs of your instruction, because it will allow a more concise meets the needs of your instruction, because it will allow a more concise
description.</p> description.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>Mnemonic Aliases</h4> <h4>Mnemonic Aliases</h4>
<div class="doc_text"> <div>
<p>The first phase of alias processing is simple instruction mnemonic <p>The first phase of alias processing is simple instruction mnemonic
remapping for classes of instructions which are allowed with two different remapping for classes of instructions which are allowed with two different
@ -1968,7 +1960,7 @@ on the current instruction set.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>Instruction Aliases</h4> <h4>Instruction Aliases</h4>
<div class="doc_text"> <div>
<p>The most general phase of alias processing occurs while matching is <p>The most general phase of alias processing occurs while matching is
happening: it provides new forms for the matcher to match along with a specific happening: it provides new forms for the matcher to match along with a specific
@ -2029,15 +2021,14 @@ subtarget specific.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3 id="na_matching">Instruction Matching</h3> <h3 id="na_matching">Instruction Matching</h3>
<div class="doc_text"><p>To Be Written</p></div> <div><p>To Be Written</p></div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -2045,20 +2036,18 @@ subtarget specific.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section of the document explains features or design decisions that are <p>This section of the document explains features or design decisions that are
specific to the code generator for a particular target. First we start specific to the code generator for a particular target. First we start
with a table that summarizes what features are supported by each target.</p> with a table that summarizes what features are supported by each target.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="targetfeatures">Target Feature Matrix</a> <a name="targetfeatures">Target Feature Matrix</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Note that this table does not include the C backend or Cpp backends, since <p>Note that this table does not include the C backend or Cpp backends, since
they do not use the target independent code generator infrastructure. It also they do not use the target independent code generator infrastructure. It also
@ -2229,12 +2218,10 @@ is the key:</p>
</table> </table>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_reliable">Is Generally Reliable</h4> <h4 id="feat_reliable">Is Generally Reliable</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target is considered to be production quality. <p>This box indicates whether the target is considered to be production quality.
This indicates that the target has been used as a static compiler to This indicates that the target has been used as a static compiler to
compile large amounts of code by a variety of different people and is in compile large amounts of code by a variety of different people and is in
@ -2244,7 +2231,7 @@ continuous use.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_asmparser">Assembly Parser</h4> <h4 id="feat_asmparser">Assembly Parser</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target supports parsing target specific .s <p>This box indicates whether the target supports parsing target specific .s
files by implementing the MCAsmParser interface. This is required for llvm-mc files by implementing the MCAsmParser interface. This is required for llvm-mc
to be able to act as a native assembler and is required for inline assembly to be able to act as a native assembler and is required for inline assembly
@ -2256,7 +2243,7 @@ support in the native .o file writer.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_disassembler">Disassembler</h4> <h4 id="feat_disassembler">Disassembler</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target supports the MCDisassembler API for <p>This box indicates whether the target supports the MCDisassembler API for
disassembling machine opcode bytes into MCInst's.</p> disassembling machine opcode bytes into MCInst's.</p>
@ -2265,7 +2252,7 @@ disassembling machine opcode bytes into MCInst's.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_inlineasm">Inline Asm</h4> <h4 id="feat_inlineasm">Inline Asm</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target supports most popular inline assembly <p>This box indicates whether the target supports most popular inline assembly
constraints and modifiers.</p> constraints and modifiers.</p>
@ -2277,7 +2264,7 @@ constraints relating to the X86 floating point stack.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_jit">JIT Support</h4> <h4 id="feat_jit">JIT Support</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target supports the JIT compiler through <p>This box indicates whether the target supports the JIT compiler through
the ExecutionEngine interface.</p> the ExecutionEngine interface.</p>
@ -2289,7 +2276,7 @@ in ARM codegen mode, but lacks NEON and full Thumb support.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_objectwrite">.o File Writing</h4> <h4 id="feat_objectwrite">.o File Writing</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target supports writing .o files (e.g. MachO, <p>This box indicates whether the target supports writing .o files (e.g. MachO,
ELF, and/or COFF) files directly from the target. Note that the target also ELF, and/or COFF) files directly from the target. Note that the target also
@ -2305,7 +2292,7 @@ file to a .o file (as is the case for many C compilers).</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4 id="feat_tailcall">Tail Calls</h4> <h4 id="feat_tailcall">Tail Calls</h4>
<div class="doc_text"> <div>
<p>This box indicates whether the target supports guaranteed tail calls. These <p>This box indicates whether the target supports guaranteed tail calls. These
are calls marked "<a href="LangRef.html#i_call">tail</a>" and use the fastcc are calls marked "<a href="LangRef.html#i_call">tail</a>" and use the fastcc
@ -2314,15 +2301,14 @@ more more details</a>.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="tailcallopt">Tail call optimization</a> <a name="tailcallopt">Tail call optimization</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Tail call optimization, callee reusing the stack of the caller, is currently <p>Tail call optimization, callee reusing the stack of the caller, is currently
supported on x86/x86-64 and PowerPC. It is performed if:</p> supported on x86/x86-64 and PowerPC. It is performed if:</p>
@ -2388,7 +2374,7 @@ define fastcc i32 @tailcaller(i32 %in1, i32 %in2) {
<a name="sibcallopt">Sibling call optimization</a> <a name="sibcallopt">Sibling call optimization</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Sibling call optimization is a restricted form of tail call optimization. <p>Sibling call optimization is a restricted form of tail call optimization.
Unlike tail call optimization described in the previous section, it can be Unlike tail call optimization described in the previous section, it can be
@ -2432,20 +2418,18 @@ entry:
<a name="x86">The X86 backend</a> <a name="x86">The X86 backend</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The X86 code generator lives in the <tt>lib/Target/X86</tt> directory. This <p>The X86 code generator lives in the <tt>lib/Target/X86</tt> directory. This
code generator is capable of targeting a variety of x86-32 and x86-64 code generator is capable of targeting a variety of x86-32 and x86-64
processors, and includes support for ISA extensions such as MMX and SSE.</p> processors, and includes support for ISA extensions such as MMX and SSE.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="x86_tt">X86 Target Triples supported</a> <a name="x86_tt">X86 Target Triples supported</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The following are the known target triples that are supported by the X86 <p>The following are the known target triples that are supported by the X86
backend. This is not an exhaustive list, and it would be useful to add those backend. This is not an exhaustive list, and it would be useful to add those
@ -2475,7 +2459,7 @@ entry:
</h4> </h4>
<div class="doc_text"> <div>
<p>The following target-specific calling conventions are known to backend:</p> <p>The following target-specific calling conventions are known to backend:</p>
@ -2494,7 +2478,7 @@ entry:
<a name="x86_memory">Representing X86 addressing modes in MachineInstrs</a> <a name="x86_memory">Representing X86 addressing modes in MachineInstrs</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The x86 has a very flexible way of accessing memory. It is capable of <p>The x86 has a very flexible way of accessing memory. It is capable of
forming memory addresses of the following expression directly in integer forming memory addresses of the following expression directly in integer
@ -2531,7 +2515,7 @@ OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm PhysReg
<a name="x86_memory">X86 address spaces supported</a> <a name="x86_memory">X86 address spaces supported</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>x86 has a feature which provides <p>x86 has a feature which provides
the ability to perform loads and stores to different address spaces the ability to perform loads and stores to different address spaces
@ -2576,7 +2560,7 @@ OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg, SignExtImm PhysReg
<a name="x86_names">Instruction naming</a> <a name="x86_names">Instruction naming</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>An instruction name consists of the base name, a default operand size, and a <p>An instruction name consists of the base name, a default operand size, and a
a character per operand with an optional special size. For example:</p> a character per operand with an optional special size. For example:</p>
@ -2592,25 +2576,25 @@ MOVSX32rm16 -&gt; movsx, 32-bit register, 16-bit memory
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="ppc">The PowerPC backend</a> <a name="ppc">The PowerPC backend</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The PowerPC code generator lives in the lib/Target/PowerPC directory. The <p>The PowerPC code generator lives in the lib/Target/PowerPC directory. The
code generation is retargetable to several variations or <i>subtargets</i> of code generation is retargetable to several variations or <i>subtargets</i> of
the PowerPC ISA; including ppc32, ppc64 and altivec.</p> the PowerPC ISA; including ppc32, ppc64 and altivec.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="ppc_abi">LLVM PowerPC ABI</a> <a name="ppc_abi">LLVM PowerPC ABI</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC <p>LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC
relative (PIC) or static addressing for accessing global values, so no TOC relative (PIC) or static addressing for accessing global values, so no TOC
@ -2630,7 +2614,7 @@ MOVSX32rm16 -&gt; movsx, 32-bit register, 16-bit memory
<a name="ppc_frame">Frame Layout</a> <a name="ppc_frame">Frame Layout</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The size of a PowerPC frame is usually fixed for the duration of a <p>The size of a PowerPC frame is usually fixed for the duration of a
function's invocation. Since the frame is fixed size, all references function's invocation. Since the frame is fixed size, all references
@ -2777,7 +2761,7 @@ MOVSX32rm16 -&gt; movsx, 32-bit register, 16-bit memory
<a name="ppc_prolog">Prolog/Epilog</a> <a name="ppc_prolog">Prolog/Epilog</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The llvm prolog and epilog are the same as described in the PowerPC ABI, with <p>The llvm prolog and epilog are the same as described in the PowerPC ABI, with
the following exceptions. Callee saved registers are spilled after the frame the following exceptions. Callee saved registers are spilled after the frame
@ -2794,12 +2778,15 @@ MOVSX32rm16 -&gt; movsx, 32-bit register, 16-bit memory
<a name="ppc_dynamic">Dynamic Allocation</a> <a name="ppc_dynamic">Dynamic Allocation</a>
</h4> </h4>
<div class="doc_text"> <div>
<p><i>TODO - More to come.</i></p> <p><i>TODO - More to come.</i></p>
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

93
docs/CodingStandards.html
View File

@ -88,7 +88,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document attempts to describe a few coding standards that are being used <p>This document attempts to describe a few coding standards that are being used
in the LLVM source tree. Although no coding standards should be regarded as in the LLVM source tree. Although no coding standards should be regarded as
@ -122,17 +122,21 @@ href="mailto:sabre@nondot.org">Chris</a>.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="sourceformating">Source Code Formatting</a> <a name="sourceformating">Source Code Formatting</a>
</h3> </h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="scf_commenting">Commenting</a> <a name="scf_commenting">Commenting</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Comments are one critical part of readability and maintainability. Everyone <p>Comments are one critical part of readability and maintainability. Everyone
knows they should comment, so should you. When writing comments, write them as knows they should comment, so should you. When writing comments, write them as
@ -141,7 +145,9 @@ etc. Although we all should probably
comment our code more than we do, there are a few very critical places that comment our code more than we do, there are a few very critical places that
documentation is very useful:</p> documentation is very useful:</p>
<b>File Headers</b> <h5>File Headers</h5>
<div>
<p>Every source file should have a header on it that describes the basic <p>Every source file should have a header on it that describes the basic
purpose of the file. If a file does not have a header, it should not be purpose of the file. If a file does not have a header, it should not be
@ -184,7 +190,9 @@ Here it's only two lines. If an algorithm is being implemented or something
tricky is going on, a reference to the paper where it is published should be tricky is going on, a reference to the paper where it is published should be
included, as well as any notes or "gotchas" in the code to watch out for.</p> included, as well as any notes or "gotchas" in the code to watch out for.</p>
<b>Class overviews</b> </div>
<h5>Class overviews</h5>
<p>Classes are one fundamental part of a good object oriented design. As such, <p>Classes are one fundamental part of a good object oriented design. As such,
a class definition should have a comment block that explains what the class is a class definition should have a comment block that explains what the class is
@ -193,7 +201,9 @@ could figure it out, it's probably safe to leave it out. Naming classes
something sane goes a long ways towards avoiding writing documentation.</p> something sane goes a long ways towards avoiding writing documentation.</p>
<b>Method information</b> <h5>Method information</h5>
<div>
<p>Methods defined in a class (as well as any global functions) should also be <p>Methods defined in a class (as well as any global functions) should also be
documented properly. A quick note about what it does and a description of the documented properly. A quick note about what it does and a description of the
@ -207,12 +217,14 @@ happens: does the method return null? Abort? Format your hard disk?</p>
</div> </div>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="scf_commentformat">Comment Formatting</a> <a name="scf_commentformat">Comment Formatting</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space, <p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
require less typing, don't have nesting problems, etc. There are a few cases require less typing, don't have nesting problems, etc. There are a few cases
@ -237,7 +249,7 @@ These nest properly and are better behaved in general than C style comments.</p>
<a name="scf_includes"><tt>#include</tt> Style</a> <a name="scf_includes"><tt>#include</tt> Style</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and <p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
include guards if working on a header file), the <a include guards if working on a header file), the <a
@ -277,7 +289,7 @@ implements are defined.</p>
<a name="scf_codewidth">Source Code Width</a> <a name="scf_codewidth">Source Code Width</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Write your code to fit within 80 columns of text. This helps those of us who <p>Write your code to fit within 80 columns of text. This helps those of us who
like to print out code and look at your code in an xterm without resizing like to print out code and look at your code in an xterm without resizing
@ -302,7 +314,7 @@ for debate.</p>
<a name="scf_spacestabs">Use Spaces Instead of Tabs</a> <a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In all cases, prefer spaces to tabs in source files. People have different <p>In all cases, prefer spaces to tabs in source files. People have different
preferred indentation levels, and different styles of indentation that they preferred indentation levels, and different styles of indentation that they
@ -323,7 +335,7 @@ makes for incredible diffs that are absolutely worthless.</p>
<a name="scf_indentation">Indent Code Consistently</a> <a name="scf_indentation">Indent Code Consistently</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Okay, in your first year of programming you were told that indentation is <p>Okay, in your first year of programming you were told that indentation is
important. If you didn't believe and internalize this then, now is the time. important. If you didn't believe and internalize this then, now is the time.
@ -331,19 +343,21 @@ Just do it.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="compilerissues">Compiler Issues</a> <a name="compilerissues">Compiler Issues</a>
</h3> </h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a> <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>If your code has compiler warnings in it, something is wrong &mdash; you <p>If your code has compiler warnings in it, something is wrong &mdash; you
aren't casting values correctly, your have "questionable" constructs in your aren't casting values correctly, your have "questionable" constructs in your
@ -397,7 +411,7 @@ be fixed by massaging the code appropriately.</p>
<a name="ci_portable_code">Write Portable Code</a> <a name="ci_portable_code">Write Portable Code</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In almost all cases, it is possible and within reason to write completely <p>In almost all cases, it is possible and within reason to write completely
portable code. If there are cases where it isn't possible to write portable portable code. If there are cases where it isn't possible to write portable
@ -415,7 +429,7 @@ libSystem.</p>
<h4> <h4>
<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a> <a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In an effort to reduce code and executable size, LLVM does not use RTTI <p>In an effort to reduce code and executable size, LLVM does not use RTTI
(e.g. <tt>dynamic_cast&lt;&gt;</tt>) or exceptions. These two language features (e.g. <tt>dynamic_cast&lt;&gt;</tt>) or exceptions. These two language features
@ -436,7 +450,7 @@ than <tt>dynamic_cast&lt;&gt;</tt>.</p>
<h4> <h4>
<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a> <a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost <p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
interchangeably. The only difference is when they are used to declare a class: interchangeably. The only difference is when they are used to declare a class:
@ -454,12 +468,17 @@ which case <tt>struct</tt> is allowed.</p>
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="styleissues">Style Issues</a> <a name="styleissues">Style Issues</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
@ -467,13 +486,14 @@ which case <tt>struct</tt> is allowed.</p>
</h3> </h3>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="hl_module">A Public Header File <b>is</b> a Module</a> <a name="hl_module">A Public Header File <b>is</b> a Module</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>C++ doesn't do too well in the modularity department. There is no real <p>C++ doesn't do too well in the modularity department. There is no real
encapsulation or data hiding (unless you use expensive protocol classes), but it encapsulation or data hiding (unless you use expensive protocol classes), but it
@ -503,7 +523,7 @@ translation unit.</p>
<a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a> <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
</h4> </h4>
<div class="doc_text"> <div>
<p><tt>#include</tt> hurts compile time performance. Don't do it unless you <p><tt>#include</tt> hurts compile time performance. Don't do it unless you
have to, especially in header files.</p> have to, especially in header files.</p>
@ -532,7 +552,7 @@ dependencies that you'll find out about later.</p>
<a name="hl_privateheaders">Keep "Internal" Headers Private</a> <a name="hl_privateheaders">Keep "Internal" Headers Private</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Many modules have a complex implementation that causes them to use more than <p>Many modules have a complex implementation that causes them to use more than
one implementation (<tt>.cpp</tt>) file. It is often tempting to put the one implementation (<tt>.cpp</tt>) file. It is often tempting to put the
@ -553,7 +573,7 @@ class itself. Just make them private (or protected) and all is well.</p>
<a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a> <a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>When reading code, keep in mind how much state and how many previous <p>When reading code, keep in mind how much state and how many previous
decisions have to be remembered by the reader to understand a block of code. decisions have to be remembered by the reader to understand a block of code.
@ -662,7 +682,7 @@ can be a big understandability win.</p>
<a name="hl_else_after_return">Don't use <tt>else</tt> after a <tt>return</tt></a> <a name="hl_else_after_return">Don't use <tt>else</tt> after a <tt>return</tt></a>
</h4> </h4>
<div class="doc_text"> <div>
<p>For similar reasons above (reduction of indentation and easier reading), <p>For similar reasons above (reduction of indentation and easier reading),
please do not use '<tt>else</tt>' or '<tt>else if</tt>' after something that please do not use '<tt>else</tt>' or '<tt>else if</tt>' after something that
@ -745,7 +765,7 @@ track of when reading the code.</p>
<a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a> <a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>It is very common to write small loops that just compute a boolean value. <p>It is very common to write small loops that just compute a boolean value.
There are a number of ways that people commonly write these, but an example of There are a number of ways that people commonly write these, but an example of
@ -802,6 +822,7 @@ locality.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
@ -809,6 +830,7 @@ locality.</p>
</h3> </h3>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
@ -817,7 +839,7 @@ locality.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress <p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
enough how important it is to use <em>descriptive</em> names. Pick names that enough how important it is to use <em>descriptive</em> names. Pick names that
@ -900,7 +922,7 @@ Vehicle MakeVehicle(VehicleType Type) {
<a name="ll_assert">Assert Liberally</a> <a name="ll_assert">Assert Liberally</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Use the "<tt>assert</tt>" macro to its fullest. Check all of your <p>Use the "<tt>assert</tt>" macro to its fullest. Check all of your
preconditions and assumptions, you never know when a bug (not necessarily even preconditions and assumptions, you never know when a bug (not necessarily even
@ -1003,7 +1025,7 @@ assert(NewToSet &amp;&amp; "The value shouldn't be in the set yet");
<a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a> <a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard <p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
namespace with an "<tt>std::</tt>" prefix, rather than rely on namespace with an "<tt>std::</tt>" prefix, rather than rely on
@ -1043,7 +1065,7 @@ use any others.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<p>If a class is defined in a header file and has a v-table (either it has <p>If a class is defined in a header file and has a v-table (either it has
virtual methods or it derives from classes with virtual methods), it must virtual methods or it derives from classes with virtual methods), it must
@ -1059,7 +1081,7 @@ increasing link times.</p>
<a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a> <a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Because C++ doesn't have a standard "<tt>foreach</tt>" loop (though it can be <p>Because C++ doesn't have a standard "<tt>foreach</tt>" loop (though it can be
emulated with macros and may be coming in C++'0x) we end up writing a lot of emulated with macros and may be coming in C++'0x) we end up writing a lot of
@ -1121,7 +1143,7 @@ prefer it.</p>
<a name="ll_iostream"><tt>#include &lt;iostream&gt;</tt> is Forbidden</a> <a name="ll_iostream"><tt>#include &lt;iostream&gt;</tt> is Forbidden</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The use of <tt>#include &lt;iostream&gt;</tt> in library files is <p>The use of <tt>#include &lt;iostream&gt;</tt> in library files is
hereby <b><em>forbidden</em></b>. The primary reason for doing this is to hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
@ -1156,7 +1178,7 @@ the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p>
<a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a> <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
</h4> </h4>
<div class="doc_text"> <div>
<p>LLVM includes a lightweight, simple, and efficient stream implementation <p>LLVM includes a lightweight, simple, and efficient stream implementation
in <tt>llvm/Support/raw_ostream.h</tt>, which provides all of the common in <tt>llvm/Support/raw_ostream.h</tt>, which provides all of the common
@ -1176,7 +1198,7 @@ declarations and constant references to <tt>raw_ostream</tt> instances.</p>
<a name="ll_avoidendl">Avoid <tt>std::endl</tt></a> <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>std::endl</tt> modifier, when used with <tt>iostreams</tt> outputs a <p>The <tt>std::endl</tt> modifier, when used with <tt>iostreams</tt> outputs a
newline to the output stream specified. In addition to doing this, however, it newline to the output stream specified. In addition to doing this, however, it
@ -1194,6 +1216,7 @@ it's better to use a literal <tt>'\n'</tt>.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
@ -1201,6 +1224,8 @@ it's better to use a literal <tt>'\n'</tt>.</p>
</h3> </h3>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div>
<p>This section describes preferred low-level formatting guidelines along with <p>This section describes preferred low-level formatting guidelines along with
reasoning on why we prefer them.</p> reasoning on why we prefer them.</p>
@ -1209,7 +1234,7 @@ reasoning on why we prefer them.</p>
<a name="micro_spaceparen">Spaces Before Parentheses</a> <a name="micro_spaceparen">Spaces Before Parentheses</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>We prefer to put a space before an open parenthesis only in control flow <p>We prefer to put a space before an open parenthesis only in control flow
statements, but not in normal function call expressions and function-like statements, but not in normal function call expressions and function-like
@ -1267,7 +1292,7 @@ this misinterpretation.</p>
<a name="micro_preincrement">Prefer Preincrement</a> <a name="micro_preincrement">Prefer Preincrement</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than <p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
@ -1287,7 +1312,7 @@ get in the habit of always using preincrement, and you won't have a problem.</p>
<a name="micro_namespaceindent">Namespace Indentation</a> <a name="micro_namespaceindent">Namespace Indentation</a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
In general, we strive to reduce indentation wherever possible. This is useful In general, we strive to reduce indentation wherever possible. This is useful
@ -1375,7 +1400,7 @@ the contents of the namespace.</p>
<a name="micro_anonns">Anonymous Namespaces</a> <a name="micro_anonns">Anonymous Namespaces</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>After talking about namespaces in general, you may be wondering about <p>After talking about namespaces in general, you may be wondering about
anonymous namespaces in particular. anonymous namespaces in particular.
@ -1455,7 +1480,9 @@ namespace just because it was declared there.
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -1463,7 +1490,7 @@ namespace just because it was declared there.
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>A lot of these comments and recommendations have been culled for other <p>A lot of these comments and recommendations have been culled for other
sources. Two particularly important books for our work are:</p> sources. Two particularly important books for our work are:</p>

10
docs/CommandGuide/index.html
View File

@ -11,7 +11,7 @@
LLVM Command Guide LLVM Command Guide
</h1> </h1>
<div class="doc_text"> <div>
<p>These documents are HTML versions of the <a href="man/man1/">man pages</a> <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 for all of the LLVM tools. These pages describe how to use the LLVM commands
@ -28,7 +28,7 @@ options) arguments to the tool you are interested in.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<ul> <ul>
@ -85,7 +85,7 @@ options) arguments to the tool you are interested in.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="/cmds/llvmgcc.html"><b>llvm-gcc</b></a> - <li><a href="/cmds/llvmgcc.html"><b>llvm-gcc</b></a> -
@ -105,7 +105,7 @@ options) arguments to the tool you are interested in.</p>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<ul> <ul>
@ -128,7 +128,7 @@ options) arguments to the tool you are interested in.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="/cmds/FileCheck.html"><b>FileCheck</b></a> - <li><a href="/cmds/FileCheck.html"><b>FileCheck</b></a> -

97
docs/CommandLine.html
View File

@ -105,7 +105,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document describes the CommandLine argument processing library. It will <p>This document describes the CommandLine argument processing library. It will
show you how to use it, and what it can do. The CommandLine library uses a show you how to use it, and what it can do. The CommandLine library uses a
@ -189,7 +189,7 @@ href="mailto:sabre@nondot.org">Chris Lattner</a>.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section of the manual runs through a simple CommandLine'ification of a <p>This section of the manual runs through a simple CommandLine'ification of a
basic compiler tool. This is intended to show you how to jump into using the basic compiler tool. This is intended to show you how to jump into using the
@ -321,14 +321,12 @@ OPTIONS:
<p>... indicating that an input filename is expected.</p> <p>... indicating that an input filename is expected.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="bool">Boolean Arguments</a> <a name="bool">Boolean Arguments</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>In addition to input and output filenames, we would like the compiler example <p>In addition to input and output filenames, we would like the compiler example
to support three boolean flags: "<tt>-f</tt>" to force writing binary output to to support three boolean flags: "<tt>-f</tt>" to force writing binary output to
@ -410,7 +408,7 @@ and <a href="#list">lists</a> of options.</p>
<a name="alias">Argument Aliases</a> <a name="alias">Argument Aliases</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>So far, the example works well, except for the fact that we need to check the <p>So far, the example works well, except for the fact that we need to check the
quiet condition like this now:</p> quiet condition like this now:</p>
@ -461,7 +459,7 @@ uses.</p>
possibilities</a> possibilities</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>So far we have seen how the CommandLine library handles builtin types like <p>So far we have seen how the CommandLine library handles builtin types like
<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle <tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
@ -571,7 +569,7 @@ which is when you would use it.</p>
<a name="namedalternatives">Named Alternatives</a> <a name="namedalternatives">Named Alternatives</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Another useful argument form is a named alternative style. We shall use this <p>Another useful argument form is a named alternative style. We shall use this
style in our compiler to specify different debug levels that can be used. style in our compiler to specify different debug levels that can be used.
@ -633,7 +631,7 @@ that you can choose the form most appropriate for your application.</p>
<a name="list">Parsing a list of options</a> <a name="list">Parsing a list of options</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Now that we have the standard run-of-the-mill argument types out of the way, <p>Now that we have the standard run-of-the-mill argument types out of the way,
lets get a little wild and crazy. Lets say that we want our optimizer to accept lets get a little wild and crazy. Lets say that we want our optimizer to accept
@ -703,7 +701,7 @@ checking we have to do.</p>
<a name="bits">Collecting options as a set of flags</a> <a name="bits">Collecting options as a set of flags</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Instead of collecting sets of options in a list, it is also possible to <p>Instead of collecting sets of options in a list, it is also possible to
gather information for enum values in a <b>bit vector</b>. The representation used by gather information for enum values in a <b>bit vector</b>. The representation used by
@ -762,7 +760,7 @@ href="#list"> <tt>cl::list</tt></a> option.</p>
<a name="description">Adding freeform text to help output</a> <a name="description">Adding freeform text to help output</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>As our program grows and becomes more mature, we may decide to put summary <p>As our program grows and becomes more mature, we may decide to put summary
information about what it does into the help output. The help output is styled information about what it does into the help output. The help output is styled
@ -800,6 +798,7 @@ OPTIONS:
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -807,21 +806,19 @@ OPTIONS:
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that you know the basics of how to use the CommandLine library, this <p>Now that you know the basics of how to use the CommandLine library, this
section will give you the detailed information you need to tune how command line section will give you the detailed information you need to tune how command line
options work, as well as information on more "advanced" command line option options work, as well as information on more "advanced" command line option
processing capabilities.</p> processing capabilities.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="positional">Positional Arguments</a> <a name="positional">Positional Arguments</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Positional arguments are those arguments that are not named, and are not <p>Positional arguments are those arguments that are not named, and are not
specified with a hyphen. Positional arguments should be used when an option is specified with a hyphen. Positional arguments should be used when an option is
@ -854,15 +851,12 @@ that command line options will be ordered according to how they are listed in a
are defined in multiple .cpp files. The fix for this problem is simply to are defined in multiple .cpp files. The fix for this problem is simply to
define all of your positional arguments in one .cpp file.</p> define all of your positional arguments in one .cpp file.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="--">Specifying positional options with hyphens</a> <a name="--">Specifying positional options with hyphens</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Sometimes you may want to specify a value to your positional argument that <p>Sometimes you may want to specify a value to your positional argument that
starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
@ -898,7 +892,7 @@ can use it like this:</p>
<h4> <h4>
<a name="getPosition">Determining absolute position with getPosition()</a> <a name="getPosition">Determining absolute position with getPosition()</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Sometimes an option can affect or modify the meaning of another option. For <p>Sometimes an option can affect or modify the meaning of another option. For
example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
<tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force <tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
@ -958,7 +952,7 @@ can use it like this:</p>
<a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a> <a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is <p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
used to construct programs that use "interpreter style" option processing. With used to construct programs that use "interpreter style" option processing. With
@ -1006,12 +1000,14 @@ href="#cl::list">cl::list</a> option.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="storage">Internal vs External Storage</a> <a name="storage">Internal vs External Storage</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>By default, all command line options automatically hold the value that they <p>By default, all command line options automatically hold the value that they
parse from the command line. This is very convenient in the common case, parse from the command line. This is very convenient in the common case,
@ -1080,7 +1076,7 @@ that <tt>DebugFlag</tt> is automatically set.</p>
<a name="attributes">Option Attributes</a> <a name="attributes">Option Attributes</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This section describes the basic attributes that you can specify on <p>This section describes the basic attributes that you can specify on
options.</p> options.</p>
@ -1170,7 +1166,7 @@ obviously).</li>
<a name="modifiers">Option Modifiers</a> <a name="modifiers">Option Modifiers</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Option modifiers are the flags and expressions that you pass into the <p>Option modifiers are the flags and expressions that you pass into the
constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
@ -1196,14 +1192,12 @@ category. The CommandLine library specifies defaults for all of these settings
that are the most useful in practice and the most common, which mean that you that are the most useful in practice and the most common, which mean that you
usually shouldn't have to worry about these.</p> usually shouldn't have to worry about these.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="hiding">Hiding an option from <tt>-help</tt> output</a> <a name="hiding">Hiding an option from <tt>-help</tt> output</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and <p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option <tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
@ -1235,7 +1229,7 @@ indicates that the option should not appear in any help output.</li>
allowed</a> allowed</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>This group of options is used to control how many time an option is allowed <p>This group of options is used to control how many time an option is allowed
(or required) to be specified on the command line of your program. Specifying a (or required) to be specified on the command line of your program. Specifying a
@ -1283,7 +1277,7 @@ retained.</p>
<a name="valrequired">Controlling whether or not a value must be specified</a> <a name="valrequired">Controlling whether or not a value must be specified</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>This group of options is used to control whether or not the option allows a <p>This group of options is used to control whether or not the option allows a
value to be present. In the case of the CommandLine library, a value is either value to be present. In the case of the CommandLine library, a value is either
@ -1332,7 +1326,7 @@ when <a href="#extensionguide">extending the library</a>.</p>
<a name="formatting">Controlling other formatting options</a> <a name="formatting">Controlling other formatting options</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The formatting option group is used to specify that the command line option <p>The formatting option group is used to specify that the command line option
has special abilities and is otherwise different from other command line has special abilities and is otherwise different from other command line
@ -1413,7 +1407,7 @@ strategy basically looks like this:</p>
<a name="misc">Miscellaneous option modifiers</a> <a name="misc">Miscellaneous option modifiers</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The miscellaneous option modifiers are the only flags where you can specify <p>The miscellaneous option modifiers are the only flags where you can specify
more than one flag from the set: they are not mutually exclusive. These flags more than one flag from the set: they are not mutually exclusive. These flags
@ -1457,7 +1451,7 @@ only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
<a name="response">Response files</a> <a name="response">Response files</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Some systems, such as certain variants of Microsoft Windows and <p>Some systems, such as certain variants of Microsoft Windows and
some older Unices have a relatively low limit on command-line some older Unices have a relatively low limit on command-line
@ -1474,13 +1468,14 @@ and
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="toplevel">Top-Level Classes and Functions</a> <a name="toplevel">Top-Level Classes and Functions</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Despite all of the built-in flexibility, the CommandLine option library <p>Despite all of the built-in flexibility, the CommandLine option library
really only consists of one function (<a really only consists of one function (<a
@ -1490,15 +1485,13 @@ href="#cl::list"><tt>cl::list</tt></a>, and <a
href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
classes in detail.</p> classes in detail.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt> <a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
function</a> function</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called <p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
directly from <tt>main</tt>, and is used to fill in the values of all of the directly from <tt>main</tt>, and is used to fill in the values of all of the
@ -1519,7 +1512,7 @@ which holds <a href="#description">additional extra text</a> to emit when the
function</a> function</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects <p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
as <a as <a
@ -1556,7 +1549,7 @@ input.</p>
function</a> function</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called <p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
directly from <tt>main</tt> and <i>before</i> directly from <tt>main</tt> and <i>before</i>
@ -1576,7 +1569,7 @@ called when the <tt>--version</tt> option is given by the user.</p>
<a name="cl::opt">The <tt>cl::opt</tt> class</a> <a name="cl::opt">The <tt>cl::opt</tt> class</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::opt</tt> class is the class used to represent scalar command line <p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
options, and is the one used most of the time. It is a templated class which options, and is the one used most of the time. It is a templated class which
@ -1611,7 +1604,7 @@ href="#customparser">custom parser</a>.</p>
<a name="cl::list">The <tt>cl::list</tt> class</a> <a name="cl::list">The <tt>cl::list</tt> class</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::list</tt> class is the class used to represent a list of command <p>The <tt>cl::list</tt> class is the class used to represent a list of command
line options. It too is a templated class which can take up to three line options. It too is a templated class which can take up to three
@ -1638,7 +1631,7 @@ be used.</p>
<a name="cl::bits">The <tt>cl::bits</tt> class</a> <a name="cl::bits">The <tt>cl::bits</tt> class</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::bits</tt> class is the class used to represent a list of command <p>The <tt>cl::bits</tt> class is the class used to represent a list of command
line options in the form of a bit vector. It is also a templated class which line options in the form of a bit vector. It is also a templated class which
@ -1663,7 +1656,7 @@ must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
<a name="cl::alias">The <tt>cl::alias</tt> class</a> <a name="cl::alias">The <tt>cl::alias</tt> class</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form <p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
aliases for other arguments.</p> aliases for other arguments.</p>
@ -1686,7 +1679,7 @@ the conversion from string to data.</p>
<a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a> <a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra <p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
help text to be printed out for the <tt>-help</tt> option.</p> help text to be printed out for the <tt>-help</tt> option.</p>
@ -1709,12 +1702,14 @@ single <tt>cl::extrahelp</tt> instance.</p>
</pre></div> </pre></div>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="builtinparsers">Builtin parsers</a> <a name="builtinparsers">Builtin parsers</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Parsers control how the string value taken from the command line is <p>Parsers control how the string value taken from the command line is
translated into a typed value, suitable for use in a C++ program. By default, translated into a typed value, suitable for use in a C++ program. By default,
@ -1773,27 +1768,27 @@ exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="extensionguide">Extension Guide</a> <a name="extensionguide">Extension Guide</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Although the CommandLine library has a lot of functionality built into it <p>Although the CommandLine library has a lot of functionality built into it
already (as discussed previously), one of its true strengths lie in its already (as discussed previously), one of its true strengths lie in its
extensibility. This section discusses how the CommandLine library works under extensibility. This section discusses how the CommandLine library works under
the covers and illustrates how to do some simple, common, extensions.</p> the covers and illustrates how to do some simple, common, extensions.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="customparser">Writing a custom parser</a> <a name="customparser">Writing a custom parser</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>One of the simplest and most common extensions is the use of a custom parser. <p>One of the simplest and most common extensions is the use of a custom parser.
As <a href="#builtinparsers">discussed previously</a>, parsers are the portion As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
@ -1936,7 +1931,7 @@ tutorial.</p>
<a name="explotingexternal">Exploiting external storage</a> <a name="explotingexternal">Exploiting external storage</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that <p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
will automatically be included in any program that links with that library. will automatically be included in any program that links with that library.
This is a feature. However, sometimes it is necessary to know the value of the This is a feature. However, sometimes it is necessary to know the value of the
@ -1955,12 +1950,14 @@ tutorial.</p>
<a name="dynamicopts">Dynamically adding command line options</a> <a name="dynamicopts">Dynamically adding command line options</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>TODO: fill in this section</p> <p>TODO: fill in this section</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

42
docs/CompilerWriterInfo.html
View File

@ -46,10 +46,12 @@
<h2><a name="hw">Hardware</a></h2> <h2><a name="hw">Hardware</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="alpha">Alpha</a></h3> <h3><a name="alpha">Alpha</a></h3>
<div class="doc_text"> <div>
<ul> <ul>
<li><a <li><a
href="http://ftp.digital.com/pub/Digital/info/semiconductor/literature/dsc-library.html">Alpha manuals</a> href="http://ftp.digital.com/pub/Digital/info/semiconductor/literature/dsc-library.html">Alpha manuals</a>
@ -60,7 +62,7 @@ href="http://ftp.digital.com/pub/Digital/info/semiconductor/literature/dsc-libra
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="arm">ARM</a></h3> <h3><a name="arm">ARM</a></h3>
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="http://www.arm.com/documentation/">ARM documentation</a> <li><a href="http://www.arm.com/documentation/">ARM documentation</a>
(<a href="http://www.arm.com/documentation/ARMProcessor_Cores/">Processor (<a href="http://www.arm.com/documentation/ARMProcessor_Cores/">Processor
@ -72,7 +74,7 @@ Cores</a>)</li>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="ia64">Itanium (ia64)</a></h3> <h3><a name="ia64">Itanium (ia64)</a></h3>
<div class="doc_text"> <div>
<ul> <ul>
<li><a <li><a
href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a> href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a>
@ -83,7 +85,7 @@ href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium docu
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="mips">MIPS</a></h3> <h3><a name="mips">MIPS</a></h3>
<div class="doc_text"> <div>
<ul> <ul>
<li><a <li><a
href="http://mips.com/content/Documentation/MIPSDocumentation/ProcessorArchitecture/doclibrary">MIPS href="http://mips.com/content/Documentation/MIPSDocumentation/ProcessorArchitecture/doclibrary">MIPS
@ -94,10 +96,12 @@ Processor Architecture</a></li>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="ppc">PowerPC</a></h3> <h3><a name="ppc">PowerPC</a></h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>IBM - Official manuals and docs</h4> <h4>IBM - Official manuals and docs</h4>
<div class="doc_text"> <div>
<ul> <ul>
<li><a <li><a
@ -131,7 +135,7 @@ PowerPC architecture</a></li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>Other documents, collections, notes</h4> <h4>Other documents, collections, notes</h4>
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li> <li><a href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
@ -143,10 +147,12 @@ branch stubs for powerpc64-linux (from binutils)</a></li>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="sparc">SPARC</a></h3> <h3><a name="sparc">SPARC</a></h3>
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="http://www.sparc.org/resource.htm">SPARC resources</a></li> <li><a href="http://www.sparc.org/resource.htm">SPARC resources</a></li>
@ -158,10 +164,12 @@ branch stubs for powerpc64-linux (from binutils)</a></li>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="x86">X86</a></h3> <h3><a name="x86">X86</a></h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>AMD - Official manuals and docs</h4> <h4>AMD - Official manuals and docs</h4>
<div class="doc_text"> <div>
<ul> <ul>
<li><a <li><a
href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.html">AMD processor manuals</a></li> href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.html">AMD processor manuals</a></li>
@ -172,7 +180,7 @@ href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.ht
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>Intel - Official manuals and docs</h4> <h4>Intel - Official manuals and docs</h4>
<div class="doc_text"> <div>
<ul> <ul>
<li><a <li><a
href="http://developer.intel.com/design/pentium4/manuals/index_new.htm">IA-32 href="http://developer.intel.com/design/pentium4/manuals/index_new.htm">IA-32
@ -186,17 +194,19 @@ Itanium documentation</a></li>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4>Other x86-specific information</h4> <h4>Other x86-specific information</h4>
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="http://www.agner.org/assem/calling_conventions.pdf">Calling <li><a href="http://www.agner.org/assem/calling_conventions.pdf">Calling
conventions for different C++ compilers and operating systems</a></li> conventions for different C++ compilers and operating systems</a></li>
</ul> </ul>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="other">Other relevant lists</a></h3> <h3><a name="other">Other relevant lists</a></h3>
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="http://gcc.gnu.org/readings.html">GCC reading list</a></li> <li><a href="http://gcc.gnu.org/readings.html">GCC reading list</a></li>
@ -204,14 +214,18 @@ conventions for different C++ compilers and operating systems</a></li>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="abi">ABI</a></h2> <h2><a name="abi">ABI</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="linux">Linux</a></h3> <h3><a name="linux">Linux</a></h3>
<div class="doc_text"> <div>
<ol> <ol>
<li><a href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI <li><a href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI
Supplement</a></li> Supplement</a></li>
@ -221,7 +235,7 @@ Supplement</a></li>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="osx">OS X</a></h3> <h3><a name="osx">OS X</a></h3>
<div class="doc_text"> <div>
<ol> <ol>
<li><a <li><a
href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O
@ -232,6 +246,8 @@ ABI</a></li>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="misc">Miscellaneous resources</a></h2> <h2><a name="misc">Miscellaneous resources</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->

4
docs/DebuggingJITedCode.html
View File

@ -17,7 +17,7 @@
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="example">Example usage</a></h2> <h2><a name="example">Example usage</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>In order to debug code JITed by LLVM, you need GDB 7.0 or newer, which is <p>In order to debug code JITed by LLVM, you need GDB 7.0 or newer, which is
available on most modern distributions of Linux. The version of GDB that Apple available on most modern distributions of Linux. The version of GDB that Apple
@ -98,7 +98,7 @@ function names.
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="background">Background</a></h2> <h2><a name="background">Background</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>Without special runtime support, debugging dynamically generated code with <p>Without special runtime support, debugging dynamically generated code with
GDB (as well as most debuggers) can be quite painful. Debuggers generally read GDB (as well as most debuggers) can be quite painful. Debuggers generally read

38
docs/DeveloperPolicy.html
View File

@ -36,7 +36,7 @@
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>This document contains the LLVM Developer Policy which defines the project's <p>This document contains the LLVM Developer Policy which defines the project's
policy towards developers and their contributions. The intent of this policy policy towards developers and their contributions. The intent of this policy
is to eliminate miscommunication, rework, and confusion that might arise from is to eliminate miscommunication, rework, and confusion that might arise from
@ -65,18 +65,17 @@
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="policies">Developer Policies</a></h2> <h2><a name="policies">Developer Policies</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>This section contains policies that pertain to frequent LLVM developers. We <p>This section contains policies that pertain to frequent LLVM developers. We
always welcome <a href="#patches">one-off patches</a> from people who do not always welcome <a href="#patches">one-off patches</a> from people who do not
routinely contribute to LLVM, but we expect more from frequent contributors routinely contribute to LLVM, but we expect more from frequent contributors
to keep the system as efficient as possible for everyone. Frequent LLVM to keep the system as efficient as possible for everyone. Frequent LLVM
contributors are expected to meet the following requirements in order for contributors are expected to meet the following requirements in order for
LLVM to maintain a high standard of quality.<p> LLVM to maintain a high standard of quality.<p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="informed">Stay Informed</a></h3> <h3><a name="informed">Stay Informed</a></h3>
<div class="doc_text"> <div>
<p>Developers should stay informed by reading at least the "dev" mailing list <p>Developers should stay informed by reading at least the "dev" mailing list
for the projects you are interested in, such as for the projects you are interested in, such as
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> for <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> for
@ -104,7 +103,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="patches">Making a Patch</a></h3> <h3><a name="patches">Making a Patch</a></h3>
<div class="doc_text"> <div>
<p>When making a patch for review, the goal is to make it as easy for the <p>When making a patch for review, the goal is to make it as easy for the
reviewer to read it as possible. As such, we recommend that you:</p> reviewer to read it as possible. As such, we recommend that you:</p>
@ -143,7 +142,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="reviews">Code Reviews</a></h3> <h3><a name="reviews">Code Reviews</a></h3>
<div class="doc_text"> <div>
<p>LLVM has a code review policy. Code review is one way to increase the quality <p>LLVM has a code review policy. Code review is one way to increase the quality
of software. We generally follow these policies:</p> of software. We generally follow these policies:</p>
@ -175,7 +174,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="owners">Code Owners</a></h3> <h3><a name="owners">Code Owners</a></h3>
<div class="doc_text"> <div>
<p>The LLVM Project relies on two features of its process to maintain rapid <p>The LLVM Project relies on two features of its process to maintain rapid
development in addition to the high quality of its source base: the development in addition to the high quality of its source base: the
@ -226,7 +225,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="testcases">Test Cases</a></h3> <h3><a name="testcases">Test Cases</a></h3>
<div class="doc_text"> <div>
<p>Developers are required to create test cases for any bugs fixed and any new <p>Developers are required to create test cases for any bugs fixed and any new
features added. Some tips for getting your testcase approved:</p> features added. Some tips for getting your testcase approved:</p>
@ -259,7 +258,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="quality">Quality</a></h3> <h3><a name="quality">Quality</a></h3>
<div class="doc_text"> <div>
<p>The minimum quality standards that any change must satisfy before being <p>The minimum quality standards that any change must satisfy before being
committed to the main development branch are:</p> committed to the main development branch are:</p>
@ -319,7 +318,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="commitaccess">Obtaining Commit Access</a></h3> <h3><a name="commitaccess">Obtaining Commit Access</a></h3>
<div class="doc_text"> <div>
<p>We grant commit access to contributors with a track record of submitting high <p>We grant commit access to contributors with a track record of submitting high
quality patches. If you would like commit access, please send an email to quality patches. If you would like commit access, please send an email to
@ -381,7 +380,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="newwork">Making a Major Change</a></h3> <h3><a name="newwork">Making a Major Change</a></h3>
<div class="doc_text"> <div>
<p>When a developer begins a major new project with the aim of contributing it <p>When a developer begins a major new project with the aim of contributing it
back to LLVM, s/he should inform the community with an email to back to LLVM, s/he should inform the community with an email to
the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a>
@ -410,7 +409,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="incremental">Incremental Development</a></h3> <h3><a name="incremental">Incremental Development</a></h3>
<div class="doc_text"> <div>
<p>In the LLVM project, we do all significant changes as a series of incremental <p>In the LLVM project, we do all significant changes as a series of incremental
patches. We have a strong dislike for huge changes or long-term development patches. We have a strong dislike for huge changes or long-term development
branches. Long-term development branches have a number of drawbacks:</p> branches. Long-term development branches have a number of drawbacks:</p>
@ -471,7 +470,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="attribution">Attribution of Changes</a></h3> <h3><a name="attribution">Attribution of Changes</a></h3>
<div class="doc_text"> <div>
<p>We believe in correct attribution of contributions to their contributors. <p>We believe in correct attribution of contributions to their contributors.
However, we do not want the source code to be littered with random However, we do not want the source code to be littered with random
attributions "this code written by J. Random Hacker" (this is noisy and attributions "this code written by J. Random Hacker" (this is noisy and
@ -483,13 +482,15 @@
<p>Overall, please do not add contributor names to the source code.</p> <p>Overall, please do not add contributor names to the source code.</p>
</div> </div>
</div>
<!--=========================================================================--> <!--=========================================================================-->
<h2> <h2>
<a name="clp">Copyright, License, and Patents</a> <a name="clp">Copyright, License, and Patents</a>
</h2> </h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>This section addresses the issues of copyright, license and patents for the <p>This section addresses the issues of copyright, license and patents for the
LLVM project. Currently, the University of Illinois is the LLVM copyright LLVM project. Currently, the University of Illinois is the LLVM copyright
holder and the terms of its license to LLVM users and developers is the holder and the terms of its license to LLVM users and developers is the
@ -501,11 +502,10 @@
legal matters but does not provide legal advice. We are not lawyers, please legal matters but does not provide legal advice. We are not lawyers, please
seek legal counsel from an attorney.</p> seek legal counsel from an attorney.</p>
</div> </div>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="copyright">Copyright</a></h3> <h3><a name="copyright">Copyright</a></h3>
<div class="doc_text"> <div>
<p>The LLVM project does not require copyright assignments, which means that the <p>The LLVM project does not require copyright assignments, which means that the
copyright for the code in the project is held by its respective contributors copyright for the code in the project is held by its respective contributors
@ -528,7 +528,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="license">License</a></h3> <h3><a name="license">License</a></h3>
<div class="doc_text"> <div>
<p>We intend to keep LLVM perpetually open source and to use a liberal open <p>We intend to keep LLVM perpetually open source and to use a liberal open
source license. All of the code in LLVM is available under the source license. All of the code in LLVM is available under the
<a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of <a href="http://www.opensource.org/licenses/UoI-NCSA.php">University of
@ -583,7 +583,7 @@
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="patents">Patents</a></h3> <h3><a name="patents">Patents</a></h3>
<div class="doc_text"> <div>
<p>To the best of our knowledge, LLVM does not infringe on any patents (we have <p>To the best of our knowledge, LLVM does not infringe on any patents (we have
actually removed code from LLVM in the past that was found to infringe). actually removed code from LLVM in the past that was found to infringe).
Having code in LLVM that infringes on patents would violate an important goal Having code in LLVM that infringes on patents would violate an important goal
@ -599,6 +599,8 @@
details.</p> details.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <address>

62
docs/ExceptionHandling.html
View File

@ -61,7 +61,7 @@
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document is the central repository for all information pertaining to <p>This document is the central repository for all information pertaining to
exception handling in LLVM. It describes the format that LLVM exception exception handling in LLVM. It describes the format that LLVM exception
@ -70,14 +70,12 @@
provides specific examples of what exception handling information is used for provides specific examples of what exception handling information is used for
in C/C++.</p> in C/C++.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="itanium">Itanium ABI Zero-cost Exception Handling</a> <a name="itanium">Itanium ABI Zero-cost Exception Handling</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Exception handling for most programming languages is designed to recover from <p>Exception handling for most programming languages is designed to recover from
conditions that rarely occur during general use of an application. To that conditions that rarely occur during general use of an application. To that
@ -110,7 +108,7 @@
<a name="sjlj">Setjmp/Longjmp Exception Handling</a> <a name="sjlj">Setjmp/Longjmp Exception Handling</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics <p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
<a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and <a href="#llvm_eh_sjlj_setjmp"><tt>llvm.eh.sjlj.setjmp</tt></a> and
@ -142,7 +140,7 @@
<a name="overview">Overview</a> <a name="overview">Overview</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>When an exception is thrown in LLVM code, the runtime does its best to find a <p>When an exception is thrown in LLVM code, the runtime does its best to find a
handler suited to processing the circumstance.</p> handler suited to processing the circumstance.</p>
@ -185,12 +183,14 @@
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2> <h2>
<a name="codegen">LLVM Code Generation</a> <a name="codegen">LLVM Code Generation</a>
</h2> </h2>
<div class="doc_text"> <div>
<p>At the time of this writing, only C++ exception handling support is available <p>At the time of this writing, only C++ exception handling support is available
in LLVM. So the remainder of this document will be somewhat C++-centric.</p> in LLVM. So the remainder of this document will be somewhat C++-centric.</p>
@ -200,14 +200,12 @@
we will describe the implementation of LLVM exception handling in terms of we will describe the implementation of LLVM exception handling in terms of
C++ examples.</p> C++ examples.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="throw">Throw</a> <a name="throw">Throw</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Languages that support exception handling typically provide a <tt>throw</tt> <p>Languages that support exception handling typically provide a <tt>throw</tt>
operation to initiate the exception process. Internally, a throw operation operation to initiate the exception process. Internally, a throw operation
@ -229,7 +227,7 @@
<a name="try_catch">Try/Catch</a> <a name="try_catch">Try/Catch</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>A call within the scope of a <i>try</i> statement can potentially raise an <p>A call within the scope of a <i>try</i> statement can potentially raise an
exception. In those circumstances, the LLVM C++ front-end replaces the call exception. In those circumstances, the LLVM C++ front-end replaces the call
@ -317,7 +315,7 @@
<a name="cleanups">Cleanups</a> <a name="cleanups">Cleanups</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>To handle destructors and cleanups in <tt>try</tt> code, control may not run <p>To handle destructors and cleanups in <tt>try</tt> code, control may not run
directly from a landing pad to the first catch. Control may actually flow directly from a landing pad to the first catch. Control may actually flow
@ -336,7 +334,7 @@
<a name="throw_filters">Throw Filters</a> <a name="throw_filters">Throw Filters</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>C++ allows the specification of which exception types can be thrown from a <p>C++ allows the specification of which exception types can be thrown from a
function. To represent this a top level landing pad may exist to filter out function. To represent this a top level landing pad may exist to filter out
@ -363,7 +361,7 @@
<a name="restrictions">Restrictions</a> <a name="restrictions">Restrictions</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The semantics of the invoke instruction require that any exception that <p>The semantics of the invoke instruction require that any exception that
unwinds through an invoke call should result in a branch to the invoke's unwinds through an invoke call should result in a branch to the invoke's
@ -384,25 +382,25 @@
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2> <h2>
<a name="format_common_intrinsics">Exception Handling Intrinsics</a> <a name="format_common_intrinsics">Exception Handling Intrinsics</a>
</h2> </h2>
<div class="doc_text"> <div>
<p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to <p>LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to
provide exception handling information at various points in generated provide exception handling information at various points in generated
code.</p> code.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4> <h4>
<a name="llvm_eh_exception">llvm.eh.exception</a> <a name="llvm_eh_exception">llvm.eh.exception</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>() i8* %<a href="#llvm_eh_exception">llvm.eh.exception</a>()
@ -417,7 +415,7 @@
<a name="llvm_eh_selector">llvm.eh.selector</a> <a name="llvm_eh_selector">llvm.eh.selector</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, ...) i32 %<a href="#llvm_eh_selector">llvm.eh.selector</a>(i8*, i8*, ...)
@ -449,7 +447,7 @@
<a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a> <a name="llvm_eh_typeid_for">llvm.eh.typeid.for</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*) i32 %<a href="#llvm_eh_typeid_for">llvm.eh.typeid.for</a>(i8*)
@ -467,7 +465,7 @@
<a name="llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a> <a name="llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
i32 %<a href="#llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>(i8*) i32 %<a href="#llvm_eh_sjlj_setjmp">llvm.eh.sjlj.setjmp</a>(i8*)
@ -496,7 +494,7 @@
<a name="llvm_eh_sjlj_longjmp">llvm.eh.sjlj.longjmp</a> <a name="llvm_eh_sjlj_longjmp">llvm.eh.sjlj.longjmp</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
void %<a href="#llvm_eh_sjlj_longjmp">llvm.eh.sjlj.setjmp</a>(i8*) void %<a href="#llvm_eh_sjlj_longjmp">llvm.eh.sjlj.setjmp</a>(i8*)
@ -516,7 +514,7 @@
<a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a> <a name="llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>() i8* %<a href="#llvm_eh_sjlj_lsda">llvm.eh.sjlj.lsda</a>()
@ -535,7 +533,7 @@
<a name="llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a> <a name="llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
void %<a href="#llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>(i32) void %<a href="#llvm_eh_sjlj_callsite">llvm.eh.sjlj.callsite</a>(i32)
@ -553,7 +551,7 @@
<a name="llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a> <a name="llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
void %<a href="#llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>(i32) void %<a href="#llvm_eh_sjlj_dispatchsetup">llvm.eh.sjlj.dispatchsetup</a>(i32)
@ -565,24 +563,24 @@
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2> <h2>
<a name="asm">Asm Table Formats</a> <a name="asm">Asm Table Formats</a>
</h2> </h2>
<div class="doc_text"> <div>
<p>There are two tables that are used by the exception handling runtime to <p>There are two tables that are used by the exception handling runtime to
determine which actions should take place when an exception is thrown.</p> determine which actions should take place when an exception is thrown.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="unwind_tables">Exception Handling Frame</a> <a name="unwind_tables">Exception Handling Frame</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind <p>An exception handling frame <tt>eh_frame</tt> is very similar to the unwind
frame used by dwarf debug info. The frame contains all the information frame used by dwarf debug info. The frame contains all the information
@ -600,7 +598,7 @@
<a name="exception_tables">Exception Tables</a> <a name="exception_tables">Exception Tables</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>An exception table contains information about what actions to take when an <p>An exception table contains information about what actions to take when an
exception is thrown in a particular part of a function's code. There is one exception is thrown in a particular part of a function's code. There is one
@ -611,12 +609,14 @@
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2> <h2>
<a name="todo">ToDo</a> <a name="todo">ToDo</a>
</h2> </h2>
<div class="doc_text"> <div>
<ol> <ol>

18
docs/ExtendingLLVM.html
View File

@ -36,7 +36,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>During the course of using LLVM, you may wish to customize it for your <p>During the course of using LLVM, you may wish to customize it for your
research project or for experimentation. At this point, you may realize that research project or for experimentation. At this point, you may realize that
@ -73,7 +73,7 @@ effort by doing so.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Adding a new intrinsic function to LLVM is much easier than adding a new <p>Adding a new intrinsic function to LLVM is much easier than adding a new
instruction. Almost all extensions to LLVM should start as an intrinsic instruction. Almost all extensions to LLVM should start as an intrinsic
@ -135,7 +135,7 @@ support for it. Generally you must do the following steps:</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier <p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier
than adding a new instruction. New nodes are often added to help represent than adding a new instruction. New nodes are often added to help represent
@ -225,7 +225,7 @@ complicated behavior in a single node (rotate).</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><span class="doc_warning">WARNING: adding instructions changes the bitcode <p><span class="doc_warning">WARNING: adding instructions changes the bitcode
format, and it will take some effort to maintain compatibility with format, and it will take some effort to maintain compatibility with
@ -282,20 +282,18 @@ to understand this new instruction.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><span class="doc_warning">WARNING: adding new types changes the bitcode <p><span class="doc_warning">WARNING: adding new types changes the bitcode
format, and will break compatibility with currently-existing LLVM format, and will break compatibility with currently-existing LLVM
installations.</span> Only add new types if it is absolutely necessary.</p> installations.</span> Only add new types if it is absolutely necessary.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="fund_type">Adding a fundamental type</a> <a name="fund_type">Adding a fundamental type</a>
</h3> </h3>
<div class="doc_text"> <div>
<ol> <ol>
@ -321,7 +319,7 @@ installations.</span> Only add new types if it is absolutely necessary.</p>
<a name="derived_type">Adding a derived type</a> <a name="derived_type">Adding a derived type</a>
</h3> </h3>
<div class="doc_text"> <div>
<ol> <ol>
<li><tt>llvm/include/llvm/Type.h</tt>: <li><tt>llvm/include/llvm/Type.h</tt>:
@ -373,6 +371,8 @@ void calcTypeName(const Type *Ty,
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

8
docs/GCCFEBuildInstrs.html
View File

@ -27,7 +27,7 @@
<h2><a name="instructions">Building llvm-gcc from Source</a></h2> <h2><a name="instructions">Building llvm-gcc from Source</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section describes how to acquire and build llvm-gcc 4.2, which is based <p>This section describes how to acquire and build llvm-gcc 4.2, which is based
on the GCC 4.2.1 front-end. Supported languages are Ada, C, C++, Fortran, on the GCC 4.2.1 front-end. Supported languages are Ada, C, C++, Fortran,
@ -70,7 +70,7 @@ svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk <i>dst-directory</i>
<h2><a name="ada">Building the Ada front-end</a></h2> <h2><a name="ada">Building the Ada front-end</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Building with support for Ada amounts to following the directions in the <p>Building with support for Ada amounts to following the directions in the
top-level <tt>README.LLVM</tt> file, adding ",ada" to EXTRALANGS, for example: top-level <tt>README.LLVM</tt> file, adding ",ada" to EXTRALANGS, for example:
<tt>EXTRALANGS=,ada</tt></p> <tt>EXTRALANGS=,ada</tt></p>
@ -236,7 +236,7 @@ make install
<h2><a name="fortran">Building the Fortran front-end</a></h2> <h2><a name="fortran">Building the Fortran front-end</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>To build with support for Fortran, follow the directions in the top-level <p>To build with support for Fortran, follow the directions in the top-level
<tt>README.LLVM</tt> file, adding ",fortran" to EXTRALANGS, for example:</p> <tt>README.LLVM</tt> file, adding ",fortran" to EXTRALANGS, for example:</p>
@ -250,7 +250,7 @@ EXTRALANGS=,fortran
<h2><a name="license">License Information</a></h2> <h2><a name="license">License Information</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The LLVM GCC frontend is licensed to you under the GNU General Public License The LLVM GCC frontend is licensed to you under the GNU General Public License
and the GNU Lesser General Public License. Please see the files COPYING and and the GNU Lesser General Public License. Please see the files COPYING and

59
docs/GarbageCollection.html
View File

@ -84,7 +84,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Garbage collection is a widely used technique that frees the programmer from <p>Garbage collection is a widely used technique that frees the programmer from
having to know the lifetimes of heap objects, making software easier to produce having to know the lifetimes of heap objects, making software easier to produce
@ -124,14 +124,12 @@ techniques dominates any low-level losses.</p>
<p>This document describes the mechanisms and interfaces provided by LLVM to <p>This document describes the mechanisms and interfaces provided by LLVM to
support accurate garbage collection.</p> support accurate garbage collection.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="feature">Goals and non-goals</a> <a name="feature">Goals and non-goals</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM's intermediate representation provides <a href="#intrinsics">garbage <p>LLVM's intermediate representation provides <a href="#intrinsics">garbage
collection intrinsics</a> that offer support for a broad class of collection intrinsics</a> that offer support for a broad class of
@ -198,13 +196,15 @@ compiler matures.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="quickstart">Getting started</a> <a name="quickstart">Getting started</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Using a GC with LLVM implies many things, for example:</p> <p>Using a GC with LLVM implies many things, for example:</p>
@ -246,14 +246,12 @@ compiler matures.</p>
includes a highly portable, built-in ShadowStack code generator. It is compiled includes a highly portable, built-in ShadowStack code generator. It is compiled
into <tt>llc</tt> and works even with the interpreter and C backends.</p> into <tt>llc</tt> and works even with the interpreter and C backends.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="quickstart-compiler">In your compiler</a> <a name="quickstart-compiler">In your compiler</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>To turn the shadow stack on for your functions, first call:</p> <p>To turn the shadow stack on for your functions, first call:</p>
@ -280,7 +278,7 @@ switching to a more advanced GC.</p>
<a name="quickstart-runtime">In your runtime</a> <a name="quickstart-runtime">In your runtime</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The shadow stack doesn't imply a memory allocation algorithm. A semispace <p>The shadow stack doesn't imply a memory allocation algorithm. A semispace
collector or building atop <tt>malloc</tt> are great places to start, and can collector or building atop <tt>malloc</tt> are great places to start, and can
@ -347,7 +345,7 @@ void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) {
<a name="shadow-stack">About the shadow stack</a> <a name="shadow-stack">About the shadow stack</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Unlike many GC algorithms which rely on a cooperative code generator to <p>Unlike many GC algorithms which rely on a cooperative code generator to
compile stack maps, this algorithm carefully maintains a linked list of stack compile stack maps, this algorithm carefully maintains a linked list of stack
@ -372,13 +370,15 @@ in order to improve performance.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="core">IR features</a><a name="intrinsics"></a> <a name="core">IR features</a><a name="intrinsics"></a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section describes the garbage collection facilities provided by the <p>This section describes the garbage collection facilities provided by the
<a href="LangRef.html">LLVM intermediate representation</a>. The exact behavior <a href="LangRef.html">LLVM intermediate representation</a>. The exact behavior
@ -390,8 +390,6 @@ intended to be a complete interface to any garbage collector. A program will
need to interface with the GC library using the facilities provided by that need to interface with the GC library using the facilities provided by that
program.</p> program.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a> <a name="gcattr">Specifying GC code generation: <tt>gc "..."</tt></a>
@ -401,7 +399,7 @@ program.</p>
define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ... define <i>ty</i> @<i>name</i>(...) <span style="text-decoration: underline">gc "<i>name</i>"</span> { ...
</tt></div> </tt></div>
<div class="doc_text"> <div>
<p>The <tt>gc</tt> function attribute is used to specify the desired GC style <p>The <tt>gc</tt> function attribute is used to specify the desired GC style
to the compiler. Its programmatic equivalent is the <tt>setGC</tt> method of to the compiler. Its programmatic equivalent is the <tt>setGC</tt> method of
@ -426,7 +424,7 @@ programs that use different garbage collection algorithms (or none at all).</p>
void @llvm.gcroot(i8** %ptrloc, i8* %metadata) void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
</tt></div> </tt></div>
<div class="doc_text"> <div>
<p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM that a stack <p>The <tt>llvm.gcroot</tt> intrinsic is used to inform LLVM that a stack
variable references an object on the heap and is to be tracked for garbage variable references an object on the heap and is to be tracked for garbage
@ -498,7 +496,7 @@ CodeBlock:
<a name="barriers">Reading and writing references in the heap</a> <a name="barriers">Reading and writing references in the heap</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Some collectors need to be informed when the mutator (the program that needs <p>Some collectors need to be informed when the mutator (the program that needs
garbage collection) either reads a pointer from or writes a pointer to a field garbage collection) either reads a pointer from or writes a pointer to a field
@ -534,8 +532,6 @@ require the corresponding barrier. Such a GC plugin will replace the intrinsic
calls with the corresponding <tt>load</tt> or <tt>store</tt> instruction if they calls with the corresponding <tt>load</tt> or <tt>store</tt> instruction if they
are used.</p> are used.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4> <h4>
<a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a> <a name="gcwrite">Write barrier: <tt>llvm.gcwrite</tt></a>
@ -545,7 +541,7 @@ are used.</p>
void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived) void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
</tt></div> </tt></div>
<div class="doc_text"> <div>
<p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic <p>For write barriers, LLVM provides the <tt>llvm.gcwrite</tt> intrinsic
function. It has exactly the same semantics as a non-volatile <tt>store</tt> to function. It has exactly the same semantics as a non-volatile <tt>store</tt> to
@ -567,7 +563,7 @@ implement reference counting.</p>
i8* @llvm.gcread(i8* %object, i8** %derived)<br> i8* @llvm.gcread(i8* %object, i8** %derived)<br>
</tt></div> </tt></div>
<div class="doc_text"> <div>
<p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function. <p>For read barriers, LLVM provides the <tt>llvm.gcread</tt> intrinsic function.
It has exactly the same semantics as a non-volatile <tt>load</tt> from the It has exactly the same semantics as a non-volatile <tt>load</tt> from the
@ -580,13 +576,17 @@ writes.</p>
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="plugin">Implementing a collector plugin</a> <a name="plugin">Implementing a collector plugin</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>User code specifies which GC code generation to use with the <tt>gc</tt> <p>User code specifies which GC code generation to use with the <tt>gc</tt>
function attribute or, equivalently, with the <tt>setGC</tt> method of function attribute or, equivalently, with the <tt>setGC</tt> method of
@ -666,14 +666,12 @@ $ llvm-as &lt; sample.ll | llc -load=MyGC.so</pre></blockquote>
<p>It is also possible to statically link the collector plugin into tools, such <p>It is also possible to statically link the collector plugin into tools, such
as a language-specific compiler front-end.</p> as a language-specific compiler front-end.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="collector-algos">Overview of available features</a> <a name="collector-algos">Overview of available features</a>
</h3> </h3>
<div class="doc_text"> <div>
<p><tt>GCStrategy</tt> provides a range of features through which a plugin <p><tt>GCStrategy</tt> provides a range of features through which a plugin
may do useful work. Some of these are callbacks, some are algorithms that can may do useful work. Some of these are callbacks, some are algorithms that can
@ -962,7 +960,7 @@ interest.</p>
<a name="stack-map">Computing stack maps</a> <a name="stack-map">Computing stack maps</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM automatically computes a stack map. One of the most important features <p>LLVM automatically computes a stack map. One of the most important features
of a <tt>GCStrategy</tt> is to compile this information into the executable in of a <tt>GCStrategy</tt> is to compile this information into the executable in
@ -1018,7 +1016,7 @@ for collector plugins which implement reference counting or a shadow stack.</p>
<a name="init-roots">Initializing roots to null: <tt>InitRoots</tt></a> <a name="init-roots">Initializing roots to null: <tt>InitRoots</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<blockquote><pre <blockquote><pre
>MyGC::MyGC() { >MyGC::MyGC() {
@ -1044,7 +1042,7 @@ this feature should be used by all GC plugins. It is enabled by default.</p>
<tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a> <tt>CustomReadBarriers</tt>, and <tt>CustomWriteBarriers</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>For GCs which use barriers or unusual treatment of stack roots, these <p>For GCs which use barriers or unusual treatment of stack roots, these
flags allow the collector to perform arbitrary transformations of the LLVM flags allow the collector to perform arbitrary transformations of the LLVM
@ -1133,7 +1131,7 @@ bool MyGC::performCustomLowering(Function &amp;F) {
<a name="safe-points">Generating safe points: <tt>NeededSafePoints</tt></a> <a name="safe-points">Generating safe points: <tt>NeededSafePoints</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM can compute four kinds of safe points:</p> <p>LLVM can compute four kinds of safe points:</p>
@ -1197,7 +1195,7 @@ safe point (because only the topmost function has been patched).</p>
<a name="assembly">Emitting assembly code: <tt>GCMetadataPrinter</tt></a> <a name="assembly">Emitting assembly code: <tt>GCMetadataPrinter</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM allows a plugin to print arbitrary assembly code before and after the <p>LLVM allows a plugin to print arbitrary assembly code before and after the
rest of a module's assembly code. At the end of the module, the GC can compile rest of a module's assembly code. At the end of the module, the GC can compile
@ -1341,6 +1339,7 @@ void MyGCPrinter::finishAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -1348,7 +1347,7 @@ void MyGCPrinter::finishAssembly(std::ostream &amp;OS, AsmPrinter &amp;AP,
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><a name="appel89">[Appel89]</a> Runtime Tags Aren't Necessary. Andrew <p><a name="appel89">[Appel89]</a> Runtime Tags Aren't Necessary. Andrew
W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.</p> W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.</p>

61
docs/GetElementPtr.html
View File

@ -61,7 +61,7 @@
<h2><a name="intro">Introduction</a></h2> <h2><a name="intro">Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document seeks to dispel the mystery and confusion surrounding LLVM's <p>This document seeks to dispel the mystery and confusion surrounding LLVM's
<a href="LangRef.html#i_getelementptr">GetElementPtr</a> (GEP) instruction. <a href="LangRef.html#i_getelementptr">GetElementPtr</a> (GEP) instruction.
Questions about the wily GEP instruction are Questions about the wily GEP instruction are
@ -74,19 +74,18 @@
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="addresses">Address Computation</a></h2> <h2><a name="addresses">Address Computation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>When people are first confronted with the GEP instruction, they tend to <p>When people are first confronted with the GEP instruction, they tend to
relate it to known concepts from other programming paradigms, most notably C relate it to known concepts from other programming paradigms, most notably C
array indexing and field selection. GEP closely resembles C array indexing array indexing and field selection. GEP closely resembles C array indexing
and field selection, however it's is a little different and this leads to and field selection, however it's is a little different and this leads to
the following questions.</p> the following questions.</p>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h3> <h3>
<a name="firstptr">What is the first index of the GEP instruction?</a> <a name="firstptr">What is the first index of the GEP instruction?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Quick answer: The index stepping through the first operand.</p> <p>Quick answer: The index stepping through the first operand.</p>
<p>The confusion with the first index usually arises from thinking about <p>The confusion with the first index usually arises from thinking about
the GetElementPtr instruction as if it was a C index operator. They aren't the the GetElementPtr instruction as if it was a C index operator. They aren't the
@ -209,7 +208,7 @@ idx3 = (char*) &amp;MyVar + 8
<a name="extra_index">Why is the extra 0 index required?</a> <a name="extra_index">Why is the extra 0 index required?</a>
</h3> </h3>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Quick answer: there are no superfluous indices.</p> <p>Quick answer: there are no superfluous indices.</p>
<p>This question arises most often when the GEP instruction is applied to a <p>This question arises most often when the GEP instruction is applied to a
global variable which is always a pointer type. For example, consider global variable which is always a pointer type. For example, consider
@ -250,7 +249,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="deref">What is dereferenced by GEP?</a> <a name="deref">What is dereferenced by GEP?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Quick answer: nothing.</p> <p>Quick answer: nothing.</p>
<p>The GetElementPtr instruction dereferences nothing. That is, it doesn't <p>The GetElementPtr instruction dereferences nothing. That is, it doesn't
access memory in any way. That's what the Load and Store instructions are for. access memory in any way. That's what the Load and Store instructions are for.
@ -305,7 +304,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="lead0">Why don't GEP x,0,0,1 and GEP x,1 alias?</a> <a name="lead0">Why don't GEP x,0,0,1 and GEP x,1 alias?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Quick Answer: They compute different address locations.</p> <p>Quick Answer: They compute different address locations.</p>
<p>If you look at the first indices in these GEP <p>If you look at the first indices in these GEP
instructions you find that they are different (0 and 1), therefore the address instructions you find that they are different (0 and 1), therefore the address
@ -334,7 +333,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="trail0">Why do GEP x,1,0,0 and GEP x,1 alias?</a> <a name="trail0">Why do GEP x,1,0,0 and GEP x,1 alias?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Quick Answer: They compute the same address location.</p> <p>Quick Answer: They compute the same address location.</p>
<p>These two GEP instructions will compute the same address because indexing <p>These two GEP instructions will compute the same address because indexing
through the 0th element does not change the address. However, it does change through the 0th element does not change the address. However, it does change
@ -358,7 +357,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="vectors">Can GEP index into vector elements?</a> <a name="vectors">Can GEP index into vector elements?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This hasn't always been forcefully disallowed, though it's not recommended. <p>This hasn't always been forcefully disallowed, though it's not recommended.
It leads to awkward special cases in the optimizers, and fundamental It leads to awkward special cases in the optimizers, and fundamental
inconsistency in the IR. In the future, it will probably be outright inconsistency in the IR. In the future, it will probably be outright
@ -371,7 +370,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="addrspace">What effect do address spaces have on GEPs?</a> <a name="addrspace">What effect do address spaces have on GEPs?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>None, except that the address space qualifier on the first operand pointer <p>None, except that the address space qualifier on the first operand pointer
type always matches the address space qualifier on the result type.</p> type always matches the address space qualifier on the result type.</p>
@ -384,7 +383,7 @@ idx3 = (char*) &amp;MyVar + 8
How is GEP different from ptrtoint, arithmetic, and inttoptr? How is GEP different from ptrtoint, arithmetic, and inttoptr?
</a> </a>
</h3> </h3>
<div class="doc_text"> <div>
<p>It's very similar; there are only subtle differences.</p> <p>It's very similar; there are only subtle differences.</p>
<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64; <p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
@ -416,7 +415,7 @@ idx3 = (char*) &amp;MyVar + 8
How do I do this? How do I do this?
</a> </a>
</h3> </h3>
<div class="doc_text"> <div>
<p>You don't. The integer computation implied by a GEP is target-independent. <p>You don't. The integer computation implied by a GEP is target-independent.
Typically what you'll need to do is make your backend pattern-match Typically what you'll need to do is make your backend pattern-match
expressions trees involving ADD, MUL, etc., which are what GEP is lowered expressions trees involving ADD, MUL, etc., which are what GEP is lowered
@ -437,7 +436,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="vla">How does VLA addressing work with GEPs?</a> <a name="vla">How does VLA addressing work with GEPs?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>GEPs don't natively support VLAs. LLVM's type system is entirely static, <p>GEPs don't natively support VLAs. LLVM's type system is entirely static,
and GEP address computations are guided by an LLVM type.</p> and GEP address computations are guided by an LLVM type.</p>
@ -453,16 +452,18 @@ idx3 = (char*) &amp;MyVar + 8
VLA and non-VLA indexing in the same manner.</p> VLA and non-VLA indexing in the same manner.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="rules">Rules</a></h2> <h2><a name="rules">Rules</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h3> <h3>
<a name="bounds">What happens if an array index is out of bounds?</a> <a name="bounds">What happens if an array index is out of bounds?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>There are two senses in which an array index can be out of bounds.</p> <p>There are two senses in which an array index can be out of bounds.</p>
<p>First, there's the array type which comes from the (static) type of <p>First, there's the array type which comes from the (static) type of
@ -504,7 +505,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="negative">Can array indices be negative?</a> <a name="negative">Can array indices be negative?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Yes. This is basically a special case of array indices being out <p>Yes. This is basically a special case of array indices being out
of bounds.</p> of bounds.</p>
@ -514,7 +515,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="compare">Can I compare two values computed with GEPs?</a> <a name="compare">Can I compare two values computed with GEPs?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Yes. If both addresses are within the same allocated object, or <p>Yes. If both addresses are within the same allocated object, or
one-past-the-end, you'll get the comparison result you expect. If either one-past-the-end, you'll get the comparison result you expect. If either
is outside of it, integer arithmetic wrapping may occur, so the is outside of it, integer arithmetic wrapping may occur, so the
@ -529,7 +530,7 @@ idx3 = (char*) &amp;MyVar + 8
the underlying object? the underlying object?
</a> </a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary <p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
pointer type. The types in a GEP serve only to define the parameters for the pointer type. The types in a GEP serve only to define the parameters for the
underlying integer computation. They need not correspond with the actual underlying integer computation. They need not correspond with the actual
@ -548,7 +549,7 @@ idx3 = (char*) &amp;MyVar + 8
Can I cast an object's address to integer and add it to null? Can I cast an object's address to integer and add it to null?
</a> </a>
</h3> </h3>
<div class="doc_text"> <div>
<p>You can compute an address that way, but if you use GEP to do the add, <p>You can compute an address that way, but if you use GEP to do the add,
you can't use that pointer to actually access the object, unless the you can't use that pointer to actually access the object, unless the
object is managed outside of LLVM.</p> object is managed outside of LLVM.</p>
@ -574,7 +575,7 @@ idx3 = (char*) &amp;MyVar + 8
that value to one address to compute the other address? that value to one address to compute the other address?
</a> </a>
</h3> </h3>
<div class="doc_text"> <div>
<p>As with arithmetic on null, You can use GEP to compute an address that <p>As with arithmetic on null, You can use GEP to compute an address that
way, but you can't use that pointer to actually access the object if you way, but you can't use that pointer to actually access the object if you
do, unless the object is managed outside of LLVM.</p> do, unless the object is managed outside of LLVM.</p>
@ -588,7 +589,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="tbaa">Can I do type-based alias analysis on LLVM IR?</a> <a name="tbaa">Can I do type-based alias analysis on LLVM IR?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>You can't do type-based alias analysis using LLVM's built-in type system, <p>You can't do type-based alias analysis using LLVM's built-in type system,
because LLVM has no restrictions on mixing types in addressing, loads or because LLVM has no restrictions on mixing types in addressing, loads or
stores.</p> stores.</p>
@ -605,7 +606,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="overflow">What happens if a GEP computation overflows?</a> <a name="overflow">What happens if a GEP computation overflows?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>If the GEP lacks the <tt>inbounds</tt> keyword, the value is the result <p>If the GEP lacks the <tt>inbounds</tt> keyword, the value is the result
from evaluating the implied two's complement integer computation. However, from evaluating the implied two's complement integer computation. However,
since there's no guarantee of where an object will be allocated in the since there's no guarantee of where an object will be allocated in the
@ -637,7 +638,7 @@ idx3 = (char*) &amp;MyVar + 8
How can I tell if my front-end is following the rules? How can I tell if my front-end is following the rules?
</a> </a>
</h3> </h3>
<div class="doc_text"> <div>
<p>There is currently no checker for the getelementptr rules. Currently, <p>There is currently no checker for the getelementptr rules. Currently,
the only way to do this is to manually check each place in your front-end the only way to do this is to manually check each place in your front-end
where GetElementPtr operators are created.</p> where GetElementPtr operators are created.</p>
@ -650,16 +651,18 @@ idx3 = (char*) &amp;MyVar + 8
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="rationale">Rationale</a></h2> <h2><a name="rationale">Rationale</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h3> <h3>
<a name="goals">Why is GEP designed this way?</a> <a name="goals">Why is GEP designed this way?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The design of GEP has the following goals, in rough unofficial <p>The design of GEP has the following goals, in rough unofficial
order of priority:</p> order of priority:</p>
<ul> <ul>
@ -681,7 +684,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="i32">Why do struct member indices always use i32?</a> <a name="i32">Why do struct member indices always use i32?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The specific type i32 is probably just a historical artifact, however it's <p>The specific type i32 is probably just a historical artifact, however it's
wide enough for all practical purposes, so there's been no need to change it. wide enough for all practical purposes, so there's been no need to change it.
It doesn't necessarily imply i32 address arithmetic; it's just an identifier It doesn't necessarily imply i32 address arithmetic; it's just an identifier
@ -696,7 +699,7 @@ idx3 = (char*) &amp;MyVar + 8
<h3> <h3>
<a name="uglygep">What's an uglygep?</a> <a name="uglygep">What's an uglygep?</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Some LLVM optimizers operate on GEPs by internally lowering them into <p>Some LLVM optimizers operate on GEPs by internally lowering them into
more primitive integer expressions, which allows them to be combined more primitive integer expressions, which allows them to be combined
with other integer expressions and/or split into multiple separate with other integer expressions and/or split into multiple separate
@ -713,11 +716,13 @@ idx3 = (char*) &amp;MyVar + 8
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="summary">Summary</a></h2> <h2><a name="summary">Summary</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>In summary, here's some things to always remember about the GetElementPtr <p>In summary, here's some things to always remember about the GetElementPtr
instruction:</p> instruction:</p>
<ol> <ol>

77
docs/GettingStarted.html
View File

@ -75,7 +75,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to LLVM! In order to get started, you first need to know some <p>Welcome to LLVM! In order to get started, you first need to know some
basic information.</p> basic information.</p>
@ -107,7 +107,7 @@ and performance.
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Here's the short story for getting up and running quickly with LLVM:</p> <p>Here's the short story for getting up and running quickly with LLVM:</p>
@ -196,20 +196,18 @@ Layout</a> to learn about the layout of the source code tree.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Before you begin to use the LLVM system, review the requirements given below. <p>Before you begin to use the LLVM system, review the requirements given below.
This may save you some trouble by knowing ahead of time what hardware and This may save you some trouble by knowing ahead of time what hardware and
software you will need.</p> software you will need.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="hardware">Hardware</a> <a name="hardware">Hardware</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM is known to work on the following platforms:</p> <p>LLVM is known to work on the following platforms:</p>
@ -373,7 +371,7 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p>
<h3> <h3>
<a name="software">Software</a> <a name="software">Software</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Compiling LLVM requires that you have several software packages <p>Compiling LLVM requires that you have several software packages
installed. The table below lists those required packages. The Package column installed. The table below lists those required packages. The Package column
is the usual name for the software package that LLVM depends on. The Version is the usual name for the software package that LLVM depends on. The Version
@ -514,7 +512,7 @@ href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p>
<a name="brokengcc">Broken versions of GCC and other tools</a> <a name="brokengcc">Broken versions of GCC and other tools</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM is very demanding of the host C++ compiler, and as such tends to expose <p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
bugs in the compiler. In particular, several versions of GCC crash when trying bugs in the compiler. In particular, several versions of GCC crash when trying
@ -607,7 +605,7 @@ upgrading to a newer version of Gold.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -615,7 +613,7 @@ upgrading to a newer version of Gold.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The remainder of this guide is meant to get you up and running with <p>The remainder of this guide is meant to get you up and running with
LLVM and to give you some basic information about the LLVM environment.</p> LLVM and to give you some basic information about the LLVM environment.</p>
@ -625,14 +623,13 @@ href="#layout">general layout</a> of the the LLVM source tree, a <a
href="#tutorial">simple example</a> using the LLVM tool chain, and <a href="#tutorial">simple example</a> using the LLVM tool chain, and <a
href="#links">links</a> to find more information about LLVM or to get href="#links">links</a> to find more information about LLVM or to get
help via e-mail.</p> help via e-mail.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="terminology">Terminology and Notation</a> <a name="terminology">Terminology and Notation</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Throughout this manual, the following names are used to denote paths <p>Throughout this manual, the following names are used to denote paths
specific to the local system and working environment. <i>These are not specific to the local system and working environment. <i>These are not
@ -669,7 +666,7 @@ All these paths are absolute:</p>
<a name="environment">Setting Up Your Environment</a> <a name="environment">Setting Up Your Environment</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
In order to compile and use LLVM, you may need to set some environment In order to compile and use LLVM, you may need to set some environment
@ -692,7 +689,7 @@ variables.
<a name="unpack">Unpacking the LLVM Archives</a> <a name="unpack">Unpacking the LLVM Archives</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
If you have the LLVM distribution, you will need to unpack it before you If you have the LLVM distribution, you will need to unpack it before you
@ -726,7 +723,7 @@ compressed with the gzip program.
<a name="checkout">Checkout LLVM from Subversion</a> <a name="checkout">Checkout LLVM from Subversion</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>If you have access to our Subversion repository, you can get a fresh copy of <p>If you have access to our Subversion repository, you can get a fresh copy of
the entire source code. All you need to do is check it out from Subversion as the entire source code. All you need to do is check it out from Subversion as
@ -797,7 +794,7 @@ instructions</a> to successfully get and build the LLVM GCC front-end.</p>
<a name="git_mirror">GIT mirror</a> <a name="git_mirror">GIT mirror</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>GIT mirrors are available for a number of LLVM subprojects. These mirrors <p>GIT mirrors are available for a number of LLVM subprojects. These mirrors
sync automatically with each Subversion commit and contain all necessary sync automatically with each Subversion commit and contain all necessary
@ -816,7 +813,7 @@ instructions</a> to successfully get and build the LLVM GCC front-end.</p>
<a name="installcf">Install the GCC Front End</a> <a name="installcf">Install the GCC Front End</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM <p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM
GCC front end) you can optionally extract the front end from the binary distribution. GCC front end) you can optionally extract the front end from the binary distribution.
@ -886,7 +883,7 @@ please let us know how you would like to see things improved by dropping us a no
<a name="config">Local LLVM Configuration</a> <a name="config">Local LLVM Configuration</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Once checked out from the Subversion repository, the LLVM suite source <p>Once checked out from the Subversion repository, the LLVM suite source
code must be code must be
@ -1008,7 +1005,7 @@ script to configure the build system:</p>
<a name="compile">Compiling the LLVM Suite Source Code</a> <a name="compile">Compiling the LLVM Suite Source Code</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Once you have configured LLVM, you can build it. There are three types of <p>Once you have configured LLVM, you can build it. There are three types of
builds:</p> builds:</p>
@ -1142,7 +1139,7 @@ that directory that is out of date.</p>
<a name="cross-compile">Cross-Compiling LLVM</a> <a name="cross-compile">Cross-Compiling LLVM</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>It is possible to cross-compile LLVM itself. That is, you can create LLVM <p>It is possible to cross-compile LLVM itself. That is, you can create LLVM
executables and libraries to be hosted on a platform different from the executables and libraries to be hosted on a platform different from the
platform where they are build (a Canadian Cross build). To configure a platform where they are build (a Canadian Cross build). To configure a
@ -1160,7 +1157,7 @@ that directory that is out of date.</p>
<a name="objfiles">The Location of LLVM Object Files</a> <a name="objfiles">The Location of LLVM Object Files</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The LLVM build system is capable of sharing a single LLVM source tree among <p>The LLVM build system is capable of sharing a single LLVM source tree among
several LLVM builds. Hence, it is possible to build LLVM for several different several LLVM builds. Hence, it is possible to build LLVM for several different
@ -1220,7 +1217,7 @@ named after the build type:</p>
<a name="optionalconfig">Optional Configuration Items</a> <a name="optionalconfig">Optional Configuration Items</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
If you're running on a Linux system that supports the "<a If you're running on a Linux system that supports the "<a
@ -1251,27 +1248,27 @@ $ sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="layout">Program Layout</a> <a name="layout">Program Layout</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>One useful source of information about the LLVM source base is the LLVM <a <p>One useful source of information about the LLVM source base is the LLVM <a
href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a
href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>. href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>.
The following is a brief introduction to code layout:</p> The following is a brief introduction to code layout:</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="examples"><tt>llvm/examples</tt></a> <a name="examples"><tt>llvm/examples</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains some simple examples of how to use the LLVM IR and <p>This directory contains some simple examples of how to use the LLVM IR and
JIT.</p> JIT.</p>
</div> </div>
@ -1281,7 +1278,7 @@ The following is a brief introduction to code layout:</p>
<a name="include"><tt>llvm/include</tt></a> <a name="include"><tt>llvm/include</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains public header files exported from the LLVM <p>This directory contains public header files exported from the LLVM
library. The three main subdirectories of this directory are:</p> library. The three main subdirectories of this directory are:</p>
@ -1312,7 +1309,7 @@ library. The three main subdirectories of this directory are:</p>
<a name="lib"><tt>llvm/lib</tt></a> <a name="lib"><tt>llvm/lib</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains most of the source files of the LLVM system. In LLVM, <p>This directory contains most of the source files of the LLVM system. In LLVM,
almost all code exists in libraries, making it very easy to share code among the almost all code exists in libraries, making it very easy to share code among the
@ -1381,7 +1378,7 @@ different <a href="#tools">tools</a>.</p>
<a name="projects"><tt>llvm/projects</tt></a> <a name="projects"><tt>llvm/projects</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains projects that are not strictly part of LLVM but are <p>This directory contains projects that are not strictly part of LLVM but are
shipped with LLVM. This is also the directory where you should create your own shipped with LLVM. This is also the directory where you should create your own
LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how
@ -1393,7 +1390,7 @@ different <a href="#tools">tools</a>.</p>
<a name="runtime"><tt>llvm/runtime</tt></a> <a name="runtime"><tt>llvm/runtime</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains libraries which are compiled into LLVM bitcode and <p>This directory contains libraries which are compiled into LLVM bitcode and
used when linking programs with the GCC front end. Most of these libraries are used when linking programs with the GCC front end. Most of these libraries are
@ -1410,7 +1407,7 @@ end to compile.</p>
<a name="test"><tt>llvm/test</tt></a> <a name="test"><tt>llvm/test</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains feature and regression tests and other basic sanity <p>This directory contains feature and regression tests and other basic sanity
checks on the LLVM infrastructure. These are intended to run quickly and cover checks on the LLVM infrastructure. These are intended to run quickly and cover
a lot of territory without being exhaustive.</p> a lot of territory without being exhaustive.</p>
@ -1421,7 +1418,7 @@ end to compile.</p>
<a name="test-suite"><tt>test-suite</tt></a> <a name="test-suite"><tt>test-suite</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This is not a directory in the normal llvm module; it is a separate <p>This is not a directory in the normal llvm module; it is a separate
Subversion Subversion
module that must be checked out (usually to <tt>projects/test-suite</tt>). module that must be checked out (usually to <tt>projects/test-suite</tt>).
@ -1440,7 +1437,7 @@ end to compile.</p>
<a name="tools"><tt>llvm/tools</tt></a> <a name="tools"><tt>llvm/tools</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The <b>tools</b> directory contains the executables built out of the <p>The <b>tools</b> directory contains the executables built out of the
libraries above, which form the main part of the user interface. You can libraries above, which form the main part of the user interface. You can
@ -1528,7 +1525,7 @@ information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p>
<a name="utils"><tt>llvm/utils</tt></a> <a name="utils"><tt>llvm/utils</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>This directory contains utilities for working with LLVM source code, and some <p>This directory contains utilities for working with LLVM source code, and some
of the utilities are actually required as part of the build process because they of the utilities are actually required as part of the build process because they
@ -1589,13 +1586,15 @@ are code generators for parts of LLVM infrastructure.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="tutorial">An Example Using the LLVM Tool Chain</a> <a name="tutorial">An Example Using the LLVM Tool Chain</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete, <p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete,
so we only include instructions for llvm-gcc4. so we only include instructions for llvm-gcc4.
</p> </p>
@ -1606,14 +1605,13 @@ create bitcode by default: <i>gcc4</i> produces native code. As the example belo
the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and
<i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode <i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode
output.</p> output.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="tutorial4">Example with llvm-gcc4</a> <a name="tutorial4">Example with llvm-gcc4</a>
</h3> </h3>
<div class="doc_text"> <div>
<ol> <ol>
<li><p>First, create a simple C file, name it 'hello.c':</p> <li><p>First, create a simple C file, name it 'hello.c':</p>
@ -1694,6 +1692,7 @@ int main() {
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
@ -1701,7 +1700,7 @@ int main() {
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>If you are having problems building or using LLVM, or if you have any other <p>If you are having problems building or using LLVM, or if you have any other
general questions about LLVM, please consult the <a href="FAQ.html">Frequently general questions about LLVM, please consult the <a href="FAQ.html">Frequently
@ -1715,7 +1714,7 @@ Asked Questions</a> page.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document is just an <b>introduction</b> on how to use LLVM to do <p>This document is just an <b>introduction</b> on how to use LLVM to do
some simple things... there are many more interesting and complicated things some simple things... there are many more interesting and complicated things

20
docs/GettingStartedVS.html
View File

@ -36,7 +36,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using <p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using
Visual Studio, not mingw or cygwin. In order to get started, you first need to Visual Studio, not mingw or cygwin. In order to get started, you first need to
@ -75,20 +75,18 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Before you begin to use the LLVM system, review the requirements given <p>Before you begin to use the LLVM system, review the requirements given
below. This may save you some trouble by knowing ahead of time what hardware below. This may save you some trouble by knowing ahead of time what hardware
and software you will need.</p> and software you will need.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="hardware"><b>Hardware</b></a> <a name="hardware"><b>Hardware</b></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine. <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine.
The LLVM source tree and object files, libraries and executables will consume The LLVM source tree and object files, libraries and executables will consume
@ -98,7 +96,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="software"><b>Software</b></a></h3> <h3><a name="software"><b>Software</b></a></h3>
<div class="doc_text"> <div>
<p>You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1 <p>You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1
beta and the normal VS2005 still have bugs that are not completely beta and the normal VS2005 still have bugs that are not completely
@ -118,13 +116,15 @@
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="quickstart"><b>Getting Started</b></a> <a name="quickstart"><b>Getting Started</b></a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Here's the short story for getting up and running quickly with LLVM:</p> <p>Here's the short story for getting up and running quickly with LLVM:</p>
@ -234,7 +234,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<ol> <ol>
<li><p>First, create a simple C file, name it 'hello.c':</p> <li><p>First, create a simple C file, name it 'hello.c':</p>
@ -324,7 +324,7 @@ int main() {
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>If you are having problems building or using LLVM, or if you have any other <p>If you are having problems building or using LLVM, or if you have any other
general questions about LLVM, please consult the <a href="FAQ.html">Frequently general questions about LLVM, please consult the <a href="FAQ.html">Frequently
@ -338,7 +338,7 @@ Asked Questions</a> page.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document is just an <b>introduction</b> to how to use LLVM to do <p>This document is just an <b>introduction</b> to how to use LLVM to do
some simple things... there are many more interesting and complicated things some simple things... there are many more interesting and complicated things

15
docs/GoldPlugin.html
View File

@ -23,7 +23,7 @@
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>Building with link time optimization requires cooperation from the <p>Building with link time optimization requires cooperation from the
system linker. LTO support on Linux systems requires that you use system linker. LTO support on Linux systems requires that you use
the <a href="http://sourceware.org/binutils">gold linker</a> which supports the <a href="http://sourceware.org/binutils">gold linker</a> which supports
@ -40,7 +40,7 @@ The same plugin can also be used by other tools such as <tt>ar</tt> and
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="build">How to build it</a></h2> <h2><a name="build">How to build it</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>You need to have gold with plugin support and build the LLVMgold <p>You need to have gold with plugin support and build the LLVMgold
plugin. Check whether you have gold running <tt>/usr/bin/ld -v</tt>. It will plugin. Check whether you have gold running <tt>/usr/bin/ld -v</tt>. It will
report &#8220;GNU gold&#8221; or else &#8220GNU ld&#8221; if not. If you have report &#8220;GNU gold&#8221; or else &#8220GNU ld&#8221; if not. If you have
@ -74,7 +74,7 @@ placed.
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="usage">Usage</a></h2> <h2><a name="usage">Usage</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>The linker takes a <tt>-plugin</tt> option that points to the path of <p>The linker takes a <tt>-plugin</tt> option that points to the path of
the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt> the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt>
would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look
@ -95,14 +95,13 @@ placed.
own gold, be sure to install the <tt>ar</tt> and <tt>nm-new</tt> you built to own gold, be sure to install the <tt>ar</tt> and <tt>nm-new</tt> you built to
<tt>/usr/bin</tt>. <tt>/usr/bin</tt>.
<p> <p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="example1">Example of link time optimization</a> <a name="example1">Example of link time optimization</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The following example shows a worked example of the gold plugin mixing <p>The following example shows a worked example of the gold plugin mixing
LLVM bitcode and native code. LLVM bitcode and native code.
<pre class="doc_code"> <pre class="doc_code">
@ -149,6 +148,8 @@ $ llvm-gcc -use-gold-plugin a.a b.o -o main # &lt;-- link with LLVMgold plugin
example</a> gold does not currently eliminate foo4.</p> example</a> gold does not currently eliminate foo4.</p>
</div> </div>
</div>
<!--=========================================================================--> <!--=========================================================================-->
<h2> <h2>
<a name="lto_autotools"> <a name="lto_autotools">
@ -156,7 +157,7 @@ $ llvm-gcc -use-gold-plugin a.a b.o -o main # &lt;-- link with LLVMgold plugin
</a> </a>
</h2> </h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>Once your system <tt>ld</tt>, <tt>ar</tt> and <tt>nm</tt> all support LLVM <p>Once your system <tt>ld</tt>, <tt>ar</tt> and <tt>nm</tt> all support LLVM
bitcode, everything is in place for an easy to use LTO build of autotooled bitcode, everything is in place for an easy to use LTO build of autotooled
projects:</p> projects:</p>
@ -195,7 +196,7 @@ export CFLAGS="-O4"
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="licensing">Licensing</a></h2> <h2><a name="licensing">Licensing</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>Gold is licensed under the GPLv3. LLVMgold uses the interface file <p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
<tt>plugin-api.h</tt> from gold which means that the resulting LLVMgold.so <tt>plugin-api.h</tt> from gold which means that the resulting LLVMgold.so
binary is also GPLv3. This can still be used to link non-GPLv3 programs just binary is also GPLv3. This can still be used to link non-GPLv3 programs just

75
docs/HowToReleaseLLVM.html
View File

@ -26,7 +26,7 @@
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document contains information about successfully releasing LLVM &mdash; <p>This document contains information about successfully releasing LLVM &mdash;
including subprojects: e.g., <tt>llvm-gcc</tt> and <tt>clang</tt> &mdash; to including subprojects: e.g., <tt>llvm-gcc</tt> and <tt>clang</tt> &mdash; to
@ -38,7 +38,7 @@
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="process">Release Timeline</a></h2> <h2><a name="process">Release Timeline</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>LLVM is released on a time based schedule &mdash; roughly every 6 months. We <p>LLVM is released on a time based schedule &mdash; roughly every 6 months. We
do not normally have dot releases because of the nature of LLVM's incremental do not normally have dot releases because of the nature of LLVM's incremental
@ -79,7 +79,7 @@
<h2><a name="process">Release Process</a></h2> <h2><a name="process">Release Process</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<ol> <ol>
<li><a href="#release-admin">Release Administrative Tasks</a> <li><a href="#release-admin">Release Administrative Tasks</a>
@ -119,12 +119,10 @@
</li> </li>
</ol> </ol>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="release-admin">Release Administrative Tasks</a></h3> <h3><a name="release-admin">Release Administrative Tasks</a></h3>
<div class="doc_text"> <div>
<p>This section describes a few administrative tasks that need to be done for <p>This section describes a few administrative tasks that need to be done for
the release process to begin. Specifically, it involves:</p> the release process to begin. Specifically, it involves:</p>
@ -135,12 +133,10 @@
<li>Tagging release candidates for the release team to begin testing</li> <li>Tagging release candidates for the release team to begin testing</li>
</ul> </ul>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="branch">Create Release Branch</a></h4> <h4><a name="branch">Create Release Branch</a></h4>
<div class="doc_text"> <div>
<p>Branch the Subversion trunk using the following procedure:</p> <p>Branch the Subversion trunk using the following procedure:</p>
@ -200,7 +196,7 @@ $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="verchanges">Update LLVM Version</a></h4> <h4><a name="verchanges">Update LLVM Version</a></h4>
<div class="doc_text"> <div>
<p>After creating the LLVM release branch, update the release branches' <p>After creating the LLVM release branch, update the release branches'
<tt>autoconf</tt> and <tt>configure.ac</tt> versions from '<tt>X.Ysvn</tt>' <tt>autoconf</tt> and <tt>configure.ac</tt> versions from '<tt>X.Ysvn</tt>'
@ -216,7 +212,7 @@ $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="dist">Build the LLVM Release Candidates</a></h4> <h4><a name="dist">Build the LLVM Release Candidates</a></h4>
<div class="doc_text"> <div>
<p>Create release candidates for <tt>llvm</tt>, <tt>llvm-gcc</tt>, <p>Create release candidates for <tt>llvm</tt>, <tt>llvm-gcc</tt>,
<tt>clang</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch with <tt>clang</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch with
@ -268,10 +264,12 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="release-build">Building the Release</a></h3> <h3><a name="release-build">Building the Release</a></h3>
<div class="doc_text"> <div>
<p>The builds of <tt>llvm</tt>, <tt>llvm-gcc</tt>, and <tt>clang</tt> <p>The builds of <tt>llvm</tt>, <tt>llvm-gcc</tt>, and <tt>clang</tt>
<em>must</em> be free of errors and warnings in Debug, Release+Asserts, and <em>must</em> be free of errors and warnings in Debug, Release+Asserts, and
@ -287,12 +285,10 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<tr align="left"><td>Release</td><td><tt>ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt></td></tr> <tr align="left"><td>Release</td><td><tt>ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt></td></tr>
</table> </table>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="build">Build LLVM</a></h4> <h4><a name="build">Build LLVM</a></h4>
<div class="doc_text"> <div>
<p>Build <tt>Debug</tt>, <tt>Release+Asserts</tt>, and <tt>Release</tt> versions <p>Build <tt>Debug</tt>, <tt>Release+Asserts</tt>, and <tt>Release</tt> versions
of <tt>llvm</tt> on all supported platforms. Directions to build of <tt>llvm</tt> on all supported platforms. Directions to build
@ -304,7 +300,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></h4> <h4><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></h4>
<div class="doc_text"> <div>
<p>Creating the <tt>llvm-gcc</tt> binary distribution (Release/Optimized) <p>Creating the <tt>llvm-gcc</tt> binary distribution (Release/Optimized)
requires performing the following steps for each supported platform:</p> requires performing the following steps for each supported platform:</p>
@ -331,7 +327,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="clangbin">Build Clang Binary Distribution</a></h4> <h4><a name="clangbin">Build Clang Binary Distribution</a></h4>
<div class="doc_text"> <div>
<p>Creating the <tt>clang</tt> binary distribution <p>Creating the <tt>clang</tt> binary distribution
(Debug/Release+Asserts/Release) requires performing the following steps for (Debug/Release+Asserts/Release) requires performing the following steps for
@ -352,7 +348,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="target-build">Target Specific Build Details</a></h4> <h4><a name="target-build">Target Specific Build Details</a></h4>
<div class="doc_text"> <div>
<p>The table below specifies which compilers are used for each Arch/OS <p>The table below specifies which compilers are used for each Arch/OS
combination when qualifying the build of <tt>llvm</tt>, <tt>llvm-gcc</tt>, combination when qualifying the build of <tt>llvm</tt>, <tt>llvm-gcc</tt>,
@ -371,10 +367,12 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="release-qualify">Building the Release</a></h3> <h3><a name="release-qualify">Building the Release</a></h3>
<div class="doc_text"> <div>
<p>A release is qualified when it has no regressions from the previous release <p>A release is qualified when it has no regressions from the previous release
(or baseline). Regressions are related to correctness first and performance (or baseline). Regressions are related to correctness first and performance
@ -390,12 +388,10 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
criteria, but these are the criteria which we found to be most important and criteria, but these are the criteria which we found to be most important and
which must be satisfied before a release can go out</b></p> which must be satisfied before a release can go out</b></p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="llvm-qualify">Qualify LLVM</a></h4> <h4><a name="llvm-qualify">Qualify LLVM</a></h4>
<div class="doc_text"> <div>
<p>LLVM is qualified when it has a clean test run without a front-end. And it <p>LLVM is qualified when it has a clean test run without a front-end. And it
has no regressions when using either <tt>llvm-gcc</tt> or <tt>clang</tt> with has no regressions when using either <tt>llvm-gcc</tt> or <tt>clang</tt> with
@ -406,7 +402,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="llvmgcc-qualify">Qualify LLVM-GCC</a></h4> <h4><a name="llvmgcc-qualify">Qualify LLVM-GCC</a></h4>
<div class="doc_text"> <div>
<p><tt>LLVM-GCC</tt> is qualified when front-end specific tests in the <p><tt>LLVM-GCC</tt> is qualified when front-end specific tests in the
<tt>llvm</tt> regression test suite all pass and there are no regressions in <tt>llvm</tt> regression test suite all pass and there are no regressions in
@ -419,7 +415,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="clang-qualify">Qualify Clang</a></h4> <h4><a name="clang-qualify">Qualify Clang</a></h4>
<div class="doc_text"> <div>
<p><tt>Clang</tt> is qualified when front-end specific tests in the <p><tt>Clang</tt> is qualified when front-end specific tests in the
<tt>llvm</tt> dejagnu test suite all pass, clang's own test suite passes <tt>llvm</tt> dejagnu test suite all pass, clang's own test suite passes
@ -430,7 +426,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="targets">Specific Target Qualification Details</a></h4> <h4><a name="targets">Specific Target Qualification Details</a></h4>
<div class="doc_text"> <div>
<table> <table>
<tr><th>Architecture</th><th>OS</th><th>llvm-gcc baseline</th><th>clang baseline</th><th>tests</th></tr> <tr><th>Architecture</th><th>OS</th><th>llvm-gcc baseline</th><th>clang baseline</th><th>tests</th></tr>
@ -444,9 +440,11 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="commTest">Community Testing</a></h3> <h3><a name="commTest">Community Testing</a></h3>
<div class="doc_text"> <div>
<p>Once all testing has been completed and appropriate bugs filed, the release <p>Once all testing has been completed and appropriate bugs filed, the release
candidate tarballs are put on the website and the LLVM community is candidate tarballs are put on the website and the LLVM community is
@ -484,7 +482,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="release-patch">Release Patch Rules</a></h3> <h3><a name="release-patch">Release Patch Rules</a></h3>
<div class="doc_text"> <div>
<p>Below are the rules regarding patching the release branch:</p> <p>Below are the rules regarding patching the release branch:</p>
@ -508,19 +506,16 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="release-final">Release Final Tasks</a></h3> <h3><a name="release-final">Release Final Tasks</a></h3>
<div class="doc_text"> <div>
<p>The final stages of the release process involves tagging the "final" release <p>The final stages of the release process involves tagging the "final" release
branch, updating documentation that refers to the release, and updating the branch, updating documentation that refers to the release, and updating the
demo page.</p> demo page.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="updocs">Update Documentation</a></h4> <h4><a name="updocs">Update Documentation</a></h4>
<div class="doc_text"> <div>
<p>Review the documentation and ensure that it is up to date. The "Release <p>Review the documentation and ensure that it is up to date. The "Release
Notes" must be updated to reflect new features, bug fixes, new known issues, Notes" must be updated to reflect new features, bug fixes, new known issues,
@ -534,7 +529,7 @@ $ tar -cvf - clang-<i>X.Y</i>rc1 | gzip &gt; clang-<i>X.Y</i>rc1.src.tar.g
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="tag">Tag the LLVM Final Release</a></h4> <h4><a name="tag">Tag the LLVM Final Release</a></h4>
<div class="doc_text"> <div>
<p>Tag the final release sources using the following procedure:</p> <p>Tag the final release sources using the following procedure:</p>
@ -556,20 +551,20 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="updemo">Update the LLVM Demo Page</a></h3> <h3><a name="updemo">Update the LLVM Demo Page</a></h3>
<div class="doc_text"> <div>
<p>The LLVM demo page must be updated to use the new release. This consists of <p>The LLVM demo page must be updated to use the new release. This consists of
using the new <tt>llvm-gcc</tt> binary and building LLVM.</p> using the new <tt>llvm-gcc</tt> binary and building LLVM.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="webupdates">Update the LLVM Website</a></h4> <h4><a name="webupdates">Update the LLVM Website</a></h4>
<div class="doc_text"> <div>
<p>The website must be updated before the release announcement is sent out. Here <p>The website must be updated before the release announcement is sent out. Here
is what to do:</p> is what to do:</p>
@ -605,12 +600,16 @@ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="announce">Announce the Release</a></h4> <h4><a name="announce">Announce the Release</a></h4>
<div class="doc_text"> <div>
<p>Have Chris send out the release announcement when everything is finished.</p> <p>Have Chris send out the release announcement when everything is finished.</p>
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <address>

18
docs/HowToSubmitABug.html
View File

@ -42,7 +42,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>If you're working with LLVM and run into a bug, we definitely want to know <p>If you're working with LLVM and run into a bug, we definitely want to know
about it. This document describes what you can do to increase the odds of about it. This document describes what you can do to increase the odds of
@ -81,7 +81,7 @@ information:</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>More often than not, bugs in the compiler cause it to crash&mdash;often due <p>More often than not, bugs in the compiler cause it to crash&mdash;often due
to an assertion failure of some sort. The most important to an assertion failure of some sort. The most important
@ -109,14 +109,12 @@ with the following extra command line options:</p>
</ul> </ul>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="front-end">Front-end bugs</a> <a name="front-end">Front-end bugs</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>If the problem is in the front-end, you should re-run the same <p>If the problem is in the front-end, you should re-run the same
<tt>llvm-gcc</tt> command that resulted in the crash, but add the <tt>llvm-gcc</tt> command that resulted in the crash, but add the
@ -141,7 +139,7 @@ has instructions on the best way to use delta.</p>
<a name="ct_optimizer">Compile-time optimization bugs</a> <a name="ct_optimizer">Compile-time optimization bugs</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>If you find that a bug crashes in the optimizer, compile your test-case to a <p>If you find that a bug crashes in the optimizer, compile your test-case to a
<tt>.bc</tt> file by passing "<tt><b>-emit-llvm -O0 -c -o foo.bc</b></tt>". <tt>.bc</tt> file by passing "<tt><b>-emit-llvm -O0 -c -o foo.bc</b></tt>".
@ -175,7 +173,7 @@ that bugpoint emits. If something goes wrong with bugpoint, please submit the
<a name="ct_codegen">Code generator bugs</a> <a name="ct_codegen">Code generator bugs</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>If you find a bug that crashes llvm-gcc in the code generator, compile your <p>If you find a bug that crashes llvm-gcc in the code generator, compile your
source file to a .bc file by passing "<tt><b>-emit-llvm -c -o foo.bc</b></tt>" source file to a .bc file by passing "<tt><b>-emit-llvm -c -o foo.bc</b></tt>"
@ -207,13 +205,15 @@ that bugpoint emits. If something goes wrong with bugpoint, please submit the
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="miscompilations">Miscompilations</a> <a name="miscompilations">Miscompilations</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>If llvm-gcc successfully produces an executable, but that executable doesn't <p>If llvm-gcc successfully produces an executable, but that executable doesn't
run right, this is either a bug in the code or a bug in the run right, this is either a bug in the code or a bug in the
@ -246,7 +246,7 @@ error.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Similarly to debugging incorrect compilation by mis-behaving passes, you can <p>Similarly to debugging incorrect compilation by mis-behaving passes, you can
debug incorrect code generation by either LLC or the JIT, using debug incorrect code generation by either LLC or the JIT, using

471
docs/LangRef.html
View File

File diff suppressed because it is too large Load Diff

31
docs/Lexicon.html
View File

@ -14,7 +14,7 @@
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2>Table Of Contents</h2> <h2>Table Of Contents</h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<table> <table>
<tr><th colspan="8"><b>- <a href="#A">A</a> -</b></th></tr> <tr><th colspan="8"><b>- <a href="#A">A</a> -</b></th></tr>
<tr> <tr>
@ -85,9 +85,10 @@
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2>Definitions</h2> <h2>Definitions</h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="A">- A -</a></h3> <h3><a name="A">- A -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="ADCE"><b>ADCE</b></a></dt> <dt><a name="ADCE"><b>ADCE</b></a></dt>
<dd>Aggressive Dead Code Elimination</dd> <dd>Aggressive Dead Code Elimination</dd>
@ -95,7 +96,7 @@
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="B">- B -</a></h3> <h3><a name="B">- B -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="BURS"><b>BURS</b></a></dt> <dt><a name="BURS"><b>BURS</b></a></dt>
<dd>Bottom Up Rewriting System&mdash;A method of instruction selection for <dd>Bottom Up Rewriting System&mdash;A method of instruction selection for
@ -105,7 +106,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="C">- C -</a></h3> <h3><a name="C">- C -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="CSE"><b>CSE</b></a></dt> <dt><a name="CSE"><b>CSE</b></a></dt>
<dd>Common Subexpression Elimination. An optimization that removes common <dd>Common Subexpression Elimination. An optimization that removes common
@ -117,7 +118,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="D">- D -</a></h3> <h3><a name="D">- D -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="DAG"><b>DAG</b></a></dt> <dt><a name="DAG"><b>DAG</b></a></dt>
<dd>Directed Acyclic Graph</dd> <dd>Directed Acyclic Graph</dd>
@ -137,7 +138,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="G">- G -</a></h3> <h3><a name="G">- G -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="GC"><b>GC</b></a></dt> <dt><a name="GC"><b>GC</b></a></dt>
<dd>Garbage Collection. The practice of using reachability analysis instead <dd>Garbage Collection. The practice of using reachability analysis instead
@ -146,7 +147,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="H">- H -</a></h3> <h3><a name="H">- H -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="Heap"><b>Heap</b></a></dt> <dt><a name="Heap"><b>Heap</b></a></dt>
<dd>In garbage collection, the region of memory which is managed using <dd>In garbage collection, the region of memory which is managed using
@ -155,7 +156,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="I">- I -</a></h3> <h3><a name="I">- I -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="IPA"><b>IPA</b></a></dt> <dt><a name="IPA"><b>IPA</b></a></dt>
<dd>Inter-Procedural Analysis. Refers to any variety of code analysis that <dd>Inter-Procedural Analysis. Refers to any variety of code analysis that
@ -170,7 +171,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="L">- L -</a></h3> <h3><a name="L">- L -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="LCSSA"><b>LCSSA</b></a></dt> <dt><a name="LCSSA"><b>LCSSA</b></a></dt>
<dd>Loop-Closed Static Single Assignment Form</dd> <dd>Loop-Closed Static Single Assignment Form</dd>
@ -184,7 +185,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="M">- M -</a></h3> <h3><a name="M">- M -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="MC"><b>MC</b></a></dt> <dt><a name="MC"><b>MC</b></a></dt>
<dd>Machine Code</dd> <dd>Machine Code</dd>
@ -192,7 +193,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
</div> </div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="O">- O -</a></h3> <h3><a name="O">- O -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="Object_Pointer"><b>Object Pointer</b></a></dt> <dt><a name="Object_Pointer"><b>Object Pointer</b></a></dt>
<dd>A pointer to an object such that the garbage collector is able to trace <dd>A pointer to an object such that the garbage collector is able to trace
@ -203,7 +204,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="P">- P -</a></h3> <h3><a name="P">- P -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="PRE"><b>PRE</b></a></dt> <dt><a name="PRE"><b>PRE</b></a></dt>
<dd>Partial Redundancy Elimination</dd> <dd>Partial Redundancy Elimination</dd>
@ -212,7 +213,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="R">- R -</a></h3> <h3><a name="R">- R -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="RAUW"><b>RAUW</b></a></dt> <dd>An abbreviation for Replace <dt><a name="RAUW"><b>RAUW</b></a></dt> <dd>An abbreviation for Replace
All Uses With. The functions User::replaceUsesOfWith(), All Uses With. The functions User::replaceUsesOfWith(),
@ -235,7 +236,7 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="S">- S -</a></h3> <h3><a name="S">- S -</a></h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><a name="Safe_Point"><b>Safe Point</b></a></dt> <dt><a name="Safe_Point"><b>Safe Point</b></a></dt>
<dd>In garbage collection, it is necessary to identify <a href="#Root">stack <dd>In garbage collection, it is necessary to identify <a href="#Root">stack
@ -261,6 +262,8 @@ href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
function.</dd> function.</dd>
</dl> </dl>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img

33
docs/LinkTimeOptimization.html
View File

@ -41,7 +41,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
LLVM features powerful intermodular optimizations which can be used at link LLVM features powerful intermodular optimizations which can be used at link
time. Link Time Optimization (LTO) is another name for intermodular optimization time. Link Time Optimization (LTO) is another name for intermodular optimization
@ -55,7 +55,7 @@ and design between the LTO optimizer and the linker.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The LLVM Link Time Optimizer provides complete transparency, while doing The LLVM Link Time Optimizer provides complete transparency, while doing
intermodular optimization, in the compiler tool chain. Its main goal is to let intermodular optimization, in the compiler tool chain. Its main goal is to let
@ -69,14 +69,13 @@ the linker and LLVM optimizer helps to do optimizations that are not possible
in other models. The linker input allows the optimizer to avoid relying on in other models. The linker input allows the optimizer to avoid relying on
conservative escape analysis. conservative escape analysis.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="example1">Example of link time optimization</a> <a name="example1">Example of link time optimization</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The following example illustrates the advantages of LTO's integrated <p>The following example illustrates the advantages of LTO's integrated
approach and clean interface. This example requires a system linker which approach and clean interface. This example requires a system linker which
supports LTO through the interface described in this document. Here, supports LTO through the interface described in this document. Here,
@ -149,7 +148,7 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
<a name="alternative_approaches">Alternative Approaches</a> <a name="alternative_approaches">Alternative Approaches</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt><b>Compiler driver invokes link time optimizer separately.</b></dt> <dt><b>Compiler driver invokes link time optimizer separately.</b></dt>
<dd>In this model the link time optimizer is not able to take advantage of <dd>In this model the link time optimizer is not able to take advantage of
@ -175,12 +174,14 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
</dl> </dl>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="multiphase">Multi-phase communication between libLTO and linker</a> <a name="multiphase">Multi-phase communication between libLTO and linker</a>
</h2> </h2>
<div class="doc_text"> <div>
<p>The linker collects information about symbol defininitions and uses in <p>The linker collects information about symbol defininitions and uses in
various link objects which is more accurate than any information collected various link objects which is more accurate than any information collected
by other tools during typical build cycles. The linker collects this by other tools during typical build cycles. The linker collects this
@ -192,14 +193,13 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
Our goal is to take advantage of tight integration between the linker and Our goal is to take advantage of tight integration between the linker and
the optimizer by sharing this information during various linking phases. the optimizer by sharing this information during various linking phases.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="phase1">Phase 1 : Read LLVM Bitcode Files</a> <a name="phase1">Phase 1 : Read LLVM Bitcode Files</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The linker first reads all object files in natural order and collects <p>The linker first reads all object files in natural order and collects
symbol information. This includes native object files as well as LLVM bitcode symbol information. This includes native object files as well as LLVM bitcode
files. To minimize the cost to the linker in the case that all .o files files. To minimize the cost to the linker in the case that all .o files
@ -223,7 +223,7 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
<a name="phase2">Phase 2 : Symbol Resolution</a> <a name="phase2">Phase 2 : Symbol Resolution</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>In this stage, the linker resolves symbols using global symbol table. <p>In this stage, the linker resolves symbols using global symbol table.
It may report undefined symbol errors, read archive members, replace It may report undefined symbol errors, read archive members, replace
weak symbols, etc. The linker is able to do this seamlessly even though it weak symbols, etc. The linker is able to do this seamlessly even though it
@ -236,7 +236,7 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
<h3> <h3>
<a name="phase3">Phase 3 : Optimize Bitcode Files</a> <a name="phase3">Phase 3 : Optimize Bitcode Files</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>After symbol resolution, the linker tells the LTO shared object which <p>After symbol resolution, the linker tells the LTO shared object which
symbols are needed by native object files. In the example above, the linker symbols are needed by native object files. In the example above, the linker
reports that only <tt>foo1()</tt> is used by native object files using reports that only <tt>foo1()</tt> is used by native object files using
@ -252,7 +252,7 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
<a name="phase4">Phase 4 : Symbol Resolution after optimization</a> <a name="phase4">Phase 4 : Symbol Resolution after optimization</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>In this phase, the linker reads optimized a native object file and <p>In this phase, the linker reads optimized a native object file and
updates the internal global symbol table to reflect any changes. The linker updates the internal global symbol table to reflect any changes. The linker
also collects information about any changes in use of external symbols by also collects information about any changes in use of external symbols by
@ -264,12 +264,14 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
bitcode files.</p> bitcode files.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="lto">libLTO</a> <a name="lto">libLTO</a>
</h2> </h2>
<div class="doc_text"> <div>
<p><tt>libLTO</tt> is a shared object that is part of the LLVM tools, and <p><tt>libLTO</tt> is a shared object that is part of the LLVM tools, and
is intended for use by a linker. <tt>libLTO</tt> provides an abstract C is intended for use by a linker. <tt>libLTO</tt> provides an abstract C
interface to use the LLVM interprocedural optimizer without exposing details interface to use the LLVM interprocedural optimizer without exposing details
@ -278,14 +280,13 @@ $ llvm-gcc a.o main.o -o main # &lt;-- standard link command without any modific
be possible for a completely different compilation technology to provide be possible for a completely different compilation technology to provide
a different libLTO that works with their object files and the standard a different libLTO that works with their object files and the standard
linker tool.</p> linker tool.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="lto_module_t">lto_module_t</a> <a name="lto_module_t">lto_module_t</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>A non-native object file is handled via an <tt>lto_module_t</tt>. <p>A non-native object file is handled via an <tt>lto_module_t</tt>.
The following functions allow the linker to check if a file (on disk The following functions allow the linker to check if a file (on disk
@ -329,7 +330,7 @@ lto_module_get_symbol_attribute(lto_module_t, unsigned int)
<a name="lto_code_gen_t">lto_code_gen_t</a> <a name="lto_code_gen_t">lto_code_gen_t</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Once the linker has loaded each non-native object files into an <p>Once the linker has loaded each non-native object files into an
<tt>lto_module_t</tt>, it can request libLTO to process them all and <tt>lto_module_t</tt>, it can request libLTO to process them all and
@ -371,6 +372,8 @@ of the native object files.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

97
docs/MakefileGuide.html
View File

@ -80,7 +80,7 @@
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document provides <em>usage</em> information about the LLVM makefile <p>This document provides <em>usage</em> information about the LLVM makefile
system. While loosely patterned after the BSD makefile system, LLVM has taken system. While loosely patterned after the BSD makefile system, LLVM has taken
a departure from BSD in order to implement additional features needed by LLVM. a departure from BSD in order to implement additional features needed by LLVM.
@ -102,17 +102,16 @@
<h2><a name="general">General Concepts</a></h2> <h2><a name="general">General Concepts</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The LLVM Makefile System is the component of LLVM that is responsible for <p>The LLVM Makefile System is the component of LLVM that is responsible for
building the software, testing it, generating distributions, checking those building the software, testing it, generating distributions, checking those
distributions, installing and uninstalling, etc. It consists of a several distributions, installing and uninstalling, etc. It consists of a several
files throughout the source tree. These files and other general concepts are files throughout the source tree. These files and other general concepts are
described in this section.</p> described in this section.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="projects">Projects</a></h3> <h3><a name="projects">Projects</a></h3>
<div class="doc_text"> <div>
<p>The LLVM Makefile System is quite generous. It not only builds its own <p>The LLVM Makefile System is quite generous. It not only builds its own
software, but it can build yours too. Built into the system is knowledge of software, but it can build yours too. Built into the system is knowledge of
the <tt>llvm/projects</tt> directory. Any directory under <tt>projects</tt> the <tt>llvm/projects</tt> directory. Any directory under <tt>projects</tt>
@ -130,7 +129,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="varvalues">Variable Values</a></h3> <h3><a name="varvalues">Variable Values</a></h3>
<div class="doc_text"> <div>
<p>To use the makefile system, you simply create a file named <p>To use the makefile system, you simply create a file named
<tt>Makefile</tt> in your directory and declare values for certain variables. <tt>Makefile</tt> in your directory and declare values for certain variables.
The variables and values that you select determine what the makefile system The variables and values that you select determine what the makefile system
@ -140,15 +139,14 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="including">Including Makefiles</a></h3> <h3><a name="including">Including Makefiles</a></h3>
<div class="doc_text"> <div>
<p>Setting variables alone is not enough. You must include into your Makefile <p>Setting variables alone is not enough. You must include into your Makefile
additional files that provide the rules of the LLVM Makefile system. The additional files that provide the rules of the LLVM Makefile system. The
various files involved are described in the sections that follow.</p> various files involved are described in the sections that follow.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="Makefile">Makefile</a></h4> <h4><a name="Makefile">Makefile</a></h4>
<div class="doc_text"> <div>
<p>Each directory to participate in the build needs to have a file named <p>Each directory to participate in the build needs to have a file named
<tt>Makefile</tt>. This is the file first read by <tt>make</tt>. It has three <tt>Makefile</tt>. This is the file first read by <tt>make</tt>. It has three
sections:</p> sections:</p>
@ -164,7 +162,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="Makefile.common">Makefile.common</a></h4> <h4><a name="Makefile.common">Makefile.common</a></h4>
<div class="doc_text"> <div>
<p>Every project must have a <tt>Makefile.common</tt> file at its top source <p>Every project must have a <tt>Makefile.common</tt> file at its top source
directory. This file serves three purposes:</p> directory. This file serves three purposes:</p>
<ol> <ol>
@ -182,7 +180,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="Makefile.config">Makefile.config</a></h4> <h4><a name="Makefile.config">Makefile.config</a></h4>
<div class="doc_text"> <div>
<p>Every project must have a <tt>Makefile.config</tt> at the top of its <p>Every project must have a <tt>Makefile.config</tt> at the top of its
<em>build</em> directory. This file is <b>generated</b> by the <em>build</em> directory. This file is <b>generated</b> by the
<tt>configure</tt> script from the pattern provided by the <tt>configure</tt> script from the pattern provided by the
@ -195,7 +193,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="Makefile.rules">Makefile.rules</a></h4> <h4><a name="Makefile.rules">Makefile.rules</a></h4>
<div class="doc_text"> <div>
<p>This file, located at <tt>$(LLVM_SRC_ROOT)/Makefile.rules</tt> is the heart <p>This file, located at <tt>$(LLVM_SRC_ROOT)/Makefile.rules</tt> is the heart
of the LLVM Makefile System. It provides all the logic, dependencies, and of the LLVM Makefile System. It provides all the logic, dependencies, and
rules for building the targets supported by the system. What it does largely rules for building the targets supported by the system. What it does largely
@ -203,9 +201,11 @@
have been set <em>before</em> <tt>Makefile.rules</tt> is included. have been set <em>before</em> <tt>Makefile.rules</tt> is included.
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="Comments">Comments</a></h3> <h3><a name="Comments">Comments</a></h3>
<div class="doc_text"> <div>
<p>User Makefiles need not have comments in them unless the construction is <p>User Makefiles need not have comments in them unless the construction is
unusual or it does not strictly follow the rules and patterns of the LLVM unusual or it does not strictly follow the rules and patterns of the LLVM
makefile system. Makefile comments are invoked with the pound (#) character. makefile system. Makefile comments are invoked with the pound (#) character.
@ -213,19 +213,20 @@
by <tt>make</tt>.</p> by <tt>make</tt>.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="tutorial">Tutorial</a></h2> <h2><a name="tutorial">Tutorial</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section provides some examples of the different kinds of modules you <p>This section provides some examples of the different kinds of modules you
can build with the LLVM makefile system. In general, each directory you can build with the LLVM makefile system. In general, each directory you
provide will build a single object although that object may be composed of provide will build a single object although that object may be composed of
additionally compiled components.</p> additionally compiled components.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="libraries">Libraries</a></h3> <h3><a name="libraries">Libraries</a></h3>
<div class="doc_text"> <div>
<p>Only a few variable definitions are needed to build a regular library. <p>Only a few variable definitions are needed to build a regular library.
Normally, the makefile system will build all the software into a single Normally, the makefile system will build all the software into a single
<tt>libname.o</tt> (pre-linked) object. This means the library is not <tt>libname.o</tt> (pre-linked) object. This means the library is not
@ -254,11 +255,10 @@
<tt>-load</tt> option. See the <tt>-load</tt> option. See the
<a href="WritingAnLLVMPass.html#makefile">WritingAnLLVMPass.html</a> document <a href="WritingAnLLVMPass.html#makefile">WritingAnLLVMPass.html</a> document
for an example of why you might want to do this. for an example of why you might want to do this.
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="BCModules">Bitcode Modules</a></h4> <h4><a name="BCModules">Bitcode Modules</a></h4>
<div class="doc_text"> <div>
<p>In some situations, it is desirable to build a single bitcode module from <p>In some situations, it is desirable to build a single bitcode module from
a variety of sources, instead of an archive, shared library, or bitcode a variety of sources, instead of an archive, shared library, or bitcode
library. Bitcode modules can be specified in addition to any of the other library. Bitcode modules can be specified in addition to any of the other
@ -281,7 +281,7 @@
<h4> <h4>
<a name="LoadableModules">Loadable Modules</a> <a name="LoadableModules">Loadable Modules</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>In some situations, you need to create a loadable module. Loadable modules <p>In some situations, you need to create a loadable module. Loadable modules
can be loaded into programs like <tt>opt</tt> or <tt>llc</tt> to specify can be loaded into programs like <tt>opt</tt> or <tt>llc</tt> to specify
additional passes to run or targets to support. Loadable modules are also additional passes to run or targets to support. Loadable modules are also
@ -309,9 +309,11 @@
library which is part of <tt>lib/System</tt> implementation.</p> library which is part of <tt>lib/System</tt> implementation.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="tools">Tools</a></h3> <h3><a name="tools">Tools</a></h3>
<div class="doc_text"> <div>
<p>For building executable programs (tools), you must provide the name of the <p>For building executable programs (tools), you must provide the name of the
tool and the names of the libraries you wish to link with the tool. For tool and the names of the libraries you wish to link with the tool. For
example:</p> example:</p>
@ -342,11 +344,10 @@
syntax is used. Note that in order to use the <tt>.a</tt> suffix, the library syntax is used. Note that in order to use the <tt>.a</tt> suffix, the library
in question must have been built with the <tt>ARCHIVE_LIBRARY</tt> option set. in question must have been built with the <tt>ARCHIVE_LIBRARY</tt> option set.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="JIT">JIT Tools</a></h4> <h4><a name="JIT">JIT Tools</a></h4>
<div class="doc_text"> <div>
<p>Many tools will want to use the JIT features of LLVM. To do this, you <p>Many tools will want to use the JIT features of LLVM. To do this, you
simply specify that you want an execution 'engine', and the makefiles will simply specify that you want an execution 'engine', and the makefiles will
automatically link in the appropriate JIT for the host or an interpreter automatically link in the appropriate JIT for the host or an interpreter
@ -365,11 +366,15 @@
</tt></pre> </tt></pre>
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="targets">Targets Supported</a></h2> <h2><a name="targets">Targets Supported</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This section describes each of the targets that can be built using the LLVM <p>This section describes each of the targets that can be built using the LLVM
Makefile system. Any target can be invoked from any directory but not all are Makefile system. Any target can be invoked from any directory but not all are
applicable to a given directory (e.g. "check", "dist" and "install" will applicable to a given directory (e.g. "check", "dist" and "install" will
@ -424,11 +429,10 @@
<td>Remove built objects from installation directory. <td>Remove built objects from installation directory.
</td></tr> </td></tr>
</table> </table>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="all">all (default)</a></h3> <h3><a name="all">all (default)</a></h3>
<div class="doc_text"> <div>
<p>When you invoke <tt>make</tt> with no arguments, you are implicitly <p>When you invoke <tt>make</tt> with no arguments, you are implicitly
instructing it to seek the "all" target (goal). This target is used for instructing it to seek the "all" target (goal). This target is used for
building the software recursively and will do different things in different building the software recursively and will do different things in different
@ -439,14 +443,14 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="all-local">all-local</a></h3> <h3><a name="all-local">all-local</a></h3>
<div class="doc_text"> <div>
<p>This target is the same as <a href="#all">all</a> but it operates only on <p>This target is the same as <a href="#all">all</a> but it operates only on
the current directory instead of recursively.</p> the current directory instead of recursively.</p>
</div> </div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="check">check</a></h3> <h3><a name="check">check</a></h3>
<div class="doc_text"> <div>
<p>This target can be invoked from anywhere within a project's directories <p>This target can be invoked from anywhere within a project's directories
but always invokes the <a href="#check-local"><tt>check-local</tt></a> target but always invokes the <a href="#check-local"><tt>check-local</tt></a> target
in the project's <tt>test</tt> directory, if it exists and has a in the project's <tt>test</tt> directory, if it exists and has a
@ -463,7 +467,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="check-local">check-local</a></h3> <h3><a name="check-local">check-local</a></h3>
<div class="doc_text"> <div>
<p>This target should be implemented by the <tt>Makefile</tt> in the project's <p>This target should be implemented by the <tt>Makefile</tt> in the project's
<tt>test</tt> directory. It is invoked by the <tt>check</tt> target elsewhere. <tt>test</tt> directory. It is invoked by the <tt>check</tt> target elsewhere.
Each project is free to define the actions of <tt>check-local</tt> as Each project is free to define the actions of <tt>check-local</tt> as
@ -474,7 +478,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="clean">clean</a></h3> <h3><a name="clean">clean</a></h3>
<div class="doc_text"> <div>
<p>This target cleans the build directory, recursively removing all things <p>This target cleans the build directory, recursively removing all things
that the Makefile builds. The cleaning rules have been made guarded so they that the Makefile builds. The cleaning rules have been made guarded so they
shouldn't go awry (via <tt>rm -f $(UNSET_VARIABLE)/*</tt> which will attempt shouldn't go awry (via <tt>rm -f $(UNSET_VARIABLE)/*</tt> which will attempt
@ -483,14 +487,14 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="clean-local">clean-local</a></h3> <h3><a name="clean-local">clean-local</a></h3>
<div class="doc_text"> <div>
<p>This target does the same thing as <tt>clean</tt> but only for the current <p>This target does the same thing as <tt>clean</tt> but only for the current
(local) directory.</p> (local) directory.</p>
</div> </div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="dist">dist</a></h3> <h3><a name="dist">dist</a></h3>
<div class="doc_text"> <div>
<p>This target builds a distribution tarball. It first builds the entire <p>This target builds a distribution tarball. It first builds the entire
project using the <tt>all</tt> target and then tars up the necessary files and project using the <tt>all</tt> target and then tars up the necessary files and
compresses it. The generated tarball is sufficient for a casual source compresses it. The generated tarball is sufficient for a casual source
@ -499,7 +503,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="dist-check">dist-check</a></h3> <h3><a name="dist-check">dist-check</a></h3>
<div class="doc_text"> <div>
<p>This target does the same thing as the <tt>dist</tt> target but also checks <p>This target does the same thing as the <tt>dist</tt> target but also checks
the distribution tarball. The check is made by unpacking the tarball to a new the distribution tarball. The check is made by unpacking the tarball to a new
directory, configuring it, building it, installing it, and then verifying that directory, configuring it, building it, installing it, and then verifying that
@ -511,7 +515,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="dist-clean">dist-clean</a></h3> <h3><a name="dist-clean">dist-clean</a></h3>
<div class="doc_text"> <div>
<p>This is a special form of the <tt>clean</tt> clean target. It performs a <p>This is a special form of the <tt>clean</tt> clean target. It performs a
normal <tt>clean</tt> but also removes things pertaining to building the normal <tt>clean</tt> but also removes things pertaining to building the
distribution.</p> distribution.</p>
@ -519,7 +523,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="install">install</a></h3> <h3><a name="install">install</a></h3>
<div class="doc_text"> <div>
<p>This target finalizes shared objects and executables and copies all <p>This target finalizes shared objects and executables and copies all
libraries, headers, executables and documentation to the directory given libraries, headers, executables and documentation to the directory given
with the <tt>--prefix</tt> option to <tt>configure</tt>. When completed, with the <tt>--prefix</tt> option to <tt>configure</tt>. When completed,
@ -537,7 +541,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="preconditions">preconditions</a></h3> <h3><a name="preconditions">preconditions</a></h3>
<div class="doc_text"> <div>
<p>This utility target checks to see if the <tt>Makefile</tt> in the object <p>This utility target checks to see if the <tt>Makefile</tt> in the object
directory is older than the <tt>Makefile</tt> in the source directory and directory is older than the <tt>Makefile</tt> in the source directory and
copies it if so. It also reruns the <tt>configure</tt> script if that needs to copies it if so. It also reruns the <tt>configure</tt> script if that needs to
@ -548,14 +552,14 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="printvars">printvars</a></h3> <h3><a name="printvars">printvars</a></h3>
<div class="doc_text"> <div>
<p>This utility target just causes the LLVM makefiles to print out some of <p>This utility target just causes the LLVM makefiles to print out some of
the makefile variables so that you can double check how things are set. </p> the makefile variables so that you can double check how things are set. </p>
</div> </div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="reconfigure">reconfigure</a></h3> <h3><a name="reconfigure">reconfigure</a></h3>
<div class="doc_text"> <div>
<p>This utility target will force a reconfigure of LLVM or your project. It <p>This utility target will force a reconfigure of LLVM or your project. It
simply runs <tt>$(PROJ_OBJ_ROOT)/config.status --recheck</tt> to rerun the simply runs <tt>$(PROJ_OBJ_ROOT)/config.status --recheck</tt> to rerun the
configuration tests and rebuild the configured files. This isn't generally configuration tests and rebuild the configured files. This isn't generally
@ -565,7 +569,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="spotless">spotless</a></h3> <h3><a name="spotless">spotless</a></h3>
<div class="doc_text"> <div>
<p>This utility target, only available when <tt>$(PROJ_OBJ_ROOT)</tt> is not <p>This utility target, only available when <tt>$(PROJ_OBJ_ROOT)</tt> is not
the same as <tt>$(PROJ_SRC_ROOT)</tt>, will completely clean the the same as <tt>$(PROJ_SRC_ROOT)</tt>, will completely clean the
<tt>$(PROJ_OBJ_ROOT)</tt> directory by removing its content entirely and <tt>$(PROJ_OBJ_ROOT)</tt> directory by removing its content entirely and
@ -577,7 +581,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="tags">tags</a></h3> <h3><a name="tags">tags</a></h3>
<div class="doc_text"> <div>
<p>This target will generate a <tt>TAGS</tt> file in the top-level source <p>This target will generate a <tt>TAGS</tt> file in the top-level source
directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file
provides an index of symbol definitions so that the editor can jump you to the provides an index of symbol definitions so that the editor can jump you to the
@ -586,17 +590,19 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="uninstall">uninstall</a></h3> <h3><a name="uninstall">uninstall</a></h3>
<div class="doc_text"> <div>
<p>This target is the opposite of the <tt>install</tt> target. It removes the <p>This target is the opposite of the <tt>install</tt> target. It removes the
header, library and executable files from the installation directories. Note header, library and executable files from the installation directories. Note
that the directories themselves are not removed because it is not guaranteed that the directories themselves are not removed because it is not guaranteed
that LLVM is the only thing installing there (e.g. --prefix=/usr).</p> that LLVM is the only thing installing there (e.g. --prefix=/usr).</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="variables">Variables</a></h2> <h2><a name="variables">Variables</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Variables are used to tell the LLVM Makefile System what to do and to <p>Variables are used to tell the LLVM Makefile System what to do and to
obtain information from it. Variables are also used internally by the LLVM obtain information from it. Variables are also used internally by the LLVM
Makefile System. Variable names that contain only the upper case alphabetic Makefile System. Variable names that contain only the upper case alphabetic
@ -604,11 +610,10 @@
variables are internal to the LLVM Makefile System and should not be relied variables are internal to the LLVM Makefile System and should not be relied
upon nor modified. The sections below describe how to use the LLVM Makefile upon nor modified. The sections below describe how to use the LLVM Makefile
variables.</p> variables.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="setvars">Control Variables</a></h3> <h3><a name="setvars">Control Variables</a></h3>
<div class="doc_text"> <div>
<p>Variables listed in the table below should be set <em>before</em> the <p>Variables listed in the table below should be set <em>before</em> the
inclusion of <a href="#Makefile.common"><tt>$(LEVEL)/Makefile.common</tt></a>. inclusion of <a href="#Makefile.common"><tt>$(LEVEL)/Makefile.common</tt></a>.
These variables provide input to the LLVM make system that tell it what to do These variables provide input to the LLVM make system that tell it what to do
@ -761,7 +766,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="overvars">Override Variables</a></h3> <h3><a name="overvars">Override Variables</a></h3>
<div class="doc_text"> <div>
<p>Override variables can be used to override the default <p>Override variables can be used to override the default
values provided by the LLVM makefile system. These variables can be set in values provided by the LLVM makefile system. These variables can be set in
several ways:</p> several ways:</p>
@ -867,7 +872,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="getvars">Readable Variables</a></h3> <h3><a name="getvars">Readable Variables</a></h3>
<div class="doc_text"> <div>
<p>Variables listed in the table below can be used by the user's Makefile but <p>Variables listed in the table below can be used by the user's Makefile but
should not be changed. Changing the value will generally cause the build to go should not be changed. Changing the value will generally cause the build to go
wrong, so don't do it.</p> wrong, so don't do it.</p>
@ -938,7 +943,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="intvars">Internal Variables</a></h3> <h3><a name="intvars">Internal Variables</a></h3>
<div class="doc_text"> <div>
<p>Variables listed below are used by the LLVM Makefile System <p>Variables listed below are used by the LLVM Makefile System
and considered internal. You should not use these variables under any and considered internal. You should not use these variables under any
circumstances.</p> circumstances.</p>
@ -1016,6 +1021,8 @@
</tt></p> </tt></p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <address>

10
docs/Packaging.html
View File

@ -19,7 +19,7 @@
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="overview">Overview</a></h2> <h2><a name="overview">Overview</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>LLVM sets certain default configure options to make sure our developers don't <p>LLVM sets certain default configure options to make sure our developers don't
break things for constrained platforms. These settings are not optimal for most break things for constrained platforms. These settings are not optimal for most
@ -36,7 +36,7 @@ developed against each.
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="compilation">Compile Flags</a></h2> <h2><a name="compilation">Compile Flags</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>LLVM runs much more quickly when it's optimized and assertions are removed. <p>LLVM runs much more quickly when it's optimized and assertions are removed.
However, such a build is currently incompatible with users who build without However, such a build is currently incompatible with users who build without
@ -67,7 +67,7 @@ versions of LLVM in parallel. The following configure flags are relevant:
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="cxx-features">C++ Features</a></h2> <h2><a name="cxx-features">C++ Features</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<dl> <dl>
<dt>RTTI</dt><dd>LLVM disables RTTI by default. Add <tt>REQUIRES_RTTI=1</tt> <dt>RTTI</dt><dd>LLVM disables RTTI by default. Add <tt>REQUIRES_RTTI=1</tt>
@ -80,7 +80,7 @@ versions of LLVM in parallel. The following configure flags are relevant:
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="shared-library">Shared Library</a></h2> <h2><a name="shared-library">Shared Library</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>Configure with <tt>--enable-shared</tt> to build <p>Configure with <tt>--enable-shared</tt> to build
<tt>libLLVM-<var>major</var>.<var>minor</var>.(so|dylib)</tt> and link the tools <tt>libLLVM-<var>major</var>.<var>minor</var>.(so|dylib)</tt> and link the tools
@ -91,7 +91,7 @@ against it. This saves lots of binary size at the cost of some startup time.
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="deps">Dependencies</a></h2> <h2><a name="deps">Dependencies</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<dl> <dl>
<dt><tt>--enable-libffi</tt></dt><dd>Depend on <a <dt><tt>--enable-libffi</tt></dt><dd>Depend on <a

257
docs/Passes.html
View File

File diff suppressed because it is too large Load Diff

324
docs/ProgrammersManual.html
View File

File diff suppressed because it is too large Load Diff

26
docs/Projects.html
View File

@ -33,7 +33,7 @@
<h2><a name="overview">Overview</a></h2> <h2><a name="overview">Overview</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The LLVM build system is designed to facilitate the building of third party <p>The LLVM build system is designed to facilitate the building of third party
projects that use LLVM header files, libraries, and tools. In order to use projects that use LLVM header files, libraries, and tools. In order to use
@ -78,7 +78,7 @@ provide enough information on how to write your own Makefiles.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Follow these simple steps to start your project:</p> <p>Follow these simple steps to start your project:</p>
@ -150,7 +150,7 @@ project should build.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>In order to use the LLVM build system, you will want to organize your <p>In order to use the LLVM build system, you will want to organize your
source code so that it can benefit from the build system's features. source code so that it can benefit from the build system's features.
@ -235,21 +235,19 @@ your <b>tools</b> directory.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The LLVM build system provides a convenient way to build libraries and <p>The LLVM build system provides a convenient way to build libraries and
executables. Most of your project Makefiles will only need to define a few executables. Most of your project Makefiles will only need to define a few
variables. Below is a list of the variables one can set and what they can variables. Below is a list of the variables one can set and what they can
do:</p> do:</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="reqVars">Required Variables</a> <a name="reqVars">Required Variables</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt>LEVEL <dt>LEVEL
@ -267,7 +265,7 @@ do:</p>
<a name="varsBuildDir">Variables for Building Subdirectories</a> <a name="varsBuildDir">Variables for Building Subdirectories</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt>DIRS <dt>DIRS
@ -298,7 +296,7 @@ do:</p>
<a name="varsBuildLib">Variables for Building Libraries</a> <a name="varsBuildLib">Variables for Building Libraries</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt>LIBRARYNAME <dt>LIBRARYNAME
@ -329,7 +327,7 @@ do:</p>
<a name="varsBuildProg">Variables for Building Programs</a> <a name="varsBuildProg">Variables for Building Programs</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt>TOOLNAME <dt>TOOLNAME
@ -372,7 +370,7 @@ do:</p>
<a name="miscVars">Miscellaneous Variables</a> <a name="miscVars">Miscellaneous Variables</a>
</h3> </h3>
<div class="doc_text"> <div>
<dl> <dl>
<dt>ExtraSource <dt>ExtraSource
@ -398,13 +396,15 @@ do:</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="objcode">Placement of Object Code</a> <a name="objcode">Placement of Object Code</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The final location of built libraries and executables will depend upon <p>The final location of built libraries and executables will depend upon
whether you do a Debug, Release, or Profile build.</p> whether you do a Debug, Release, or Profile build.</p>
@ -432,7 +432,7 @@ whether you do a Debug, Release, or Profile build.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>If you have any questions or need any help creating an LLVM project, <p>If you have any questions or need any help creating an LLVM project,
the LLVM team would be more than happy to help. You can always post your the LLVM team would be more than happy to help. You can always post your

104
docs/SourceLevelDebugging.html
View File

@ -71,7 +71,7 @@ height="369">
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This document is the central repository for all information pertaining to <p>This document is the central repository for all information pertaining to
debug information in LLVM. It describes the <a href="#format">actual format debug information in LLVM. It describes the <a href="#format">actual format
@ -80,14 +80,12 @@ height="369">
Further, this document provides specific examples of what debug information Further, this document provides specific examples of what debug information
for C/C++ looks like.</p> for C/C++ looks like.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="phil">Philosophy behind LLVM debugging information</a> <a name="phil">Philosophy behind LLVM debugging information</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The idea of the LLVM debugging information is to capture how the important <p>The idea of the LLVM debugging information is to capture how the important
pieces of the source-language's Abstract Syntax Tree map onto LLVM code. pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
@ -137,7 +135,7 @@ height="369">
<a name="consumers">Debug information consumers</a> <a name="consumers">Debug information consumers</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The role of debug information is to provide meta information normally <p>The role of debug information is to provide meta information normally
stripped away during the compilation process. This meta information provides stripped away during the compilation process. This meta information provides
@ -161,7 +159,7 @@ height="369">
<a name="debugopt">Debugging optimized code</a> <a name="debugopt">Debugging optimized code</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>An extremely high priority of LLVM debugging information is to make it <p>An extremely high priority of LLVM debugging information is to make it
interact well with optimizations and analysis. In particular, the LLVM debug interact well with optimizations and analysis. In particular, the LLVM debug
@ -226,13 +224,15 @@ height="369">
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="format">Debugging information format</a> <a name="format">Debugging information format</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>LLVM debugging information has been carefully designed to make it possible <p>LLVM debugging information has been carefully designed to make it possible
for the optimizer to optimize the program and debugging information without for the optimizer to optimize the program and debugging information without
@ -265,14 +265,12 @@ height="369">
common to any source-language. The <a href="#ccxx_frontend">next section</a> common to any source-language. The <a href="#ccxx_frontend">next section</a>
describes the data layout conventions used by the C and C++ front-ends.</p> describes the data layout conventions used by the C and C++ front-ends.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="debug_info_descriptors">Debug information descriptors</a> <a name="debug_info_descriptors">Debug information descriptors</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>In consideration of the complexity and volume of debug information, LLVM <p>In consideration of the complexity and volume of debug information, LLVM
provides a specification for well formed debug descriptors. </p> provides a specification for well formed debug descriptors. </p>
@ -312,14 +310,12 @@ height="369">
<p>The details of the various descriptors follow.</p> <p>The details of the various descriptors follow.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4> <h4>
<a name="format_compile_units">Compile unit descriptors</a> <a name="format_compile_units">Compile unit descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -355,7 +351,7 @@ height="369">
<a name="format_files">File descriptors</a> <a name="format_files">File descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -384,7 +380,7 @@ height="369">
<a name="format_global_variables">Global variable descriptors</a> <a name="format_global_variables">Global variable descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -417,7 +413,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p>
<a name="format_subprograms">Subprogram descriptors</a> <a name="format_subprograms">Subprogram descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -461,7 +457,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p>
<a name="format_blocks">Block descriptors</a> <a name="format_blocks">Block descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -487,7 +483,7 @@ global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p>
<a name="format_basic_type">Basic type descriptors</a> <a name="format_basic_type">Basic type descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -539,7 +535,7 @@ DW_ATE_unsigned_char = 8
<a name="format_derived_type">Derived type descriptors</a> <a name="format_derived_type">Derived type descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -611,7 +607,7 @@ DW_TAG_restrict_type = 55
<a name="format_composite_type">Composite type descriptors</a> <a name="format_composite_type">Composite type descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -698,7 +694,7 @@ DW_TAG_inheritance = 28
<a name="format_subrange">Subrange descriptors</a> <a name="format_subrange">Subrange descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -724,7 +720,7 @@ DW_TAG_inheritance = 28
<a name="format_enumeration">Enumerator descriptors</a> <a name="format_enumeration">Enumerator descriptors</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -748,7 +744,7 @@ DW_TAG_inheritance = 28
<a name="format_variables">Local variables</a> <a name="format_variables">Local variables</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -787,24 +783,24 @@ DW_TAG_return_variable = 258
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="format_common_intrinsics">Debugger intrinsic functions</a> <a name="format_common_intrinsics">Debugger intrinsic functions</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
provide debug information at various points in generated code.</p> provide debug information at various points in generated code.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4> <h4>
<a name="format_common_declare">llvm.dbg.declare</a> <a name="format_common_declare">llvm.dbg.declare</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata) void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
</pre> </pre>
@ -819,7 +815,7 @@ DW_TAG_return_variable = 258
<a name="format_common_value">llvm.dbg.value</a> <a name="format_common_value">llvm.dbg.value</a>
</h4> </h4>
<div class="doc_text"> <div>
<pre> <pre>
void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata) void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
</pre> </pre>
@ -831,12 +827,14 @@ DW_TAG_return_variable = 258
user source variable. </p> user source variable. </p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="format_common_lifetime">Object lifetimes and scoping</a> <a name="format_common_lifetime">Object lifetimes and scoping</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>In many languages, the local variables in functions can have their lifetimes <p>In many languages, the local variables in functions can have their lifetimes
or scopes limited to a subset of a function. In the C family of languages, or scopes limited to a subset of a function. In the C family of languages,
for example, variables are only live (readable and writable) within the for example, variables are only live (readable and writable) within the
@ -994,13 +992,15 @@ call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="ccxx_frontend">C/C++ front-end specific debug information</a> <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The C and C++ front-ends represent information about the program in a format <p>The C and C++ front-ends represent information about the program in a format
that is effectively identical that is effectively identical
@ -1021,14 +1021,12 @@ call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
<p>The following sections provide examples of various C/C++ constructs and the <p>The following sections provide examples of various C/C++ constructs and the
debug information that would best describe those constructs.</p> debug information that would best describe those constructs.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="ccxx_compile_units">C/C++ source file information</a> <a name="ccxx_compile_units">C/C++ source file information</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
in the directory <tt>/Users/mine/sources</tt>, the following code:</p> in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
@ -1106,7 +1104,7 @@ using <tt>Instruction::getMetadata()</tt> and
<a name="ccxx_global_variable">C/C++ global variable information</a> <a name="ccxx_global_variable">C/C++ global variable information</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Given an integer global variable declared as follows:</p> <p>Given an integer global variable declared as follows:</p>
@ -1176,7 +1174,7 @@ int MyGlobal = 100;
<a name="ccxx_subprogram">C/C++ function information</a> <a name="ccxx_subprogram">C/C++ function information</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Given a function declared as follows:</p> <p>Given a function declared as follows:</p>
@ -1233,18 +1231,16 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_types">C/C++ basic types</a> <a name="ccxx_basic_types">C/C++ basic types</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The following are the basic type descriptors for C/C++ core types:</p> <p>The following are the basic type descriptors for C/C++ core types:</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4> <h4>
<a name="ccxx_basic_type_bool">bool</a> <a name="ccxx_basic_type_bool">bool</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1270,7 +1266,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_char">char</a> <a name="ccxx_basic_char">char</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1296,7 +1292,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_unsigned_char">unsigned char</a> <a name="ccxx_basic_unsigned_char">unsigned char</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1322,7 +1318,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_short">short</a> <a name="ccxx_basic_short">short</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1348,7 +1344,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_unsigned_short">unsigned short</a> <a name="ccxx_basic_unsigned_short">unsigned short</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1374,7 +1370,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_int">int</a> <a name="ccxx_basic_int">int</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1399,7 +1395,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_unsigned_int">unsigned int</a> <a name="ccxx_basic_unsigned_int">unsigned int</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1425,7 +1421,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_long_long">long long</a> <a name="ccxx_basic_long_long">long long</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1451,7 +1447,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_unsigned_long_long">unsigned long long</a> <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1477,7 +1473,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_float">float</a> <a name="ccxx_basic_float">float</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1503,7 +1499,7 @@ define i32 @main(i32 %argc, i8** %argv) {
<a name="ccxx_basic_double">double</a> <a name="ccxx_basic_double">double</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"> <div class="doc_code">
<pre> <pre>
@ -1524,12 +1520,14 @@ define i32 @main(i32 %argc, i8** %argv) {
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="ccxx_derived_types">C/C++ derived types</a> <a name="ccxx_derived_types">C/C++ derived types</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Given the following as an example of C/C++ derived type:</p> <p>Given the following as an example of C/C++ derived type:</p>
@ -1614,7 +1612,7 @@ typedef const int *IntPtr;
<a name="ccxx_composite_types">C/C++ struct/union types</a> <a name="ccxx_composite_types">C/C++ struct/union types</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Given the following as an example of C/C++ struct type:</p> <p>Given the following as an example of C/C++ struct type:</p>
@ -1727,7 +1725,7 @@ struct Color {
<a name="ccxx_enumeration_types">C/C++ enumeration types</a> <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Given the following as an example of C/C++ enumeration type:</p> <p>Given the following as an example of C/C++ enumeration type:</p>
@ -1788,6 +1786,8 @@ enum Trees {
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

37
docs/SystemLibrary.html
View File

@ -37,7 +37,7 @@
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="abstract">Abstract</a></h2> <h2><a name="abstract">Abstract</a></h2>
<div class="doc_text"> <div>
<p>This document provides some details on LLVM's System Library, located in <p>This document provides some details on LLVM's System Library, located in
the source at <tt>lib/System</tt> and <tt>include/llvm/System</tt>. The the source at <tt>lib/System</tt> and <tt>include/llvm/System</tt>. The
library's purpose is to shield LLVM from the differences between operating library's purpose is to shield LLVM from the differences between operating
@ -66,17 +66,16 @@
<h2> <h2>
<a name="requirements">Keeping LLVM Portable</a> <a name="requirements">Keeping LLVM Portable</a>
</h2> </h2>
<div class="doc_text"> <div>
<p>In order to keep LLVM portable, LLVM developers should adhere to a set of <p>In order to keep LLVM portable, LLVM developers should adhere to a set of
portability rules associated with the System Library. Adherence to these rules portability rules associated with the System Library. Adherence to these rules
should help the System Library achieve its goal of shielding LLVM from the should help the System Library achieve its goal of shielding LLVM from the
variations in operating system interfaces and doing so efficiently. The variations in operating system interfaces and doing so efficiently. The
following sections define the rules needed to fulfill this objective.</p> following sections define the rules needed to fulfill this objective.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="headers">Don't Include System Headers</a></h3> <h3><a name="headers">Don't Include System Headers</a></h3>
<div class="doc_text"> <div>
<p>Except in <tt>lib/System</tt>, no LLVM source code should directly <p>Except in <tt>lib/System</tt>, no LLVM source code should directly
<tt>#include</tt> a system header. Care has been taken to remove all such <tt>#include</tt> a system header. Care has been taken to remove all such
<tt>#includes</tt> from LLVM while <tt>lib/System</tt> was being <tt>#includes</tt> from LLVM while <tt>lib/System</tt> was being
@ -91,7 +90,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="expose">Don't Expose System Headers</a></h3> <h3><a name="expose">Don't Expose System Headers</a></h3>
<div class="doc_text"> <div>
<p>The System Library must shield LLVM from <em>all</em> system headers. To <p>The System Library must shield LLVM from <em>all</em> system headers. To
obtain system level functionality, LLVM source must obtain system level functionality, LLVM source must
<tt>#include "llvm/System/Thing.h"</tt> and nothing else. This means that <tt>#include "llvm/System/Thing.h"</tt> and nothing else. This means that
@ -102,7 +101,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="c_headers">Use Standard C Headers</a></h3> <h3><a name="c_headers">Use Standard C Headers</a></h3>
<div class="doc_text"> <div>
<p>The <em>standard</em> C headers (the ones beginning with "c") are allowed <p>The <em>standard</em> C headers (the ones beginning with "c") are allowed
to be exposed through the <tt>lib/System</tt> interface. These headers and to be exposed through the <tt>lib/System</tt> interface. These headers and
the things they declare are considered to be platform agnostic. LLVM source the things they declare are considered to be platform agnostic. LLVM source
@ -112,7 +111,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="cpp_headers">Use Standard C++ Headers</a></h3> <h3><a name="cpp_headers">Use Standard C++ Headers</a></h3>
<div class="doc_text"> <div>
<p>The <em>standard</em> C++ headers from the standard C++ library and <p>The <em>standard</em> C++ headers from the standard C++ library and
standard template library may be exposed through the <tt>lib/System</tt> standard template library may be exposed through the <tt>lib/System</tt>
interface. These headers and the things they declare are considered to be interface. These headers and the things they declare are considered to be
@ -122,7 +121,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="highlev">High Level Interface</a></h3> <h3><a name="highlev">High Level Interface</a></h3>
<div class="doc_text"> <div>
<p>The entry points specified in the interface of lib/System must be aimed at <p>The entry points specified in the interface of lib/System must be aimed at
completing some reasonably high level task needed by LLVM. We do not want to completing some reasonably high level task needed by LLVM. We do not want to
simply wrap each operating system call. It would be preferable to wrap several simply wrap each operating system call. It would be preferable to wrap several
@ -141,7 +140,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="nounused">No Unused Functionality</a></h3> <h3><a name="nounused">No Unused Functionality</a></h3>
<div class="doc_text"> <div>
<p>There must be no functionality specified in the interface of lib/System <p>There must be no functionality specified in the interface of lib/System
that isn't actually used by LLVM. We're not writing a general purpose that isn't actually used by LLVM. We're not writing a general purpose
operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM
@ -151,7 +150,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="nodupl">No Duplicate Implementations</a></h3> <h3><a name="nodupl">No Duplicate Implementations</a></h3>
<div class="doc_text"> <div>
<p>The implementation of a function for a given platform must be written <p>The implementation of a function for a given platform must be written
exactly once. This implies that it must be possible to apply a function's exactly once. This implies that it must be possible to apply a function's
implementation to multiple operating systems if those operating systems can implementation to multiple operating systems if those operating systems can
@ -162,7 +161,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="virtuals">No Virtual Methods</a></h3> <h3><a name="virtuals">No Virtual Methods</a></h3>
<div class="doc_text"> <div>
<p>The System Library interfaces can be called quite frequently by LLVM. In <p>The System Library interfaces can be called quite frequently by LLVM. In
order to make those calls as efficient as possible, we discourage the use of order to make those calls as efficient as possible, we discourage the use of
virtual methods. There is no need to use inheritance for implementation virtual methods. There is no need to use inheritance for implementation
@ -172,7 +171,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="nofunc">No Exposed Functions</a></h3> <h3><a name="nofunc">No Exposed Functions</a></h3>
<div class="doc_text"> <div>
<p>Any functions defined by system libraries (i.e. not defined by lib/System) <p>Any functions defined by system libraries (i.e. not defined by lib/System)
must not be exposed through the lib/System interface, even if the header file must not be exposed through the lib/System interface, even if the header file
for that function is not exposed. This prevents inadvertent use of system for that function is not exposed. This prevents inadvertent use of system
@ -188,7 +187,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="nodata">No Exposed Data</a></h3> <h3><a name="nodata">No Exposed Data</a></h3>
<div class="doc_text"> <div>
<p>Any data defined by system libraries (i.e. not defined by lib/System) must <p>Any data defined by system libraries (i.e. not defined by lib/System) must
not be exposed through the lib/System interface, even if the header file for not be exposed through the lib/System interface, even if the header file for
that function is not exposed. As with functions, this prevents inadvertent use that function is not exposed. As with functions, this prevents inadvertent use
@ -197,7 +196,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="softerrors">Minimize Soft Errors</a></h3> <h3><a name="softerrors">Minimize Soft Errors</a></h3>
<div class="doc_text"> <div>
<p>Operating system interfaces will generally provide error results for every <p>Operating system interfaces will generally provide error results for every
little thing that could go wrong. In almost all cases, you can divide these little thing that could go wrong. In almost all cases, you can divide these
error results into two groups: normal/good/soft and abnormal/bad/hard. That error results into two groups: normal/good/soft and abnormal/bad/hard. That
@ -236,7 +235,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="throw_spec">No throw Specifications</a></h3> <h3><a name="throw_spec">No throw Specifications</a></h3>
<div class="doc_text"> <div>
<p>None of the lib/System interface functions may be declared with C++ <p>None of the lib/System interface functions may be declared with C++
<tt>throw()</tt> specifications on them. This requirement makes sure that the <tt>throw()</tt> specifications on them. This requirement makes sure that the
compiler does not insert additional exception handling code into the interface compiler does not insert additional exception handling code into the interface
@ -248,7 +247,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="organization">Code Organization</a></h3> <h3><a name="organization">Code Organization</a></h3>
<div class="doc_text"> <div>
<p>Implementations of the System Library interface are separated by their <p>Implementations of the System Library interface are separated by their
general class of operating system. Currently only Unix and Win32 classes are general class of operating system. Currently only Unix and Win32 classes are
defined but more could be added for other operating system classifications. defined but more could be added for other operating system classifications.
@ -277,7 +276,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="semantics">Consistent Semantics</a></h3> <h3><a name="semantics">Consistent Semantics</a></h3>
<div class="doc_text"> <div>
<p>The implementation of a lib/System interface can vary drastically between <p>The implementation of a lib/System interface can vary drastically between
platforms. That's okay as long as the end result of the interface function platforms. That's okay as long as the end result of the interface function
is the same. For example, a function to create a directory is pretty straight is the same. For example, a function to create a directory is pretty straight
@ -292,11 +291,13 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="bug">Bug 351</a></h3> <h3><a name="bug">Bug 351</a></h3>
<div class="doc_text"> <div>
<p>See <a href="http://llvm.org/PR351">bug 351</a> <p>See <a href="http://llvm.org/PR351">bug 351</a>
for further details on the progress of this work</p> for further details on the progress of this work</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

55
docs/TableGenFundamentals.html
View File

@ -9,7 +9,7 @@
<h1>TableGen Fundamentals</h1> <h1>TableGen Fundamentals</h1>
<div class="doc_text"> <div>
<ul> <ul>
<li><a href="#introduction">Introduction</a> <li><a href="#introduction">Introduction</a>
<ol> <ol>
@ -53,7 +53,7 @@
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>TableGen's purpose is to help a human develop and maintain records of <p>TableGen's purpose is to help a human develop and maintain records of
domain-specific information. Because there may be a large number of these domain-specific information. Because there may be a large number of these
@ -72,12 +72,10 @@ find an emacs "TableGen mode" and a vim language file in the
<tt>llvm/utils/emacs</tt> and <tt>llvm/utils/vim</tt> directories of your LLVM <tt>llvm/utils/emacs</tt> and <tt>llvm/utils/vim</tt> directories of your LLVM
distribution, respectively.</p> distribution, respectively.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="concepts">Basic concepts</a></h3> <h3><a name="concepts">Basic concepts</a></h3>
<div class="doc_text"> <div>
<p>TableGen files consist of two key parts: 'classes' and 'definitions', both <p>TableGen files consist of two key parts: 'classes' and 'definitions', both
of which are considered 'records'.</p> of which are considered 'records'.</p>
@ -114,7 +112,7 @@ multiclass, as if they were declared in the current multiclass.</p>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="example">An example record</a></h3> <h3><a name="example">An example record</a></h3>
<div class="doc_text"> <div>
<p>With no other arguments, TableGen parses the specified file and prints out <p>With no other arguments, TableGen parses the specified file and prints out
all of the classes, then all of the definitions. This is a good way to see what all of the classes, then all of the definitions. This is a good way to see what
@ -214,7 +212,7 @@ abstractions they prefer to use when describing their information.</p>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="running">Running TableGen</a></h3> <h3><a name="running">Running TableGen</a></h3>
<div class="doc_text"> <div>
<p>TableGen runs just like any other LLVM tool. The first (optional) argument <p>TableGen runs just like any other LLVM tool. The first (optional) argument
specifies the file to read. If a filename is not specified, <tt>tblgen</tt> specifies the file to read. If a filename is not specified, <tt>tblgen</tt>
@ -256,27 +254,28 @@ what you need and formats it in the appropriate way.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="syntax">TableGen syntax</a></h2> <h2><a name="syntax">TableGen syntax</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>TableGen doesn't care about the meaning of data (that is up to the backend to <p>TableGen doesn't care about the meaning of data (that is up to the backend to
define), but it does care about syntax, and it enforces a simple type system. define), but it does care about syntax, and it enforces a simple type system.
This section describes the syntax and the constructs allowed in a TableGen file. This section describes the syntax and the constructs allowed in a TableGen file.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3><a name="primitives">TableGen primitives</a></h3> <h3><a name="primitives">TableGen primitives</a></h3>
<div>
<!-- --------------------------------------------------------------------------> <!-- -------------------------------------------------------------------------->
<h4><a name="comments">TableGen comments</a></h4> <h4><a name="comments">TableGen comments</a></h4>
<div class="doc_text"> <div>
<p>TableGen supports BCPL style "<tt>//</tt>" comments, which run to the end of <p>TableGen supports BCPL style "<tt>//</tt>" comments, which run to the end of
the line, and it also supports <b>nestable</b> "<tt>/* */</tt>" comments.</p> the line, and it also supports <b>nestable</b> "<tt>/* */</tt>" comments.</p>
@ -288,7 +287,7 @@ the line, and it also supports <b>nestable</b> "<tt>/* */</tt>" comments.</p>
<a name="types">The TableGen type system</a> <a name="types">The TableGen type system</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>TableGen files are strongly typed, in a simple (but complete) type-system. <p>TableGen files are strongly typed, in a simple (but complete) type-system.
These types are used to perform automatic conversions, check for errors, and to These types are used to perform automatic conversions, check for errors, and to
@ -348,7 +347,7 @@ needed.</p>
<a name="values">TableGen values and expressions</a> <a name="values">TableGen values and expressions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>TableGen allows for a pretty reasonable number of different expression forms <p>TableGen allows for a pretty reasonable number of different expression forms
when building up values. These forms allow the TableGen file to be written in a when building up values. These forms allow the TableGen file to be written in a
@ -433,12 +432,14 @@ to a "<tt>bits&lt;4&gt;</tt>" value, for example.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="classesdefs">Classes and definitions</a> <a name="classesdefs">Classes and definitions</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>As mentioned in the <a href="#concepts">intro</a>, classes and definitions <p>As mentioned in the <a href="#concepts">intro</a>, classes and definitions
(collectively known as 'records') in TableGen are the main high-level unit of (collectively known as 'records') in TableGen are the main high-level unit of
@ -473,14 +474,12 @@ between a group of records and isolating it in a single place. Also, classes
permit the specification of default values for their subclasses, allowing the permit the specification of default values for their subclasses, allowing the
subclasses to override them as they wish.</p> subclasses to override them as they wish.</p>
</div>
<!----------------------------------------------------------------------------> <!---------------------------------------------------------------------------->
<h4> <h4>
<a name="valuedef">Value definitions</a> <a name="valuedef">Value definitions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Value definitions define named entries in records. A value must be defined <p>Value definitions define named entries in records. A value must be defined
before it can be referred to as the operand for another value definition or before it can be referred to as the operand for another value definition or
@ -496,7 +495,7 @@ equal sign. Value definitions require terminating semicolons.</p>
<a name="recordlet">'let' expressions</a> <a name="recordlet">'let' expressions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>A record-level let expression is used to change the value of a value <p>A record-level let expression is used to change the value of a value
definition in a record. This is primarily useful when a superclass defines a definition in a record. This is primarily useful when a superclass defines a
@ -523,7 +522,7 @@ because the <tt>D</tt> class overrode its value.</p>
<a name="templateargs">Class template arguments</a> <a name="templateargs">Class template arguments</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>TableGen permits the definition of parameterized classes as well as normal <p>TableGen permits the definition of parameterized classes as well as normal
concrete classes. Parameterized TableGen classes specify a list of variable concrete classes. Parameterized TableGen classes specify a list of variable
@ -614,7 +613,7 @@ X86 backend.</p>
<a name="multiclass">Multiclass definitions and instances</a> <a name="multiclass">Multiclass definitions and instances</a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
While classes with template arguments are a good way to factor commonality While classes with template arguments are a good way to factor commonality
@ -772,17 +771,21 @@ before them.
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="filescope">File scope entities</a> <a name="filescope">File scope entities</a>
</h3> </h3>
<div>
<!-- --------------------------------------------------------------------------> <!-- -------------------------------------------------------------------------->
<h4> <h4>
<a name="include">File inclusion</a> <a name="include">File inclusion</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>TableGen supports the '<tt>include</tt>' token, which textually substitutes <p>TableGen supports the '<tt>include</tt>' token, which textually substitutes
the specified file in place of the include directive. The filename should be the specified file in place of the include directive. The filename should be
specified as a double quoted string immediately after the '<tt>include</tt>' specified as a double quoted string immediately after the '<tt>include</tt>'
@ -801,7 +804,7 @@ keyword. Example:</p>
<a name="globallet">'let' expressions</a> <a name="globallet">'let' expressions</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>"Let" expressions at file scope are similar to <a href="#recordlet">"let" <p>"Let" expressions at file scope are similar to <a href="#recordlet">"let"
expressions within a record</a>, except they can specify a value binding for expressions within a record</a>, except they can specify a value binding for
@ -864,11 +867,15 @@ several levels of multiclass instanciations. This also avoids the need of using
</pre> </pre>
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="codegen">Code Generator backend info</a></h2> <h2><a name="codegen">Code Generator backend info</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Expressions used by code generator to describe instructions and isel <p>Expressions used by code generator to describe instructions and isel
patterns:</p> patterns:</p>
@ -885,7 +892,7 @@ patterns:</p>
<h2><a name="backends">TableGen backends</a></h2> <h2><a name="backends">TableGen backends</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>TODO: How they work, how to write one. This section should not contain <p>TODO: How they work, how to write one. This section should not contain
details about any particular backend, except maybe -print-enums as an example. details about any particular backend, except maybe -print-enums as an example.

74
docs/TestingGuide.html
View File

@ -55,7 +55,7 @@
<h2><a name="overview">Overview</a></h2> <h2><a name="overview">Overview</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>This document is the reference manual for the LLVM testing infrastructure. It <p>This document is the reference manual for the LLVM testing infrastructure. It
documents the structure of the LLVM testing infrastructure, the tools needed to documents the structure of the LLVM testing infrastructure, the tools needed to
@ -67,7 +67,7 @@ use it, and how to add and run tests.</p>
<h2><a name="requirements">Requirements</a></h2> <h2><a name="requirements">Requirements</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>In order to use the LLVM testing infrastructure, you will need all of the <p>In order to use the LLVM testing infrastructure, you will need all of the
software required to build LLVM, as well software required to build LLVM, as well
@ -79,7 +79,7 @@ as <a href="http://python.org">Python</a> 2.4 or later.</p>
<h2><a name="org">LLVM testing infrastructure organization</a></h2> <h2><a name="org">LLVM testing infrastructure organization</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>The LLVM testing infrastructure contains two major categories of tests: <p>The LLVM testing infrastructure contains two major categories of tests:
regression tests and whole programs. The regression tests are contained inside regression tests and whole programs. The regression tests are contained inside
@ -89,13 +89,11 @@ referred to as the "LLVM test suite" and are in the <tt>test-suite</tt> module
in subversion. in subversion.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="regressiontests">Regression tests</a></h3> <h3><a name="regressiontests">Regression tests</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>The regression tests are small pieces of code that test a specific feature of <p>The regression tests are small pieces of code that test a specific feature of
LLVM or trigger a specific bug in LLVM. They are usually written in LLVM LLVM or trigger a specific bug in LLVM. They are usually written in LLVM
@ -122,7 +120,7 @@ application or benchmark.</p>
<h3><a name="testsuite">Test suite</a></h3> <h3><a name="testsuite">Test suite</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>The test suite contains whole programs, which are pieces of <p>The test suite contains whole programs, which are pieces of
code which can be compiled and linked into a stand-alone program that can be code which can be compiled and linked into a stand-alone program that can be
@ -147,7 +145,7 @@ generates code.</p>
<h3><a name="debuginfotests">Debugging Information tests</a></h3> <h3><a name="debuginfotests">Debugging Information tests</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>The test suite contains tests to check quality of debugging information. <p>The test suite contains tests to check quality of debugging information.
The test are written in C based languages or in LLVM assembly language. </p> The test are written in C based languages or in LLVM assembly language. </p>
@ -159,11 +157,13 @@ test suite for more information . This test suite is located in the
</div> </div>
</div>
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="quick">Quick start</a></h2> <h2><a name="quick">Quick start</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>The tests are located in two separate Subversion modules. The regressions <p>The tests are located in two separate Subversion modules. The regressions
tests are in the main "llvm" module under the directory tests are in the main "llvm" module under the directory
@ -179,6 +179,7 @@ Alternatively, you can configure the <tt>test-suite</tt> module manually.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="quickregressiontests">Regression tests</a></h3> <h3><a name="quickregressiontests">Regression tests</a></h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<p>To run all of the LLVM regression tests, use master Makefile in <p>To run all of the LLVM regression tests, use master Makefile in
the <tt>llvm/test</tt> directory:</p> the <tt>llvm/test</tt> directory:</p>
@ -238,10 +239,14 @@ script which is built as part of LLVM. For example, to run the
<p>For more information on using the 'lit' tool, see 'llvm-lit --help' or the <p>For more information on using the 'lit' tool, see 'llvm-lit --help' or the
'lit' man page.</p> 'lit' man page.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="quicktestsuite">Test suite</a></h3> <h3><a name="quicktestsuite">Test suite</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div>
<p>To run the comprehensive test suite (tests that compile and execute whole <p>To run the comprehensive test suite (tests that compile and execute whole
programs), first checkout and setup the <tt>test-suite</tt> module:</p> programs), first checkout and setup the <tt>test-suite</tt> module:</p>
@ -292,8 +297,9 @@ that subdirectory.</p>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="quickdebuginfotests">Debugging Information tests</a></h3> <h3><a name="quickdebuginfotests">Debugging Information tests</a></h3>
<div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p> To run debugging information tests simply checkout the tests inside <p> To run debugging information tests simply checkout the tests inside
clang/test directory. </p> clang/test directory. </p>
@ -309,10 +315,14 @@ clang/test directory. </p>
</div> </div>
</div>
</div>
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="rtstructure">Regression test structure</a></h2> <h2><a name="rtstructure">Regression test structure</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>The LLVM regression tests are driven by 'lit' and are located in <p>The LLVM regression tests are driven by 'lit' and are located in
the <tt>llvm/test</tt> directory. the <tt>llvm/test</tt> directory.
@ -334,12 +344,10 @@ clang/test directory. </p>
<li><tt>Verifier</tt>: tests the IR verifier.</li> <li><tt>Verifier</tt>: tests the IR verifier.</li>
</ul> </ul>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="rtcustom">Writing new regression tests</a></h3> <h3><a name="rtcustom">Writing new regression tests</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>The regression test structure is very simple, but does require some <p>The regression test structure is very simple, but does require some
information to be set. This information is gathered via <tt>configure</tt> and information to be set. This information is gathered via <tt>configure</tt> and
is written to a file, <tt>lit.site.cfg</tt> is written to a file, <tt>lit.site.cfg</tt>
@ -494,7 +502,7 @@ negatives).</p>
<h3><a name="FileCheck">The FileCheck utility</a></h3> <h3><a name="FileCheck">The FileCheck utility</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>A powerful feature of the RUN: lines is that it allows any arbitrary commands <p>A powerful feature of the RUN: lines is that it allows any arbitrary commands
to be executed as part of the test harness. While standard (portable) unix to be executed as part of the test harness. While standard (portable) unix
@ -560,14 +568,12 @@ is a "subl" in between those labels. If it existed somewhere else in the file,
that would not count: "grep subl" matches if subl exists anywhere in the that would not count: "grep subl" matches if subl exists anywhere in the
file.</p> file.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="FileCheck-check-prefix">The FileCheck -check-prefix option</a> <a name="FileCheck-check-prefix">The FileCheck -check-prefix option</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The FileCheck -check-prefix option allows multiple test configurations to be <p>The FileCheck -check-prefix option allows multiple test configurations to be
driven from one .ll file. This is useful in many circumstances, for example, driven from one .ll file. This is useful in many circumstances, for example,
@ -602,7 +608,7 @@ both 32-bit and 64-bit code generation.</p>
<a name="FileCheck-CHECK-NEXT">The "CHECK-NEXT:" directive</a> <a name="FileCheck-CHECK-NEXT">The "CHECK-NEXT:" directive</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Sometimes you want to match lines and would like to verify that matches <p>Sometimes you want to match lines and would like to verify that matches
happen on exactly consecutive lines with no other lines in between them. In happen on exactly consecutive lines with no other lines in between them. In
@ -643,7 +649,7 @@ directive in a file.</p>
<a name="FileCheck-CHECK-NOT">The "CHECK-NOT:" directive</a> <a name="FileCheck-CHECK-NOT">The "CHECK-NOT:" directive</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The CHECK-NOT: directive is used to verify that a string doesn't occur <p>The CHECK-NOT: directive is used to verify that a string doesn't occur
between two matches (or the first match and the beginning of the file). For between two matches (or the first match and the beginning of the file). For
@ -674,7 +680,7 @@ define i8 @coerce_offset0(i32 %V, i32* %P) {
<a name="FileCheck-Matching">FileCheck Pattern Matching Syntax</a> <a name="FileCheck-Matching">FileCheck Pattern Matching Syntax</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The CHECK: and CHECK-NOT: directives both take a pattern to match. For most <p>The CHECK: and CHECK-NOT: directives both take a pattern to match. For most
uses of FileCheck, fixed string matching is perfectly sufficient. For some uses of FileCheck, fixed string matching is perfectly sufficient. For some
@ -707,7 +713,7 @@ braces explicitly from the input, you can use something ugly like
<a name="FileCheck-Variables">FileCheck Variables</a> <a name="FileCheck-Variables">FileCheck Variables</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>It is often useful to match a pattern and then verify that it occurs again <p>It is often useful to match a pattern and then verify that it occurs again
later in the file. For codegen tests, this can be useful to allow any register, later in the file. For codegen tests, this can be useful to allow any register,
@ -742,10 +748,12 @@ define two separate CHECK lines that match on the same line.
</div> </div>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="rtvars">Variables and substitutions</a></h3> <h3><a name="rtvars">Variables and substitutions</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>With a RUN line there are a number of substitutions that are permitted. In <p>With a RUN line there are a number of substitutions that are permitted. In
general, any Tcl variable that is available in the <tt>substitute</tt> general, any Tcl variable that is available in the <tt>substitute</tt>
function (in <tt>test/lib/llvm.exp</tt>) can be substituted into a RUN line. function (in <tt>test/lib/llvm.exp</tt>) can be substituted into a RUN line.
@ -840,7 +848,7 @@ define two separate CHECK lines that match on the same line.
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3><a name="rtfeatures">Other Features</a></h3> <h3><a name="rtfeatures">Other Features</a></h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>To make RUN line writing easier, there are several shell scripts located <p>To make RUN line writing easier, there are several shell scripts located
in the <tt>llvm/test/Scripts</tt> directory. This directory is in the PATH in the <tt>llvm/test/Scripts</tt> directory. This directory is in the PATH
when running tests, so you can just call these scripts using their name. For when running tests, so you can just call these scripts using their name. For
@ -895,11 +903,13 @@ define two separate CHECK lines that match on the same line.
</div> </div>
</div>
<!--=========================================================================--> <!--=========================================================================-->
<h2><a name="testsuitestructure">Test suite Structure</a></h2> <h2><a name="testsuitestructure">Test suite Structure</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>The <tt>test-suite</tt> module contains a number of programs that can be compiled <p>The <tt>test-suite</tt> module contains a number of programs that can be compiled
with LLVM and executed. These programs are compiled using the native compiler with LLVM and executed. These programs are compiled using the native compiler
@ -967,7 +977,7 @@ will help you separate benign warnings from actual test failures.</p>
<h2><a name="testsuiterun">Running the test suite</a></h2> <h2><a name="testsuiterun">Running the test suite</a></h2>
<!--=========================================================================--> <!--=========================================================================-->
<div class="doc_text"> <div>
<p>First, all tests are executed within the LLVM object directory tree. They <p>First, all tests are executed within the LLVM object directory tree. They
<i>are not</i> executed inside of the LLVM source tree. This is because the <i>are not</i> executed inside of the LLVM source tree. This is because the
@ -1022,15 +1032,13 @@ test suite creates temporary files during execution.</p>
have the suite checked out and configured, you don't need to do it again (unless have the suite checked out and configured, you don't need to do it again (unless
the test code or configure script changes).</p> the test code or configure script changes).</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3> <h3>
<a name="testsuiteexternal">Configuring External Tests</a> <a name="testsuiteexternal">Configuring External Tests</a>
</h3> </h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>In order to run the External tests in the <tt>test-suite</tt> <p>In order to run the External tests in the <tt>test-suite</tt>
module, you must specify <i>--with-externals</i>. This module, you must specify <i>--with-externals</i>. This
must be done during the <em>re-configuration</em> step (see above), must be done during the <em>re-configuration</em> step (see above),
@ -1062,7 +1070,7 @@ the test code or configure script changes).</p>
<a name="testsuitetests">Running different tests</a> <a name="testsuitetests">Running different tests</a>
</h3> </h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>In addition to the regular "whole program" tests, the <tt>test-suite</tt> <p>In addition to the regular "whole program" tests, the <tt>test-suite</tt>
module also provides a mechanism for compiling the programs in different ways. module also provides a mechanism for compiling the programs in different ways.
If the variable TEST is defined on the <tt>gmake</tt> command line, the test system will If the variable TEST is defined on the <tt>gmake</tt> command line, the test system will
@ -1086,7 +1094,7 @@ LLVM.</p>
<a name="testsuiteoutput">Generating test output</a> <a name="testsuiteoutput">Generating test output</a>
</h3> </h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>There are a number of ways to run the tests and generate output. The most <p>There are a number of ways to run the tests and generate output. The most
simple one is simply running <tt>gmake</tt> with no arguments. This will simple one is simply running <tt>gmake</tt> with no arguments. This will
compile and run all programs in the tree using a number of different methods compile and run all programs in the tree using a number of different methods
@ -1119,7 +1127,7 @@ LLVM.</p>
</h3> </h3>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<div class="doc_text"> <div>
<p>Assuming you can run the test suite, (e.g. "<tt>gmake TEST=nightly report</tt>" <p>Assuming you can run the test suite, (e.g. "<tt>gmake TEST=nightly report</tt>"
should work), it is really easy to run optimizations or code generator should work), it is really easy to run optimizations or code generator
@ -1185,6 +1193,8 @@ example reports that can do fancy stuff.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

18
docs/UsingLibraries.html
View File

@ -31,7 +31,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2><a name="abstract">Abstract</a></h2> <h2><a name="abstract">Abstract</a></h2>
<div class="doc_text"> <div>
<p>Amongst other things, LLVM is a toolkit for building compilers, linkers, <p>Amongst other things, LLVM is a toolkit for building compilers, linkers,
runtime executives, virtual machines, and other program execution related runtime executives, virtual machines, and other program execution related
tools. In addition to the LLVM tool set, the functionality of LLVM is tools. In addition to the LLVM tool set, the functionality of LLVM is
@ -46,7 +46,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2><a name="introduction">Introduction</a></h2> <h2><a name="introduction">Introduction</a></h2>
<div class="doc_text"> <div>
<p>If you're writing a compiler, virtual machine, or any other utility based <p>If you're writing a compiler, virtual machine, or any other utility based
on LLVM, you'll need to figure out which of the many libraries files you will on LLVM, you'll need to figure out which of the many libraries files you will
need to link with to be successful. An understanding of the contents of these need to link with to be successful. An understanding of the contents of these
@ -75,7 +75,7 @@
</div> </div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2><a name="descriptions">Library Descriptions</a></h2> <h2><a name="descriptions">Library Descriptions</a></h2>
<div class="doc_text"> <div>
<p>The table below categorizes each library <p>The table below categorizes each library
<table style="text-align:left"> <table style="text-align:left">
<tr><th>Library</th><th>Forms</th><th>Description</th></tr> <tr><th>Library</th><th>Forms</th><th>Description</th></tr>
@ -153,7 +153,7 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2><a name="dependencies">Using llvm-config</a></h2> <h2><a name="dependencies">Using llvm-config</a></h2>
<div class="doc_text"> <div>
<p>The <tt>llvm-config</tt> tool is a perl script that produces on its output <p>The <tt>llvm-config</tt> tool is a perl script that produces on its output
various kinds of information. For example, the source or object directories various kinds of information. For example, the source or object directories
used to build LLVM can be accessed by passing options to <tt>llvm-config</tt>. used to build LLVM can be accessed by passing options to <tt>llvm-config</tt>.
@ -402,15 +402,14 @@
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h2><a name="rot">Linkage Rules Of Thumb</a></h2> <h2><a name="rot">Linkage Rules Of Thumb</a></h2>
<div class="doc_text"> <div>
<p>This section contains various "rules of thumb" about what files you <p>This section contains various "rules of thumb" about what files you
should link into your programs.</p> should link into your programs.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="always">Always Link LLVMCore, LLVMSupport, and LLVMSystem</a> <a name="always">Always Link LLVMCore, LLVMSupport, and LLVMSystem</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>No matter what you do with LLVM, the last three entries in the value of <p>No matter what you do with LLVM, the last three entries in the value of
your LLVMLIBS make variable should always be: your LLVMLIBS make variable should always be:
<tt>LLVMCore LLVMSupport.a LLVMSystem.a</tt>. There are no <tt>LLVM</tt> <tt>LLVMCore LLVMSupport.a LLVMSystem.a</tt>. There are no <tt>LLVM</tt>
@ -420,13 +419,16 @@
<h3> <h3>
<a name="onlyone">Never link both archive and re-linked library</a> <a name="onlyone">Never link both archive and re-linked library</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>There is never any point to linking both the re-linked (<tt>.o</tt>) and <p>There is never any point to linking both the re-linked (<tt>.o</tt>) and
the archive (<tt>.a</tt>) versions of a library. Since the re-linked version the archive (<tt>.a</tt>) versions of a library. Since the re-linked version
includes the entire library, the archive version will not resolve any symbols. includes the entire library, the archive version will not resolve any symbols.
You could even end up with link error if you place the archive version before You could even end up with link error if you place the archive version before
the re-linked version on the linker's command line.</p> the re-linked version on the linker's command line.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<hr> <hr>
<div class="doc_footer"> <div class="doc_footer">

87
docs/WritingAnLLVMBackend.html
View File

@ -66,7 +66,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
This document describes techniques for writing compiler backends that convert This document describes techniques for writing compiler backends that convert
@ -91,13 +91,11 @@ characteristics, such as a RISC instruction set and straightforward calling
conventions. conventions.
</p> </p>
</div>
<h3> <h3>
<a name="Audience">Audience</a> <a name="Audience">Audience</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The audience for this document is anyone who needs to write an LLVM backend to The audience for this document is anyone who needs to write an LLVM backend to
@ -110,7 +108,7 @@ generate code for a specific hardware or software target.
<a name="Prerequisite">Prerequisite Reading</a> <a name="Prerequisite">Prerequisite Reading</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
These essential documents must be read before reading this document: These essential documents must be read before reading this document:
@ -159,7 +157,7 @@ machine dependent features.
<a name="Basic">Basic Steps</a> <a name="Basic">Basic Steps</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
To write a compiler backend for LLVM that converts the LLVM IR to code for a To write a compiler backend for LLVM that converts the LLVM IR to code for a
@ -224,7 +222,7 @@ that the class will need and which components will need to be subclassed.
<a name="Preliminaries">Preliminaries</a> <a name="Preliminaries">Preliminaries</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
To actually create your compiler backend, you need to create and modify a few To actually create your compiler backend, you need to create and modify a few
@ -281,13 +279,15 @@ regenerate configure by running <tt>./autoconf/AutoRegen.sh</tt>.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="TargetMachine">Target Machine</a> <a name="TargetMachine">Target Machine</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
<tt>LLVMTargetMachine</tt> is designed as a base class for targets implemented <tt>LLVMTargetMachine</tt> is designed as a base class for targets implemented
@ -360,11 +360,6 @@ public:
</pre> </pre>
</div> </div>
</div>
<div class="doc_text">
<ul> <ul>
<li><tt>getInstrInfo()</tt></li> <li><tt>getInstrInfo()</tt></li>
<li><tt>getRegisterInfo()</tt></li> <li><tt>getRegisterInfo()</tt></li>
@ -398,10 +393,6 @@ SparcTargetMachine::SparcTargetMachine(const Module &amp;M, const std::string &a
</pre> </pre>
</div> </div>
</div>
<div class="doc_text">
<p>Hyphens separate portions of the <tt>TargetDescription</tt> string.</p> <p>Hyphens separate portions of the <tt>TargetDescription</tt> string.</p>
<ul> <ul>
@ -429,7 +420,7 @@ SparcTargetMachine::SparcTargetMachine(const Module &amp;M, const std::string &a
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
You must also register your target with the <tt>TargetRegistry</tt>, which is You must also register your target with the <tt>TargetRegistry</tt>, which is
@ -485,7 +476,7 @@ For more information, see
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
You should describe a concrete target-specific class that represents the You should describe a concrete target-specific class that represents the
@ -514,14 +505,12 @@ input files and placed in <tt>XXXGenRegisterInfo.h.inc</tt> and
implementation of <tt>XXXRegisterInfo</tt> requires hand-coding. implementation of <tt>XXXRegisterInfo</tt> requires hand-coding.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="RegisterDef">Defining a Register</a> <a name="RegisterDef">Defining a Register</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The <tt>XXXRegisterInfo.td</tt> file typically starts with register definitions The <tt>XXXRegisterInfo.td</tt> file typically starts with register definitions
@ -704,7 +693,7 @@ fields of a register's TargetRegisterDesc.
<a name="RegisterClassDef">Defining a Register Class</a> <a name="RegisterClassDef">Defining a Register Class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The <tt>RegisterClass</tt> class (specified in <tt>Target.td</tt>) is used to The <tt>RegisterClass</tt> class (specified in <tt>Target.td</tt>) is used to
@ -899,7 +888,7 @@ namespace SP { // Register class instances
<a href="CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a> <a href="CodeGenerator.html#targetregisterinfo">TargetRegisterInfo</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The final step is to hand code portions of <tt>XXXRegisterInfo</tt>, which The final step is to hand code portions of <tt>XXXRegisterInfo</tt>, which
@ -933,13 +922,15 @@ implementation in <tt>SparcRegisterInfo.cpp</tt>:
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="InstructionSet">Instruction Set</a> <a name="InstructionSet">Instruction Set</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
During the early stages of code generation, the LLVM IR code is converted to a During the early stages of code generation, the LLVM IR code is converted to a
@ -1188,14 +1179,12 @@ correspond to the values in <tt>SparcInstrInfo.td</tt>. I.e.,
<tt>SPCC::ICC_NE = 9</tt>, <tt>SPCC::FCC_U = 23</tt> and so on.) <tt>SPCC::ICC_NE = 9</tt>, <tt>SPCC::FCC_U = 23</tt> and so on.)
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="operandMapping">Instruction Operand Mapping</a> <a name="operandMapping">Instruction Operand Mapping</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The code generator backend maps instruction operands to fields in the The code generator backend maps instruction operands to fields in the
@ -1288,7 +1277,7 @@ the <tt>rd</tt>, <tt>rs1</tt>, and <tt>rs2</tt> fields respectively.
<a href="CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a> <a href="CodeGenerator.html#targetinstrinfo">TargetInstrInfo</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The final step is to hand code portions of <tt>XXXInstrInfo</tt>, which The final step is to hand code portions of <tt>XXXInstrInfo</tt>, which
@ -1330,7 +1319,7 @@ implementation in <tt>SparcInstrInfo.cpp</tt>:
<h3> <h3>
<a name="branchFolding">Branch Folding and If Conversion</a> <a name="branchFolding">Branch Folding and If Conversion</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
Performance can be improved by combining instructions or by eliminating Performance can be improved by combining instructions or by eliminating
@ -1485,13 +1474,15 @@ branch.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="InstructionSelector">Instruction Selector</a> <a name="InstructionSelector">Instruction Selector</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
LLVM uses a <tt>SelectionDAG</tt> to represent LLVM IR instructions, and nodes LLVM uses a <tt>SelectionDAG</tt> to represent LLVM IR instructions, and nodes
@ -1642,14 +1633,12 @@ SDNode *Select_ISD_STORE(const SDValue &amp;N) {
</pre> </pre>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="LegalizePhase">The SelectionDAG Legalize Phase</a> <a name="LegalizePhase">The SelectionDAG Legalize Phase</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
The Legalize phase converts a DAG to use types and operations that are natively The Legalize phase converts a DAG to use types and operations that are natively
@ -1716,14 +1705,12 @@ a <tt>LegalAction</tt> type enum value: <tt>Promote</tt>, <tt>Expand</tt>,
contains examples of all four <tt>LegalAction</tt> values. contains examples of all four <tt>LegalAction</tt> values.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="promote">Promote</a> <a name="promote">Promote</a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
For an operation without native support for a given type, the specified type may For an operation without native support for a given type, the specified type may
@ -1746,7 +1733,7 @@ setLoadExtAction(ISD::SEXTLOAD, MVT::i1, Promote);
<a name="expand">Expand</a> <a name="expand">Expand</a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
For a type without native support, a value may need to be broken down further, For a type without native support, a value may need to be broken down further,
@ -1771,7 +1758,7 @@ setOperationAction(ISD::FCOS, MVT::f32, Expand);
<a name="custom">Custom</a> <a name="custom">Custom</a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
For some operations, simple type promotion or operation expansion may be For some operations, simple type promotion or operation expansion may be
@ -1837,7 +1824,7 @@ static SDValue LowerFP_TO_SINT(SDValue Op, SelectionDAG &amp;DAG) {
<a name="legal">Legal</a> <a name="legal">Legal</a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
The <tt>Legal</tt> LegalizeAction enum value simply indicates that an The <tt>Legal</tt> LegalizeAction enum value simply indicates that an
@ -1865,12 +1852,14 @@ if (TM.getSubtarget&lt;SparcSubtarget&gt;().isV9())
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="callingConventions">Calling Conventions</a> <a name="callingConventions">Calling Conventions</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
To support target-specific calling conventions, <tt>XXXGenCallingConv.td</tt> To support target-specific calling conventions, <tt>XXXGenCallingConv.td</tt>
@ -2015,13 +2004,15 @@ def RetCC_X86_32 : CallingConv&lt;[
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="assemblyPrinter">Assembly Printer</a> <a name="assemblyPrinter">Assembly Printer</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
During the code emission stage, the code generator may utilize an LLVM pass to During the code emission stage, the code generator may utilize an LLVM pass to
@ -2176,7 +2167,7 @@ output.
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Subtarget support is used to inform the code generation process of instruction Subtarget support is used to inform the code generation process of instruction
@ -2294,7 +2285,7 @@ XXXSubtarget::XXXSubtarget(const Module &amp;M, const std::string &amp;FS) {
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The implementation of a target machine optionally includes a Just-In-Time (JIT) The implementation of a target machine optionally includes a Just-In-Time (JIT)
@ -2333,14 +2324,12 @@ Both <tt>XXXJITInfo.cpp</tt> and <tt>XXXCodeEmitter.cpp</tt> must include the
that write data (in bytes, words, strings, etc.) to the output stream. that write data (in bytes, words, strings, etc.) to the output stream.
</p> </p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="mce">Machine Code Emitter</a> <a name="mce">Machine Code Emitter</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
In <tt>XXXCodeEmitter.cpp</tt>, a target-specific of the <tt>Emitter</tt> class In <tt>XXXCodeEmitter.cpp</tt>, a target-specific of the <tt>Emitter</tt> class
@ -2482,7 +2471,7 @@ enum RelocationType {
<a name="targetJITInfo">Target JIT Info</a> <a name="targetJITInfo">Target JIT Info</a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <p>
<tt>XXXJITInfo.cpp</tt> implements the JIT interfaces for target-specific <tt>XXXJITInfo.cpp</tt> implements the JIT interfaces for target-specific
@ -2537,6 +2526,8 @@ with assembler.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>

168
docs/WritingAnLLVMPass.html
View File

@ -126,7 +126,7 @@
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM <p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM
passes are where most of the interesting parts of the compiler exist. Passes passes are where most of the interesting parts of the compiler exist. Passes
@ -161,7 +161,7 @@ more advanced features are discussed.</p>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Here we describe how to write the "hello world" of passes. The "Hello" pass <p>Here we describe how to write the "hello world" of passes. The "Hello" pass
is designed to simply print out the name of non-external functions that exist in is designed to simply print out the name of non-external functions that exist in
@ -169,14 +169,12 @@ the program being compiled. It does not modify the program at all, it just
inspects it. The source code and files for this pass are available in the LLVM inspects it. The source code and files for this pass are available in the LLVM
source tree in the <tt>lib/Transforms/Hello</tt> directory.</p> source tree in the <tt>lib/Transforms/Hello</tt> directory.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="makefile">Setting up the build environment</a> <a name="makefile">Setting up the build environment</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>First, configure and build LLVM. This needs to be done directly inside the <p>First, configure and build LLVM. This needs to be done directly inside the
LLVM source tree rather than in a separate objects directory. LLVM source tree rather than in a separate objects directory.
@ -224,7 +222,7 @@ the pass itself.</p>
<a name="basiccode">Basic code required</a> <a name="basiccode">Basic code required</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Now that we have a way to compile our new pass, we just have to write it. <p>Now that we have a way to compile our new pass, we just have to write it.
Start out with:</p> Start out with:</p>
@ -360,7 +358,7 @@ them) to be useful.</p>
<a name="running">Running a pass with <tt>opt</tt></a> <a name="running">Running a pass with <tt>opt</tt></a>
</h3> </h3>
<div class="doc_text"> <div>
<p>Now that you have a brand new shiny shared object file, we can use the <p>Now that you have a brand new shiny shared object file, we can use the
<tt>opt</tt> command to run an LLVM program through your pass. Because you <tt>opt</tt> command to run an LLVM program through your pass. Because you
@ -446,13 +444,15 @@ about some more details of how they work and how to use them.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="passtype">Pass classes and requirements</a> <a name="passtype">Pass classes and requirements</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>One of the first things that you should do when designing a new pass is to <p>One of the first things that you should do when designing a new pass is to
decide what class you should subclass for your pass. The <a decide what class you should subclass for your pass. The <a
@ -467,14 +467,12 @@ listed. This gives the LLVM Pass Infrastructure information necessary to
optimize how passes are run, so that the resultant compiler isn't unnecessarily optimize how passes are run, so that the resultant compiler isn't unnecessarily
slow.</p> slow.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="ImmutablePass">The <tt>ImmutablePass</tt> class</a> <a name="ImmutablePass">The <tt>ImmutablePass</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The most plain and boring type of pass is the "<tt><a <p>The most plain and boring type of pass is the "<tt><a
href="http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html">ImmutablePass</a></tt>" href="http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html">ImmutablePass</a></tt>"
@ -497,7 +495,7 @@ invalidated, and are never "run".</p>
<a name="ModulePass">The <tt>ModulePass</tt> class</a> <a name="ModulePass">The <tt>ModulePass</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The "<tt><a <p>The "<tt><a
href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a></tt>" href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a></tt>"
@ -519,14 +517,12 @@ DominatorTree for function definitions, not declarations.</p>
<tt>ModulePass</tt> and overload the <tt>runOnModule</tt> method with the <tt>ModulePass</tt> and overload the <tt>runOnModule</tt> method with the
following signature:</p> following signature:</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="runOnModule">The <tt>runOnModule</tt> method</a> <a name="runOnModule">The <tt>runOnModule</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnModule(Module &amp;M) = 0; <b>virtual bool</b> runOnModule(Module &amp;M) = 0;
@ -538,12 +534,14 @@ false otherwise.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a> <a name="CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The "<tt><a <p>The "<tt><a
href="http://llvm.org/doxygen/classllvm_1_1CallGraphSCCPass.html">CallGraphSCCPass</a></tt>" href="http://llvm.org/doxygen/classllvm_1_1CallGraphSCCPass.html">CallGraphSCCPass</a></tt>"
@ -584,8 +582,6 @@ because it has to handle SCCs with more than one node in it. All of the virtual
methods described below should return true if they modified the program, or methods described below should return true if they modified the program, or
false if they didn't.</p> false if they didn't.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="doInitialization_scc"> <a name="doInitialization_scc">
@ -593,7 +589,7 @@ false if they didn't.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doInitialization(CallGraph &amp;CG); <b>virtual bool</b> doInitialization(CallGraph &amp;CG);
@ -614,7 +610,7 @@ fast).</p>
<a name="runOnSCC">The <tt>runOnSCC</tt> method</a> <a name="runOnSCC">The <tt>runOnSCC</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnSCC(CallGraphSCC &amp;SCC) = 0; <b>virtual bool</b> runOnSCC(CallGraphSCC &amp;SCC) = 0;
@ -633,7 +629,7 @@ otherwise.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doFinalization(CallGraph &amp;CG); <b>virtual bool</b> doFinalization(CallGraph &amp;CG);
@ -646,12 +642,14 @@ program being compiled.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="FunctionPass">The <tt>FunctionPass</tt> class</a> <a name="FunctionPass">The <tt>FunctionPass</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>In contrast to <tt>ModulePass</tt> subclasses, <tt><a <p>In contrast to <tt>ModulePass</tt> subclasses, <tt><a
href="http://llvm.org/doxygen/classllvm_1_1Pass.html">FunctionPass</a></tt> href="http://llvm.org/doxygen/classllvm_1_1Pass.html">FunctionPass</a></tt>
@ -676,8 +674,6 @@ href="#basiccode">Hello World</a> pass for example). <tt>FunctionPass</tt>'s
may overload three virtual methods to do their work. All of these methods may overload three virtual methods to do their work. All of these methods
should return true if they modified the program, or false if they didn't.</p> should return true if they modified the program, or false if they didn't.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="doInitialization_mod"> <a name="doInitialization_mod">
@ -685,7 +681,7 @@ should return true if they modified the program, or false if they didn't.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doInitialization(Module &amp;M); <b>virtual bool</b> doInitialization(Module &amp;M);
@ -713,7 +709,7 @@ free functions that it needs, adding prototypes to the module if necessary.</p>
<a name="runOnFunction">The <tt>runOnFunction</tt> method</a> <a name="runOnFunction">The <tt>runOnFunction</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnFunction(Function &amp;F) = 0; <b>virtual bool</b> runOnFunction(Function &amp;F) = 0;
@ -732,7 +728,7 @@ be returned if the function is modified.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doFinalization(Module &amp;M); <b>virtual bool</b> doFinalization(Module &amp;M);
@ -745,12 +741,14 @@ program being compiled.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="LoopPass">The <tt>LoopPass</tt> class </a> <a name="LoopPass">The <tt>LoopPass</tt> class </a>
</h3> </h3>
<div class="doc_text"> <div>
<p> All <tt>LoopPass</tt> execute on each loop in the function independent of <p> All <tt>LoopPass</tt> execute on each loop in the function independent of
all of the other loops in the function. <tt>LoopPass</tt> processes loops in all of the other loops in the function. <tt>LoopPass</tt> processes loops in
@ -761,7 +759,6 @@ loop nest order such that outer most loop is processed last. </p>
straightforward. <tt>LoopPass</tt>'s may overload three virtual methods to straightforward. <tt>LoopPass</tt>'s may overload three virtual methods to
do their work. All these methods should return true if they modified the do their work. All these methods should return true if they modified the
program, or false if they didn't. </p> program, or false if they didn't. </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
@ -770,7 +767,7 @@ program, or false if they didn't. </p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doInitialization(Loop *, LPPassManager &amp;LPM); <b>virtual bool</b> doInitialization(Loop *, LPPassManager &amp;LPM);
@ -791,7 +788,7 @@ information.</p>
<a name="runOnLoop">The <tt>runOnLoop</tt> method</a> <a name="runOnLoop">The <tt>runOnLoop</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnLoop(Loop *, LPPassManager &amp;LPM) = 0; <b>virtual bool</b> runOnLoop(Loop *, LPPassManager &amp;LPM) = 0;
@ -809,7 +806,7 @@ should be used to update loop nest.</p>
<a name="doFinalization_loop">The <tt>doFinalization()</tt> method</a> <a name="doFinalization_loop">The <tt>doFinalization()</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doFinalization(); <b>virtual bool</b> doFinalization();
@ -822,12 +819,14 @@ program being compiled. </p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="RegionPass">The <tt>RegionPass</tt> class </a> <a name="RegionPass">The <tt>RegionPass</tt> class </a>
</h3> </h3>
<div class="doc_text"> <div>
<p> <tt>RegionPass</tt> is similar to <a href="#LoopPass"><tt>LoopPass</tt></a>, <p> <tt>RegionPass</tt> is similar to <a href="#LoopPass"><tt>LoopPass</tt></a>,
but executes on each single entry single exit region in the function. but executes on each single entry single exit region in the function.
@ -839,7 +838,6 @@ the <tt>RGPassManager</tt> interface. You may overload three virtual methods of
<tt>RegionPass</tt> to implement your own region pass. All these <tt>RegionPass</tt> to implement your own region pass. All these
methods should return true if they modified the program, or false if they didn not. methods should return true if they modified the program, or false if they didn not.
</p> </p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
@ -848,7 +846,7 @@ methods should return true if they modified the program, or false if they didn n
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doInitialization(Region *, RGPassManager &amp;RGM); <b>virtual bool</b> doInitialization(Region *, RGPassManager &amp;RGM);
@ -869,7 +867,7 @@ information.</p>
<a name="runOnRegion">The <tt>runOnRegion</tt> method</a> <a name="runOnRegion">The <tt>runOnRegion</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnRegion(Region *, RGPassManager &amp;RGM) = 0; <b>virtual bool</b> runOnRegion(Region *, RGPassManager &amp;RGM) = 0;
@ -887,7 +885,7 @@ should be used to update region tree.</p>
<a name="doFinalization_region">The <tt>doFinalization()</tt> method</a> <a name="doFinalization_region">The <tt>doFinalization()</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doFinalization(); <b>virtual bool</b> doFinalization();
@ -900,14 +898,14 @@ program being compiled. </p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a> <a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p><tt>BasicBlockPass</tt>'s are just like <a <p><tt>BasicBlockPass</tt>'s are just like <a
href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit
@ -929,8 +927,6 @@ href="#doInitialization_mod"><tt>doInitialization(Module &amp;)</tt></a> and <a
href="#doFinalization_mod"><tt>doFinalization(Module &amp;)</tt></a> methods that <a href="#doFinalization_mod"><tt>doFinalization(Module &amp;)</tt></a> methods that <a
href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have the following virtual methods that may also be implemented:</p> href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have the following virtual methods that may also be implemented:</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="doInitialization_fn"> <a name="doInitialization_fn">
@ -938,7 +934,7 @@ href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have the followi
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doInitialization(Function &amp;F); <b>virtual bool</b> doInitialization(Function &amp;F);
@ -959,7 +955,7 @@ fast).</p>
<a name="runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a> <a name="runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnBasicBlock(BasicBlock &amp;BB) = 0; <b>virtual bool</b> runOnBasicBlock(BasicBlock &amp;BB) = 0;
@ -979,7 +975,7 @@ if the basic block is modified.</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> doFinalization(Function &amp;F); <b>virtual bool</b> doFinalization(Function &amp;F);
@ -993,12 +989,14 @@ finalization.</p>
</div> </div>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h3> <h3>
<a name="MachineFunctionPass">The <tt>MachineFunctionPass</tt> class</a> <a name="MachineFunctionPass">The <tt>MachineFunctionPass</tt> class</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>A <tt>MachineFunctionPass</tt> is a part of the LLVM code generator that <p>A <tt>MachineFunctionPass</tt> is a part of the LLVM code generator that
executes on the machine-dependent representation of each LLVM function in the executes on the machine-dependent representation of each LLVM function in the
@ -1023,8 +1021,6 @@ href="#runOnMachineFunction"><tt>runOnMachineFunction</tt></a> (including global
data)</li> data)</li>
</ol> </ol>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="runOnMachineFunction"> <a name="runOnMachineFunction">
@ -1032,7 +1028,7 @@ data)</li>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual bool</b> runOnMachineFunction(MachineFunction &amp;MF) = 0; <b>virtual bool</b> runOnMachineFunction(MachineFunction &amp;MF) = 0;
@ -1053,13 +1049,17 @@ remember, you may not modify the LLVM <tt>Function</tt> or its contents from a
</div> </div>
</div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="registration">Pass registration</a> <a name="registration">Pass registration</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>In the <a href="#basiccode">Hello World</a> example pass we illustrated how <p>In the <a href="#basiccode">Hello World</a> example pass we illustrated how
pass registration works, and discussed some of the reasons that it is used and pass registration works, and discussed some of the reasons that it is used and
@ -1076,14 +1076,12 @@ well as for debug output generated by the <tt>--debug-pass</tt> option.</p>
<p>If you want your pass to be easily dumpable, you should <p>If you want your pass to be easily dumpable, you should
implement the virtual <tt>print</tt> method:</p> implement the virtual <tt>print</tt> method:</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="print">The <tt>print</tt> method</a> <a name="print">The <tt>print</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual void</b> print(std::ostream &amp;O, <b>const</b> Module *M) <b>const</b>; <b>virtual void</b> print(std::ostream &amp;O, <b>const</b> Module *M) <b>const</b>;
@ -1103,13 +1101,15 @@ depended on.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="interaction">Specifying interactions between passes</a> <a name="interaction">Specifying interactions between passes</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>One of the main responsibilities of the <tt>PassManager</tt> is to make sure <p>One of the main responsibilities of the <tt>PassManager</tt> is to make sure
that passes interact with each other correctly. Because <tt>PassManager</tt> that passes interact with each other correctly. Because <tt>PassManager</tt>
@ -1126,14 +1126,12 @@ specifies. If a pass does not implement the <tt><a
href="#getAnalysisUsage">getAnalysisUsage</a></tt> method, it defaults to not href="#getAnalysisUsage">getAnalysisUsage</a></tt> method, it defaults to not
having any prerequisite passes, and invalidating <b>all</b> other passes.</p> having any prerequisite passes, and invalidating <b>all</b> other passes.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="getAnalysisUsage">The <tt>getAnalysisUsage</tt> method</a> <a name="getAnalysisUsage">The <tt>getAnalysisUsage</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual void</b> getAnalysisUsage(AnalysisUsage &amp;Info) <b>const</b>; <b>virtual void</b> getAnalysisUsage(AnalysisUsage &amp;Info) <b>const</b>;
@ -1156,7 +1154,7 @@ object:</p>
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
If your pass requires a previous pass to be executed (an analysis for example), If your pass requires a previous pass to be executed (an analysis for example),
it can use one of these methods to arrange for it to be run before your pass. it can use one of these methods to arrange for it to be run before your pass.
@ -1184,7 +1182,7 @@ pass is.
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<p> <p>
One of the jobs of the PassManager is to optimize how and when analyses are run. One of the jobs of the PassManager is to optimize how and when analyses are run.
In particular, it attempts to avoid recomputing data unless it needs to. For In particular, it attempts to avoid recomputing data unless it needs to. For
@ -1221,7 +1219,7 @@ the fact that it hacks on the CFG.
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<i>// This example modifies the program, but does not modify the CFG</i> <i>// This example modifies the program, but does not modify the CFG</i>
@ -1241,7 +1239,7 @@ the fact that it hacks on the CFG.
</a> </a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>Pass::getAnalysis&lt;&gt;</tt> method is automatically inherited by <p>The <tt>Pass::getAnalysis&lt;&gt;</tt> method is automatically inherited by
your class, providing you with access to the passes that you declared that you your class, providing you with access to the passes that you declared that you
@ -1293,13 +1291,15 @@ if it is active. For example:</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="analysisgroup">Implementing Analysis Groups</a> <a name="analysisgroup">Implementing Analysis Groups</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we understand the basics of how passes are defined, how they are <p>Now that we understand the basics of how passes are defined, how they are
used, and how they are required from other passes, it's time to get a little bit used, and how they are required from other passes, it's time to get a little bit
@ -1318,14 +1318,12 @@ between these two extremes for other implementations). To cleanly support
situations like this, the LLVM Pass Infrastructure supports the notion of situations like this, the LLVM Pass Infrastructure supports the notion of
Analysis Groups.</p> Analysis Groups.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="agconcepts">Analysis Group Concepts</a> <a name="agconcepts">Analysis Group Concepts</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>An Analysis Group is a single simple interface that may be implemented by <p>An Analysis Group is a single simple interface that may be implemented by
multiple different passes. Analysis Groups can be given human readable names multiple different passes. Analysis Groups can be given human readable names
@ -1376,7 +1374,7 @@ hypothetical example) instead.</p>
<a name="registerag">Using <tt>RegisterAnalysisGroup</tt></a> <a name="registerag">Using <tt>RegisterAnalysisGroup</tt></a>
</h4> </h4>
<div class="doc_text"> <div>
<p>The <tt>RegisterAnalysisGroup</tt> template is used to register the analysis <p>The <tt>RegisterAnalysisGroup</tt> template is used to register the analysis
group itself, while the <tt>INITIALIZE_AG_PASS</tt> is used to add pass group itself, while the <tt>INITIALIZE_AG_PASS</tt> is used to add pass
@ -1433,13 +1431,15 @@ pass is the default implementation for the interface.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="passStatistics">Pass Statistics</a> <a name="passStatistics">Pass Statistics</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The <a <p>The <a
href="http://llvm.org/doxygen/Statistic_8h-source.html"><tt>Statistic</tt></a> href="http://llvm.org/doxygen/Statistic_8h-source.html"><tt>Statistic</tt></a>
class is designed to be an easy way to expose various success class is designed to be an easy way to expose various success
@ -1456,7 +1456,7 @@ line. See the <a href="http://llvm.org/docs/ProgrammersManual.html#Statistic">St
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The <a <p>The <a
href="http://llvm.org/doxygen/PassManager_8h-source.html"><tt>PassManager</tt></a> href="http://llvm.org/doxygen/PassManager_8h-source.html"><tt>PassManager</tt></a>
@ -1623,14 +1623,12 @@ Hello: main
<p>Which shows that we don't accidentally invalidate dominator information <p>Which shows that we don't accidentally invalidate dominator information
anymore, and therefore do not have to compute it twice.</p> anymore, and therefore do not have to compute it twice.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="releaseMemory">The <tt>releaseMemory</tt> method</a> <a name="releaseMemory">The <tt>releaseMemory</tt> method</a>
</h4> </h4>
<div class="doc_text"> <div>
<div class="doc_code"><pre> <div class="doc_code"><pre>
<b>virtual void</b> releaseMemory(); <b>virtual void</b> releaseMemory();
@ -1651,13 +1649,15 @@ class, before the next call of <tt>run*</tt> in your pass.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="registering">Registering dynamically loaded passes</a> <a name="registering">Registering dynamically loaded passes</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><i>Size matters</i> when constructing production quality tools using llvm, <p><i>Size matters</i> when constructing production quality tools using llvm,
both for the purposes of distribution, and for regulating the resident code size both for the purposes of distribution, and for regulating the resident code size
@ -1684,14 +1684,12 @@ the static destructor <i>unregisters</i>. Thus a pass that is statically linked
in the tool will be registered at start up. A dynamically loaded pass will in the tool will be registered at start up. A dynamically loaded pass will
register on load and unregister at unload.</p> register on load and unregister at unload.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h3> <h3>
<a name="registering_existing">Using existing registries</a> <a name="registering_existing">Using existing registries</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>There are predefined registries to track instruction scheduling <p>There are predefined registries to track instruction scheduling
(<tt>RegisterScheduler</tt>) and register allocation (<tt>RegisterRegAlloc</tt>) (<tt>RegisterScheduler</tt>) and register allocation (<tt>RegisterRegAlloc</tt>)
@ -1756,7 +1754,7 @@ call line to <tt>llvm/Codegen/LinkAllCodegenComponents.h</tt>.</p>
<a name="registering_new">Creating new registries</a> <a name="registering_new">Creating new registries</a>
</h3> </h3>
<div class="doc_text"> <div>
<p>The easiest way to get started is to clone one of the existing registries; we <p>The easiest way to get started is to clone one of the existing registries; we
recommend <tt>llvm/CodeGen/RegAllocRegistry.h</tt>. The key things to modify recommend <tt>llvm/CodeGen/RegAllocRegistry.h</tt>. The key things to modify
@ -1784,13 +1782,15 @@ creator.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="debughints">Using GDB with dynamically loaded passes</a> <a name="debughints">Using GDB with dynamically loaded passes</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Unfortunately, using GDB with dynamically loaded passes is not as easy as it <p>Unfortunately, using GDB with dynamically loaded passes is not as easy as it
should be. First of all, you can't set a breakpoint in a shared object that has should be. First of all, you can't set a breakpoint in a shared object that has
@ -1802,14 +1802,12 @@ GDB.</p>
transformation invoked by <tt>opt</tt>, although nothing described here depends transformation invoked by <tt>opt</tt>, although nothing described here depends
on that.</p> on that.</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="breakpoint">Setting a breakpoint in your pass</a> <a name="breakpoint">Setting a breakpoint in your pass</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>First thing you do is start <tt>gdb</tt> on the <tt>opt</tt> process:</p> <p>First thing you do is start <tt>gdb</tt> on the <tt>opt</tt> process:</p>
@ -1854,7 +1852,7 @@ or do other standard debugging stuff.</p>
<a name="debugmisc">Miscellaneous Problems</a> <a name="debugmisc">Miscellaneous Problems</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Once you have the basics down, there are a couple of problems that GDB has, <p>Once you have the basics down, there are a couple of problems that GDB has,
some with solutions, some without.</p> some with solutions, some without.</p>
@ -1882,26 +1880,26 @@ href="mailto:sabre@nondot.org">Chris</a>.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2> <h2>
<a name="future">Future extensions planned</a> <a name="future">Future extensions planned</a>
</h2> </h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Although the LLVM Pass Infrastructure is very capable as it stands, and does <p>Although the LLVM Pass Infrastructure is very capable as it stands, and does
some nifty stuff, there are things we'd like to add in the future. Here is some nifty stuff, there are things we'd like to add in the future. Here is
where we are going:</p> where we are going:</p>
</div>
<!-- _______________________________________________________________________ --> <!-- _______________________________________________________________________ -->
<h4> <h4>
<a name="SMP">Multithreaded LLVM</a> <a name="SMP">Multithreaded LLVM</a>
</h4> </h4>
<div class="doc_text"> <div>
<p>Multiple CPU machines are becoming more common and compilation can never be <p>Multiple CPU machines are becoming more common and compilation can never be
fast enough: obviously we should allow for a multithreaded compiler. Because of fast enough: obviously we should allow for a multithreaded compiler. Because of
@ -1919,6 +1917,8 @@ Despite that, we have kept the LLVM passes SMP ready, and you should too.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <address>

2
docs/index.html
View File

@ -13,7 +13,6 @@
see <a href="http://llvm.org/releases/">the download page</a> to find see <a href="http://llvm.org/releases/">the download page</a> to find
your documentation.</p> your documentation.</p>
<div class="doc_text">
<table class="layout" width="95%"><tr class="layout"><td class="left"> <table class="layout" width="95%"><tr class="layout"><td class="left">
<ul> <ul>
<li><a href="#llvmdesign">LLVM Design</a></li> <li><a href="#llvmdesign">LLVM Design</a></li>
@ -32,7 +31,6 @@ your documentation.</p>
</p> </p>
</form> </form>
</td></tr></table> </td></tr></table>
</div>
<div class="doc_author"> <div class="doc_author">
<p>Written by <a href="http://llvm.org/">The LLVM Team</a></p> <p>Written by <a href="http://llvm.org/">The LLVM Team</a></p>

6
docs/tutorial/LangImpl1.html
View File

@ -33,7 +33,7 @@
<h2><a name="intro">Tutorial Introduction</a></h2> <h2><a name="intro">Tutorial Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to the "Implementing a language with LLVM" tutorial. This tutorial <p>Welcome to the "Implementing a language with LLVM" tutorial. This tutorial
runs through the implementation of a simple language, showing how fun and runs through the implementation of a simple language, showing how fun and
@ -126,7 +126,7 @@ languages!</p>
<h2><a name="language">The Basic Language</a></h2> <h2><a name="language">The Basic Language</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This tutorial will be illustrated with a toy language that we'll call <p>This tutorial will be illustrated with a toy language that we'll call
"<a href="http://en.wikipedia.org/wiki/Kaleidoscope">Kaleidoscope</a>" (derived "<a href="http://en.wikipedia.org/wiki/Kaleidoscope">Kaleidoscope</a>" (derived
@ -184,7 +184,7 @@ a Mandelbrot Set</a> at various levels of magnification.</p>
<h2><a name="lexer">The Lexer</a></h2> <h2><a name="lexer">The Lexer</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>When it comes to implementing a language, the first thing needed is <p>When it comes to implementing a language, the first thing needed is
the ability to process a text file and recognize what it says. The traditional the ability to process a text file and recognize what it says. The traditional

18
docs/tutorial/LangImpl2.html
View File

@ -39,7 +39,7 @@
<h2><a name="intro">Chapter 2 Introduction</a></h2> <h2><a name="intro">Chapter 2 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 2 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 2 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. This chapter shows you how to use the lexer, built in with LLVM</a>" tutorial. This chapter shows you how to use the lexer, built in
@ -64,7 +64,7 @@ Tree.</p>
<h2><a name="ast">The Abstract Syntax Tree (AST)</a></h2> <h2><a name="ast">The Abstract Syntax Tree (AST)</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The AST for a program captures its behavior in such a way that it is easy for <p>The AST for a program captures its behavior in such a way that it is easy for
later stages of the compiler (e.g. code generation) to interpret. We basically later stages of the compiler (e.g. code generation) to interpret. We basically
@ -181,7 +181,7 @@ bodies in Kaleidoscope.</p>
<h2><a name="parserbasics">Parser Basics</a></h2> <h2><a name="parserbasics">Parser Basics</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we have an AST to build, we need to define the parser code to build <p>Now that we have an AST to build, we need to define the parser code to build
it. The idea here is that we want to parse something like "x+y" (which is it. The idea here is that we want to parse something like "x+y" (which is
@ -242,7 +242,7 @@ piece of our grammar: numeric literals.</p>
<h2><a name="parserprimexprs">Basic Expression Parsing</a></h2> <h2><a name="parserprimexprs">Basic Expression Parsing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>We start with numeric literals, because they are the simplest to process. <p>We start with numeric literals, because they are the simplest to process.
For each production in our grammar, we'll define a function which parses that For each production in our grammar, we'll define a function which parses that
@ -396,7 +396,7 @@ They are a bit more complex.</p>
<h2><a name="parserbinops">Binary Expression Parsing</a></h2> <h2><a name="parserbinops">Binary Expression Parsing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Binary expressions are significantly harder to parse because they are often <p>Binary expressions are significantly harder to parse because they are often
ambiguous. For example, when given the string "x+y*z", the parser can choose ambiguous. For example, when given the string "x+y*z", the parser can choose
@ -618,7 +618,7 @@ handle function definitions, etc.</p>
<h2><a name="parsertop">Parsing the Rest</a></h2> <h2><a name="parsertop">Parsing the Rest</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The next thing missing is handling of function prototypes. In Kaleidoscope, The next thing missing is handling of function prototypes. In Kaleidoscope,
@ -715,7 +715,7 @@ actually <em>execute</em> this code we've built!</p>
<h2><a name="driver">The Driver</a></h2> <h2><a name="driver">The Driver</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The driver for this simply invokes all of the parsing pieces with a top-level <p>The driver for this simply invokes all of the parsing pieces with a top-level
dispatch loop. There isn't much interesting here, so I'll just include the dispatch loop. There isn't much interesting here, so I'll just include the
@ -754,7 +754,7 @@ type "4+5;", and the parser will know you are done.</p>
<h2><a name="conclusions">Conclusions</a></h2> <h2><a name="conclusions">Conclusions</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>With just under 400 lines of commented code (240 lines of non-comment, <p>With just under 400 lines of commented code (240 lines of non-comment,
non-blank code), we fully defined our minimal language, including a lexer, non-blank code), we fully defined our minimal language, including a lexer,
@ -791,7 +791,7 @@ Representation (IR) from the AST.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for this and the previous chapter. Here is the complete code listing for this and the previous chapter.

12
docs/tutorial/LangImpl3.html
View File

@ -37,7 +37,7 @@ Support</li>
<h2><a name="intro">Chapter 3 Introduction</a></h2> <h2><a name="intro">Chapter 3 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 3 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 3 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. This chapter shows you how to transform the <a with LLVM</a>" tutorial. This chapter shows you how to transform the <a
@ -60,7 +60,7 @@ releases page</a>.</p>
<h2><a name="basics">Code Generation Setup</a></h2> <h2><a name="basics">Code Generation Setup</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
In order to generate LLVM IR, we want some simple setup to get started. First In order to generate LLVM IR, we want some simple setup to get started. First
@ -150,7 +150,7 @@ has already been done, and we'll just use it to emit code.
<h2><a name="exprs">Expression Code Generation</a></h2> <h2><a name="exprs">Expression Code Generation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Generating LLVM code for expression nodes is very straightforward: less <p>Generating LLVM code for expression nodes is very straightforward: less
than 45 lines of commented code for all four of our expression nodes. First than 45 lines of commented code for all four of our expression nodes. First
@ -296,7 +296,7 @@ basic framework.</p>
<h2><a name="funcs">Function Code Generation</a></h2> <h2><a name="funcs">Function Code Generation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Code generation for prototypes and functions must handle a number of <p>Code generation for prototypes and functions must handle a number of
details, which make their code less beautiful than expression code details, which make their code less beautiful than expression code
@ -518,7 +518,7 @@ def bar() foo(1, 2); # error, unknown function "foo"
<h2><a name="driver">Driver Changes and Closing Thoughts</a></h2> <h2><a name="driver">Driver Changes and Closing Thoughts</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
For now, code generation to LLVM doesn't really get us much, except that we can For now, code generation to LLVM doesn't really get us much, except that we can
@ -659,7 +659,7 @@ support</a> to this so we can actually start running code!</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

10
docs/tutorial/LangImpl4.html
View File

@ -36,7 +36,7 @@ Flow</li>
<h2><a name="intro">Chapter 4 Introduction</a></h2> <h2><a name="intro">Chapter 4 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 4 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 4 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. Chapters 1-3 described the implementation of a simple with LLVM</a>" tutorial. Chapters 1-3 described the implementation of a simple
@ -51,7 +51,7 @@ for the Kaleidoscope language.</p>
<h2><a name="trivialconstfold">Trivial Constant Folding</a></h2> <h2><a name="trivialconstfold">Trivial Constant Folding</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Our demonstration for Chapter 3 is elegant and easy to extend. Unfortunately, Our demonstration for Chapter 3 is elegant and easy to extend. Unfortunately,
@ -136,7 +136,7 @@ range of optimizations that you can use, in the form of "passes".</p>
<h2><a name="optimizerpasses">LLVM Optimization Passes</a></h2> <h2><a name="optimizerpasses">LLVM Optimization Passes</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>LLVM provides many optimization passes, which do many different sorts of <p>LLVM provides many optimization passes, which do many different sorts of
things and have different tradeoffs. Unlike other systems, LLVM doesn't hold things and have different tradeoffs. Unlike other systems, LLVM doesn't hold
@ -267,7 +267,7 @@ executing it!</p>
<h2><a name="jit">Adding a JIT Compiler</a></h2> <h2><a name="jit">Adding a JIT Compiler</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Code that is available in LLVM IR can have a wide variety of tools <p>Code that is available in LLVM IR can have a wide variety of tools
applied to it. For example, you can run optimizations on it (as we did above), applied to it. For example, you can run optimizations on it (as we did above),
@ -475,7 +475,7 @@ tackling some interesting LLVM IR issues along the way.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

36
docs/tutorial/LangImpl5.html
View File

@ -51,7 +51,7 @@ User-defined Operators</li>
<h2><a name="intro">Chapter 5 Introduction</a></h2> <h2><a name="intro">Chapter 5 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 5 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 5 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. Parts 1-4 described the implementation of the simple with LLVM</a>" tutorial. Parts 1-4 described the implementation of the simple
@ -68,7 +68,7 @@ have an if/then/else expression plus a simple 'for' loop.</p>
<h2><a name="ifthen">If/Then/Else</a></h2> <h2><a name="ifthen">If/Then/Else</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Extending Kaleidoscope to support if/then/else is quite straightforward. It Extending Kaleidoscope to support if/then/else is quite straightforward. It
@ -108,14 +108,12 @@ Since Kaleidoscope allows side-effects, this behavior is important to nail down.
<p>Now that we know what we "want", lets break this down into its constituent <p>Now that we know what we "want", lets break this down into its constituent
pieces.</p> pieces.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="iflexer">Lexer Extensions for If/Then/Else</a></h4> <h4><a name="iflexer">Lexer Extensions for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The lexer extensions are straightforward. First we add new enum values <p>The lexer extensions are straightforward. First we add new enum values
for the relevant tokens:</p> for the relevant tokens:</p>
@ -148,7 +146,7 @@ stuff:</p>
<h4><a name="ifast">AST Extensions for If/Then/Else</a></h4> <h4><a name="ifast">AST Extensions for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>To represent the new expression we add a new AST node for it:</p> <p>To represent the new expression we add a new AST node for it:</p>
@ -173,7 +171,7 @@ public:
<h4><a name="ifparser">Parser Extensions for If/Then/Else</a></h4> <h4><a name="ifparser">Parser Extensions for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Now that we have the relevant tokens coming from the lexer and we have the <p>Now that we have the relevant tokens coming from the lexer and we have the
AST node to build, our parsing logic is relatively straightforward. First we AST node to build, our parsing logic is relatively straightforward. First we
@ -231,7 +229,7 @@ static ExprAST *ParsePrimary() {
<h4><a name="ifir">LLVM IR for If/Then/Else</a></h4> <h4><a name="ifir">LLVM IR for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Now that we have it parsing and building the AST, the final piece is adding <p>Now that we have it parsing and building the AST, the final piece is adding
LLVM code generation support. This is the most interesting part of the LLVM code generation support. This is the most interesting part of the
@ -347,7 +345,7 @@ directly.</p>
<h4><a name="ifcodegen">Code Generation for If/Then/Else</a></h4> <h4><a name="ifcodegen">Code Generation for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>In order to generate code for this, we implement the <tt>Codegen</tt> method <p>In order to generate code for this, we implement the <tt>Codegen</tt> method
for <tt>IfExprAST</tt>:</p> for <tt>IfExprAST</tt>:</p>
@ -496,11 +494,13 @@ another useful expression that is familiar from non-functional languages...</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="for">'for' Loop Expression</a></h2> <h2><a name="for">'for' Loop Expression</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we know how to add basic control flow constructs to the language, <p>Now that we know how to add basic control flow constructs to the language,
we have the tools to add more powerful things. Lets add something more we have the tools to add more powerful things. Lets add something more
@ -529,13 +529,11 @@ variables, it will get more useful.</p>
<p>As before, lets talk about the changes that we need to Kaleidoscope to <p>As before, lets talk about the changes that we need to Kaleidoscope to
support this.</p> support this.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="forlexer">Lexer Extensions for the 'for' Loop</a></h4> <h4><a name="forlexer">Lexer Extensions for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The lexer extensions are the same sort of thing as for if/then/else:</p> <p>The lexer extensions are the same sort of thing as for if/then/else:</p>
@ -564,7 +562,7 @@ support this.</p>
<h4><a name="forast">AST Extensions for the 'for' Loop</a></h4> <h4><a name="forast">AST Extensions for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The AST node is just as simple. It basically boils down to capturing <p>The AST node is just as simple. It basically boils down to capturing
the variable name and the constituent expressions in the node.</p> the variable name and the constituent expressions in the node.</p>
@ -590,7 +588,7 @@ public:
<h4><a name="forparser">Parser Extensions for the 'for' Loop</a></h4> <h4><a name="forparser">Parser Extensions for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The parser code is also fairly standard. The only interesting thing here is <p>The parser code is also fairly standard. The only interesting thing here is
handling of the optional step value. The parser code handles it by checking to handling of the optional step value. The parser code handles it by checking to
@ -649,7 +647,7 @@ static ExprAST *ParseForExpr() {
<h4><a name="forir">LLVM IR for the 'for' Loop</a></h4> <h4><a name="forir">LLVM IR for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Now we get to the good part: the LLVM IR we want to generate for this thing. <p>Now we get to the good part: the LLVM IR we want to generate for this thing.
With the simple example above, we get this LLVM IR (note that this dump is With the simple example above, we get this LLVM IR (note that this dump is
@ -694,7 +692,7 @@ expressions, and some basic blocks. Lets see how this fits together.</p>
<h4><a name="forcodegen">Code Generation for the 'for' Loop</a></h4> <h4><a name="forcodegen">Code Generation for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The first part of Codegen is very simple: we just output the start expression <p>The first part of Codegen is very simple: we just output the start expression
for the loop value:</p> for the loop value:</p>
@ -867,11 +865,13 @@ language.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

12
docs/tutorial/LangImpl6.html
View File

@ -37,7 +37,7 @@ Variables / SSA Construction</li>
<h2><a name="intro">Chapter 6 Introduction</a></h2> <h2><a name="intro">Chapter 6 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 6 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 6 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. At this point in our tutorial, we now have a fully with LLVM</a>" tutorial. At this point in our tutorial, we now have a fully
@ -63,7 +63,7 @@ an example of what you can build with Kaleidoscope and its feature set.</p>
<h2><a name="idea">User-defined Operators: the Idea</a></h2> <h2><a name="idea">User-defined Operators: the Idea</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The "operator overloading" that we will add to Kaleidoscope is more general than The "operator overloading" that we will add to Kaleidoscope is more general than
@ -128,7 +128,7 @@ operators.</p>
<h2><a name="binary">User-defined Binary Operators</a></h2> <h2><a name="binary">User-defined Binary Operators</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Adding support for user-defined binary operators is pretty simple with our <p>Adding support for user-defined binary operators is pretty simple with our
current framework. We'll first add support for the unary/binary keywords:</p> current framework. We'll first add support for the unary/binary keywords:</p>
@ -345,7 +345,7 @@ see what it takes.</p>
<h2><a name="unary">User-defined Unary Operators</a></h2> <h2><a name="unary">User-defined Unary Operators</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Since we don't currently support unary operators in the Kaleidoscope <p>Since we don't currently support unary operators in the Kaleidoscope
language, we'll need to add everything to support them. Above, we added simple language, we'll need to add everything to support them. Above, we added simple
@ -494,7 +494,7 @@ is simpler primarily because it doesn't need to handle any predefined operators.
<h2><a name="example">Kicking the Tires</a></h2> <h2><a name="example">Kicking the Tires</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>It is somewhat hard to believe, but with a few simple extensions we've <p>It is somewhat hard to believe, but with a few simple extensions we've
covered in the last chapters, we have grown a real-ish language. With this, we covered in the last chapters, we have grown a real-ish language. With this, we
@ -799,7 +799,7 @@ add variable mutation without building SSA in your front-end.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

16
docs/tutorial/LangImpl7.html
View File

@ -41,7 +41,7 @@
<h2><a name="intro">Chapter 7 Introduction</a></h2> <h2><a name="intro">Chapter 7 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 7 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 7 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. In chapters 1 through 6, we've built a very with LLVM</a>" tutorial. In chapters 1 through 6, we've built a very
@ -69,7 +69,7 @@ support for this, though the way it works is a bit unexpected for some.</p>
<h2><a name="why">Why is this a hard problem?</a></h2> <h2><a name="why">Why is this a hard problem?</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
To understand why mutable variables cause complexities in SSA construction, To understand why mutable variables cause complexities in SSA construction,
@ -143,7 +143,7 @@ logic.</p>
<h2><a name="memory">Memory in LLVM</a></h2> <h2><a name="memory">Memory in LLVM</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The 'trick' here is that while LLVM does require all register values to be <p>The 'trick' here is that while LLVM does require all register values to be
in SSA form, it does not require (or permit) memory objects to be in SSA form. in SSA form, it does not require (or permit) memory objects to be in SSA form.
@ -324,7 +324,7 @@ variables now!
<h2><a name="kalvars">Mutable Variables in Kaleidoscope</a></h2> <h2><a name="kalvars">Mutable Variables in Kaleidoscope</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we know the sort of problem we want to tackle, lets see what this <p>Now that we know the sort of problem we want to tackle, lets see what this
looks like in the context of our little Kaleidoscope language. We're going to looks like in the context of our little Kaleidoscope language. We're going to
@ -380,7 +380,7 @@ Kaleidoscope to support new variable definitions.
<h2><a name="adjustments">Adjusting Existing Variables for Mutation</a></h2> <h2><a name="adjustments">Adjusting Existing Variables for Mutation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The symbol table in Kaleidoscope is managed at code generation time by the The symbol table in Kaleidoscope is managed at code generation time by the
@ -649,7 +649,7 @@ we'll add the assignment operator.</p>
<h2><a name="assignment">New Assignment Operator</a></h2> <h2><a name="assignment">New Assignment Operator</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>With our current framework, adding a new assignment operator is really <p>With our current framework, adding a new assignment operator is really
simple. We will parse it just like any other binary operator, but handle it simple. We will parse it just like any other binary operator, but handle it
@ -746,7 +746,7 @@ add this next!
<h2><a name="localvars">User-defined Local Variables</a></h2> <h2><a name="localvars">User-defined Local Variables</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Adding var/in is just like any other other extensions we made to <p>Adding var/in is just like any other other extensions we made to
Kaleidoscope: we extend the lexer, the parser, the AST and the code generator. Kaleidoscope: we extend the lexer, the parser, the AST and the code generator.
@ -979,7 +979,7 @@ anywhere in sight.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with mutable Here is the complete code listing for our running example, enhanced with mutable

24
docs/tutorial/LangImpl8.html
View File

@ -45,7 +45,7 @@
<h2><a name="conclusion">Tutorial Conclusion</a></h2> <h2><a name="conclusion">Tutorial Conclusion</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to the the final chapter of the "<a href="index.html">Implementing a <p>Welcome to the the final chapter of the "<a href="index.html">Implementing a
language with LLVM</a>" tutorial. In the course of this tutorial, we have grown language with LLVM</a>" tutorial. In the course of this tutorial, we have grown
@ -156,18 +156,16 @@ are very useful if you want to take advantage of LLVM's capabilities.</p>
<h2><a name="llvmirproperties">Properties of the LLVM IR</a></h2> <h2><a name="llvmirproperties">Properties of the LLVM IR</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>We have a couple common questions about code in the LLVM IR form - lets just <p>We have a couple common questions about code in the LLVM IR form - lets just
get these out of the way right now, shall we?</p> get these out of the way right now, shall we?</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="targetindep">Target Independence</a></h4> <h4><a name="targetindep">Target Independence</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Kaleidoscope is an example of a "portable language": any program written in <p>Kaleidoscope is an example of a "portable language": any program written in
Kaleidoscope will work the same way on any target that it runs on. Many other Kaleidoscope will work the same way on any target that it runs on. Many other
@ -221,7 +219,7 @@ in-kernel language.</p>
<h4><a name="safety">Safety Guarantees</a></h4> <h4><a name="safety">Safety Guarantees</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Many of the languages above are also "safe" languages: it is impossible for <p>Many of the languages above are also "safe" languages: it is impossible for
a program written in Java to corrupt its address space and crash the process a program written in Java to corrupt its address space and crash the process
@ -243,7 +241,7 @@ list</a> if you are interested in more details.</p>
<h4><a name="langspecific">Language-Specific Optimizations</a></h4> <h4><a name="langspecific">Language-Specific Optimizations</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>One thing about LLVM that turns off many people is that it does not solve all <p>One thing about LLVM that turns off many people is that it does not solve all
the world's problems in one system (sorry 'world hunger', someone else will have the world's problems in one system (sorry 'world hunger', someone else will have
@ -293,23 +291,23 @@ language-specific AST.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="tipsandtricks">Tips and Tricks</a></h2> <h2><a name="tipsandtricks">Tips and Tricks</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>There is a variety of useful tips and tricks that you come to know after <p>There is a variety of useful tips and tricks that you come to know after
working on/with LLVM that aren't obvious at first glance. Instead of letting working on/with LLVM that aren't obvious at first glance. Instead of letting
everyone rediscover them, this section talks about some of these issues.</p> everyone rediscover them, this section talks about some of these issues.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="offsetofsizeof">Implementing portable offsetof/sizeof</a></h4> <h4><a name="offsetofsizeof">Implementing portable offsetof/sizeof</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>One interesting thing that comes up, if you are trying to keep the code <p>One interesting thing that comes up, if you are trying to keep the code
generated by your compiler "target independent", is that you often need to know generated by your compiler "target independent", is that you often need to know
@ -329,7 +327,7 @@ in a portable way.</p>
<h4><a name="gcstack">Garbage Collected Stack Frames</a></h4> <h4><a name="gcstack">Garbage Collected Stack Frames</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Some languages want to explicitly manage their stack frames, often so that <p>Some languages want to explicitly manage their stack frames, often so that
they are garbage collected or to allow easy implementation of closures. There they are garbage collected or to allow easy implementation of closures. There
@ -343,6 +341,8 @@ Passing Style</a> and the use of tail calls (which LLVM also supports).</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <address>

6
docs/tutorial/OCamlLangImpl1.html
View File

@ -38,7 +38,7 @@ AST</li>
<h2><a name="intro">Tutorial Introduction</a></h2> <h2><a name="intro">Tutorial Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to the "Implementing a language with LLVM" tutorial. This tutorial <p>Welcome to the "Implementing a language with LLVM" tutorial. This tutorial
runs through the implementation of a simple language, showing how fun and runs through the implementation of a simple language, showing how fun and
@ -133,7 +133,7 @@ languages!</p>
<h2><a name="language">The Basic Language</a></h2> <h2><a name="language">The Basic Language</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>This tutorial will be illustrated with a toy language that we'll call <p>This tutorial will be illustrated with a toy language that we'll call
"<a href="http://en.wikipedia.org/wiki/Kaleidoscope">Kaleidoscope</a>" (derived "<a href="http://en.wikipedia.org/wiki/Kaleidoscope">Kaleidoscope</a>" (derived
@ -191,7 +191,7 @@ a Mandelbrot Set</a> at various levels of magnification.</p>
<h2><a name="lexer">The Lexer</a></h2> <h2><a name="lexer">The Lexer</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>When it comes to implementing a language, the first thing needed is <p>When it comes to implementing a language, the first thing needed is
the ability to process a text file and recognize what it says. The traditional the ability to process a text file and recognize what it says. The traditional

18
docs/tutorial/OCamlLangImpl2.html
View File

@ -43,7 +43,7 @@
<h2><a name="intro">Chapter 2 Introduction</a></h2> <h2><a name="intro">Chapter 2 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 2 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 2 of the "<a href="index.html">Implementing a language
with LLVM in Objective Caml</a>" tutorial. This chapter shows you how to use with LLVM in Objective Caml</a>" tutorial. This chapter shows you how to use
@ -68,7 +68,7 @@ Tree.</p>
<h2><a name="ast">The Abstract Syntax Tree (AST)</a></h2> <h2><a name="ast">The Abstract Syntax Tree (AST)</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The AST for a program captures its behavior in such a way that it is easy for <p>The AST for a program captures its behavior in such a way that it is easy for
later stages of the compiler (e.g. code generation) to interpret. We basically later stages of the compiler (e.g. code generation) to interpret. We basically
@ -149,7 +149,7 @@ bodies in Kaleidoscope.</p>
<h2><a name="parserbasics">Parser Basics</a></h2> <h2><a name="parserbasics">Parser Basics</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we have an AST to build, we need to define the parser code to build <p>Now that we have an AST to build, we need to define the parser code to build
it. The idea here is that we want to parse something like "x+y" (which is it. The idea here is that we want to parse something like "x+y" (which is
@ -184,7 +184,7 @@ piece of our grammar: numeric literals.</p>
<h2><a name="parserprimexprs">Basic Expression Parsing</a></h2> <h2><a name="parserprimexprs">Basic Expression Parsing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>We start with numeric literals, because they are the simplest to process. <p>We start with numeric literals, because they are the simplest to process.
For each production in our grammar, we'll define a function which parses that For each production in our grammar, we'll define a function which parses that
@ -305,7 +305,7 @@ They are a bit more complex.</p>
<h2><a name="parserbinops">Binary Expression Parsing</a></h2> <h2><a name="parserbinops">Binary Expression Parsing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Binary expressions are significantly harder to parse because they are often <p>Binary expressions are significantly harder to parse because they are often
ambiguous. For example, when given the string "x+y*z", the parser can choose ambiguous. For example, when given the string "x+y*z", the parser can choose
@ -518,7 +518,7 @@ handle function definitions, etc.</p>
<h2><a name="parsertop">Parsing the Rest</a></h2> <h2><a name="parsertop">Parsing the Rest</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The next thing missing is handling of function prototypes. In Kaleidoscope, The next thing missing is handling of function prototypes. In Kaleidoscope,
@ -597,7 +597,7 @@ actually <em>execute</em> this code we've built!</p>
<h2><a name="driver">The Driver</a></h2> <h2><a name="driver">The Driver</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The driver for this simply invokes all of the parsing pieces with a top-level <p>The driver for this simply invokes all of the parsing pieces with a top-level
dispatch loop. There isn't much interesting here, so I'll just include the dispatch loop. There isn't much interesting here, so I'll just include the
@ -653,7 +653,7 @@ type "4+5;", and the parser will know you are done.</p>
<h2><a name="conclusions">Conclusions</a></h2> <h2><a name="conclusions">Conclusions</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>With just under 300 lines of commented code (240 lines of non-comment, <p>With just under 300 lines of commented code (240 lines of non-comment,
non-blank code), we fully defined our minimal language, including a lexer, non-blank code), we fully defined our minimal language, including a lexer,
@ -690,7 +690,7 @@ Representation (IR) from the AST.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for this and the previous chapter. Here is the complete code listing for this and the previous chapter.

12
docs/tutorial/OCamlLangImpl3.html
View File

@ -41,7 +41,7 @@ Support</li>
<h2><a name="intro">Chapter 3 Introduction</a></h2> <h2><a name="intro">Chapter 3 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 3 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 3 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. This chapter shows you how to transform the <a with LLVM</a>" tutorial. This chapter shows you how to transform the <a
@ -60,7 +60,7 @@ LLVM SVN to work. LLVM 2.2 and before will not work with it.</p>
<h2><a name="basics">Code Generation Setup</a></h2> <h2><a name="basics">Code Generation Setup</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
In order to generate LLVM IR, we want some simple setup to get started. First In order to generate LLVM IR, we want some simple setup to get started. First
@ -131,7 +131,7 @@ that this has already been done, and we'll just use it to emit code.</p>
<h2><a name="exprs">Expression Code Generation</a></h2> <h2><a name="exprs">Expression Code Generation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Generating LLVM code for expression nodes is very straightforward: less <p>Generating LLVM code for expression nodes is very straightforward: less
than 30 lines of commented code for all four of our expression nodes. First than 30 lines of commented code for all four of our expression nodes. First
@ -266,7 +266,7 @@ basic framework.</p>
<h2><a name="funcs">Function Code Generation</a></h2> <h2><a name="funcs">Function Code Generation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Code generation for prototypes and functions must handle a number of <p>Code generation for prototypes and functions must handle a number of
details, which make their code less beautiful than expression code details, which make their code less beautiful than expression code
@ -469,7 +469,7 @@ def bar() foo(1, 2); # error, unknown function "foo"
<h2><a name="driver">Driver Changes and Closing Thoughts</a></h2> <h2><a name="driver">Driver Changes and Closing Thoughts</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
For now, code generation to LLVM doesn't really get us much, except that we can For now, code generation to LLVM doesn't really get us much, except that we can
@ -609,7 +609,7 @@ support</a> to this so we can actually start running code!</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

10
docs/tutorial/OCamlLangImpl4.html
View File

@ -40,7 +40,7 @@ Flow</li>
<h2><a name="intro">Chapter 4 Introduction</a></h2> <h2><a name="intro">Chapter 4 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 4 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 4 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. Chapters 1-3 described the implementation of a simple with LLVM</a>" tutorial. Chapters 1-3 described the implementation of a simple
@ -55,7 +55,7 @@ for the Kaleidoscope language.</p>
<h2><a name="trivialconstfold">Trivial Constant Folding</a></h2> <h2><a name="trivialconstfold">Trivial Constant Folding</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p><b>Note:</b> the default <tt>IRBuilder</tt> now always includes the constant <p><b>Note:</b> the default <tt>IRBuilder</tt> now always includes the constant
folding optimisations below.<p> folding optimisations below.<p>
@ -150,7 +150,7 @@ range of optimizations that you can use, in the form of "passes".</p>
<h2><a name="optimizerpasses">LLVM Optimization Passes</a></h2> <h2><a name="optimizerpasses">LLVM Optimization Passes</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>LLVM provides many optimization passes, which do many different sorts of <p>LLVM provides many optimization passes, which do many different sorts of
things and have different tradeoffs. Unlike other systems, LLVM doesn't hold things and have different tradeoffs. Unlike other systems, LLVM doesn't hold
@ -284,7 +284,7 @@ executing it!</p>
<h2><a name="jit">Adding a JIT Compiler</a></h2> <h2><a name="jit">Adding a JIT Compiler</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Code that is available in LLVM IR can have a wide variety of tools <p>Code that is available in LLVM IR can have a wide variety of tools
applied to it. For example, you can run optimizations on it (as we did above), applied to it. For example, you can run optimizations on it (as we did above),
@ -487,7 +487,7 @@ constructs</a>, tackling some interesting LLVM IR issues along the way.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

36
docs/tutorial/OCamlLangImpl5.html
View File

@ -55,7 +55,7 @@ User-defined Operators</li>
<h2><a name="intro">Chapter 5 Introduction</a></h2> <h2><a name="intro">Chapter 5 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 5 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 5 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. Parts 1-4 described the implementation of the simple with LLVM</a>" tutorial. Parts 1-4 described the implementation of the simple
@ -72,7 +72,7 @@ have an if/then/else expression plus a simple 'for' loop.</p>
<h2><a name="ifthen">If/Then/Else</a></h2> <h2><a name="ifthen">If/Then/Else</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Extending Kaleidoscope to support if/then/else is quite straightforward. It Extending Kaleidoscope to support if/then/else is quite straightforward. It
@ -112,14 +112,12 @@ Since Kaleidoscope allows side-effects, this behavior is important to nail down.
<p>Now that we know what we "want", lets break this down into its constituent <p>Now that we know what we "want", lets break this down into its constituent
pieces.</p> pieces.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="iflexer">Lexer Extensions for If/Then/Else</a></h4> <h4><a name="iflexer">Lexer Extensions for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The lexer extensions are straightforward. First we add new variants <p>The lexer extensions are straightforward. First we add new variants
for the relevant tokens:</p> for the relevant tokens:</p>
@ -155,7 +153,7 @@ stuff:</p>
<h4><a name="ifast">AST Extensions for If/Then/Else</a></h4> <h4><a name="ifast">AST Extensions for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>To represent the new expression we add a new AST variant for it:</p> <p>To represent the new expression we add a new AST variant for it:</p>
@ -176,7 +174,7 @@ type expr =
<h4><a name="ifparser">Parser Extensions for If/Then/Else</a></h4> <h4><a name="ifparser">Parser Extensions for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Now that we have the relevant tokens coming from the lexer and we have the <p>Now that we have the relevant tokens coming from the lexer and we have the
AST node to build, our parsing logic is relatively straightforward. First we AST node to build, our parsing logic is relatively straightforward. First we
@ -214,7 +212,7 @@ let rec parse_primary = parser
<h4><a name="ifir">LLVM IR for If/Then/Else</a></h4> <h4><a name="ifir">LLVM IR for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Now that we have it parsing and building the AST, the final piece is adding <p>Now that we have it parsing and building the AST, the final piece is adding
LLVM code generation support. This is the most interesting part of the LLVM code generation support. This is the most interesting part of the
@ -331,7 +329,7 @@ directly.</p>
<h4><a name="ifcodegen">Code Generation for If/Then/Else</a></h4> <h4><a name="ifcodegen">Code Generation for If/Then/Else</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>In order to generate code for this, we implement the <tt>Codegen</tt> method <p>In order to generate code for this, we implement the <tt>Codegen</tt> method
for <tt>IfExprAST</tt>:</p> for <tt>IfExprAST</tt>:</p>
@ -488,11 +486,13 @@ another useful expression that is familiar from non-functional languages...</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="for">'for' Loop Expression</a></h2> <h2><a name="for">'for' Loop Expression</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we know how to add basic control flow constructs to the language, <p>Now that we know how to add basic control flow constructs to the language,
we have the tools to add more powerful things. Lets add something more we have the tools to add more powerful things. Lets add something more
@ -521,13 +521,11 @@ variables, it will get more useful.</p>
<p>As before, lets talk about the changes that we need to Kaleidoscope to <p>As before, lets talk about the changes that we need to Kaleidoscope to
support this.</p> support this.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="forlexer">Lexer Extensions for the 'for' Loop</a></h4> <h4><a name="forlexer">Lexer Extensions for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The lexer extensions are the same sort of thing as for if/then/else:</p> <p>The lexer extensions are the same sort of thing as for if/then/else:</p>
@ -557,7 +555,7 @@ support this.</p>
<h4><a name="forast">AST Extensions for the 'for' Loop</a></h4> <h4><a name="forast">AST Extensions for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The AST variant is just as simple. It basically boils down to capturing <p>The AST variant is just as simple. It basically boils down to capturing
the variable name and the constituent expressions in the node.</p> the variable name and the constituent expressions in the node.</p>
@ -577,7 +575,7 @@ type expr =
<h4><a name="forparser">Parser Extensions for the 'for' Loop</a></h4> <h4><a name="forparser">Parser Extensions for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The parser code is also fairly standard. The only interesting thing here is <p>The parser code is also fairly standard. The only interesting thing here is
handling of the optional step value. The parser code handles it by checking to handling of the optional step value. The parser code handles it by checking to
@ -624,7 +622,7 @@ let rec parse_primary = parser
<h4><a name="forir">LLVM IR for the 'for' Loop</a></h4> <h4><a name="forir">LLVM IR for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Now we get to the good part: the LLVM IR we want to generate for this thing. <p>Now we get to the good part: the LLVM IR we want to generate for this thing.
With the simple example above, we get this LLVM IR (note that this dump is With the simple example above, we get this LLVM IR (note that this dump is
@ -669,7 +667,7 @@ expressions, and some basic blocks. Lets see how this fits together.</p>
<h4><a name="forcodegen">Code Generation for the 'for' Loop</a></h4> <h4><a name="forcodegen">Code Generation for the 'for' Loop</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>The first part of Codegen is very simple: we just output the start expression <p>The first part of Codegen is very simple: we just output the start expression
for the loop value:</p> for the loop value:</p>
@ -842,11 +840,13 @@ to our poor innocent language.</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

12
docs/tutorial/OCamlLangImpl6.html
View File

@ -41,7 +41,7 @@ Variables / SSA Construction</li>
<h2><a name="intro">Chapter 6 Introduction</a></h2> <h2><a name="intro">Chapter 6 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 6 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 6 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. At this point in our tutorial, we now have a fully with LLVM</a>" tutorial. At this point in our tutorial, we now have a fully
@ -67,7 +67,7 @@ an example of what you can build with Kaleidoscope and its feature set.</p>
<h2><a name="idea">User-defined Operators: the Idea</a></h2> <h2><a name="idea">User-defined Operators: the Idea</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The "operator overloading" that we will add to Kaleidoscope is more general than The "operator overloading" that we will add to Kaleidoscope is more general than
@ -132,7 +132,7 @@ operators.</p>
<h2><a name="binary">User-defined Binary Operators</a></h2> <h2><a name="binary">User-defined Binary Operators</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Adding support for user-defined binary operators is pretty simple with our <p>Adding support for user-defined binary operators is pretty simple with our
current framework. We'll first add support for the unary/binary keywords:</p> current framework. We'll first add support for the unary/binary keywords:</p>
@ -323,7 +323,7 @@ see what it takes.</p>
<h2><a name="unary">User-defined Unary Operators</a></h2> <h2><a name="unary">User-defined Unary Operators</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Since we don't currently support unary operators in the Kaleidoscope <p>Since we don't currently support unary operators in the Kaleidoscope
language, we'll need to add everything to support them. Above, we added simple language, we'll need to add everything to support them. Above, we added simple
@ -475,7 +475,7 @@ is simpler primarily because it doesn't need to handle any predefined operators.
<h2><a name="example">Kicking the Tires</a></h2> <h2><a name="example">Kicking the Tires</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>It is somewhat hard to believe, but with a few simple extensions we've <p>It is somewhat hard to believe, but with a few simple extensions we've
covered in the last chapters, we have grown a real-ish language. With this, we covered in the last chapters, we have grown a real-ish language. With this, we
@ -781,7 +781,7 @@ add variable mutation without building SSA in your front-end.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with the Here is the complete code listing for our running example, enhanced with the

16
docs/tutorial/OCamlLangImpl7.html
View File

@ -45,7 +45,7 @@
<h2><a name="intro">Chapter 7 Introduction</a></h2> <h2><a name="intro">Chapter 7 Introduction</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to Chapter 7 of the "<a href="index.html">Implementing a language <p>Welcome to Chapter 7 of the "<a href="index.html">Implementing a language
with LLVM</a>" tutorial. In chapters 1 through 6, we've built a very with LLVM</a>" tutorial. In chapters 1 through 6, we've built a very
@ -73,7 +73,7 @@ support for this, though the way it works is a bit unexpected for some.</p>
<h2><a name="why">Why is this a hard problem?</a></h2> <h2><a name="why">Why is this a hard problem?</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
To understand why mutable variables cause complexities in SSA construction, To understand why mutable variables cause complexities in SSA construction,
@ -147,7 +147,7 @@ logic.</p>
<h2><a name="memory">Memory in LLVM</a></h2> <h2><a name="memory">Memory in LLVM</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>The 'trick' here is that while LLVM does require all register values to be <p>The 'trick' here is that while LLVM does require all register values to be
in SSA form, it does not require (or permit) memory objects to be in SSA form. in SSA form, it does not require (or permit) memory objects to be in SSA form.
@ -328,7 +328,7 @@ variables now!
<h2><a name="kalvars">Mutable Variables in Kaleidoscope</a></h2> <h2><a name="kalvars">Mutable Variables in Kaleidoscope</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Now that we know the sort of problem we want to tackle, lets see what this <p>Now that we know the sort of problem we want to tackle, lets see what this
looks like in the context of our little Kaleidoscope language. We're going to looks like in the context of our little Kaleidoscope language. We're going to
@ -384,7 +384,7 @@ Kaleidoscope to support new variable definitions.
<h2><a name="adjustments">Adjusting Existing Variables for Mutation</a></h2> <h2><a name="adjustments">Adjusting Existing Variables for Mutation</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
The symbol table in Kaleidoscope is managed at code generation time by the The symbol table in Kaleidoscope is managed at code generation time by the
@ -673,7 +673,7 @@ we'll add the assignment operator.</p>
<h2><a name="assignment">New Assignment Operator</a></h2> <h2><a name="assignment">New Assignment Operator</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>With our current framework, adding a new assignment operator is really <p>With our current framework, adding a new assignment operator is really
simple. We will parse it just like any other binary operator, but handle it simple. We will parse it just like any other binary operator, but handle it
@ -774,7 +774,7 @@ add this next!
<h2><a name="localvars">User-defined Local Variables</a></h2> <h2><a name="localvars">User-defined Local Variables</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Adding var/in is just like any other other extensions we made to <p>Adding var/in is just like any other other extensions we made to
Kaleidoscope: we extend the lexer, the parser, the AST and the code generator. Kaleidoscope: we extend the lexer, the parser, the AST and the code generator.
@ -956,7 +956,7 @@ anywhere in sight.</p>
<h2><a name="code">Full Code Listing</a></h2> <h2><a name="code">Full Code Listing</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p> <p>
Here is the complete code listing for our running example, enhanced with mutable Here is the complete code listing for our running example, enhanced with mutable

24
docs/tutorial/OCamlLangImpl8.html
View File

@ -45,7 +45,7 @@
<h2><a name="conclusion">Tutorial Conclusion</a></h2> <h2><a name="conclusion">Tutorial Conclusion</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>Welcome to the the final chapter of the "<a href="index.html">Implementing a <p>Welcome to the the final chapter of the "<a href="index.html">Implementing a
language with LLVM</a>" tutorial. In the course of this tutorial, we have grown language with LLVM</a>" tutorial. In the course of this tutorial, we have grown
@ -156,18 +156,16 @@ are very useful if you want to take advantage of LLVM's capabilities.</p>
<h2><a name="llvmirproperties">Properties of the LLVM IR</a></h2> <h2><a name="llvmirproperties">Properties of the LLVM IR</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>We have a couple common questions about code in the LLVM IR form - lets just <p>We have a couple common questions about code in the LLVM IR form - lets just
get these out of the way right now, shall we?</p> get these out of the way right now, shall we?</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="targetindep">Target Independence</a></h4> <h4><a name="targetindep">Target Independence</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Kaleidoscope is an example of a "portable language": any program written in <p>Kaleidoscope is an example of a "portable language": any program written in
Kaleidoscope will work the same way on any target that it runs on. Many other Kaleidoscope will work the same way on any target that it runs on. Many other
@ -221,7 +219,7 @@ in-kernel language.</p>
<h4><a name="safety">Safety Guarantees</a></h4> <h4><a name="safety">Safety Guarantees</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Many of the languages above are also "safe" languages: it is impossible for <p>Many of the languages above are also "safe" languages: it is impossible for
a program written in Java to corrupt its address space and crash the process a program written in Java to corrupt its address space and crash the process
@ -243,7 +241,7 @@ list</a> if you are interested in more details.</p>
<h4><a name="langspecific">Language-Specific Optimizations</a></h4> <h4><a name="langspecific">Language-Specific Optimizations</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>One thing about LLVM that turns off many people is that it does not solve all <p>One thing about LLVM that turns off many people is that it does not solve all
the world's problems in one system (sorry 'world hunger', someone else will have the world's problems in one system (sorry 'world hunger', someone else will have
@ -293,23 +291,23 @@ language-specific AST.
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<h2><a name="tipsandtricks">Tips and Tricks</a></h2> <h2><a name="tipsandtricks">Tips and Tricks</a></h2>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<div class="doc_text"> <div>
<p>There is a variety of useful tips and tricks that you come to know after <p>There is a variety of useful tips and tricks that you come to know after
working on/with LLVM that aren't obvious at first glance. Instead of letting working on/with LLVM that aren't obvious at first glance. Instead of letting
everyone rediscover them, this section talks about some of these issues.</p> everyone rediscover them, this section talks about some of these issues.</p>
</div>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<h4><a name="offsetofsizeof">Implementing portable offsetof/sizeof</a></h4> <h4><a name="offsetofsizeof">Implementing portable offsetof/sizeof</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>One interesting thing that comes up, if you are trying to keep the code <p>One interesting thing that comes up, if you are trying to keep the code
generated by your compiler "target independent", is that you often need to know generated by your compiler "target independent", is that you often need to know
@ -329,7 +327,7 @@ in a portable way.</p>
<h4><a name="gcstack">Garbage Collected Stack Frames</a></h4> <h4><a name="gcstack">Garbage Collected Stack Frames</a></h4>
<!-- ======================================================================= --> <!-- ======================================================================= -->
<div class="doc_text"> <div>
<p>Some languages want to explicitly manage their stack frames, often so that <p>Some languages want to explicitly manage their stack frames, often so that
they are garbage collected or to allow easy implementation of closures. There they are garbage collected or to allow easy implementation of closures. There
@ -343,6 +341,8 @@ Passing Style</a> and the use of tail calls (which LLVM also supports).</p>
</div> </div>
</div>
<!-- *********************************************************************** --> <!-- *********************************************************************** -->
<hr> <hr>
<address> <address>