[Patch docs 0/5] Update some of md.texi

[Patch docs 0/5] Update some of md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 1407 bytes --]

Hi,

I was recently stuck on a flight and flicking through md.texi, when
I realised some of it was rather outdated. Consequently, I thought
I would have a go at updating it, and while I was there, clean up some
of the style issues I've spotted over the last few years.

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.
  * Update some K&R C and make it use GNU-style.

I've split the patch to a 5-patch series, roughly covering one section
in each.

There is probably much more that I can do to clean these up, and of
course there is the rest of the file to do... If this work is useful,
I'm happy to keep going over the next couple of weekends.

I've read through the output in info and a web browser, and I couldn't
spot any major formatting errors.

OK?

Thanks,
James

---
James Greenhalgh (5):
  [Patch docs 1/5] Update the first section of md.texi
  [Patch docs 2/5] Update "Instruction Patterns" in md.texi
  [Patch docs 3/5] Update "RTL Template" in md.texi
  [Patch docs 4/5] Update "Output Template/Statement" from md.texi
  [Patch docs 5/5] Update "Predicates" from md.texi

[Patch docs 3/5] Update "RTL Template" in md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 547 bytes --]


Hi,

This patch updates the RTL Template section of md.texi.

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.

OK?

Thanks,
James

---
2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (RTL Template): Update text.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0003-Patch-docs-3-5-Update-RTL-Template-in-md.texi.patch --]
[-- Type: text/x-patch;  name=0003-Patch-docs-3-5-Update-RTL-Template-in-md.texi.patch, Size: 15138 bytes --]

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index b852981..a589f5b 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -257,25 +257,23 @@ type of CPU for which code is being generated.
 @cindex recognizing insns
 @cindex insns, recognizing
 
-The RTL template is used to define which insns match the particular pattern
+The RTL template is used to define which insns match the pattern
 and how to find their operands.  For named patterns, the RTL template also
-says how to construct an insn from specified operands.
+defines how to construct an insn from specified operands.
 
-Construction involves substituting specified operands into a copy of the
-template.  Matching involves determining the values that serve as the
-operands in the insn being matched.  Both of these activities are
-controlled by special expression types that direct matching and
-substitution of the operands.
+Constructing an insn involves substituting specified operands into a
+copy of the template.  Matching an insn involves determining the values
+that serve as the operands in the insn being matched.  Both of these
+activities are controlled by the special RTL expressions described below.
 
 @table @code
 @findex match_operand
 @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
 This expression is a placeholder for operand number @var{n} of
-the insn.  When constructing an insn, operand number @var{n}
-will be substituted at this point.  When matching an insn, whatever
-appears at this position in the insn will be taken as operand
-number @var{n}; but it must satisfy @var{predicate} or this instruction
-pattern will not match at all.
+the instruction pattern.  When constructing RTL, operand number @var{n}
+will be substituted at this point.  When matching an insn, assuming the
+@var{predicate} is satisfied, whatever appears at this position in the
+insn will be taken as operand number @var{n}.
 
 Operand numbers must be chosen consecutively counting from zero in
 each instruction pattern.  There may be only one @code{match_operand}
@@ -286,15 +284,15 @@ used only in @code{match_dup} expressions have higher values than all
 other operand numbers.
 
 @var{predicate} is a string that is the name of a function that
-accepts two arguments, an expression and a machine mode.
-@xref{Predicates}.  During matching, the function will be called with
-the putative operand as the expression and @var{m} as the mode
-argument (if @var{m} is not specified, @code{VOIDmode} will be used,
+accepts two arguments, an expression and a machine mode
+(@pxref{Predicates}).  During matching, the function will be called
+with the operand as the expression and @var{m} as the mode
+argument (if @var{m} is not specified, then @code{VOIDmode} will be used,
 which normally causes @var{predicate} to accept any mode).  If it
 returns zero, this instruction pattern fails to match.
-@var{predicate} may be an empty string; then it means no test is to be
-done on the operand, so anything which occurs in this position is
-valid.
+
+@var{predicate} may be an empty string.  This represents a predicate for
+which any operand will be considered valid.
 
 Most of the time, @var{predicate} will reject modes other than @var{m}---but
 not always.  For example, the predicate @code{address_operand} uses
@@ -302,80 +300,89 @@ not always.  For example, the predicate @code{address_operand} uses
 Many predicates accept @code{const_int} nodes even though their mode is
 @code{VOIDmode}.
 
-@var{constraint} controls reloading and the choice of the best register
-class to use for a value, as explained later (@pxref{Constraints}).
-If the constraint would be an empty string, it can be omitted.
-
-People are often unclear on the difference between the constraint and the
-predicate.  The predicate helps decide whether a given insn matches the
-pattern.  The constraint plays no role in this decision; instead, it
-controls various decisions in the case of an insn which does match.
+@var{constraint} controls the best register class to use for a value,
+and therefore register allocation and reloading, as explained
+later (@pxref{Constraints}).  If the constraint would be an empty
+string, it can be omitted.
+
+In summary, the predicate is used to control whether the instruction
+pattern is a valid match for an insn.  The constraint is used to control
+register allocation decisions in the case of an instruction pattern which
+has already been matched to an insn.
+
+It is an error for the contraints of an operand to be impossible to fulfil
+for operands which are valid for the predicate of the operand.  Formally;
+for all operands for which the predicate would be true, there must exist
+at least one valid register class for that operand.  Note that this
+restriction does not forbid accepting operands which will need additional
+handling to move them to a valid register class.  This restriction would,
+however, prevent combining a constraint set requiring the use of an
+immediate value with a predicate allowing any operand, as it is not
+possible to convert all operand types to immediate values.
 
 @findex match_scratch
 @item (match_scratch:@var{m} @var{n} @var{constraint})
-This expression is also a placeholder for operand number @var{n}
-and indicates that operand must be a @code{scratch} or @code{reg}
+This expression is a placeholder for operand number @var{n}
+and indicates that the operand must be a @code{scratch} or @code{reg}
 expression.
 
-When matching patterns, this is equivalent to
+When matching instruction patterns, this is equivalent to:
 
 @smallexample
-(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
+(match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
 @end smallexample
 
-but, when generating RTL, it produces a (@code{scratch}:@var{m})
-expression.
+When constructing RTL, it produces a (@code{scratch}:@var{m}) expression.
 
-If the last few expressions in a @code{parallel} are @code{clobber}
-expressions whose operands are either a hard register or
-@code{match_scratch}, the combiner can add or delete them when
-necessary.  @xref{Side Effects}.
+If the last expressions in an instruction pattern containing a
+@code{parallel} are @code{clobber} expressions whose operands are either
+a hard register or @code{match_scratch}, the combine pass of the compiler
+will automatically add or delete them where necessary (@xref{Side Effects}).
 
 @findex match_dup
 @item (match_dup @var{n})
-This expression is also a placeholder for operand number @var{n}.
+This expression is a placeholder for operand number @var{n}.
 It is used when the operand needs to appear more than once in the
-insn.
+instruction pattern.
 
-In construction, @code{match_dup} acts just like @code{match_operand}:
-the operand is substituted into the insn being constructed.  But in
-matching, @code{match_dup} behaves differently.  It assumes that operand
+When constructing RTL, @code{match_dup} acts just like @code{match_operand}:
+the operand is substituted into the insn being constructed.
+
+When matching an insn, @code{match_dup} assumes that operand
 number @var{n} has already been determined by a @code{match_operand}
-appearing earlier in the recognition template, and it matches only an
+appearing earlier in the instruction pattern, and matches only an
 identical-looking expression.
 
 Note that @code{match_dup} should not be used to tell the compiler that
-a particular register is being used for two operands (example:
-@code{add} that adds one register to another; the second register is
-both an input operand and the output operand).  Use a matching
-constraint (@pxref{Simple Constraints}) for those.  @code{match_dup} is for the cases where one
-operand is used in two places in the template, such as an instruction
-that computes both a quotient and a remainder, where the opcode takes
-two input operands but the RTL template has to refer to each of those
-twice; once for the quotient pattern and once for the remainder pattern.
+a particular register is being used for two operands.  Rather, the
+@code{constraint} field of an @code{match_operand} should be used to tie
+the two operands through a matching constraint (@pxref{Simple Constraints}).
+@code{match_dup} should be used in cases where one operand is used in two
+places in the template, for example in an instruction that computes both a
+quotient and a remainder, where the opcode takes two input operands but
+the RTL template has to refer to each of those twice; once for the quotient
+pattern and once for the remainder pattern.
 
 @findex match_operator
 @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
-This pattern is a kind of placeholder for a variable RTL expression
+This expression is a placeholder for a variable RTL expression
 code.
 
-When constructing an insn, it stands for an RTL expression whose
-expression code is taken from that of operand @var{n}, and whose
-operands are constructed from the patterns @var{operands}.
+When constructing RTL, it stands for an RTL expression whose expression
+code is taken from that of operand @var{n}, and whose operands are
+constructed from the @var{operands} of the instruction pattern.
 
-When matching an expression, it matches an expression if the function
-@var{predicate} returns nonzero on that expression @emph{and} the
-patterns @var{operands} match the operands of the expression.
+When matching an insn, it matches if @var{predicate} returns nonzero for
+the expression code @emph{and} the @var{operands} of the expression are
+valid for the instruction pattern.
 
-Suppose that the function @code{commutative_operator} is defined as
-follows, to match any expression whose operator is one of the
-commutative arithmetic operators of RTL and whose mode is @var{mode}:
+In this example, the function @code{commutative_operator} is defined to
+match any expression whose operator is one of the commutative arithmetic
+operators of RTL and whose mode is @var{mode}:
 
 @smallexample
 int
-commutative_integer_operator (x, mode)
-     rtx x;
-     machine_mode mode;
+commutative_integer_operator (rtx x, machine_mode mode)
 @{
   enum rtx_code code = GET_CODE (x);
   if (GET_MODE (x) != mode)
@@ -385,8 +392,9 @@ commutative_integer_operator (x, mode)
 @}
 @end smallexample
 
-Then the following pattern will match any RTL expression consisting
-of a commutative operator applied to two general operands:
+Given this @var{predicate}, the following pattern will match any RTL
+expression consisting of a commutative operator applied to two general
+operands:
 
 @smallexample
 (match_operator:SI 3 "commutative_operator"
@@ -397,18 +405,18 @@ of a commutative operator applied to two general operands:
 Here the vector @code{[@var{operands}@dots{}]} contains two patterns
 because the expressions to be matched all contain two operands.
 
-When this pattern does match, the two operands of the commutative
+When this pattern is matched, the two operands of the commutative
 operator are recorded as operands 1 and 2 of the insn.  (This is done
 by the two instances of @code{match_operand}.)  Operand 3 of the insn
-will be the entire commutative expression: use @code{GET_CODE
-(operands[3])} to see which commutative operator was used.
+will be the entire commutative expression: @code{GET_CODE (operands[3])}
+will give which commutative operator was used.
 
 The machine mode @var{m} of @code{match_operator} works like that of
 @code{match_operand}: it is passed as the second argument to the
-predicate function, and that function is solely responsible for
-deciding whether the expression to be matched ``has'' that mode.
+predicate function.  The predicate is responsible for deciding whether
+the expression to be matched has the correct mode.
 
-When constructing an insn, argument 3 of the gen-function will specify
+When constructing RTL, argument 3 of the gen-function will specify
 the operation (i.e.@: the expression code) for the expression to be
 made.  It should be an RTL expression, whose expression code is copied
 into a new expression whose operands are arguments 1 and 2 of the
@@ -416,24 +424,29 @@ gen-function.  The subexpressions of argument 3 are not used;
 only its expression code matters.
 
 When @code{match_operator} is used in a pattern for matching an insn,
-it usually best if the operand number of the @code{match_operator}
-is higher than that of the actual operands of the insn.  This improves
-register allocation because the register allocator often looks at
-operands 1 and 2 of insns to see if it can do register tying.
-
-There is no way to specify constraints in @code{match_operator}.  The
-operand of the insn which corresponds to the @code{match_operator}
-never has any constraints because it is never reloaded as a whole.
-However, if parts of its @var{operands} are matched by
-@code{match_operand} patterns, those parts may have constraints of
-their own.
+it is usually best if the operand number of the @code{match_operator}
+is higher than that of the actual operands of the insn.  This can
+improve register allocation because the register allocator often
+looks at operands 1 and 2 of insns to see if they are suitable
+for register tying.
+
+There is no way to specify constraints in a @code{match_operator}
+expression.  The operand of the insn which corresponds to the
+@code{match_operator} never has any constraints because it is never
+reloaded as a whole.  However, if parts of its @var{operands} are
+matched by @code{match_operand} patterns, those parts may have
+constraints of their own.
 
 @findex match_op_dup
 @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
 Like @code{match_dup}, except that it applies to operators instead of
-operands.  When constructing an insn, operand number @var{n} will be
-substituted at this point.  But in matching, @code{match_op_dup} behaves
-differently.  It assumes that operand number @var{n} has already been
+operands.
+
+When constructing RTL, operand number @var{n} will be substituted at
+this point.
+
+When matching an insn, @code{match_op_dup} behaves differently.  It
+assumes that operand number @var{n} has already been
 determined by a @code{match_operator} appearing earlier in the
 recognition template, and it matches only an identical-looking
 expression.
@@ -442,7 +455,7 @@ expression.
 @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
 This pattern is a placeholder for an insn that consists of a
 @code{parallel} expression with a variable number of elements.  This
-expression should only appear at the top level of an insn pattern.
+expression may only appear at the top level of an insn pattern.
 
 When constructing an insn, operand number @var{n} will be substituted at
 this point.  When matching an insn, it matches if the body of the insn

[Patch docs 4/5] Update "Output Template/Statement" from md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 624 bytes --]


Hi,

This patch updates the text in the "Output Template" and "Output
Statement" sections of md.texi.

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.

OK?

Thanks,
James

---
2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Output Template): Update text.
	(Output Statement): Likewise.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0004-Patch-docs-4-5-Update-Output-Template-Statement-from.patch --]
[-- Type: text/x-patch;  name=0004-Patch-docs-4-5-Update-Output-Template-Statement-from.patch, Size: 10600 bytes --]

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index a589f5b..3b853c8 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -519,7 +519,7 @@ Like @code{match_op_dup}, but for @code{match_parallel} instead of
 @cindex percent sign
 The @dfn{output template} is a string which specifies how to output the
 assembler code for an instruction pattern.  Most of the template is a
-fixed string which is output literally.  The character @samp{%} is used
+fixed string which is output verbatim.  The character @samp{%} is used
 to specify where to substitute an operand; it can also be used to
 identify places where different variants of the assembler require
 different syntax.
@@ -528,9 +528,29 @@ In the simplest case, a @samp{%} followed by a digit @var{n} says to output
 operand @var{n} at that point in the string.
 
 @samp{%} followed by a letter and a digit says to output an operand in an
-alternate fashion.  Four letters have standard, built-in meanings described
-below.  The machine description macro @code{PRINT_OPERAND} can define
-additional letters with nonstandard meanings.
+alternate fashion.  Four letters and two punctuation characters have
+standard, built-in meanings described below.  The target macro
+@code{PRINT_OPERAND} can define additional letters or punctuation
+characters with nonstandard meanings.
+
+One use of nonstandard letters or punctuation following @samp{%} is to
+distinguish between different assembler dialects for the same machine.
+This is used in the m68k target to distinguish between Motorola and MIT
+assebler syntax.
+
+Motorola syntax requires periods in most opcode names, while MIT syntax
+does not. For example, the opcode @samp{movel} in MIT syntax is written as
+@samp{move.l} in Motorola syntax.  The same file of patterns is used for
+both kinds of output syntax, but the character sequence @samp{%.} is used
+in each place where Motorola syntax requires a period.  The
+@code{PRINT_OPERAND} macro is defined to ouput a period when compiling
+for the Motorola syntax, and to output nothing when compiling for the MIT
+syntax.
+
+Alternatively, if the target macro @code{ASSEMBLER_DIALECT} is defined,
+an output template of the form @samp{@{option0|option1|option2@}} can be
+used to output different variants of assembler language syntax
+(@pxref{Instruction Output}).
 
 @samp{%c@var{digit}} can be used to substitute an operand that is a
 constant value without the syntax that normally indicates an immediate
@@ -549,8 +569,8 @@ as if it were a memory reference.
 instruction.
 
 @samp{%=} outputs a number which is unique to each instruction in the
-entire compilation.  This is useful for making local labels to be
-referred to more than once in a single template that generates multiple
+entire compilation.  This is useful for creating local labels which may
+be referred to more than once in a single template that generates multiple
 assembler instructions.
 
 @samp{%} followed by a punctuation character specifies a substitution that
@@ -566,82 +586,68 @@ The template may generate multiple assembler instructions.  Write the text
 for the instructions, with @samp{\;} between them.
 
 @cindex matching operands
-When the RTL contains two operands which are required by constraint to match
-each other, the output template must refer only to the lower-numbered operand.
-Matching operands are not always identical, and the rest of the compiler
-arranges to put the proper RTL expression for printing into the lower-numbered
-operand.
-
-One use of nonstandard letters or punctuation following @samp{%} is to
-distinguish between different assembler languages for the same machine; for
-example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
-requires periods in most opcode names, while MIT syntax does not.  For
-example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
-syntax.  The same file of patterns is used for both kinds of output syntax,
-but the character sequence @samp{%.} is used in each place where Motorola
-syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
-defines the sequence to output a period; the macro for MIT syntax defines
-it to do nothing.
+When the RTL contains two operands which are required by their constraints
+to match each other, the output template must refer only to the
+lower-numbered operand.  Matching operands are not always identical,
+and only the lower-numbered operand is guaranteed to contain the
+RTL expression for printing.
 
 @cindex @code{#} in template
 As a special case, a template consisting of the single character @code{#}
-instructs the compiler to first split the insn, and then output the
-resulting instructions separately.  This helps eliminate redundancy in the
-output templates.   If you have a @code{define_insn} that needs to emit
-multiple assembler instructions, and there is a matching @code{define_split}
-already defined, then you can simply use @code{#} as the output template
-instead of writing an output template that emits the multiple assembler
-instructions.
+instructs the compiler to use a matching @code{define_split} expression
+to split the insn.  This will generate a new sequence of insns, which
+will then be output according to their own templates.  This helps eliminate
+redundancy in the output templates.
 
-If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
-of the form @samp{@{option0|option1|option2@}} in the templates.  These
-describe multiple variants of assembler language syntax.
-@xref{Instruction Output}.
-
-@node Output Statement
-@section C Statements for Assembler Output
-@cindex output statements
-@cindex C statements for assembler output
-@cindex generating assembler output
+@subsection Output Templates with Multiple Operand Constraints
+@cindex multiple output templates
 
 Often a single fixed template string cannot produce correct and efficient
 assembler code for all the cases that are recognized by a single
 instruction pattern.  For example, the opcodes may depend on the kinds of
-operands; or some unfortunate combinations of operands may require extra
-machine instructions.
+operands; or some combinations of operands may require extra machine
+instructions.
 
 If the output control string starts with a @samp{@@}, then it is actually
 a series of templates, each on a separate line.  (Blank lines and
 leading spaces and tabs are ignored.)  The templates correspond to the
-pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
-if a target machine has a two-address add instruction @samp{addr} to add
-into a register and another @samp{addm} to add a register to memory, you
-might write this pattern:
+pattern's constraint alternatives (@pxref{Multi-Alternative}).
+
+For example, if a target machine has a two-address add instruction
+@samp{addreg} to add into a register and another @samp{addmem} to add
+a register to memory, this pattern could be used to describe the
+instructions.
 
 @smallexample
 (define_insn "addsi3"
   [(set (match_operand:SI 0 "general_operand" "=r,m")
         (plus:SI (match_operand:SI 1 "general_operand" "0,0")
-                 (match_operand:SI 2 "general_operand" "g,r")))]
+                 (match_operand:SI 2 "general_operand" "r,r")))]
   ""
   "@@
-   addr %2,%0
-   addm %2,%0")
+   addreg %2,%0
+   addmem %2,%0")
 @end smallexample
 
+@node Output Statement
+@section C Statements for Assembler Output
+@cindex output statements
+@cindex C statements for assembler output
+@cindex generating assembler output
 @cindex @code{*} in template
 @cindex asterisk in template
+
 If the output control string starts with a @samp{*}, then it is not an
 output template but rather a piece of C program that should compute a
-template.  It should execute a @code{return} statement to return the
-template-string you want.  Most such templates use C string literals, which
-require doublequote characters to delimit them.  To include these
-doublequote characters in the string, prefix each one with @samp{\}.
+template string and return it.  Most such templates use C string
+literals, which require doublequote characters to delimit them.  To
+include these doublequote characters in the string, prefix each one
+with @samp{\}.
 
-If the output control string is written as a brace block instead of a
-double-quoted string, it is automatically assumed to be C code.  In that
-case, it is not necessary to put in a leading asterisk, or to escape the
-doublequotes surrounding C string literals.
+The output control string may also be written as a brace block instead of a
+double-quoted string.  In this case, it is also treated as C code.  When
+using the brace block form, it is not necessary to write the leading
+asterisk, or to escape the doublequotes surrounding C string literals.
 
 The operands may be found in the array @code{operands}, whose C data type
 is @code{rtx []}.
@@ -663,12 +669,11 @@ vector may be @code{operands}, or it may be another array of @code{rtx}
 that you declare locally and initialize yourself.
 
 @findex which_alternative
-When an insn pattern has multiple alternatives in its constraints, often
-the appearance of the assembler code is determined mostly by which alternative
-was matched.  When this is so, the C code can test the variable
-@code{which_alternative}, which is the ordinal number of the alternative
-that was actually satisfied (0 for the first, 1 for the second alternative,
-etc.).
+Where an insn pattern has multiple alternatives in its constraints, the
+appearance of the assembler code is often determined by which alternative
+was matched.  The variable @code{which_alternative} contains this
+information, and gives the ordinal number of the alternative that was
+chosen (0 for the first, 1 for the second alternative, etc.).
 
 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
 for registers and @samp{clrmem} for memory locations.  Here is how
@@ -701,8 +706,8 @@ as follows, having the output control string start with a @samp{@@}:
 @end group
 @end smallexample
 
-If you just need a little bit of C code in one (or a few) alternatives,
-you can use @samp{*} inside of a @samp{@@} multi-alternative template:
+Where C code in only needed in one (or a few) alternatives, you can
+use @samp{*} inside of a @samp{@@} multi-alternative template:
 
 @smallexample
 @group

[Patch docs 1/5] Update the first section of md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 614 bytes --]


Hi,

This patch updates the introduction to, and first section of, md.texi.

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.

OK?

Thanks,
James

---
2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Machine Descriptions): Update text.
	(menu): Likewise.
	(Overview): Likewise.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Patch-docs-1-5-Update-the-first-section-of-md.texi.patch --]
[-- Type: text/x-patch;  name=0001-Patch-docs-1-5-Update-the-first-section-of-md.texi.patch, Size: 7784 bytes --]

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 7f0426c..0277f14 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -7,39 +7,39 @@
 @chapter Machine Descriptions
 @cindex machine descriptions
 
-A machine description has two parts: a file of instruction patterns
-(@file{.md} file) and a C header file of macro definitions.
+A machine description has two parts: one or more files describing the
+instructions available on the target (@file{.md} files) and one or more
+C/C++ source files implementing target hooks and macros.  These are
+described in the next chapter (@pxref{Target Macros}).
 
-The @file{.md} file for a target machine contains a pattern for each
-instruction that the target machine supports (or at least each instruction
-that is worth telling the compiler about).  It may also contain comments.
-A semicolon causes the rest of the line to be a comment, unless the semicolon
-is inside a quoted string.
-
-See the next chapter for information on the C header file.
+This chapter describes the @file{.md} files for a target machine.  These
+contain the instruction patterns which are used by the compiler when
+expanding gimple to RTL, during the RTL optimization passes, and when
+emitting assembler code.
 
 @menu
 * Overview::            How the machine description is used.
 * Patterns::            How to write instruction patterns.
 * Example::             An explained example of a @code{define_insn} pattern.
-* RTL Template::        The RTL template defines what insns match a pattern.
+* RTL Template::        The RTL template defines which insns may match a
+                        pattern.
 * Output Template::     The output template says how to make assembler code
-                        from such an insn.
+                        from an insn matched to an instruction pattern.
 * Output Statement::    For more generality, write C code to output
                         the assembler code.
-* Predicates::          Controlling what kinds of operands can be used
-                        for an insn.
+* Predicates::          Controlling which kinds of operands can be used
+                        when matching an insn to an instruction pattern.
 * Constraints::         Fine-tuning operand selection.
 * Standard Names::      Names mark patterns to use for code generation.
 * Pattern Ordering::    When the order of patterns makes a difference.
 * Dependent Patterns::  Having one pattern may make you need another.
 * Jump Patterns::       Special considerations for patterns for jump insns.
 * Looping Patterns::    How to define patterns for special looping insns.
-* Insn Canonicalizations::Canonicalization of Instructions
+* Insn Canonicalizations::Canonicalization of instructions
 * Expander Definitions::Generating a sequence of several RTL insns
                         for a standard operation.
-* Insn Splitting::      Splitting Instructions into Multiple Instructions.
-* Including Patterns::  Including Patterns in Machine Descriptions.
+* Insn Splitting::      Splitting insns into multiple insns.
+* Including Patterns::  Including patterns in machine descriptions.
 * Peephole Definitions::Defining machine-specific peephole optimizations.
 * Insn Attributes::     Specifying the value of attributes for generated insns.
 * Conditional Execution::Generating @code{define_insn} patterns for
@@ -54,50 +54,60 @@ See the next chapter for information on the C header file.
 @node Overview
 @section Overview of How the Machine Description is Used
 
-There are three main conversions that happen in the compiler:
+There are four main conversions that happen in the compiler:
 
 @enumerate
 
 @item
-The front end reads the source code and builds a parse tree.
+The front end reads the source code and converts it to an intermediate,
+front end specific, tree based representation.
 
 @item
-The parse tree is used to generate an RTL insn list based on named
-instruction patterns.
+This tree based representation is lowered (gimplified) to a gimple
+representation.
 
 @item
-The insn list is matched against the RTL templates to produce assembler
-code.
+The gimple representation is transformed (expanded) to an RTL
+representation.  This RTL representation is a doubly-linked chain of
+objects called insns, known as the insn list.
+
+@item
+The insn list is optimized, and the optimized insn list is matched
+against @code{define_insn} instruction patterns in the machine description
+to produce assembler code.
 
 @end enumerate
 
-For the generate pass, only the names of the insns matter, from either a
-named @code{define_insn} or a @code{define_expand}.  The compiler will
+When expanding from gimple to RTL, only named @code{define_insn}
+constructs and @code{define_expand} constructs are used.  The compiler will
 choose the pattern with the right name and apply the operands according
 to the documentation later in this chapter, without regard for the RTL
-template or operand constraints.  Note that the names the compiler looks
-for are hard-coded in the compiler---it will ignore unnamed patterns and
-patterns with names it doesn't know about, but if you don't provide a
-named pattern it needs, it will abort.
+template or operand constraints.  Note that the names which are used for
+expansion are hard-coded in the compiler---unnamed patterns and patterns
+with names which do not have a standard meaning are ignored during
+expansion.  If you don't provide a named pattern that the compiler is
+trying to expand, it may try a different expansion strategy.  If no
+other expansion strategies are possible, the compiler will abort.
 
 If a @code{define_insn} is used, the template given is inserted into the
-insn list.  If a @code{define_expand} is used, one of three things
-happens, based on the condition logic.  The condition logic may manually
-create new insns for the insn list, say via @code{emit_insn()}, and
-invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
-compiler to use an alternate way of performing that task.  If it invokes
-neither @code{DONE} nor @code{FAIL}, the template given in the pattern
+insn list.
+
+If a @code{define_expand} is used, one of three things happens, encoded in
+the condition logic.  The condition logic may manually create new insns
+for the insn list, say via @code{emit_insn ()}, and invoke @code{DONE},
+indicating a successful expansion.  If the standard pattern name permits
+it, the condition logic may invoke @code{FAIL} to express that an alternate
+strategy should be used to performing the expansion.  If the condition logic
+invokes neither @code{DONE} nor @code{FAIL}, the template given in the pattern
 is inserted, as if the @code{define_expand} were a @code{define_insn}.
 
 Once the insn list is generated, various optimization passes convert,
-replace, and rearrange the insns in the insn list.  This is where the
-@code{define_split} and @code{define_peephole} patterns get used, for
-example.
-
-Finally, the insn list's RTL is matched up with the RTL templates in the
-@code{define_insn} patterns, and those patterns are used to emit the
-final assembly code.  For this purpose, each named @code{define_insn}
-acts like it's unnamed, since the names are ignored.
+replace, and rearrange the insns in the insn list.
+
+Finally, the insn list's RTL is matched with the RTL templates from the
+@code{define_insn} instruction patterns, and those patterns are used to
+emit the final assembly code.  For this purpose, names are ignored.  All
+@code{define_insn} are considered for matching.
 
 @node Patterns
 @section Everything about Instruction Patterns

[Patch docs 2/5] Update "Instruction Patterns" in md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 606 bytes --]


Hi,

This patch updates the second section of md.texi - "Everything about
Patterns".

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.

OK?

Thanks,
James

---
2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Instruction Patterns): Update text.
	(Example): Update text.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-Patch-docs-2-5-Update-Instruction-Patterns-in-md.tex.patch --]
[-- Type: text/x-patch;  name=0002-Patch-docs-2-5-Update-Instruction-Patterns-in-md.tex.patch, Size: 8402 bytes --]

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 0277f14..b852981 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -115,85 +115,98 @@ emit the final assembly code.  For this purpose, names are ignored.  All
 @cindex instruction patterns
 
 @findex define_insn
-Each instruction pattern contains an incomplete RTL expression, with pieces
-to be filled in later, operand constraints that restrict how the pieces can
-be filled in, and an output pattern or C code to generate the assembler
-output, all wrapped up in a @code{define_insn} expression.
+A @code{define_insn} expression is used to define instruction patterns
+to which insns may be matched.  A @code{define_insn} expression contains
+an incomplete RTL expression, with pieces to be filled in later, operand
+constraints that restrict how the pieces can be filled in, and an output
+template or C code to generate the assembler output.
 
-A @code{define_insn} is an RTL expression containing four or five operands:
+A @code{define_insn} contains either four or five components:
 
 @enumerate
 @item
-An optional name.  The presence of a name indicate that this instruction
-pattern can perform a certain standard job for the RTL-generation
-pass of the compiler.  This pass knows certain names and will use
-the instruction patterns with those names, if the names are defined
-in the machine description.
-
-The absence of a name is indicated by writing an empty string
-where the name should go.  Nameless instruction patterns are never
-used for generating RTL code, but they may permit several simpler insns
-to be combined later on.
-
-Names that are not thus known and used in RTL-generation have no
-effect; they are equivalent to no name at all.
+The @dfn{insn name}: When expanding from gimple to RTL, and when performing
+optimizations, the compiler looks for patterns with certain names,
+collectively known as the standard pattern names (@pxref{Standard Names}).
+The target-independent infrastructure in the compiler which references
+these names is generally accessed through the interfaces defined
+in @code{optabs.c}.
+
+Names that are not listed as one of the standard pattern names are not
+used directly by the target-independent code.  However, machine
+descriptions may themselves make use of named patterns in
+@code{define_expand} or @code{define_split} expressions.
+
+It is also possible to define a nameless instruction pattern.  This uses
+an empty string in place of the name.  Nameless instruction patterns cannot
+be used when generating RTL code, but they may be matched against during
+the combine and split passes of the compiler.
+
+Where names are given to instruction patterns, these must be unique
+in the machine description file.
 
 For the purpose of debugging the compiler, you may also specify a
 name beginning with the @samp{*} character.  Such a name is used only
-for identifying the instruction in RTL dumps; it is entirely equivalent
-to having a nameless pattern for all other purposes.
+for identifying the instruction in RTL dumps; it is equivalent to having
+a nameless pattern for all other purposes.  Names beginning with the
+@samp{*} character are not required to be unique.
 
 @item
-The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
-RTL expressions which show what the instruction should look like.  It is
-incomplete because it may contain @code{match_operand},
+The @dfn{RTL template}: This is a vector of incomplete RTL expressions
+which describe the semantics of the instruction (@pxref{RTL Template}).
+It is incomplete because it may contain @code{match_operand},
 @code{match_operator}, and @code{match_dup} expressions that stand for
 operands of the instruction.
 
-If the vector has only one element, that element is the template for the
-instruction pattern.  If the vector has multiple elements, then the
-instruction pattern is a @code{parallel} expression containing the
-elements described.
+If the vector has multiple elements, the RTL template is treated as a
+@code{parallel} expression.
 
 @item
 @cindex pattern conditions
 @cindex conditions, in patterns
-A condition.  This is a string which contains a C expression that is
-the final test to decide whether an insn body matches this pattern.
+The condition: This is a string which contains a C expression.  When the
+compiler attempts to match RTL against a pattern, the condition is
+evaluated.  If the condition evaluates to @code{true}, the match is
+permitted.  The condition may be an empty string, which is treated
+as always @code{true}.
 
 @cindex named patterns and conditions
-For a named pattern, the condition (if present) may not depend on
-the data in the insn being matched, but only the target-machine-type
-flags.  The compiler needs to test these conditions during
-initialization in order to learn exactly which named instructions are
-available in a particular run.
+For a named pattern, the condition may not depend on the data in the
+insn being matched, but only the target-machine-type flags.  The compiler
+needs to test these conditions during initialization in order to learn
+exactly which named instructions are available in a particular run.
 
 @findex operands
 For nameless patterns, the condition is applied only when matching an
 individual insn, and only after the insn has matched the pattern's
 recognition template.  The insn's operands may be found in the vector
-@code{operands}.  For an insn where the condition has once matched, it
-can't be used to control register allocation, for example by excluding
-certain hard registers or hard register combinations.
+@code{operands}.
+
+For an insn where the condition has once matched, it
+cannot later be used to control register allocation by excluding
+certain register or value combinations.
 
 @item
-The @dfn{output template}: a string that says how to output matching
-insns as assembler code.  @samp{%} in this string specifies where
-to substitute the value of an operand.  @xref{Output Template}.
+The @dfn{output template} or @dfn{output statement}: This is either
+a string, or a fragment of C code which returns a string.
 
-When simple substitution isn't general enough, you can specify a piece
-of C code to compute the output.  @xref{Output Statement}.
+If it is a string, that string forms the output template and defines how
+a matched insn should be output as assembler code
+(@pxref{Output Template}).  If it is a fragment of C code, this should
+return a string which will be used as the output template
+(@pxref{Output Statement}).
 
 @item
-Optionally, a vector containing the values of attributes for insns matching
-this pattern.  @xref{Insn Attributes}.
+The @dfn{insn attributes}: This is an optional vector containing the values of
+attributes for insns matching this pattern (@pxref{Insn Attributes}).
 @end enumerate
 
 @node Example
 @section Example of @code{define_insn}
 @cindex @code{define_insn} example
 
-Here is an actual example of an instruction pattern, for the 68000/68020.
+Here is an example of an instruction pattern, taken from the machine
+description for the 68000/68020.
 
 @smallexample
 (define_insn "tstsi"
@@ -223,12 +236,12 @@ This can also be written using braced strings:
 @})
 @end smallexample
 
-This is an instruction that sets the condition codes based on the value of
-a general operand.  It has no condition, so any insn whose RTL description
-has the form shown may be handled according to this pattern.  The name
-@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
-pass that, when it is necessary to test such a value, an insn to do so
-can be constructed using this pattern.
+This describes an instruction which sets the condition codes based on the
+value of a general operand.  It has no condition, so any insn with an RTL
+description of the form shown may be matched to this pattern.  The name
+@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
+generation pass that, when it is necessary to test such a value, an insn
+to do so can be constructed using this pattern.
 
 The output control string is a piece of C code which chooses which
 output template to return based on the kind of operand and the specific

[Patch docs 5/5] Update "Predicates" from md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 545 bytes --]


Hi,

This patch updates the predicates section from md.texi.

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.

OK?

Thanks,
James

---
2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Predicates): Update text.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0005-Patch-docs-5-5-Update-Predicates-from-md.texi.patch --]
[-- Type: text/x-patch;  name=0005-Patch-docs-5-5-Update-Predicates-from-md.texi.patch, Size: 16454 bytes --]

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 3b853c8..e1fd8c6 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -737,9 +737,8 @@ predicates used with @code{match_operand} have names that end in
 @samp{_operand}, and those used with @code{match_operator} have names
 that end in @samp{_operator}.
 
-All predicates are Boolean functions (in the mathematical sense) of
-two arguments: the RTL expression that is being considered at that
-position in the instruction pattern, and the machine mode that the
+Predicates take two arguments: the RTL expression that is being considered
+at that position in the instruction pattern, and the machine mode that the
 @code{match_operand} or @code{match_operator} specifies.  In this
 section, the first argument is called @var{op} and the second argument
 @var{mode}.  Predicates can be called from C as ordinary two-argument
@@ -747,39 +746,51 @@ functions; this can be useful in output templates or other
 machine-specific code.
 
 Operand predicates can allow operands that are not actually acceptable
-to the hardware, as long as the constraints give reload the ability to
-fix them up (@pxref{Constraints}).  However, GCC will usually generate
-better code if the predicates specify the requirements of the machine
-instructions as closely as possible.  Reload cannot fix up operands
-that must be constants (``immediate operands''); you must use a
-predicate that allows only constants, or else enforce the requirement
-in the extra condition.
+to the hardware, as long as the constraints can be fulfilled, perhaps by
+moving the operand between register classes, during register allocation
+(@pxref{Constraints}).  However, GCC will usually generate better code
+if the predicates specify the requirements of the machine instructions
+as closely as possible.
+
+It is an error for the contraints of an operand to be impossible to fulfil
+for operands which are valid for the predicate of the operand.  One such
+example would be the combination of a predicate allowing any operand,
+with a constraint requiring only immediate operands.  Here, the predicate
+may permit a register operand containing a non-constant value, which it would
+not be possible to convert to an immediate operand.
 
 @cindex predicates and machine modes
 @cindex normal predicates
 @cindex special predicates
-Most predicates handle their @var{mode} argument in a uniform manner.
-If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
-any mode.  If @var{mode} is anything else, then @var{op} must have the
-same mode, unless @var{op} is a @code{CONST_INT} or integer
-@code{CONST_DOUBLE}.  These RTL expressions always have
-@code{VOIDmode}, so it would be counterproductive to check that their
-mode matches.  Instead, predicates that accept @code{CONST_INT} and/or
-integer @code{CONST_DOUBLE} check that the value stored in the
-constant will fit in the requested mode.
-
-Predicates with this behavior are called @dfn{normal}.
-@command{genrecog} can optimize the instruction recognizer based on
-knowledge of how normal predicates treat modes.  It can also diagnose
-certain kinds of common errors in the use of normal predicates; for
-instance, it is almost always an error to use a normal predicate
-without specifying a mode.
-
-Predicates that do something different with their @var{mode} argument
-are called @dfn{special}.  The generic predicates
-@code{address_operand} and @code{pmode_register_operand} are special
-predicates.  @command{genrecog} does not do any optimizations or
-diagnosis when special predicates are used.
+@dfn{Normal} predicates are those for which the relationship between
+@var{mode} and @var{op} can be described in one of the following ways.
+
+@enumerate
+@item
+If @var{mode} is @code{VOIDmode} or is unspecified, then @var{op} can have
+any mode.
+
+@item
+If @var{mode} is a defined mode, then @var{op} must be of the same mode.
+
+@item
+If @var{op} is a @code{CONST_INT} or an integer @code{CONST_DOUBLE} RTL
+expression, @var{mode} can be any mode.  The predicate must itself
+check that the range of @var{mode} is sufficient to contain the value in
+@var{op}.
+@end enumerate
+
+Using normal predicates allows for additional optimization to be
+performed in the @command{genrecog} program.  This can result in a
+more efficient instruction recognizer.  @command{genrecog} is also able
+to diagnose common errors in the use of normal predicates, such as a
+missing @var{mode}.
+
+Predicates that do not have the relationship described above between their
+@var{mode} and @var{op} arguments are called @dfn{special} predicates.
+The generic predicates @code{address_operand} and
+@code{pmode_register_operand} are special predicates. @command{genrecog}
+does not do any optimizations or diagnosis when special predicates are used.
 
 @menu
 * Machine-Independent Predicates::  Predicates available to all back ends.
@@ -794,25 +805,25 @@ diagnosis when special predicates are used.
 
 These are the generic predicates available to all back ends.  They are
 defined in @file{recog.c}.  The first category of predicates allow
-only constant, or @dfn{immediate}, operands.
+only constant, or @dfn{immediate}, operands and are normal predicates.
 
 @defun immediate_operand
 This predicate allows any sort of constant that fits in @var{mode}.
-It is an appropriate choice for instructions that take operands that
-must be constant.
+It is an appropriate choice for operands to an instruction which requires
+a constant.
 @end defun
 
 @defun const_int_operand
 This predicate allows any @code{CONST_INT} expression that fits in
-@var{mode}.  It is an appropriate choice for an immediate operand that
-does not allow a symbol or label.
+@var{mode}.  It is an appropriate choice for operands to an instruction
+which requires an integer constant that may not be a symbol or a label.
 @end defun
 
 @defun const_double_operand
-This predicate accepts any @code{CONST_DOUBLE} expression that has
+This predicate allows any @code{CONST_DOUBLE} expression that has
 exactly @var{mode}.  If @var{mode} is @code{VOIDmode}, it will also
-accept @code{CONST_INT}.  It is intended for immediate floating point
-constants.
+accept any @code{CONST_INT} expression.  It is an appropriate choice for
+operands to an instruction which requires a floating point constant.
 @end defun
 
 @noindent
@@ -821,30 +832,33 @@ register.
 
 @defun register_operand
 This predicate allows any @code{REG} or @code{SUBREG} expression that
-is valid for @var{mode}.  It is often suitable for arithmetic
-instruction operands on a RISC machine.
+is valid for @var{mode}.  It is an appropriate choice for operands to an
+instruction which requires a machine register.
 @end defun
 
 @defun pmode_register_operand
-This is a slight variant on @code{register_operand} which works around
-a limitation in the machine-description reader.
+This predicate is a slight variant on @code{register_operand} which works
+around a limitation in the machine-description reader.  As @code{Pmode}
+can be an alias for some other mode, and might vary with machine-specific
+options, the machine-description reader is unable to accept @code{P} mode
+suffixes (@pxref{Misc}).
+
+Consequently, the construct:
 
 @smallexample
 (match_operand @var{n} "pmode_register_operand" @var{constraint})
 @end smallexample
 
 @noindent
-means exactly what
+expresses what would have otherwise have been written as:
 
 @smallexample
 (match_operand:P @var{n} "register_operand" @var{constraint})
 @end smallexample
 
 @noindent
-would mean, if the machine-description reader accepted @samp{:P}
-mode suffixes.  Unfortunately, it cannot, because @code{Pmode} is an
-alias for some other mode, and might vary with machine-specific
-options.  @xref{Misc}.
+were it not for the deficiencies in the machine-description reader.
+
 @end defun
 
 @defun scratch_operand
@@ -857,15 +871,15 @@ it should not be used directly.
 The third category of predicates allow only some kind of memory reference.
 
 @defun memory_operand
-This predicate allows any valid reference to a quantity of mode
+This predicate allows any valid reference to an objects of mode
 @var{mode} in memory, as determined by the weak form of
 @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
 @end defun
 
 @defun address_operand
-This predicate is a little unusual; it allows any operand that is a
-valid expression for the @emph{address} of a quantity of mode
-@var{mode}, again determined by the weak form of
+This is a special predicate which allows any operand that is a
+valid expression for the @emph{address} of an object of mode
+@var{mode}, as determined by the weak form of
 @code{GO_IF_LEGITIMATE_ADDRESS}.  To first order, if
 @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
 @code{memory_operand}, then @var{exp} is acceptable to
@@ -874,29 +888,31 @@ the mode @var{mode}.
 @end defun
 
 @defun indirect_operand
-This is a stricter form of @code{memory_operand} which allows only
-memory references with a @code{general_operand} as the address
-expression.  New uses of this predicate are discouraged, because
-@code{general_operand} is very permissive, so it's hard to tell what
-an @code{indirect_operand} does or does not allow.  If a target has
-different requirements for memory operands for different instructions,
-it is better to define target-specific predicates which enforce the
-hardware's requirements explicitly.
+This predicate is a stricter form of @code{memory_operand} which allows
+only memory references with a @code{general_operand} as the address
+expression.  New uses of this predicate are discouraged.
+
+The @code{general_operand} predicate is very permissive, consequently,
+an @code{indirect_operand} may permit more address expressions than would
+be expected.  A target with different requirements for memory operands
+for different instructions should instead define target-specific predicates
+which enforce the hardware's requirements explicitly.
 @end defun
 
 @defun push_operand
 This predicate allows a memory reference suitable for pushing a value
 onto the stack.  This will be a @code{MEM} which refers to
 @code{stack_pointer_rtx}, with a side-effect in its address expression
-(@pxref{Incdec}); which one is determined by the
+(@pxref{Incdec}). The type of side-effect is defined by the
 @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
 @end defun
 
 @defun pop_operand
 This predicate allows a memory reference suitable for popping a value
-off the stack.  Again, this will be a @code{MEM} referring to
+off the stack.  This will be a @code{MEM} referring to
 @code{stack_pointer_rtx}, with a side-effect in its address
-expression.  However, this time @code{STACK_POP_CODE} is expected.
+expression.  The type of side-effect is defined by the @code{STACK_POP_CODE}
+macro.
 @end defun
 
 @noindent
@@ -969,27 +985,38 @@ subexpression of @var{op} has one of a given list of RTX codes.
 
 The first operand of this expression is a string constant containing a
 comma-separated list of RTX code names (in lower case).  These are the
-codes for which the @code{MATCH_CODE} will be true.
-
-The second operand is a string constant which indicates what
-subexpression of @var{op} to examine.  If it is absent or the empty
-string, @var{op} itself is examined.  Otherwise, the string constant
-must be a sequence of digits and/or lowercase letters.  Each character
-indicates a subexpression to extract from the current expression; for
-the first character this is @var{op}, for the second and subsequent
-characters it is the result of the previous character.  A digit
-@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
-extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
-alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on).  The
-@code{MATCH_CODE} then examines the RTX code of the subexpression
-extracted by the complete string.  It is not possible to extract
-components of an @code{rtvec} that is not at position 0 within its RTX
-object.
+expected codes for which the @code{MATCH_CODE} will be true.
+
+The second, optional, operand is a string constant which indicates which
+subexpression of @var{op} to examine.  If it is absent or is the empty
+string, @var{op} itself is examined.
+
+Otherwise, the string constant must be a sequence of digits and/or
+lowercase letters.  Each character indicates a subexpression to extract
+from the current expression, @var{e}.  For the first character this is
+@var{op}, for the second and subsequent characters it is the result of
+the subexpression indicated by the previous character.
+
+A digit @var{n} extracts the @var{n}'th subexpression of the current
+expression, as if by @samp{@w{XEXP (@var{e}, @var{n})}}.
+
+A letter @var{l} extracts an element from the vector subexpression which
+is found at operand 0 of the current expression.  First @var{l} is
+converted to an integer @var{n} by taking the alphabetic ordinal of
+@var{l} (0 for `a', 1 for 'b', and so on).  @var{n} is then used to extract
+the @var{n}'th element of the vector subexpression at operand 0 of the current
+expression, as if by @samp{@w{XVECEXP (@var{e}, 0, @var{n})}}. It is not
+possible to extract components of an @code{rtvec} that is not at position
+0 within its RTX object.
+
+@code{MATCH_CODE} evaluates to true if the RTX code of the current
+expression, @var{e}, having parsed the full string, matches any of
+those listed in the expected codes.
 
 @item MATCH_TEST
 This expression has one operand, a string constant containing a C
-expression.  The predicate's arguments, @var{op} and @var{mode}, are
-available with those names in the C expression.  The @code{MATCH_TEST}
+expression.  The arguments to the predicate, @var{op} and @var{mode},
+are available with those names in the C expression.  @code{MATCH_TEST}
 evaluates to true if the C expression evaluates to a nonzero value.
 @code{MATCH_TEST} expressions must not have side effects.
 
@@ -1001,8 +1028,8 @@ The basic @samp{MATCH_} expressions can be combined using these
 logical operators, which have the semantics of the C operators
 @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively.  As
 in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
-arbitrary number of arguments; this has exactly the same effect as
-writing a chain of two-argument @code{AND} or @code{IOR} expressions.
+arbitrary number of arguments; this has the same effect as writing a
+chain of two-argument @code{AND} or @code{IOR} expressions.
 @end table
 
 @item
@@ -1015,8 +1042,8 @@ available with those names.
 If a code block is present in a predicate definition, then the RTL
 expression must evaluate to true @emph{and} the code block must
 execute @samp{@w{return true}} for the predicate to allow the operand.
-The RTL expression is evaluated first; do not re-check anything in the
-code block that was checked in the RTL expression.
+The RTL expression is evaluated first.  There is no reason to re-check
+anything in the code block that was checked in the RTL expression.
 @end itemize
 
 The program @command{genrecog} scans @code{define_predicate} and
@@ -1062,10 +1089,10 @@ mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
 @code{CONST_DOUBLE}.  They do @emph{not} check specifically for
 integer @code{CONST_DOUBLE}, nor do they test that the value of either
 kind of constant fits in the requested mode.  This is because
-target-specific predicates that take constants usually have to do more
-stringent value checks anyway.  If you need the exact same treatment
-of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
-provide, use a @code{MATCH_OPERAND} subexpression to call
+target-specific predicates that take constants usually have a more restricted
+range than that of the full machine mode.  If you need the exact same
+treatment of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic
+predicates provide, use a @code{MATCH_OPERAND} subexpression to call
 @code{const_int_operand}, @code{const_double_operand}, or
 @code{immediate_operand}.
 

Re: [Patch docs 0/5] Update some of md.texi

[Joseph Myers]

On Tue, 6 Jan 2015, James Greenhalgh wrote:

> I was aiming to:
> 
>   * Remove outdated details of the compiler.
>   * Remove long or obscure words that, while accurate, only served to
>     obfuscate a simple idea.
>   * Refer to similar things in a consistent fashion - in particular
>     trying to keep consistent use of "insn" and "pattern".
>   * Remove superflous examples, or waffling.
>   * Update some K&R C and make it use GNU-style.
> 
> I've split the patch to a 5-patch series, roughly covering one section
> in each.

It would be much more reviewable if the patches were split logically - 
each addressing only one of the five issues you mention above - rather 
than physically.  As is, I have no idea of the motivation of each of the 
changes made by each patch (and, as applicable, the rationale for 
considering the change to be (a) correct, (b) not removing any useful 
information (for example, the first patch appears to remove the only 
documentation of .md comment syntax, but there is no discussion of this 
point anywhere in the write-up of that patch), (c) an improvement), and 
"Update text." is thoroughly unhelpful as a ChangeLog entry to explain the 
intent of the changes.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [Patch docs 0/5] Update some of md.texi

[James Greenhalgh]

On Tue, Jan 06, 2015 at 02:56:58PM +0000, Joseph Myers wrote:
> On Tue, 6 Jan 2015, James Greenhalgh wrote:
> 
> > I was aiming to:
> > 
> >   * Remove outdated details of the compiler.
> >   * Remove long or obscure words that, while accurate, only served to
> >     obfuscate a simple idea.
> >   * Refer to similar things in a consistent fashion - in particular
> >     trying to keep consistent use of "insn" and "pattern".
> >   * Remove superflous examples, or waffling.
> >   * Update some K&R C and make it use GNU-style.
> > 
> > I've split the patch to a 5-patch series, roughly covering one section
> > in each.
> 
> It would be much more reviewable if the patches were split logically - 
> each addressing only one of the five issues you mention above - rather 
> than physically.

That is rather difficult to tease out of a documentation patch without
ending up with a very deep patch stack. Of course such a request is
possible, but often the partial change makes little sense or improvement
without rewriting an entire section, and the burden of making the
intermediary changes read well makes the process of rewriting documentation
exceedingly laborious. Splitting to this granularity essentially requires
a per-paragraph justification.

In reality, a per-paragraph justification of my changes will be easier
for me to provide than a deep patch set. I'll try to find some time one
evening this week to "review" my patches to give this context, if that
would be acceptable.

Hopefully I'll find a few more areas where the text can be improved
along the way!

> and  "Update text." is thoroughly unhelpful as a ChangeLog entry to
> explain the intent of the changes.

Well, indeed, but ChangeLog entries have always been a
thoroughly unhelpful "what changed" rather than "why did it
change". (grep ": Update\." gcc/ChangeLog*) !

Thanks,
James

Re: [Patch docs 1/5] Update the first section of md.texi

[James Greenhalgh]

As requested, please find a paragraph-by-paragraph justification for
the changes in this patch below.

I hope this aids review.

Of particular interest for this patch is the removal of the text
describing the semicolon for a comment syntax. I believe that a
description of the syntax of a .md file does not belong in the
introduction. I don't have a good suggestion as to where it should
move to.

Thanks,
James

On Tue, Jan 06, 2015 at 11:21:38AM +0000, James Greenhalgh wrote:
> diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
> index 7f0426c..0277f14 100644
> --- a/gcc/doc/md.texi
> +++ b/gcc/doc/md.texi
> @@ -7,39 +7,39 @@
>  @chapter Machine Descriptions
>  @cindex machine descriptions
>  
> -A machine description has two parts: a file of instruction patterns
> -(@file{.md} file) and a C header file of macro definitions.
> +A machine description has two parts: one or more files describing the
> +instructions available on the target (@file{.md} files) and one or more
> +C/C++ source files implementing target hooks and macros.  These are
> +described in the next chapter (@pxref{Target Macros}).

The original text was inaccurate. .md files can be included in one
another, so it is wrong to say "a file". Real-world backends are not
just C header files of macro definitions.

Rather than just mentioning the next chapter, cross-reference it.

> -The @file{.md} file for a target machine contains a pattern for each
> -instruction that the target machine supports (or at least each instruction
> -that is worth telling the compiler about).  It may also contain comments.
> -A semicolon causes the rest of the line to be a comment, unless the semicolon
> -is inside a quoted string.

A detailed description of the syntax of a .md file does not belong in an
introduction. It is a deficiency of this patch set that this text is not
added back elsewhere. Do you have any suggestions of where the text could
sensibly go?

> -See the next chapter for information on the C header file.

Moved above.

> +This chapter describes the @file{.md} files for a target machine.  These
> +contain the instruction patterns which are used by the compiler when
> +expanding gimple to RTL, during the RTL optimization passes, and when
> +emitting assembler code.

New text. Give a high level overview of what is in an md file and why
we want it.

>  
>  @menu
>  * Overview::            How the machine description is used.
>  * Patterns::            How to write instruction patterns.
>  * Example::             An explained example of a @code{define_insn} pattern.
> -* RTL Template::        The RTL template defines what insns match a pattern.
> +* RTL Template::        The RTL template defines which insns may match a
> +                        pattern.

s/what/which/ -- This reads better to me
s/match/may match/ -- Many things can result in an RTL Template not
matching; pattern ordering, predicates, failing conditions, etc.

>  * Output Template::     The output template says how to make assembler code
> -                        from such an insn.
> +                        from an insn matched to an instruction pattern.

The previous text did not make sense. "such an insn" is not bound to
anything if I am reading the contents non-linearly (as I am likely to do).

>  * Output Statement::    For more generality, write C code to output
>                          the assembler code.
> -* Predicates::          Controlling what kinds of operands can be used
> -                        for an insn.
> +* Predicates::          Controlling which kinds of operands can be used
> +                        when matching an insn to an instruction pattern.

s/what/which/ -- Reads better to me.

Add text qualifying when predicates are used - predicates can't be used
to instruct register allocation after pattern matching, they are only
used in pattern matching.

>  * Constraints::         Fine-tuning operand selection.
>  * Standard Names::      Names mark patterns to use for code generation.
>  * Pattern Ordering::    When the order of patterns makes a difference.
>  * Dependent Patterns::  Having one pattern may make you need another.
>  * Jump Patterns::       Special considerations for patterns for jump insns.
>  * Looping Patterns::    How to define patterns for special looping insns.
> -* Insn Canonicalizations::Canonicalization of Instructions
> +* Insn Canonicalizations::Canonicalization of instructions

We don't use title case elsewhere in the descriptions.

>  * Expander Definitions::Generating a sequence of several RTL insns
>                          for a standard operation.
> -* Insn Splitting::      Splitting Instructions into Multiple Instructions.
> -* Including Patterns::  Including Patterns in Machine Descriptions.
> +* Insn Splitting::      Splitting insns into multiple insns.
> +* Including Patterns::  Including patterns in machine descriptions.

Insn splitting acts on insns (a compiler concept) not instructions (a
machine concept).

We don't use title case elsewhere in the descriptions.

>  * Peephole Definitions::Defining machine-specific peephole optimizations.
>  * Insn Attributes::     Specifying the value of attributes for generated insns.
>  * Conditional Execution::Generating @code{define_insn} patterns for
> @@ -54,50 +54,60 @@ See the next chapter for information on the C header file.
>  @node Overview
>  @section Overview of How the Machine Description is Used
>  
> -There are three main conversions that happen in the compiler:
> +There are four main conversions that happen in the compiler:

The previous text is inaccurate.

>  
>  @enumerate
>  
>  @item
> -The front end reads the source code and builds a parse tree.
> +The front end reads the source code and converts it to an intermediate,
> +front end specific, tree based representation.

The previous text is imprecise.

>  @item
> -The parse tree is used to generate an RTL insn list based on named
> -instruction patterns.
> +This tree based representation is lowered (gimplified) to a gimple
> +representation.

The previous text is inaccurate.

>  
>  @item
> -The insn list is matched against the RTL templates to produce assembler
> -code.
> +The gimple representation is transformed (expanded) to an RTL
> +representation.  This RTL representation is a doubly-linked chain of
> +objects called insns, known as the insn list.

New text describing expansion from gimple to RTL.

> +
> +@item
> +The insn list is optimized, and the optimized insn list is matched
> +against @code{define_insn} instruction patterns in the machine description
> +to produce assembler code.

Add text describing that the insn list is further optimized before
instruction selection.

>  
>  @end enumerate
>  
> -For the generate pass, only the names of the insns matter, from either a
> -named @code{define_insn} or a @code{define_expand}.  The compiler will
> +When expanding from gimple to RTL, only named @code{define_insn}
> +constructs and @code{define_expand} constructs are used.  The compiler will
>  choose the pattern with the right name and apply the operands according
>  to the documentation later in this chapter, without regard for the RTL
> -template or operand constraints.  Note that the names the compiler looks
> -for are hard-coded in the compiler---it will ignore unnamed patterns and
> -patterns with names it doesn't know about, but if you don't provide a
> -named pattern it needs, it will abort.
> +template or operand constraints.  Note that the names which are used for
> +expansion are hard-coded in the compiler---unnamed patterns and patterns
> +with names which do not have a standard meaning are ignored during
> +expansion.  If you don't provide a named pattern that the compiler is
> +trying to expand, it may try a different expansion strategy.  If no
> +other expansion strategies are possible, the compiler will abort.

This is a general cleanup to make the text less casual.  This could do
with a second pass over it to remove the repeated use of "you" and the
anthropomorphism of the compiler.

I prefer the text below. We lose "without regard for the RTL template or
operand constraints", but this is contradictory anyway, as the RTL template
is used when expanding a define_insn.

  When expanding from gimple to RTL, only named @code{define_insn}
  constructs and @code{define_expand} constructs are used.  The set of
  names which are meaningful during expansion are detailed later in this
  chapter (@pxref{Standard Names}.  Note that the names which are used for
  expansion are hard-coded in the compiler---unnamed patterns and patterns
  with names which do not have a standard meaning are ignored during
  expansion.  If a named pattern that the compiler is trying to expand,
  is not provided, it may try a different expansion strategy.  If no
  other expansion strategies are possible, the compiler will abort.



>  
>  If a @code{define_insn} is used, the template given is inserted into the
> -insn list.  If a @code{define_expand} is used, one of three things
> -happens, based on the condition logic.  The condition logic may manually
> -create new insns for the insn list, say via @code{emit_insn()}, and
> -invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
> -compiler to use an alternate way of performing that task.  If it invokes
> -neither @code{DONE} nor @code{FAIL}, the template given in the pattern
> +insn list.
> +
> +If a @code{define_expand} is used, one of three things happens, encoded in
> +the condition logic.  The condition logic may manually create new insns
> +for the insn list, say via @code{emit_insn ()}, and invoke @code{DONE},
> +indicating a successful expansion.  If the standard pattern name permits
> +it, the condition logic may invoke @code{FAIL} to express that an alternate
> +strategy should be used to performing the expansion.  If the condition logic
> +invokes neither @code{DONE} nor @code{FAIL}, the template given in the pattern
>  is inserted, as if the @code{define_expand} were a @code{define_insn}.

Split one paragraph to two. One dealing with define_insn expressions, one
for define_expand expressions. This aids readability.

s/based on the condition logic/encoded in the condition logic/ -- I
don't like the use of "based on" to describe code, the code explicitly
says what to do, the compiler doesn't "base" what to do on the code.

I dislike that the condition logic is the actor in the paragraph, but I
struggled to rewrite it, so I gave up and just replaced the unclear use of
"it" with "the condition logic".

>  Once the insn list is generated, various optimization passes convert,
> -replace, and rearrange the insns in the insn list.  This is where the
> -@code{define_split} and @code{define_peephole} patterns get used, for
> -example.

These examples don't add anything useful and introduce new keywords we've
not mentioned before.

> -Finally, the insn list's RTL is matched up with the RTL templates in the
> -@code{define_insn} patterns, and those patterns are used to emit the
> -final assembly code.  For this purpose, each named @code{define_insn}
> -acts like it's unnamed, since the names are ignored.
> +replace, and rearrange the insns in the insn list.
> +
> +Finally, the insn list's RTL is matched with the RTL templates from the
> +@code{define_insn} instruction patterns, and those patterns are used to
> +emit the final assembly code.  For this purpose, names are ignored.  All
> +@code{define_insn} are considered for matching.

Just a rewording. The previous text is unnecessarily verbose.

Re: Re: [Patch docs 0/5] Update some of md.texi

[Sandra Loosemore]

On Tue, 6 Jan 2015, James Greenhalgh wrote:

> On Tue, Jan 06, 2015 at 02:56:58PM +0000, Joseph Myers wrote:
>> On Tue, 6 Jan 2015, James Greenhalgh wrote:
>>
>>> I was aiming to:
>>>
>>>   * Remove outdated details of the compiler.
>>>   * Remove long or obscure words that, while accurate, only served to
>>>     obfuscate a simple idea.
>>>   * Refer to similar things in a consistent fashion - in particular
>>>     trying to keep consistent use of "insn" and "pattern".
>>>   * Remove superflous examples, or waffling.
>>>   * Update some K&R C and make it use GNU-style.
>>>
>>> I've split the patch to a 5-patch series, roughly covering one section
>>> in each.
>>
>> It would be much more reviewable if the patches were split logically -
>> each addressing only one of the five issues you mention above - rather
>> than physically.
>
> That is rather difficult to tease out of a documentation patch without
> ending up with a very deep patch stack. Of course such a request is
> possible, but often the partial change makes little sense or improvement
> without rewriting an entire section, and the burden of making the
> intermediary changes read well makes the process of rewriting documentation
> exceedingly laborious. Splitting to this granularity essentially requires
> a per-paragraph justification.
>
> In reality, a per-paragraph justification of my changes will be easier
> for me to provide than a deep patch set. I'll try to find some time one
> evening this week to "review" my patches to give this context, if that
> would be acceptable.
>
> Hopefully I'll find a few more areas where the text can be improved
> along the way!

FWIW, I've had the same dilemma with edits to the GCC user documentation 
-- it's too easy to spend a few hours going through the document and end 
up with a gigantic patch that is totally unreviewable (because nobody 
really wants to take the time to go through tedious mechanical changes 
and nobody can identify the substantive changes mixed in with them or 
reconstruct your logic for making them).  I've concluded that the best 
way is *not* to try to maintain a big patch stack, but just to make 
multiple passes through the document to fix different types of problems 
incrementally.  E.g. address markup and grammar issues separately from 
rewrites of a whole section, in particular. I have a notepad where I've 
jotted down some things I've identified that are in need of fixing while 
I've been working on other things in invoke.texi, but no patches beyond 
the ones I've already posted and committed.

 From time to time I've wondered if we might not be better off moving 
towards something like the Wikipedia model for maintaining the GNU 
documentation (where everyone can make or revert changes and editors are 
encouraged to make changes boldly), but WP's tools are better suited for 
that model than Texinfo, patches, and SVN.  I do think that taking a 
more lenient view of "obvious fixes" for documentation than for code 
changes is appropriate, though, since bad doc changes can simply be 
reverted and are unlikely to break GCC or hold up other developers' work 
meanwhile.  It also sometimes (often?) takes months to get code patches 
reviewed and such a heavyweight process for documentation changes would 
only discourage volunteers from undertaking such work as they have time.

-Sandra

Re: [Patch docs 0/5] Update some of md.texi

[Joseph Myers]

On Tue, 6 Jan 2015, James Greenhalgh wrote:

> > and  "Update text." is thoroughly unhelpful as a ChangeLog entry to
> > explain the intent of the changes.
> 
> Well, indeed, but ChangeLog entries have always been a
> thoroughly unhelpful "what changed" rather than "why did it
> change". (grep ": Update\." gcc/ChangeLog*) !

That should be for cases where it's e.g. a completely mechanical change 
following from a more fully described change to a file listed earlier in 
the ChangeLog entry.  For this sort of documentation patch, "what changed" 
should be more specific (e.g. if you're updating the description of passes 
to refer to gimplification then say so in the ChangeLog entry).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [Patch docs 1/5] Update the first section of md.texi

[Joseph Myers]

On Tue, 6 Jan 2015, James Greenhalgh wrote:

> > -The @file{.md} file for a target machine contains a pattern for each
> > -instruction that the target machine supports (or at least each instruction
> > -that is worth telling the compiler about).  It may also contain comments.
> > -A semicolon causes the rest of the line to be a comment, unless the semicolon
> > -is inside a quoted string.
> 
> A detailed description of the syntax of a .md file does not belong in an
> introduction. It is a deficiency of this patch set that this text is not
> added back elsewhere. Do you have any suggestions of where the text could
> sensibly go?

A section that describes the lexical structure and syntax of .md files?

> > @@ -54,50 +54,60 @@ See the next chapter for information on the C header file.
> >  @node Overview
> >  @section Overview of How the Machine Description is Used
> >  
> > -There are three main conversions that happen in the compiler:
> > +There are four main conversions that happen in the compiler:
> 
> The previous text is inaccurate.

It would seem better not to give a specific number (just as we've tried to 
keep down the number of references in the web pages to a particular 
version control system).

> I prefer the text below. We lose "without regard for the RTL template or
> operand constraints", but this is contradictory anyway, as the RTL template
> is used when expanding a define_insn.

I believe the point of "without regard for the RTL template or operand 
constraints" is that when e.g. expanding addition of two SImode values, 
the RTL template from the addsi3 pattern is inserted blindly, even if that 
RTL looks nothing like RTL for an addition; nothing looks for an (add:SI) 
pattern, or generates such RTL if it's not what the RTL for addsi3 looks 
like.

I should point out, if giving paragraph-by-paragraph rationale, that *each 
revision of the patch* needs to give the paragraph-by-paragraph rationale 
corresponding to that revision of the patch - that a piece passed over for 
one revision by one reviewer may be reviewed in more detail later or by 
another reviewer.  This may be easier with a finer-grained division of the 
patch submission.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [Patch docs 1/5] Update the first section of md.texi

[Jeff Law]

On 01/06/15 11:55, Joseph Myers wrote:
> On Tue, 6 Jan 2015, James Greenhalgh wrote:
>
>>> -The @file{.md} file for a target machine contains a pattern for each
>>> -instruction that the target machine supports (or at least each instruction
>>> -that is worth telling the compiler about).  It may also contain comments.
>>> -A semicolon causes the rest of the line to be a comment, unless the semicolon
>>> -is inside a quoted string.
>>
>> A detailed description of the syntax of a .md file does not belong in an
>> introduction. It is a deficiency of this patch set that this text is not
>> added back elsewhere. Do you have any suggestions of where the text could
>> sensibly go?
>
> A section that describes the lexical structure and syntax of .md files?
Seems reasonable. However, is that too heavyweight?

ISTM we have, effectively 3 items.

Directives that start with an open-paren and end with their associated 
close paren.  ANything in between those parens is governed by the 
documentation for the specific directive.

Outside a directive we can lines with are empty or contain just 
whitespace.  These lines are effectively ignored.

Also outside a directive are lines that start with ';;'. From the ';;' 
to the end of line are comments and ignored.



>
>>> @@ -54,50 +54,60 @@ See the next chapter for information on the C header file.
>>>   @node Overview
>>>   @section Overview of How the Machine Description is Used
>>>
>>> -There are three main conversions that happen in the compiler:
>>> +There are four main conversions that happen in the compiler:
>>
>> The previous text is inaccurate.
>
> It would seem better not to give a specific number (just as we've tried to
> keep down the number of references in the web pages to a particular
> version control system).
Agreed. It's bound to get out of date as some point.


>
>> I prefer the text below. We lose "without regard for the RTL template or
>> operand constraints", but this is contradictory anyway, as the RTL template
>> is used when expanding a define_insn.
>
> I believe the point of "without regard for the RTL template or operand
> constraints" is that when e.g. expanding addition of two SImode values,
> the RTL template from the addsi3 pattern is inserted blindly, even if that
> RTL looks nothing like RTL for an addition; nothing looks for an (add:SI)
> pattern, or generates such RTL if it's not what the RTL for addsi3 looks
> like.
Right, but the next paragraph expands on things a bit and I think is 
sufficient that we can drop the "without regard for the RTL template". 
So perhaps take that out, but leave the "without regard for the operand 
constraints".

Jeff

Re: [Patch docs 2/5] Update "Instruction Patterns" in md.texi

[Jeff Law]

On 01/06/15 04:21, James Greenhalgh wrote:
> Hi,
>
> This patch updates the second section of md.texi - "Everything about
> Patterns".
>
> I was aiming to:
>
>    * Remove outdated details of the compiler.
>    * Remove long or obscure words that, while accurate, only served to
>      obfuscate a simple idea.
>    * Refer to similar things in a consistent fashion - in particular
>      trying to keep consistent use of "insn" and "pattern".
>    * Remove superflous examples, or waffling.
>
> OK?
>
> Thanks,
> James
>
> ---
> 2015-01-06  James Greenhalgh<james.greenhalgh@arm.com>
>
> 	* doc/md.texi (Instruction Patterns): Update text.
> 	(Example): Update text.
>
>
> 0002-Patch-docs-2-5-Update-Instruction-Patterns-in-md.tex.patch
>
>
> diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
> index 0277f14..b852981 100644
> --- a/gcc/doc/md.texi
> +++ b/gcc/doc/md.texi
> @@ -115,85 +115,98 @@ emit the final assembly code.  For this purpose, names are ignored.  All
>   @cindex instruction patterns
>
>   @findex define_insn
> -Each instruction pattern contains an incomplete RTL expression, with pieces
> -to be filled in later, operand constraints that restrict how the pieces can
> -be filled in, and an output pattern or C code to generate the assembler
> -output, all wrapped up in a @code{define_insn} expression.
> +A @code{define_insn} expression is used to define instruction patterns
> +to which insns may be matched.  A @code{define_insn} expression contains
> +an incomplete RTL expression, with pieces to be filled in later, operand
> +constraints that restrict how the pieces can be filled in, and an output
> +template or C code to generate the assembler output.
>
> -A @code{define_insn} is an RTL expression containing four or five operands:
> +A @code{define_insn} contains either four or five components:
How about
A @code{define_insn} contains the following components:

>
>   @enumerate
>   @item
> -An optional name.  The presence of a name indicate that this instruction
> -pattern can perform a certain standard job for the RTL-generation
> -pass of the compiler.  This pass knows certain names and will use
> -the instruction patterns with those names, if the names are defined
> -in the machine description.
> -
> -The absence of a name is indicated by writing an empty string
> -where the name should go.  Nameless instruction patterns are never
> -used for generating RTL code, but they may permit several simpler insns
> -to be combined later on.
> -
> -Names that are not thus known and used in RTL-generation have no
> -effect; they are equivalent to no name at all.
> +The @dfn{insn name}: When expanding from gimple to RTL, and when performing
> +optimizations, the compiler looks for patterns with certain names,
IIRC reload looks for specific named patterns as well.   There may be 
other places that look for standard named patterns.

Which makes me wonder how hard we should try to nail this down.  Maybe 
something along the lines of passes which generate new insns may look 
for standard names.

> +collectively known as the standard pattern names (@pxref{Standard Names}).
> +The target-independent infrastructure in the compiler which references
> +these names is generally accessed through the interfaces defined
> +in @code{optabs.c}.
Hmm, I'm not sure I'd call out optabs.c here because looking up standard 
names happens all over the place.

> +
> +Names that are not listed as one of the standard pattern names are not
> +used directly by the target-independent code.  However, machine
> +descriptions may themselves make use of named patterns in
> +@code{define_expand} or @code{define_split} expressions.
"make use of named patterns when generating insns" or something similar? 
  In theory that covers us if we have other define_foo things that want 
to look at named patterns in the future.

> +
> +It is also possible to define a nameless instruction pattern.  This uses
> +an empty string in place of the name.  Nameless instruction patterns cannot
> +be used when generating RTL code, but they may be matched against during
> +the combine and split passes of the compiler.
Wouldn't necessarily call out combine here -- nameless patterns could be 
matched anytime RTL is changed.  Just changing an operand from a 
constant to a register or vice-versa may trigger the use of a nameless 
pattern.

> +
> +Where names are given to instruction patterns, these must be unique
> +in the machine description file.
We can have multiple .md files, so probably unique across the machine 
description files for the given target.

>
>   @item
> -The @dfn{output template}: a string that says how to output matching
> -insns as assembler code.  @samp{%} in this string specifies where
> -to substitute the value of an operand.  @xref{Output Template}.
> +The @dfn{output template} or @dfn{output statement}: This is either
> +a string, or a fragment of C code which returns a string.
>
> -When simple substitution isn't general enough, you can specify a piece
> -of C code to compute the output.  @xref{Output Statement}.
> +If it is a string, that string forms the output template and defines how
> +a matched insn should be output as assembler code
> +(@pxref{Output Template}).  If it is a fragment of C code, this should
> +return a string which will be used as the output template
> +(@pxref{Output Statement}).
Can't we have multiple output templates (one per constraint)?  Ah, 
that's discussed later.  No worries.

If I havne't commented, then those hunks should be considered OK -- you 
can check those hunks in if you want.

jeff

Re: [Patch docs 1/5] Update the first section of md.texi

[Segher Boessenkool]

On Thu, Jan 08, 2015 at 02:43:27PM -0700, Jeff Law wrote:
> >A section that describes the lexical structure and syntax of .md files?
> Seems reasonable. However, is that too heavyweight?
> 
> ISTM we have, effectively 3 items.
> 
> Directives that start with an open-paren and end with their associated 
> close paren.  ANything in between those parens is governed by the 
> documentation for the specific directive.
> 
> Outside a directive we can lines with are empty or contain just 
> whitespace.  These lines are effectively ignored.
> 
> Also outside a directive are lines that start with ';;'. From the ';;' 
> to the end of line are comments and ignored.

Empty lines are whitespace.  Comments are whitespace (two kinds of
comments: ";comment<EOL/EOF>" (single semi-colon!), as well as C-style
/*comments*/).

At the top level, you have <optional whitespace> '(' <opt ws> <name>
<whatever that kind of thing wants> <opt ws> ')'; repeat; <opt ws>.

<whatever> is constrained by just a few things: anything starting with
'"' is parsed as a string (i.e. until a non-quoted second '"'); everything
starting with '{' is parsed as a C block (i.e. until a matching '}'),
and outside of those the parens have to match.

Oh, and <name> can contain much more than just alphanumerics, but we
really shouldn't document that ;-)


Segher

Re: [Patch docs 2/5] Update "Instruction Patterns" in md.texi

[Segher Boessenkool]

On Thu, Jan 08, 2015 at 03:00:02PM -0700, Jeff Law wrote:
> On 01/06/15 04:21, James Greenhalgh wrote:
> >-A @code{define_insn} is an RTL expression containing four or five 
> >operands:
> >+A @code{define_insn} contains either four or five components:
> How about
> A @code{define_insn} contains the following components:
> 
> >
> >  @enumerate
> >  @item
> >-An optional name.  The presence of a name indicate that this instruction
> >-pattern can perform a certain standard job for the RTL-generation
> >-pass of the compiler.  This pass knows certain names and will use
> >-the instruction patterns with those names, if the names are defined
> >-in the machine description.
> >-
> >-The absence of a name is indicated by writing an empty string
> >-where the name should go.  Nameless instruction patterns are never
> >-used for generating RTL code, but they may permit several simpler insns
> >-to be combined later on.
> >-
> >-Names that are not thus known and used in RTL-generation have no
> >-effect; they are equivalent to no name at all.
> >+The @dfn{insn name}: When expanding from gimple to RTL, and when 
> >performing
> >+optimizations, the compiler looks for patterns with certain names,
> IIRC reload looks for specific named patterns as well.   There may be 
> other places that look for standard named patterns.
> 
> Which makes me wonder how hard we should try to nail this down.  Maybe 
> something along the lines of passes which generate new insns may look 
> for standard names.

This whole business with standard names isn't specific to define_insn
(also define_insn_and_split and define_expand), so perhaps it should
be moved elsewhere?

Patterns with names that start with a '*' behave like nameless patterns
as well (except where the name is printed, like in dump files).  This
should be mentioned in the same place too I think (it currently is
mentioned _somewhere_ I think, but I cannot find it, hrm).


Segher

Re: [Patch docs 2/5] Update "Instruction Patterns" in md.texi

[James Greenhalgh]

[-- Attachment #1: Type: text/plain, Size: 517 bytes --]

On Thu, Jan 08, 2015 at 10:00:02PM +0000, Jeff Law wrote:
> On 01/06/15 04:21, James Greenhalgh wrote:
> If I havne't commented, then those hunks should be considered OK -- you 
> can check those hunks in if you want.

Thanks Jeff,

I've committed the attached as revision 219432. I'll work on respinning
the other hunks when I get a free half hour.

Cheers,
James

---
2015-01-11  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Instruction Patterns): Rewrite text for
	clarity.
	(Example): Likewise.


[-- Attachment #2: 0001-Patch-Docs-Copy-edit-the-text-in-Everything-about-pa.patch --]
[-- Type: text/x-diff, Size: 7166 bytes --]

From fbb3c8d1110f3e7122e0ce860d15c24c142d5db6 Mon Sep 17 00:00:00 2001
From: James Greenhalgh <james.greenhalgh@arm.com>
Date: Sun, 11 Jan 2015 17:07:36 +0000
Subject: [Patch Docs] Copy edit the text in "Everything about patterns"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="------------2.2.0"

This is a multi-part message in MIME format.
--------------2.2.0
Content-Type: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding: 8bit


2015-01-11  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Instruction Patterns): Rewrite text for
	clarity.
	(Example): Likewise.


--------------2.2.0
Content-Type: text/x-patch; name="0001-Patch-Docs-Copy-edit-the-text-in-Everything-about-pa.patch"
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename="0001-Patch-Docs-Copy-edit-the-text-in-Everything-about-pa.patch"

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index ed35d9c..71d3db9 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -115,10 +115,11 @@ emit the final assembly code.  For this purpose, names are ignored.  All
 @cindex instruction patterns
 
 @findex define_insn
-Each instruction pattern contains an incomplete RTL expression, with pieces
-to be filled in later, operand constraints that restrict how the pieces can
-be filled in, and an output pattern or C code to generate the assembler
-output, all wrapped up in a @code{define_insn} expression.
+A @code{define_insn} expression is used to define instruction patterns
+to which insns may be matched.  A @code{define_insn} expression contains
+an incomplete RTL expression, with pieces to be filled in later, operand
+constraints that restrict how the pieces can be filled in, and an output
+template or C code to generate the assembler output.
 
 A @code{define_insn} is an RTL expression containing four or five operands:
 
@@ -140,60 +141,63 @@ effect; they are equivalent to no name at all.
 
 For the purpose of debugging the compiler, you may also specify a
 name beginning with the @samp{*} character.  Such a name is used only
-for identifying the instruction in RTL dumps; it is entirely equivalent
-to having a nameless pattern for all other purposes.
+for identifying the instruction in RTL dumps; it is equivalent to having
+a nameless pattern for all other purposes.  Names beginning with the
+@samp{*} character are not required to be unique.
 
 @item
-The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
-RTL expressions which show what the instruction should look like.  It is
-incomplete because it may contain @code{match_operand},
+The @dfn{RTL template}: This is a vector of incomplete RTL expressions
+which describe the semantics of the instruction (@pxref{RTL Template}).
+It is incomplete because it may contain @code{match_operand},
 @code{match_operator}, and @code{match_dup} expressions that stand for
 operands of the instruction.
 
-If the vector has only one element, that element is the template for the
-instruction pattern.  If the vector has multiple elements, then the
-instruction pattern is a @code{parallel} expression containing the
-elements described.
+If the vector has multiple elements, the RTL template is treated as a
+@code{parallel} expression.
 
 @item
 @cindex pattern conditions
 @cindex conditions, in patterns
-A condition.  This is a string which contains a C expression that is
-the final test to decide whether an insn body matches this pattern.
+The condition: This is a string which contains a C expression.  When the
+compiler attempts to match RTL against a pattern, the condition is
+evaluated.  If the condition evaluates to @code{true}, the match is
+permitted.  The condition may be an empty string, which is treated
+as always @code{true}.
 
 @cindex named patterns and conditions
-For a named pattern, the condition (if present) may not depend on
-the data in the insn being matched, but only the target-machine-type
-flags.  The compiler needs to test these conditions during
-initialization in order to learn exactly which named instructions are
-available in a particular run.
+For a named pattern, the condition may not depend on the data in the
+insn being matched, but only the target-machine-type flags.  The compiler
+needs to test these conditions during initialization in order to learn
+exactly which named instructions are available in a particular run.
 
 @findex operands
 For nameless patterns, the condition is applied only when matching an
 individual insn, and only after the insn has matched the pattern's
 recognition template.  The insn's operands may be found in the vector
-@code{operands}.  For an insn where the condition has once matched, it
-can't be used to control register allocation, for example by excluding
-certain hard registers or hard register combinations.
+@code{operands}.
+
+For an insn where the condition has once matched, it
+cannot later be used to control register allocation by excluding
+certain register or value combinations.
 
 @item
-The @dfn{output template}: a string that says how to output matching
-insns as assembler code.  @samp{%} in this string specifies where
-to substitute the value of an operand.  @xref{Output Template}.
+The @dfn{output template} or @dfn{output statement}: This is either
+a string, or a fragment of C code which returns a string.
 
 When simple substitution isn't general enough, you can specify a piece
 of C code to compute the output.  @xref{Output Statement}.
 
 @item
-Optionally, a vector containing the values of attributes for insns matching
-this pattern.  @xref{Insn Attributes}.
+The @dfn{insn attributes}: This is an optional vector containing the values of
+attributes for insns matching this pattern (@pxref{Insn Attributes}).
 @end enumerate
 
 @node Example
 @section Example of @code{define_insn}
 @cindex @code{define_insn} example
 
-Here is an actual example of an instruction pattern, for the 68000/68020.
+Here is an example of an instruction pattern, taken from the machine
+description for the 68000/68020.
 
 @smallexample
 (define_insn "tstsi"
@@ -223,12 +227,12 @@ This can also be written using braced strings:
 @})
 @end smallexample
 
-This is an instruction that sets the condition codes based on the value of
-a general operand.  It has no condition, so any insn whose RTL description
-has the form shown may be handled according to this pattern.  The name
-@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
-pass that, when it is necessary to test such a value, an insn to do so
-can be constructed using this pattern.
+This describes an instruction which sets the condition codes based on the
+value of a general operand.  It has no condition, so any insn with an RTL
+description of the form shown may be matched to this pattern.  The name
+@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
+generation pass that, when it is necessary to test such a value, an insn
+to do so can be constructed using this pattern.
 
 The output control string is a piece of C code which chooses which
 output template to return based on the kind of operand and the specific

--------------2.2.0--

Re: [Patch docs 4/5] Update "Output Template/Statement" from md.texi

[Jeff Law]

On 01/06/15 04:21, James Greenhalgh wrote:
>
> Hi,
>
> This patch updates the text in the "Output Template" and "Output
> Statement" sections of md.texi.
>
> I was aiming to:
>
>    * Remove outdated details of the compiler.
>    * Remove long or obscure words that, while accurate, only served to
>      obfuscate a simple idea.
>    * Refer to similar things in a consistent fashion - in particular
>      trying to keep consistent use of "insn" and "pattern".
>    * Remove superflous examples, or waffling.
>
> OK?
>
> Thanks,
> James
>
> ---
> 2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>
>
> 	* doc/md.texi (Output Template): Update text.
> 	(Output Statement): Likewise.
With a better ChangeLog, this is OK.

I'm a bit amazed how the m68k stuff for handling the different syntaxes 
ended up in the "matching operands" section.  Egad.  You might consider 
noting that as an example of how those characters are useful.

One of the things about our manual that is kind of lame is the number of 
examples that come from obsolete/dead architectures.  But I'm not going 
to ask you to change that.

Jeff

Re: [Patch docs 3/5] Update "RTL Template" in md.texi

[Jeff Law]

On 01/06/15 04:21, James Greenhalgh wrote:
> Hi,
>
> This patch updates the RTL Template section of md.texi.
>
> I was aiming to:
>
>    * Remove outdated details of the compiler.
>    * Remove long or obscure words that, while accurate, only served to
>      obfuscate a simple idea.
>    * Refer to similar things in a consistent fashion - in particular
>      trying to keep consistent use of "insn" and "pattern".
>    * Remove superflous examples, or waffling.
>
> OK?
>
> Thanks,
> James
>
> ---
> 2015-01-06  James Greenhalgh<james.greenhalgh@arm.com>
>
> 	* doc/md.texi (RTL Template): Update text.
>
>
> 0003-Patch-docs-3-5-Update-RTL-Template-in-md.texi.patch
>
>
> diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
> index b852981..a589f5b 100644
> --- a/gcc/doc/md.texi
> +++ b/gcc/doc/md.texi
> @@ -257,25 +257,23 @@ type of CPU for which code is being generated.
>   @cindex recognizing insns
>   @cindex insns, recognizing
>
> -The RTL template is used to define which insns match the particular pattern
> +The RTL template is used to define which insns match the pattern
>   and how to find their operands.  For named patterns, the RTL template also
> -says how to construct an insn from specified operands.
> +defines how to construct an insn from specified operands.
>
> -Construction involves substituting specified operands into a copy of the
> -template.  Matching involves determining the values that serve as the
> -operands in the insn being matched.  Both of these activities are
> -controlled by special expression types that direct matching and
> -substitution of the operands.
> +Constructing an insn involves substituting specified operands into a
> +copy of the template.  Matching an insn involves determining the values
> +that serve as the operands in the insn being matched.  Both of these
> +activities are controlled by the special RTL expressions described below.
Matching also involves verifying that the values serving as operands 
match their associated predicates.  I guess that's discussed below and 
probably doesn't need to be explicitly mentioned here.


>
>   @table @code
>   @findex match_operand
>   @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
>   This expression is a placeholder for operand number @var{n} of
> -the insn.  When constructing an insn, operand number @var{n}
> -will be substituted at this point.  When matching an insn, whatever
> -appears at this position in the insn will be taken as operand
> -number @var{n}; but it must satisfy @var{predicate} or this instruction
> -pattern will not match at all.
> +the instruction pattern.  When constructing RTL, operand number @var{n}
> +will be substituted at this point.  When matching an insn, assuming the
> +@var{predicate} is satisfied, whatever appears at this position in the
> +insn will be taken as operand number @var{n}.
So are you referring to the operand predicates here or the insn's 
condition?   The new wording made me almost think you'd confused operand 
predicates and insn conditions.  This probably needs further refinement.



> @@ -302,80 +300,89 @@ not always.  For example, the predicate @code{address_operand} uses
>   Many predicates accept @code{const_int} nodes even though their mode is
>   @code{VOIDmode}.
>
> -@var{constraint} controls reloading and the choice of the best register
> -class to use for a value, as explained later (@pxref{Constraints}).
> -If the constraint would be an empty string, it can be omitted.
> -
> -People are often unclear on the difference between the constraint and the
> -predicate.  The predicate helps decide whether a given insn matches the
> -pattern.  The constraint plays no role in this decision; instead, it
> -controls various decisions in the case of an insn which does match.
> +@var{constraint} controls the best register class to use for a value,
> +and therefore register allocation and reloading, as explained
> +later (@pxref{Constraints}).  If the constraint would be an empty
> +string, it can be omitted.
> +
> +In summary, the predicate is used to control whether the instruction
> +pattern is a valid match for an insn.  The constraint is used to control
> +register allocation decisions in the case of an instruction pattern which
> +has already been matched to an insn.
> +
> +It is an error for the contraints of an operand to be impossible to fulfil
s/contraints/constraints/

> +for operands which are valid for the predicate of the operand.  Formally;
> +for all operands for which the predicate would be true, there must exist
> +at least one valid register class for that operand.  Note that this
> +restriction does not forbid accepting operands which will need additional
> +handling to move them to a valid register class.  This restriction would,
> +however, prevent combining a constraint set requiring the use of an
> +immediate value with a predicate allowing any operand, as it is not
> +possible to convert all operand types to immediate values.
I wonder if it's worth mentioning that, having predicates which are 
similar to the constraints in terms of what matches is generally preferred.

That's an overarching goal in how we want to write patterns these days. 
  It lessens the reliance on reload for producing proper code and 
ultimately that tends to result in better performing code as well.  This 
can be added as a follow-up if you wish.


> @@ -416,24 +424,29 @@ gen-function.  The subexpressions of argument 3 are not used;
>   only its expression code matters.
>
>   When @code{match_operator} is used in a pattern for matching an insn,
> -it usually best if the operand number of the @code{match_operator}
> -is higher than that of the actual operands of the insn.  This improves
> -register allocation because the register allocator often looks at
> -operands 1 and 2 of insns to see if it can do register tying.
> -
> -There is no way to specify constraints in @code{match_operator}.  The
> -operand of the insn which corresponds to the @code{match_operator}
> -never has any constraints because it is never reloaded as a whole.
> -However, if parts of its @var{operands} are matched by
> -@code{match_operand} patterns, those parts may have constraints of
> -their own.
> +it is usually best if the operand number of the @code{match_operator}
> +is higher than that of the actual operands of the insn.  This can
> +improve register allocation because the register allocator often
> +looks at operands 1 and 2 of insns to see if they are suitable
> +for register tying.
Gak.  I don't think the allocator cares anymore about the specific 
operand numbering.  I really wonder if we should just remove that stuff.

I think the only part that needs another iteration is the change where I 
briefly thought you were referring to insn conditions rather than 
operand predicates.  THe rest is either OK as-is (where I didn't 
comment) or after making the trivial changes.

Re: [Patch docs 3/5] Update "RTL Template" in md.texi

[Richard Sandiford]

Thanks for tackling this.

[Sorry, just realised Jeff is going through this ATM too, so sorry for
any dups]

I think Sandra and probably others prefer to avoid an explicit future
tense, e.g. "X is substituted" rather than "X will be substituted".

James Greenhalgh <james.greenhalgh@arm.com> writes:
> @@ -286,15 +284,15 @@ used only in @code{match_dup} expressions have higher values than all
>  other operand numbers.
>  
>  @var{predicate} is a string that is the name of a function that
> -accepts two arguments, an expression and a machine mode.
> -@xref{Predicates}.  During matching, the function will be called with
> -the putative operand as the expression and @var{m} as the mode
> -argument (if @var{m} is not specified, @code{VOIDmode} will be used,
> +accepts two arguments, an expression and a machine mode
> +(@pxref{Predicates}).  During matching, the function will be called
> +with the operand as the expression and @var{m} as the mode
> +argument (if @var{m} is not specified, then @code{VOIDmode} will be used,
>  which normally causes @var{predicate} to accept any mode).  If it
>  returns zero, this instruction pattern fails to match.
> -@var{predicate} may be an empty string; then it means no test is to be
> -done on the operand, so anything which occurs in this position is
> -valid.
> +
> +@var{predicate} may be an empty string.  This represents a predicate for
> +which any operand will be considered valid.

In some ways I think the original version is more accurate.
Something like (match_operand:BLK 1 "") doesn't test anything;
the :BLK is ignored.

> @@ -302,80 +300,89 @@ not always.  For example, the predicate @code{address_operand} uses
>  Many predicates accept @code{const_int} nodes even though their mode is
>  @code{VOIDmode}.
>  
> -@var{constraint} controls reloading and the choice of the best register
> -class to use for a value, as explained later (@pxref{Constraints}).
> -If the constraint would be an empty string, it can be omitted.
> -
> -People are often unclear on the difference between the constraint and the
> -predicate.  The predicate helps decide whether a given insn matches the
> -pattern.  The constraint plays no role in this decision; instead, it
> -controls various decisions in the case of an insn which does match.
> +@var{constraint} controls the best register class to use for a value,
> +and therefore register allocation and reloading, as explained
> +later (@pxref{Constraints}).  If the constraint would be an empty
> +string, it can be omitted.
> +
> +In summary, the predicate is used to control whether the instruction
> +pattern is a valid match for an insn.  The constraint is used to control
> +register allocation decisions in the case of an instruction pattern which
> +has already been matched to an insn.
> +
> +It is an error for the contraints of an operand to be impossible to fulfil
> +for operands which are valid for the predicate of the operand.  Formally;
> +for all operands for which the predicate would be true, there must exist
> +at least one valid register class for that operand.

This could be a bit misleading.  For memories it's sufficient to provide
a suitably general memory constraint (i.e. one that accepts at least
(mem (reg))).  The constraints don't also need to specify a register class
for the operand.

>  Note that this
> +restriction does not forbid accepting operands which will need additional
> +handling to move them to a valid register class.  This restriction would,
> +however, prevent combining a constraint set requiring the use of an
> +immediate value with a predicate allowing any operand, as it is not
> +possible to convert all operand types to immediate values.

The other way is also important, and in some ways easier to describe:
it is invalid for a constraint to accept something that the predicate
doesn't.  I think it might be worth saying that first.

>  @findex match_scratch
>  @item (match_scratch:@var{m} @var{n} @var{constraint})
> -This expression is also a placeholder for operand number @var{n}
> -and indicates that operand must be a @code{scratch} or @code{reg}
> +This expression is a placeholder for operand number @var{n}
> +and indicates that the operand must be a @code{scratch} or @code{reg}
>  expression.
>  
> -When matching patterns, this is equivalent to
> +When matching instruction patterns, this is equivalent to:
>  
>  @smallexample
> -(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
> +(match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
>  @end smallexample

The original was correct here.  The string is a constraint rather
than a predicate.

> -When matching an expression, it matches an expression if the function
> -@var{predicate} returns nonzero on that expression @emph{and} the
> -patterns @var{operands} match the operands of the expression.
> +When matching an insn, it matches if @var{predicate} returns nonzero for
> +the expression code @emph{and} the @var{operands} of the expression are
> +valid for the instruction pattern.

"expression" rather than "expression code" was correct here.
The predicate gets passed the rtx corresponding to operand n
and is allowed to examine its operands as well as its code.

> -Suppose that the function @code{commutative_operator} is defined as
> -follows, to match any expression whose operator is one of the
> -commutative arithmetic operators of RTL and whose mode is @var{mode}:
> +In this example, the function @code{commutative_operator} is defined to
> +match any expression whose operator is one of the commutative arithmetic
> +operators of RTL and whose mode is @var{mode}:
>  
>  @smallexample
>  int
> -commutative_integer_operator (x, mode)
> -     rtx x;
> -     machine_mode mode;
> +commutative_integer_operator (rtx x, machine_mode mode)
>  @{
>    enum rtx_code code = GET_CODE (x);
>    if (GET_MODE (x) != mode)

Sorry for the mission creep, but while you're there, it'd be good
to make the example use define_predicate instead.

> @@ -416,24 +424,29 @@ gen-function.  The subexpressions of argument 3 are not used;
>  only its expression code matters.
>  
>  When @code{match_operator} is used in a pattern for matching an insn,
> -it usually best if the operand number of the @code{match_operator}
> -is higher than that of the actual operands of the insn.  This improves
> -register allocation because the register allocator often looks at
> -operands 1 and 2 of insns to see if it can do register tying.
> -
> -There is no way to specify constraints in @code{match_operator}.  The
> -operand of the insn which corresponds to the @code{match_operator}
> -never has any constraints because it is never reloaded as a whole.
> -However, if parts of its @var{operands} are matched by
> -@code{match_operand} patterns, those parts may have constraints of
> -their own.
> +it is usually best if the operand number of the @code{match_operator}
> +is higher than that of the actual operands of the insn.  This can
> +improve register allocation because the register allocator often
> +looks at operands 1 and 2 of insns to see if they are suitable
> +for register tying.

I think we can drop this bit.  It doesn't apply to either IRA or LRA
as far as I know.

Thanks,
Richard

Re: [Patch docs 4/5] Update "Output Template/Statement" from md.texi

[Richard Sandiford]

James Greenhalgh <james.greenhalgh@arm.com> writes:
>  If the output control string starts with a @samp{@@}, then it is actually
>  a series of templates, each on a separate line.  (Blank lines and
>  leading spaces and tabs are ignored.)  The templates correspond to the
> -pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
> -if a target machine has a two-address add instruction @samp{addr} to add
> -into a register and another @samp{addm} to add a register to memory, you
> -might write this pattern:
> +pattern's constraint alternatives (@pxref{Multi-Alternative}).
> +
> +For example, if a target machine has a two-address add instruction
> +@samp{addreg} to add into a register and another @samp{addmem} to add
> +a register to memory, this pattern could be used to describe the
> +instructions.
>  
>  @smallexample
>  (define_insn "addsi3"
>    [(set (match_operand:SI 0 "general_operand" "=r,m")
>          (plus:SI (match_operand:SI 1 "general_operand" "0,0")
> -                 (match_operand:SI 2 "general_operand" "g,r")))]
> +                 (match_operand:SI 2 "general_operand" "r,r")))]
>    ""
>    "@@
> -   addr %2,%0
> -   addm %2,%0")
> +   addreg %2,%0
> +   addmem %2,%0")
>  @end smallexample

While there, I think we should tighten the predicates to
nonimmediate_operand for operands 0 and 1 and -- given the
new constraints -- register_operand for operand 2.

Thanks,
Richard

Re: [Patch docs 1/5] Update the first section of md.texi

[Richard Sandiford]

James Greenhalgh <james.greenhalgh@arm.com> writes:
> -For the generate pass, only the names of the insns matter, from either a
> -named @code{define_insn} or a @code{define_expand}.  The compiler will
> +When expanding from gimple to RTL, only named @code{define_insn}
> +constructs and @code{define_expand} constructs are used.  The compiler will
>  choose the pattern with the right name and apply the operands according
>  to the documentation later in this chapter, without regard for the RTL
> -template or operand constraints.  Note that the names the compiler looks
> -for are hard-coded in the compiler---it will ignore unnamed patterns and
> -patterns with names it doesn't know about, but if you don't provide a
> -named pattern it needs, it will abort.
> +template or operand constraints.  Note that the names which are used for
> +expansion are hard-coded in the compiler---unnamed patterns and patterns
> +with names which do not have a standard meaning are ignored during
> +expansion.  If you don't provide a named pattern that the compiler is
> +trying to expand, it may try a different expansion strategy.  If no
> +other expansion strategies are possible, the compiler will abort.

Minor nit, I think both "which"es here should be "that"s.

>  If a @code{define_insn} is used, the template given is inserted into the
> -insn list.  If a @code{define_expand} is used, one of three things
> -happens, based on the condition logic.  The condition logic may manually
> -create new insns for the insn list, say via @code{emit_insn()}, and
> -invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
> -compiler to use an alternate way of performing that task.  If it invokes
> -neither @code{DONE} nor @code{FAIL}, the template given in the pattern
> +insn list.
> +
> +If a @code{define_expand} is used, one of three things happens, encoded in
> +the condition logic.  The condition logic may manually create new insns
> +for the insn list, say via @code{emit_insn ()}, and invoke @code{DONE},
> +indicating a successful expansion.  If the standard pattern name permits
> +it, the condition logic may invoke @code{FAIL} to express that an alternate
> +strategy should be used to performing the expansion.  If the condition logic
> +invokes neither @code{DONE} nor @code{FAIL}, the template given in the pattern

Can we s/alternate/alternative/ at the same time?  I think "alternative"
is still correct in US English.

s/to performing/to perform/.

Thanks,
Richard

Re: [Patch docs 2/5] Update "Instruction Patterns" in md.texi

[Richard Sandiford]

James Greenhalgh <james.greenhalgh@arm.com> writes:
>  @node Example
>  @section Example of @code{define_insn}
>  @cindex @code{define_insn} example
>  
> -Here is an actual example of an instruction pattern, for the 68000/68020.
> +Here is an example of an instruction pattern, taken from the machine
> +description for the 68000/68020.
>  
>  @smallexample
>  (define_insn "tstsi"

Might be mission creep again, but: tstsi is no longer a named pattern.
Maybe we should put something more modern in there...

Thanks,
Richard

Re: [Patch docs 5/5] Update "Predicates" from md.texi

[Richard Sandiford]

James Greenhalgh <james.greenhalgh@arm.com> writes:
> @@ -794,25 +805,25 @@ diagnosis when special predicates are used.
>  
>  These are the generic predicates available to all back ends.  They are
>  defined in @file{recog.c}.  The first category of predicates allow
> -only constant, or @dfn{immediate}, operands.
> +only constant, or @dfn{immediate}, operands and are normal predicates.
>  
>  @defun immediate_operand
>  This predicate allows any sort of constant that fits in @var{mode}.
> -It is an appropriate choice for instructions that take operands that
> -must be constant.
> +It is an appropriate choice for operands to an instruction which requires
> +a constant.
>  @end defun

Maybe it's just me, but I find this quite hard to parse.  How about
"for operands that accept any legitimate constant" (with a reference
to TARGET_LEGITIMATE_CONSTANT_P)?

> @@ -857,15 +871,15 @@ it should not be used directly.
>  The third category of predicates allow only some kind of memory reference.
>  
>  @defun memory_operand
> -This predicate allows any valid reference to a quantity of mode
> +This predicate allows any valid reference to an objects of mode
>  @var{mode} in memory, as determined by the weak form of
>  @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
>  @end defun

s/an objects/an object/

Thanks,
Richard