From: James Greenhalgh <james.greenhalgh@arm.com>
To: gcc-patches@gcc.gnu.org
Cc: gerald@pfeifer.com, joseph@codesourcery.com
Subject: [Patch docs 4/5] Update "Output Template/Statement" from md.texi
Date: Tue, 06 Jan 2015 11:22:00 -0000 [thread overview]
Message-ID: <1420543302-11008-5-git-send-email-james.greenhalgh@arm.com> (raw)
In-Reply-To: <1420543302-11008-1-git-send-email-james.greenhalgh@arm.com>
[-- 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
next prev parent reply other threads:[~2015-01-06 11:22 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-01-06 11:21 [Patch docs 0/5] Update some of md.texi James Greenhalgh
2015-01-06 11:22 ` [Patch docs 2/5] Update "Instruction Patterns" in md.texi James Greenhalgh
2015-01-08 22:00 ` Jeff Law
2015-01-09 2:19 ` Segher Boessenkool
2015-01-11 17:40 ` James Greenhalgh
2015-01-12 22:31 ` Richard Sandiford
2015-01-06 11:22 ` [Patch docs 3/5] Update "RTL Template" " James Greenhalgh
2015-01-12 22:04 ` Jeff Law
2015-01-12 22:11 ` Richard Sandiford
2015-01-06 11:22 ` [Patch docs 1/5] Update the first section of md.texi James Greenhalgh
2015-01-06 16:56 ` James Greenhalgh
2015-01-06 18:55 ` Joseph Myers
2015-01-08 21:43 ` Jeff Law
2015-01-09 2:11 ` Segher Boessenkool
2015-01-12 22:29 ` Richard Sandiford
2015-01-06 11:22 ` James Greenhalgh [this message]
2015-01-12 21:46 ` [Patch docs 4/5] Update "Output Template/Statement" from md.texi Jeff Law
2015-01-12 22:19 ` Richard Sandiford
2015-01-06 11:23 ` [Patch docs 5/5] Update "Predicates" " James Greenhalgh
2015-01-12 22:42 ` Richard Sandiford
2015-01-06 14:57 ` [Patch docs 0/5] Update some of md.texi Joseph Myers
2015-01-06 15:26 ` James Greenhalgh
2015-01-06 17:31 ` Sandra Loosemore
2015-01-06 18:46 ` Joseph Myers
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1420543302-11008-5-git-send-email-james.greenhalgh@arm.com \
--to=james.greenhalgh@arm.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=gerald@pfeifer.com \
--cc=joseph@codesourcery.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).