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