Merge branch 'master' of ssh://
[dragonfly.git] / contrib / gcc-3.4 / gcc / doc / md.texi
1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
2@c 2002, 2003, 2004 Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
7@node Machine Desc
8@chapter Machine Descriptions
9@cindex machine descriptions
11A machine description has two parts: a file of instruction patterns
12(@file{.md} file) and a C header file of macro definitions.
14The @file{.md} file for a target machine contains a pattern for each
15instruction that the target machine supports (or at least each instruction
16that is worth telling the compiler about). It may also contain comments.
17A semicolon causes the rest of the line to be a comment, unless the semicolon
18is inside a quoted string.
20See the next chapter for information on the C header file.
23* Overview:: How the machine description is used.
24* Patterns:: How to write instruction patterns.
25* Example:: An explained example of a @code{define_insn} pattern.
26* RTL Template:: The RTL template defines what insns match a pattern.
27* Output Template:: The output template says how to make assembler code
28 from such an insn.
29* Output Statement:: For more generality, write C code to output
30 the assembler code.
31* Constraints:: When not all operands are general operands.
32* Standard Names:: Names mark patterns to use for code generation.
33* Pattern Ordering:: When the order of patterns makes a difference.
34* Dependent Patterns:: Having one pattern may make you need another.
35* Jump Patterns:: Special considerations for patterns for jump insns.
36* Looping Patterns:: How to define patterns for special looping insns.
37* Insn Canonicalizations::Canonicalization of Instructions
38* Expander Definitions::Generating a sequence of several RTL insns
39 for a standard operation.
40* Insn Splitting:: Splitting Instructions into Multiple Instructions.
41* Including Patterns:: Including Patterns in Machine Descriptions.
42* Peephole Definitions::Defining machine-specific peephole optimizations.
43* Insn Attributes:: Specifying the value of attributes for generated insns.
44* Conditional Execution::Generating @code{define_insn} patterns for
45 predication.
46* Constant Definitions::Defining symbolic constants that can be used in the
47 md file.
48@end menu
50@node Overview
51@section Overview of How the Machine Description is Used
53There are three main conversions that happen in the compiler:
58The front end reads the source code and builds a parse tree.
61The parse tree is used to generate an RTL insn list based on named
62instruction patterns.
65The insn list is matched against the RTL templates to produce assembler
68@end enumerate
70For the generate pass, only the names of the insns matter, from either a
71named @code{define_insn} or a @code{define_expand}. The compiler will
72choose the pattern with the right name and apply the operands according
73to the documentation later in this chapter, without regard for the RTL
74template or operand constraints. Note that the names the compiler looks
75for are hard-coded in the compiler---it will ignore unnamed patterns and
76patterns with names it doesn't know about, but if you don't provide a
77named pattern it needs, it will abort.
79If a @code{define_insn} is used, the template given is inserted into the
80insn list. If a @code{define_expand} is used, one of three things
81happens, based on the condition logic. The condition logic may manually
82create new insns for the insn list, say via @code{emit_insn()}, and
83invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the
84compiler to use an alternate way of performing that task. If it invokes
85neither @code{DONE} nor @code{FAIL}, the template given in the pattern
86is inserted, as if the @code{define_expand} were a @code{define_insn}.
88Once the insn list is generated, various optimization passes convert,
89replace, and rearrange the insns in the insn list. This is where the
90@code{define_split} and @code{define_peephole} patterns get used, for
93Finally, the insn list's RTL is matched up with the RTL templates in the
94@code{define_insn} patterns, and those patterns are used to emit the
95final assembly code. For this purpose, each named @code{define_insn}
96acts like it's unnamed, since the names are ignored.
98@node Patterns
99@section Everything about Instruction Patterns
100@cindex patterns
101@cindex instruction patterns
103@findex define_insn
104Each instruction pattern contains an incomplete RTL expression, with pieces
105to be filled in later, operand constraints that restrict how the pieces can
106be filled in, and an output pattern or C code to generate the assembler
107output, all wrapped up in a @code{define_insn} expression.
109A @code{define_insn} is an RTL expression containing four or five operands:
113An optional name. The presence of a name indicate that this instruction
114pattern can perform a certain standard job for the RTL-generation
115pass of the compiler. This pass knows certain names and will use
116the instruction patterns with those names, if the names are defined
117in the machine description.
119The absence of a name is indicated by writing an empty string
120where the name should go. Nameless instruction patterns are never
121used for generating RTL code, but they may permit several simpler insns
122to be combined later on.
124Names that are not thus known and used in RTL-generation have no
125effect; they are equivalent to no name at all.
127For the purpose of debugging the compiler, you may also specify a
128name beginning with the @samp{*} character. Such a name is used only
129for identifying the instruction in RTL dumps; it is entirely equivalent
130to having a nameless pattern for all other purposes.
133The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
134RTL expressions which show what the instruction should look like. It is
135incomplete because it may contain @code{match_operand},
136@code{match_operator}, and @code{match_dup} expressions that stand for
137operands of the instruction.
139If the vector has only one element, that element is the template for the
140instruction pattern. If the vector has multiple elements, then the
141instruction pattern is a @code{parallel} expression containing the
142elements described.
145@cindex pattern conditions
146@cindex conditions, in patterns
147A condition. This is a string which contains a C expression that is
148the final test to decide whether an insn body matches this pattern.
150@cindex named patterns and conditions
151For a named pattern, the condition (if present) may not depend on
152the data in the insn being matched, but only the target-machine-type
153flags. The compiler needs to test these conditions during
154initialization in order to learn exactly which named instructions are
155available in a particular run.
157@findex operands
158For nameless patterns, the condition is applied only when matching an
159individual insn, and only after the insn has matched the pattern's
160recognition template. The insn's operands may be found in the vector
161@code{operands}. For an insn where the condition has once matched, it
162can't be used to control register allocation, for example by excluding
163certain hard registers or hard register combinations.
166The @dfn{output template}: a string that says how to output matching
167insns as assembler code. @samp{%} in this string specifies where
168to substitute the value of an operand. @xref{Output Template}.
170When simple substitution isn't general enough, you can specify a piece
171of C code to compute the output. @xref{Output Statement}.
174Optionally, a vector containing the values of attributes for insns matching
175this pattern. @xref{Insn Attributes}.
176@end enumerate
178@node Example
179@section Example of @code{define_insn}
180@cindex @code{define_insn} example
182Here is an actual example of an instruction pattern, for the 68000/68020.
185(define_insn "tstsi"
186 [(set (cc0)
187 (match_operand:SI 0 "general_operand" "rm"))]
188 ""
189 "*
191 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
192 return \"tstl %0\";
193 return \"cmpl #0,%0\";
195@end smallexample
198This can also be written using braced strings:
201(define_insn "tstsi"
202 [(set (cc0)
203 (match_operand:SI 0 "general_operand" "rm"))]
204 ""
206 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
207 return "tstl %0";
208 return "cmpl #0,%0";
210@end smallexample
212This is an instruction that sets the condition codes based on the value of
213a general operand. It has no condition, so any insn whose RTL description
214has the form shown may be handled according to this pattern. The name
215@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
216pass that, when it is necessary to test such a value, an insn to do so
217can be constructed using this pattern.
219The output control string is a piece of C code which chooses which
220output template to return based on the kind of operand and the specific
221type of CPU for which code is being generated.
223@samp{"rm"} is an operand constraint. Its meaning is explained below.
225@node RTL Template
226@section RTL Template
227@cindex RTL insn template
228@cindex generating insns
229@cindex insns, generating
230@cindex recognizing insns
231@cindex insns, recognizing
233The RTL template is used to define which insns match the particular pattern
234and how to find their operands. For named patterns, the RTL template also
235says how to construct an insn from specified operands.
237Construction involves substituting specified operands into a copy of the
238template. Matching involves determining the values that serve as the
239operands in the insn being matched. Both of these activities are
240controlled by special expression types that direct matching and
241substitution of the operands.
243@table @code
244@findex match_operand
245@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
246This expression is a placeholder for operand number @var{n} of
247the insn. When constructing an insn, operand number @var{n}
248will be substituted at this point. When matching an insn, whatever
249appears at this position in the insn will be taken as operand
250number @var{n}; but it must satisfy @var{predicate} or this instruction
251pattern will not match at all.
253Operand numbers must be chosen consecutively counting from zero in
254each instruction pattern. There may be only one @code{match_operand}
255expression in the pattern for each operand number. Usually operands
256are numbered in the order of appearance in @code{match_operand}
257expressions. In the case of a @code{define_expand}, any operand numbers
258used only in @code{match_dup} expressions have higher values than all
259other operand numbers.
261@var{predicate} is a string that is the name of a C function that accepts two
262arguments, an expression and a machine mode. During matching, the
263function will be called with the putative operand as the expression and
264@var{m} as the mode argument (if @var{m} is not specified,
265@code{VOIDmode} will be used, which normally causes @var{predicate} to accept
266any mode). If it returns zero, this instruction pattern fails to match.
267@var{predicate} may be an empty string; then it means no test is to be done
268on the operand, so anything which occurs in this position is valid.
270Most of the time, @var{predicate} will reject modes other than @var{m}---but
271not always. For example, the predicate @code{address_operand} uses
272@var{m} as the mode of memory ref that the address should be valid for.
273Many predicates accept @code{const_int} nodes even though their mode is
276@var{constraint} controls reloading and the choice of the best register
277class to use for a value, as explained later (@pxref{Constraints}).
279People are often unclear on the difference between the constraint and the
280predicate. The predicate helps decide whether a given insn matches the
281pattern. The constraint plays no role in this decision; instead, it
282controls various decisions in the case of an insn which does match.
284@findex general_operand
285On CISC machines, the most common @var{predicate} is
286@code{"general_operand"}. This function checks that the putative
287operand is either a constant, a register or a memory reference, and that
288it is valid for mode @var{m}.
290@findex register_operand
291For an operand that must be a register, @var{predicate} should be
292@code{"register_operand"}. Using @code{"general_operand"} would be
293valid, since the reload pass would copy any non-register operands
294through registers, but this would make GCC do extra work, it would
295prevent invariant operands (such as constant) from being removed from
296loops, and it would prevent the register allocator from doing the best
297possible job. On RISC machines, it is usually most efficient to allow
298@var{predicate} to accept only objects that the constraints allow.
300@findex immediate_operand
301For an operand that must be a constant, you must be sure to either use
302@code{"immediate_operand"} for @var{predicate}, or make the instruction
303pattern's extra condition require a constant, or both. You cannot
304expect the constraints to do this work! If the constraints allow only
305constants, but the predicate allows something else, the compiler will
306crash when that case arises.
308@findex match_scratch
309@item (match_scratch:@var{m} @var{n} @var{constraint})
310This expression is also a placeholder for operand number @var{n}
311and indicates that operand must be a @code{scratch} or @code{reg}
314When matching patterns, this is equivalent to
317(match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
318@end smallexample
320but, when generating RTL, it produces a (@code{scratch}:@var{m})
323If the last few expressions in a @code{parallel} are @code{clobber}
324expressions whose operands are either a hard register or
325@code{match_scratch}, the combiner can add or delete them when
326necessary. @xref{Side Effects}.
328@findex match_dup
329@item (match_dup @var{n})
330This expression is also a placeholder for operand number @var{n}.
331It is used when the operand needs to appear more than once in the
334In construction, @code{match_dup} acts just like @code{match_operand}:
335the operand is substituted into the insn being constructed. But in
336matching, @code{match_dup} behaves differently. It assumes that operand
337number @var{n} has already been determined by a @code{match_operand}
338appearing earlier in the recognition template, and it matches only an
339identical-looking expression.
341Note that @code{match_dup} should not be used to tell the compiler that
342a particular register is being used for two operands (example:
343@code{add} that adds one register to another; the second register is
344both an input operand and the output operand). Use a matching
345constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one
346operand is used in two places in the template, such as an instruction
347that computes both a quotient and a remainder, where the opcode takes
348two input operands but the RTL template has to refer to each of those
349twice; once for the quotient pattern and once for the remainder pattern.
351@findex match_operator
352@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
353This pattern is a kind of placeholder for a variable RTL expression
356When constructing an insn, it stands for an RTL expression whose
357expression code is taken from that of operand @var{n}, and whose
358operands are constructed from the patterns @var{operands}.
360When matching an expression, it matches an expression if the function
361@var{predicate} returns nonzero on that expression @emph{and} the
362patterns @var{operands} match the operands of the expression.
364Suppose that the function @code{commutative_operator} is defined as
365follows, to match any expression whose operator is one of the
366commutative arithmetic operators of RTL and whose mode is @var{mode}:
370commutative_operator (x, mode)
371 rtx x;
372 enum machine_mode mode;
374 enum rtx_code code = GET_CODE (x);
375 if (GET_MODE (x) != mode)
376 return 0;
377 return (GET_RTX_CLASS (code) == 'c'
378 || code == EQ || code == NE);
380@end smallexample
382Then the following pattern will match any RTL expression consisting
383of a commutative operator applied to two general operands:
386(match_operator:SI 3 "commutative_operator"
387 [(match_operand:SI 1 "general_operand" "g")
388 (match_operand:SI 2 "general_operand" "g")])
389@end smallexample
391Here the vector @code{[@var{operands}@dots{}]} contains two patterns
392because the expressions to be matched all contain two operands.
394When this pattern does match, the two operands of the commutative
395operator are recorded as operands 1 and 2 of the insn. (This is done
396by the two instances of @code{match_operand}.) Operand 3 of the insn
397will be the entire commutative expression: use @code{GET_CODE
398(operands[3])} to see which commutative operator was used.
400The machine mode @var{m} of @code{match_operator} works like that of
401@code{match_operand}: it is passed as the second argument to the
402predicate function, and that function is solely responsible for
403deciding whether the expression to be matched ``has'' that mode.
405When constructing an insn, argument 3 of the gen-function will specify
406the operation (i.e.@: the expression code) for the expression to be
407made. It should be an RTL expression, whose expression code is copied
408into a new expression whose operands are arguments 1 and 2 of the
409gen-function. The subexpressions of argument 3 are not used;
410only its expression code matters.
412When @code{match_operator} is used in a pattern for matching an insn,
413it usually best if the operand number of the @code{match_operator}
414is higher than that of the actual operands of the insn. This improves
415register allocation because the register allocator often looks at
416operands 1 and 2 of insns to see if it can do register tying.
418There is no way to specify constraints in @code{match_operator}. The
419operand of the insn which corresponds to the @code{match_operator}
420never has any constraints because it is never reloaded as a whole.
421However, if parts of its @var{operands} are matched by
422@code{match_operand} patterns, those parts may have constraints of
423their own.
425@findex match_op_dup
426@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
427Like @code{match_dup}, except that it applies to operators instead of
428operands. When constructing an insn, operand number @var{n} will be
429substituted at this point. But in matching, @code{match_op_dup} behaves
430differently. It assumes that operand number @var{n} has already been
431determined by a @code{match_operator} appearing earlier in the
432recognition template, and it matches only an identical-looking
435@findex match_parallel
436@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
437This pattern is a placeholder for an insn that consists of a
438@code{parallel} expression with a variable number of elements. This
439expression should only appear at the top level of an insn pattern.
441When constructing an insn, operand number @var{n} will be substituted at
442this point. When matching an insn, it matches if the body of the insn
443is a @code{parallel} expression with at least as many elements as the
444vector of @var{subpat} expressions in the @code{match_parallel}, if each
445@var{subpat} matches the corresponding element of the @code{parallel},
446@emph{and} the function @var{predicate} returns nonzero on the
447@code{parallel} that is the body of the insn. It is the responsibility
448of the predicate to validate elements of the @code{parallel} beyond
449those listed in the @code{match_parallel}.
451A typical use of @code{match_parallel} is to match load and store
452multiple expressions, which can contain a variable number of elements
453in a @code{parallel}. For example,
456(define_insn ""
457 [(match_parallel 0 "load_multiple_operation"
458 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
459 (match_operand:SI 2 "memory_operand" "m"))
460 (use (reg:SI 179))
461 (clobber (reg:SI 179))])]
462 ""
463 "loadm 0,0,%1,%2")
464@end smallexample
466This example comes from @file{}. The function
467@code{load_multiple_operation} is defined in @file{a29k.c} and checks
468that subsequent elements in the @code{parallel} are the same as the
469@code{set} in the pattern, except that they are referencing subsequent
470registers and memory locations.
472An insn that matches this pattern might look like:
476 [(set (reg:SI 20) (mem:SI (reg:SI 100)))
477 (use (reg:SI 179))
478 (clobber (reg:SI 179))
479 (set (reg:SI 21)
480 (mem:SI (plus:SI (reg:SI 100)
481 (const_int 4))))
482 (set (reg:SI 22)
483 (mem:SI (plus:SI (reg:SI 100)
484 (const_int 8))))])
485@end smallexample
487@findex match_par_dup
488@item (match_par_dup @var{n} [@var{subpat}@dots{}])
489Like @code{match_op_dup}, but for @code{match_parallel} instead of
492@findex match_insn
493@item (match_insn @var{predicate})
494Match a complete insn. Unlike the other @code{match_*} recognizers,
495@code{match_insn} does not take an operand number.
497The machine mode @var{m} of @code{match_insn} works like that of
498@code{match_operand}: it is passed as the second argument to the
499predicate function, and that function is solely responsible for
500deciding whether the expression to be matched ``has'' that mode.
502@findex match_insn2
503@item (match_insn2 @var{n} @var{predicate})
504Match a complete insn.
506The machine mode @var{m} of @code{match_insn2} works like that of
507@code{match_operand}: it is passed as the second argument to the
508predicate function, and that function is solely responsible for
509deciding whether the expression to be matched ``has'' that mode.
511@end table
513@node Output Template
514@section Output Templates and Operand Substitution
515@cindex output templates
516@cindex operand substitution
518@cindex @samp{%} in template
519@cindex percent sign
520The @dfn{output template} is a string which specifies how to output the
521assembler code for an instruction pattern. Most of the template is a
522fixed string which is output literally. The character @samp{%} is used
523to specify where to substitute an operand; it can also be used to
524identify places where different variants of the assembler require
525different syntax.
527In the simplest case, a @samp{%} followed by a digit @var{n} says to output
528operand @var{n} at that point in the string.
530@samp{%} followed by a letter and a digit says to output an operand in an
531alternate fashion. Four letters have standard, built-in meanings described
532below. The machine description macro @code{PRINT_OPERAND} can define
533additional letters with nonstandard meanings.
535@samp{%c@var{digit}} can be used to substitute an operand that is a
536constant value without the syntax that normally indicates an immediate
539@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
540the constant is negated before printing.
542@samp{%a@var{digit}} can be used to substitute an operand as if it were a
543memory reference, with the actual operand treated as the address. This may
544be useful when outputting a ``load address'' instruction, because often the
545assembler syntax for such an instruction requires you to write the operand
546as if it were a memory reference.
548@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
551@samp{%=} outputs a number which is unique to each instruction in the
552entire compilation. This is useful for making local labels to be
553referred to more than once in a single template that generates multiple
554assembler instructions.
556@samp{%} followed by a punctuation character specifies a substitution that
557does not use an operand. Only one case is standard: @samp{%%} outputs a
558@samp{%} into the assembler code. Other nonstandard cases can be
559defined in the @code{PRINT_OPERAND} macro. You must also define
560which punctuation characters are valid with the
563@cindex \
564@cindex backslash
565The template may generate multiple assembler instructions. Write the text
566for the instructions, with @samp{\;} between them.
568@cindex matching operands
569When the RTL contains two operands which are required by constraint to match
570each other, the output template must refer only to the lower-numbered operand.
571Matching operands are not always identical, and the rest of the compiler
572arranges to put the proper RTL expression for printing into the lower-numbered
575One use of nonstandard letters or punctuation following @samp{%} is to
576distinguish between different assembler languages for the same machine; for
577example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
578requires periods in most opcode names, while MIT syntax does not. For
579example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
580syntax. The same file of patterns is used for both kinds of output syntax,
581but the character sequence @samp{%.} is used in each place where Motorola
582syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
583defines the sequence to output a period; the macro for MIT syntax defines
584it to do nothing.
586@cindex @code{#} in template
587As a special case, a template consisting of the single character @code{#}
588instructs the compiler to first split the insn, and then output the
589resulting instructions separately. This helps eliminate redundancy in the
590output templates. If you have a @code{define_insn} that needs to emit
591multiple assembler instructions, and there is an matching @code{define_split}
592already defined, then you can simply use @code{#} as the output template
593instead of writing an output template that emits the multiple assembler
596If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
597of the form @samp{@{option0|option1|option2@}} in the templates. These
598describe multiple variants of assembler language syntax.
599@xref{Instruction Output}.
601@node Output Statement
602@section C Statements for Assembler Output
603@cindex output statements
604@cindex C statements for assembler output
605@cindex generating assembler output
607Often a single fixed template string cannot produce correct and efficient
608assembler code for all the cases that are recognized by a single
609instruction pattern. For example, the opcodes may depend on the kinds of
610operands; or some unfortunate combinations of operands may require extra
611machine instructions.
613If the output control string starts with a @samp{@@}, then it is actually
614a series of templates, each on a separate line. (Blank lines and
615leading spaces and tabs are ignored.) The templates correspond to the
616pattern's constraint alternatives (@pxref{Multi-Alternative}). For example,
617if a target machine has a two-address add instruction @samp{addr} to add
618into a register and another @samp{addm} to add a register to memory, you
619might write this pattern:
622(define_insn "addsi3"
623 [(set (match_operand:SI 0 "general_operand" "=r,m")
624 (plus:SI (match_operand:SI 1 "general_operand" "0,0")
625 (match_operand:SI 2 "general_operand" "g,r")))]
626 ""
627 "@@
628 addr %2,%0
629 addm %2,%0")
630@end smallexample
632@cindex @code{*} in template
633@cindex asterisk in template
634If the output control string starts with a @samp{*}, then it is not an
635output template but rather a piece of C program that should compute a
636template. It should execute a @code{return} statement to return the
637template-string you want. Most such templates use C string literals, which
638require doublequote characters to delimit them. To include these
639doublequote characters in the string, prefix each one with @samp{\}.
641If the output control string is written as a brace block instead of a
642double-quoted string, it is automatically assumed to be C code. In that
643case, it is not necessary to put in a leading asterisk, or to escape the
644doublequotes surrounding C string literals.
646The operands may be found in the array @code{operands}, whose C data type
647is @code{rtx []}.
649It is very common to select different ways of generating assembler code
650based on whether an immediate operand is within a certain range. Be
651careful when doing this, because the result of @code{INTVAL} is an
652integer on the host machine. If the host machine has more bits in an
653@code{int} than the target machine has in the mode in which the constant
654will be used, then some of the bits you get from @code{INTVAL} will be
655superfluous. For proper results, you must carefully disregard the
656values of those bits.
658@findex output_asm_insn
659It is possible to output an assembler instruction and then go on to output
660or compute more of them, using the subroutine @code{output_asm_insn}. This
661receives two arguments: a template-string and a vector of operands. The
662vector may be @code{operands}, or it may be another array of @code{rtx}
663that you declare locally and initialize yourself.
665@findex which_alternative
666When an insn pattern has multiple alternatives in its constraints, often
667the appearance of the assembler code is determined mostly by which alternative
668was matched. When this is so, the C code can test the variable
669@code{which_alternative}, which is the ordinal number of the alternative
670that was actually satisfied (0 for the first, 1 for the second alternative,
673For example, suppose there are two opcodes for storing zero, @samp{clrreg}
674for registers and @samp{clrmem} for memory locations. Here is how
675a pattern could use @code{which_alternative} to choose between them:
678(define_insn ""
679 [(set (match_operand:SI 0 "general_operand" "=r,m")
680 (const_int 0))]
681 ""
682 @{
683 return (which_alternative == 0
684 ? "clrreg %0" : "clrmem %0");
685 @})
686@end smallexample
688The example above, where the assembler code to generate was
689@emph{solely} determined by the alternative, could also have been specified
690as follows, having the output control string start with a @samp{@@}:
694(define_insn ""
695 [(set (match_operand:SI 0 "general_operand" "=r,m")
696 (const_int 0))]
697 ""
698 "@@
699 clrreg %0
700 clrmem %0")
701@end group
702@end smallexample
703@end ifset
705@c Most of this node appears by itself (in a different place) even
706@c when the INTERNALS flag is clear. Passages that require the internals
707@c manual's context are conditionalized to appear only in the internals manual.
708@ifset INTERNALS
709@node Constraints
710@section Operand Constraints
711@cindex operand constraints
712@cindex constraints
714Each @code{match_operand} in an instruction pattern can specify a
715constraint for the type of operands allowed.
716@end ifset
717@ifclear INTERNALS
718@node Constraints
719@section Constraints for @code{asm} Operands
720@cindex operand constraints, @code{asm}
721@cindex constraints, @code{asm}
722@cindex @code{asm} constraints
724Here are specific details on what constraint letters you can use with
725@code{asm} operands.
726@end ifclear
727Constraints can say whether
728an operand may be in a register, and which kinds of register; whether the
729operand can be a memory reference, and which kinds of address; whether the
730operand may be an immediate constant, and which possible values it may
731have. Constraints can also require two operands to match.
733@ifset INTERNALS
735* Simple Constraints:: Basic use of constraints.
736* Multi-Alternative:: When an insn has two alternative constraint-patterns.
737* Class Preferences:: Constraints guide which hard register to put things in.
738* Modifiers:: More precise control over effects of constraints.
739* Machine Constraints:: Existing constraints for some particular machines.
740@end menu
741@end ifset
743@ifclear INTERNALS
745* Simple Constraints:: Basic use of constraints.
746* Multi-Alternative:: When an insn has two alternative constraint-patterns.
747* Modifiers:: More precise control over effects of constraints.
748* Machine Constraints:: Special constraints for some particular machines.
749@end menu
750@end ifclear
752@node Simple Constraints
753@subsection Simple Constraints
754@cindex simple constraints
756The simplest kind of constraint is a string full of letters, each of
757which describes one kind of operand that is permitted. Here are
758the letters that are allowed:
760@table @asis
761@item whitespace
762Whitespace characters are ignored and can be inserted at any position
763except the first. This enables each alternative for different operands to
764be visually aligned in the machine description even if they have different
765number of constraints and modifiers.
767@cindex @samp{m} in constraint
768@cindex memory references in constraints
769@item @samp{m}
770A memory operand is allowed, with any kind of address that the machine
771supports in general.
773@cindex offsettable address
774@cindex @samp{o} in constraint
775@item @samp{o}
776A memory operand is allowed, but only if the address is
777@dfn{offsettable}. This means that adding a small integer (actually,
778the width in bytes of the operand, as determined by its machine mode)
779may be added to the address and the result is also a valid memory
782@cindex autoincrement/decrement addressing
783For example, an address which is constant is offsettable; so is an
784address that is the sum of a register and a constant (as long as a
785slightly larger constant is also within the range of address-offsets
786supported by the machine); but an autoincrement or autodecrement
787address is not offsettable. More complicated indirect/indexed
788addresses may or may not be offsettable depending on the other
789addressing modes that the machine supports.
791Note that in an output operand which can be matched by another
792operand, the constraint letter @samp{o} is valid only when accompanied
793by both @samp{<} (if the target machine has predecrement addressing)
794and @samp{>} (if the target machine has preincrement addressing).
796@cindex @samp{V} in constraint
797@item @samp{V}
798A memory operand that is not offsettable. In other words, anything that
799would fit the @samp{m} constraint but not the @samp{o} constraint.
801@cindex @samp{<} in constraint
802@item @samp{<}
803A memory operand with autodecrement addressing (either predecrement or
804postdecrement) is allowed.
806@cindex @samp{>} in constraint
807@item @samp{>}
808A memory operand with autoincrement addressing (either preincrement or
809postincrement) is allowed.
811@cindex @samp{r} in constraint
812@cindex registers in constraints
813@item @samp{r}
814A register operand is allowed provided that it is in a general
817@cindex constants in constraints
818@cindex @samp{i} in constraint
819@item @samp{i}
820An immediate integer operand (one with constant value) is allowed.
821This includes symbolic constants whose values will be known only at
822assembly time.
824@cindex @samp{n} in constraint
825@item @samp{n}
826An immediate integer operand with a known numeric value is allowed.
827Many systems cannot support assembly-time constants for operands less
828than a word wide. Constraints for these operands should use @samp{n}
829rather than @samp{i}.
831@cindex @samp{I} in constraint
832@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
833Other letters in the range @samp{I} through @samp{P} may be defined in
834a machine-dependent fashion to permit immediate integer operands with
835explicit integer values in specified ranges. For example, on the
83668000, @samp{I} is defined to stand for the range of values 1 to 8.
837This is the range permitted as a shift count in the shift
840@cindex @samp{E} in constraint
841@item @samp{E}
842An immediate floating operand (expression code @code{const_double}) is
843allowed, but only if the target floating point format is the same as
844that of the host machine (on which the compiler is running).
846@cindex @samp{F} in constraint
847@item @samp{F}
848An immediate floating operand (expression code @code{const_double} or
849@code{const_vector}) is allowed.
851@cindex @samp{G} in constraint
852@cindex @samp{H} in constraint
853@item @samp{G}, @samp{H}
854@samp{G} and @samp{H} may be defined in a machine-dependent fashion to
855permit immediate floating operands in particular ranges of values.
857@cindex @samp{s} in constraint
858@item @samp{s}
859An immediate integer operand whose value is not an explicit integer is
862This might appear strange; if an insn allows a constant operand with a
863value not known at compile time, it certainly must allow any known
864value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
865better code to be generated.
867For example, on the 68000 in a fullword instruction it is possible to
868use an immediate operand; but if the immediate value is between @minus{}128
869and 127, better code results from loading the value into a register and
870using the register. This is because the load into the register can be
871done with a @samp{moveq} instruction. We arrange for this to happen
872by defining the letter @samp{K} to mean ``any integer outside the
873range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
876@cindex @samp{g} in constraint
877@item @samp{g}
878Any register, memory or immediate integer operand is allowed, except for
879registers that are not general registers.
881@cindex @samp{X} in constraint
882@item @samp{X}
883@ifset INTERNALS
884Any operand whatsoever is allowed, even if it does not satisfy
885@code{general_operand}. This is normally used in the constraint of
886a @code{match_scratch} when certain alternatives will not actually
887require a scratch register.
888@end ifset
889@ifclear INTERNALS
890Any operand whatsoever is allowed.
891@end ifclear
893@cindex @samp{0} in constraint
894@cindex digits in constraint
895@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
896An operand that matches the specified operand number is allowed. If a
897digit is used together with letters within the same alternative, the
898digit should come last.
900This number is allowed to be more than a single digit. If multiple
901digits are encountered consecutively, they are interpreted as a single
902decimal integer. There is scant chance for ambiguity, since to-date
903it has never been desirable that @samp{10} be interpreted as matching
904either operand 1 @emph{or} operand 0. Should this be desired, one
905can use multiple alternatives instead.
907@cindex matching constraint
908@cindex constraint, matching
909This is called a @dfn{matching constraint} and what it really means is
910that the assembler has only a single operand that fills two roles
911@ifset INTERNALS
912considered separate in the RTL insn. For example, an add insn has two
913input operands and one output operand in the RTL, but on most CISC
914@end ifset
915@ifclear INTERNALS
916which @code{asm} distinguishes. For example, an add instruction uses
917two input operands and an output operand, but on most CISC
918@end ifclear
919machines an add instruction really has only two operands, one of them an
920input-output operand:
923addl #35,r12
924@end smallexample
926Matching constraints are used in these circumstances.
927More precisely, the two operands that match must include one input-only
928operand and one output-only operand. Moreover, the digit must be a
929smaller number than the number of the operand that uses it in the
932@ifset INTERNALS
933For operands to match in a particular case usually means that they
934are identical-looking RTL expressions. But in a few special cases
935specific kinds of dissimilarity are allowed. For example, @code{*x}
936as an input operand will match @code{*x++} as an output operand.
937For proper results in such cases, the output template should always
938use the output-operand's number when printing the operand.
939@end ifset
941@cindex load address instruction
942@cindex push address instruction
943@cindex address constraints
944@cindex @samp{p} in constraint
945@item @samp{p}
946An operand that is a valid memory address is allowed. This is
947for ``load address'' and ``push address'' instructions.
949@findex address_operand
950@samp{p} in the constraint must be accompanied by @code{address_operand}
951as the predicate in the @code{match_operand}. This predicate interprets
952the mode specified in the @code{match_operand} as the mode of the memory
953reference for which the address would be valid.
955@cindex other register constraints
956@cindex extensible constraints
957@item @var{other-letters}
958Other letters can be defined in machine-dependent fashion to stand for
959particular classes of registers or other arbitrary operand types.
960@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
961for data, address and floating point registers.
963@ifset INTERNALS
964The machine description macro @code{REG_CLASS_FROM_LETTER} has first
965cut at the otherwise unused letters. If it evaluates to @code{NO_REGS},
966then @code{EXTRA_CONSTRAINT} is evaluated.
968A typical use for @code{EXTRA_CONSTRAINT} would be to distinguish certain
969types of memory references that affect other insn operands.
970@end ifset
971@end table
973@ifset INTERNALS
974In order to have valid assembler code, each operand must satisfy
975its constraint. But a failure to do so does not prevent the pattern
976from applying to an insn. Instead, it directs the compiler to modify
977the code so that the constraint will be satisfied. Usually this is
978done by copying an operand into a register.
980Contrast, therefore, the two instruction patterns that follow:
983(define_insn ""
984 [(set (match_operand:SI 0 "general_operand" "=r")
985 (plus:SI (match_dup 0)
986 (match_operand:SI 1 "general_operand" "r")))]
987 ""
988 "@dots{}")
989@end smallexample
992which has two operands, one of which must appear in two places, and
995(define_insn ""
996 [(set (match_operand:SI 0 "general_operand" "=r")
997 (plus:SI (match_operand:SI 1 "general_operand" "0")
998 (match_operand:SI 2 "general_operand" "r")))]
999 ""
1000 "@dots{}")
1001@end smallexample
1004which has three operands, two of which are required by a constraint to be
1005identical. If we are considering an insn of the form
1008(insn @var{n} @var{prev} @var{next}
1009 (set (reg:SI 3)
1010 (plus:SI (reg:SI 6) (reg:SI 109)))
1011 @dots{})
1012@end smallexample
1015the first pattern would not apply at all, because this insn does not
1016contain two identical subexpressions in the right place. The pattern would
1017say, ``That does not look like an add instruction; try other patterns.''
1018The second pattern would say, ``Yes, that's an add instruction, but there
1019is something wrong with it.'' It would direct the reload pass of the
1020compiler to generate additional insns to make the constraint true. The
1021results might look like this:
1024(insn @var{n2} @var{prev} @var{n}
1025 (set (reg:SI 3) (reg:SI 6))
1026 @dots{})
1028(insn @var{n} @var{n2} @var{next}
1029 (set (reg:SI 3)
1030 (plus:SI (reg:SI 3) (reg:SI 109)))
1031 @dots{})
1032@end smallexample
1034It is up to you to make sure that each operand, in each pattern, has
1035constraints that can handle any RTL expression that could be present for
1036that operand. (When multiple alternatives are in use, each pattern must,
1037for each possible combination of operand expressions, have at least one
1038alternative which can handle that combination of operands.) The
1039constraints don't need to @emph{allow} any possible operand---when this is
1040the case, they do not constrain---but they must at least point the way to
1041reloading any possible operand so that it will fit.
1043@itemize @bullet
1045If the constraint accepts whatever operands the predicate permits,
1046there is no problem: reloading is never necessary for this operand.
1048For example, an operand whose constraints permit everything except
1049registers is safe provided its predicate rejects registers.
1051An operand whose predicate accepts only constant values is safe
1052provided its constraints include the letter @samp{i}. If any possible
1053constant value is accepted, then nothing less than @samp{i} will do;
1054if the predicate is more selective, then the constraints may also be
1055more selective.
1058Any operand expression can be reloaded by copying it into a register.
1059So if an operand's constraints allow some kind of register, it is
1060certain to be safe. It need not permit all classes of registers; the
1061compiler knows how to copy a register into another register of the
1062proper class in order to make an instruction valid.
1064@cindex nonoffsettable memory reference
1065@cindex memory reference, nonoffsettable
1067A nonoffsettable memory reference can be reloaded by copying the
1068address into a register. So if the constraint uses the letter
1069@samp{o}, all memory references are taken care of.
1072A constant operand can be reloaded by allocating space in memory to
1073hold it as preinitialized data. Then the memory reference can be used
1074in place of the constant. So if the constraint uses the letters
1075@samp{o} or @samp{m}, constant operands are not a problem.
1078If the constraint permits a constant and a pseudo register used in an insn
1079was not allocated to a hard register and is equivalent to a constant,
1080the register will be replaced with the constant. If the predicate does
1081not permit a constant and the insn is re-recognized for some reason, the
1082compiler will crash. Thus the predicate must always recognize any
1083objects allowed by the constraint.
1084@end itemize
1086If the operand's predicate can recognize registers, but the constraint does
1087not permit them, it can make the compiler crash. When this operand happens
1088to be a register, the reload pass will be stymied, because it does not know
1089how to copy a register temporarily into memory.
1091If the predicate accepts a unary operator, the constraint applies to the
1092operand. For example, the MIPS processor at ISA level 3 supports an
1093instruction which adds two registers in @code{SImode} to produce a
1094@code{DImode} result, but only if the registers are correctly sign
1095extended. This predicate for the input operands accepts a
1096@code{sign_extend} of an @code{SImode} register. Write the constraint
1097to indicate the type of register that is required for the operand of the
1099@end ifset
1101@node Multi-Alternative
1102@subsection Multiple Alternative Constraints
1103@cindex multiple alternative constraints
1105Sometimes a single instruction has multiple alternative sets of possible
1106operands. For example, on the 68000, a logical-or instruction can combine
1107register or an immediate value into memory, or it can combine any kind of
1108operand into a register; but it cannot combine one memory location into
1111These constraints are represented as multiple alternatives. An alternative
1112can be described by a series of letters for each operand. The overall
1113constraint for an operand is made from the letters for this operand
1114from the first alternative, a comma, the letters for this operand from
1115the second alternative, a comma, and so on until the last alternative.
1116@ifset INTERNALS
1117Here is how it is done for fullword logical-or on the 68000:
1120(define_insn "iorsi3"
1121 [(set (match_operand:SI 0 "general_operand" "=m,d")
1122 (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1123 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1124 @dots{})
1125@end smallexample
1127The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1128operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
11292. The second alternative has @samp{d} (data register) for operand 0,
1130@samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and
1131@samp{%} in the constraints apply to all the alternatives; their
1132meaning is explained in the next section (@pxref{Class Preferences}).
1133@end ifset
1135@c FIXME Is this ? and ! stuff of use in asm()? If not, hide unless INTERNAL
1136If all the operands fit any one alternative, the instruction is valid.
1137Otherwise, for each alternative, the compiler counts how many instructions
1138must be added to copy the operands so that that alternative applies.
1139The alternative requiring the least copying is chosen. If two alternatives
1140need the same amount of copying, the one that comes first is chosen.
1141These choices can be altered with the @samp{?} and @samp{!} characters:
1143@table @code
1144@cindex @samp{?} in constraint
1145@cindex question mark
1146@item ?
1147Disparage slightly the alternative that the @samp{?} appears in,
1148as a choice when no alternative applies exactly. The compiler regards
1149this alternative as one unit more costly for each @samp{?} that appears
1150in it.
1152@cindex @samp{!} in constraint
1153@cindex exclamation point
1154@item !
1155Disparage severely the alternative that the @samp{!} appears in.
1156This alternative can still be used if it fits without reloading,
1157but if reloading is needed, some other alternative will be used.
1158@end table
1160@ifset INTERNALS
1161When an insn pattern has multiple alternatives in its constraints, often
1162the appearance of the assembler code is determined mostly by which
1163alternative was matched. When this is so, the C code for writing the
1164assembler code can use the variable @code{which_alternative}, which is
1165the ordinal number of the alternative that was actually satisfied (0 for
1166the first, 1 for the second alternative, etc.). @xref{Output Statement}.
1167@end ifset
1169@ifset INTERNALS
1170@node Class Preferences
1171@subsection Register Class Preferences
1172@cindex class preference constraints
1173@cindex register class preference constraints
1175@cindex voting between constraint alternatives
1176The operand constraints have another function: they enable the compiler
1177to decide which kind of hardware register a pseudo register is best
1178allocated to. The compiler examines the constraints that apply to the
1179insns that use the pseudo register, looking for the machine-dependent
1180letters such as @samp{d} and @samp{a} that specify classes of registers.
1181The pseudo register is put in whichever class gets the most ``votes''.
1182The constraint letters @samp{g} and @samp{r} also vote: they vote in
1183favor of a general register. The machine description says which registers
1184are considered general.
1186Of course, on some machines all registers are equivalent, and no register
1187classes are defined. Then none of this complexity is relevant.
1188@end ifset
1190@node Modifiers
1191@subsection Constraint Modifier Characters
1192@cindex modifiers in constraints
1193@cindex constraint modifier characters
1195@c prevent bad page break with this line
1196Here are constraint modifier characters.
1198@table @samp
1199@cindex @samp{=} in constraint
1200@item =
1201Means that this operand is write-only for this instruction: the previous
1202value is discarded and replaced by output data.
1204@cindex @samp{+} in constraint
1205@item +
1206Means that this operand is both read and written by the instruction.
1208When the compiler fixes up the operands to satisfy the constraints,
1209it needs to know which operands are inputs to the instruction and
1210which are outputs from it. @samp{=} identifies an output; @samp{+}
1211identifies an operand that is both input and output; all other operands
1212are assumed to be input only.
1214If you specify @samp{=} or @samp{+} in a constraint, you put it in the
1215first character of the constraint string.
1217@cindex @samp{&} in constraint
1218@cindex earlyclobber operand
1219@item &
1220Means (in a particular alternative) that this operand is an
1221@dfn{earlyclobber} operand, which is modified before the instruction is
1222finished using the input operands. Therefore, this operand may not lie
1223in a register that is used as an input operand or as part of any memory
1226@samp{&} applies only to the alternative in which it is written. In
1227constraints with multiple alternatives, sometimes one alternative
1228requires @samp{&} while others do not. See, for example, the
1229@samp{movdf} insn of the 68000.
1231An input operand can be tied to an earlyclobber operand if its only
1232use as an input occurs before the early result is written. Adding
1233alternatives of this form often allows GCC to produce better code
1234when only some of the inputs can be affected by the earlyclobber.
1235See, for example, the @samp{mulsi3} insn of the ARM@.
1237@samp{&} does not obviate the need to write @samp{=}.
1239@cindex @samp{%} in constraint
1240@item %
1241Declares the instruction to be commutative for this operand and the
1242following operand. This means that the compiler may interchange the
1243two operands if that is the cheapest way to make all operands fit the
1245@ifset INTERNALS
1246This is often used in patterns for addition instructions
1247that really have only two operands: the result must go in one of the
1248arguments. Here for example, is how the 68000 halfword-add
1249instruction is defined:
1252(define_insn "addhi3"
1253 [(set (match_operand:HI 0 "general_operand" "=m,r")
1254 (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1255 (match_operand:HI 2 "general_operand" "di,g")))]
1256 @dots{})
1257@end smallexample
1258@end ifset
1259GCC can only handle one commutative pair in an asm; if you use more,
1260the compiler may fail. Note that you need not use the modifier if
1261the two alternatives are strictly identical; this would only waste
1262time in the reload pass.
1264@cindex @samp{#} in constraint
1265@item #
1266Says that all following characters, up to the next comma, are to be
1267ignored as a constraint. They are significant only for choosing
1268register preferences.
1270@cindex @samp{*} in constraint
1271@item *
1272Says that the following character should be ignored when choosing
1273register preferences. @samp{*} has no effect on the meaning of the
1274constraint as a constraint, and no effect on reloading.
1276@ifset INTERNALS
1277Here is an example: the 68000 has an instruction to sign-extend a
1278halfword in a data register, and can also sign-extend a value by
1279copying it into an address register. While either kind of register is
1280acceptable, the constraints on an address-register destination are
1281less strict, so it is best if register allocation makes an address
1282register its goal. Therefore, @samp{*} is used so that the @samp{d}
1283constraint letter (for data register) is ignored when computing
1284register preferences.
1287(define_insn "extendhisi2"
1288 [(set (match_operand:SI 0 "general_operand" "=*d,a")
1289 (sign_extend:SI
1290 (match_operand:HI 1 "general_operand" "0,g")))]
1291 @dots{})
1292@end smallexample
1293@end ifset
1294@end table
1296@node Machine Constraints
1297@subsection Constraints for Particular Machines
1298@cindex machine specific constraints
1299@cindex constraints, machine specific
1301Whenever possible, you should use the general-purpose constraint letters
1302in @code{asm} arguments, since they will convey meaning more readily to
1303people reading your code. Failing that, use the constraint letters
1304that usually have very similar meanings across architectures. The most
1305commonly used constraints are @samp{m} and @samp{r} (for memory and
1306general-purpose registers respectively; @pxref{Simple Constraints}), and
1307@samp{I}, usually the letter indicating the most common
1308immediate-constant format.
1310For each machine architecture, the
1311@file{config/@var{machine}/@var{machine}.h} file defines additional
1312constraints. These constraints are used by the compiler itself for
1313instruction generation, as well as for @code{asm} statements; therefore,
1314some of the constraints are not particularly interesting for @code{asm}.
1315The constraints are defined through these macros:
1317@table @code
1319Register class constraints (usually lowercase).
1322Immediate constant constraints, for non-floating point constants of
1323word size or smaller precision (usually uppercase).
1326Immediate constant constraints, for all floating point constants and for
1327constants of greater than word size precision (usually uppercase).
1330Special cases of registers or memory. This macro is not required, and
1331is only defined for some machines.
1332@end table
1334Inspecting these macro definitions in the compiler source for your
1335machine is the best way to be certain you have the right constraints.
1336However, here is a summary of the machine-dependent constraints
1337available on some particular machines.
1339@table @emph
1340@item ARM family---@file{arm.h}
1341@table @code
1342@item f
1343Floating-point register
1345@item F
1346One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0
1347or 10.0
1349@item G
1350Floating-point constant that would satisfy the constraint @samp{F} if it
1351were negated
1353@item I
1354Integer that is valid as an immediate operand in a data processing
1355instruction. That is, an integer in the range 0 to 255 rotated by a
1356multiple of 2
1358@item J
1359Integer in the range @minus{}4095 to 4095
1361@item K
1362Integer that satisfies constraint @samp{I} when inverted (ones complement)
1364@item L
1365Integer that satisfies constraint @samp{I} when negated (twos complement)
1367@item M
1368Integer in the range 0 to 32
1370@item Q
1371A memory reference where the exact address is in a single register
1372(`@samp{m}' is preferable for @code{asm} statements)
1374@item R
1375An item in the constant pool
1377@item S
1378A symbol in the text segment of the current file
1379@end table
1381@item AVR family---@file{avr.h}
1382@table @code
1383@item l
1384Registers from r0 to r15
1386@item a
1387Registers from r16 to r23
1389@item d
1390Registers from r16 to r31
1392@item w
1393Registers from r24 to r31. These registers can be used in @samp{adiw} command
1395@item e
1396Pointer register (r26--r31)
1398@item b
1399Base pointer register (r28--r31)
1401@item q
1402Stack pointer register (SPH:SPL)
1404@item t
1405Temporary register r0
1407@item x
1408Register pair X (r27:r26)
1410@item y
1411Register pair Y (r29:r28)
1413@item z
1414Register pair Z (r31:r30)
1416@item I
1417Constant greater than @minus{}1, less than 64
1419@item J
1420Constant greater than @minus{}64, less than 1
1422@item K
1423Constant integer 2
1425@item L
1426Constant integer 0
1428@item M
1429Constant that fits in 8 bits
1431@item N
1432Constant integer @minus{}1
1434@item O
1435Constant integer 8, 16, or 24
1437@item P
1438Constant integer 1
1440@item G
1441A floating point constant 0.0
1442@end table
1444@item PowerPC and IBM RS6000---@file{rs6000.h}
1445@table @code
1446@item b
1447Address base register
1449@item f
1450Floating point register
1452@item v
1453Vector register
1455@item h
1456@samp{MQ}, @samp{CTR}, or @samp{LINK} register
1458@item q
1459@samp{MQ} register
1461@item c
1462@samp{CTR} register
1464@item l
1465@samp{LINK} register
1467@item x
1468@samp{CR} register (condition register) number 0
1470@item y
1471@samp{CR} register (condition register)
1473@item z
1474@samp{FPMEM} stack memory for FPR-GPR transfers
1476@item I
1477Signed 16-bit constant
1479@item J
1480Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for
1481@code{SImode} constants)
1483@item K
1484Unsigned 16-bit constant
1486@item L
1487Signed 16-bit constant shifted left 16 bits
1489@item M
1490Constant larger than 31
1492@item N
1493Exact power of 2
1495@item O
1498@item P
1499Constant whose negation is a signed 16-bit constant
1501@item G
1502Floating point constant that can be loaded into a register with one
1503instruction per word
1505@item Q
1506Memory operand that is an offset from a register (@samp{m} is preferable
1507for @code{asm} statements)
1509@item R
1510AIX TOC entry
1512@item S
1513Constant suitable as a 64-bit mask operand
1515@item T
1516Constant suitable as a 32-bit mask operand
1518@item U
1519System V Release 4 small data area reference
1520@end table
1522@item Intel 386---@file{i386.h}
1523@table @code
1524@item q
1525@samp{a}, @code{b}, @code{c}, or @code{d} register for the i386.
1526For x86-64 it is equivalent to @samp{r} class. (for 8-bit instructions that
1527do not use upper halves)
1529@item Q
1530@samp{a}, @code{b}, @code{c}, or @code{d} register. (for 8-bit instructions,
1531that do use upper halves)
1533@item R
1534Legacy register---equivalent to @code{r} class in i386 mode.
1535(for non-8-bit registers used together with 8-bit upper halves in a single
1538@item A
1539Specifies the @samp{a} or @samp{d} registers. This is primarily useful
1540for 64-bit integer values (when in 32-bit mode) intended to be returned
1541with the @samp{d} register holding the most significant bits and the
1542@samp{a} register holding the least significant bits.
1544@item f
1545Floating point register
1547@item t
1548First (top of stack) floating point register
1550@item u
1551Second floating point register
1553@item a
1554@samp{a} register
1556@item b
1557@samp{b} register
1559@item c
1560@samp{c} register
1562@item C
1563Specifies constant that can be easily constructed in SSE register without
1564loading it from memory.
1566@item d
1567@samp{d} register
1569@item D
1570@samp{di} register
1572@item S
1573@samp{si} register
1575@item x
1576@samp{xmm} SSE register
1578@item y
1579MMX register
1581@item I
1582Constant in range 0 to 31 (for 32-bit shifts)
1584@item J
1585Constant in range 0 to 63 (for 64-bit shifts)
1587@item K
1590@item L
1593@item M
15940, 1, 2, or 3 (shifts for @code{lea} instruction)
1596@item N
1597Constant in range 0 to 255 (for @code{out} instruction)
1599@item Z
1600Constant in range 0 to @code{0xffffffff} or symbolic reference known to fit specified range.
1601(for using immediates in zero extending 32-bit to 64-bit x86-64 instructions)
1603@item e
1604Constant in range @minus{}2147483648 to 2147483647 or symbolic reference known to fit specified range.
1605(for using immediates in 64-bit x86-64 instructions)
1607@item G
1608Standard 80387 floating point constant
1609@end table
1611@item Intel 960---@file{i960.h}
1612@table @code
1613@item f
1614Floating point register (@code{fp0} to @code{fp3})
1616@item l
1617Local register (@code{r0} to @code{r15})
1619@item b
1620Global register (@code{g0} to @code{g15})
1622@item d
1623Any local or global register
1625@item I
1626Integers from 0 to 31
1628@item J
1631@item K
1632Integers from @minus{}31 to 0
1634@item G
1635Floating point 0
1637@item H
1638Floating point 1
1639@end table
1641@item Intel IA-64---@file{ia64.h}
1642@table @code
1643@item a
1644General register @code{r0} to @code{r3} for @code{addl} instruction
1646@item b
1647Branch register
1649@item c
1650Predicate register (@samp{c} as in ``conditional'')
1652@item d
1653Application register residing in M-unit
1655@item e
1656Application register residing in I-unit
1658@item f
1659Floating-point register
1661@item m
1662Memory operand.
1663Remember that @samp{m} allows postincrement and postdecrement which
1664require printing with @samp{%Pn} on IA-64.
1665Use @samp{S} to disallow postincrement and postdecrement.
1667@item G
1668Floating-point constant 0.0 or 1.0
1670@item I
167114-bit signed integer constant
1673@item J
167422-bit signed integer constant
1676@item K
16778-bit signed integer constant for logical instructions
1679@item L
16808-bit adjusted signed integer constant for compare pseudo-ops
1682@item M
16836-bit unsigned integer constant for shift counts
1685@item N
16869-bit signed integer constant for load and store postincrements
1688@item O
1689The constant zero
1691@item P
16920 or -1 for @code{dep} instruction
1694@item Q
1695Non-volatile memory for floating-point loads and stores
1697@item R
1698Integer constant in the range 1 to 4 for @code{shladd} instruction
1700@item S
1701Memory operand except postincrement and postdecrement
1702@end table
1704@item FRV---@file{frv.h}
1705@table @code
1706@item a
1707Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
1709@item b
1710Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
1712@item c
1713Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
1714@code{icc0} to @code{icc3}).
1716@item d
1717Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
1719@item e
1720Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
1721Odd registers are excluded not in the class but through the use of a machine
1722mode larger than 4 bytes.
1724@item f
1725Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
1727@item h
1728Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
1729Odd registers are excluded not in the class but through the use of a machine
1730mode larger than 4 bytes.
1732@item l
1733Register in the class @code{LR_REG} (the @code{lr} register).
1735@item q
1736Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
1737Register numbers not divisible by 4 are excluded not in the class but through
1738the use of a machine mode larger than 8 bytes.
1740@item t
1741Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
1743@item u
1744Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
1746@item v
1747Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
1749@item w
1750Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
1752@item x
1753Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
1754Register numbers not divisible by 4 are excluded not in the class but through
1755the use of a machine mode larger than 8 bytes.
1757@item z
1758Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
1760@item A
1761Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
1763@item B
1764Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
1766@item C
1767Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
1769@item G
1770Floating point constant zero
1772@item I
17736-bit signed integer constant
1775@item J
177610-bit signed integer constant
1778@item L
177916-bit signed integer constant
1781@item M
178216-bit unsigned integer constant
1784@item N
178512-bit signed integer constant that is negative---i.e.@: in the
1786range of @minus{}2048 to @minus{}1
1788@item O
1789Constant zero
1791@item P
179212-bit signed integer constant that is greater than zero---i.e.@: in the
1793range of 1 to 2047.
1795@end table
1797@item IP2K---@file{ip2k.h}
1798@table @code
1799@item a
1800@samp{DP} or @samp{IP} registers (general address)
1802@item f
1803@samp{IP} register
1805@item j
1806@samp{IPL} register
1808@item k
1809@samp{IPH} register
1811@item b
1812@samp{DP} register
1814@item y
1815@samp{DPH} register
1817@item z
1818@samp{DPL} register
1820@item q
1821@samp{SP} register
1823@item c
1824@samp{DP} or @samp{SP} registers (offsettable address)
1826@item d
1827Non-pointer registers (not @samp{SP}, @samp{DP}, @samp{IP})
1829@item u
1830Non-SP registers (everything except @samp{SP})
1832@item R
1833Indirect through @samp{IP} - Avoid this except for @code{QImode}, since we
1834can't access extra bytes
1836@item S
1837Indirect through @samp{SP} or @samp{DP} with short displacement (0..127)
1839@item T
1840Data-section immediate value
1842@item I
1843Integers from @minus{}255 to @minus{}1
1845@item J
1846Integers from 0 to 7---valid bit number in a register
1848@item K
1849Integers from 0 to 127---valid displacement for addressing mode
1851@item L
1852Integers from 1 to 127
1854@item M
1855Integer @minus{}1
1857@item N
1858Integer 1
1860@item O
1863@item P
1864Integers from 0 to 255
1865@end table
1867@item MIPS---@file{mips.h}
1868@table @code
1869@item d
1870General-purpose integer register
1872@item f
1873Floating-point register (if available)
1875@item h
1876@samp{Hi} register
1878@item l
1879@samp{Lo} register
1881@item x
1882@samp{Hi} or @samp{Lo} register
1884@item y
1885General-purpose integer register
1887@item z
1888Floating-point status register
1890@item I
1891Signed 16-bit constant (for arithmetic instructions)
1893@item J
1896@item K
1897Zero-extended 16-bit constant (for logic instructions)
1899@item L
1900Constant with low 16 bits zero (can be loaded with @code{lui})
1902@item M
190332-bit constant which requires two instructions to load (a constant
1904which is not @samp{I}, @samp{K}, or @samp{L})
1906@item N
1907Negative 16-bit constant
1909@item O
1910Exact power of two
1912@item P
1913Positive 16-bit constant
1915@item G
1916Floating point zero
1918@item Q
1919Memory reference that can be loaded with more than one instruction
1920(@samp{m} is preferable for @code{asm} statements)
1922@item R
1923Memory reference that can be loaded with one instruction
1924(@samp{m} is preferable for @code{asm} statements)
1926@item S
1927Memory reference in external OSF/rose PIC format
1928(@samp{m} is preferable for @code{asm} statements)
1929@end table
1931@item Motorola 680x0---@file{m68k.h}
1932@table @code
1933@item a
1934Address register
1936@item d
1937Data register
1939@item f
194068881 floating-point register, if available
1942@item I
1943Integer in the range 1 to 8
1945@item J
194616-bit signed number
1948@item K
1949Signed number whose magnitude is greater than 0x80
1951@item L
1952Integer in the range @minus{}8 to @minus{}1
1954@item M
1955Signed number whose magnitude is greater than 0x100
1957@item G
1958Floating point constant that is not a 68881 constant
1959@end table
1961@item Motorola 68HC11 & 68HC12 families---@file{m68hc11.h}
1962@table @code
1963@item a
1964Register 'a'
1966@item b
1967Register 'b'
1969@item d
1970Register 'd'
1972@item q
1973An 8-bit register
1975@item t
1976Temporary soft register _.tmp
1978@item u
1979A soft register _.d1 to _.d31
1981@item w
1982Stack pointer register
1984@item x
1985Register 'x'
1987@item y
1988Register 'y'
1990@item z
1991Pseudo register 'z' (replaced by 'x' or 'y' at the end)
1993@item A
1994An address register: x, y or z
1996@item B
1997An address register: x or y
1999@item D
2000Register pair (x:d) to form a 32-bit value
2002@item L
2003Constants in the range @minus{}65536 to 65535
2005@item M
2006Constants whose 16-bit low part is zero
2008@item N
2009Constant integer 1 or @minus{}1
2011@item O
2012Constant integer 16
2014@item P
2015Constants in the range @minus{}8 to 2
2017@end table
2019@need 1000
2020@item SPARC---@file{sparc.h}
2021@table @code
2022@item f
2023Floating-point register on the SPARC-V8 architecture and
2024lower floating-point register on the SPARC-V9 architecture.
2026@item e
2027Floating-point register. It is equivalent to @samp{f} on the
2028SPARC-V8 architecture and contains both lower and upper
2029floating-point registers on the SPARC-V9 architecture.
2031@item c
2032Floating-point condition code register.
2034@item d
2035Lower floating-point register. It is only valid on the SPARC-V9
2036architecture when the Visual Instruction Set is available.
2038@item b
2039Floating-point register. It is only valid on the SPARC-V9 architecture
2040when the Visual Instruction Set is available.
2042@item h
204364-bit global or out register for the SPARC-V8+ architecture.
2045@item I
2046Signed 13-bit constant
2048@item J
2051@item K
205232-bit constant with the low 12 bits clear (a constant that can be
2053loaded with the @code{sethi} instruction)
2055@item L
2056A constant in the range supported by @code{movcc} instructions
2058@item M
2059A constant in the range supported by @code{movrcc} instructions
2061@item N
2062Same as @samp{K}, except that it verifies that bits that are not in the
2063lower 32-bit range are all zero. Must be used instead of @samp{K} for
2064modes wider than @code{SImode}
2066@item O
2067The constant 4096
2069@item G
2070Floating-point zero
2072@item H
2073Signed 13-bit constant, sign-extended to 32 or 64 bits
2075@item Q
2076Floating-point constant whose integral representation can
2077be moved into an integer register using a single sethi
2080@item R
2081Floating-point constant whose integral representation can
2082be moved into an integer register using a single mov
2085@item S
2086Floating-point constant whose integral representation can
2087be moved into an integer register using a high/lo_sum
2088instruction sequence
2090@item T
2091Memory address aligned to an 8-byte boundary
2093@item U
2094Even register
2096@item W
2097Memory address for @samp{e} constraint registers.
2099@end table
2101@item TMS320C3x/C4x---@file{c4x.h}
2102@table @code
2103@item a
2104Auxiliary (address) register (ar0-ar7)
2106@item b
2107Stack pointer register (sp)
2109@item c
2110Standard (32-bit) precision integer register
2112@item f
2113Extended (40-bit) precision register (r0-r11)
2115@item k
2116Block count register (bk)
2118@item q
2119Extended (40-bit) precision low register (r0-r7)
2121@item t
2122Extended (40-bit) precision register (r0-r1)
2124@item u
2125Extended (40-bit) precision register (r2-r3)
2127@item v
2128Repeat count register (rc)
2130@item x
2131Index register (ir0-ir1)
2133@item y
2134Status (condition code) register (st)
2136@item z
2137Data page register (dp)
2139@item G
2140Floating-point zero
2142@item H
2143Immediate 16-bit floating-point constant
2145@item I
2146Signed 16-bit constant
2148@item J
2149Signed 8-bit constant
2151@item K
2152Signed 5-bit constant
2154@item L
2155Unsigned 16-bit constant
2157@item M
2158Unsigned 8-bit constant
2160@item N
2161Ones complement of unsigned 16-bit constant
2163@item O
2164High 16-bit constant (32-bit constant with 16 LSBs zero)
2166@item Q
2167Indirect memory reference with signed 8-bit or index register displacement
2169@item R
2170Indirect memory reference with unsigned 5-bit displacement
2172@item S
2173Indirect memory reference with 1 bit or index register displacement
2175@item T
2176Direct memory reference
2178@item U
2179Symbolic address
2181@end table
2183@item S/390 and zSeries---@file{s390.h}
2184@table @code
2185@item a
2186Address register (general purpose register except r0)
2188@item d
2189Data register (arbitrary general purpose register)
2191@item f
2192Floating-point register
2194@item I
2195Unsigned 8-bit constant (0--255)
2197@item J
2198Unsigned 12-bit constant (0--4095)
2200@item K
2201Signed 16-bit constant (@minus{}32768--32767)
2203@item L
2204Value appropriate as displacement.
2205@table @code
2206 @item (0..4095)
2207 for short displacement
2208 @item (-524288..524287)
2209 for long displacement
2210@end table
2212@item M
2213Constant integer with a value of 0x7fffffff.
2215@item N
2216Multiple letter constraint followed by 4 parameter letters.
2217@table @code
2218 @item 0..9:
2219 number of the part counting from most to least significant
2220 @item H,Q:
2221 mode of the part
2222 @item D,S,H:
2223 mode of the containing operand
2224 @item 0,F:
2225 value of the other parts (F - all bits set)
2226@end table
2227The constraint matches if the specified part of a constant
2228has a value different from it's other parts.
2230@item Q
2231Memory reference without index register and with short displacement.
2233@item R
2234Memory reference with index register and short displacement.
2236@item S
2237Memory reference without index register but with long displacement.
2239@item T
2240Memory reference with index register and long displacement.
2242@item U
2243Pointer with short displacement.
2245@item W
2246Pointer with long displacement.
2248@item Y
2249Shift count operand.
2251@end table
2253@item Xstormy16---@file{stormy16.h}
2254@table @code
2255@item a
2256Register r0.
2258@item b
2259Register r1.
2261@item c
2262Register r2.
2264@item d
2265Register r8.
2267@item e
2268Registers r0 through r7.
2270@item t
2271Registers r0 and r1.
2273@item y
2274The carry register.
2276@item z
2277Registers r8 and r9.
2279@item I
2280A constant between 0 and 3 inclusive.
2282@item J
2283A constant that has exactly one bit set.
2285@item K
2286A constant that has exactly one bit clear.
2288@item L
2289A constant between 0 and 255 inclusive.
2291@item M
2292A constant between @minus{}255 and 0 inclusive.
2294@item N
2295A constant between @minus{}3 and 0 inclusive.
2297@item O
2298A constant between 1 and 4 inclusive.
2300@item P
2301A constant between @minus{}4 and @minus{}1 inclusive.
2303@item Q
2304A memory reference that is a stack push.
2306@item R
2307A memory reference that is a stack pop.
2309@item S
2310A memory reference that refers to a constant address of known value.
2312@item T
2313The register indicated by Rx (not implemented yet).
2315@item U
2316A constant that is not between 2 and 15 inclusive.
2318@item Z
2319The constant 0.
2321@end table
2323@item Xtensa---@file{xtensa.h}
2324@table @code
2325@item a
2326General-purpose 32-bit register
2328@item b
2329One-bit boolean register
2331@item A
2332MAC16 40-bit accumulator register
2334@item I
2335Signed 12-bit integer constant, for use in MOVI instructions
2337@item J
2338Signed 8-bit integer constant, for use in ADDI instructions
2340@item K
2341Integer constant valid for BccI instructions
2343@item L
2344Unsigned constant valid for BccUI instructions
2346@end table
2348@end table
2350@ifset INTERNALS
2351@node Standard Names
2352@section Standard Pattern Names For Generation
2353@cindex standard pattern names
2354@cindex pattern names
2355@cindex names, pattern
2357Here is a table of the instruction names that are meaningful in the RTL
2358generation pass of the compiler. Giving one of these names to an
2359instruction pattern tells the RTL generation pass that it can use the
2360pattern to accomplish a certain task.
2362@table @asis
2363@cindex @code{mov@var{m}} instruction pattern
2364@item @samp{mov@var{m}}
2365Here @var{m} stands for a two-letter machine mode name, in lowercase.
2366This instruction pattern moves data with that machine mode from operand
23671 to operand 0. For example, @samp{movsi} moves full-word data.
2369If operand 0 is a @code{subreg} with mode @var{m} of a register whose
2370own mode is wider than @var{m}, the effect of this instruction is
2371to store the specified value in the part of the register that corresponds
2372to mode @var{m}. Bits outside of @var{m}, but which are within the
2373same target word as the @code{subreg} are undefined. Bits which are
2374outside the target word are left unchanged.
2376This class of patterns is special in several ways. First of all, each
2377of these names up to and including full word size @emph{must} be defined,
2378because there is no other way to copy a datum from one place to another.
2379If there are patterns accepting operands in larger modes,
2380@samp{mov@var{m}} must be defined for integer modes of those sizes.
2382Second, these patterns are not used solely in the RTL generation pass.
2383Even the reload pass can generate move insns to copy values from stack
2384slots into temporary registers. When it does so, one of the operands is
2385a hard register and the other is an operand that can need to be reloaded
2386into a register.
2388@findex force_reg
2389Therefore, when given such a pair of operands, the pattern must generate
2390RTL which needs no reloading and needs no temporary registers---no
2391registers other than the operands. For example, if you support the
2392pattern with a @code{define_expand}, then in such a case the
2393@code{define_expand} mustn't call @code{force_reg} or any other such
2394function which might generate new pseudo registers.
2396This requirement exists even for subword modes on a RISC machine where
2397fetching those modes from memory normally requires several insns and
2398some temporary registers.
2400@findex change_address
2401During reload a memory reference with an invalid address may be passed
2402as an operand. Such an address will be replaced with a valid address
2403later in the reload pass. In this case, nothing may be done with the
2404address except to use it as it stands. If it is copied, it will not be
2405replaced with a valid address. No attempt should be made to make such
2406an address into a valid address and no routine (such as
2407@code{change_address}) that will do so may be called. Note that
2408@code{general_operand} will fail when applied to such an address.
2410@findex reload_in_progress
2411The global variable @code{reload_in_progress} (which must be explicitly
2412declared if required) can be used to determine whether such special
2413handling is required.
2415The variety of operands that have reloads depends on the rest of the
2416machine description, but typically on a RISC machine these can only be
2417pseudo registers that did not get hard registers, while on other
2418machines explicit memory references will get optional reloads.
2420If a scratch register is required to move an object to or from memory,
2421it can be allocated using @code{gen_reg_rtx} prior to life analysis.
2423If there are cases which need scratch registers during or after reload,
2424you must define @code{SECONDARY_INPUT_RELOAD_CLASS} and/or
2425@code{SECONDARY_OUTPUT_RELOAD_CLASS} to detect them, and provide
2426patterns @samp{reload_in@var{m}} or @samp{reload_out@var{m}} to handle
2427them. @xref{Register Classes}.
2429@findex no_new_pseudos
2430The global variable @code{no_new_pseudos} can be used to determine if it
2431is unsafe to create new pseudo registers. If this variable is nonzero, then
2432it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
2434The constraints on a @samp{mov@var{m}} must permit moving any hard
2435register to any other hard register provided that
2436@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
2437@code{REGISTER_MOVE_COST} applied to their classes returns a value of 2.
2439It is obligatory to support floating point @samp{mov@var{m}}
2440instructions into and out of any registers that can hold fixed point
2441values, because unions and structures (which have modes @code{SImode} or
2442@code{DImode}) can be in those registers and they may have floating
2443point members.
2445There may also be a need to support fixed point @samp{mov@var{m}}
2446instructions in and out of floating point registers. Unfortunately, I
2447have forgotten why this was so, and I don't know whether it is still
2448true. If @code{HARD_REGNO_MODE_OK} rejects fixed point values in
2449floating point registers, then the constraints of the fixed point
2450@samp{mov@var{m}} instructions must be designed to avoid ever trying to
2451reload into a floating point register.
2453@cindex @code{reload_in} instruction pattern
2454@cindex @code{reload_out} instruction pattern
2455@item @samp{reload_in@var{m}}
2456@itemx @samp{reload_out@var{m}}
2457Like @samp{mov@var{m}}, but used when a scratch register is required to
2458move between operand 0 and operand 1. Operand 2 describes the scratch
2459register. See the discussion of the @code{SECONDARY_RELOAD_CLASS}
2460macro in @pxref{Register Classes}.
2462There are special restrictions on the form of the @code{match_operand}s
2463used in these patterns. First, only the predicate for the reload
2464operand is examined, i.e., @code{reload_in} examines operand 1, but not
2465the predicates for operand 0 or 2. Second, there may be only one
2466alternative in the constraints. Third, only a single register class
2467letter may be used for the constraint; subsequent constraint letters
2468are ignored. As a special exception, an empty constraint string
2469matches the @code{ALL_REGS} register class. This may relieve ports
2470of the burden of defining an @code{ALL_REGS} constraint letter just
2471for these patterns.
2473@cindex @code{movstrict@var{m}} instruction pattern
2474@item @samp{movstrict@var{m}}
2475Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
2476with mode @var{m} of a register whose natural mode is wider,
2477the @samp{movstrict@var{m}} instruction is guaranteed not to alter
2478any of the register except the part which belongs to mode @var{m}.
2480@cindex @code{load_multiple} instruction pattern
2481@item @samp{load_multiple}
2482Load several consecutive memory locations into consecutive registers.
2483Operand 0 is the first of the consecutive registers, operand 1
2484is the first memory location, and operand 2 is a constant: the
2485number of consecutive registers.
2487Define this only if the target machine really has such an instruction;
2488do not define this if the most efficient way of loading consecutive
2489registers from memory is to do them one at a time.
2491On some machines, there are restrictions as to which consecutive
2492registers can be stored into memory, such as particular starting or
2493ending register numbers or only a range of valid counts. For those
2494machines, use a @code{define_expand} (@pxref{Expander Definitions})
2495and make the pattern fail if the restrictions are not met.
2497Write the generated insn as a @code{parallel} with elements being a
2498@code{set} of one register from the appropriate memory location (you may
2499also need @code{use} or @code{clobber} elements). Use a
2500@code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See
2501@file{} for examples of the use of this insn pattern.
2503@cindex @samp{store_multiple} instruction pattern
2504@item @samp{store_multiple}
2505Similar to @samp{load_multiple}, but store several consecutive registers
2506into consecutive memory locations. Operand 0 is the first of the
2507consecutive memory locations, operand 1 is the first register, and
2508operand 2 is a constant: the number of consecutive registers.
2510@cindex @code{push@var{m}} instruction pattern
2511@item @samp{push@var{m}}
2512Output a push instruction. Operand 0 is value to push. Used only when
2513@code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be
2514missing and in such case an @code{mov} expander is used instead, with a
2515@code{MEM} expression forming the push operation. The @code{mov} expander
2516method is deprecated.
2518@cindex @code{add@var{m}3} instruction pattern
2519@item @samp{add@var{m}3}
2520Add operand 2 and operand 1, storing the result in operand 0. All operands
2521must have mode @var{m}. This can be used even on two-address machines, by
2522means of constraints requiring operands 1 and 0 to be the same location.
2524@cindex @code{sub@var{m}3} instruction pattern
2525@cindex @code{mul@var{m}3} instruction pattern
2526@cindex @code{div@var{m}3} instruction pattern
2527@cindex @code{udiv@var{m}3} instruction pattern
2528@cindex @code{mod@var{m}3} instruction pattern
2529@cindex @code{umod@var{m}3} instruction pattern
2530@cindex @code{smin@var{m}3} instruction pattern
2531@cindex @code{smax@var{m}3} instruction pattern
2532@cindex @code{umin@var{m}3} instruction pattern
2533@cindex @code{umax@var{m}3} instruction pattern
2534@cindex @code{and@var{m}3} instruction pattern
2535@cindex @code{ior@var{m}3} instruction pattern
2536@cindex @code{xor@var{m}3} instruction pattern
2537@item @samp{sub@var{m}3}, @samp{mul@var{m}3}
2538@itemx @samp{div@var{m}3}, @samp{udiv@var{m}3}, @samp{mod@var{m}3}, @samp{umod@var{m}3}
2539@itemx @samp{smin@var{m}3}, @samp{smax@var{m}3}, @samp{umin@var{m}3}, @samp{umax@var{m}3}
2540@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
2541Similar, for other arithmetic operations.
2542@cindex @code{min@var{m}3} instruction pattern
2543@cindex @code{max@var{m}3} instruction pattern
2544@itemx @samp{min@var{m}3}, @samp{max@var{m}3}
2545Floating point min and max operations. If both operands are zeros,
2546or if either operand is NaN, then it is unspecified which of the two
2547operands is returned as the result.
2550@cindex @code{mulhisi3} instruction pattern
2551@item @samp{mulhisi3}
2552Multiply operands 1 and 2, which have mode @code{HImode}, and store
2553a @code{SImode} product in operand 0.
2555@cindex @code{mulqihi3} instruction pattern
2556@cindex @code{mulsidi3} instruction pattern
2557@item @samp{mulqihi3}, @samp{mulsidi3}
2558Similar widening-multiplication instructions of other widths.
2560@cindex @code{umulqihi3} instruction pattern
2561@cindex @code{umulhisi3} instruction pattern
2562@cindex @code{umulsidi3} instruction pattern
2563@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
2564Similar widening-multiplication instructions that do unsigned
2567@cindex @code{smul@var{m}3_highpart} instruction pattern
2568@item @samp{smul@var{m}3_highpart}
2569Perform a signed multiplication of operands 1 and 2, which have mode
2570@var{m}, and store the most significant half of the product in operand 0.
2571The least significant half of the product is discarded.
2573@cindex @code{umul@var{m}3_highpart} instruction pattern
2574@item @samp{umul@var{m}3_highpart}
2575Similar, but the multiplication is unsigned.
2577@cindex @code{divmod@var{m}4} instruction pattern
2578@item @samp{divmod@var{m}4}
2579Signed division that produces both a quotient and a remainder.
2580Operand 1 is divided by operand 2 to produce a quotient stored
2581in operand 0 and a remainder stored in operand 3.
2583For machines with an instruction that produces both a quotient and a
2584remainder, provide a pattern for @samp{divmod@var{m}4} but do not
2585provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This
2586allows optimization in the relatively common case when both the quotient
2587and remainder are computed.
2589If an instruction that just produces a quotient or just a remainder
2590exists and is more efficient than the instruction that produces both,
2591write the output routine of @samp{divmod@var{m}4} to call
2592@code{find_reg_note} and look for a @code{REG_UNUSED} note on the
2593quotient or remainder and generate the appropriate instruction.
2595@cindex @code{udivmod@var{m}4} instruction pattern
2596@item @samp{udivmod@var{m}4}
2597Similar, but does unsigned division.
2599@cindex @code{ashl@var{m}3} instruction pattern
2600@item @samp{ashl@var{m}3}
2601Arithmetic-shift operand 1 left by a number of bits specified by operand
26022, and store the result in operand 0. Here @var{m} is the mode of
2603operand 0 and operand 1; operand 2's mode is specified by the
2604instruction pattern, and the compiler will convert the operand to that
2605mode before generating the instruction.
2607@cindex @code{ashr@var{m}3} instruction pattern
2608@cindex @code{lshr@var{m}3} instruction pattern
2609@cindex @code{rotl@var{m}3} instruction pattern
2610@cindex @code{rotr@var{m}3} instruction pattern
2611@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
2612Other shift and rotate instructions, analogous to the
2613@code{ashl@var{m}3} instructions.
2615@cindex @code{neg@var{m}2} instruction pattern
2616@item @samp{neg@var{m}2}
2617Negate operand 1 and store the result in operand 0.
2619@cindex @code{abs@var{m}2} instruction pattern
2620@item @samp{abs@var{m}2}
2621Store the absolute value of operand 1 into operand 0.
2623@cindex @code{sqrt@var{m}2} instruction pattern
2624@item @samp{sqrt@var{m}2}
2625Store the square root of operand 1 into operand 0.
2627The @code{sqrt} built-in function of C always uses the mode which
2628corresponds to the C data type @code{double} and the @code{sqrtf}
2629built-in function uses the mode which corresponds to the C data
2630type @code{float}.
2632@cindex @code{cos@var{m}2} instruction pattern
2633@item @samp{cos@var{m}2}
2634Store the cosine of operand 1 into operand 0.
2636The @code{cos} built-in function of C always uses the mode which
2637corresponds to the C data type @code{double} and the @code{cosf}
2638built-in function uses the mode which corresponds to the C data
2639type @code{float}.
2641@cindex @code{sin@var{m}2} instruction pattern
2642@item @samp{sin@var{m}2}
2643Store the sine of operand 1 into operand 0.
2645The @code{sin} built-in function of C always uses the mode which
2646corresponds to the C data type @code{double} and the @code{sinf}
2647built-in function uses the mode which corresponds to the C data
2648type @code{float}.
2650@cindex @code{exp@var{m}2} instruction pattern
2651@item @samp{exp@var{m}2}
2652Store the exponential of operand 1 into operand 0.
2654The @code{exp} built-in function of C always uses the mode which
2655corresponds to the C data type @code{double} and the @code{expf}
2656built-in function uses the mode which corresponds to the C data
2657type @code{float}.
2659@cindex @code{log@var{m}2} instruction pattern
2660@item @samp{log@var{m}2}
2661Store the natural logarithm of operand 1 into operand 0.
2663The @code{log} built-in function of C always uses the mode which
2664corresponds to the C data type @code{double} and the @code{logf}
2665built-in function uses the mode which corresponds to the C data
2666type @code{float}.
2668@cindex @code{pow@var{m}3} instruction pattern
2669@item @samp{pow@var{m}3}
2670Store the value of operand 1 raised to the exponent operand 2
2671into operand 0.
2673The @code{pow} built-in function of C always uses the mode which
2674corresponds to the C data type @code{double} and the @code{powf}
2675built-in function uses the mode which corresponds to the C data
2676type @code{float}.
2678@cindex @code{atan2@var{m}3} instruction pattern
2679@item @samp{atan2@var{m}3}
2680Store the arc tangent (inverse tangent) of operand 1 divided by
2681operand 2 into operand 0, using the signs of both arguments to
2682determine the quadrant of the result.
2684The @code{atan2} built-in function of C always uses the mode which
2685corresponds to the C data type @code{double} and the @code{atan2f}
2686built-in function uses the mode which corresponds to the C data
2687type @code{float}.
2689@cindex @code{floor@var{m}2} instruction pattern
2690@item @samp{floor@var{m}2}
2691Store the largest integral value not greater than argument.
2693The @code{floor} built-in function of C always uses the mode which
2694corresponds to the C data type @code{double} and the @code{floorf}
2695built-in function uses the mode which corresponds to the C data
2696type @code{float}.
2698@cindex @code{trunc@var{m}2} instruction pattern
2699@item @samp{trunc@var{m}2}
2700Store the argument rounded to integer towards zero.
2702The @code{trunc} built-in function of C always uses the mode which
2703corresponds to the C data type @code{double} and the @code{truncf}
2704built-in function uses the mode which corresponds to the C data
2705type @code{float}.
2707@cindex @code{round@var{m}2} instruction pattern
2708@item @samp{round@var{m}2}
2709Store the argument rounded to integer away from zero.
2711The @code{round} built-in function of C always uses the mode which
2712corresponds to the C data type @code{double} and the @code{roundf}
2713built-in function uses the mode which corresponds to the C data
2714type @code{float}.
2716@cindex @code{ceil@var{m}2} instruction pattern
2717@item @samp{ceil@var{m}2}
2718Store the argument rounded to integer away from zero.
2720The @code{ceil} built-in function of C always uses the mode which
2721corresponds to the C data type @code{double} and the @code{ceilf}
2722built-in function uses the mode which corresponds to the C data
2723type @code{float}.
2725@cindex @code{nearbyint@var{m}2} instruction pattern
2726@item @samp{nearbyint@var{m}2}
2727Store the argument rounded according to the default rounding mode
2729The @code{nearbyint} built-in function of C always uses the mode which
2730corresponds to the C data type @code{double} and the @code{nearbyintf}
2731built-in function uses the mode which corresponds to the C data
2732type @code{float}.
2734@cindex @code{ffs@var{m}2} instruction pattern
2735@item @samp{ffs@var{m}2}
2736Store into operand 0 one plus the index of the least significant 1-bit
2737of operand 1. If operand 1 is zero, store zero. @var{m} is the mode
2738of operand 0; operand 1's mode is specified by the instruction
2739pattern, and the compiler will convert the operand to that mode before
2740generating the instruction.
2742The @code{ffs} built-in function of C always uses the mode which
2743corresponds to the C data type @code{int}.
2745@cindex @code{clz@var{m}2} instruction pattern
2746@item @samp{clz@var{m}2}
2747Store into operand 0 the number of leading 0-bits in @var{x}, starting
2748at the most significant bit position. If @var{x} is 0, the result is
2749undefined. @var{m} is the mode of operand 0; operand 1's mode is
2750specified by the instruction pattern, and the compiler will convert the
2751operand to that mode before generating the instruction.
2753@cindex @code{ctz@var{m}2} instruction pattern
2754@item @samp{ctz@var{m}2}
2755Store into operand 0 the number of trailing 0-bits in @var{x}, starting
2756at the least significant bit position. If @var{x} is 0, the result is
2757undefined. @var{m} is the mode of operand 0; operand 1's mode is
2758specified by the instruction pattern, and the compiler will convert the
2759operand to that mode before generating the instruction.
2761@cindex @code{popcount@var{m}2} instruction pattern
2762@item @samp{popcount@var{m}2}
2763Store into operand 0 the number of 1-bits in @var{x}. @var{m} is the
2764mode of operand 0; operand 1's mode is specified by the instruction
2765pattern, and the compiler will convert the operand to that mode before
2766generating the instruction.
2768@cindex @code{parity@var{m}2} instruction pattern
2769@item @samp{parity@var{m}2}
2770Store into operand 0 the parity of @var{x}, i.@:e. the number of 1-bits
2771in @var{x} modulo 2. @var{m} is the mode of operand 0; operand 1's mode
2772is specified by the instruction pattern, and the compiler will convert
2773the operand to that mode before generating the instruction.
2775@cindex @code{one_cmpl@var{m}2} instruction pattern
2776@item @samp{one_cmpl@var{m}2}
2777Store the bitwise-complement of operand 1 into operand 0.
2779@cindex @code{cmp@var{m}} instruction pattern
2780@item @samp{cmp@var{m}}
2781Compare operand 0 and operand 1, and set the condition codes.
2782The RTL pattern should look like this:
2785(set (cc0) (compare (match_operand:@var{m} 0 @dots{})
2786 (match_operand:@var{m} 1 @dots{})))
2787@end smallexample
2789@cindex @code{tst@var{m}} instruction pattern
2790@item @samp{tst@var{m}}
2791Compare operand 0 against zero, and set the condition codes.
2792The RTL pattern should look like this:
2795(set (cc0) (match_operand:@var{m} 0 @dots{}))
2796@end smallexample
2798@samp{tst@var{m}} patterns should not be defined for machines that do
2799not use @code{(cc0)}. Doing so would confuse the optimizer since it
2800would no longer be clear which @code{set} operations were comparisons.
2801The @samp{cmp@var{m}} patterns should be used instead.
2803@cindex @code{movstr@var{m}} instruction pattern
2804@item @samp{movstr@var{m}}
2805Block move instruction. The addresses of the destination and source
2806strings are the first two operands, and both are in mode @code{Pmode}.
2808The number of bytes to move is the third operand, in mode @var{m}.
2809Usually, you specify @code{word_mode} for @var{m}. However, if you can
2810generate better code knowing the range of valid lengths is smaller than
2811those representable in a full word, you should provide a pattern with a
2812mode corresponding to the range of values you can handle efficiently
2813(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
2814that appear negative) and also a pattern with @code{word_mode}.
2816The fourth operand is the known shared alignment of the source and
2817destination, in the form of a @code{const_int} rtx. Thus, if the
2818compiler knows that both source and destination are word-aligned,
2819it may provide the value 4 for this operand.
2821Descriptions of multiple @code{movstr@var{m}} patterns can only be
2822beneficial if the patterns for smaller modes have fewer restrictions
2823on their first, second and fourth operands. Note that the mode @var{m}
2824in @code{movstr@var{m}} does not impose any restriction on the mode of
2825individually moved data units in the block.
2827These patterns need not give special consideration to the possibility
2828that the source and destination strings might overlap.
2830@cindex @code{clrstr@var{m}} instruction pattern
2831@item @samp{clrstr@var{m}}
2832Block clear instruction. The addresses of the destination string is the
2833first operand, in mode @code{Pmode}. The number of bytes to clear is
2834the second operand, in mode @var{m}. See @samp{movstr@var{m}} for
2835a discussion of the choice of mode.
2837The third operand is the known alignment of the destination, in the form
2838of a @code{const_int} rtx. Thus, if the compiler knows that the
2839destination is word-aligned, it may provide the value 4 for this
2842The use for multiple @code{clrstr@var{m}} is as for @code{movstr@var{m}}.
2844@cindex @code{cmpstr@var{m}} instruction pattern
2845@item @samp{cmpstr@var{m}}
2846String compare instruction, with five operands. Operand 0 is the output;
2847it has mode @var{m}. The remaining four operands are like the operands
2848of @samp{movstr@var{m}}. The two memory blocks specified are compared
2849byte by byte in lexicographic order starting at the beginning of each
2850string. The instruction is not allowed to prefetch more than one byte
2851at a time since either string may end in the first byte and reading past
2852that may access an invalid page or segment and cause a fault. The
2853effect of the instruction is to store a value in operand 0 whose sign
2854indicates the result of the comparison.
2856@cindex @code{cmpmem@var{m}} instruction pattern
2857@item @samp{cmpmem@var{m}}
2858Block compare instruction, with five operands like the operands
2859of @samp{cmpstr@var{m}}. The two memory blocks specified are compared
2860byte by byte in lexicographic order starting at the beginning of each
2861block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch
2862any bytes in the two memory blocks. The effect of the instruction is
2863to store a value in operand 0 whose sign indicates the result of the
2866@cindex @code{strlen@var{m}} instruction pattern
2867@item @samp{strlen@var{m}}
2868Compute the length of a string, with three operands.
2869Operand 0 is the result (of mode @var{m}), operand 1 is
2870a @code{mem} referring to the first character of the string,
2871operand 2 is the character to search for (normally zero),
2872and operand 3 is a constant describing the known alignment
2873of the beginning of the string.
2875@cindex @code{float@var{mn}2} instruction pattern
2876@item @samp{float@var{m}@var{n}2}
2877Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
2878floating point mode @var{n} and store in operand 0 (which has mode
2881@cindex @code{floatuns@var{mn}2} instruction pattern
2882@item @samp{floatuns@var{m}@var{n}2}
2883Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
2884to floating point mode @var{n} and store in operand 0 (which has mode
2887@cindex @code{fix@var{mn}2} instruction pattern
2888@item @samp{fix@var{m}@var{n}2}
2889Convert operand 1 (valid for floating point mode @var{m}) to fixed
2890point mode @var{n} as a signed number and store in operand 0 (which
2891has mode @var{n}). This instruction's result is defined only when
2892the value of operand 1 is an integer.
2894@cindex @code{fixuns@var{mn}2} instruction pattern
2895@item @samp{fixuns@var{m}@var{n}2}
2896Convert operand 1 (valid for floating point mode @var{m}) to fixed
2897point mode @var{n} as an unsigned number and store in operand 0 (which
2898has mode @var{n}). This instruction's result is defined only when the
2899value of operand 1 is an integer.
2901@cindex @code{ftrunc@var{m}2} instruction pattern
2902@item @samp{ftrunc@var{m}2}
2903Convert operand 1 (valid for floating point mode @var{m}) to an
2904integer value, still represented in floating point mode @var{m}, and
2905store it in operand 0 (valid for floating point mode @var{m}).
2907@cindex @code{fix_trunc@var{mn}2} instruction pattern
2908@item @samp{fix_trunc@var{m}@var{n}2}
2909Like @samp{fix@var{m}@var{n}2} but works for any floating point value
2910of mode @var{m} by converting the value to an integer.
2912@cindex @code{fixuns_trunc@var{mn}2} instruction pattern
2913@item @samp{fixuns_trunc@var{m}@var{n}2}
2914Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
2915value of mode @var{m} by converting the value to an integer.
2917@cindex @code{trunc@var{mn}2} instruction pattern
2918@item @samp{trunc@var{m}@var{n}2}
2919Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
2920store in operand 0 (which has mode @var{n}). Both modes must be fixed
2921point or both floating point.
2923@cindex @code{extend@var{mn}2} instruction pattern
2924@item @samp{extend@var{m}@var{n}2}
2925Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
2926store in operand 0 (which has mode @var{n}). Both modes must be fixed
2927point or both floating point.
2929@cindex @code{zero_extend@var{mn}2} instruction pattern
2930@item @samp{zero_extend@var{m}@var{n}2}
2931Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
2932store in operand 0 (which has mode @var{n}). Both modes must be fixed
2935@cindex @code{extv} instruction pattern
2936@item @samp{extv}
2937Extract a bit-field from operand 1 (a register or memory operand), where
2938operand 2 specifies the width in bits and operand 3 the starting bit,
2939and store it in operand 0. Operand 0 must have mode @code{word_mode}.
2940Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
2941@code{word_mode} is allowed only for registers. Operands 2 and 3 must
2942be valid for @code{word_mode}.
2944The RTL generation pass generates this instruction only with constants
2945for operands 2 and 3.
2947The bit-field value is sign-extended to a full word integer
2948before it is stored in operand 0.
2950@cindex @code{extzv} instruction pattern
2951@item @samp{extzv}
2952Like @samp{extv} except that the bit-field value is zero-extended.
2954@cindex @code{insv} instruction pattern
2955@item @samp{insv}
2956Store operand 3 (which must be valid for @code{word_mode}) into a
2957bit-field in operand 0, where operand 1 specifies the width in bits and
2958operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or
2959@code{word_mode}; often @code{word_mode} is allowed only for registers.
2960Operands 1 and 2 must be valid for @code{word_mode}.
2962The RTL generation pass generates this instruction only with constants
2963for operands 1 and 2.
2965@cindex @code{mov@var{mode}cc} instruction pattern
2966@item @samp{mov@var{mode}cc}
2967Conditionally move operand 2 or operand 3 into operand 0 according to the
2968comparison in operand 1. If the comparison is true, operand 2 is moved
2969into operand 0, otherwise operand 3 is moved.
2971The mode of the operands being compared need not be the same as the operands
2972being moved. Some machines, sparc64 for example, have instructions that
2973conditionally move an integer value based on the floating point condition
2974codes and vice versa.
2976If the machine does not have conditional move instructions, do not
2977define these patterns.
2979@cindex @code{add@var{mode}cc} instruction pattern
2980@item @samp{add@var{mode}cc}
2981Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally
2982move operand 2 or (operands 2 + operand 3) into operand 0 according to the
2983comparison in operand 1. If the comparison is true, operand 2 is moved into
2984operand 0, otherwise (operand 2 + operand 3) is moved.
2986@cindex @code{s@var{cond}} instruction pattern
2987@item @samp{s@var{cond}}
2988Store zero or nonzero in the operand according to the condition codes.
2989Value stored is nonzero iff the condition @var{cond} is true.
2990@var{cond} is the name of a comparison operation expression code, such
2991as @code{eq}, @code{lt} or @code{leu}.
2993You specify the mode that the operand must have when you write the
2994@code{match_operand} expression. The compiler automatically sees
2995which mode you have used and supplies an operand of that mode.
2997The value stored for a true condition must have 1 as its low bit, or
2998else must be negative. Otherwise the instruction is not suitable and
2999you should omit it from the machine description. You describe to the
3000compiler exactly which value is stored by defining the macro
3001@code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be
3002found that can be used for all the @samp{s@var{cond}} patterns, you
3003should omit those operations from the machine description.
3005These operations may fail, but should do so only in relatively
3006uncommon cases; if they would fail for common cases involving
3007integer comparisons, it is best to omit these patterns.
3009If these operations are omitted, the compiler will usually generate code
3010that copies the constant one to the target and branches around an
3011assignment of zero to the target. If this code is more efficient than
3012the potential instructions used for the @samp{s@var{cond}} pattern
3013followed by those required to convert the result into a 1 or a zero in
3014@code{SImode}, you should omit the @samp{s@var{cond}} operations from
3015the machine description.
3017@cindex @code{b@var{cond}} instruction pattern
3018@item @samp{b@var{cond}}
3019Conditional branch instruction. Operand 0 is a @code{label_ref} that
3020refers to the label to jump to. Jump if the condition codes meet
3021condition @var{cond}.
3023Some machines do not follow the model assumed here where a comparison
3024instruction is followed by a conditional branch instruction. In that
3025case, the @samp{cmp@var{m}} (and @samp{tst@var{m}}) patterns should
3026simply store the operands away and generate all the required insns in a
3027@code{define_expand} (@pxref{Expander Definitions}) for the conditional
3028branch operations. All calls to expand @samp{b@var{cond}} patterns are
3029immediately preceded by calls to expand either a @samp{cmp@var{m}}
3030pattern or a @samp{tst@var{m}} pattern.
3032Machines that use a pseudo register for the condition code value, or
3033where the mode used for the comparison depends on the condition being
3034tested, should also use the above mechanism. @xref{Jump Patterns}.
3036The above discussion also applies to the @samp{mov@var{mode}cc} and
3037@samp{s@var{cond}} patterns.
3039@cindex @code{jump} instruction pattern
3040@item @samp{jump}
3041A jump inside a function; an unconditional branch. Operand 0 is the
3042@code{label_ref} of the label to jump to. This pattern name is mandatory
3043on all machines.
3045@cindex @code{call} instruction pattern
3046@item @samp{call}
3047Subroutine call instruction returning no value. Operand 0 is the
3048function to call; operand 1 is the number of bytes of arguments pushed
3049as a @code{const_int}; operand 2 is the number of registers used as
3052On most machines, operand 2 is not actually stored into the RTL
3053pattern. It is supplied for the sake of some RISC machines which need
3054to put this information into the assembler code; they can put it in
3055the RTL instead of operand 1.
3057Operand 0 should be a @code{mem} RTX whose address is the address of the
3058function. Note, however, that this address can be a @code{symbol_ref}
3059expression even if it would not be a legitimate memory address on the
3060target machine. If it is also not a valid argument for a call
3061instruction, the pattern for this operation should be a
3062@code{define_expand} (@pxref{Expander Definitions}) that places the
3063address into a register and uses that register in the call instruction.
3065@cindex @code{call_value} instruction pattern
3066@item @samp{call_value}
3067Subroutine call instruction returning a value. Operand 0 is the hard
3068register in which the value is returned. There are three more
3069operands, the same as the three operands of the @samp{call}
3070instruction (but with numbers increased by one).
3072Subroutines that return @code{BLKmode} objects use the @samp{call}
3075@cindex @code{call_pop} instruction pattern
3076@cindex @code{call_value_pop} instruction pattern
3077@item @samp{call_pop}, @samp{call_value_pop}
3078Similar to @samp{call} and @samp{call_value}, except used if defined and
3079if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel}
3080that contains both the function call and a @code{set} to indicate the
3081adjustment made to the frame pointer.
3083For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
3084patterns increases the number of functions for which the frame pointer
3085can be eliminated, if desired.
3087@cindex @code{untyped_call} instruction pattern
3088@item @samp{untyped_call}
3089Subroutine call instruction returning a value of any type. Operand 0 is
3090the function to call; operand 1 is a memory location where the result of
3091calling the function is to be stored; operand 2 is a @code{parallel}
3092expression where each element is a @code{set} expression that indicates
3093the saving of a function return value into the result block.
3095This instruction pattern should be defined to support
3096@code{__builtin_apply} on machines where special instructions are needed
3097to call a subroutine with arbitrary arguments or to save the value
3098returned. This instruction pattern is required on machines that have
3099multiple registers that can hold a return value
3100(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
3102@cindex @code{return} instruction pattern
3103@item @samp{return}
3104Subroutine return instruction. This instruction pattern name should be
3105defined only if a single instruction can do all the work of returning
3106from a function.
3108Like the @samp{mov@var{m}} patterns, this pattern is also used after the
3109RTL generation phase. In this case it is to support machines where
3110multiple instructions are usually needed to return from a function, but
3111some class of functions only requires one instruction to implement a
3112return. Normally, the applicable functions are those which do not need
3113to save any registers or allocate stack space.
3115@findex reload_completed
3116@findex leaf_function_p
3117For such machines, the condition specified in this pattern should only
3118be true when @code{reload_completed} is nonzero and the function's
3119epilogue would only be a single instruction. For machines with register
3120windows, the routine @code{leaf_function_p} may be used to determine if
3121a register window push is required.
3123Machines that have conditional return instructions should define patterns
3124such as
3127(define_insn ""
3128 [(set (pc)
3129 (if_then_else (match_operator
3130 0 "comparison_operator"
3131 [(cc0) (const_int 0)])
3132 (return)
3133 (pc)))]
3134 "@var{condition}"
3135 "@dots{}")
3136@end smallexample
3138where @var{condition} would normally be the same condition specified on the
3139named @samp{return} pattern.
3141@cindex @code{untyped_return} instruction pattern
3142@item @samp{untyped_return}
3143Untyped subroutine return instruction. This instruction pattern should
3144be defined to support @code{__builtin_return} on machines where special
3145instructions are needed to return a value of any type.
3147Operand 0 is a memory location where the result of calling a function
3148with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
3149expression where each element is a @code{set} expression that indicates
3150the restoring of a function return value from the result block.
3152@cindex @code{nop} instruction pattern
3153@item @samp{nop}
3154No-op instruction. This instruction pattern name should always be defined
3155to output a no-op in assembler code. @code{(const_int 0)} will do as an
3156RTL pattern.
3158@cindex @code{indirect_jump} instruction pattern
3159@item @samp{indirect_jump}
3160An instruction to jump to an address which is operand zero.
3161This pattern name is mandatory on all machines.
3163@cindex @code{casesi} instruction pattern
3164@item @samp{casesi}
3165Instruction to jump through a dispatch table, including bounds checking.
3166This instruction takes five operands:
3170The index to dispatch on, which has mode @code{SImode}.
3173The lower bound for indices in the table, an integer constant.
3176The total range of indices in the table---the largest index
3177minus the smallest one (both inclusive).
3180A label that precedes the table itself.
3183A label to jump to if the index has a value outside the bounds.
3184(If the machine-description macro @code{CASE_DROPS_THROUGH} is defined,
3185then an out-of-bounds index drops through to the code following
3186the jump table instead of jumping to this label. In that case,
3187this label is not actually used by the @samp{casesi} instruction,
3188but it is always provided as an operand.)
3189@end enumerate
3191The table is a @code{addr_vec} or @code{addr_diff_vec} inside of a
3192@code{jump_insn}. The number of elements in the table is one plus the
3193difference between the upper bound and the lower bound.
3195@cindex @code{tablejump} instruction pattern
3196@item @samp{tablejump}
3197Instruction to jump to a variable address. This is a low-level
3198capability which can be used to implement a dispatch table when there
3199is no @samp{casesi} pattern.
3201This pattern requires two operands: the address or offset, and a label
3202which should immediately precede the jump table. If the macro
3203@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
3204operand is an offset which counts from the address of the table; otherwise,
3205it is an absolute address to jump to. In either case, the first operand has
3206mode @code{Pmode}.
3208The @samp{tablejump} insn is always the last insn before the jump
3209table it uses. Its assembler code normally has no need to use the
3210second operand, but you should incorporate it in the RTL pattern so
3211that the jump optimizer will not delete the table as unreachable code.
3214@cindex @code{decrement_and_branch_until_zero} instruction pattern
3215@item @samp{decrement_and_branch_until_zero}
3216Conditional branch instruction that decrements a register and
3217jumps if the register is nonzero. Operand 0 is the register to
3218decrement and test; operand 1 is the label to jump to if the
3219register is nonzero. @xref{Looping Patterns}.
3221This optional instruction pattern is only used by the combiner,
3222typically for loops reversed by the loop optimizer when strength
3223reduction is enabled.
3225@cindex @code{doloop_end} instruction pattern
3226@item @samp{doloop_end}
3227Conditional branch instruction that decrements a register and jumps if
3228the register is nonzero. This instruction takes five operands: Operand
32290 is the register to decrement and test; operand 1 is the number of loop
3230iterations as a @code{const_int} or @code{const0_rtx} if this cannot be
3231determined until run-time; operand 2 is the actual or estimated maximum
3232number of iterations as a @code{const_int}; operand 3 is the number of
3233enclosed loops as a @code{const_int} (an innermost loop has a value of
32341); operand 4 is the label to jump to if the register is nonzero.
3235@xref{Looping Patterns}.
3237This optional instruction pattern should be defined for machines with
3238low-overhead looping instructions as the loop optimizer will try to
3239modify suitable loops to utilize it. If nested low-overhead looping is
3240not supported, use a @code{define_expand} (@pxref{Expander Definitions})
3241and make the pattern fail if operand 3 is not @code{const1_rtx}.
3242Similarly, if the actual or estimated maximum number of iterations is
3243too large for this instruction, make it fail.
3245@cindex @code{doloop_begin} instruction pattern
3246@item @samp{doloop_begin}
3247Companion instruction to @code{doloop_end} required for machines that
3248need to perform some initialization, such as loading special registers
3249used by a low-overhead looping instruction. If initialization insns do
3250not always need to be emitted, use a @code{define_expand}
3251(@pxref{Expander Definitions}) and make it fail.
3254@cindex @code{canonicalize_funcptr_for_compare} instruction pattern
3255@item @samp{canonicalize_funcptr_for_compare}
3256Canonicalize the function pointer in operand 1 and store the result
3257into operand 0.
3259Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
3260may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
3261and also has mode @code{Pmode}.
3263Canonicalization of a function pointer usually involves computing
3264the address of the function which would be called if the function
3265pointer were used in an indirect call.
3267Only define this pattern if function pointers on the target machine
3268can have different values but still call the same function when
3269used in an indirect call.
3271@cindex @code{save_stack_block} instruction pattern
3272@cindex @code{save_stack_function} instruction pattern
3273@cindex @code{save_stack_nonlocal} instruction pattern
3274@cindex @code{restore_stack_block} instruction pattern
3275@cindex @code{restore_stack_function} instruction pattern
3276@cindex @code{restore_stack_nonlocal} instruction pattern
3277@item @samp{save_stack_block}
3278@itemx @samp{save_stack_function}
3279@itemx @samp{save_stack_nonlocal}
3280@itemx @samp{restore_stack_block}
3281@itemx @samp{restore_stack_function}
3282@itemx @samp{restore_stack_nonlocal}
3283Most machines save and restore the stack pointer by copying it to or
3284from an object of mode @code{Pmode}. Do not define these patterns on
3285such machines.
3287Some machines require special handling for stack pointer saves and
3288restores. On those machines, define the patterns corresponding to the
3289non-standard cases by using a @code{define_expand} (@pxref{Expander
3290Definitions}) that produces the required insns. The three types of
3291saves and restores are:
3295@samp{save_stack_block} saves the stack pointer at the start of a block
3296that allocates a variable-sized object, and @samp{restore_stack_block}
3297restores the stack pointer when the block is exited.
3300@samp{save_stack_function} and @samp{restore_stack_function} do a
3301similar job for the outermost block of a function and are used when the
3302function allocates variable-sized objects or calls @code{alloca}. Only
3303the epilogue uses the restored stack pointer, allowing a simpler save or
3304restore sequence on some machines.
3307@samp{save_stack_nonlocal} is used in functions that contain labels
3308branched to by nested functions. It saves the stack pointer in such a
3309way that the inner function can use @samp{restore_stack_nonlocal} to
3310restore the stack pointer. The compiler generates code to restore the
3311frame and argument pointer registers, but some machines require saving
3312and restoring additional data such as register window information or
3313stack backchains. Place insns in these patterns to save and restore any
3314such required data.
3315@end enumerate
3317When saving the stack pointer, operand 0 is the save area and operand 1
3318is the stack pointer. The mode used to allocate the save area defaults
3319to @code{Pmode} but you can override that choice by defining the
3320@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must
3321specify an integral mode, or @code{VOIDmode} if no save area is needed
3322for a particular type of save (either because no save is needed or
3323because a machine-specific save area can be used). Operand 0 is the
3324stack pointer and operand 1 is the save area for restore operations. If
3325@samp{save_stack_block} is defined, operand 0 must not be
3326@code{VOIDmode} since these saves can be arbitrarily nested.
3328A save area is a @code{mem} that is at a constant offset from
3329@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
3330nonlocal gotos and a @code{reg} in the other two cases.
3332@cindex @code{allocate_stack} instruction pattern
3333@item @samp{allocate_stack}
3334Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
3335the stack pointer to create space for dynamically allocated data.
3337Store the resultant pointer to this space into operand 0. If you
3338are allocating space from the main stack, do this by emitting a
3339move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
3340If you are allocating the space elsewhere, generate code to copy the
3341location of the space to operand 0. In the latter case, you must
3342ensure this space gets freed when the corresponding space on the main
3343stack is free.
3345Do not define this pattern if all that must be done is the subtraction.
3346Some machines require other operations such as stack probes or
3347maintaining the back chain. Define this pattern to emit those
3348operations in addition to updating the stack pointer.
3350@cindex @code{check_stack} instruction pattern
3351@item @samp{check_stack}
3352If stack checking cannot be done on your system by probing the stack with
3353a load or store instruction (@pxref{Stack Checking}), define this pattern
3354to perform the needed check and signaling an error if the stack
3355has overflowed. The single operand is the location in the stack furthest
3356from the current stack pointer that you need to validate. Normally,
3357on machines where this pattern is needed, you would obtain the stack
3358limit from a global or thread-specific variable or register.
3360@cindex @code{nonlocal_goto} instruction pattern
3361@item @samp{nonlocal_goto}
3362Emit code to generate a non-local goto, e.g., a jump from one function
3363to a label in an outer function. This pattern has four arguments,
3364each representing a value to be used in the jump. The first
3365argument is to be loaded into the frame pointer, the second is
3366the address to branch to (code to dispatch to the actual label),
3367the third is the address of a location where the stack is saved,
3368and the last is the address of the label, to be placed in the
3369location for the incoming static chain.
3371On most machines you need not define this pattern, since GCC will
3372already generate the correct code, which is to load the frame pointer
3373and static chain, restore the stack (using the
3374@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
3375to the dispatcher. You need only define this pattern if this code will
3376not work on your machine.
3378@cindex @code{nonlocal_goto_receiver} instruction pattern
3379@item @samp{nonlocal_goto_receiver}
3380This pattern, if defined, contains code needed at the target of a
3381nonlocal goto after the code already generated by GCC@. You will not
3382normally need to define this pattern. A typical reason why you might
3383need this pattern is if some value, such as a pointer to a global table,
3384must be restored when the frame pointer is restored. Note that a nonlocal
3385goto only occurs within a unit-of-translation, so a global table pointer
3386that is shared by all functions of a given module need not be restored.
3387There are no arguments.
3389@cindex @code{exception_receiver} instruction pattern
3390@item @samp{exception_receiver}
3391This pattern, if defined, contains code needed at the site of an
3392exception handler that isn't needed at the site of a nonlocal goto. You
3393will not normally need to define this pattern. A typical reason why you
3394might need this pattern is if some value, such as a pointer to a global
3395table, must be restored after control flow is branched to the handler of
3396an exception. There are no arguments.
3398@cindex @code{builtin_setjmp_setup} instruction pattern
3399@item @samp{builtin_setjmp_setup}
3400This pattern, if defined, contains additional code needed to initialize
3401the @code{jmp_buf}. You will not normally need to define this pattern.
3402A typical reason why you might need this pattern is if some value, such
3403as a pointer to a global table, must be restored. Though it is
3404preferred that the pointer value be recalculated if possible (given the
3405address of a label for instance). The single argument is a pointer to
3406the @code{jmp_buf}. Note that the buffer is five words long and that
3407the first three are normally used by the generic mechanism.
3409@cindex @code{builtin_setjmp_receiver} instruction pattern
3410@item @samp{builtin_setjmp_receiver}
3411This pattern, if defined, contains code needed at the site of an
3412built-in setjmp that isn't needed at the site of a nonlocal goto. You
3413will not normally need to define this pattern. A typical reason why you
3414might need this pattern is if some value, such as a pointer to a global
3415table, must be restored. It takes one argument, which is the label
3416to which builtin_longjmp transfered control; this pattern may be emitted
3417at a small offset from that label.
3419@cindex @code{builtin_longjmp} instruction pattern
3420@item @samp{builtin_longjmp}
3421This pattern, if defined, performs the entire action of the longjmp.
3422You will not normally need to define this pattern unless you also define
3423@code{builtin_setjmp_setup}. The single argument is a pointer to the
3426@cindex @code{eh_return} instruction pattern
3427@item @samp{eh_return}
3428This pattern, if defined, affects the way @code{__builtin_eh_return},
3429and thence the call frame exception handling library routines, are
3430built. It is intended to handle non-trivial actions needed along
3431the abnormal return path.
3433The address of the exception handler to which the function should return
3434is passed as operand to this pattern. It will normally need to copied by
3435the pattern to some special register or memory location.
3436If the pattern needs to determine the location of the target call
3437frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
3438if defined; it will have already been assigned.
3440If this pattern is not defined, the default action will be to simply
3441copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either
3442that macro or this pattern needs to be defined if call frame exception
3443handling is to be used.
3445@cindex @code{prologue} instruction pattern
3446@anchor{prologue instruction pattern}
3447@item @samp{prologue}
3448This pattern, if defined, emits RTL for entry to a function. The function
3449entry is responsible for setting up the stack frame, initializing the frame
3450pointer register, saving callee saved registers, etc.
3452Using a prologue pattern is generally preferred over defining
3453@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
3455The @code{prologue} pattern is particularly useful for targets which perform
3456instruction scheduling.
3458@cindex @code{epilogue} instruction pattern
3459@anchor{epilogue instruction pattern}
3460@item @samp{epilogue}
3461This pattern emits RTL for exit from a function. The function
3462exit is responsible for deallocating the stack frame, restoring callee saved
3463registers and emitting the return instruction.
3465Using an epilogue pattern is generally preferred over defining
3466@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
3468The @code{epilogue} pattern is particularly useful for targets which perform
3469instruction scheduling or which have delay slots for their return instruction.
3471@cindex @code{sibcall_epilogue} instruction pattern
3472@item @samp{sibcall_epilogue}
3473This pattern, if defined, emits RTL for exit from a function without the final
3474branch back to the calling function. This pattern will be emitted before any
3475sibling call (aka tail call) sites.
3477The @code{sibcall_epilogue} pattern must not clobber any arguments used for
3478parameter passing or any stack slots for arguments passed to the current
3481@cindex @code{trap} instruction pattern
3482@item @samp{trap}
3483This pattern, if defined, signals an error, typically by causing some
3484kind of signal to be raised. Among other places, it is used by the Java
3485front end to signal `invalid array index' exceptions.
3487@cindex @code{conditional_trap} instruction pattern
3488@item @samp{conditional_trap}
3489Conditional trap instruction. Operand 0 is a piece of RTL which
3490performs a comparison. Operand 1 is the trap code, an integer.
3492A typical @code{conditional_trap} pattern looks like
3495(define_insn "conditional_trap"
3496 [(trap_if (match_operator 0 "trap_operator"
3497 [(cc0) (const_int 0)])
3498 (match_operand 1 "const_int_operand" "i"))]
3499 ""
3500 "@dots{}")
3501@end smallexample
3503@cindex @code{prefetch} instruction pattern
3504@item @samp{prefetch}
3506This pattern, if defined, emits code for a non-faulting data prefetch
3507instruction. Operand 0 is the address of the memory to prefetch. Operand 1
3508is a constant 1 if the prefetch is preparing for a write to the memory
3509address, or a constant 0 otherwise. Operand 2 is the expected degree of
3510temporal locality of the data and is a value between 0 and 3, inclusive; 0
3511means that the data has no temporal locality, so it need not be left in the
3512cache after the access; 3 means that the data has a high degree of temporal
3513locality and should be left in all levels of cache possible; 1 and 2 mean,
3514respectively, a low or moderate degree of temporal locality.
3516Targets that do not support write prefetches or locality hints can ignore
3517the values of operands 1 and 2.
3519@end table
3521@end ifset
3522@c Each of the following nodes are wrapped in separate
3523@c "@ifset INTERNALS" to work around memory limits for the default
3524@c configuration in older tetex distributions. Known to not work:
3525@c tetex-1.0.7, known to work: tetex-2.0.2.
3526@ifset INTERNALS
3527@node Pattern Ordering
3528@section When the Order of Patterns Matters
3529@cindex Pattern Ordering
3530@cindex Ordering of Patterns
3532Sometimes an insn can match more than one instruction pattern. Then the
3533pattern that appears first in the machine description is the one used.
3534Therefore, more specific patterns (patterns that will match fewer things)
3535and faster instructions (those that will produce better code when they
3536do match) should usually go first in the description.
3538In some cases the effect of ordering the patterns can be used to hide
3539a pattern when it is not valid. For example, the 68000 has an
3540instruction for converting a fullword to floating point and another
3541for converting a byte to floating point. An instruction converting
3542an integer to floating point could match either one. We put the
3543pattern to convert the fullword first to make sure that one will
3544be used rather than the other. (Otherwise a large integer might
3545be generated as a single-byte immediate quantity, which would not work.)
3546Instead of using this pattern ordering it would be possible to make the
3547pattern for convert-a-byte smart enough to deal properly with any
3548constant value.
3550@end ifset
3551@ifset INTERNALS
3552@node Dependent Patterns
3553@section Interdependence of Patterns
3554@cindex Dependent Patterns
3555@cindex Interdependence of Patterns
3557Every machine description must have a named pattern for each of the
3558conditional branch names @samp{b@var{cond}}. The recognition template
3559must always have the form
3562(set (pc)
3563 (if_then_else (@var{cond} (cc0) (const_int 0))
3564 (label_ref (match_operand 0 "" ""))
3565 (pc)))
3566@end smallexample
3569In addition, every machine description must have an anonymous pattern
3570for each of the possible reverse-conditional branches. Their templates
3571look like
3574(set (pc)
3575 (if_then_else (@var{cond} (cc0) (const_int 0))
3576 (pc)
3577 (label_ref (match_operand 0 "" ""))))
3578@end smallexample
3581They are necessary because jump optimization can turn direct-conditional
3582branches into reverse-conditional branches.
3584It is often convenient to use the @code{match_operator} construct to
3585reduce the number of patterns that must be specified for branches. For
3589(define_insn ""
3590 [(set (pc)
3591 (if_then_else (match_operator 0 "comparison_operator"
3592 [(cc0) (const_int 0)])
3593 (pc)
3594 (label_ref (match_operand 1 "" ""))))]
3595 "@var{condition}"
3596 "@dots{}")
3597@end smallexample
3599In some cases machines support instructions identical except for the
3600machine mode of one or more operands. For example, there may be
3601``sign-extend halfword'' and ``sign-extend byte'' instructions whose
3602patterns are
3605(set (match_operand:SI 0 @dots{})
3606 (extend:SI (match_operand:HI 1 @dots{})))
3608(set (match_operand:SI 0 @dots{})
3609 (extend:SI (match_operand:QI 1 @dots{})))
3610@end smallexample
3613Constant integers do not specify a machine mode, so an instruction to
3614extend a constant value could match either pattern. The pattern it
3615actually will match is the one that appears first in the file. For correct
3616results, this must be the one for the widest possible mode (@code{HImode},
3617here). If the pattern matches the @code{QImode} instruction, the results
3618will be incorrect if the constant value does not actually fit that mode.
3620Such instructions to extend constants are rarely generated because they are
3621optimized away, but they do occasionally happen in nonoptimized
3624If a constraint in a pattern allows a constant, the reload pass may
3625replace a register with a constant permitted by the constraint in some
3626cases. Similarly for memory references. Because of this substitution,
3627you should not provide separate patterns for increment and decrement
3628instructions. Instead, they should be generated from the same pattern
3629that supports register-register add insns by examining the operands and
3630generating the appropriate machine instruction.
3632@end ifset
3633@ifset INTERNALS
3634@node Jump Patterns
3635@section Defining Jump Instruction Patterns
3636@cindex jump instruction patterns
3637@cindex defining jump instruction patterns
3639For most machines, GCC assumes that the machine has a condition code.
3640A comparison insn sets the condition code, recording the results of both
3641signed and unsigned comparison of the given operands. A separate branch
3642insn tests the condition code and branches or not according its value.
3643The branch insns come in distinct signed and unsigned flavors. Many
3644common machines, such as the VAX, the 68000 and the 32000, work this
3647Some machines have distinct signed and unsigned compare instructions, and
3648only one set of conditional branch instructions. The easiest way to handle
3649these machines is to treat them just like the others until the final stage
3650where assembly code is written. At this time, when outputting code for the
3651compare instruction, peek ahead at the following branch using
3652@code{next_cc0_user (insn)}. (The variable @code{insn} refers to the insn
3653being output, in the output-writing code in an instruction pattern.) If
3654the RTL says that is an unsigned branch, output an unsigned compare;
3655otherwise output a signed compare. When the branch itself is output, you
3656can treat signed and unsigned branches identically.
3658The reason you can do this is that GCC always generates a pair of
3659consecutive RTL insns, possibly separated by @code{note} insns, one to
3660set the condition code and one to test it, and keeps the pair inviolate
3661until the end.
3663To go with this technique, you must define the machine-description macro
3664@code{NOTICE_UPDATE_CC} to do @code{CC_STATUS_INIT}; in other words, no
3665compare instruction is superfluous.
3667Some machines have compare-and-branch instructions and no condition code.
3668A similar technique works for them. When it is time to ``output'' a
3669compare instruction, record its operands in two static variables. When
3670outputting the branch-on-condition-code instruction that follows, actually
3671output a compare-and-branch instruction that uses the remembered operands.
3673It also works to define patterns for compare-and-branch instructions.
3674In optimizing compilation, the pair of compare and branch instructions
3675will be combined according to these patterns. But this does not happen
3676if optimization is not requested. So you must use one of the solutions
3677above in addition to any special patterns you define.
3679In many RISC machines, most instructions do not affect the condition
3680code and there may not even be a separate condition code register. On
3681these machines, the restriction that the definition and use of the
3682condition code be adjacent insns is not necessary and can prevent
3683important optimizations. For example, on the IBM RS/6000, there is a
3684delay for taken branches unless the condition code register is set three
3685instructions earlier than the conditional branch. The instruction
3686scheduler cannot perform this optimization if it is not permitted to
3687separate the definition and use of the condition code register.
3689On these machines, do not use @code{(cc0)}, but instead use a register
3690to represent the condition code. If there is a specific condition code
3691register in the machine, use a hard register. If the condition code or
3692comparison result can be placed in any general register, or if there are
3693multiple condition registers, use a pseudo register.
3695@findex prev_cc0_setter
3696@findex next_cc0_user
3697On some machines, the type of branch instruction generated may depend on
3698the way the condition code was produced; for example, on the 68k and
3699SPARC, setting the condition code directly from an add or subtract
3700instruction does not clear the overflow bit the way that a test
3701instruction does, so a different branch instruction must be used for
3702some conditional branches. For machines that use @code{(cc0)}, the set
3703and use of the condition code must be adjacent (separated only by
3704@code{note} insns) allowing flags in @code{cc_status} to be used.
3705(@xref{Condition Code}.) Also, the comparison and branch insns can be
3706located from each other by using the functions @code{prev_cc0_setter}
3707and @code{next_cc0_user}.
3709However, this is not true on machines that do not use @code{(cc0)}. On
3710those machines, no assumptions can be made about the adjacency of the
3711compare and branch insns and the above methods cannot be used. Instead,
3712we use the machine mode of the condition code register to record
3713different formats of the condition code register.
3715Registers used to store the condition code value should have a mode that
3716is in class @code{MODE_CC}. Normally, it will be @code{CCmode}. If
3717additional modes are required (as for the add example mentioned above in
3718the SPARC), define the macro @code{EXTRA_CC_MODES} to list the
3719additional modes required (@pxref{Condition Code}). Also define
3720@code{SELECT_CC_MODE} to choose a mode given an operand of a compare.
3722If it is known during RTL generation that a different mode will be
3723required (for example, if the machine has separate compare instructions
3724for signed and unsigned quantities, like most IBM processors), they can
3725be specified at that time.
3727If the cases that require different modes would be made by instruction
3728combination, the macro @code{SELECT_CC_MODE} determines which machine
3729mode should be used for the comparison result. The patterns should be
3730written using that mode. To support the case of the add on the SPARC
3731discussed above, we have the pattern
3734(define_insn ""
3735 [(set (reg:CC_NOOV 0)
3736 (compare:CC_NOOV
3737 (plus:SI (match_operand:SI 0 "register_operand" "%r")
3738 (match_operand:SI 1 "arith_operand" "rI"))
3739 (const_int 0)))]
3740 ""
3741 "@dots{}")
3742@end smallexample
3744The @code{SELECT_CC_MODE} macro on the SPARC returns @code{CC_NOOVmode}
3745for comparisons whose argument is a @code{plus}.
3747@end ifset
3748@ifset INTERNALS
3749@node Looping Patterns
3750@section Defining Looping Instruction Patterns
3751@cindex looping instruction patterns
3752@cindex defining looping instruction patterns
3754Some machines have special jump instructions that can be utilized to
3755make loops more efficient. A common example is the 68000 @samp{dbra}
3756instruction which performs a decrement of a register and a branch if the
3757result was greater than zero. Other machines, in particular digital
3758signal processors (DSPs), have special block repeat instructions to
3759provide low-overhead loop support. For example, the TI TMS320C3x/C4x
3760DSPs have a block repeat instruction that loads special registers to
3761mark the top and end of a loop and to count the number of loop
3762iterations. This avoids the need for fetching and executing a