Updated documentation. Changed struct_packed() to packed_struct().

git-svn-id: http://llvm-py.googlecode.com/svn/trunk@6 8d1e9007-1d4e-0410-b67e-1979fd6579aa

llvm/core.py

@@ -314,12 +314,12 @@ class Type(object):
 
         Creates a structure type with elements of types as given in the
         iterable `element_tys'. This method creates a unpacked
-        structure. For a packed one, use struct_packed() method."""
+        structure. For a packed one, use packed_struct() method."""
         elems = unpack_types(element_tys)
         return _make_type(_core.LLVMStructType(elems, 0), TYPE_STRUCT)
 
     @staticmethod
-    def struct_packed(element_tys):
+    def packed_struct(element_tys):
         """Create a (packed) structure type.
 
         Creates a structure type with elements of types as given in the
@@ -605,7 +605,7 @@ class Constant(Value):
         return Constant(_core.LLVMConstStruct(consts, 0))
     
     @staticmethod
-    def struct_packed(consts):
+    def packed_struct(consts):
         const_ptrs = unpack_constants(consts)
         return Constant(_core.LLVMConstStruct(consts, 1))
     
@@ -763,7 +763,7 @@ class Constant(Value):
         check_is_constant(mask)
         return Constant(_core.LLVMConstShuffleVector(self.ptr, vector_b.ptr, mask.ptr))
 
-    
+
 class GlobalValue(Constant):
 
     def __init__(self, ptr):
@@ -1051,7 +1051,7 @@ class Builder(object):
         return Instruction(_core.LLVMBuildCondBr(self.ptr, if_value.ptr, then_blk.ptr, else_blk.ptr))
         
     def switch(self, value, else_blk, n=10):
-        check_is_value(value)
+        check_is_value(value)  # value has to be of any 'int' type
         check_is_basic_block(else_blk)
         return SwitchInstruction(_core.LLVMBuildSwitch(self.ptr, value.ptr, else_blk.ptr, n))
         

www/makeweb.py

@@ -6,7 +6,7 @@ from string import Template
 from optparse import OptionParser
 
 # files in src dir that should not be copied to web dir
-SKIP_FILES = [ 'layout.conf' ]
+SKIP_FILES = [ 'layout.conf', '.svn' ]
 
 # asciidoc command line
 ASCIIDOC = 'asciidoc --unsafe --conf-file=${srcdir}/layout.conf -a icons -o ${outfile} ${infile}'
@@ -50,7 +50,8 @@ def copy(opts, inp, outp):
             if not opts.dryrun:
                 os.mkdir(outp)
         for file in os.listdir(inp):
-            copy(opts, os.path.join(inp, file), os.path.join(outp, file))
+            if file not in SKIP_FILES:
+                copy(opts, os.path.join(inp, file), os.path.join(outp, file))
     else:
         if _is_older(inp, outp) or opts.force:
             if opts.verbose:

www/src/contribute.txt

@@ -13,3 +13,5 @@ latest code can be checked out from SVN like so:
 $ svn checkout http://llvm-py.googlecode.com/svn/trunk/ llvm-py
 ----
 
+You can browse the source online at:
+http://code.google.com/p/llvm-py/source/browse[http://code.google.com/p/llvm-py/source/browse].

www/src/userguide.txt

@@ -146,30 +146,159 @@ follow these steps:
 - create a function of type _tf_ named _sum_
 - add a _basic block_ to the function
 - using a helper object called an _instruction builder_, add two
-  instructions into the basic block: . an instruction to add the two
-  arguments and store the result into a temporary variable . a return
-  instruction to return the value of the temporary variable
+  instructions into the basic block:
+  . an instruction to add the two arguments and store the result into
+    a temporary variable
+  . a return instruction to return the value of the temporary variable
 
 (A basic block is a block of instructions.)
 
 LLVM has it's own instruction set; the instructions used above (+add+
-and +ret+) are from this set. The full set of instructions are:
+and +ret+) are from this set. The LLVM instructions are at a higher
+level than the usual assembly language; for example there are
+instructions related to variable argument handling, exception handling,
+and garbage collection. These allow high-level languages to be
+represented cleanly in the IR.
+
+The full set of instructions are:
 
 TODO
 
-SSA
-~~~
 
-All LLVM instructions are represented in the SSA form. Essentially, this
-means that any variable can be assigned to only once. 
+SSA Form and PHI Nodes
+~~~~~~~~~~~~~~~~~~~~~~
+
+All LLVM instructions are represented in the _Static Single Assignment_
+(SSA) form. Essentially, this means that any variable can be assigned to
+only once. Such a representation facilitates better optimization, among
+other benefits.
+
+A consequence of single assignment are PHI (+++Φ+++) nodes. These
+are required when a variable can be assigned a different value based on
+the path of control flow. For example, the value of +b+ at the end of
+execution of the snippet below:
+
+----
+a = 1;
+if (v < 10)
+  a = 2;
+b = a;
+----
+
+cannot be determined statically. The value of '2' cannot be assigned to
+the 'original' +a+, since +a+ can be assigned to only once. There are
+two +a+ 's in there, and the last assignment has to choose between which
+version to pick. This is accomplished by adding a PHI node:
+
+----
+a1 = 1;
+if (v < 10)
+  a2 = 2;
+b = PHI(a1, a2);
+----
+
+The PHI node selects +a1+ or +a2+, depending on where the control
+reached the PHI node. The argument +a1+ of the PHI node is associated
+with the block +"a1 = 1;"+ and +a2+ with the block +"a2 = 2;"+.
+
+PHI nodes have to be explicitly created in the LLVM IR. The LLVM
+instruction set therefore has an instruction called _phi_.
+
+
+LLVM Assembly Language
+~~~~~~~~~~~~~~~~~~~~~~
+
+The LLVM IR can be represented offline in two formats
+- a textual, human-readable form, similar to assembly language, called
+  the LLVM assembly language (files with .ll extension) (XXX ?)
+- a binary form, called the LLVM bitcode (files with .bc extension)
+All three formats (the in-memory IR, the LLVM assembly language and the
+LLVM bitcode) represent the _same_ information. Each format can be
+converted into the other two formats (using LLVM APIs).
+
+The http://www.llvm.org/demo/[LLVM demo page] lets you type in C or C++
+code, converts it into LLVM IR and outputs the IR as LLVM assembly
+language code.
+
+Here's a function in C, that calculates the sum of the first _n_
+fibonacci numbers:
+
+[C]
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+int fibsum(int n)
+{
+}
+source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+And here's the corresponding LLVM assembly listing, as provided by the
+demo page:
+
+----
+----
+
+Note the ... TODO ...
+
+The http://www.llvm.org/docs/LangRef.html[LLVM Language Reference]
+defines the LLVM assembly language including the entire instruction set.
+
+
+Modules
+~~~~~~~
+
+Modules, in the LLVM IR, are similar to a single _C_ language source
+file (.c file). A module contains:
+
+- functions (declarations and definitions)
+- global variables and constants
+- global type aliases (typedef-s)
+
+Modules are top-level containers; all executable code representation is
+contained within modules.
+
+
+Optimization and Passes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+LLVM provides quite a few optimization algorithms that work on the IR.
+These algorithms are organized as _passes_. Each pass does something
+specific, like combining redundant instructions. Passes need not always
+optimize the IR, it can also do other operations like inserting
+instrumentation code, or analysing the IR (the result of which can be
+used by passes that do optimizations) or even printing call graphs.
+
+This LLVM http://www.llvm.org/docs/Passes.html[documentation page]
+describes all the available passes, and what they do.
+
+LLVM does not automatically choose to run any passes, anytime. Passes
+have to be explicitly selected and run on each module. This gives you
+the flexibility to choose transformations and optimizations that are
+most suitable for the code in the module.
+
+There is a LLVM binary called http://www.llvm.org/cmds/opt.html[opt],
+which lets you run passes on bitcode files from the command line. You
+can write your own passes (in C/C\+\+, as a shared library). This can be
+loaded and executed by +opt+. (Although _llvm-py_ does not allow you to
+write your own passes, it does allow you to navigate the entire IR at
+any stage, and perform any transforms on it as you like.)
+
+Passes are run using a _pass manager_. For our purposes, there are two
 
-Executable code, in "real-life", is represented as a sequence of machine
-instructions, which typically reside in e
 
-IR, Module
-Passes
 Execution Engine
+~~~~~~~~~~~~~~~~
+
+TODO
+
+
 BitCode
+~~~~~~~
+
+TODO
+
+llvm-gcc
+~~~~~~~~
+
+TODO
 
 The _llvm-py_ Package
 ---------------------
@@ -187,4 +316,3 @@ constants
 values
 
 
-