[polly] r206898 - IslCodeGeneration: Document the IslExprBuilder

[Tobias Grosser]

Author: grosser
Date: Tue Apr 22 09:26:51 2014
New Revision: 206898

URL: http://llvm.org/viewvc/llvm-project?rev=206898&view=rev
Log:
IslCodeGeneration: Document the IslExprBuilder

Modified:
    polly/trunk/lib/CodeGen/IslCodeGeneration.cpp

Modified: polly/trunk/lib/CodeGen/IslCodeGeneration.cpp
URL: http://llvm.org/viewvc/llvm-project/polly/trunk/lib/CodeGen/IslCodeGeneration.cpp?rev=206898&r1=206897&r2=206898&view=diff
==============================================================================
--- polly/trunk/lib/CodeGen/IslCodeGeneration.cpp (original)
+++ polly/trunk/lib/CodeGen/IslCodeGeneration.cpp Tue Apr 22 09:26:51 2014
@@ -136,15 +136,98 @@ void RuntimeDebugBuilder::createIntPrint
   createFlush();
 }
 
-/// @brief Calculate the Value of a certain isl_ast_expr
+/// @brief LLVM-IR generator for isl_ast_expr[essions]
+///
+/// This generator generates LLVM-IR that performs the computation described by
+/// an isl_ast_expr[ession].
+///
+/// Example:
+///
+///   An isl_ast_expr[ession] can look like this:
+///
+///     (N + M) + 10
+///
+///   The IslExprBuilder could create the following LLVM-IR:
+///
+///     %tmp1 = add nsw i64 %N
+///     %tmp2 = add nsw i64 %tmp1, %M
+///     %tmp3 = add nsw i64 %tmp2, 10
+///
+/// The implementation of this class is mostly a mapping from isl_ast_expr
+/// constructs to the corresponding LLVM-IR constructs.
+///
+/// The following decisions may need some explanation:
+///
+/// 1) Which data-type to choose
+///
+/// isl_ast_expr[essions] are untyped expressions that assume arbitrary
+/// precision integer computations. LLVM-IR instead has fixed size integers.
+/// When lowering to LLVM-IR we need to chose both the size of the data type and
+/// the sign of the operations we use.
+///
+/// At the moment, we hardcode i64 bit signed computations. Our experience has
+/// shown that 64 bit are generally large enough for the loop bounds that appear
+/// in the wild. Signed computations are needed, as loop bounds may become
+/// negative.
+///
+/// FIXME: Hardcoding sizes can cause issues:
+///
+///   a) Certain run-time checks that we may want to generate can involve the
+///      size of the data types the computation is performed on. When code
+///      generating these run-time checks to isl_ast_expr[essions], the
+///      resulting computation may require more than 64 bit.
+///
+///   b) On embedded systems and especially for high-level-synthesis 64 bit
+///      computations are very costly.
+///
+///   The right approach is to compute the minimal necessary bitwidth and
+///   signedness for each subexpression during in the isl AST generation and
+///   to use this information in our IslAstGenerator. Preliminary patches are
+///   available, but have not been committed yet.
+///
+/// 2) We always flag computations with 'nsw'
+///
+/// As isl_ast_expr[essions] assume arbitrary precision, no wrapping should
+/// ever occur in the generated LLVM-IR (assuming the data type chosen is large
+/// enough).
 class IslExprBuilder {
 public:
+  /// @brief Construct an IslExprBuilder.
+  ///
+  /// @param Builder The IRBuilder used to construct the isl_ast_expr[ession].
+  ///                The insert location of this IRBuilder defines WHERE the
+  ///                corresponding LLVM-IR is generated.
+  ///
+  /// @param IDToValue The isl_ast_expr[ession] may reference parameters or
+  ///                  variables (identified by an isl_id). The IDTOValue map
+  ///                  specifies the LLVM-IR Values that correspond to these
+  ///                  parameters and variables.
   IslExprBuilder(PollyIRBuilder &Builder,
-                 std::map<isl_id *, Value *> &IDToValue, Pass *P)
+                 std::map<isl_id *, Value *> &IDToValue)
       : Builder(Builder), IDToValue(IDToValue) {}
 
+  /// @brief Create LLVM-IR for an isl_ast_expr[ession].
+  ///
+  /// @param Expr The ast expression for which we generate LLVM-IR.
+  ///
+  /// @return The llvm::Value* containing the result of the computation.
   Value *create(__isl_take isl_ast_expr *Expr);
+
+  /// @brief Return the largest of two types.
+  ///
+  /// @param T1 The first type.
+  /// @param T2 The second type.
+  ///
+  /// @return The largest of the two types.
   Type *getWidestType(Type *T1, Type *T2);
+
+  /// @brief Return the type with which this expression should be computed.
+  ///
+  /// The type needs to be large enough to hold all possible input and all
+  /// possible output values.
+  ///
+  /// @param Expr The expression for which to find the type.
+  /// @return The type with which the expression should be computed.
   IntegerType *getType(__isl_keep isl_ast_expr *Expr);
 
 private:
@@ -542,7 +625,7 @@ class IslNodeBuilder {
 public:
   IslNodeBuilder(PollyIRBuilder &Builder, LoopAnnotator &Annotator, Pass *P)
       : Builder(Builder), Annotator(Annotator),
-        ExprBuilder(Builder, IDToValue, P), P(P) {}
+        ExprBuilder(Builder, IDToValue), P(P) {}
 
   void addParameters(__isl_take isl_set *Context);
   void create(__isl_take isl_ast_node *Node);