From patchwork Tue Jan 6 11:21:38 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: James Greenhalgh X-Patchwork-Id: 425624 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id A9B381400DE for ; Tue, 6 Jan 2015 22:22:27 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-type; q=dns; s=default; b=r99Ye4SbniOjYg9c Vqu+SzahQlPxrz2tRGxrmva+UNC51OlgxWbg8gTK8qecBiOflEYrmBs2Mj5ElL0o 2P/XeLEjRCrWtuVyMltZR3V1fpUts7S2SEQ832Slsl+ECSQZgBZk3qvvQ47x/m+B Wk4jokw54EHNgsH9AMPAComU2P4= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-type; s=default; bh=esyhxIBie68XlV0fXrN5Zb HIyIQ=; b=LdcCiW38j5Spu0jQJQjqjtSPx/Vlm+KLQyVbYMScdB1pdSQfeasPyc RfN2X2IgG4UTpW8v2vW3sf1ENckjO1spAhrhyZv780utl0DuhthURXLFhxGzaXn/ 3cLumAWYQXvl4xXrScQwUby233+3YHuUmHctMixBFVJUqb7c/za9Y= Received: (qmail 31502 invoked by alias); 6 Jan 2015 11:22:20 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 31487 invoked by uid 89); 6 Jan 2015 11:22:18 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.6 required=5.0 tests=AWL, BAYES_00, MEDICAL_SUBJECT, SPF_PASS autolearn=no version=3.3.2 X-HELO: service87.mimecast.com Received: from service87.mimecast.com (HELO service87.mimecast.com) (91.220.42.44) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 06 Jan 2015 11:22:16 +0000 Received: from cam-owa2.Emea.Arm.com (fw-tnat.cambridge.arm.com [217.140.96.140]) by service87.mimecast.com; Tue, 06 Jan 2015 11:22:14 +0000 Received: from e106375-lin.cambridge.arm.com ([10.1.255.212]) by cam-owa2.Emea.Arm.com with Microsoft SMTPSVC(6.0.3790.3959); Tue, 6 Jan 2015 11:22:13 +0000 From: James Greenhalgh To: gcc-patches@gcc.gnu.org Cc: gerald@pfeifer.com, joseph@codesourcery.com Subject: [Patch docs 1/5] Update the first section of md.texi Date: Tue, 6 Jan 2015 11:21:38 +0000 Message-Id: <1420543302-11008-2-git-send-email-james.greenhalgh@arm.com> In-Reply-To: <1420543302-11008-1-git-send-email-james.greenhalgh@arm.com> References: <1420543302-11008-1-git-send-email-james.greenhalgh@arm.com> MIME-Version: 1.0 X-MC-Unique: 115010611221401301 X-IsSubscribed: yes 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 * 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