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