This updates it with changed/added features.
pfd-build checked and inspected, applied.
Richard.
2014-10-14 Richard Biener <rguent...@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.
