[PATCH][match-and-simplify] Update texi documentation

[Richard Biener <rguenther at suse dot de>]

This updates it with changed/added features.

pfd-build checked and inspected, applied.

Richard.

2014-10-14  Richard Biener  <rguenther@suse.de>

	* doc/match-and-simplify.texi: Update.

Index: gcc/doc/match-and-simplify.texi
===================================================================
--- gcc/doc/match-and-simplify.texi	(revision 216146)
+++ gcc/doc/match-and-simplify.texi	(working copy)
@@ -38,6 +38,8 @@ APIs are introduced.
 @deftypefnx {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, tree, gimple_seq *, tree (*)(tree))
 @deftypefnx {GIMPLE function} tree gimple_simplify (enum tree_code, tree, tree, tree, tree, gimple_seq *, tree (*)(tree))
 @deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, gimple_seq *, tree (*)(tree))
+@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, tree, gimple_seq *, tree (*)(tree))
+@deftypefnx {GIMPLE function} tree gimple_simplify (enum built_in_function, tree, tree, tree, gimple_seq *, tree (*)(tree))
 The main GIMPLE API entry to the expression simplifications mimicing
 that of the GENERIC fold_@{unary,binary,ternary@} functions.
 @end deftypefn
@@ -48,22 +50,27 @@ inserted on (if @code{NULL} then simplif
 are not performed) and a valueization hook that can be used to
 tie simplifications to a SSA lattice.
 
-In addition to those APIs a fold_stmt-like interface is provided with
+In addition to those APIs @code{fold_stmt} is overloaded with
+a valueization hook:
 
-@deftypefn bool gimple_simplify (gimple_stmt_iterator *, tree (*)(tree));
+@deftypefn bool fold_stmt (gimple_stmt_iterator *, tree (*)(tree));
 @end deftypefn
 
-which also has the additional valueization hook.
 
 Ontop of these a @code{fold_buildN}-like API for GIMPLE is introduced:
 
-@deftypefn tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree, tree (*valueize) (tree) = NULL);
-@deftypefnx tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree (*valueize) (tree) = NULL);
+@deftypefn {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree (*valueize) (tree) = NULL);
+@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree (*valueize) (tree) = NULL);
+@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum tree_code, tree, tree, tree, tree, tree (*valueize) (tree) = NULL);
+@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree (*valueize) (tree) = NULL);
+@deftypefnx {GIMPLE function} tree gimple_build (gimple_seq *, location_t, enum built_in_function, tree, tree, tree, tree (*valueize) (tree) = NULL);
+@deftypefnx {GIMPLE function} tree gimple_convert (gimple_seq *, location_t, tree, tree);
 @end deftypefn
 
-which is supposed to replace @code{force_gimple_operand (fold_buildN (...), ...)}.
+which is supposed to replace @code{force_gimple_operand (fold_buildN (...), ...)}
+and calls to @code{fold_convert}.  Overloads without the @code{location_t}
+argument exist.  Built statements are inserted on the provided sequence
+and simplification is performed using the optional valueization hook.
 
 
 @node The Language
@@ -72,7 +79,7 @@ which is supposed to replace @code{force
 
 The language to write expression simplifications in resembles other
 domain-specific languages GCC uses.  Thus it is lispy.  Lets start
-with an example from the match.pd file on the branch:
+with an example from the match.pd file:
 
 @smallexample
 (simplify
@@ -86,13 +93,14 @@ That contains at least two operands - an
 with the GIMPLE or GENERIC IL and a replacement expression that is
 returned if the match was successful.
 
-Expressions have an ID, @code{bit_and} in this case.  Expressions can
+Expressions have an operator ID, @code{bit_and} in this case.  Expressions can
 be lower-case tree codes with @code{_expr} stripped off or builtin
 function code names in all-caps, like @code{BUILT_IN_SQRT}.
 
 @code{@@n} denotes a so-called capture.  It captures the operand and lets
 you refer to it in other places of the match-and-simplify.  In the
-above example it is refered to in the replacement expression.
+above example it is refered to in the replacement expression.  Captures
+are @code{@@} followed by a number or an identifier.
 
 @smallexample
 (simplify
@@ -103,7 +111,8 @@ above example it is refered to in the re
 In this example @code{@@0} is mentioned twice which constrains the matched
 expression to have two equal operands.  This example also introduces
 operands written in C code.  These can be used in the expression
-replacements and are supposed to evaluate to a tree node.
+replacements and are supposed to evaluate to a tree node which has to
+be a valid GIMPLE operand (so you cannot generate expressions in C code).
 
 @smallexample
 (simplify
@@ -124,6 +133,23 @@ to enable the replacement expression.  T
 of the @code{if} is a standard C expression which may contain references
 to captures.
 
+A @code{if} expression can be used to specify a common condition
+for multiple simplify patterns, avoiding the need
+to repeat that multiple times:
+
+@smallexample
+(if (!TYPE_SATURATING (type)
+     && !FLOAT_TYPE_P (type) && !FIXED_POINT_TYPE_P (type))
+  (simplify
+    (minus (plus @@0 @@1) @@0)
+    @@1)
+  (simplify
+    (minus (minus @@0 @@1) @@0)
+    (negate @@1)))
+@end smallexample
+
+Ifs can be nested.
+
 Captures can also be used for capturing results of sub-expressions.
 
 @smallexample
@@ -173,31 +199,116 @@ Usual canonicalizations you know from GE
 applied before matching, so for example constant operands always
 come second in commutative expressions.
 
-Two more features exist to avoid too much repetition.
+More features exist to avoid too much repetition.
 
 @smallexample
-(for op in plus pointer_plus minus bit_ior bit_xor
+(for op (plus pointer_plus minus bit_ior bit_xor)
   (simplify
     (op @@0 integer_zerop)
     @@0))
 @end smallexample
 
 A @code{for} expression can be used to repeat a pattern for each
-operator specified, substituting @code{op}.
+operator specified, substituting @code{op}.  @code{for} can be
+nested and a @code{for} can have multiple operators to iterate.
 
 @smallexample
-(if (!TYPE_SATURATING (type)
-     && !FLOAT_TYPE_P (type) && !FIXED_POINT_TYPE_P (type))
-  (simplify
-    (minus (plus @@0 @@1) @@0)
-    @@1)
-  (simplify
-    (minus (minus @@0 @@1) @@0)
-    (negate @@1)))
+(for opa (plus minus)
+     opb (minus plus)
+  (for opc (plus minus)
+    (simplify...
 @end smallexample
 
-A @code{if} expression can be used to specify a common condition
-for multiple match-and-simplify patterns, avoiding the need
-to repeat that multiple times.
+In this example the pattern will be repeated four times with
+@code{opa, opb, opc} being @code{plus, minus, plus},
+@code{plus, minus, minus}, @code{minus, plus, plus},
+@code{minus, plus, minus}.
+
+Another building block are @code{with} expressions in the
+result expression which nest the generated code in a new C block
+followed by its argument:
+
+@smallexample
+(simplify
+ (convert (mult @@0 @@1))
+ (with @{ tree utype = unsigned_type_for (type); @}
+  (convert (mult (convert:utype @@0) (convert:utype @@1)))))
+@end smallexample
+
+This allows code nested in the @code{with} to refer to the declared
+variables.  In the above case we use the feature to specify the
+type of a generated expression with the @code{:type} syntax where
+@code{type} needs to be an identifier that refers to the desired type.
+Usually the types of the generated result expressions are
+determined from the context, but sometimes like in the above case
+it is required that you specify them explicitely.
+
+As intermediate conversions are often optional there is a way to
+avoid the need to repeat patterns both with and without such
+conversions.  Namely you can mark a conversion as being optional
+with a @code{?}:
+
+@smallexample
+(simplify
+ (eq (convert@@0 @@1) (convert? @@2))
+ (eq @@1 (convert @@2)))
+@end smallexample
+
+which will match both @code{(eq (convert @@1) (convert @@2))} and
+@code{(eq (convert @@1) @@2)}.  The optional converts are supposed
+to be all either present or not, thus
+@code{(eq (convert? @@1) (convert? @@2))} will result in two
+patterns only.  If you want to match all four combinations you
+have access to two additional conditional converts as in
+@code{(eq (convert1? @@1) (convert2? @@2))}.
+
+Predicates available from the GCC middle-end need to be made
+available explicitely via @code{define_predicates}:
+
+@smallexample
+(define_predicates
+ integer_onep integer_zerop integer_all_onesp)
+@end smallexample
+
+You can also define predicates using the pattern matching language
+and the @code{match} form:
+
+@smallexample
+(match negate_expr_p
+ INTEGER_CST
+ (if (TYPE_OVERFLOW_WRAPS (type)
+      || may_negate_without_overflow_p (t))))
+(match negate_expr_p
+ (negate @@0))
+@end smallexample
+
+This shows that for @code{match} expressions there is @code{t}
+available which captures the outermost expression (something
+not possible in the @code{simplify} context).  As you can see
+@code{match} has an identifier as first operand which is how
+you refer to the predicate in patterns.  Multiple @code{match}
+for the same identifier add additional cases where the predicate
+matches.
+
+Predicates can also match an expression in which case you need
+to provide a template specifying the identifier and where to
+get its operands from:
+
+@smallexample
+(match (logical_inverted_value @@0)
+ (eq @@0 integer_zerop))
+(match (logical_inverted_value @@0)
+ (bit_not truth_valued_p@@0))
+@end smallexample
+
+You can use the above predicate like
+
+@smallexample
+(simplify
+ (bit_and @@0 (logical_inverted_value @@0))
+ @{ build_zero_cst (type); @})
+@end smallexample
 
+Which will match a bitwise and of an operand with its logical
+inverted value.