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.greenha...@arm.com>
* doc/md.texi (Machine Descriptions): Update text.
(menu): Likewise.
(Overview): Likewise.
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
