[PATCH] doc: Document order of define_peephole2 scanning

[Hans-Peter Nilsson <hp@axis.com>]

Generated pdf inspected.  Ok to commit?

Thoughts on fixing the IMHO wart to also expose all
replacements to all define_peephole2?  Looks feasible
(famous last words), but then again I haven't checked the
history yet.

-- >8 --
I was a bit surprised when my define_peephole2 didn't match,
but it was because it was expected to partially match the
generated output of a previous define_peephole2.  I had
assumed that the algorithm exposed newly created opportunities
to all define_peephole2's.  While things can change in that
direction, let's start with documenting the current state.

	* doc/md.texi (define_peephole2): Document order of scanning.
---
 gcc/doc/md.texi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 07bf8bdebffb..0f9e32d2c648 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -9362,6 +9362,14 @@ If the preparation falls through (invokes neither @code{DONE} nor
 @code{FAIL}), then the @code{define_peephole2} uses the replacement
 template.
 
+Insns are scanned in forward order from beginning to end for each basic
+block, but the basic blocks are scanned in reverse order of appearance
+in a function.  After a successful replacement, scanning for further
+opportunities for @code{define_peephole2} matches, resumes at the last
+generated insn.  I.e. for the example above, the first insn that can be
+matched by another @code{define_peephole2}, is @code{(set (match_dup 3)
+(match_dup 4))}.
+
 @end ifset
 @ifset INTERNALS
 @node Insn Attributes
-- 
2.30.2