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

[Jeff Law <law@redhat.com>]

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