xref: /dragonfly/contrib/gcc-4.7/gcc/doc/md.texi (revision e4b17023)
1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
2@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
3@c Free Software Foundation, Inc.
4@c This is part of the GCC manual.
5@c For copying conditions, see the file gcc.texi.
6
7@ifset INTERNALS
8@node Machine Desc
9@chapter Machine Descriptions
10@cindex machine descriptions
11
12A machine description has two parts: a file of instruction patterns
13(@file{.md} file) and a C header file of macro definitions.
14
15The @file{.md} file for a target machine contains a pattern for each
16instruction that the target machine supports (or at least each instruction
17that is worth telling the compiler about).  It may also contain comments.
18A semicolon causes the rest of the line to be a comment, unless the semicolon
19is inside a quoted string.
20
21See the next chapter for information on the C header file.
22
23@menu
24* Overview::            How the machine description is used.
25* Patterns::            How to write instruction patterns.
26* Example::             An explained example of a @code{define_insn} pattern.
27* RTL Template::        The RTL template defines what insns match a pattern.
28* Output Template::     The output template says how to make assembler code
29                        from such an insn.
30* Output Statement::    For more generality, write C code to output
31                        the assembler code.
32* Predicates::          Controlling what kinds of operands can be used
33                        for an insn.
34* Constraints::         Fine-tuning operand selection.
35* Standard Names::      Names mark patterns to use for code generation.
36* Pattern Ordering::    When the order of patterns makes a difference.
37* Dependent Patterns::  Having one pattern may make you need another.
38* Jump Patterns::       Special considerations for patterns for jump insns.
39* Looping Patterns::    How to define patterns for special looping insns.
40* Insn Canonicalizations::Canonicalization of Instructions
41* Expander Definitions::Generating a sequence of several RTL insns
42                        for a standard operation.
43* Insn Splitting::      Splitting Instructions into Multiple Instructions.
44* Including Patterns::  Including Patterns in Machine Descriptions.
45* Peephole Definitions::Defining machine-specific peephole optimizations.
46* Insn Attributes::     Specifying the value of attributes for generated insns.
47* Conditional Execution::Generating @code{define_insn} patterns for
48                         predication.
49* Constant Definitions::Defining symbolic constants that can be used in the
50                        md file.
51* Iterators::           Using iterators to generate patterns from a template.
52@end menu
53
54@node Overview
55@section Overview of How the Machine Description is Used
56
57There are three main conversions that happen in the compiler:
58
59@enumerate
60
61@item
62The front end reads the source code and builds a parse tree.
63
64@item
65The parse tree is used to generate an RTL insn list based on named
66instruction patterns.
67
68@item
69The insn list is matched against the RTL templates to produce assembler
70code.
71
72@end enumerate
73
74For the generate pass, only the names of the insns matter, from either a
75named @code{define_insn} or a @code{define_expand}.  The compiler will
76choose the pattern with the right name and apply the operands according
77to the documentation later in this chapter, without regard for the RTL
78template or operand constraints.  Note that the names the compiler looks
79for are hard-coded in the compiler---it will ignore unnamed patterns and
80patterns with names it doesn't know about, but if you don't provide a
81named pattern it needs, it will abort.
82
83If a @code{define_insn} is used, the template given is inserted into the
84insn list.  If a @code{define_expand} is used, one of three things
85happens, based on the condition logic.  The condition logic may manually
86create new insns for the insn list, say via @code{emit_insn()}, and
87invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
88compiler to use an alternate way of performing that task.  If it invokes
89neither @code{DONE} nor @code{FAIL}, the template given in the pattern
90is inserted, as if the @code{define_expand} were a @code{define_insn}.
91
92Once the insn list is generated, various optimization passes convert,
93replace, and rearrange the insns in the insn list.  This is where the
94@code{define_split} and @code{define_peephole} patterns get used, for
95example.
96
97Finally, the insn list's RTL is matched up with the RTL templates in the
98@code{define_insn} patterns, and those patterns are used to emit the
99final assembly code.  For this purpose, each named @code{define_insn}
100acts like it's unnamed, since the names are ignored.
101
102@node Patterns
103@section Everything about Instruction Patterns
104@cindex patterns
105@cindex instruction patterns
106
107@findex define_insn
108Each instruction pattern contains an incomplete RTL expression, with pieces
109to be filled in later, operand constraints that restrict how the pieces can
110be filled in, and an output pattern or C code to generate the assembler
111output, all wrapped up in a @code{define_insn} expression.
112
113A @code{define_insn} is an RTL expression containing four or five operands:
114
115@enumerate
116@item
117An optional name.  The presence of a name indicate that this instruction
118pattern can perform a certain standard job for the RTL-generation
119pass of the compiler.  This pass knows certain names and will use
120the instruction patterns with those names, if the names are defined
121in the machine description.
122
123The absence of a name is indicated by writing an empty string
124where the name should go.  Nameless instruction patterns are never
125used for generating RTL code, but they may permit several simpler insns
126to be combined later on.
127
128Names that are not thus known and used in RTL-generation have no
129effect; they are equivalent to no name at all.
130
131For the purpose of debugging the compiler, you may also specify a
132name beginning with the @samp{*} character.  Such a name is used only
133for identifying the instruction in RTL dumps; it is entirely equivalent
134to having a nameless pattern for all other purposes.
135
136@item
137The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
138RTL expressions which show what the instruction should look like.  It is
139incomplete because it may contain @code{match_operand},
140@code{match_operator}, and @code{match_dup} expressions that stand for
141operands of the instruction.
142
143If the vector has only one element, that element is the template for the
144instruction pattern.  If the vector has multiple elements, then the
145instruction pattern is a @code{parallel} expression containing the
146elements described.
147
148@item
149@cindex pattern conditions
150@cindex conditions, in patterns
151A condition.  This is a string which contains a C expression that is
152the final test to decide whether an insn body matches this pattern.
153
154@cindex named patterns and conditions
155For a named pattern, the condition (if present) may not depend on
156the data in the insn being matched, but only the target-machine-type
157flags.  The compiler needs to test these conditions during
158initialization in order to learn exactly which named instructions are
159available in a particular run.
160
161@findex operands
162For nameless patterns, the condition is applied only when matching an
163individual insn, and only after the insn has matched the pattern's
164recognition template.  The insn's operands may be found in the vector
165@code{operands}.  For an insn where the condition has once matched, it
166can't be used to control register allocation, for example by excluding
167certain hard registers or hard register combinations.
168
169@item
170The @dfn{output template}: a string that says how to output matching
171insns as assembler code.  @samp{%} in this string specifies where
172to substitute the value of an operand.  @xref{Output Template}.
173
174When simple substitution isn't general enough, you can specify a piece
175of C code to compute the output.  @xref{Output Statement}.
176
177@item
178Optionally, a vector containing the values of attributes for insns matching
179this pattern.  @xref{Insn Attributes}.
180@end enumerate
181
182@node Example
183@section Example of @code{define_insn}
184@cindex @code{define_insn} example
185
186Here is an actual example of an instruction pattern, for the 68000/68020.
187
188@smallexample
189(define_insn "tstsi"
190  [(set (cc0)
191        (match_operand:SI 0 "general_operand" "rm"))]
192  ""
193  "*
194@{
195  if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
196    return \"tstl %0\";
197  return \"cmpl #0,%0\";
198@}")
199@end smallexample
200
201@noindent
202This can also be written using braced strings:
203
204@smallexample
205(define_insn "tstsi"
206  [(set (cc0)
207        (match_operand:SI 0 "general_operand" "rm"))]
208  ""
209@{
210  if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
211    return "tstl %0";
212  return "cmpl #0,%0";
213@})
214@end smallexample
215
216This is an instruction that sets the condition codes based on the value of
217a general operand.  It has no condition, so any insn whose RTL description
218has the form shown may be handled according to this pattern.  The name
219@samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL generation
220pass that, when it is necessary to test such a value, an insn to do so
221can be constructed using this pattern.
222
223The output control string is a piece of C code which chooses which
224output template to return based on the kind of operand and the specific
225type of CPU for which code is being generated.
226
227@samp{"rm"} is an operand constraint.  Its meaning is explained below.
228
229@node RTL Template
230@section RTL Template
231@cindex RTL insn template
232@cindex generating insns
233@cindex insns, generating
234@cindex recognizing insns
235@cindex insns, recognizing
236
237The RTL template is used to define which insns match the particular pattern
238and how to find their operands.  For named patterns, the RTL template also
239says how to construct an insn from specified operands.
240
241Construction involves substituting specified operands into a copy of the
242template.  Matching involves determining the values that serve as the
243operands in the insn being matched.  Both of these activities are
244controlled by special expression types that direct matching and
245substitution of the operands.
246
247@table @code
248@findex match_operand
249@item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
250This expression is a placeholder for operand number @var{n} of
251the insn.  When constructing an insn, operand number @var{n}
252will be substituted at this point.  When matching an insn, whatever
253appears at this position in the insn will be taken as operand
254number @var{n}; but it must satisfy @var{predicate} or this instruction
255pattern will not match at all.
256
257Operand numbers must be chosen consecutively counting from zero in
258each instruction pattern.  There may be only one @code{match_operand}
259expression in the pattern for each operand number.  Usually operands
260are numbered in the order of appearance in @code{match_operand}
261expressions.  In the case of a @code{define_expand}, any operand numbers
262used only in @code{match_dup} expressions have higher values than all
263other operand numbers.
264
265@var{predicate} is a string that is the name of a function that
266accepts two arguments, an expression and a machine mode.
267@xref{Predicates}.  During matching, the function will be called with
268the putative operand as the expression and @var{m} as the mode
269argument (if @var{m} is not specified, @code{VOIDmode} will be used,
270which normally causes @var{predicate} to accept any mode).  If it
271returns zero, this instruction pattern fails to match.
272@var{predicate} may be an empty string; then it means no test is to be
273done on the operand, so anything which occurs in this position is
274valid.
275
276Most of the time, @var{predicate} will reject modes other than @var{m}---but
277not always.  For example, the predicate @code{address_operand} uses
278@var{m} as the mode of memory ref that the address should be valid for.
279Many predicates accept @code{const_int} nodes even though their mode is
280@code{VOIDmode}.
281
282@var{constraint} controls reloading and the choice of the best register
283class to use for a value, as explained later (@pxref{Constraints}).
284If the constraint would be an empty string, it can be omitted.
285
286People are often unclear on the difference between the constraint and the
287predicate.  The predicate helps decide whether a given insn matches the
288pattern.  The constraint plays no role in this decision; instead, it
289controls various decisions in the case of an insn which does match.
290
291@findex match_scratch
292@item (match_scratch:@var{m} @var{n} @var{constraint})
293This expression is also a placeholder for operand number @var{n}
294and indicates that operand must be a @code{scratch} or @code{reg}
295expression.
296
297When matching patterns, this is equivalent to
298
299@smallexample
300(match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
301@end smallexample
302
303but, when generating RTL, it produces a (@code{scratch}:@var{m})
304expression.
305
306If the last few expressions in a @code{parallel} are @code{clobber}
307expressions whose operands are either a hard register or
308@code{match_scratch}, the combiner can add or delete them when
309necessary.  @xref{Side Effects}.
310
311@findex match_dup
312@item (match_dup @var{n})
313This expression is also a placeholder for operand number @var{n}.
314It is used when the operand needs to appear more than once in the
315insn.
316
317In construction, @code{match_dup} acts just like @code{match_operand}:
318the operand is substituted into the insn being constructed.  But in
319matching, @code{match_dup} behaves differently.  It assumes that operand
320number @var{n} has already been determined by a @code{match_operand}
321appearing earlier in the recognition template, and it matches only an
322identical-looking expression.
323
324Note that @code{match_dup} should not be used to tell the compiler that
325a particular register is being used for two operands (example:
326@code{add} that adds one register to another; the second register is
327both an input operand and the output operand).  Use a matching
328constraint (@pxref{Simple Constraints}) for those.  @code{match_dup} is for the cases where one
329operand is used in two places in the template, such as an instruction
330that computes both a quotient and a remainder, where the opcode takes
331two input operands but the RTL template has to refer to each of those
332twice; once for the quotient pattern and once for the remainder pattern.
333
334@findex match_operator
335@item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
336This pattern is a kind of placeholder for a variable RTL expression
337code.
338
339When constructing an insn, it stands for an RTL expression whose
340expression code is taken from that of operand @var{n}, and whose
341operands are constructed from the patterns @var{operands}.
342
343When matching an expression, it matches an expression if the function
344@var{predicate} returns nonzero on that expression @emph{and} the
345patterns @var{operands} match the operands of the expression.
346
347Suppose that the function @code{commutative_operator} is defined as
348follows, to match any expression whose operator is one of the
349commutative arithmetic operators of RTL and whose mode is @var{mode}:
350
351@smallexample
352int
353commutative_integer_operator (x, mode)
354     rtx x;
355     enum machine_mode mode;
356@{
357  enum rtx_code code = GET_CODE (x);
358  if (GET_MODE (x) != mode)
359    return 0;
360  return (GET_RTX_CLASS (code) == RTX_COMM_ARITH
361          || code == EQ || code == NE);
362@}
363@end smallexample
364
365Then the following pattern will match any RTL expression consisting
366of a commutative operator applied to two general operands:
367
368@smallexample
369(match_operator:SI 3 "commutative_operator"
370  [(match_operand:SI 1 "general_operand" "g")
371   (match_operand:SI 2 "general_operand" "g")])
372@end smallexample
373
374Here the vector @code{[@var{operands}@dots{}]} contains two patterns
375because the expressions to be matched all contain two operands.
376
377When this pattern does match, the two operands of the commutative
378operator are recorded as operands 1 and 2 of the insn.  (This is done
379by the two instances of @code{match_operand}.)  Operand 3 of the insn
380will be the entire commutative expression: use @code{GET_CODE
381(operands[3])} to see which commutative operator was used.
382
383The machine mode @var{m} of @code{match_operator} works like that of
384@code{match_operand}: it is passed as the second argument to the
385predicate function, and that function is solely responsible for
386deciding whether the expression to be matched ``has'' that mode.
387
388When constructing an insn, argument 3 of the gen-function will specify
389the operation (i.e.@: the expression code) for the expression to be
390made.  It should be an RTL expression, whose expression code is copied
391into a new expression whose operands are arguments 1 and 2 of the
392gen-function.  The subexpressions of argument 3 are not used;
393only its expression code matters.
394
395When @code{match_operator} is used in a pattern for matching an insn,
396it usually best if the operand number of the @code{match_operator}
397is higher than that of the actual operands of the insn.  This improves
398register allocation because the register allocator often looks at
399operands 1 and 2 of insns to see if it can do register tying.
400
401There is no way to specify constraints in @code{match_operator}.  The
402operand of the insn which corresponds to the @code{match_operator}
403never has any constraints because it is never reloaded as a whole.
404However, if parts of its @var{operands} are matched by
405@code{match_operand} patterns, those parts may have constraints of
406their own.
407
408@findex match_op_dup
409@item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
410Like @code{match_dup}, except that it applies to operators instead of
411operands.  When constructing an insn, operand number @var{n} will be
412substituted at this point.  But in matching, @code{match_op_dup} behaves
413differently.  It assumes that operand number @var{n} has already been
414determined by a @code{match_operator} appearing earlier in the
415recognition template, and it matches only an identical-looking
416expression.
417
418@findex match_parallel
419@item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
420This pattern is a placeholder for an insn that consists of a
421@code{parallel} expression with a variable number of elements.  This
422expression should only appear at the top level of an insn pattern.
423
424When constructing an insn, operand number @var{n} will be substituted at
425this point.  When matching an insn, it matches if the body of the insn
426is a @code{parallel} expression with at least as many elements as the
427vector of @var{subpat} expressions in the @code{match_parallel}, if each
428@var{subpat} matches the corresponding element of the @code{parallel},
429@emph{and} the function @var{predicate} returns nonzero on the
430@code{parallel} that is the body of the insn.  It is the responsibility
431of the predicate to validate elements of the @code{parallel} beyond
432those listed in the @code{match_parallel}.
433
434A typical use of @code{match_parallel} is to match load and store
435multiple expressions, which can contain a variable number of elements
436in a @code{parallel}.  For example,
437
438@smallexample
439(define_insn ""
440  [(match_parallel 0 "load_multiple_operation"
441     [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
442           (match_operand:SI 2 "memory_operand" "m"))
443      (use (reg:SI 179))
444      (clobber (reg:SI 179))])]
445  ""
446  "loadm 0,0,%1,%2")
447@end smallexample
448
449This example comes from @file{a29k.md}.  The function
450@code{load_multiple_operation} is defined in @file{a29k.c} and checks
451that subsequent elements in the @code{parallel} are the same as the
452@code{set} in the pattern, except that they are referencing subsequent
453registers and memory locations.
454
455An insn that matches this pattern might look like:
456
457@smallexample
458(parallel
459 [(set (reg:SI 20) (mem:SI (reg:SI 100)))
460  (use (reg:SI 179))
461  (clobber (reg:SI 179))
462  (set (reg:SI 21)
463       (mem:SI (plus:SI (reg:SI 100)
464                        (const_int 4))))
465  (set (reg:SI 22)
466       (mem:SI (plus:SI (reg:SI 100)
467                        (const_int 8))))])
468@end smallexample
469
470@findex match_par_dup
471@item (match_par_dup @var{n} [@var{subpat}@dots{}])
472Like @code{match_op_dup}, but for @code{match_parallel} instead of
473@code{match_operator}.
474
475@end table
476
477@node Output Template
478@section Output Templates and Operand Substitution
479@cindex output templates
480@cindex operand substitution
481
482@cindex @samp{%} in template
483@cindex percent sign
484The @dfn{output template} is a string which specifies how to output the
485assembler code for an instruction pattern.  Most of the template is a
486fixed string which is output literally.  The character @samp{%} is used
487to specify where to substitute an operand; it can also be used to
488identify places where different variants of the assembler require
489different syntax.
490
491In the simplest case, a @samp{%} followed by a digit @var{n} says to output
492operand @var{n} at that point in the string.
493
494@samp{%} followed by a letter and a digit says to output an operand in an
495alternate fashion.  Four letters have standard, built-in meanings described
496below.  The machine description macro @code{PRINT_OPERAND} can define
497additional letters with nonstandard meanings.
498
499@samp{%c@var{digit}} can be used to substitute an operand that is a
500constant value without the syntax that normally indicates an immediate
501operand.
502
503@samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
504the constant is negated before printing.
505
506@samp{%a@var{digit}} can be used to substitute an operand as if it were a
507memory reference, with the actual operand treated as the address.  This may
508be useful when outputting a ``load address'' instruction, because often the
509assembler syntax for such an instruction requires you to write the operand
510as if it were a memory reference.
511
512@samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
513instruction.
514
515@samp{%=} outputs a number which is unique to each instruction in the
516entire compilation.  This is useful for making local labels to be
517referred to more than once in a single template that generates multiple
518assembler instructions.
519
520@samp{%} followed by a punctuation character specifies a substitution that
521does not use an operand.  Only one case is standard: @samp{%%} outputs a
522@samp{%} into the assembler code.  Other nonstandard cases can be
523defined in the @code{PRINT_OPERAND} macro.  You must also define
524which punctuation characters are valid with the
525@code{PRINT_OPERAND_PUNCT_VALID_P} macro.
526
527@cindex \
528@cindex backslash
529The template may generate multiple assembler instructions.  Write the text
530for the instructions, with @samp{\;} between them.
531
532@cindex matching operands
533When the RTL contains two operands which are required by constraint to match
534each other, the output template must refer only to the lower-numbered operand.
535Matching operands are not always identical, and the rest of the compiler
536arranges to put the proper RTL expression for printing into the lower-numbered
537operand.
538
539One use of nonstandard letters or punctuation following @samp{%} is to
540distinguish between different assembler languages for the same machine; for
541example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
542requires periods in most opcode names, while MIT syntax does not.  For
543example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
544syntax.  The same file of patterns is used for both kinds of output syntax,
545but the character sequence @samp{%.} is used in each place where Motorola
546syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
547defines the sequence to output a period; the macro for MIT syntax defines
548it to do nothing.
549
550@cindex @code{#} in template
551As a special case, a template consisting of the single character @code{#}
552instructs the compiler to first split the insn, and then output the
553resulting instructions separately.  This helps eliminate redundancy in the
554output templates.   If you have a @code{define_insn} that needs to emit
555multiple assembler instructions, and there is a matching @code{define_split}
556already defined, then you can simply use @code{#} as the output template
557instead of writing an output template that emits the multiple assembler
558instructions.
559
560If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
561of the form @samp{@{option0|option1|option2@}} in the templates.  These
562describe multiple variants of assembler language syntax.
563@xref{Instruction Output}.
564
565@node Output Statement
566@section C Statements for Assembler Output
567@cindex output statements
568@cindex C statements for assembler output
569@cindex generating assembler output
570
571Often a single fixed template string cannot produce correct and efficient
572assembler code for all the cases that are recognized by a single
573instruction pattern.  For example, the opcodes may depend on the kinds of
574operands; or some unfortunate combinations of operands may require extra
575machine instructions.
576
577If the output control string starts with a @samp{@@}, then it is actually
578a series of templates, each on a separate line.  (Blank lines and
579leading spaces and tabs are ignored.)  The templates correspond to the
580pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
581if a target machine has a two-address add instruction @samp{addr} to add
582into a register and another @samp{addm} to add a register to memory, you
583might write this pattern:
584
585@smallexample
586(define_insn "addsi3"
587  [(set (match_operand:SI 0 "general_operand" "=r,m")
588        (plus:SI (match_operand:SI 1 "general_operand" "0,0")
589                 (match_operand:SI 2 "general_operand" "g,r")))]
590  ""
591  "@@
592   addr %2,%0
593   addm %2,%0")
594@end smallexample
595
596@cindex @code{*} in template
597@cindex asterisk in template
598If the output control string starts with a @samp{*}, then it is not an
599output template but rather a piece of C program that should compute a
600template.  It should execute a @code{return} statement to return the
601template-string you want.  Most such templates use C string literals, which
602require doublequote characters to delimit them.  To include these
603doublequote characters in the string, prefix each one with @samp{\}.
604
605If the output control string is written as a brace block instead of a
606double-quoted string, it is automatically assumed to be C code.  In that
607case, it is not necessary to put in a leading asterisk, or to escape the
608doublequotes surrounding C string literals.
609
610The operands may be found in the array @code{operands}, whose C data type
611is @code{rtx []}.
612
613It is very common to select different ways of generating assembler code
614based on whether an immediate operand is within a certain range.  Be
615careful when doing this, because the result of @code{INTVAL} is an
616integer on the host machine.  If the host machine has more bits in an
617@code{int} than the target machine has in the mode in which the constant
618will be used, then some of the bits you get from @code{INTVAL} will be
619superfluous.  For proper results, you must carefully disregard the
620values of those bits.
621
622@findex output_asm_insn
623It is possible to output an assembler instruction and then go on to output
624or compute more of them, using the subroutine @code{output_asm_insn}.  This
625receives two arguments: a template-string and a vector of operands.  The
626vector may be @code{operands}, or it may be another array of @code{rtx}
627that you declare locally and initialize yourself.
628
629@findex which_alternative
630When an insn pattern has multiple alternatives in its constraints, often
631the appearance of the assembler code is determined mostly by which alternative
632was matched.  When this is so, the C code can test the variable
633@code{which_alternative}, which is the ordinal number of the alternative
634that was actually satisfied (0 for the first, 1 for the second alternative,
635etc.).
636
637For example, suppose there are two opcodes for storing zero, @samp{clrreg}
638for registers and @samp{clrmem} for memory locations.  Here is how
639a pattern could use @code{which_alternative} to choose between them:
640
641@smallexample
642(define_insn ""
643  [(set (match_operand:SI 0 "general_operand" "=r,m")
644        (const_int 0))]
645  ""
646  @{
647  return (which_alternative == 0
648          ? "clrreg %0" : "clrmem %0");
649  @})
650@end smallexample
651
652The example above, where the assembler code to generate was
653@emph{solely} determined by the alternative, could also have been specified
654as follows, having the output control string start with a @samp{@@}:
655
656@smallexample
657@group
658(define_insn ""
659  [(set (match_operand:SI 0 "general_operand" "=r,m")
660        (const_int 0))]
661  ""
662  "@@
663   clrreg %0
664   clrmem %0")
665@end group
666@end smallexample
667
668@node Predicates
669@section Predicates
670@cindex predicates
671@cindex operand predicates
672@cindex operator predicates
673
674A predicate determines whether a @code{match_operand} or
675@code{match_operator} expression matches, and therefore whether the
676surrounding instruction pattern will be used for that combination of
677operands.  GCC has a number of machine-independent predicates, and you
678can define machine-specific predicates as needed.  By convention,
679predicates used with @code{match_operand} have names that end in
680@samp{_operand}, and those used with @code{match_operator} have names
681that end in @samp{_operator}.
682
683All predicates are Boolean functions (in the mathematical sense) of
684two arguments: the RTL expression that is being considered at that
685position in the instruction pattern, and the machine mode that the
686@code{match_operand} or @code{match_operator} specifies.  In this
687section, the first argument is called @var{op} and the second argument
688@var{mode}.  Predicates can be called from C as ordinary two-argument
689functions; this can be useful in output templates or other
690machine-specific code.
691
692Operand predicates can allow operands that are not actually acceptable
693to the hardware, as long as the constraints give reload the ability to
694fix them up (@pxref{Constraints}).  However, GCC will usually generate
695better code if the predicates specify the requirements of the machine
696instructions as closely as possible.  Reload cannot fix up operands
697that must be constants (``immediate operands''); you must use a
698predicate that allows only constants, or else enforce the requirement
699in the extra condition.
700
701@cindex predicates and machine modes
702@cindex normal predicates
703@cindex special predicates
704Most predicates handle their @var{mode} argument in a uniform manner.
705If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
706any mode.  If @var{mode} is anything else, then @var{op} must have the
707same mode, unless @var{op} is a @code{CONST_INT} or integer
708@code{CONST_DOUBLE}.  These RTL expressions always have
709@code{VOIDmode}, so it would be counterproductive to check that their
710mode matches.  Instead, predicates that accept @code{CONST_INT} and/or
711integer @code{CONST_DOUBLE} check that the value stored in the
712constant will fit in the requested mode.
713
714Predicates with this behavior are called @dfn{normal}.
715@command{genrecog} can optimize the instruction recognizer based on
716knowledge of how normal predicates treat modes.  It can also diagnose
717certain kinds of common errors in the use of normal predicates; for
718instance, it is almost always an error to use a normal predicate
719without specifying a mode.
720
721Predicates that do something different with their @var{mode} argument
722are called @dfn{special}.  The generic predicates
723@code{address_operand} and @code{pmode_register_operand} are special
724predicates.  @command{genrecog} does not do any optimizations or
725diagnosis when special predicates are used.
726
727@menu
728* Machine-Independent Predicates::  Predicates available to all back ends.
729* Defining Predicates::             How to write machine-specific predicate
730                                    functions.
731@end menu
732
733@node Machine-Independent Predicates
734@subsection Machine-Independent Predicates
735@cindex machine-independent predicates
736@cindex generic predicates
737
738These are the generic predicates available to all back ends.  They are
739defined in @file{recog.c}.  The first category of predicates allow
740only constant, or @dfn{immediate}, operands.
741
742@defun immediate_operand
743This predicate allows any sort of constant that fits in @var{mode}.
744It is an appropriate choice for instructions that take operands that
745must be constant.
746@end defun
747
748@defun const_int_operand
749This predicate allows any @code{CONST_INT} expression that fits in
750@var{mode}.  It is an appropriate choice for an immediate operand that
751does not allow a symbol or label.
752@end defun
753
754@defun const_double_operand
755This predicate accepts any @code{CONST_DOUBLE} expression that has
756exactly @var{mode}.  If @var{mode} is @code{VOIDmode}, it will also
757accept @code{CONST_INT}.  It is intended for immediate floating point
758constants.
759@end defun
760
761@noindent
762The second category of predicates allow only some kind of machine
763register.
764
765@defun register_operand
766This predicate allows any @code{REG} or @code{SUBREG} expression that
767is valid for @var{mode}.  It is often suitable for arithmetic
768instruction operands on a RISC machine.
769@end defun
770
771@defun pmode_register_operand
772This is a slight variant on @code{register_operand} which works around
773a limitation in the machine-description reader.
774
775@smallexample
776(match_operand @var{n} "pmode_register_operand" @var{constraint})
777@end smallexample
778
779@noindent
780means exactly what
781
782@smallexample
783(match_operand:P @var{n} "register_operand" @var{constraint})
784@end smallexample
785
786@noindent
787would mean, if the machine-description reader accepted @samp{:P}
788mode suffixes.  Unfortunately, it cannot, because @code{Pmode} is an
789alias for some other mode, and might vary with machine-specific
790options.  @xref{Misc}.
791@end defun
792
793@defun scratch_operand
794This predicate allows hard registers and @code{SCRATCH} expressions,
795but not pseudo-registers.  It is used internally by @code{match_scratch};
796it should not be used directly.
797@end defun
798
799@noindent
800The third category of predicates allow only some kind of memory reference.
801
802@defun memory_operand
803This predicate allows any valid reference to a quantity of mode
804@var{mode} in memory, as determined by the weak form of
805@code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
806@end defun
807
808@defun address_operand
809This predicate is a little unusual; it allows any operand that is a
810valid expression for the @emph{address} of a quantity of mode
811@var{mode}, again determined by the weak form of
812@code{GO_IF_LEGITIMATE_ADDRESS}.  To first order, if
813@samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
814@code{memory_operand}, then @var{exp} is acceptable to
815@code{address_operand}.  Note that @var{exp} does not necessarily have
816the mode @var{mode}.
817@end defun
818
819@defun indirect_operand
820This is a stricter form of @code{memory_operand} which allows only
821memory references with a @code{general_operand} as the address
822expression.  New uses of this predicate are discouraged, because
823@code{general_operand} is very permissive, so it's hard to tell what
824an @code{indirect_operand} does or does not allow.  If a target has
825different requirements for memory operands for different instructions,
826it is better to define target-specific predicates which enforce the
827hardware's requirements explicitly.
828@end defun
829
830@defun push_operand
831This predicate allows a memory reference suitable for pushing a value
832onto the stack.  This will be a @code{MEM} which refers to
833@code{stack_pointer_rtx}, with a side-effect in its address expression
834(@pxref{Incdec}); which one is determined by the
835@code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
836@end defun
837
838@defun pop_operand
839This predicate allows a memory reference suitable for popping a value
840off the stack.  Again, this will be a @code{MEM} referring to
841@code{stack_pointer_rtx}, with a side-effect in its address
842expression.  However, this time @code{STACK_POP_CODE} is expected.
843@end defun
844
845@noindent
846The fourth category of predicates allow some combination of the above
847operands.
848
849@defun nonmemory_operand
850This predicate allows any immediate or register operand valid for @var{mode}.
851@end defun
852
853@defun nonimmediate_operand
854This predicate allows any register or memory operand valid for @var{mode}.
855@end defun
856
857@defun general_operand
858This predicate allows any immediate, register, or memory operand
859valid for @var{mode}.
860@end defun
861
862@noindent
863Finally, there are two generic operator predicates.
864
865@defun comparison_operator
866This predicate matches any expression which performs an arithmetic
867comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the
868expression code.
869@end defun
870
871@defun ordered_comparison_operator
872This predicate matches any expression which performs an arithmetic
873comparison in @var{mode} and whose expression code is valid for integer
874modes; that is, the expression code will be one of @code{eq}, @code{ne},
875@code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu},
876@code{ge}, @code{geu}.
877@end defun
878
879@node Defining Predicates
880@subsection Defining Machine-Specific Predicates
881@cindex defining predicates
882@findex define_predicate
883@findex define_special_predicate
884
885Many machines have requirements for their operands that cannot be
886expressed precisely using the generic predicates.  You can define
887additional predicates using @code{define_predicate} and
888@code{define_special_predicate} expressions.  These expressions have
889three operands:
890
891@itemize @bullet
892@item
893The name of the predicate, as it will be referred to in
894@code{match_operand} or @code{match_operator} expressions.
895
896@item
897An RTL expression which evaluates to true if the predicate allows the
898operand @var{op}, false if it does not.  This expression can only use
899the following RTL codes:
900
901@table @code
902@item MATCH_OPERAND
903When written inside a predicate expression, a @code{MATCH_OPERAND}
904expression evaluates to true if the predicate it names would allow
905@var{op}.  The operand number and constraint are ignored.  Due to
906limitations in @command{genrecog}, you can only refer to generic
907predicates and predicates that have already been defined.
908
909@item MATCH_CODE
910This expression evaluates to true if @var{op} or a specified
911subexpression of @var{op} has one of a given list of RTX codes.
912
913The first operand of this expression is a string constant containing a
914comma-separated list of RTX code names (in lower case).  These are the
915codes for which the @code{MATCH_CODE} will be true.
916
917The second operand is a string constant which indicates what
918subexpression of @var{op} to examine.  If it is absent or the empty
919string, @var{op} itself is examined.  Otherwise, the string constant
920must be a sequence of digits and/or lowercase letters.  Each character
921indicates a subexpression to extract from the current expression; for
922the first character this is @var{op}, for the second and subsequent
923characters it is the result of the previous character.  A digit
924@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
925extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
926alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on).  The
927@code{MATCH_CODE} then examines the RTX code of the subexpression
928extracted by the complete string.  It is not possible to extract
929components of an @code{rtvec} that is not at position 0 within its RTX
930object.
931
932@item MATCH_TEST
933This expression has one operand, a string constant containing a C
934expression.  The predicate's arguments, @var{op} and @var{mode}, are
935available with those names in the C expression.  The @code{MATCH_TEST}
936evaluates to true if the C expression evaluates to a nonzero value.
937@code{MATCH_TEST} expressions must not have side effects.
938
939@item  AND
940@itemx IOR
941@itemx NOT
942@itemx IF_THEN_ELSE
943The basic @samp{MATCH_} expressions can be combined using these
944logical operators, which have the semantics of the C operators
945@samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively.  As
946in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
947arbitrary number of arguments; this has exactly the same effect as
948writing a chain of two-argument @code{AND} or @code{IOR} expressions.
949@end table
950
951@item
952An optional block of C code, which should execute
953@samp{@w{return true}} if the predicate is found to match and
954@samp{@w{return false}} if it does not.  It must not have any side
955effects.  The predicate arguments, @var{op} and @var{mode}, are
956available with those names.
957
958If a code block is present in a predicate definition, then the RTL
959expression must evaluate to true @emph{and} the code block must
960execute @samp{@w{return true}} for the predicate to allow the operand.
961The RTL expression is evaluated first; do not re-check anything in the
962code block that was checked in the RTL expression.
963@end itemize
964
965The program @command{genrecog} scans @code{define_predicate} and
966@code{define_special_predicate} expressions to determine which RTX
967codes are possibly allowed.  You should always make this explicit in
968the RTL predicate expression, using @code{MATCH_OPERAND} and
969@code{MATCH_CODE}.
970
971Here is an example of a simple predicate definition, from the IA64
972machine description:
973
974@smallexample
975@group
976;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.}
977(define_predicate "small_addr_symbolic_operand"
978  (and (match_code "symbol_ref")
979       (match_test "SYMBOL_REF_SMALL_ADDR_P (op)")))
980@end group
981@end smallexample
982
983@noindent
984And here is another, showing the use of the C block.
985
986@smallexample
987@group
988;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.}
989(define_predicate "gr_register_operand"
990  (match_operand 0 "register_operand")
991@{
992  unsigned int regno;
993  if (GET_CODE (op) == SUBREG)
994    op = SUBREG_REG (op);
995
996  regno = REGNO (op);
997  return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno));
998@})
999@end group
1000@end smallexample
1001
1002Predicates written with @code{define_predicate} automatically include
1003a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same
1004mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
1005@code{CONST_DOUBLE}.  They do @emph{not} check specifically for
1006integer @code{CONST_DOUBLE}, nor do they test that the value of either
1007kind of constant fits in the requested mode.  This is because
1008target-specific predicates that take constants usually have to do more
1009stringent value checks anyway.  If you need the exact same treatment
1010of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
1011provide, use a @code{MATCH_OPERAND} subexpression to call
1012@code{const_int_operand}, @code{const_double_operand}, or
1013@code{immediate_operand}.
1014
1015Predicates written with @code{define_special_predicate} do not get any
1016automatic mode checks, and are treated as having special mode handling
1017by @command{genrecog}.
1018
1019The program @command{genpreds} is responsible for generating code to
1020test predicates.  It also writes a header file containing function
1021declarations for all machine-specific predicates.  It is not necessary
1022to declare these predicates in @file{@var{cpu}-protos.h}.
1023@end ifset
1024
1025@c Most of this node appears by itself (in a different place) even
1026@c when the INTERNALS flag is clear.  Passages that require the internals
1027@c manual's context are conditionalized to appear only in the internals manual.
1028@ifset INTERNALS
1029@node Constraints
1030@section Operand Constraints
1031@cindex operand constraints
1032@cindex constraints
1033
1034Each @code{match_operand} in an instruction pattern can specify
1035constraints for the operands allowed.  The constraints allow you to
1036fine-tune matching within the set of operands allowed by the
1037predicate.
1038
1039@end ifset
1040@ifclear INTERNALS
1041@node Constraints
1042@section Constraints for @code{asm} Operands
1043@cindex operand constraints, @code{asm}
1044@cindex constraints, @code{asm}
1045@cindex @code{asm} constraints
1046
1047Here are specific details on what constraint letters you can use with
1048@code{asm} operands.
1049@end ifclear
1050Constraints can say whether
1051an operand may be in a register, and which kinds of register; whether the
1052operand can be a memory reference, and which kinds of address; whether the
1053operand may be an immediate constant, and which possible values it may
1054have.  Constraints can also require two operands to match.
1055Side-effects aren't allowed in operands of inline @code{asm}, unless
1056@samp{<} or @samp{>} constraints are used, because there is no guarantee
1057that the side-effects will happen exactly once in an instruction that can update
1058the addressing register.
1059
1060@ifset INTERNALS
1061@menu
1062* Simple Constraints::  Basic use of constraints.
1063* Multi-Alternative::   When an insn has two alternative constraint-patterns.
1064* Class Preferences::   Constraints guide which hard register to put things in.
1065* Modifiers::           More precise control over effects of constraints.
1066* Disable Insn Alternatives:: Disable insn alternatives using the @code{enabled} attribute.
1067* Machine Constraints:: Existing constraints for some particular machines.
1068* Define Constraints::  How to define machine-specific constraints.
1069* C Constraint Interface:: How to test constraints from C code.
1070@end menu
1071@end ifset
1072
1073@ifclear INTERNALS
1074@menu
1075* Simple Constraints::  Basic use of constraints.
1076* Multi-Alternative::   When an insn has two alternative constraint-patterns.
1077* Modifiers::           More precise control over effects of constraints.
1078* Machine Constraints:: Special constraints for some particular machines.
1079@end menu
1080@end ifclear
1081
1082@node Simple Constraints
1083@subsection Simple Constraints
1084@cindex simple constraints
1085
1086The simplest kind of constraint is a string full of letters, each of
1087which describes one kind of operand that is permitted.  Here are
1088the letters that are allowed:
1089
1090@table @asis
1091@item whitespace
1092Whitespace characters are ignored and can be inserted at any position
1093except the first.  This enables each alternative for different operands to
1094be visually aligned in the machine description even if they have different
1095number of constraints and modifiers.
1096
1097@cindex @samp{m} in constraint
1098@cindex memory references in constraints
1099@item @samp{m}
1100A memory operand is allowed, with any kind of address that the machine
1101supports in general.
1102Note that the letter used for the general memory constraint can be
1103re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro.
1104
1105@cindex offsettable address
1106@cindex @samp{o} in constraint
1107@item @samp{o}
1108A memory operand is allowed, but only if the address is
1109@dfn{offsettable}.  This means that adding a small integer (actually,
1110the width in bytes of the operand, as determined by its machine mode)
1111may be added to the address and the result is also a valid memory
1112address.
1113
1114@cindex autoincrement/decrement addressing
1115For example, an address which is constant is offsettable; so is an
1116address that is the sum of a register and a constant (as long as a
1117slightly larger constant is also within the range of address-offsets
1118supported by the machine); but an autoincrement or autodecrement
1119address is not offsettable.  More complicated indirect/indexed
1120addresses may or may not be offsettable depending on the other
1121addressing modes that the machine supports.
1122
1123Note that in an output operand which can be matched by another
1124operand, the constraint letter @samp{o} is valid only when accompanied
1125by both @samp{<} (if the target machine has predecrement addressing)
1126and @samp{>} (if the target machine has preincrement addressing).
1127
1128@cindex @samp{V} in constraint
1129@item @samp{V}
1130A memory operand that is not offsettable.  In other words, anything that
1131would fit the @samp{m} constraint but not the @samp{o} constraint.
1132
1133@cindex @samp{<} in constraint
1134@item @samp{<}
1135A memory operand with autodecrement addressing (either predecrement or
1136postdecrement) is allowed.  In inline @code{asm} this constraint is only
1137allowed if the operand is used exactly once in an instruction that can
1138handle the side-effects.  Not using an operand with @samp{<} in constraint
1139string in the inline @code{asm} pattern at all or using it in multiple
1140instructions isn't valid, because the side-effects wouldn't be performed
1141or would be performed more than once.  Furthermore, on some targets
1142the operand with @samp{<} in constraint string must be accompanied by
1143special instruction suffixes like @code{%U0} instruction suffix on PowerPC
1144or @code{%P0} on IA-64.
1145
1146@cindex @samp{>} in constraint
1147@item @samp{>}
1148A memory operand with autoincrement addressing (either preincrement or
1149postincrement) is allowed.  In inline @code{asm} the same restrictions
1150as for @samp{<} apply.
1151
1152@cindex @samp{r} in constraint
1153@cindex registers in constraints
1154@item @samp{r}
1155A register operand is allowed provided that it is in a general
1156register.
1157
1158@cindex constants in constraints
1159@cindex @samp{i} in constraint
1160@item @samp{i}
1161An immediate integer operand (one with constant value) is allowed.
1162This includes symbolic constants whose values will be known only at
1163assembly time or later.
1164
1165@cindex @samp{n} in constraint
1166@item @samp{n}
1167An immediate integer operand with a known numeric value is allowed.
1168Many systems cannot support assembly-time constants for operands less
1169than a word wide.  Constraints for these operands should use @samp{n}
1170rather than @samp{i}.
1171
1172@cindex @samp{I} in constraint
1173@item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
1174Other letters in the range @samp{I} through @samp{P} may be defined in
1175a machine-dependent fashion to permit immediate integer operands with
1176explicit integer values in specified ranges.  For example, on the
117768000, @samp{I} is defined to stand for the range of values 1 to 8.
1178This is the range permitted as a shift count in the shift
1179instructions.
1180
1181@cindex @samp{E} in constraint
1182@item @samp{E}
1183An immediate floating operand (expression code @code{const_double}) is
1184allowed, but only if the target floating point format is the same as
1185that of the host machine (on which the compiler is running).
1186
1187@cindex @samp{F} in constraint
1188@item @samp{F}
1189An immediate floating operand (expression code @code{const_double} or
1190@code{const_vector}) is allowed.
1191
1192@cindex @samp{G} in constraint
1193@cindex @samp{H} in constraint
1194@item @samp{G}, @samp{H}
1195@samp{G} and @samp{H} may be defined in a machine-dependent fashion to
1196permit immediate floating operands in particular ranges of values.
1197
1198@cindex @samp{s} in constraint
1199@item @samp{s}
1200An immediate integer operand whose value is not an explicit integer is
1201allowed.
1202
1203This might appear strange; if an insn allows a constant operand with a
1204value not known at compile time, it certainly must allow any known
1205value.  So why use @samp{s} instead of @samp{i}?  Sometimes it allows
1206better code to be generated.
1207
1208For example, on the 68000 in a fullword instruction it is possible to
1209use an immediate operand; but if the immediate value is between @minus{}128
1210and 127, better code results from loading the value into a register and
1211using the register.  This is because the load into the register can be
1212done with a @samp{moveq} instruction.  We arrange for this to happen
1213by defining the letter @samp{K} to mean ``any integer outside the
1214range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
1215constraints.
1216
1217@cindex @samp{g} in constraint
1218@item @samp{g}
1219Any register, memory or immediate integer operand is allowed, except for
1220registers that are not general registers.
1221
1222@cindex @samp{X} in constraint
1223@item @samp{X}
1224@ifset INTERNALS
1225Any operand whatsoever is allowed, even if it does not satisfy
1226@code{general_operand}.  This is normally used in the constraint of
1227a @code{match_scratch} when certain alternatives will not actually
1228require a scratch register.
1229@end ifset
1230@ifclear INTERNALS
1231Any operand whatsoever is allowed.
1232@end ifclear
1233
1234@cindex @samp{0} in constraint
1235@cindex digits in constraint
1236@item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
1237An operand that matches the specified operand number is allowed.  If a
1238digit is used together with letters within the same alternative, the
1239digit should come last.
1240
1241This number is allowed to be more than a single digit.  If multiple
1242digits are encountered consecutively, they are interpreted as a single
1243decimal integer.  There is scant chance for ambiguity, since to-date
1244it has never been desirable that @samp{10} be interpreted as matching
1245either operand 1 @emph{or} operand 0.  Should this be desired, one
1246can use multiple alternatives instead.
1247
1248@cindex matching constraint
1249@cindex constraint, matching
1250This is called a @dfn{matching constraint} and what it really means is
1251that the assembler has only a single operand that fills two roles
1252@ifset INTERNALS
1253considered separate in the RTL insn.  For example, an add insn has two
1254input operands and one output operand in the RTL, but on most CISC
1255@end ifset
1256@ifclear INTERNALS
1257which @code{asm} distinguishes.  For example, an add instruction uses
1258two input operands and an output operand, but on most CISC
1259@end ifclear
1260machines an add instruction really has only two operands, one of them an
1261input-output operand:
1262
1263@smallexample
1264addl #35,r12
1265@end smallexample
1266
1267Matching constraints are used in these circumstances.
1268More precisely, the two operands that match must include one input-only
1269operand and one output-only operand.  Moreover, the digit must be a
1270smaller number than the number of the operand that uses it in the
1271constraint.
1272
1273@ifset INTERNALS
1274For operands to match in a particular case usually means that they
1275are identical-looking RTL expressions.  But in a few special cases
1276specific kinds of dissimilarity are allowed.  For example, @code{*x}
1277as an input operand will match @code{*x++} as an output operand.
1278For proper results in such cases, the output template should always
1279use the output-operand's number when printing the operand.
1280@end ifset
1281
1282@cindex load address instruction
1283@cindex push address instruction
1284@cindex address constraints
1285@cindex @samp{p} in constraint
1286@item @samp{p}
1287An operand that is a valid memory address is allowed.  This is
1288for ``load address'' and ``push address'' instructions.
1289
1290@findex address_operand
1291@samp{p} in the constraint must be accompanied by @code{address_operand}
1292as the predicate in the @code{match_operand}.  This predicate interprets
1293the mode specified in the @code{match_operand} as the mode of the memory
1294reference for which the address would be valid.
1295
1296@cindex other register constraints
1297@cindex extensible constraints
1298@item @var{other-letters}
1299Other letters can be defined in machine-dependent fashion to stand for
1300particular classes of registers or other arbitrary operand types.
1301@samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
1302for data, address and floating point registers.
1303@end table
1304
1305@ifset INTERNALS
1306In order to have valid assembler code, each operand must satisfy
1307its constraint.  But a failure to do so does not prevent the pattern
1308from applying to an insn.  Instead, it directs the compiler to modify
1309the code so that the constraint will be satisfied.  Usually this is
1310done by copying an operand into a register.
1311
1312Contrast, therefore, the two instruction patterns that follow:
1313
1314@smallexample
1315(define_insn ""
1316  [(set (match_operand:SI 0 "general_operand" "=r")
1317        (plus:SI (match_dup 0)
1318                 (match_operand:SI 1 "general_operand" "r")))]
1319  ""
1320  "@dots{}")
1321@end smallexample
1322
1323@noindent
1324which has two operands, one of which must appear in two places, and
1325
1326@smallexample
1327(define_insn ""
1328  [(set (match_operand:SI 0 "general_operand" "=r")
1329        (plus:SI (match_operand:SI 1 "general_operand" "0")
1330                 (match_operand:SI 2 "general_operand" "r")))]
1331  ""
1332  "@dots{}")
1333@end smallexample
1334
1335@noindent
1336which has three operands, two of which are required by a constraint to be
1337identical.  If we are considering an insn of the form
1338
1339@smallexample
1340(insn @var{n} @var{prev} @var{next}
1341  (set (reg:SI 3)
1342       (plus:SI (reg:SI 6) (reg:SI 109)))
1343  @dots{})
1344@end smallexample
1345
1346@noindent
1347the first pattern would not apply at all, because this insn does not
1348contain two identical subexpressions in the right place.  The pattern would
1349say, ``That does not look like an add instruction; try other patterns''.
1350The second pattern would say, ``Yes, that's an add instruction, but there
1351is something wrong with it''.  It would direct the reload pass of the
1352compiler to generate additional insns to make the constraint true.  The
1353results might look like this:
1354
1355@smallexample
1356(insn @var{n2} @var{prev} @var{n}
1357  (set (reg:SI 3) (reg:SI 6))
1358  @dots{})
1359
1360(insn @var{n} @var{n2} @var{next}
1361  (set (reg:SI 3)
1362       (plus:SI (reg:SI 3) (reg:SI 109)))
1363  @dots{})
1364@end smallexample
1365
1366It is up to you to make sure that each operand, in each pattern, has
1367constraints that can handle any RTL expression that could be present for
1368that operand.  (When multiple alternatives are in use, each pattern must,
1369for each possible combination of operand expressions, have at least one
1370alternative which can handle that combination of operands.)  The
1371constraints don't need to @emph{allow} any possible operand---when this is
1372the case, they do not constrain---but they must at least point the way to
1373reloading any possible operand so that it will fit.
1374
1375@itemize @bullet
1376@item
1377If the constraint accepts whatever operands the predicate permits,
1378there is no problem: reloading is never necessary for this operand.
1379
1380For example, an operand whose constraints permit everything except
1381registers is safe provided its predicate rejects registers.
1382
1383An operand whose predicate accepts only constant values is safe
1384provided its constraints include the letter @samp{i}.  If any possible
1385constant value is accepted, then nothing less than @samp{i} will do;
1386if the predicate is more selective, then the constraints may also be
1387more selective.
1388
1389@item
1390Any operand expression can be reloaded by copying it into a register.
1391So if an operand's constraints allow some kind of register, it is
1392certain to be safe.  It need not permit all classes of registers; the
1393compiler knows how to copy a register into another register of the
1394proper class in order to make an instruction valid.
1395
1396@cindex nonoffsettable memory reference
1397@cindex memory reference, nonoffsettable
1398@item
1399A nonoffsettable memory reference can be reloaded by copying the
1400address into a register.  So if the constraint uses the letter
1401@samp{o}, all memory references are taken care of.
1402
1403@item
1404A constant operand can be reloaded by allocating space in memory to
1405hold it as preinitialized data.  Then the memory reference can be used
1406in place of the constant.  So if the constraint uses the letters
1407@samp{o} or @samp{m}, constant operands are not a problem.
1408
1409@item
1410If the constraint permits a constant and a pseudo register used in an insn
1411was not allocated to a hard register and is equivalent to a constant,
1412the register will be replaced with the constant.  If the predicate does
1413not permit a constant and the insn is re-recognized for some reason, the
1414compiler will crash.  Thus the predicate must always recognize any
1415objects allowed by the constraint.
1416@end itemize
1417
1418If the operand's predicate can recognize registers, but the constraint does
1419not permit them, it can make the compiler crash.  When this operand happens
1420to be a register, the reload pass will be stymied, because it does not know
1421how to copy a register temporarily into memory.
1422
1423If the predicate accepts a unary operator, the constraint applies to the
1424operand.  For example, the MIPS processor at ISA level 3 supports an
1425instruction which adds two registers in @code{SImode} to produce a
1426@code{DImode} result, but only if the registers are correctly sign
1427extended.  This predicate for the input operands accepts a
1428@code{sign_extend} of an @code{SImode} register.  Write the constraint
1429to indicate the type of register that is required for the operand of the
1430@code{sign_extend}.
1431@end ifset
1432
1433@node Multi-Alternative
1434@subsection Multiple Alternative Constraints
1435@cindex multiple alternative constraints
1436
1437Sometimes a single instruction has multiple alternative sets of possible
1438operands.  For example, on the 68000, a logical-or instruction can combine
1439register or an immediate value into memory, or it can combine any kind of
1440operand into a register; but it cannot combine one memory location into
1441another.
1442
1443These constraints are represented as multiple alternatives.  An alternative
1444can be described by a series of letters for each operand.  The overall
1445constraint for an operand is made from the letters for this operand
1446from the first alternative, a comma, the letters for this operand from
1447the second alternative, a comma, and so on until the last alternative.
1448@ifset INTERNALS
1449Here is how it is done for fullword logical-or on the 68000:
1450
1451@smallexample
1452(define_insn "iorsi3"
1453  [(set (match_operand:SI 0 "general_operand" "=m,d")
1454        (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1455                (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1456  @dots{})
1457@end smallexample
1458
1459The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1460operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
14612.  The second alternative has @samp{d} (data register) for operand 0,
1462@samp{0} for operand 1, and @samp{dmKs} for operand 2.  The @samp{=} and
1463@samp{%} in the constraints apply to all the alternatives; their
1464meaning is explained in the next section (@pxref{Class Preferences}).
1465@end ifset
1466
1467@c FIXME Is this ? and ! stuff of use in asm()?  If not, hide unless INTERNAL
1468If all the operands fit any one alternative, the instruction is valid.
1469Otherwise, for each alternative, the compiler counts how many instructions
1470must be added to copy the operands so that that alternative applies.
1471The alternative requiring the least copying is chosen.  If two alternatives
1472need the same amount of copying, the one that comes first is chosen.
1473These choices can be altered with the @samp{?} and @samp{!} characters:
1474
1475@table @code
1476@cindex @samp{?} in constraint
1477@cindex question mark
1478@item ?
1479Disparage slightly the alternative that the @samp{?} appears in,
1480as a choice when no alternative applies exactly.  The compiler regards
1481this alternative as one unit more costly for each @samp{?} that appears
1482in it.
1483
1484@cindex @samp{!} in constraint
1485@cindex exclamation point
1486@item !
1487Disparage severely the alternative that the @samp{!} appears in.
1488This alternative can still be used if it fits without reloading,
1489but if reloading is needed, some other alternative will be used.
1490@end table
1491
1492@ifset INTERNALS
1493When an insn pattern has multiple alternatives in its constraints, often
1494the appearance of the assembler code is determined mostly by which
1495alternative was matched.  When this is so, the C code for writing the
1496assembler code can use the variable @code{which_alternative}, which is
1497the ordinal number of the alternative that was actually satisfied (0 for
1498the first, 1 for the second alternative, etc.).  @xref{Output Statement}.
1499@end ifset
1500
1501@ifset INTERNALS
1502@node Class Preferences
1503@subsection Register Class Preferences
1504@cindex class preference constraints
1505@cindex register class preference constraints
1506
1507@cindex voting between constraint alternatives
1508The operand constraints have another function: they enable the compiler
1509to decide which kind of hardware register a pseudo register is best
1510allocated to.  The compiler examines the constraints that apply to the
1511insns that use the pseudo register, looking for the machine-dependent
1512letters such as @samp{d} and @samp{a} that specify classes of registers.
1513The pseudo register is put in whichever class gets the most ``votes''.
1514The constraint letters @samp{g} and @samp{r} also vote: they vote in
1515favor of a general register.  The machine description says which registers
1516are considered general.
1517
1518Of course, on some machines all registers are equivalent, and no register
1519classes are defined.  Then none of this complexity is relevant.
1520@end ifset
1521
1522@node Modifiers
1523@subsection Constraint Modifier Characters
1524@cindex modifiers in constraints
1525@cindex constraint modifier characters
1526
1527@c prevent bad page break with this line
1528Here are constraint modifier characters.
1529
1530@table @samp
1531@cindex @samp{=} in constraint
1532@item =
1533Means that this operand is write-only for this instruction: the previous
1534value is discarded and replaced by output data.
1535
1536@cindex @samp{+} in constraint
1537@item +
1538Means that this operand is both read and written by the instruction.
1539
1540When the compiler fixes up the operands to satisfy the constraints,
1541it needs to know which operands are inputs to the instruction and
1542which are outputs from it.  @samp{=} identifies an output; @samp{+}
1543identifies an operand that is both input and output; all other operands
1544are assumed to be input only.
1545
1546If you specify @samp{=} or @samp{+} in a constraint, you put it in the
1547first character of the constraint string.
1548
1549@cindex @samp{&} in constraint
1550@cindex earlyclobber operand
1551@item &
1552Means (in a particular alternative) that this operand is an
1553@dfn{earlyclobber} operand, which is modified before the instruction is
1554finished using the input operands.  Therefore, this operand may not lie
1555in a register that is used as an input operand or as part of any memory
1556address.
1557
1558@samp{&} applies only to the alternative in which it is written.  In
1559constraints with multiple alternatives, sometimes one alternative
1560requires @samp{&} while others do not.  See, for example, the
1561@samp{movdf} insn of the 68000.
1562
1563An input operand can be tied to an earlyclobber operand if its only
1564use as an input occurs before the early result is written.  Adding
1565alternatives of this form often allows GCC to produce better code
1566when only some of the inputs can be affected by the earlyclobber.
1567See, for example, the @samp{mulsi3} insn of the ARM@.
1568
1569@samp{&} does not obviate the need to write @samp{=}.
1570
1571@cindex @samp{%} in constraint
1572@item %
1573Declares the instruction to be commutative for this operand and the
1574following operand.  This means that the compiler may interchange the
1575two operands if that is the cheapest way to make all operands fit the
1576constraints.
1577@ifset INTERNALS
1578This is often used in patterns for addition instructions
1579that really have only two operands: the result must go in one of the
1580arguments.  Here for example, is how the 68000 halfword-add
1581instruction is defined:
1582
1583@smallexample
1584(define_insn "addhi3"
1585  [(set (match_operand:HI 0 "general_operand" "=m,r")
1586     (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1587              (match_operand:HI 2 "general_operand" "di,g")))]
1588  @dots{})
1589@end smallexample
1590@end ifset
1591GCC can only handle one commutative pair in an asm; if you use more,
1592the compiler may fail.  Note that you need not use the modifier if
1593the two alternatives are strictly identical; this would only waste
1594time in the reload pass.  The modifier is not operational after
1595register allocation, so the result of @code{define_peephole2}
1596and @code{define_split}s performed after reload cannot rely on
1597@samp{%} to make the intended insn match.
1598
1599@cindex @samp{#} in constraint
1600@item #
1601Says that all following characters, up to the next comma, are to be
1602ignored as a constraint.  They are significant only for choosing
1603register preferences.
1604
1605@cindex @samp{*} in constraint
1606@item *
1607Says that the following character should be ignored when choosing
1608register preferences.  @samp{*} has no effect on the meaning of the
1609constraint as a constraint, and no effect on reloading.
1610
1611@ifset INTERNALS
1612Here is an example: the 68000 has an instruction to sign-extend a
1613halfword in a data register, and can also sign-extend a value by
1614copying it into an address register.  While either kind of register is
1615acceptable, the constraints on an address-register destination are
1616less strict, so it is best if register allocation makes an address
1617register its goal.  Therefore, @samp{*} is used so that the @samp{d}
1618constraint letter (for data register) is ignored when computing
1619register preferences.
1620
1621@smallexample
1622(define_insn "extendhisi2"
1623  [(set (match_operand:SI 0 "general_operand" "=*d,a")
1624        (sign_extend:SI
1625         (match_operand:HI 1 "general_operand" "0,g")))]
1626  @dots{})
1627@end smallexample
1628@end ifset
1629@end table
1630
1631@node Machine Constraints
1632@subsection Constraints for Particular Machines
1633@cindex machine specific constraints
1634@cindex constraints, machine specific
1635
1636Whenever possible, you should use the general-purpose constraint letters
1637in @code{asm} arguments, since they will convey meaning more readily to
1638people reading your code.  Failing that, use the constraint letters
1639that usually have very similar meanings across architectures.  The most
1640commonly used constraints are @samp{m} and @samp{r} (for memory and
1641general-purpose registers respectively; @pxref{Simple Constraints}), and
1642@samp{I}, usually the letter indicating the most common
1643immediate-constant format.
1644
1645Each architecture defines additional constraints.  These constraints
1646are used by the compiler itself for instruction generation, as well as
1647for @code{asm} statements; therefore, some of the constraints are not
1648particularly useful for @code{asm}.  Here is a summary of some of the
1649machine-dependent constraints available on some particular machines;
1650it includes both constraints that are useful for @code{asm} and
1651constraints that aren't.  The compiler source file mentioned in the
1652table heading for each architecture is the definitive reference for
1653the meanings of that architecture's constraints.
1654
1655@table @emph
1656@item ARM family---@file{config/arm/arm.h}
1657@table @code
1658@item f
1659Floating-point register
1660
1661@item w
1662VFP floating-point register
1663
1664@item F
1665One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0
1666or 10.0
1667
1668@item G
1669Floating-point constant that would satisfy the constraint @samp{F} if it
1670were negated
1671
1672@item I
1673Integer that is valid as an immediate operand in a data processing
1674instruction.  That is, an integer in the range 0 to 255 rotated by a
1675multiple of 2
1676
1677@item J
1678Integer in the range @minus{}4095 to 4095
1679
1680@item K
1681Integer that satisfies constraint @samp{I} when inverted (ones complement)
1682
1683@item L
1684Integer that satisfies constraint @samp{I} when negated (twos complement)
1685
1686@item M
1687Integer in the range 0 to 32
1688
1689@item Q
1690A memory reference where the exact address is in a single register
1691(`@samp{m}' is preferable for @code{asm} statements)
1692
1693@item R
1694An item in the constant pool
1695
1696@item S
1697A symbol in the text segment of the current file
1698
1699@item Uv
1700A memory reference suitable for VFP load/store insns (reg+constant offset)
1701
1702@item Uy
1703A memory reference suitable for iWMMXt load/store instructions.
1704
1705@item Uq
1706A memory reference suitable for the ARMv4 ldrsb instruction.
1707@end table
1708
1709@item AVR family---@file{config/avr/constraints.md}
1710@table @code
1711@item l
1712Registers from r0 to r15
1713
1714@item a
1715Registers from r16 to r23
1716
1717@item d
1718Registers from r16 to r31
1719
1720@item w
1721Registers from r24 to r31.  These registers can be used in @samp{adiw} command
1722
1723@item e
1724Pointer register (r26--r31)
1725
1726@item b
1727Base pointer register (r28--r31)
1728
1729@item q
1730Stack pointer register (SPH:SPL)
1731
1732@item t
1733Temporary register r0
1734
1735@item x
1736Register pair X (r27:r26)
1737
1738@item y
1739Register pair Y (r29:r28)
1740
1741@item z
1742Register pair Z (r31:r30)
1743
1744@item I
1745Constant greater than @minus{}1, less than 64
1746
1747@item J
1748Constant greater than @minus{}64, less than 1
1749
1750@item K
1751Constant integer 2
1752
1753@item L
1754Constant integer 0
1755
1756@item M
1757Constant that fits in 8 bits
1758
1759@item N
1760Constant integer @minus{}1
1761
1762@item O
1763Constant integer 8, 16, or 24
1764
1765@item P
1766Constant integer 1
1767
1768@item G
1769A floating point constant 0.0
1770
1771@item Q
1772A memory address based on Y or Z pointer with displacement.
1773@end table
1774
1775@item Epiphany---@file{config/epiphany/constraints.md}
1776@table @code
1777@item U16
1778An unsigned 16-bit constant.
1779
1780@item K
1781An unsigned 5-bit constant.
1782
1783@item L
1784A signed 11-bit constant.
1785
1786@item Cm1
1787A signed 11-bit constant added to @minus{}1.
1788Can only match when the @option{-m1reg-@var{reg}} option is active.
1789
1790@item Cl1
1791Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
1792being a block of trailing zeroes.
1793Can only match when the @option{-m1reg-@var{reg}} option is active.
1794
1795@item Cr1
1796Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
1797rest being zeroes.  Or to put it another way, one less than a power of two.
1798Can only match when the @option{-m1reg-@var{reg}} option is active.
1799
1800@item Cal
1801Constant for arithmetic/logical operations.
1802This is like @code{i}, except that for position independent code,
1803no symbols / expressions needing relocations are allowed.
1804
1805@item Csy
1806Symbolic constant for call/jump instruction.
1807
1808@item Rcs
1809The register class usable in short insns.  This is a register class
1810constraint, and can thus drive register allocation.
1811This constraint won't match unless @option{-mprefer-short-insn-regs} is
1812in effect.
1813
1814@item Rsc
1815The the register class of registers that can be used to hold a
1816sibcall call address.  I.e., a caller-saved register.
1817
1818@item Rct
1819Core control register class.
1820
1821@item Rgs
1822The register group usable in short insns.
1823This constraint does not use a register class, so that it only
1824passively matches suitable registers, and doesn't drive register allocation.
1825
1826@ifset INTERNALS
1827@item Car
1828Constant suitable for the addsi3_r pattern.  This is a valid offset
1829For byte, halfword, or word addressing.
1830@end ifset
1831
1832@item Rra
1833Matches the return address if it can be replaced with the link register.
1834
1835@item Rcc
1836Matches the integer condition code register.
1837
1838@item Sra
1839Matches the return address if it is in a stack slot.
1840
1841@item Cfm
1842Matches control register values to switch fp mode, which are encapsulated in
1843@code{UNSPEC_FP_MODE}.
1844@end table
1845
1846@item CR16 Architecture---@file{config/cr16/cr16.h}
1847@table @code
1848
1849@item b
1850Registers from r0 to r14 (registers without stack pointer)
1851
1852@item t
1853Register from r0 to r11 (all 16-bit registers)
1854
1855@item p
1856Register from r12 to r15 (all 32-bit registers)
1857
1858@item I
1859Signed constant that fits in 4 bits
1860
1861@item J
1862Signed constant that fits in 5 bits
1863
1864@item K
1865Signed constant that fits in 6 bits
1866
1867@item L
1868Unsigned constant that fits in 4 bits
1869
1870@item M
1871Signed constant that fits in 32 bits
1872
1873@item N
1874Check for 64 bits wide constants for add/sub instructions
1875
1876@item G
1877Floating point constant that is legal for store immediate
1878@end table
1879
1880@item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
1881@table @code
1882@item a
1883General register 1
1884
1885@item f
1886Floating point register
1887
1888@item q
1889Shift amount register
1890
1891@item x
1892Floating point register (deprecated)
1893
1894@item y
1895Upper floating point register (32-bit), floating point register (64-bit)
1896
1897@item Z
1898Any register
1899
1900@item I
1901Signed 11-bit integer constant
1902
1903@item J
1904Signed 14-bit integer constant
1905
1906@item K
1907Integer constant that can be deposited with a @code{zdepi} instruction
1908
1909@item L
1910Signed 5-bit integer constant
1911
1912@item M
1913Integer constant 0
1914
1915@item N
1916Integer constant that can be loaded with a @code{ldil} instruction
1917
1918@item O
1919Integer constant whose value plus one is a power of 2
1920
1921@item P
1922Integer constant that can be used for @code{and} operations in @code{depi}
1923and @code{extru} instructions
1924
1925@item S
1926Integer constant 31
1927
1928@item U
1929Integer constant 63
1930
1931@item G
1932Floating-point constant 0.0
1933
1934@item A
1935A @code{lo_sum} data-linkage-table memory operand
1936
1937@item Q
1938A memory operand that can be used as the destination operand of an
1939integer store instruction
1940
1941@item R
1942A scaled or unscaled indexed memory operand
1943
1944@item T
1945A memory operand for floating-point loads and stores
1946
1947@item W
1948A register indirect memory operand
1949@end table
1950
1951@item picoChip family---@file{picochip.h}
1952@table @code
1953@item k
1954Stack register.
1955
1956@item f
1957Pointer register.  A register which can be used to access memory without
1958supplying an offset.  Any other register can be used to access memory,
1959but will need a constant offset.  In the case of the offset being zero,
1960it is more efficient to use a pointer register, since this reduces code
1961size.
1962
1963@item t
1964A twin register.  A register which may be paired with an adjacent
1965register to create a 32-bit register.
1966
1967@item a
1968Any absolute memory address (e.g., symbolic constant, symbolic
1969constant + offset).
1970
1971@item I
19724-bit signed integer.
1973
1974@item J
19754-bit unsigned integer.
1976
1977@item K
19788-bit signed integer.
1979
1980@item M
1981Any constant whose absolute value is no greater than 4-bits.
1982
1983@item N
198410-bit signed integer
1985
1986@item O
198716-bit signed integer.
1988
1989@end table
1990
1991@item PowerPC and IBM RS6000---@file{config/rs6000/rs6000.h}
1992@table @code
1993@item b
1994Address base register
1995
1996@item d
1997Floating point register (containing 64-bit value)
1998
1999@item f
2000Floating point register (containing 32-bit value)
2001
2002@item v
2003Altivec vector register
2004
2005@item wd
2006VSX vector register to hold vector double data
2007
2008@item wf
2009VSX vector register to hold vector float data
2010
2011@item ws
2012VSX vector register to hold scalar float data
2013
2014@item wa
2015Any VSX register
2016
2017@item h
2018@samp{MQ}, @samp{CTR}, or @samp{LINK} register
2019
2020@item q
2021@samp{MQ} register
2022
2023@item c
2024@samp{CTR} register
2025
2026@item l
2027@samp{LINK} register
2028
2029@item x
2030@samp{CR} register (condition register) number 0
2031
2032@item y
2033@samp{CR} register (condition register)
2034
2035@item z
2036@samp{XER[CA]} carry bit (part of the XER register)
2037
2038@item I
2039Signed 16-bit constant
2040
2041@item J
2042Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for
2043@code{SImode} constants)
2044
2045@item K
2046Unsigned 16-bit constant
2047
2048@item L
2049Signed 16-bit constant shifted left 16 bits
2050
2051@item M
2052Constant larger than 31
2053
2054@item N
2055Exact power of 2
2056
2057@item O
2058Zero
2059
2060@item P
2061Constant whose negation is a signed 16-bit constant
2062
2063@item G
2064Floating point constant that can be loaded into a register with one
2065instruction per word
2066
2067@item H
2068Integer/Floating point constant that can be loaded into a register using
2069three instructions
2070
2071@item m
2072Memory operand.
2073Normally, @code{m} does not allow addresses that update the base register.
2074If @samp{<} or @samp{>} constraint is also used, they are allowed and
2075therefore on PowerPC targets in that case it is only safe
2076to use @samp{m<>} in an @code{asm} statement if that @code{asm} statement
2077accesses the operand exactly once.  The @code{asm} statement must also
2078use @samp{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
2079corresponding load or store instruction.  For example:
2080
2081@smallexample
2082asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
2083@end smallexample
2084
2085is correct but:
2086
2087@smallexample
2088asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
2089@end smallexample
2090
2091is not.
2092
2093@item es
2094A ``stable'' memory operand; that is, one which does not include any
2095automodification of the base register.  This used to be useful when
2096@samp{m} allowed automodification of the base register, but as those are now only
2097allowed when @samp{<} or @samp{>} is used, @samp{es} is basically the same
2098as @samp{m} without @samp{<} and @samp{>}.
2099
2100@item Q
2101Memory operand that is an offset from a register (it is usually better
2102to use @samp{m} or @samp{es} in @code{asm} statements)
2103
2104@item Z
2105Memory operand that is an indexed or indirect from a register (it is
2106usually better to use @samp{m} or @samp{es} in @code{asm} statements)
2107
2108@item R
2109AIX TOC entry
2110
2111@item a
2112Address operand that is an indexed or indirect from a register (@samp{p} is
2113preferable for @code{asm} statements)
2114
2115@item S
2116Constant suitable as a 64-bit mask operand
2117
2118@item T
2119Constant suitable as a 32-bit mask operand
2120
2121@item U
2122System V Release 4 small data area reference
2123
2124@item t
2125AND masks that can be performed by two rldic@{l, r@} instructions
2126
2127@item W
2128Vector constant that does not require memory
2129
2130@item j
2131Vector constant that is all zeros.
2132
2133@end table
2134
2135@item Intel 386---@file{config/i386/constraints.md}
2136@table @code
2137@item R
2138Legacy register---the eight integer registers available on all
2139i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
2140@code{si}, @code{di}, @code{bp}, @code{sp}).
2141
2142@item q
2143Any register accessible as @code{@var{r}l}.  In 32-bit mode, @code{a},
2144@code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.
2145
2146@item Q
2147Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
2148@code{c}, and @code{d}.
2149
2150@ifset INTERNALS
2151@item l
2152Any register that can be used as the index in a base+index memory
2153access: that is, any general register except the stack pointer.
2154@end ifset
2155
2156@item a
2157The @code{a} register.
2158
2159@item b
2160The @code{b} register.
2161
2162@item c
2163The @code{c} register.
2164
2165@item d
2166The @code{d} register.
2167
2168@item S
2169The @code{si} register.
2170
2171@item D
2172The @code{di} register.
2173
2174@item A
2175The @code{a} and @code{d} registers.  This class is used for instructions
2176that return double word results in the @code{ax:dx} register pair.  Single
2177word values will be allocated either in @code{ax} or @code{dx}.
2178For example on i386 the following implements @code{rdtsc}:
2179
2180@smallexample
2181unsigned long long rdtsc (void)
2182@{
2183  unsigned long long tick;
2184  __asm__ __volatile__("rdtsc":"=A"(tick));
2185  return tick;
2186@}
2187@end smallexample
2188
2189This is not correct on x86_64 as it would allocate tick in either @code{ax}
2190or @code{dx}.  You have to use the following variant instead:
2191
2192@smallexample
2193unsigned long long rdtsc (void)
2194@{
2195  unsigned int tickl, tickh;
2196  __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
2197  return ((unsigned long long)tickh << 32)|tickl;
2198@}
2199@end smallexample
2200
2201
2202@item f
2203Any 80387 floating-point (stack) register.
2204
2205@item t
2206Top of 80387 floating-point stack (@code{%st(0)}).
2207
2208@item u
2209Second from top of 80387 floating-point stack (@code{%st(1)}).
2210
2211@item y
2212Any MMX register.
2213
2214@item x
2215Any SSE register.
2216
2217@item Yz
2218First SSE register (@code{%xmm0}).
2219
2220@ifset INTERNALS
2221@item Y2
2222Any SSE register, when SSE2 is enabled.
2223
2224@item Yi
2225Any SSE register, when SSE2 and inter-unit moves are enabled.
2226
2227@item Ym
2228Any MMX register, when inter-unit moves are enabled.
2229@end ifset
2230
2231@item I
2232Integer constant in the range 0 @dots{} 31, for 32-bit shifts.
2233
2234@item J
2235Integer constant in the range 0 @dots{} 63, for 64-bit shifts.
2236
2237@item K
2238Signed 8-bit integer constant.
2239
2240@item L
2241@code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.
2242
2243@item M
22440, 1, 2, or 3 (shifts for the @code{lea} instruction).
2245
2246@item N
2247Unsigned 8-bit integer constant (for @code{in} and @code{out}
2248instructions).
2249
2250@ifset INTERNALS
2251@item O
2252Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
2253@end ifset
2254
2255@item G
2256Standard 80387 floating point constant.
2257
2258@item C
2259Standard SSE floating point constant.
2260
2261@item e
226232-bit signed integer constant, or a symbolic reference known
2263to fit that range (for immediate operands in sign-extending x86-64
2264instructions).
2265
2266@item Z
226732-bit unsigned integer constant, or a symbolic reference known
2268to fit that range (for immediate operands in zero-extending x86-64
2269instructions).
2270
2271@end table
2272
2273@item Intel IA-64---@file{config/ia64/ia64.h}
2274@table @code
2275@item a
2276General register @code{r0} to @code{r3} for @code{addl} instruction
2277
2278@item b
2279Branch register
2280
2281@item c
2282Predicate register (@samp{c} as in ``conditional'')
2283
2284@item d
2285Application register residing in M-unit
2286
2287@item e
2288Application register residing in I-unit
2289
2290@item f
2291Floating-point register
2292
2293@item m
2294Memory operand.  If used together with @samp{<} or @samp{>},
2295the operand can have postincrement and postdecrement which
2296require printing with @samp{%Pn} on IA-64.
2297
2298@item G
2299Floating-point constant 0.0 or 1.0
2300
2301@item I
230214-bit signed integer constant
2303
2304@item J
230522-bit signed integer constant
2306
2307@item K
23088-bit signed integer constant for logical instructions
2309
2310@item L
23118-bit adjusted signed integer constant for compare pseudo-ops
2312
2313@item M
23146-bit unsigned integer constant for shift counts
2315
2316@item N
23179-bit signed integer constant for load and store postincrements
2318
2319@item O
2320The constant zero
2321
2322@item P
23230 or @minus{}1 for @code{dep} instruction
2324
2325@item Q
2326Non-volatile memory for floating-point loads and stores
2327
2328@item R
2329Integer constant in the range 1 to 4 for @code{shladd} instruction
2330
2331@item S
2332Memory operand except postincrement and postdecrement.  This is
2333now roughly the same as @samp{m} when not used together with @samp{<}
2334or @samp{>}.
2335@end table
2336
2337@item FRV---@file{config/frv/frv.h}
2338@table @code
2339@item a
2340Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
2341
2342@item b
2343Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
2344
2345@item c
2346Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
2347@code{icc0} to @code{icc3}).
2348
2349@item d
2350Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
2351
2352@item e
2353Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
2354Odd registers are excluded not in the class but through the use of a machine
2355mode larger than 4 bytes.
2356
2357@item f
2358Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
2359
2360@item h
2361Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
2362Odd registers are excluded not in the class but through the use of a machine
2363mode larger than 4 bytes.
2364
2365@item l
2366Register in the class @code{LR_REG} (the @code{lr} register).
2367
2368@item q
2369Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
2370Register numbers not divisible by 4 are excluded not in the class but through
2371the use of a machine mode larger than 8 bytes.
2372
2373@item t
2374Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
2375
2376@item u
2377Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
2378
2379@item v
2380Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
2381
2382@item w
2383Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
2384
2385@item x
2386Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
2387Register numbers not divisible by 4 are excluded not in the class but through
2388the use of a machine mode larger than 8 bytes.
2389
2390@item z
2391Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
2392
2393@item A
2394Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
2395
2396@item B
2397Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
2398
2399@item C
2400Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
2401
2402@item G
2403Floating point constant zero
2404
2405@item I
24066-bit signed integer constant
2407
2408@item J
240910-bit signed integer constant
2410
2411@item L
241216-bit signed integer constant
2413
2414@item M
241516-bit unsigned integer constant
2416
2417@item N
241812-bit signed integer constant that is negative---i.e.@: in the
2419range of @minus{}2048 to @minus{}1
2420
2421@item O
2422Constant zero
2423
2424@item P
242512-bit signed integer constant that is greater than zero---i.e.@: in the
2426range of 1 to 2047.
2427
2428@end table
2429
2430@item Blackfin family---@file{config/bfin/constraints.md}
2431@table @code
2432@item a
2433P register
2434
2435@item d
2436D register
2437
2438@item z
2439A call clobbered P register.
2440
2441@item q@var{n}
2442A single register.  If @var{n} is in the range 0 to 7, the corresponding D
2443register.  If it is @code{A}, then the register P0.
2444
2445@item D
2446Even-numbered D register
2447
2448@item W
2449Odd-numbered D register
2450
2451@item e
2452Accumulator register.
2453
2454@item A
2455Even-numbered accumulator register.
2456
2457@item B
2458Odd-numbered accumulator register.
2459
2460@item b
2461I register
2462
2463@item v
2464B register
2465
2466@item f
2467M register
2468
2469@item c
2470Registers used for circular buffering, i.e. I, B, or L registers.
2471
2472@item C
2473The CC register.
2474
2475@item t
2476LT0 or LT1.
2477
2478@item k
2479LC0 or LC1.
2480
2481@item u
2482LB0 or LB1.
2483
2484@item x
2485Any D, P, B, M, I or L register.
2486
2487@item y
2488Additional registers typically used only in prologues and epilogues: RETS,
2489RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP.
2490
2491@item w
2492Any register except accumulators or CC.
2493
2494@item Ksh
2495Signed 16 bit integer (in the range @minus{}32768 to 32767)
2496
2497@item Kuh
2498Unsigned 16 bit integer (in the range 0 to 65535)
2499
2500@item Ks7
2501Signed 7 bit integer (in the range @minus{}64 to 63)
2502
2503@item Ku7
2504Unsigned 7 bit integer (in the range 0 to 127)
2505
2506@item Ku5
2507Unsigned 5 bit integer (in the range 0 to 31)
2508
2509@item Ks4
2510Signed 4 bit integer (in the range @minus{}8 to 7)
2511
2512@item Ks3
2513Signed 3 bit integer (in the range @minus{}3 to 4)
2514
2515@item Ku3
2516Unsigned 3 bit integer (in the range 0 to 7)
2517
2518@item P@var{n}
2519Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4.
2520
2521@item PA
2522An integer equal to one of the MACFLAG_XXX constants that is suitable for
2523use with either accumulator.
2524
2525@item PB
2526An integer equal to one of the MACFLAG_XXX constants that is suitable for
2527use only with accumulator A1.
2528
2529@item M1
2530Constant 255.
2531
2532@item M2
2533Constant 65535.
2534
2535@item J
2536An integer constant with exactly a single bit set.
2537
2538@item L
2539An integer constant with all bits set except exactly one.
2540
2541@item H
2542
2543@item Q
2544Any SYMBOL_REF.
2545@end table
2546
2547@item M32C---@file{config/m32c/m32c.c}
2548@table @code
2549@item Rsp
2550@itemx Rfb
2551@itemx Rsb
2552@samp{$sp}, @samp{$fb}, @samp{$sb}.
2553
2554@item Rcr
2555Any control register, when they're 16 bits wide (nothing if control
2556registers are 24 bits wide)
2557
2558@item Rcl
2559Any control register, when they're 24 bits wide.
2560
2561@item R0w
2562@itemx R1w
2563@itemx R2w
2564@itemx R3w
2565$r0, $r1, $r2, $r3.
2566
2567@item R02
2568$r0 or $r2, or $r2r0 for 32 bit values.
2569
2570@item R13
2571$r1 or $r3, or $r3r1 for 32 bit values.
2572
2573@item Rdi
2574A register that can hold a 64 bit value.
2575
2576@item Rhl
2577$r0 or $r1 (registers with addressable high/low bytes)
2578
2579@item R23
2580$r2 or $r3
2581
2582@item Raa
2583Address registers
2584
2585@item Raw
2586Address registers when they're 16 bits wide.
2587
2588@item Ral
2589Address registers when they're 24 bits wide.
2590
2591@item Rqi
2592Registers that can hold QI values.
2593
2594@item Rad
2595Registers that can be used with displacements ($a0, $a1, $sb).
2596
2597@item Rsi
2598Registers that can hold 32 bit values.
2599
2600@item Rhi
2601Registers that can hold 16 bit values.
2602
2603@item Rhc
2604Registers chat can hold 16 bit values, including all control
2605registers.
2606
2607@item Rra
2608$r0 through R1, plus $a0 and $a1.
2609
2610@item Rfl
2611The flags register.
2612
2613@item Rmm
2614The memory-based pseudo-registers $mem0 through $mem15.
2615
2616@item Rpi
2617Registers that can hold pointers (16 bit registers for r8c, m16c; 24
2618bit registers for m32cm, m32c).
2619
2620@item Rpa
2621Matches multiple registers in a PARALLEL to form a larger register.
2622Used to match function return values.
2623
2624@item Is3
2625@minus{}8 @dots{} 7
2626
2627@item IS1
2628@minus{}128 @dots{} 127
2629
2630@item IS2
2631@minus{}32768 @dots{} 32767
2632
2633@item IU2
26340 @dots{} 65535
2635
2636@item In4
2637@minus{}8 @dots{} @minus{}1 or 1 @dots{} 8
2638
2639@item In5
2640@minus{}16 @dots{} @minus{}1 or 1 @dots{} 16
2641
2642@item In6
2643@minus{}32 @dots{} @minus{}1 or 1 @dots{} 32
2644
2645@item IM2
2646@minus{}65536 @dots{} @minus{}1
2647
2648@item Ilb
2649An 8 bit value with exactly one bit set.
2650
2651@item Ilw
2652A 16 bit value with exactly one bit set.
2653
2654@item Sd
2655The common src/dest memory addressing modes.
2656
2657@item Sa
2658Memory addressed using $a0 or $a1.
2659
2660@item Si
2661Memory addressed with immediate addresses.
2662
2663@item Ss
2664Memory addressed using the stack pointer ($sp).
2665
2666@item Sf
2667Memory addressed using the frame base register ($fb).
2668
2669@item Ss
2670Memory addressed using the small base register ($sb).
2671
2672@item S1
2673$r1h
2674@end table
2675
2676@item MeP---@file{config/mep/constraints.md}
2677@table @code
2678
2679@item a
2680The $sp register.
2681
2682@item b
2683The $tp register.
2684
2685@item c
2686Any control register.
2687
2688@item d
2689Either the $hi or the $lo register.
2690
2691@item em
2692Coprocessor registers that can be directly loaded ($c0-$c15).
2693
2694@item ex
2695Coprocessor registers that can be moved to each other.
2696
2697@item er
2698Coprocessor registers that can be moved to core registers.
2699
2700@item h
2701The $hi register.
2702
2703@item j
2704The $rpc register.
2705
2706@item l
2707The $lo register.
2708
2709@item t
2710Registers which can be used in $tp-relative addressing.
2711
2712@item v
2713The $gp register.
2714
2715@item x
2716The coprocessor registers.
2717
2718@item y
2719The coprocessor control registers.
2720
2721@item z
2722The $0 register.
2723
2724@item A
2725User-defined register set A.
2726
2727@item B
2728User-defined register set B.
2729
2730@item C
2731User-defined register set C.
2732
2733@item D
2734User-defined register set D.
2735
2736@item I
2737Offsets for $gp-rel addressing.
2738
2739@item J
2740Constants that can be used directly with boolean insns.
2741
2742@item K
2743Constants that can be moved directly to registers.
2744
2745@item L
2746Small constants that can be added to registers.
2747
2748@item M
2749Long shift counts.
2750
2751@item N
2752Small constants that can be compared to registers.
2753
2754@item O
2755Constants that can be loaded into the top half of registers.
2756
2757@item S
2758Signed 8-bit immediates.
2759
2760@item T
2761Symbols encoded for $tp-rel or $gp-rel addressing.
2762
2763@item U
2764Non-constant addresses for loading/saving coprocessor registers.
2765
2766@item W
2767The top half of a symbol's value.
2768
2769@item Y
2770A register indirect address without offset.
2771
2772@item Z
2773Symbolic references to the control bus.
2774
2775@end table
2776
2777@item MicroBlaze---@file{config/microblaze/constraints.md}
2778@table @code
2779@item d
2780A general register (@code{r0} to @code{r31}).
2781
2782@item z
2783A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
2784
2785@end table
2786
2787@item MIPS---@file{config/mips/constraints.md}
2788@table @code
2789@item d
2790An address register.  This is equivalent to @code{r} unless
2791generating MIPS16 code.
2792
2793@item f
2794A floating-point register (if available).
2795
2796@item h
2797Formerly the @code{hi} register.  This constraint is no longer supported.
2798
2799@item l
2800The @code{lo} register.  Use this register to store values that are
2801no bigger than a word.
2802
2803@item x
2804The concatenated @code{hi} and @code{lo} registers.  Use this register
2805to store doubleword values.
2806
2807@item c
2808A register suitable for use in an indirect jump.  This will always be
2809@code{$25} for @option{-mabicalls}.
2810
2811@item v
2812Register @code{$3}.  Do not use this constraint in new code;
2813it is retained only for compatibility with glibc.
2814
2815@item y
2816Equivalent to @code{r}; retained for backwards compatibility.
2817
2818@item z
2819A floating-point condition code register.
2820
2821@item I
2822A signed 16-bit constant (for arithmetic instructions).
2823
2824@item J
2825Integer zero.
2826
2827@item K
2828An unsigned 16-bit constant (for logic instructions).
2829
2830@item L
2831A signed 32-bit constant in which the lower 16 bits are zero.
2832Such constants can be loaded using @code{lui}.
2833
2834@item M
2835A constant that cannot be loaded using @code{lui}, @code{addiu}
2836or @code{ori}.
2837
2838@item N
2839A constant in the range @minus{}65535 to @minus{}1 (inclusive).
2840
2841@item O
2842A signed 15-bit constant.
2843
2844@item P
2845A constant in the range 1 to 65535 (inclusive).
2846
2847@item G
2848Floating-point zero.
2849
2850@item R
2851An address that can be used in a non-macro load or store.
2852@end table
2853
2854@item Motorola 680x0---@file{config/m68k/constraints.md}
2855@table @code
2856@item a
2857Address register
2858
2859@item d
2860Data register
2861
2862@item f
286368881 floating-point register, if available
2864
2865@item I
2866Integer in the range 1 to 8
2867
2868@item J
286916-bit signed number
2870
2871@item K
2872Signed number whose magnitude is greater than 0x80
2873
2874@item L
2875Integer in the range @minus{}8 to @minus{}1
2876
2877@item M
2878Signed number whose magnitude is greater than 0x100
2879
2880@item N
2881Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate
2882
2883@item O
288416 (for rotate using swap)
2885
2886@item P
2887Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate
2888
2889@item R
2890Numbers that mov3q can handle
2891
2892@item G
2893Floating point constant that is not a 68881 constant
2894
2895@item S
2896Operands that satisfy 'm' when -mpcrel is in effect
2897
2898@item T
2899Operands that satisfy 's' when -mpcrel is not in effect
2900
2901@item Q
2902Address register indirect addressing mode
2903
2904@item U
2905Register offset addressing
2906
2907@item W
2908const_call_operand
2909
2910@item Cs
2911symbol_ref or const
2912
2913@item Ci
2914const_int
2915
2916@item C0
2917const_int 0
2918
2919@item Cj
2920Range of signed numbers that don't fit in 16 bits
2921
2922@item Cmvq
2923Integers valid for mvq
2924
2925@item Capsw
2926Integers valid for a moveq followed by a swap
2927
2928@item Cmvz
2929Integers valid for mvz
2930
2931@item Cmvs
2932Integers valid for mvs
2933
2934@item Ap
2935push_operand
2936
2937@item Ac
2938Non-register operands allowed in clr
2939
2940@end table
2941
2942@item Moxie---@file{config/moxie/constraints.md}
2943@table @code
2944@item A
2945An absolute address
2946
2947@item B
2948An offset address
2949
2950@item W
2951A register indirect memory operand
2952
2953@item I
2954A constant in the range of 0 to 255.
2955
2956@item N
2957A constant in the range of 0 to @minus{}255.
2958
2959@end table
2960
2961@item PDP-11---@file{config/pdp11/constraints.md}
2962@table @code
2963@item a
2964Floating point registers AC0 through AC3.  These can be loaded from/to
2965memory with a single instruction.
2966
2967@item d
2968Odd numbered general registers (R1, R3, R5).  These are used for
296916-bit multiply operations.
2970
2971@item f
2972Any of the floating point registers (AC0 through AC5).
2973
2974@item G
2975Floating point constant 0.
2976
2977@item I
2978An integer constant that fits in 16 bits.
2979
2980@item J
2981An integer constant whose low order 16 bits are zero.
2982
2983@item K
2984An integer constant that does not meet the constraints for codes
2985@samp{I} or @samp{J}.
2986
2987@item L
2988The integer constant 1.
2989
2990@item M
2991The integer constant @minus{}1.
2992
2993@item N
2994The integer constant 0.
2995
2996@item O
2997Integer constants @minus{}4 through @minus{}1 and 1 through 4; shifts by these
2998amounts are handled as multiple single-bit shifts rather than a single
2999variable-length shift.
3000
3001@item Q
3002A memory reference which requires an additional word (address or
3003offset) after the opcode.
3004
3005@item R
3006A memory reference that is encoded within the opcode.
3007
3008@end table
3009
3010@item RL78---@file{config/rl78/constraints.md}
3011@table @code
3012
3013@item Int3
3014An integer constant in the range 1 @dots{} 7.
3015@item Int8
3016An integer constant in the range 0 @dots{} 255.
3017@item J
3018An integer constant in the range @minus{}255 @dots{} 0
3019@item K
3020The integer constant 1.
3021@item L
3022The integer constant -1.
3023@item M
3024The integer constant 0.
3025@item N
3026The integer constant 2.
3027@item O
3028The integer constant -2.
3029@item P
3030An integer constant in the range 1 @dots{} 15.
3031@item Qbi
3032The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
3033@item Qsc
3034The synthetic compare types--gt, lt, ge, and le.
3035@item Wab
3036A memory reference with an absolute address.
3037@item Wbc
3038A memory reference using @code{BC} as a base register, with an optional offset.
3039@item Wca
3040A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
3041@item Wcv
3042A memory reference using any 16-bit register pair for the address, for calls.
3043@item Wd2
3044A memory reference using @code{DE} as a base register, with an optional offset.
3045@item Wde
3046A memory reference using @code{DE} as a base register, without any offset.
3047@item Wfr
3048Any memory reference to an address in the far address space.
3049@item Wh1
3050A memory reference using @code{HL} as a base register, with an optional one-byte offset.
3051@item Whb
3052A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
3053@item Whl
3054A memory reference using @code{HL} as a base register, without any offset.
3055@item Ws1
3056A memory reference using @code{SP} as a base register, with an optional one-byte offset.
3057@item Y
3058Any memory reference to an address in the near address space.
3059@item A
3060The @code{AX} register.
3061@item B
3062The @code{BC} register.
3063@item D
3064The @code{DE} register.
3065@item R
3066@code{A} through @code{L} registers.
3067@item S
3068The @code{SP} register.
3069@item T
3070The @code{HL} register.
3071@item Z08W
3072The 16-bit @code{R8} register.
3073@item Z10W
3074The 16-bit @code{R10} register.
3075@item Zint
3076The registers reserved for interrupts (@code{R24} to @code{R31}).
3077@item a
3078The @code{A} register.
3079@item b
3080The @code{B} register.
3081@item c
3082The @code{C} register.
3083@item d
3084The @code{D} register.
3085@item e
3086The @code{E} register.
3087@item h
3088The @code{H} register.
3089@item l
3090The @code{L} register.
3091@item v
3092The virtual registers.
3093@item w
3094The @code{PSW} register.
3095@item x
3096The @code{X} register.
3097
3098@end table
3099
3100@item RX---@file{config/rx/constraints.md}
3101@table @code
3102@item Q
3103An address which does not involve register indirect addressing or
3104pre/post increment/decrement addressing.
3105
3106@item Symbol
3107A symbol reference.
3108
3109@item Int08
3110A constant in the range @minus{}256 to 255, inclusive.
3111
3112@item Sint08
3113A constant in the range @minus{}128 to 127, inclusive.
3114
3115@item Sint16
3116A constant in the range @minus{}32768 to 32767, inclusive.
3117
3118@item Sint24
3119A constant in the range @minus{}8388608 to 8388607, inclusive.
3120
3121@item Uint04
3122A constant in the range 0 to 15, inclusive.
3123
3124@end table
3125
3126@need 1000
3127@item SPARC---@file{config/sparc/sparc.h}
3128@table @code
3129@item f
3130Floating-point register on the SPARC-V8 architecture and
3131lower floating-point register on the SPARC-V9 architecture.
3132
3133@item e
3134Floating-point register.  It is equivalent to @samp{f} on the
3135SPARC-V8 architecture and contains both lower and upper
3136floating-point registers on the SPARC-V9 architecture.
3137
3138@item c
3139Floating-point condition code register.
3140
3141@item d
3142Lower floating-point register.  It is only valid on the SPARC-V9
3143architecture when the Visual Instruction Set is available.
3144
3145@item b
3146Floating-point register.  It is only valid on the SPARC-V9 architecture
3147when the Visual Instruction Set is available.
3148
3149@item h
315064-bit global or out register for the SPARC-V8+ architecture.
3151
3152@item D
3153A vector constant
3154
3155@item I
3156Signed 13-bit constant
3157
3158@item J
3159Zero
3160
3161@item K
316232-bit constant with the low 12 bits clear (a constant that can be
3163loaded with the @code{sethi} instruction)
3164
3165@item L
3166A constant in the range supported by @code{movcc} instructions
3167
3168@item M
3169A constant in the range supported by @code{movrcc} instructions
3170
3171@item N
3172Same as @samp{K}, except that it verifies that bits that are not in the
3173lower 32-bit range are all zero.  Must be used instead of @samp{K} for
3174modes wider than @code{SImode}
3175
3176@item O
3177The constant 4096
3178
3179@item G
3180Floating-point zero
3181
3182@item H
3183Signed 13-bit constant, sign-extended to 32 or 64 bits
3184
3185@item Q
3186Floating-point constant whose integral representation can
3187be moved into an integer register using a single sethi
3188instruction
3189
3190@item R
3191Floating-point constant whose integral representation can
3192be moved into an integer register using a single mov
3193instruction
3194
3195@item S
3196Floating-point constant whose integral representation can
3197be moved into an integer register using a high/lo_sum
3198instruction sequence
3199
3200@item T
3201Memory address aligned to an 8-byte boundary
3202
3203@item U
3204Even register
3205
3206@item W
3207Memory address for @samp{e} constraint registers
3208
3209@item Y
3210Vector zero
3211
3212@end table
3213
3214@item SPU---@file{config/spu/spu.h}
3215@table @code
3216@item a
3217An immediate which can be loaded with the il/ila/ilh/ilhu instructions.  const_int is treated as a 64 bit value.
3218
3219@item c
3220An immediate for and/xor/or instructions.  const_int is treated as a 64 bit value.
3221
3222@item d
3223An immediate for the @code{iohl} instruction.  const_int is treated as a 64 bit value.
3224
3225@item f
3226An immediate which can be loaded with @code{fsmbi}.
3227
3228@item A
3229An immediate which can be loaded with the il/ila/ilh/ilhu instructions.  const_int is treated as a 32 bit value.
3230
3231@item B
3232An immediate for most arithmetic instructions.  const_int is treated as a 32 bit value.
3233
3234@item C
3235An immediate for and/xor/or instructions.  const_int is treated as a 32 bit value.
3236
3237@item D
3238An immediate for the @code{iohl} instruction.  const_int is treated as a 32 bit value.
3239
3240@item I
3241A constant in the range [@minus{}64, 63] for shift/rotate instructions.
3242
3243@item J
3244An unsigned 7-bit constant for conversion/nop/channel instructions.
3245
3246@item K
3247A signed 10-bit constant for most arithmetic instructions.
3248
3249@item M
3250A signed 16 bit immediate for @code{stop}.
3251
3252@item N
3253An unsigned 16-bit constant for @code{iohl} and @code{fsmbi}.
3254
3255@item O
3256An unsigned 7-bit constant whose 3 least significant bits are 0.
3257
3258@item P
3259An unsigned 3-bit constant for 16-byte rotates and shifts
3260
3261@item R
3262Call operand, reg, for indirect calls
3263
3264@item S
3265Call operand, symbol, for relative calls.
3266
3267@item T
3268Call operand, const_int, for absolute calls.
3269
3270@item U
3271An immediate which can be loaded with the il/ila/ilh/ilhu instructions.  const_int is sign extended to 128 bit.
3272
3273@item W
3274An immediate for shift and rotate instructions.  const_int is treated as a 32 bit value.
3275
3276@item Y
3277An immediate for and/xor/or instructions.  const_int is sign extended as a 128 bit.
3278
3279@item Z
3280An immediate for the @code{iohl} instruction.  const_int is sign extended to 128 bit.
3281
3282@end table
3283
3284@item S/390 and zSeries---@file{config/s390/s390.h}
3285@table @code
3286@item a
3287Address register (general purpose register except r0)
3288
3289@item c
3290Condition code register
3291
3292@item d
3293Data register (arbitrary general purpose register)
3294
3295@item f
3296Floating-point register
3297
3298@item I
3299Unsigned 8-bit constant (0--255)
3300
3301@item J
3302Unsigned 12-bit constant (0--4095)
3303
3304@item K
3305Signed 16-bit constant (@minus{}32768--32767)
3306
3307@item L
3308Value appropriate as displacement.
3309@table @code
3310@item (0..4095)
3311for short displacement
3312@item (@minus{}524288..524287)
3313for long displacement
3314@end table
3315
3316@item M
3317Constant integer with a value of 0x7fffffff.
3318
3319@item N
3320Multiple letter constraint followed by 4 parameter letters.
3321@table @code
3322@item 0..9:
3323number of the part counting from most to least significant
3324@item H,Q:
3325mode of the part
3326@item D,S,H:
3327mode of the containing operand
3328@item 0,F:
3329value of the other parts (F---all bits set)
3330@end table
3331The constraint matches if the specified part of a constant
3332has a value different from its other parts.
3333
3334@item Q
3335Memory reference without index register and with short displacement.
3336
3337@item R
3338Memory reference with index register and short displacement.
3339
3340@item S
3341Memory reference without index register but with long displacement.
3342
3343@item T
3344Memory reference with index register and long displacement.
3345
3346@item U
3347Pointer with short displacement.
3348
3349@item W
3350Pointer with long displacement.
3351
3352@item Y
3353Shift count operand.
3354
3355@end table
3356
3357@item Score family---@file{config/score/score.h}
3358@table @code
3359@item d
3360Registers from r0 to r32.
3361
3362@item e
3363Registers from r0 to r16.
3364
3365@item t
3366r8---r11 or r22---r27 registers.
3367
3368@item h
3369hi register.
3370
3371@item l
3372lo register.
3373
3374@item x
3375hi + lo register.
3376
3377@item q
3378cnt register.
3379
3380@item y
3381lcb register.
3382
3383@item z
3384scb register.
3385
3386@item a
3387cnt + lcb + scb register.
3388
3389@item c
3390cr0---cr15 register.
3391
3392@item b
3393cp1 registers.
3394
3395@item f
3396cp2 registers.
3397
3398@item i
3399cp3 registers.
3400
3401@item j
3402cp1 + cp2 + cp3 registers.
3403
3404@item I
3405High 16-bit constant (32-bit constant with 16 LSBs zero).
3406
3407@item J
3408Unsigned 5 bit integer (in the range 0 to 31).
3409
3410@item K
3411Unsigned 16 bit integer (in the range 0 to 65535).
3412
3413@item L
3414Signed 16 bit integer (in the range @minus{}32768 to 32767).
3415
3416@item M
3417Unsigned 14 bit integer (in the range 0 to 16383).
3418
3419@item N
3420Signed 14 bit integer (in the range @minus{}8192 to 8191).
3421
3422@item Z
3423Any SYMBOL_REF.
3424@end table
3425
3426@item Xstormy16---@file{config/stormy16/stormy16.h}
3427@table @code
3428@item a
3429Register r0.
3430
3431@item b
3432Register r1.
3433
3434@item c
3435Register r2.
3436
3437@item d
3438Register r8.
3439
3440@item e
3441Registers r0 through r7.
3442
3443@item t
3444Registers r0 and r1.
3445
3446@item y
3447The carry register.
3448
3449@item z
3450Registers r8 and r9.
3451
3452@item I
3453A constant between 0 and 3 inclusive.
3454
3455@item J
3456A constant that has exactly one bit set.
3457
3458@item K
3459A constant that has exactly one bit clear.
3460
3461@item L
3462A constant between 0 and 255 inclusive.
3463
3464@item M
3465A constant between @minus{}255 and 0 inclusive.
3466
3467@item N
3468A constant between @minus{}3 and 0 inclusive.
3469
3470@item O
3471A constant between 1 and 4 inclusive.
3472
3473@item P
3474A constant between @minus{}4 and @minus{}1 inclusive.
3475
3476@item Q
3477A memory reference that is a stack push.
3478
3479@item R
3480A memory reference that is a stack pop.
3481
3482@item S
3483A memory reference that refers to a constant address of known value.
3484
3485@item T
3486The register indicated by Rx (not implemented yet).
3487
3488@item U
3489A constant that is not between 2 and 15 inclusive.
3490
3491@item Z
3492The constant 0.
3493
3494@end table
3495
3496@item TI C6X family---@file{config/c6x/constraints.md}
3497@table @code
3498@item a
3499Register file A (A0--A31).
3500
3501@item b
3502Register file B (B0--B31).
3503
3504@item A
3505Predicate registers in register file A (A0--A2 on C64X and
3506higher, A1 and A2 otherwise).
3507
3508@item B
3509Predicate registers in register file B (B0--B2).
3510
3511@item C
3512A call-used register in register file B (B0--B9, B16--B31).
3513
3514@item Da
3515Register file A, excluding predicate registers (A3--A31,
3516plus A0 if not C64X or higher).
3517
3518@item Db
3519Register file B, excluding predicate registers (B3--B31).
3520
3521@item Iu4
3522Integer constant in the range 0 @dots{} 15.
3523
3524@item Iu5
3525Integer constant in the range 0 @dots{} 31.
3526
3527@item In5
3528Integer constant in the range @minus{}31 @dots{} 0.
3529
3530@item Is5
3531Integer constant in the range @minus{}16 @dots{} 15.
3532
3533@item I5x
3534Integer constant that can be the operand of an ADDA or a SUBA insn.
3535
3536@item IuB
3537Integer constant in the range 0 @dots{} 65535.
3538
3539@item IsB
3540Integer constant in the range @minus{}32768 @dots{} 32767.
3541
3542@item IsC
3543Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.
3544
3545@item Jc
3546Integer constant that is a valid mask for the clr instruction.
3547
3548@item Js
3549Integer constant that is a valid mask for the set instruction.
3550
3551@item Q
3552Memory location with A base register.
3553
3554@item R
3555Memory location with B base register.
3556
3557@ifset INTERNALS
3558@item S0
3559On C64x+ targets, a GP-relative small data reference.
3560
3561@item S1
3562Any kind of @code{SYMBOL_REF}, for use in a call address.
3563
3564@item Si
3565Any kind of immediate operand, unless it matches the S0 constraint.
3566
3567@item T
3568Memory location with B base register, but not using a long offset.
3569
3570@item W
3571A memory operand with an address that can't be used in an unaligned access.
3572
3573@end ifset
3574@item Z
3575Register B14 (aka DP).
3576
3577@end table
3578
3579@item TILE-Gx---@file{config/tilegx/constraints.md}
3580@table @code
3581@item R00
3582@itemx R01
3583@itemx R02
3584@itemx R03
3585@itemx R04
3586@itemx R05
3587@itemx R06
3588@itemx R07
3589@itemx R08
3590@itemx R09
3591@itemx R10
3592Each of these represents a register constraint for an individual
3593register, from r0 to r10.
3594
3595@item I
3596Signed 8-bit integer constant.
3597
3598@item J
3599Signed 16-bit integer constant.
3600
3601@item K
3602Unsigned 16-bit integer constant.
3603
3604@item L
3605Integer constant that fits in one signed byte when incremented by one
3606(@minus{}129 @dots{} 126).
3607
3608@item m
3609Memory operand.  If used together with @samp{<} or @samp{>}, the
3610operand can have postincrement which requires printing with @samp{%In}
3611and @samp{%in} on TILE-Gx.  For example:
3612
3613@smallexample
3614asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val));
3615@end smallexample
3616
3617@item M
3618A bit mask suitable for the BFINS instruction.
3619
3620@item N
3621Integer constant that is a byte tiled out eight times.
3622
3623@item O
3624The integer zero constant.
3625
3626@item P
3627Integer constant that is a sign-extended byte tiled out as four shorts.
3628
3629@item Q
3630Integer constant that fits in one signed byte when incremented
3631(@minus{}129 @dots{} 126), but excluding -1.
3632
3633@item S
3634Integer constant that has all 1 bits consecutive and starting at bit 0.
3635
3636@item T
3637A 16-bit fragment of a got, tls, or pc-relative reference.
3638
3639@item U
3640Memory operand except postincrement.  This is roughly the same as
3641@samp{m} when not used together with @samp{<} or @samp{>}.
3642
3643@item W
3644An 8-element vector constant with identical elements.
3645
3646@item Y
3647A 4-element vector constant with identical elements.
3648
3649@item Z0
3650The integer constant 0xffffffff.
3651
3652@item Z1
3653The integer constant 0xffffffff00000000.
3654
3655@end table
3656
3657@item TILEPro---@file{config/tilepro/constraints.md}
3658@table @code
3659@item R00
3660@itemx R01
3661@itemx R02
3662@itemx R03
3663@itemx R04
3664@itemx R05
3665@itemx R06
3666@itemx R07
3667@itemx R08
3668@itemx R09
3669@itemx R10
3670Each of these represents a register constraint for an individual
3671register, from r0 to r10.
3672
3673@item I
3674Signed 8-bit integer constant.
3675
3676@item J
3677Signed 16-bit integer constant.
3678
3679@item K
3680Nonzero integer constant with low 16 bits zero.
3681
3682@item L
3683Integer constant that fits in one signed byte when incremented by one
3684(@minus{}129 @dots{} 126).
3685
3686@item m
3687Memory operand.  If used together with @samp{<} or @samp{>}, the
3688operand can have postincrement which requires printing with @samp{%In}
3689and @samp{%in} on TILEPro.  For example:
3690
3691@smallexample
3692asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val));
3693@end smallexample
3694
3695@item M
3696A bit mask suitable for the MM instruction.
3697
3698@item N
3699Integer constant that is a byte tiled out four times.
3700
3701@item O
3702The integer zero constant.
3703
3704@item P
3705Integer constant that is a sign-extended byte tiled out as two shorts.
3706
3707@item Q
3708Integer constant that fits in one signed byte when incremented
3709(@minus{}129 @dots{} 126), but excluding -1.
3710
3711@item T
3712A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative
3713reference.
3714
3715@item U
3716Memory operand except postincrement.  This is roughly the same as
3717@samp{m} when not used together with @samp{<} or @samp{>}.
3718
3719@item W
3720A 4-element vector constant with identical elements.
3721
3722@item Y
3723A 2-element vector constant with identical elements.
3724
3725@end table
3726
3727@item Xtensa---@file{config/xtensa/constraints.md}
3728@table @code
3729@item a
3730General-purpose 32-bit register
3731
3732@item b
3733One-bit boolean register
3734
3735@item A
3736MAC16 40-bit accumulator register
3737
3738@item I
3739Signed 12-bit integer constant, for use in MOVI instructions
3740
3741@item J
3742Signed 8-bit integer constant, for use in ADDI instructions
3743
3744@item K
3745Integer constant valid for BccI instructions
3746
3747@item L
3748Unsigned constant valid for BccUI instructions
3749
3750@end table
3751
3752@end table
3753
3754@ifset INTERNALS
3755@node Disable Insn Alternatives
3756@subsection Disable insn alternatives using the @code{enabled} attribute
3757@cindex enabled
3758
3759The @code{enabled} insn attribute may be used to disable certain insn
3760alternatives for machine-specific reasons.  This is useful when adding
3761new instructions to an existing pattern which are only available for
3762certain cpu architecture levels as specified with the @code{-march=}
3763option.
3764
3765If an insn alternative is disabled, then it will never be used.  The
3766compiler treats the constraints for the disabled alternative as
3767unsatisfiable.
3768
3769In order to make use of the @code{enabled} attribute a back end has to add
3770in the machine description files:
3771
3772@enumerate
3773@item
3774A definition of the @code{enabled} insn attribute.  The attribute is
3775defined as usual using the @code{define_attr} command.  This
3776definition should be based on other insn attributes and/or target flags.
3777The @code{enabled} attribute is a numeric attribute and should evaluate to
3778@code{(const_int 1)} for an enabled alternative and to
3779@code{(const_int 0)} otherwise.
3780@item
3781A definition of another insn attribute used to describe for what
3782reason an insn alternative might be available or
3783not.  E.g. @code{cpu_facility} as in the example below.
3784@item
3785An assignment for the second attribute to each insn definition
3786combining instructions which are not all available under the same
3787circumstances.  (Note: It obviously only makes sense for definitions
3788with more than one alternative.  Otherwise the insn pattern should be
3789disabled or enabled using the insn condition.)
3790@end enumerate
3791
3792E.g. the following two patterns could easily be merged using the @code{enabled}
3793attribute:
3794
3795@smallexample
3796
3797(define_insn "*movdi_old"
3798  [(set (match_operand:DI 0 "register_operand" "=d")
3799        (match_operand:DI 1 "register_operand" " d"))]
3800  "!TARGET_NEW"
3801  "lgr %0,%1")
3802
3803(define_insn "*movdi_new"
3804  [(set (match_operand:DI 0 "register_operand" "=d,f,d")
3805        (match_operand:DI 1 "register_operand" " d,d,f"))]
3806  "TARGET_NEW"
3807  "@@
3808   lgr  %0,%1
3809   ldgr %0,%1
3810   lgdr %0,%1")
3811
3812@end smallexample
3813
3814to:
3815
3816@smallexample
3817
3818(define_insn "*movdi_combined"
3819  [(set (match_operand:DI 0 "register_operand" "=d,f,d")
3820        (match_operand:DI 1 "register_operand" " d,d,f"))]
3821  ""
3822  "@@
3823   lgr  %0,%1
3824   ldgr %0,%1
3825   lgdr %0,%1"
3826  [(set_attr "cpu_facility" "*,new,new")])
3827
3828@end smallexample
3829
3830with the @code{enabled} attribute defined like this:
3831
3832@smallexample
3833
3834(define_attr "cpu_facility" "standard,new" (const_string "standard"))
3835
3836(define_attr "enabled" ""
3837  (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
3838         (and (eq_attr "cpu_facility" "new")
3839              (ne (symbol_ref "TARGET_NEW") (const_int 0)))
3840         (const_int 1)]
3841        (const_int 0)))
3842
3843@end smallexample
3844
3845@end ifset
3846
3847@ifset INTERNALS
3848@node Define Constraints
3849@subsection Defining Machine-Specific Constraints
3850@cindex defining constraints
3851@cindex constraints, defining
3852
3853Machine-specific constraints fall into two categories: register and
3854non-register constraints.  Within the latter category, constraints
3855which allow subsets of all possible memory or address operands should
3856be specially marked, to give @code{reload} more information.
3857
3858Machine-specific constraints can be given names of arbitrary length,
3859but they must be entirely composed of letters, digits, underscores
3860(@samp{_}), and angle brackets (@samp{< >}).  Like C identifiers, they
3861must begin with a letter or underscore.
3862
3863In order to avoid ambiguity in operand constraint strings, no
3864constraint can have a name that begins with any other constraint's
3865name.  For example, if @code{x} is defined as a constraint name,
3866@code{xy} may not be, and vice versa.  As a consequence of this rule,
3867no constraint may begin with one of the generic constraint letters:
3868@samp{E F V X g i m n o p r s}.
3869
3870Register constraints correspond directly to register classes.
3871@xref{Register Classes}.  There is thus not much flexibility in their
3872definitions.
3873
3874@deffn {MD Expression} define_register_constraint name regclass docstring
3875All three arguments are string constants.
3876@var{name} is the name of the constraint, as it will appear in
3877@code{match_operand} expressions.  If @var{name} is a multi-letter
3878constraint its length shall be the same for all constraints starting
3879with the same letter.  @var{regclass} can be either the
3880name of the corresponding register class (@pxref{Register Classes}),
3881or a C expression which evaluates to the appropriate register class.
3882If it is an expression, it must have no side effects, and it cannot
3883look at the operand.  The usual use of expressions is to map some
3884register constraints to @code{NO_REGS} when the register class
3885is not available on a given subarchitecture.
3886
3887@var{docstring} is a sentence documenting the meaning of the
3888constraint.  Docstrings are explained further below.
3889@end deffn
3890
3891Non-register constraints are more like predicates: the constraint
3892definition gives a Boolean expression which indicates whether the
3893constraint matches.
3894
3895@deffn {MD Expression} define_constraint name docstring exp
3896The @var{name} and @var{docstring} arguments are the same as for
3897@code{define_register_constraint}, but note that the docstring comes
3898immediately after the name for these expressions.  @var{exp} is an RTL
3899expression, obeying the same rules as the RTL expressions in predicate
3900definitions.  @xref{Defining Predicates}, for details.  If it
3901evaluates true, the constraint matches; if it evaluates false, it
3902doesn't. Constraint expressions should indicate which RTL codes they
3903might match, just like predicate expressions.
3904
3905@code{match_test} C expressions have access to the
3906following variables:
3907
3908@table @var
3909@item op
3910The RTL object defining the operand.
3911@item mode
3912The machine mode of @var{op}.
3913@item ival
3914@samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
3915@item hval
3916@samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
3917@code{const_double}.
3918@item lval
3919@samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
3920@code{const_double}.
3921@item rval
3922@samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
3923@code{const_double}.
3924@end table
3925
3926The @var{*val} variables should only be used once another piece of the
3927expression has verified that @var{op} is the appropriate kind of RTL
3928object.
3929@end deffn
3930
3931Most non-register constraints should be defined with
3932@code{define_constraint}.  The remaining two definition expressions
3933are only appropriate for constraints that should be handled specially
3934by @code{reload} if they fail to match.
3935
3936@deffn {MD Expression} define_memory_constraint name docstring exp
3937Use this expression for constraints that match a subset of all memory
3938operands: that is, @code{reload} can make them match by converting the
3939operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
3940base register (from the register class specified by
3941@code{BASE_REG_CLASS}, @pxref{Register Classes}).
3942
3943For example, on the S/390, some instructions do not accept arbitrary
3944memory references, but only those that do not make use of an index
3945register.  The constraint letter @samp{Q} is defined to represent a
3946memory address of this type.  If @samp{Q} is defined with
3947@code{define_memory_constraint}, a @samp{Q} constraint can handle any
3948memory operand, because @code{reload} knows it can simply copy the
3949memory address into a base register if required.  This is analogous to
3950the way an @samp{o} constraint can handle any memory operand.
3951
3952The syntax and semantics are otherwise identical to
3953@code{define_constraint}.
3954@end deffn
3955
3956@deffn {MD Expression} define_address_constraint name docstring exp
3957Use this expression for constraints that match a subset of all address
3958operands: that is, @code{reload} can make the constraint match by
3959converting the operand to the form @samp{@w{(reg @var{X})}}, again
3960with @var{X} a base register.
3961
3962Constraints defined with @code{define_address_constraint} can only be
3963used with the @code{address_operand} predicate, or machine-specific
3964predicates that work the same way.  They are treated analogously to
3965the generic @samp{p} constraint.
3966
3967The syntax and semantics are otherwise identical to
3968@code{define_constraint}.
3969@end deffn
3970
3971For historical reasons, names beginning with the letters @samp{G H}
3972are reserved for constraints that match only @code{const_double}s, and
3973names beginning with the letters @samp{I J K L M N O P} are reserved
3974for constraints that match only @code{const_int}s.  This may change in
3975the future.  For the time being, constraints with these names must be
3976written in a stylized form, so that @code{genpreds} can tell you did
3977it correctly:
3978
3979@smallexample
3980@group
3981(define_constraint "[@var{GHIJKLMNOP}]@dots{}"
3982  "@var{doc}@dots{}"
3983  (and (match_code "const_int")  ; @r{@code{const_double} for G/H}
3984       @var{condition}@dots{}))            ; @r{usually a @code{match_test}}
3985@end group
3986@end smallexample
3987@c the semicolons line up in the formatted manual
3988
3989It is fine to use names beginning with other letters for constraints
3990that match @code{const_double}s or @code{const_int}s.
3991
3992Each docstring in a constraint definition should be one or more complete
3993sentences, marked up in Texinfo format.  @emph{They are currently unused.}
3994In the future they will be copied into the GCC manual, in @ref{Machine
3995Constraints}, replacing the hand-maintained tables currently found in
3996that section.  Also, in the future the compiler may use this to give
3997more helpful diagnostics when poor choice of @code{asm} constraints
3998causes a reload failure.
3999
4000If you put the pseudo-Texinfo directive @samp{@@internal} at the
4001beginning of a docstring, then (in the future) it will appear only in
4002the internals manual's version of the machine-specific constraint tables.
4003Use this for constraints that should not appear in @code{asm} statements.
4004
4005@node C Constraint Interface
4006@subsection Testing constraints from C
4007@cindex testing constraints
4008@cindex constraints, testing
4009
4010It is occasionally useful to test a constraint from C code rather than
4011implicitly via the constraint string in a @code{match_operand}.  The
4012generated file @file{tm_p.h} declares a few interfaces for working
4013with machine-specific constraints.  None of these interfaces work with
4014the generic constraints described in @ref{Simple Constraints}.  This
4015may change in the future.
4016
4017@strong{Warning:} @file{tm_p.h} may declare other functions that
4018operate on constraints, besides the ones documented here.  Do not use
4019those functions from machine-dependent code.  They exist to implement
4020the old constraint interface that machine-independent components of
4021the compiler still expect.  They will change or disappear in the
4022future.
4023
4024Some valid constraint names are not valid C identifiers, so there is a
4025mangling scheme for referring to them from C@.  Constraint names that
4026do not contain angle brackets or underscores are left unchanged.
4027Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and
4028each @samp{>} with @samp{_g}.  Here are some examples:
4029
4030@c the @c's prevent double blank lines in the printed manual.
4031@example
4032@multitable {Original} {Mangled}
4033@item @strong{Original} @tab @strong{Mangled}  @c
4034@item @code{x}     @tab @code{x}       @c
4035@item @code{P42x}  @tab @code{P42x}    @c
4036@item @code{P4_x}  @tab @code{P4__x}   @c
4037@item @code{P4>x}  @tab @code{P4_gx}   @c
4038@item @code{P4>>}  @tab @code{P4_g_g}  @c
4039@item @code{P4_g>} @tab @code{P4__g_g} @c
4040@end multitable
4041@end example
4042
4043Throughout this section, the variable @var{c} is either a constraint
4044in the abstract sense, or a constant from @code{enum constraint_num};
4045the variable @var{m} is a mangled constraint name (usually as part of
4046a larger identifier).
4047
4048@deftp Enum constraint_num
4049For each machine-specific constraint, there is a corresponding
4050enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
4051constraint.  Functions that take an @code{enum constraint_num} as an
4052argument expect one of these constants.
4053
4054Machine-independent constraints do not have associated constants.
4055This may change in the future.
4056@end deftp
4057
4058@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
4059For each machine-specific, non-register constraint @var{m}, there is
4060one of these functions; it returns @code{true} if @var{exp} satisfies the
4061constraint.  These functions are only visible if @file{rtl.h} was included
4062before @file{tm_p.h}.
4063@end deftypefun
4064
4065@deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
4066Like the @code{satisfies_constraint_@var{m}} functions, but the
4067constraint to test is given as an argument, @var{c}.  If @var{c}
4068specifies a register constraint, this function will always return
4069@code{false}.
4070@end deftypefun
4071
4072@deftypefun {enum reg_class} regclass_for_constraint (enum constraint_num @var{c})
4073Returns the register class associated with @var{c}.  If @var{c} is not
4074a register constraint, or those registers are not available for the
4075currently selected subtarget, returns @code{NO_REGS}.
4076@end deftypefun
4077
4078Here is an example use of @code{satisfies_constraint_@var{m}}.  In
4079peephole optimizations (@pxref{Peephole Definitions}), operand
4080constraint strings are ignored, so if there are relevant constraints,
4081they must be tested in the C condition.  In the example, the
4082optimization is applied if operand 2 does @emph{not} satisfy the
4083@samp{K} constraint.  (This is a simplified version of a peephole
4084definition from the i386 machine description.)
4085
4086@smallexample
4087(define_peephole2
4088  [(match_scratch:SI 3 "r")
4089   (set (match_operand:SI 0 "register_operand" "")
4090        (mult:SI (match_operand:SI 1 "memory_operand" "")
4091                 (match_operand:SI 2 "immediate_operand" "")))]
4092
4093  "!satisfies_constraint_K (operands[2])"
4094
4095  [(set (match_dup 3) (match_dup 1))
4096   (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]
4097
4098  "")
4099@end smallexample
4100
4101@node Standard Names
4102@section Standard Pattern Names For Generation
4103@cindex standard pattern names
4104@cindex pattern names
4105@cindex names, pattern
4106
4107Here is a table of the instruction names that are meaningful in the RTL
4108generation pass of the compiler.  Giving one of these names to an
4109instruction pattern tells the RTL generation pass that it can use the
4110pattern to accomplish a certain task.
4111
4112@table @asis
4113@cindex @code{mov@var{m}} instruction pattern
4114@item @samp{mov@var{m}}
4115Here @var{m} stands for a two-letter machine mode name, in lowercase.
4116This instruction pattern moves data with that machine mode from operand
41171 to operand 0.  For example, @samp{movsi} moves full-word data.
4118
4119If operand 0 is a @code{subreg} with mode @var{m} of a register whose
4120own mode is wider than @var{m}, the effect of this instruction is
4121to store the specified value in the part of the register that corresponds
4122to mode @var{m}.  Bits outside of @var{m}, but which are within the
4123same target word as the @code{subreg} are undefined.  Bits which are
4124outside the target word are left unchanged.
4125
4126This class of patterns is special in several ways.  First of all, each
4127of these names up to and including full word size @emph{must} be defined,
4128because there is no other way to copy a datum from one place to another.
4129If there are patterns accepting operands in larger modes,
4130@samp{mov@var{m}} must be defined for integer modes of those sizes.
4131
4132Second, these patterns are not used solely in the RTL generation pass.
4133Even the reload pass can generate move insns to copy values from stack
4134slots into temporary registers.  When it does so, one of the operands is
4135a hard register and the other is an operand that can need to be reloaded
4136into a register.
4137
4138@findex force_reg
4139Therefore, when given such a pair of operands, the pattern must generate
4140RTL which needs no reloading and needs no temporary registers---no
4141registers other than the operands.  For example, if you support the
4142pattern with a @code{define_expand}, then in such a case the
4143@code{define_expand} mustn't call @code{force_reg} or any other such
4144function which might generate new pseudo registers.
4145
4146This requirement exists even for subword modes on a RISC machine where
4147fetching those modes from memory normally requires several insns and
4148some temporary registers.
4149
4150@findex change_address
4151During reload a memory reference with an invalid address may be passed
4152as an operand.  Such an address will be replaced with a valid address
4153later in the reload pass.  In this case, nothing may be done with the
4154address except to use it as it stands.  If it is copied, it will not be
4155replaced with a valid address.  No attempt should be made to make such
4156an address into a valid address and no routine (such as
4157@code{change_address}) that will do so may be called.  Note that
4158@code{general_operand} will fail when applied to such an address.
4159
4160@findex reload_in_progress
4161The global variable @code{reload_in_progress} (which must be explicitly
4162declared if required) can be used to determine whether such special
4163handling is required.
4164
4165The variety of operands that have reloads depends on the rest of the
4166machine description, but typically on a RISC machine these can only be
4167pseudo registers that did not get hard registers, while on other
4168machines explicit memory references will get optional reloads.
4169
4170If a scratch register is required to move an object to or from memory,
4171it can be allocated using @code{gen_reg_rtx} prior to life analysis.
4172
4173If there are cases which need scratch registers during or after reload,
4174you must provide an appropriate secondary_reload target hook.
4175
4176@findex can_create_pseudo_p
4177The macro @code{can_create_pseudo_p} can be used to determine if it
4178is unsafe to create new pseudo registers.  If this variable is nonzero, then
4179it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
4180
4181The constraints on a @samp{mov@var{m}} must permit moving any hard
4182register to any other hard register provided that
4183@code{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
4184@code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
4185of 2.
4186
4187It is obligatory to support floating point @samp{mov@var{m}}
4188instructions into and out of any registers that can hold fixed point
4189values, because unions and structures (which have modes @code{SImode} or
4190@code{DImode}) can be in those registers and they may have floating
4191point members.
4192
4193There may also be a need to support fixed point @samp{mov@var{m}}
4194instructions in and out of floating point registers.  Unfortunately, I
4195have forgotten why this was so, and I don't know whether it is still
4196true.  If @code{HARD_REGNO_MODE_OK} rejects fixed point values in
4197floating point registers, then the constraints of the fixed point
4198@samp{mov@var{m}} instructions must be designed to avoid ever trying to
4199reload into a floating point register.
4200
4201@cindex @code{reload_in} instruction pattern
4202@cindex @code{reload_out} instruction pattern
4203@item @samp{reload_in@var{m}}
4204@itemx @samp{reload_out@var{m}}
4205These named patterns have been obsoleted by the target hook
4206@code{secondary_reload}.
4207
4208Like @samp{mov@var{m}}, but used when a scratch register is required to
4209move between operand 0 and operand 1.  Operand 2 describes the scratch
4210register.  See the discussion of the @code{SECONDARY_RELOAD_CLASS}
4211macro in @pxref{Register Classes}.
4212
4213There are special restrictions on the form of the @code{match_operand}s
4214used in these patterns.  First, only the predicate for the reload
4215operand is examined, i.e., @code{reload_in} examines operand 1, but not
4216the predicates for operand 0 or 2.  Second, there may be only one
4217alternative in the constraints.  Third, only a single register class
4218letter may be used for the constraint; subsequent constraint letters
4219are ignored.  As a special exception, an empty constraint string
4220matches the @code{ALL_REGS} register class.  This may relieve ports
4221of the burden of defining an @code{ALL_REGS} constraint letter just
4222for these patterns.
4223
4224@cindex @code{movstrict@var{m}} instruction pattern
4225@item @samp{movstrict@var{m}}
4226Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
4227with mode @var{m} of a register whose natural mode is wider,
4228the @samp{movstrict@var{m}} instruction is guaranteed not to alter
4229any of the register except the part which belongs to mode @var{m}.
4230
4231@cindex @code{movmisalign@var{m}} instruction pattern
4232@item @samp{movmisalign@var{m}}
4233This variant of a move pattern is designed to load or store a value
4234from a memory address that is not naturally aligned for its mode.
4235For a store, the memory will be in operand 0; for a load, the memory
4236will be in operand 1.  The other operand is guaranteed not to be a
4237memory, so that it's easy to tell whether this is a load or store.
4238
4239This pattern is used by the autovectorizer, and when expanding a
4240@code{MISALIGNED_INDIRECT_REF} expression.
4241
4242@cindex @code{load_multiple} instruction pattern
4243@item @samp{load_multiple}
4244Load several consecutive memory locations into consecutive registers.
4245Operand 0 is the first of the consecutive registers, operand 1
4246is the first memory location, and operand 2 is a constant: the
4247number of consecutive registers.
4248
4249Define this only if the target machine really has such an instruction;
4250do not define this if the most efficient way of loading consecutive
4251registers from memory is to do them one at a time.
4252
4253On some machines, there are restrictions as to which consecutive
4254registers can be stored into memory, such as particular starting or
4255ending register numbers or only a range of valid counts.  For those
4256machines, use a @code{define_expand} (@pxref{Expander Definitions})
4257and make the pattern fail if the restrictions are not met.
4258
4259Write the generated insn as a @code{parallel} with elements being a
4260@code{set} of one register from the appropriate memory location (you may
4261also need @code{use} or @code{clobber} elements).  Use a
4262@code{match_parallel} (@pxref{RTL Template}) to recognize the insn.  See
4263@file{rs6000.md} for examples of the use of this insn pattern.
4264
4265@cindex @samp{store_multiple} instruction pattern
4266@item @samp{store_multiple}
4267Similar to @samp{load_multiple}, but store several consecutive registers
4268into consecutive memory locations.  Operand 0 is the first of the
4269consecutive memory locations, operand 1 is the first register, and
4270operand 2 is a constant: the number of consecutive registers.
4271
4272@cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
4273@item @samp{vec_load_lanes@var{m}@var{n}}
4274Perform an interleaved load of several vectors from memory operand 1
4275into register operand 0.  Both operands have mode @var{m}.  The register
4276operand is viewed as holding consecutive vectors of mode @var{n},
4277while the memory operand is a flat array that contains the same number
4278of elements.  The operation is equivalent to:
4279
4280@smallexample
4281int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4282for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4283  for (i = 0; i < c; i++)
4284    operand0[i][j] = operand1[j * c + i];
4285@end smallexample
4286
4287For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
4288from memory into a register of mode @samp{TI}@.  The register
4289contains two consecutive vectors of mode @samp{V4HI}@.
4290
4291This pattern can only be used if:
4292@smallexample
4293TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
4294@end smallexample
4295is true.  GCC assumes that, if a target supports this kind of
4296instruction for some mode @var{n}, it also supports unaligned
4297loads for vectors of mode @var{n}.
4298
4299@cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
4300@item @samp{vec_store_lanes@var{m}@var{n}}
4301Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
4302and register operands reversed.  That is, the instruction is
4303equivalent to:
4304
4305@smallexample
4306int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4307for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4308  for (i = 0; i < c; i++)
4309    operand0[j * c + i] = operand1[i][j];
4310@end smallexample
4311
4312for a memory operand 0 and register operand 1.
4313
4314@cindex @code{vec_set@var{m}} instruction pattern
4315@item @samp{vec_set@var{m}}
4316Set given field in the vector value.  Operand 0 is the vector to modify,
4317operand 1 is new value of field and operand 2 specify the field index.
4318
4319@cindex @code{vec_extract@var{m}} instruction pattern
4320@item @samp{vec_extract@var{m}}
4321Extract given field from the vector value.  Operand 1 is the vector, operand 2
4322specify field index and operand 0 place to store value into.
4323
4324@cindex @code{vec_init@var{m}} instruction pattern
4325@item @samp{vec_init@var{m}}
4326Initialize the vector to given values.  Operand 0 is the vector to initialize
4327and operand 1 is parallel containing values for individual fields.
4328
4329@cindex @code{vcond@var{m}@var{n}} instruction pattern
4330@item @samp{vcond@var{m}@var{n}}
4331Output a conditional vector move.  Operand 0 is the destination to
4332receive a combination of operand 1 and operand 2, which are of mode @var{m},
4333dependent on the outcome of the predicate in operand 3 which is a
4334vector comparison with operands of mode @var{n} in operands 4 and 5.  The
4335modes @var{m} and @var{n} should have the same size.  Operand 0
4336will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk}
4337where @var{msk} is computed by element-wise evaluation of the vector
4338comparison with a truth value of all-ones and a false value of all-zeros.
4339
4340@cindex @code{vec_perm@var{m}} instruction pattern
4341@item @samp{vec_perm@var{m}}
4342Output a (variable) vector permutation.  Operand 0 is the destination
4343to receive elements from operand 1 and operand 2, which are of mode
4344@var{m}.  Operand 3 is the @dfn{selector}.  It is an integral mode
4345vector of the same width and number of elements as mode @var{m}.
4346
4347The input elements are numbered from 0 in operand 1 through
4348@math{2*@var{N}-1} in operand 2.  The elements of the selector must
4349be computed modulo @math{2*@var{N}}.  Note that if
4350@code{rtx_equal_p(operand1, operand2)}, this can be implemented
4351with just operand 1 and selector elements modulo @var{N}.
4352
4353In order to make things easy for a number of targets, if there is no
4354@samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
4355where @var{q} is a vector of @code{QImode} of the same width as @var{m},
4356the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
4357mode @var{q}.
4358
4359@cindex @code{vec_perm_const@var{m}} instruction pattern
4360@item @samp{vec_perm_const@var{m}}
4361Like @samp{vec_perm} except that the permutation is a compile-time
4362constant.  That is, operand 3, the @dfn{selector}, is a @code{CONST_VECTOR}.
4363
4364Some targets cannot perform a permutation with a variable selector,
4365but can efficiently perform a constant permutation.  Further, the
4366target hook @code{vec_perm_ok} is queried to determine if the
4367specific constant permutation is available efficiently; the named
4368pattern is never expanded without @code{vec_perm_ok} returning true.
4369
4370There is no need for a target to supply both @samp{vec_perm@var{m}}
4371and @samp{vec_perm_const@var{m}} if the former can trivially implement
4372the operation with, say, the vector constant loaded into a register.
4373
4374@cindex @code{push@var{m}1} instruction pattern
4375@item @samp{push@var{m}1}
4376Output a push instruction.  Operand 0 is value to push.  Used only when
4377@code{PUSH_ROUNDING} is defined.  For historical reason, this pattern may be
4378missing and in such case an @code{mov} expander is used instead, with a
4379@code{MEM} expression forming the push operation.  The @code{mov} expander
4380method is deprecated.
4381
4382@cindex @code{add@var{m}3} instruction pattern
4383@item @samp{add@var{m}3}
4384Add operand 2 and operand 1, storing the result in operand 0.  All operands
4385must have mode @var{m}.  This can be used even on two-address machines, by
4386means of constraints requiring operands 1 and 0 to be the same location.
4387
4388@cindex @code{ssadd@var{m}3} instruction pattern
4389@cindex @code{usadd@var{m}3} instruction pattern
4390@cindex @code{sub@var{m}3} instruction pattern
4391@cindex @code{sssub@var{m}3} instruction pattern
4392@cindex @code{ussub@var{m}3} instruction pattern
4393@cindex @code{mul@var{m}3} instruction pattern
4394@cindex @code{ssmul@var{m}3} instruction pattern
4395@cindex @code{usmul@var{m}3} instruction pattern
4396@cindex @code{div@var{m}3} instruction pattern
4397@cindex @code{ssdiv@var{m}3} instruction pattern
4398@cindex @code{udiv@var{m}3} instruction pattern
4399@cindex @code{usdiv@var{m}3} instruction pattern
4400@cindex @code{mod@var{m}3} instruction pattern
4401@cindex @code{umod@var{m}3} instruction pattern
4402@cindex @code{umin@var{m}3} instruction pattern
4403@cindex @code{umax@var{m}3} instruction pattern
4404@cindex @code{and@var{m}3} instruction pattern
4405@cindex @code{ior@var{m}3} instruction pattern
4406@cindex @code{xor@var{m}3} instruction pattern
4407@item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
4408@item @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
4409@item @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
4410@itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
4411@itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
4412@itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
4413@itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
4414@itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
4415Similar, for other arithmetic operations.
4416
4417@cindex @code{fma@var{m}4} instruction pattern
4418@item @samp{fma@var{m}4}
4419Multiply operand 2 and operand 1, then add operand 3, storing the
4420result in operand 0.  All operands must have mode @var{m}.  This
4421pattern is used to implement the @code{fma}, @code{fmaf}, and
4422@code{fmal} builtin functions from the ISO C99 standard.  The
4423@code{fma} operation may produce different results than doing the
4424multiply followed by the add if the machine does not perform a
4425rounding step between the operations.
4426
4427@cindex @code{fms@var{m}4} instruction pattern
4428@item @samp{fms@var{m}4}
4429Like @code{fma@var{m}4}, except operand 3 subtracted from the
4430product instead of added to the product.  This is represented
4431in the rtl as
4432
4433@smallexample
4434(fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
4435@end smallexample
4436
4437@cindex @code{fnma@var{m}4} instruction pattern
4438@item @samp{fnma@var{m}4}
4439Like @code{fma@var{m}4} except that the intermediate product
4440is negated before being added to operand 3.  This is represented
4441in the rtl as
4442
4443@smallexample
4444(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
4445@end smallexample
4446
4447@cindex @code{fnms@var{m}4} instruction pattern
4448@item @samp{fnms@var{m}4}
4449Like @code{fms@var{m}4} except that the intermediate product
4450is negated before subtracting operand 3.  This is represented
4451in the rtl as
4452
4453@smallexample
4454(fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
4455@end smallexample
4456
4457@cindex @code{min@var{m}3} instruction pattern
4458@cindex @code{max@var{m}3} instruction pattern
4459@item @samp{smin@var{m}3}, @samp{smax@var{m}3}
4460Signed minimum and maximum operations.  When used with floating point,
4461if both operands are zeros, or if either operand is @code{NaN}, then
4462it is unspecified which of the two operands is returned as the result.
4463
4464@cindex @code{reduc_smin_@var{m}} instruction pattern
4465@cindex @code{reduc_smax_@var{m}} instruction pattern
4466@item @samp{reduc_smin_@var{m}}, @samp{reduc_smax_@var{m}}
4467Find the signed minimum/maximum of the elements of a vector. The vector is
4468operand 1, and the scalar result is stored in the least significant bits of
4469operand 0 (also a vector). The output and input vector should have the same
4470modes.
4471
4472@cindex @code{reduc_umin_@var{m}} instruction pattern
4473@cindex @code{reduc_umax_@var{m}} instruction pattern
4474@item @samp{reduc_umin_@var{m}}, @samp{reduc_umax_@var{m}}
4475Find the unsigned minimum/maximum of the elements of a vector. The vector is
4476operand 1, and the scalar result is stored in the least significant bits of
4477operand 0 (also a vector). The output and input vector should have the same
4478modes.
4479
4480@cindex @code{reduc_splus_@var{m}} instruction pattern
4481@item @samp{reduc_splus_@var{m}}
4482Compute the sum of the signed elements of a vector. The vector is operand 1,
4483and the scalar result is stored in the least significant bits of operand 0
4484(also a vector). The output and input vector should have the same modes.
4485
4486@cindex @code{reduc_uplus_@var{m}} instruction pattern
4487@item @samp{reduc_uplus_@var{m}}
4488Compute the sum of the unsigned elements of a vector. The vector is operand 1,
4489and the scalar result is stored in the least significant bits of operand 0
4490(also a vector). The output and input vector should have the same modes.
4491
4492@cindex @code{sdot_prod@var{m}} instruction pattern
4493@item @samp{sdot_prod@var{m}}
4494@cindex @code{udot_prod@var{m}} instruction pattern
4495@item @samp{udot_prod@var{m}}
4496Compute the sum of the products of two signed/unsigned elements.
4497Operand 1 and operand 2 are of the same mode. Their product, which is of a
4498wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or
4499wider than the mode of the product. The result is placed in operand 0, which
4500is of the same mode as operand 3.
4501
4502@cindex @code{ssum_widen@var{m3}} instruction pattern
4503@item @samp{ssum_widen@var{m3}}
4504@cindex @code{usum_widen@var{m3}} instruction pattern
4505@item @samp{usum_widen@var{m3}}
4506Operands 0 and 2 are of the same mode, which is wider than the mode of
4507operand 1. Add operand 1 to operand 2 and place the widened result in
4508operand 0. (This is used express accumulation of elements into an accumulator
4509of a wider mode.)
4510
4511@cindex @code{vec_shl_@var{m}} instruction pattern
4512@cindex @code{vec_shr_@var{m}} instruction pattern
4513@item @samp{vec_shl_@var{m}}, @samp{vec_shr_@var{m}}
4514Whole vector left/right shift in bits.
4515Operand 1 is a vector to be shifted.
4516Operand 2 is an integer shift amount in bits.
4517Operand 0 is where the resulting shifted vector is stored.
4518The output and input vectors should have the same modes.
4519
4520@cindex @code{vec_pack_trunc_@var{m}} instruction pattern
4521@item @samp{vec_pack_trunc_@var{m}}
4522Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
4523are vectors of the same mode having N integral or floating point elements
4524of size S@.  Operand 0 is the resulting vector in which 2*N elements of
4525size N/2 are concatenated after narrowing them down using truncation.
4526
4527@cindex @code{vec_pack_ssat_@var{m}} instruction pattern
4528@cindex @code{vec_pack_usat_@var{m}} instruction pattern
4529@item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
4530Narrow (demote) and merge the elements of two vectors.  Operands 1 and 2
4531are vectors of the same mode having N integral elements of size S.
4532Operand 0 is the resulting vector in which the elements of the two input
4533vectors are concatenated after narrowing them down using signed/unsigned
4534saturating arithmetic.
4535
4536@cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
4537@cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
4538@item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
4539Narrow, convert to signed/unsigned integral type and merge the elements
4540of two vectors.  Operands 1 and 2 are vectors of the same mode having N
4541floating point elements of size S@.  Operand 0 is the resulting vector
4542in which 2*N elements of size N/2 are concatenated.
4543
4544@cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
4545@cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
4546@item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
4547Extract and widen (promote) the high/low part of a vector of signed
4548integral or floating point elements.  The input vector (operand 1) has N
4549elements of size S@.  Widen (promote) the high/low elements of the vector
4550using signed or floating point extension and place the resulting N/2
4551values of size 2*S in the output vector (operand 0).
4552
4553@cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
4554@cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
4555@item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
4556Extract and widen (promote) the high/low part of a vector of unsigned
4557integral elements.  The input vector (operand 1) has N elements of size S.
4558Widen (promote) the high/low elements of the vector using zero extension and
4559place the resulting N/2 values of size 2*S in the output vector (operand 0).
4560
4561@cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
4562@cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
4563@cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
4564@cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
4565@item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
4566@itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
4567Extract, convert to floating point type and widen the high/low part of a
4568vector of signed/unsigned integral elements.  The input vector (operand 1)
4569has N elements of size S@.  Convert the high/low elements of the vector using
4570floating point conversion and place the resulting N/2 values of size 2*S in
4571the output vector (operand 0).
4572
4573@cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
4574@cindex @code{vec_widen_umult_lo__@var{m}} instruction pattern
4575@cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
4576@cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
4577@item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
4578@itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
4579Signed/Unsigned widening multiplication.  The two inputs (operands 1 and 2)
4580are vectors with N signed/unsigned elements of size S@.  Multiply the high/low
4581elements of the two vectors, and put the N/2 products of size 2*S in the
4582output vector (operand 0).
4583
4584@cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
4585@cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
4586@cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
4587@cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
4588@item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
4589@itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
4590Signed/Unsigned widening shift left.  The first input (operand 1) is a vector
4591with N signed/unsigned elements of size S@.  Operand 2 is a constant.  Shift
4592the high/low elements of operand 1, and put the N/2 results of size 2*S in the
4593output vector (operand 0).
4594
4595@cindex @code{mulhisi3} instruction pattern
4596@item @samp{mulhisi3}
4597Multiply operands 1 and 2, which have mode @code{HImode}, and store
4598a @code{SImode} product in operand 0.
4599
4600@cindex @code{mulqihi3} instruction pattern
4601@cindex @code{mulsidi3} instruction pattern
4602@item @samp{mulqihi3}, @samp{mulsidi3}
4603Similar widening-multiplication instructions of other widths.
4604
4605@cindex @code{umulqihi3} instruction pattern
4606@cindex @code{umulhisi3} instruction pattern
4607@cindex @code{umulsidi3} instruction pattern
4608@item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
4609Similar widening-multiplication instructions that do unsigned
4610multiplication.
4611
4612@cindex @code{usmulqihi3} instruction pattern
4613@cindex @code{usmulhisi3} instruction pattern
4614@cindex @code{usmulsidi3} instruction pattern
4615@item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
4616Similar widening-multiplication instructions that interpret the first
4617operand as unsigned and the second operand as signed, then do a signed
4618multiplication.
4619
4620@cindex @code{smul@var{m}3_highpart} instruction pattern
4621@item @samp{smul@var{m}3_highpart}
4622Perform a signed multiplication of operands 1 and 2, which have mode
4623@var{m}, and store the most significant half of the product in operand 0.
4624The least significant half of the product is discarded.
4625
4626@cindex @code{umul@var{m}3_highpart} instruction pattern
4627@item @samp{umul@var{m}3_highpart}
4628Similar, but the multiplication is unsigned.
4629
4630@cindex @code{madd@var{m}@var{n}4} instruction pattern
4631@item @samp{madd@var{m}@var{n}4}
4632Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
4633operand 3, and store the result in operand 0.  Operands 1 and 2
4634have mode @var{m} and operands 0 and 3 have mode @var{n}.
4635Both modes must be integer or fixed-point modes and @var{n} must be twice
4636the size of @var{m}.
4637
4638In other words, @code{madd@var{m}@var{n}4} is like
4639@code{mul@var{m}@var{n}3} except that it also adds operand 3.
4640
4641These instructions are not allowed to @code{FAIL}.
4642
4643@cindex @code{umadd@var{m}@var{n}4} instruction pattern
4644@item @samp{umadd@var{m}@var{n}4}
4645Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
4646operands instead of sign-extending them.
4647
4648@cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
4649@item @samp{ssmadd@var{m}@var{n}4}
4650Like @code{madd@var{m}@var{n}4}, but all involved operations must be
4651signed-saturating.
4652
4653@cindex @code{usmadd@var{m}@var{n}4} instruction pattern
4654@item @samp{usmadd@var{m}@var{n}4}
4655Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
4656unsigned-saturating.
4657
4658@cindex @code{msub@var{m}@var{n}4} instruction pattern
4659@item @samp{msub@var{m}@var{n}4}
4660Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
4661result from operand 3, and store the result in operand 0.  Operands 1 and 2
4662have mode @var{m} and operands 0 and 3 have mode @var{n}.
4663Both modes must be integer or fixed-point modes and @var{n} must be twice
4664the size of @var{m}.
4665
4666In other words, @code{msub@var{m}@var{n}4} is like
4667@code{mul@var{m}@var{n}3} except that it also subtracts the result
4668from operand 3.
4669
4670These instructions are not allowed to @code{FAIL}.
4671
4672@cindex @code{umsub@var{m}@var{n}4} instruction pattern
4673@item @samp{umsub@var{m}@var{n}4}
4674Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
4675operands instead of sign-extending them.
4676
4677@cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
4678@item @samp{ssmsub@var{m}@var{n}4}
4679Like @code{msub@var{m}@var{n}4}, but all involved operations must be
4680signed-saturating.
4681
4682@cindex @code{usmsub@var{m}@var{n}4} instruction pattern
4683@item @samp{usmsub@var{m}@var{n}4}
4684Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
4685unsigned-saturating.
4686
4687@cindex @code{divmod@var{m}4} instruction pattern
4688@item @samp{divmod@var{m}4}
4689Signed division that produces both a quotient and a remainder.
4690Operand 1 is divided by operand 2 to produce a quotient stored
4691in operand 0 and a remainder stored in operand 3.
4692
4693For machines with an instruction that produces both a quotient and a
4694remainder, provide a pattern for @samp{divmod@var{m}4} but do not
4695provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}.  This
4696allows optimization in the relatively common case when both the quotient
4697and remainder are computed.
4698
4699If an instruction that just produces a quotient or just a remainder
4700exists and is more efficient than the instruction that produces both,
4701write the output routine of @samp{divmod@var{m}4} to call
4702@code{find_reg_note} and look for a @code{REG_UNUSED} note on the
4703quotient or remainder and generate the appropriate instruction.
4704
4705@cindex @code{udivmod@var{m}4} instruction pattern
4706@item @samp{udivmod@var{m}4}
4707Similar, but does unsigned division.
4708
4709@anchor{shift patterns}
4710@cindex @code{ashl@var{m}3} instruction pattern
4711@cindex @code{ssashl@var{m}3} instruction pattern
4712@cindex @code{usashl@var{m}3} instruction pattern
4713@item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
4714Arithmetic-shift operand 1 left by a number of bits specified by operand
47152, and store the result in operand 0.  Here @var{m} is the mode of
4716operand 0 and operand 1; operand 2's mode is specified by the
4717instruction pattern, and the compiler will convert the operand to that
4718mode before generating the instruction.  The meaning of out-of-range shift
4719counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
4720@xref{TARGET_SHIFT_TRUNCATION_MASK}.  Operand 2 is always a scalar type.
4721
4722@cindex @code{ashr@var{m}3} instruction pattern
4723@cindex @code{lshr@var{m}3} instruction pattern
4724@cindex @code{rotl@var{m}3} instruction pattern
4725@cindex @code{rotr@var{m}3} instruction pattern
4726@item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
4727Other shift and rotate instructions, analogous to the
4728@code{ashl@var{m}3} instructions.  Operand 2 is always a scalar type.
4729
4730@cindex @code{vashl@var{m}3} instruction pattern
4731@cindex @code{vashr@var{m}3} instruction pattern
4732@cindex @code{vlshr@var{m}3} instruction pattern
4733@cindex @code{vrotl@var{m}3} instruction pattern
4734@cindex @code{vrotr@var{m}3} instruction pattern
4735@item @samp{vashl@var{m}3}, @samp{vashr@var{m}3}, @samp{vlshr@var{m}3}, @samp{vrotl@var{m}3}, @samp{vrotr@var{m}3}
4736Vector shift and rotate instructions that take vectors as operand 2
4737instead of a scalar type.
4738
4739@cindex @code{neg@var{m}2} instruction pattern
4740@cindex @code{ssneg@var{m}2} instruction pattern
4741@cindex @code{usneg@var{m}2} instruction pattern
4742@item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
4743Negate operand 1 and store the result in operand 0.
4744
4745@cindex @code{abs@var{m}2} instruction pattern
4746@item @samp{abs@var{m}2}
4747Store the absolute value of operand 1 into operand 0.
4748
4749@cindex @code{sqrt@var{m}2} instruction pattern
4750@item @samp{sqrt@var{m}2}
4751Store the square root of operand 1 into operand 0.
4752
4753The @code{sqrt} built-in function of C always uses the mode which
4754corresponds to the C data type @code{double} and the @code{sqrtf}
4755built-in function uses the mode which corresponds to the C data
4756type @code{float}.
4757
4758@cindex @code{fmod@var{m}3} instruction pattern
4759@item @samp{fmod@var{m}3}
4760Store the remainder of dividing operand 1 by operand 2 into
4761operand 0, rounded towards zero to an integer.
4762
4763The @code{fmod} built-in function of C always uses the mode which
4764corresponds to the C data type @code{double} and the @code{fmodf}
4765built-in function uses the mode which corresponds to the C data
4766type @code{float}.
4767
4768@cindex @code{remainder@var{m}3} instruction pattern
4769@item @samp{remainder@var{m}3}
4770Store the remainder of dividing operand 1 by operand 2 into
4771operand 0, rounded to the nearest integer.
4772
4773The @code{remainder} built-in function of C always uses the mode
4774which corresponds to the C data type @code{double} and the
4775@code{remainderf} built-in function uses the mode which corresponds
4776to the C data type @code{float}.
4777
4778@cindex @code{cos@var{m}2} instruction pattern
4779@item @samp{cos@var{m}2}
4780Store the cosine of operand 1 into operand 0.
4781
4782The @code{cos} built-in function of C always uses the mode which
4783corresponds to the C data type @code{double} and the @code{cosf}
4784built-in function uses the mode which corresponds to the C data
4785type @code{float}.
4786
4787@cindex @code{sin@var{m}2} instruction pattern
4788@item @samp{sin@var{m}2}
4789Store the sine of operand 1 into operand 0.
4790
4791The @code{sin} built-in function of C always uses the mode which
4792corresponds to the C data type @code{double} and the @code{sinf}
4793built-in function uses the mode which corresponds to the C data
4794type @code{float}.
4795
4796@cindex @code{exp@var{m}2} instruction pattern
4797@item @samp{exp@var{m}2}
4798Store the exponential of operand 1 into operand 0.
4799
4800The @code{exp} built-in function of C always uses the mode which
4801corresponds to the C data type @code{double} and the @code{expf}
4802built-in function uses the mode which corresponds to the C data
4803type @code{float}.
4804
4805@cindex @code{log@var{m}2} instruction pattern
4806@item @samp{log@var{m}2}
4807Store the natural logarithm of operand 1 into operand 0.
4808
4809The @code{log} built-in function of C always uses the mode which
4810corresponds to the C data type @code{double} and the @code{logf}
4811built-in function uses the mode which corresponds to the C data
4812type @code{float}.
4813
4814@cindex @code{pow@var{m}3} instruction pattern
4815@item @samp{pow@var{m}3}
4816Store the value of operand 1 raised to the exponent operand 2
4817into operand 0.
4818
4819The @code{pow} built-in function of C always uses the mode which
4820corresponds to the C data type @code{double} and the @code{powf}
4821built-in function uses the mode which corresponds to the C data
4822type @code{float}.
4823
4824@cindex @code{atan2@var{m}3} instruction pattern
4825@item @samp{atan2@var{m}3}
4826Store the arc tangent (inverse tangent) of operand 1 divided by
4827operand 2 into operand 0, using the signs of both arguments to
4828determine the quadrant of the result.
4829
4830The @code{atan2} built-in function of C always uses the mode which
4831corresponds to the C data type @code{double} and the @code{atan2f}
4832built-in function uses the mode which corresponds to the C data
4833type @code{float}.
4834
4835@cindex @code{floor@var{m}2} instruction pattern
4836@item @samp{floor@var{m}2}
4837Store the largest integral value not greater than argument.
4838
4839The @code{floor} built-in function of C always uses the mode which
4840corresponds to the C data type @code{double} and the @code{floorf}
4841built-in function uses the mode which corresponds to the C data
4842type @code{float}.
4843
4844@cindex @code{btrunc@var{m}2} instruction pattern
4845@item @samp{btrunc@var{m}2}
4846Store the argument rounded to integer towards zero.
4847
4848The @code{trunc} built-in function of C always uses the mode which
4849corresponds to the C data type @code{double} and the @code{truncf}
4850built-in function uses the mode which corresponds to the C data
4851type @code{float}.
4852
4853@cindex @code{round@var{m}2} instruction pattern
4854@item @samp{round@var{m}2}
4855Store the argument rounded to integer away from zero.
4856
4857The @code{round} built-in function of C always uses the mode which
4858corresponds to the C data type @code{double} and the @code{roundf}
4859built-in function uses the mode which corresponds to the C data
4860type @code{float}.
4861
4862@cindex @code{ceil@var{m}2} instruction pattern
4863@item @samp{ceil@var{m}2}
4864Store the argument rounded to integer away from zero.
4865
4866The @code{ceil} built-in function of C always uses the mode which
4867corresponds to the C data type @code{double} and the @code{ceilf}
4868built-in function uses the mode which corresponds to the C data
4869type @code{float}.
4870
4871@cindex @code{nearbyint@var{m}2} instruction pattern
4872@item @samp{nearbyint@var{m}2}
4873Store the argument rounded according to the default rounding mode
4874
4875The @code{nearbyint} built-in function of C always uses the mode which
4876corresponds to the C data type @code{double} and the @code{nearbyintf}
4877built-in function uses the mode which corresponds to the C data
4878type @code{float}.
4879
4880@cindex @code{rint@var{m}2} instruction pattern
4881@item @samp{rint@var{m}2}
4882Store the argument rounded according to the default rounding mode and
4883raise the inexact exception when the result differs in value from
4884the argument
4885
4886The @code{rint} built-in function of C always uses the mode which
4887corresponds to the C data type @code{double} and the @code{rintf}
4888built-in function uses the mode which corresponds to the C data
4889type @code{float}.
4890
4891@cindex @code{lrint@var{m}@var{n}2}
4892@item @samp{lrint@var{m}@var{n}2}
4893Convert operand 1 (valid for floating point mode @var{m}) to fixed
4894point mode @var{n} as a signed number according to the current
4895rounding mode and store in operand 0 (which has mode @var{n}).
4896
4897@cindex @code{lround@var{m}@var{n}2}
4898@item @samp{lround@var{m}@var{n}2}
4899Convert operand 1 (valid for floating point mode @var{m}) to fixed
4900point mode @var{n} as a signed number rounding to nearest and away
4901from zero and store in operand 0 (which has mode @var{n}).
4902
4903@cindex @code{lfloor@var{m}@var{n}2}
4904@item @samp{lfloor@var{m}@var{n}2}
4905Convert operand 1 (valid for floating point mode @var{m}) to fixed
4906point mode @var{n} as a signed number rounding down and store in
4907operand 0 (which has mode @var{n}).
4908
4909@cindex @code{lceil@var{m}@var{n}2}
4910@item @samp{lceil@var{m}@var{n}2}
4911Convert operand 1 (valid for floating point mode @var{m}) to fixed
4912point mode @var{n} as a signed number rounding up and store in
4913operand 0 (which has mode @var{n}).
4914
4915@cindex @code{copysign@var{m}3} instruction pattern
4916@item @samp{copysign@var{m}3}
4917Store a value with the magnitude of operand 1 and the sign of operand
49182 into operand 0.
4919
4920The @code{copysign} built-in function of C always uses the mode which
4921corresponds to the C data type @code{double} and the @code{copysignf}
4922built-in function uses the mode which corresponds to the C data
4923type @code{float}.
4924
4925@cindex @code{ffs@var{m}2} instruction pattern
4926@item @samp{ffs@var{m}2}
4927Store into operand 0 one plus the index of the least significant 1-bit
4928of operand 1.  If operand 1 is zero, store zero.  @var{m} is the mode
4929of operand 0; operand 1's mode is specified by the instruction
4930pattern, and the compiler will convert the operand to that mode before
4931generating the instruction.
4932
4933The @code{ffs} built-in function of C always uses the mode which
4934corresponds to the C data type @code{int}.
4935
4936@cindex @code{clz@var{m}2} instruction pattern
4937@item @samp{clz@var{m}2}
4938Store into operand 0 the number of leading 0-bits in @var{x}, starting
4939at the most significant bit position.  If @var{x} is 0, the
4940@code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
4941the result is undefined or has a useful value.
4942@var{m} is the mode of operand 0; operand 1's mode is
4943specified by the instruction pattern, and the compiler will convert the
4944operand to that mode before generating the instruction.
4945
4946@cindex @code{ctz@var{m}2} instruction pattern
4947@item @samp{ctz@var{m}2}
4948Store into operand 0 the number of trailing 0-bits in @var{x}, starting
4949at the least significant bit position.  If @var{x} is 0, the
4950@code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
4951the result is undefined or has a useful value.
4952@var{m} is the mode of operand 0; operand 1's mode is
4953specified by the instruction pattern, and the compiler will convert the
4954operand to that mode before generating the instruction.
4955
4956@cindex @code{popcount@var{m}2} instruction pattern
4957@item @samp{popcount@var{m}2}
4958Store into operand 0 the number of 1-bits in @var{x}.  @var{m} is the
4959mode of operand 0; operand 1's mode is specified by the instruction
4960pattern, and the compiler will convert the operand to that mode before
4961generating the instruction.
4962
4963@cindex @code{parity@var{m}2} instruction pattern
4964@item @samp{parity@var{m}2}
4965Store into operand 0 the parity of @var{x}, i.e.@: the number of 1-bits
4966in @var{x} modulo 2.  @var{m} is the mode of operand 0; operand 1's mode
4967is specified by the instruction pattern, and the compiler will convert
4968the operand to that mode before generating the instruction.
4969
4970@cindex @code{one_cmpl@var{m}2} instruction pattern
4971@item @samp{one_cmpl@var{m}2}
4972Store the bitwise-complement of operand 1 into operand 0.
4973
4974@cindex @code{movmem@var{m}} instruction pattern
4975@item @samp{movmem@var{m}}
4976Block move instruction.  The destination and source blocks of memory
4977are the first two operands, and both are @code{mem:BLK}s with an
4978address in mode @code{Pmode}.
4979
4980The number of bytes to move is the third operand, in mode @var{m}.
4981Usually, you specify @code{word_mode} for @var{m}.  However, if you can
4982generate better code knowing the range of valid lengths is smaller than
4983those representable in a full word, you should provide a pattern with a
4984mode corresponding to the range of values you can handle efficiently
4985(e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
4986that appear negative) and also a pattern with @code{word_mode}.
4987
4988The fourth operand is the known shared alignment of the source and
4989destination, in the form of a @code{const_int} rtx.  Thus, if the
4990compiler knows that both source and destination are word-aligned,
4991it may provide the value 4 for this operand.
4992
4993Optional operands 5 and 6 specify expected alignment and size of block
4994respectively.  The expected alignment differs from alignment in operand 4
4995in a way that the blocks are not required to be aligned according to it in
4996all cases. This expected alignment is also in bytes, just like operand 4.
4997Expected size, when unknown, is set to @code{(const_int -1)}.
4998
4999Descriptions of multiple @code{movmem@var{m}} patterns can only be
5000beneficial if the patterns for smaller modes have fewer restrictions
5001on their first, second and fourth operands.  Note that the mode @var{m}
5002in @code{movmem@var{m}} does not impose any restriction on the mode of
5003individually moved data units in the block.
5004
5005These patterns need not give special consideration to the possibility
5006that the source and destination strings might overlap.
5007
5008@cindex @code{movstr} instruction pattern
5009@item @samp{movstr}
5010String copy instruction, with @code{stpcpy} semantics.  Operand 0 is
5011an output operand in mode @code{Pmode}.  The addresses of the
5012destination and source strings are operands 1 and 2, and both are
5013@code{mem:BLK}s with addresses in mode @code{Pmode}.  The execution of
5014the expansion of this pattern should store in operand 0 the address in
5015which the @code{NUL} terminator was stored in the destination string.
5016
5017@cindex @code{setmem@var{m}} instruction pattern
5018@item @samp{setmem@var{m}}
5019Block set instruction.  The destination string is the first operand,
5020given as a @code{mem:BLK} whose address is in mode @code{Pmode}.  The
5021number of bytes to set is the second operand, in mode @var{m}.  The value to
5022initialize the memory with is the third operand. Targets that only support the
5023clearing of memory should reject any value that is not the constant 0.  See
5024@samp{movmem@var{m}} for a discussion of the choice of mode.
5025
5026The fourth operand is the known alignment of the destination, in the form
5027of a @code{const_int} rtx.  Thus, if the compiler knows that the
5028destination is word-aligned, it may provide the value 4 for this
5029operand.
5030
5031Optional operands 5 and 6 specify expected alignment and size of block
5032respectively.  The expected alignment differs from alignment in operand 4
5033in a way that the blocks are not required to be aligned according to it in
5034all cases. This expected alignment is also in bytes, just like operand 4.
5035Expected size, when unknown, is set to @code{(const_int -1)}.
5036
5037The use for multiple @code{setmem@var{m}} is as for @code{movmem@var{m}}.
5038
5039@cindex @code{cmpstrn@var{m}} instruction pattern
5040@item @samp{cmpstrn@var{m}}
5041String compare instruction, with five operands.  Operand 0 is the output;
5042it has mode @var{m}.  The remaining four operands are like the operands
5043of @samp{movmem@var{m}}.  The two memory blocks specified are compared
5044byte by byte in lexicographic order starting at the beginning of each
5045string.  The instruction is not allowed to prefetch more than one byte
5046at a time since either string may end in the first byte and reading past
5047that may access an invalid page or segment and cause a fault.  The
5048comparison terminates early if the fetched bytes are different or if
5049they are equal to zero.  The effect of the instruction is to store a
5050value in operand 0 whose sign indicates the result of the comparison.
5051
5052@cindex @code{cmpstr@var{m}} instruction pattern
5053@item @samp{cmpstr@var{m}}
5054String compare instruction, without known maximum length.  Operand 0 is the
5055output; it has mode @var{m}.  The second and third operand are the blocks of
5056memory to be compared; both are @code{mem:BLK} with an address in mode
5057@code{Pmode}.
5058
5059The fourth operand is the known shared alignment of the source and
5060destination, in the form of a @code{const_int} rtx.  Thus, if the
5061compiler knows that both source and destination are word-aligned,
5062it may provide the value 4 for this operand.
5063
5064The two memory blocks specified are compared byte by byte in lexicographic
5065order starting at the beginning of each string.  The instruction is not allowed
5066to prefetch more than one byte at a time since either string may end in the
5067first byte and reading past that may access an invalid page or segment and
5068cause a fault.  The comparison will terminate when the fetched bytes
5069are different or if they are equal to zero.  The effect of the
5070instruction is to store a value in operand 0 whose sign indicates the
5071result of the comparison.
5072
5073@cindex @code{cmpmem@var{m}} instruction pattern
5074@item @samp{cmpmem@var{m}}
5075Block compare instruction, with five operands like the operands
5076of @samp{cmpstr@var{m}}.  The two memory blocks specified are compared
5077byte by byte in lexicographic order starting at the beginning of each
5078block.  Unlike @samp{cmpstr@var{m}} the instruction can prefetch
5079any bytes in the two memory blocks.  Also unlike @samp{cmpstr@var{m}}
5080the comparison will not stop if both bytes are zero.  The effect of
5081the instruction is to store a value in operand 0 whose sign indicates
5082the result of the comparison.
5083
5084@cindex @code{strlen@var{m}} instruction pattern
5085@item @samp{strlen@var{m}}
5086Compute the length of a string, with three operands.
5087Operand 0 is the result (of mode @var{m}), operand 1 is
5088a @code{mem} referring to the first character of the string,
5089operand 2 is the character to search for (normally zero),
5090and operand 3 is a constant describing the known alignment
5091of the beginning of the string.
5092
5093@cindex @code{float@var{m}@var{n}2} instruction pattern
5094@item @samp{float@var{m}@var{n}2}
5095Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
5096floating point mode @var{n} and store in operand 0 (which has mode
5097@var{n}).
5098
5099@cindex @code{floatuns@var{m}@var{n}2} instruction pattern
5100@item @samp{floatuns@var{m}@var{n}2}
5101Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
5102to floating point mode @var{n} and store in operand 0 (which has mode
5103@var{n}).
5104
5105@cindex @code{fix@var{m}@var{n}2} instruction pattern
5106@item @samp{fix@var{m}@var{n}2}
5107Convert operand 1 (valid for floating point mode @var{m}) to fixed
5108point mode @var{n} as a signed number and store in operand 0 (which
5109has mode @var{n}).  This instruction's result is defined only when
5110the value of operand 1 is an integer.
5111
5112If the machine description defines this pattern, it also needs to
5113define the @code{ftrunc} pattern.
5114
5115@cindex @code{fixuns@var{m}@var{n}2} instruction pattern
5116@item @samp{fixuns@var{m}@var{n}2}
5117Convert operand 1 (valid for floating point mode @var{m}) to fixed
5118point mode @var{n} as an unsigned number and store in operand 0 (which
5119has mode @var{n}).  This instruction's result is defined only when the
5120value of operand 1 is an integer.
5121
5122@cindex @code{ftrunc@var{m}2} instruction pattern
5123@item @samp{ftrunc@var{m}2}
5124Convert operand 1 (valid for floating point mode @var{m}) to an
5125integer value, still represented in floating point mode @var{m}, and
5126store it in operand 0 (valid for floating point mode @var{m}).
5127
5128@cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
5129@item @samp{fix_trunc@var{m}@var{n}2}
5130Like @samp{fix@var{m}@var{n}2} but works for any floating point value
5131of mode @var{m} by converting the value to an integer.
5132
5133@cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
5134@item @samp{fixuns_trunc@var{m}@var{n}2}
5135Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
5136value of mode @var{m} by converting the value to an integer.
5137
5138@cindex @code{trunc@var{m}@var{n}2} instruction pattern
5139@item @samp{trunc@var{m}@var{n}2}
5140Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
5141store in operand 0 (which has mode @var{n}).  Both modes must be fixed
5142point or both floating point.
5143
5144@cindex @code{extend@var{m}@var{n}2} instruction pattern
5145@item @samp{extend@var{m}@var{n}2}
5146Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
5147store in operand 0 (which has mode @var{n}).  Both modes must be fixed
5148point or both floating point.
5149
5150@cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
5151@item @samp{zero_extend@var{m}@var{n}2}
5152Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
5153store in operand 0 (which has mode @var{n}).  Both modes must be fixed
5154point.
5155
5156@cindex @code{fract@var{m}@var{n}2} instruction pattern
5157@item @samp{fract@var{m}@var{n}2}
5158Convert operand 1 of mode @var{m} to mode @var{n} and store in
5159operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
5160could be fixed-point to fixed-point, signed integer to fixed-point,
5161fixed-point to signed integer, floating-point to fixed-point,
5162or fixed-point to floating-point.
5163When overflows or underflows happen, the results are undefined.
5164
5165@cindex @code{satfract@var{m}@var{n}2} instruction pattern
5166@item @samp{satfract@var{m}@var{n}2}
5167Convert operand 1 of mode @var{m} to mode @var{n} and store in
5168operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
5169could be fixed-point to fixed-point, signed integer to fixed-point,
5170or floating-point to fixed-point.
5171When overflows or underflows happen, the instruction saturates the
5172results to the maximum or the minimum.
5173
5174@cindex @code{fractuns@var{m}@var{n}2} instruction pattern
5175@item @samp{fractuns@var{m}@var{n}2}
5176Convert operand 1 of mode @var{m} to mode @var{n} and store in
5177operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
5178could be unsigned integer to fixed-point, or
5179fixed-point to unsigned integer.
5180When overflows or underflows happen, the results are undefined.
5181
5182@cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
5183@item @samp{satfractuns@var{m}@var{n}2}
5184Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
5185@var{n} and store in operand 0 (which has mode @var{n}).
5186When overflows or underflows happen, the instruction saturates the
5187results to the maximum or the minimum.
5188
5189@cindex @code{extv} instruction pattern
5190@item @samp{extv}
5191Extract a bit-field from operand 1 (a register or memory operand), where
5192operand 2 specifies the width in bits and operand 3 the starting bit,
5193and store it in operand 0.  Operand 0 must have mode @code{word_mode}.
5194Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
5195@code{word_mode} is allowed only for registers.  Operands 2 and 3 must
5196be valid for @code{word_mode}.
5197
5198The RTL generation pass generates this instruction only with constants
5199for operands 2 and 3 and the constant is never zero for operand 2.
5200
5201The bit-field value is sign-extended to a full word integer
5202before it is stored in operand 0.
5203
5204@cindex @code{extzv} instruction pattern
5205@item @samp{extzv}
5206Like @samp{extv} except that the bit-field value is zero-extended.
5207
5208@cindex @code{insv} instruction pattern
5209@item @samp{insv}
5210Store operand 3 (which must be valid for @code{word_mode}) into a
5211bit-field in operand 0, where operand 1 specifies the width in bits and
5212operand 2 the starting bit.  Operand 0 may have mode @code{byte_mode} or
5213@code{word_mode}; often @code{word_mode} is allowed only for registers.
5214Operands 1 and 2 must be valid for @code{word_mode}.
5215
5216The RTL generation pass generates this instruction only with constants
5217for operands 1 and 2 and the constant is never zero for operand 1.
5218
5219@cindex @code{mov@var{mode}cc} instruction pattern
5220@item @samp{mov@var{mode}cc}
5221Conditionally move operand 2 or operand 3 into operand 0 according to the
5222comparison in operand 1.  If the comparison is true, operand 2 is moved
5223into operand 0, otherwise operand 3 is moved.
5224
5225The mode of the operands being compared need not be the same as the operands
5226being moved.  Some machines, sparc64 for example, have instructions that
5227conditionally move an integer value based on the floating point condition
5228codes and vice versa.
5229
5230If the machine does not have conditional move instructions, do not
5231define these patterns.
5232
5233@cindex @code{add@var{mode}cc} instruction pattern
5234@item @samp{add@var{mode}cc}
5235Similar to @samp{mov@var{mode}cc} but for conditional addition.  Conditionally
5236move operand 2 or (operands 2 + operand 3) into operand 0 according to the
5237comparison in operand 1.  If the comparison is true, operand 2 is moved into
5238operand 0, otherwise (operand 2 + operand 3) is moved.
5239
5240@cindex @code{cstore@var{mode}4} instruction pattern
5241@item @samp{cstore@var{mode}4}
5242Store zero or nonzero in operand 0 according to whether a comparison
5243is true.  Operand 1 is a comparison operator.  Operand 2 and operand 3
5244are the first and second operand of the comparison, respectively.
5245You specify the mode that operand 0 must have when you write the
5246@code{match_operand} expression.  The compiler automatically sees which
5247mode you have used and supplies an operand of that mode.
5248
5249The value stored for a true condition must have 1 as its low bit, or
5250else must be negative.  Otherwise the instruction is not suitable and
5251you should omit it from the machine description.  You describe to the
5252compiler exactly which value is stored by defining the macro
5253@code{STORE_FLAG_VALUE} (@pxref{Misc}).  If a description cannot be
5254found that can be used for all the possible comparison operators, you
5255should pick one and use a @code{define_expand} to map all results
5256onto the one you chose.
5257
5258These operations may @code{FAIL}, but should do so only in relatively
5259uncommon cases; if they would @code{FAIL} for common cases involving
5260integer comparisons, it is best to restrict the predicates to not
5261allow these operands.  Likewise if a given comparison operator will
5262always fail, independent of the operands (for floating-point modes, the
5263@code{ordered_comparison_operator} predicate is often useful in this case).
5264
5265If this pattern is omitted, the compiler will generate a conditional
5266branch---for example, it may copy a constant one to the target and branching
5267around an assignment of zero to the target---or a libcall.  If the predicate
5268for operand 1 only rejects some operators, it will also try reordering the
5269operands and/or inverting the result value (e.g.@: by an exclusive OR).
5270These possibilities could be cheaper or equivalent to the instructions
5271used for the @samp{cstore@var{mode}4} pattern followed by those required
5272to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
5273case, you can and should make operand 1's predicate reject some operators
5274in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
5275from the machine description.
5276
5277@cindex @code{cbranch@var{mode}4} instruction pattern
5278@item @samp{cbranch@var{mode}4}
5279Conditional branch instruction combined with a compare instruction.
5280Operand 0 is a comparison operator.  Operand 1 and operand 2 are the
5281first and second operands of the comparison, respectively.  Operand 3
5282is a @code{label_ref} that refers to the label to jump to.
5283
5284@cindex @code{jump} instruction pattern
5285@item @samp{jump}
5286A jump inside a function; an unconditional branch.  Operand 0 is the
5287@code{label_ref} of the label to jump to.  This pattern name is mandatory
5288on all machines.
5289
5290@cindex @code{call} instruction pattern
5291@item @samp{call}
5292Subroutine call instruction returning no value.  Operand 0 is the
5293function to call; operand 1 is the number of bytes of arguments pushed
5294as a @code{const_int}; operand 2 is the number of registers used as
5295operands.
5296
5297On most machines, operand 2 is not actually stored into the RTL
5298pattern.  It is supplied for the sake of some RISC machines which need
5299to put this information into the assembler code; they can put it in
5300the RTL instead of operand 1.
5301
5302Operand 0 should be a @code{mem} RTX whose address is the address of the
5303function.  Note, however, that this address can be a @code{symbol_ref}
5304expression even if it would not be a legitimate memory address on the
5305target machine.  If it is also not a valid argument for a call
5306instruction, the pattern for this operation should be a
5307@code{define_expand} (@pxref{Expander Definitions}) that places the
5308address into a register and uses that register in the call instruction.
5309
5310@cindex @code{call_value} instruction pattern
5311@item @samp{call_value}
5312Subroutine call instruction returning a value.  Operand 0 is the hard
5313register in which the value is returned.  There are three more
5314operands, the same as the three operands of the @samp{call}
5315instruction (but with numbers increased by one).
5316
5317Subroutines that return @code{BLKmode} objects use the @samp{call}
5318insn.
5319
5320@cindex @code{call_pop} instruction pattern
5321@cindex @code{call_value_pop} instruction pattern
5322@item @samp{call_pop}, @samp{call_value_pop}
5323Similar to @samp{call} and @samp{call_value}, except used if defined and
5324if @code{RETURN_POPS_ARGS} is nonzero.  They should emit a @code{parallel}
5325that contains both the function call and a @code{set} to indicate the
5326adjustment made to the frame pointer.
5327
5328For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
5329patterns increases the number of functions for which the frame pointer
5330can be eliminated, if desired.
5331
5332@cindex @code{untyped_call} instruction pattern
5333@item @samp{untyped_call}
5334Subroutine call instruction returning a value of any type.  Operand 0 is
5335the function to call; operand 1 is a memory location where the result of
5336calling the function is to be stored; operand 2 is a @code{parallel}
5337expression where each element is a @code{set} expression that indicates
5338the saving of a function return value into the result block.
5339
5340This instruction pattern should be defined to support
5341@code{__builtin_apply} on machines where special instructions are needed
5342to call a subroutine with arbitrary arguments or to save the value
5343returned.  This instruction pattern is required on machines that have
5344multiple registers that can hold a return value
5345(i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
5346
5347@cindex @code{return} instruction pattern
5348@item @samp{return}
5349Subroutine return instruction.  This instruction pattern name should be
5350defined only if a single instruction can do all the work of returning
5351from a function.
5352
5353Like the @samp{mov@var{m}} patterns, this pattern is also used after the
5354RTL generation phase.  In this case it is to support machines where
5355multiple instructions are usually needed to return from a function, but
5356some class of functions only requires one instruction to implement a
5357return.  Normally, the applicable functions are those which do not need
5358to save any registers or allocate stack space.
5359
5360It is valid for this pattern to expand to an instruction using
5361@code{simple_return} if no epilogue is required.
5362
5363@cindex @code{simple_return} instruction pattern
5364@item @samp{simple_return}
5365Subroutine return instruction.  This instruction pattern name should be
5366defined only if a single instruction can do all the work of returning
5367from a function on a path where no epilogue is required.  This pattern
5368is very similar to the @code{return} instruction pattern, but it is emitted
5369only by the shrink-wrapping optimization on paths where the function
5370prologue has not been executed, and a function return should occur without
5371any of the effects of the epilogue.  Additional uses may be introduced on
5372paths where both the prologue and the epilogue have executed.
5373
5374@findex reload_completed
5375@findex leaf_function_p
5376For such machines, the condition specified in this pattern should only
5377be true when @code{reload_completed} is nonzero and the function's
5378epilogue would only be a single instruction.  For machines with register
5379windows, the routine @code{leaf_function_p} may be used to determine if
5380a register window push is required.
5381
5382Machines that have conditional return instructions should define patterns
5383such as
5384
5385@smallexample
5386(define_insn ""
5387  [(set (pc)
5388        (if_then_else (match_operator
5389                         0 "comparison_operator"
5390                         [(cc0) (const_int 0)])
5391                      (return)
5392                      (pc)))]
5393  "@var{condition}"
5394  "@dots{}")
5395@end smallexample
5396
5397where @var{condition} would normally be the same condition specified on the
5398named @samp{return} pattern.
5399
5400@cindex @code{untyped_return} instruction pattern
5401@item @samp{untyped_return}
5402Untyped subroutine return instruction.  This instruction pattern should
5403be defined to support @code{__builtin_return} on machines where special
5404instructions are needed to return a value of any type.
5405
5406Operand 0 is a memory location where the result of calling a function
5407with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
5408expression where each element is a @code{set} expression that indicates
5409the restoring of a function return value from the result block.
5410
5411@cindex @code{nop} instruction pattern
5412@item @samp{nop}
5413No-op instruction.  This instruction pattern name should always be defined
5414to output a no-op in assembler code.  @code{(const_int 0)} will do as an
5415RTL pattern.
5416
5417@cindex @code{indirect_jump} instruction pattern
5418@item @samp{indirect_jump}
5419An instruction to jump to an address which is operand zero.
5420This pattern name is mandatory on all machines.
5421
5422@cindex @code{casesi} instruction pattern
5423@item @samp{casesi}
5424Instruction to jump through a dispatch table, including bounds checking.
5425This instruction takes five operands:
5426
5427@enumerate
5428@item
5429The index to dispatch on, which has mode @code{SImode}.
5430
5431@item
5432The lower bound for indices in the table, an integer constant.
5433
5434@item
5435The total range of indices in the table---the largest index
5436minus the smallest one (both inclusive).
5437
5438@item
5439A label that precedes the table itself.
5440
5441@item
5442A label to jump to if the index has a value outside the bounds.
5443@end enumerate
5444
5445The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
5446@code{jump_insn}.  The number of elements in the table is one plus the
5447difference between the upper bound and the lower bound.
5448
5449@cindex @code{tablejump} instruction pattern
5450@item @samp{tablejump}
5451Instruction to jump to a variable address.  This is a low-level
5452capability which can be used to implement a dispatch table when there
5453is no @samp{casesi} pattern.
5454
5455This pattern requires two operands: the address or offset, and a label
5456which should immediately precede the jump table.  If the macro
5457@code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
5458operand is an offset which counts from the address of the table; otherwise,
5459it is an absolute address to jump to.  In either case, the first operand has
5460mode @code{Pmode}.
5461
5462The @samp{tablejump} insn is always the last insn before the jump
5463table it uses.  Its assembler code normally has no need to use the
5464second operand, but you should incorporate it in the RTL pattern so
5465that the jump optimizer will not delete the table as unreachable code.
5466
5467
5468@cindex @code{decrement_and_branch_until_zero} instruction pattern
5469@item @samp{decrement_and_branch_until_zero}
5470Conditional branch instruction that decrements a register and
5471jumps if the register is nonzero.  Operand 0 is the register to
5472decrement and test; operand 1 is the label to jump to if the
5473register is nonzero.  @xref{Looping Patterns}.
5474
5475This optional instruction pattern is only used by the combiner,
5476typically for loops reversed by the loop optimizer when strength
5477reduction is enabled.
5478
5479@cindex @code{doloop_end} instruction pattern
5480@item @samp{doloop_end}
5481Conditional branch instruction that decrements a register and jumps if
5482the register is nonzero.  This instruction takes five operands: Operand
54830 is the register to decrement and test; operand 1 is the number of loop
5484iterations as a @code{const_int} or @code{const0_rtx} if this cannot be
5485determined until run-time; operand 2 is the actual or estimated maximum
5486number of iterations as a @code{const_int}; operand 3 is the number of
5487enclosed loops as a @code{const_int} (an innermost loop has a value of
54881); operand 4 is the label to jump to if the register is nonzero.
5489@xref{Looping Patterns}.
5490
5491This optional instruction pattern should be defined for machines with
5492low-overhead looping instructions as the loop optimizer will try to
5493modify suitable loops to utilize it.  If nested low-overhead looping is
5494not supported, use a @code{define_expand} (@pxref{Expander Definitions})
5495and make the pattern fail if operand 3 is not @code{const1_rtx}.
5496Similarly, if the actual or estimated maximum number of iterations is
5497too large for this instruction, make it fail.
5498
5499@cindex @code{doloop_begin} instruction pattern
5500@item @samp{doloop_begin}
5501Companion instruction to @code{doloop_end} required for machines that
5502need to perform some initialization, such as loading special registers
5503used by a low-overhead looping instruction.  If initialization insns do
5504not always need to be emitted, use a @code{define_expand}
5505(@pxref{Expander Definitions}) and make it fail.
5506
5507
5508@cindex @code{canonicalize_funcptr_for_compare} instruction pattern
5509@item @samp{canonicalize_funcptr_for_compare}
5510Canonicalize the function pointer in operand 1 and store the result
5511into operand 0.
5512
5513Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
5514may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
5515and also has mode @code{Pmode}.
5516
5517Canonicalization of a function pointer usually involves computing
5518the address of the function which would be called if the function
5519pointer were used in an indirect call.
5520
5521Only define this pattern if function pointers on the target machine
5522can have different values but still call the same function when
5523used in an indirect call.
5524
5525@cindex @code{save_stack_block} instruction pattern
5526@cindex @code{save_stack_function} instruction pattern
5527@cindex @code{save_stack_nonlocal} instruction pattern
5528@cindex @code{restore_stack_block} instruction pattern
5529@cindex @code{restore_stack_function} instruction pattern
5530@cindex @code{restore_stack_nonlocal} instruction pattern
5531@item @samp{save_stack_block}
5532@itemx @samp{save_stack_function}
5533@itemx @samp{save_stack_nonlocal}
5534@itemx @samp{restore_stack_block}
5535@itemx @samp{restore_stack_function}
5536@itemx @samp{restore_stack_nonlocal}
5537Most machines save and restore the stack pointer by copying it to or
5538from an object of mode @code{Pmode}.  Do not define these patterns on
5539such machines.
5540
5541Some machines require special handling for stack pointer saves and
5542restores.  On those machines, define the patterns corresponding to the
5543non-standard cases by using a @code{define_expand} (@pxref{Expander
5544Definitions}) that produces the required insns.  The three types of
5545saves and restores are:
5546
5547@enumerate
5548@item
5549@samp{save_stack_block} saves the stack pointer at the start of a block
5550that allocates a variable-sized object, and @samp{restore_stack_block}
5551restores the stack pointer when the block is exited.
5552
5553@item
5554@samp{save_stack_function} and @samp{restore_stack_function} do a
5555similar job for the outermost block of a function and are used when the
5556function allocates variable-sized objects or calls @code{alloca}.  Only
5557the epilogue uses the restored stack pointer, allowing a simpler save or
5558restore sequence on some machines.
5559
5560@item
5561@samp{save_stack_nonlocal} is used in functions that contain labels
5562branched to by nested functions.  It saves the stack pointer in such a
5563way that the inner function can use @samp{restore_stack_nonlocal} to
5564restore the stack pointer.  The compiler generates code to restore the
5565frame and argument pointer registers, but some machines require saving
5566and restoring additional data such as register window information or
5567stack backchains.  Place insns in these patterns to save and restore any
5568such required data.
5569@end enumerate
5570
5571When saving the stack pointer, operand 0 is the save area and operand 1
5572is the stack pointer.  The mode used to allocate the save area defaults
5573to @code{Pmode} but you can override that choice by defining the
5574@code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}).  You must
5575specify an integral mode, or @code{VOIDmode} if no save area is needed
5576for a particular type of save (either because no save is needed or
5577because a machine-specific save area can be used).  Operand 0 is the
5578stack pointer and operand 1 is the save area for restore operations.  If
5579@samp{save_stack_block} is defined, operand 0 must not be
5580@code{VOIDmode} since these saves can be arbitrarily nested.
5581
5582A save area is a @code{mem} that is at a constant offset from
5583@code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
5584nonlocal gotos and a @code{reg} in the other two cases.
5585
5586@cindex @code{allocate_stack} instruction pattern
5587@item @samp{allocate_stack}
5588Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
5589the stack pointer to create space for dynamically allocated data.
5590
5591Store the resultant pointer to this space into operand 0.  If you
5592are allocating space from the main stack, do this by emitting a
5593move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
5594If you are allocating the space elsewhere, generate code to copy the
5595location of the space to operand 0.  In the latter case, you must
5596ensure this space gets freed when the corresponding space on the main
5597stack is free.
5598
5599Do not define this pattern if all that must be done is the subtraction.
5600Some machines require other operations such as stack probes or
5601maintaining the back chain.  Define this pattern to emit those
5602operations in addition to updating the stack pointer.
5603
5604@cindex @code{check_stack} instruction pattern
5605@item @samp{check_stack}
5606If stack checking (@pxref{Stack Checking}) cannot be done on your system by
5607probing the stack, define this pattern to perform the needed check and signal
5608an error if the stack has overflowed.  The single operand is the address in
5609the stack farthest from the current stack pointer that you need to validate.
5610Normally, on platforms where this pattern is needed, you would obtain the
5611stack limit from a global or thread-specific variable or register.
5612
5613@cindex @code{probe_stack} instruction pattern
5614@item @samp{probe_stack}
5615If stack checking (@pxref{Stack Checking}) can be done on your system by
5616probing the stack but doing it with a ``store zero'' instruction is not valid
5617or optimal, define this pattern to do the probing differently and signal an
5618error if the stack has overflowed.  The single operand is the memory reference
5619in the stack that needs to be probed.
5620
5621@cindex @code{nonlocal_goto} instruction pattern
5622@item @samp{nonlocal_goto}
5623Emit code to generate a non-local goto, e.g., a jump from one function
5624to a label in an outer function.  This pattern has four arguments,
5625each representing a value to be used in the jump.  The first
5626argument is to be loaded into the frame pointer, the second is
5627the address to branch to (code to dispatch to the actual label),
5628the third is the address of a location where the stack is saved,
5629and the last is the address of the label, to be placed in the
5630location for the incoming static chain.
5631
5632On most machines you need not define this pattern, since GCC will
5633already generate the correct code, which is to load the frame pointer
5634and static chain, restore the stack (using the
5635@samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
5636to the dispatcher.  You need only define this pattern if this code will
5637not work on your machine.
5638
5639@cindex @code{nonlocal_goto_receiver} instruction pattern
5640@item @samp{nonlocal_goto_receiver}
5641This pattern, if defined, contains code needed at the target of a
5642nonlocal goto after the code already generated by GCC@.  You will not
5643normally need to define this pattern.  A typical reason why you might
5644need this pattern is if some value, such as a pointer to a global table,
5645must be restored when the frame pointer is restored.  Note that a nonlocal
5646goto only occurs within a unit-of-translation, so a global table pointer
5647that is shared by all functions of a given module need not be restored.
5648There are no arguments.
5649
5650@cindex @code{exception_receiver} instruction pattern
5651@item @samp{exception_receiver}
5652This pattern, if defined, contains code needed at the site of an
5653exception handler that isn't needed at the site of a nonlocal goto.  You
5654will not normally need to define this pattern.  A typical reason why you
5655might need this pattern is if some value, such as a pointer to a global
5656table, must be restored after control flow is branched to the handler of
5657an exception.  There are no arguments.
5658
5659@cindex @code{builtin_setjmp_setup} instruction pattern
5660@item @samp{builtin_setjmp_setup}
5661This pattern, if defined, contains additional code needed to initialize
5662the @code{jmp_buf}.  You will not normally need to define this pattern.
5663A typical reason why you might need this pattern is if some value, such
5664as a pointer to a global table, must be restored.  Though it is
5665preferred that the pointer value be recalculated if possible (given the
5666address of a label for instance).  The single argument is a pointer to
5667the @code{jmp_buf}.  Note that the buffer is five words long and that
5668the first three are normally used by the generic mechanism.
5669
5670@cindex @code{builtin_setjmp_receiver} instruction pattern
5671@item @samp{builtin_setjmp_receiver}
5672This pattern, if defined, contains code needed at the site of a
5673built-in setjmp that isn't needed at the site of a nonlocal goto.  You
5674will not normally need to define this pattern.  A typical reason why you
5675might need this pattern is if some value, such as a pointer to a global
5676table, must be restored.  It takes one argument, which is the label
5677to which builtin_longjmp transfered control; this pattern may be emitted
5678at a small offset from that label.
5679
5680@cindex @code{builtin_longjmp} instruction pattern
5681@item @samp{builtin_longjmp}
5682This pattern, if defined, performs the entire action of the longjmp.
5683You will not normally need to define this pattern unless you also define
5684@code{builtin_setjmp_setup}.  The single argument is a pointer to the
5685@code{jmp_buf}.
5686
5687@cindex @code{eh_return} instruction pattern
5688@item @samp{eh_return}
5689This pattern, if defined, affects the way @code{__builtin_eh_return},
5690and thence the call frame exception handling library routines, are
5691built.  It is intended to handle non-trivial actions needed along
5692the abnormal return path.
5693
5694The address of the exception handler to which the function should return
5695is passed as operand to this pattern.  It will normally need to copied by
5696the pattern to some special register or memory location.
5697If the pattern needs to determine the location of the target call
5698frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
5699if defined; it will have already been assigned.
5700
5701If this pattern is not defined, the default action will be to simply
5702copy the return address to @code{EH_RETURN_HANDLER_RTX}.  Either
5703that macro or this pattern needs to be defined if call frame exception
5704handling is to be used.
5705
5706@cindex @code{prologue} instruction pattern
5707@anchor{prologue instruction pattern}
5708@item @samp{prologue}
5709This pattern, if defined, emits RTL for entry to a function.  The function
5710entry is responsible for setting up the stack frame, initializing the frame
5711pointer register, saving callee saved registers, etc.
5712
5713Using a prologue pattern is generally preferred over defining
5714@code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
5715
5716The @code{prologue} pattern is particularly useful for targets which perform
5717instruction scheduling.
5718
5719@cindex @code{window_save} instruction pattern
5720@anchor{window_save instruction pattern}
5721@item @samp{window_save}
5722This pattern, if defined, emits RTL for a register window save.  It should
5723be defined if the target machine has register windows but the window events
5724are decoupled from calls to subroutines.  The canonical example is the SPARC
5725architecture.
5726
5727@cindex @code{epilogue} instruction pattern
5728@anchor{epilogue instruction pattern}
5729@item @samp{epilogue}
5730This pattern emits RTL for exit from a function.  The function
5731exit is responsible for deallocating the stack frame, restoring callee saved
5732registers and emitting the return instruction.
5733
5734Using an epilogue pattern is generally preferred over defining
5735@code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
5736
5737The @code{epilogue} pattern is particularly useful for targets which perform
5738instruction scheduling or which have delay slots for their return instruction.
5739
5740@cindex @code{sibcall_epilogue} instruction pattern
5741@item @samp{sibcall_epilogue}
5742This pattern, if defined, emits RTL for exit from a function without the final
5743branch back to the calling function.  This pattern will be emitted before any
5744sibling call (aka tail call) sites.
5745
5746The @code{sibcall_epilogue} pattern must not clobber any arguments used for
5747parameter passing or any stack slots for arguments passed to the current
5748function.
5749
5750@cindex @code{trap} instruction pattern
5751@item @samp{trap}
5752This pattern, if defined, signals an error, typically by causing some
5753kind of signal to be raised.  Among other places, it is used by the Java
5754front end to signal `invalid array index' exceptions.
5755
5756@cindex @code{ctrap@var{MM}4} instruction pattern
5757@item @samp{ctrap@var{MM}4}
5758Conditional trap instruction.  Operand 0 is a piece of RTL which
5759performs a comparison, and operands 1 and 2 are the arms of the
5760comparison.  Operand 3 is the trap code, an integer.
5761
5762A typical @code{ctrap} pattern looks like
5763
5764@smallexample
5765(define_insn "ctrapsi4"
5766  [(trap_if (match_operator 0 "trap_operator"
5767             [(match_operand 1 "register_operand")
5768              (match_operand 2 "immediate_operand")])
5769            (match_operand 3 "const_int_operand" "i"))]
5770  ""
5771  "@dots{}")
5772@end smallexample
5773
5774@cindex @code{prefetch} instruction pattern
5775@item @samp{prefetch}
5776
5777This pattern, if defined, emits code for a non-faulting data prefetch
5778instruction.  Operand 0 is the address of the memory to prefetch.  Operand 1
5779is a constant 1 if the prefetch is preparing for a write to the memory
5780address, or a constant 0 otherwise.  Operand 2 is the expected degree of
5781temporal locality of the data and is a value between 0 and 3, inclusive; 0
5782means that the data has no temporal locality, so it need not be left in the
5783cache after the access; 3 means that the data has a high degree of temporal
5784locality and should be left in all levels of cache possible;  1 and 2 mean,
5785respectively, a low or moderate degree of temporal locality.
5786
5787Targets that do not support write prefetches or locality hints can ignore
5788the values of operands 1 and 2.
5789
5790@cindex @code{blockage} instruction pattern
5791@item @samp{blockage}
5792
5793This pattern defines a pseudo insn that prevents the instruction
5794scheduler from moving instructions across the boundary defined by the
5795blockage insn.  Normally an UNSPEC_VOLATILE pattern.
5796
5797@cindex @code{memory_barrier} instruction pattern
5798@item @samp{memory_barrier}
5799
5800If the target memory model is not fully synchronous, then this pattern
5801should be defined to an instruction that orders both loads and stores
5802before the instruction with respect to loads and stores after the instruction.
5803This pattern has no operands.
5804
5805@cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
5806@item @samp{sync_compare_and_swap@var{mode}}
5807
5808This pattern, if defined, emits code for an atomic compare-and-swap
5809operation.  Operand 1 is the memory on which the atomic operation is
5810performed.  Operand 2 is the ``old'' value to be compared against the
5811current contents of the memory location.  Operand 3 is the ``new'' value
5812to store in the memory if the compare succeeds.  Operand 0 is the result
5813of the operation; it should contain the contents of the memory
5814before the operation.  If the compare succeeds, this should obviously be
5815a copy of operand 2.
5816
5817This pattern must show that both operand 0 and operand 1 are modified.
5818
5819This pattern must issue any memory barrier instructions such that all
5820memory operations before the atomic operation occur before the atomic
5821operation and all memory operations after the atomic operation occur
5822after the atomic operation.
5823
5824For targets where the success or failure of the compare-and-swap
5825operation is available via the status flags, it is possible to
5826avoid a separate compare operation and issue the subsequent
5827branch or store-flag operation immediately after the compare-and-swap.
5828To this end, GCC will look for a @code{MODE_CC} set in the
5829output of @code{sync_compare_and_swap@var{mode}}; if the machine
5830description includes such a set, the target should also define special
5831@code{cbranchcc4} and/or @code{cstorecc4} instructions.  GCC will then
5832be able to take the destination of the @code{MODE_CC} set and pass it
5833to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
5834operand of the comparison (the second will be @code{(const_int 0)}).
5835
5836For targets where the operating system may provide support for this
5837operation via library calls, the @code{sync_compare_and_swap_optab}
5838may be initialized to a function with the same interface as the
5839@code{__sync_val_compare_and_swap_@var{n}} built-in.  If the entire
5840set of @var{__sync} builtins are supported via library calls, the
5841target can initialize all of the optabs at once with
5842@code{init_sync_libfuncs}.
5843For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
5844assumed that these library calls do @emph{not} use any kind of
5845interruptable locking.
5846
5847@cindex @code{sync_add@var{mode}} instruction pattern
5848@cindex @code{sync_sub@var{mode}} instruction pattern
5849@cindex @code{sync_ior@var{mode}} instruction pattern
5850@cindex @code{sync_and@var{mode}} instruction pattern
5851@cindex @code{sync_xor@var{mode}} instruction pattern
5852@cindex @code{sync_nand@var{mode}} instruction pattern
5853@item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
5854@itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
5855@itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
5856
5857These patterns emit code for an atomic operation on memory.
5858Operand 0 is the memory on which the atomic operation is performed.
5859Operand 1 is the second operand to the binary operator.
5860
5861This pattern must issue any memory barrier instructions such that all
5862memory operations before the atomic operation occur before the atomic
5863operation and all memory operations after the atomic operation occur
5864after the atomic operation.
5865
5866If these patterns are not defined, the operation will be constructed
5867from a compare-and-swap operation, if defined.
5868
5869@cindex @code{sync_old_add@var{mode}} instruction pattern
5870@cindex @code{sync_old_sub@var{mode}} instruction pattern
5871@cindex @code{sync_old_ior@var{mode}} instruction pattern
5872@cindex @code{sync_old_and@var{mode}} instruction pattern
5873@cindex @code{sync_old_xor@var{mode}} instruction pattern
5874@cindex @code{sync_old_nand@var{mode}} instruction pattern
5875@item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
5876@itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
5877@itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
5878
5879These patterns are emit code for an atomic operation on memory,
5880and return the value that the memory contained before the operation.
5881Operand 0 is the result value, operand 1 is the memory on which the
5882atomic operation is performed, and operand 2 is the second operand
5883to the binary operator.
5884
5885This pattern must issue any memory barrier instructions such that all
5886memory operations before the atomic operation occur before the atomic
5887operation and all memory operations after the atomic operation occur
5888after the atomic operation.
5889
5890If these patterns are not defined, the operation will be constructed
5891from a compare-and-swap operation, if defined.
5892
5893@cindex @code{sync_new_add@var{mode}} instruction pattern
5894@cindex @code{sync_new_sub@var{mode}} instruction pattern
5895@cindex @code{sync_new_ior@var{mode}} instruction pattern
5896@cindex @code{sync_new_and@var{mode}} instruction pattern
5897@cindex @code{sync_new_xor@var{mode}} instruction pattern
5898@cindex @code{sync_new_nand@var{mode}} instruction pattern
5899@item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
5900@itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
5901@itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
5902
5903These patterns are like their @code{sync_old_@var{op}} counterparts,
5904except that they return the value that exists in the memory location
5905after the operation, rather than before the operation.
5906
5907@cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
5908@item @samp{sync_lock_test_and_set@var{mode}}
5909
5910This pattern takes two forms, based on the capabilities of the target.
5911In either case, operand 0 is the result of the operand, operand 1 is
5912the memory on which the atomic operation is performed, and operand 2
5913is the value to set in the lock.
5914
5915In the ideal case, this operation is an atomic exchange operation, in
5916which the previous value in memory operand is copied into the result
5917operand, and the value operand is stored in the memory operand.
5918
5919For less capable targets, any value operand that is not the constant 1
5920should be rejected with @code{FAIL}.  In this case the target may use
5921an atomic test-and-set bit operation.  The result operand should contain
59221 if the bit was previously set and 0 if the bit was previously clear.
5923The true contents of the memory operand are implementation defined.
5924
5925This pattern must issue any memory barrier instructions such that the
5926pattern as a whole acts as an acquire barrier, that is all memory
5927operations after the pattern do not occur until the lock is acquired.
5928
5929If this pattern is not defined, the operation will be constructed from
5930a compare-and-swap operation, if defined.
5931
5932@cindex @code{sync_lock_release@var{mode}} instruction pattern
5933@item @samp{sync_lock_release@var{mode}}
5934
5935This pattern, if defined, releases a lock set by
5936@code{sync_lock_test_and_set@var{mode}}.  Operand 0 is the memory
5937that contains the lock; operand 1 is the value to store in the lock.
5938
5939If the target doesn't implement full semantics for
5940@code{sync_lock_test_and_set@var{mode}}, any value operand which is not
5941the constant 0 should be rejected with @code{FAIL}, and the true contents
5942of the memory operand are implementation defined.
5943
5944This pattern must issue any memory barrier instructions such that the
5945pattern as a whole acts as a release barrier, that is the lock is
5946released only after all previous memory operations have completed.
5947
5948If this pattern is not defined, then a @code{memory_barrier} pattern
5949will be emitted, followed by a store of the value to the memory operand.
5950
5951@cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
5952@item @samp{atomic_compare_and_swap@var{mode}}
5953This pattern, if defined, emits code for an atomic compare-and-swap
5954operation with memory model semantics.  Operand 2 is the memory on which
5955the atomic operation is performed.  Operand 0 is an output operand which
5956is set to true or false based on whether the operation succeeded.  Operand
59571 is an output operand which is set to the contents of the memory before
5958the operation was attempted.  Operand 3 is the value that is expected to
5959be in memory.  Operand 4 is the value to put in memory if the expected
5960value is found there.  Operand 5 is set to 1 if this compare and swap is to
5961be treated as a weak operation.  Operand 6 is the memory model to be used
5962if the operation is a success.  Operand 7 is the memory model to be used
5963if the operation fails.
5964
5965If memory referred to in operand 2 contains the value in operand 3, then
5966operand 4 is stored in memory pointed to by operand 2 and fencing based on
5967the memory model in operand 6 is issued.
5968
5969If memory referred to in operand 2 does not contain the value in operand 3,
5970then fencing based on the memory model in operand 7 is issued.
5971
5972If a target does not support weak compare-and-swap operations, or the port
5973elects not to implement weak operations, the argument in operand 5 can be
5974ignored.  Note a strong implementation must be provided.
5975
5976If this pattern is not provided, the @code{__atomic_compare_exchange}
5977built-in functions will utilize the legacy @code{sync_compare_and_swap}
5978pattern with an @code{__ATOMIC_SEQ_CST} memory model.
5979
5980@cindex @code{atomic_load@var{mode}} instruction pattern
5981@item @samp{atomic_load@var{mode}}
5982This pattern implements an atomic load operation with memory model
5983semantics.  Operand 1 is the memory address being loaded from.  Operand 0
5984is the result of the load.  Operand 2 is the memory model to be used for
5985the load operation.
5986
5987If not present, the @code{__atomic_load} built-in function will either
5988resort to a normal load with memory barriers, or a compare-and-swap
5989operation if a normal load would not be atomic.
5990
5991@cindex @code{atomic_store@var{mode}} instruction pattern
5992@item @samp{atomic_store@var{mode}}
5993This pattern implements an atomic store operation with memory model
5994semantics.  Operand 0 is the memory address being stored to.  Operand 1
5995is the value to be written.  Operand 2 is the memory model to be used for
5996the operation.
5997
5998If not present, the @code{__atomic_store} built-in function will attempt to
5999perform a normal store and surround it with any required memory fences.  If
6000the store would not be atomic, then an @code{__atomic_exchange} is
6001attempted with the result being ignored.
6002
6003@cindex @code{atomic_exchange@var{mode}} instruction pattern
6004@item @samp{atomic_exchange@var{mode}}
6005This pattern implements an atomic exchange operation with memory model
6006semantics.  Operand 1 is the memory location the operation is performed on.
6007Operand 0 is an output operand which is set to the original value contained
6008in the memory pointed to by operand 1.  Operand 2 is the value to be
6009stored.  Operand 3 is the memory model to be used.
6010
6011If this pattern is not present, the built-in function
6012@code{__atomic_exchange} will attempt to preform the operation with a
6013compare and swap loop.
6014
6015@cindex @code{atomic_add@var{mode}} instruction pattern
6016@cindex @code{atomic_sub@var{mode}} instruction pattern
6017@cindex @code{atomic_or@var{mode}} instruction pattern
6018@cindex @code{atomic_and@var{mode}} instruction pattern
6019@cindex @code{atomic_xor@var{mode}} instruction pattern
6020@cindex @code{atomic_nand@var{mode}} instruction pattern
6021@item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
6022@itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
6023@itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
6024
6025These patterns emit code for an atomic operation on memory with memory
6026model semantics. Operand 0 is the memory on which the atomic operation is
6027performed.  Operand 1 is the second operand to the binary operator.
6028Operand 2 is the memory model to be used by the operation.
6029
6030If these patterns are not defined, attempts will be made to use legacy
6031@code{sync} patterns, or equivilent patterns which return a result.  If
6032none of these are available a compare-and-swap loop will be used.
6033
6034@cindex @code{atomic_fetch_add@var{mode}} instruction pattern
6035@cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
6036@cindex @code{atomic_fetch_or@var{mode}} instruction pattern
6037@cindex @code{atomic_fetch_and@var{mode}} instruction pattern
6038@cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
6039@cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
6040@item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
6041@itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
6042@itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
6043
6044These patterns emit code for an atomic operation on memory with memory
6045model semantics, and return the original value. Operand 0 is an output
6046operand which contains the value of the memory location before the
6047operation was performed.  Operand 1 is the memory on which the atomic
6048operation is performed.  Operand 2 is the second operand to the binary
6049operator.  Operand 3 is the memory model to be used by the operation.
6050
6051If these patterns are not defined, attempts will be made to use legacy
6052@code{sync} patterns.  If none of these are available a compare-and-swap
6053loop will be used.
6054
6055@cindex @code{atomic_add_fetch@var{mode}} instruction pattern
6056@cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
6057@cindex @code{atomic_or_fetch@var{mode}} instruction pattern
6058@cindex @code{atomic_and_fetch@var{mode}} instruction pattern
6059@cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
6060@cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
6061@item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
6062@itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
6063@itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
6064
6065These patterns emit code for an atomic operation on memory with memory
6066model semantics and return the result after the operation is performed.
6067Operand 0 is an output operand which contains the value after the
6068operation.  Operand 1 is the memory on which the atomic operation is
6069performed.  Operand 2 is the second operand to the binary operator.
6070Operand 3 is the memory model to be used by the operation.
6071
6072If these patterns are not defined, attempts will be made to use legacy
6073@code{sync} patterns, or equivilent patterns which return the result before
6074the operation followed by the arithmetic operation required to produce the
6075result.  If none of these are available a compare-and-swap loop will be
6076used.
6077
6078@cindex @code{atomic_test_and_set} instruction pattern
6079@item @samp{atomic_test_and_set}
6080
6081This pattern emits code for @code{__builtin_atomic_test_and_set}.
6082Operand 0 is an output operand which is set to true if the previous
6083previous contents of the byte was "set", and false otherwise.  Operand 1
6084is the @code{QImode} memory to be modified.  Operand 2 is the memory
6085model to be used.
6086
6087The specific value that defines "set" is implementation defined, and
6088is normally based on what is performed by the native atomic test and set
6089instruction.
6090
6091@cindex @code{mem_thread_fence@var{mode}} instruction pattern
6092@item @samp{mem_thread_fence@var{mode}}
6093This pattern emits code required to implement a thread fence with
6094memory model semantics.  Operand 0 is the memory model to be used.
6095
6096If this pattern is not specified, all memory models except
6097@code{__ATOMIC_RELAXED} will result in issuing a @code{sync_synchronize}
6098barrier pattern.
6099
6100@cindex @code{mem_signal_fence@var{mode}} instruction pattern
6101@item @samp{mem_signal_fence@var{mode}}
6102This pattern emits code required to implement a signal fence with
6103memory model semantics.  Operand 0 is the memory model to be used.
6104
6105This pattern should impact the compiler optimizers the same way that
6106mem_signal_fence does, but it does not need to issue any barrier
6107instructions.
6108
6109If this pattern is not specified, all memory models except
6110@code{__ATOMIC_RELAXED} will result in issuing a @code{sync_synchronize}
6111barrier pattern.
6112
6113@cindex @code{stack_protect_set} instruction pattern
6114@item @samp{stack_protect_set}
6115
6116This pattern, if defined, moves a @code{ptr_mode} value from the memory
6117in operand 1 to the memory in operand 0 without leaving the value in
6118a register afterward.  This is to avoid leaking the value some place
6119that an attacker might use to rewrite the stack guard slot after
6120having clobbered it.
6121
6122If this pattern is not defined, then a plain move pattern is generated.
6123
6124@cindex @code{stack_protect_test} instruction pattern
6125@item @samp{stack_protect_test}
6126
6127This pattern, if defined, compares a @code{ptr_mode} value from the
6128memory in operand 1 with the memory in operand 0 without leaving the
6129value in a register afterward and branches to operand 2 if the values
6130weren't equal.
6131
6132If this pattern is not defined, then a plain compare pattern and
6133conditional branch pattern is used.
6134
6135@cindex @code{clear_cache} instruction pattern
6136@item @samp{clear_cache}
6137
6138This pattern, if defined, flushes the instruction cache for a region of
6139memory.  The region is bounded to by the Pmode pointers in operand 0
6140inclusive and operand 1 exclusive.
6141
6142If this pattern is not defined, a call to the library function
6143@code{__clear_cache} is used.
6144
6145@end table
6146
6147@end ifset
6148@c Each of the following nodes are wrapped in separate
6149@c "@ifset INTERNALS" to work around memory limits for the default
6150@c configuration in older tetex distributions.  Known to not work:
6151@c tetex-1.0.7, known to work: tetex-2.0.2.
6152@ifset INTERNALS
6153@node Pattern Ordering
6154@section When the Order of Patterns Matters
6155@cindex Pattern Ordering
6156@cindex Ordering of Patterns
6157
6158Sometimes an insn can match more than one instruction pattern.  Then the
6159pattern that appears first in the machine description is the one used.
6160Therefore, more specific patterns (patterns that will match fewer things)
6161and faster instructions (those that will produce better code when they
6162do match) should usually go first in the description.
6163
6164In some cases the effect of ordering the patterns can be used to hide
6165a pattern when it is not valid.  For example, the 68000 has an
6166instruction for converting a fullword to floating point and another
6167for converting a byte to floating point.  An instruction converting
6168an integer to floating point could match either one.  We put the
6169pattern to convert the fullword first to make sure that one will
6170be used rather than the other.  (Otherwise a large integer might
6171be generated as a single-byte immediate quantity, which would not work.)
6172Instead of using this pattern ordering it would be possible to make the
6173pattern for convert-a-byte smart enough to deal properly with any
6174constant value.
6175
6176@end ifset
6177@ifset INTERNALS
6178@node Dependent Patterns
6179@section Interdependence of Patterns
6180@cindex Dependent Patterns
6181@cindex Interdependence of Patterns
6182
6183In some cases machines support instructions identical except for the
6184machine mode of one or more operands.  For example, there may be
6185``sign-extend halfword'' and ``sign-extend byte'' instructions whose
6186patterns are
6187
6188@smallexample
6189(set (match_operand:SI 0 @dots{})
6190     (extend:SI (match_operand:HI 1 @dots{})))
6191
6192(set (match_operand:SI 0 @dots{})
6193     (extend:SI (match_operand:QI 1 @dots{})))
6194@end smallexample
6195
6196@noindent
6197Constant integers do not specify a machine mode, so an instruction to
6198extend a constant value could match either pattern.  The pattern it
6199actually will match is the one that appears first in the file.  For correct
6200results, this must be the one for the widest possible mode (@code{HImode},
6201here).  If the pattern matches the @code{QImode} instruction, the results
6202will be incorrect if the constant value does not actually fit that mode.
6203
6204Such instructions to extend constants are rarely generated because they are
6205optimized away, but they do occasionally happen in nonoptimized
6206compilations.
6207
6208If a constraint in a pattern allows a constant, the reload pass may
6209replace a register with a constant permitted by the constraint in some
6210cases.  Similarly for memory references.  Because of this substitution,
6211you should not provide separate patterns for increment and decrement
6212instructions.  Instead, they should be generated from the same pattern
6213that supports register-register add insns by examining the operands and
6214generating the appropriate machine instruction.
6215
6216@end ifset
6217@ifset INTERNALS
6218@node Jump Patterns
6219@section Defining Jump Instruction Patterns
6220@cindex jump instruction patterns
6221@cindex defining jump instruction patterns
6222
6223GCC does not assume anything about how the machine realizes jumps.
6224The machine description should define a single pattern, usually
6225a @code{define_expand}, which expands to all the required insns.
6226
6227Usually, this would be a comparison insn to set the condition code
6228and a separate branch insn testing the condition code and branching
6229or not according to its value.  For many machines, however,
6230separating compares and branches is limiting, which is why the
6231more flexible approach with one @code{define_expand} is used in GCC.
6232The machine description becomes clearer for architectures that
6233have compare-and-branch instructions but no condition code.  It also
6234works better when different sets of comparison operators are supported
6235by different kinds of conditional branches (e.g. integer vs. floating-point),
6236or by conditional branches with respect to conditional stores.
6237
6238Two separate insns are always used if the machine description represents
6239a condition code register using the legacy RTL expression @code{(cc0)},
6240and on most machines that use a separate condition code register
6241(@pxref{Condition Code}).  For machines that use @code{(cc0)}, in
6242fact, the set and use of the condition code must be separate and
6243adjacent@footnote{@code{note} insns can separate them, though.}, thus
6244allowing flags in @code{cc_status} to be used (@pxref{Condition Code}) and
6245so that the comparison and branch insns could be located from each other
6246by using the functions @code{prev_cc0_setter} and @code{next_cc0_user}.
6247
6248Even in this case having a single entry point for conditional branches
6249is advantageous, because it handles equally well the case where a single
6250comparison instruction records the results of both signed and unsigned
6251comparison of the given operands (with the branch insns coming in distinct
6252signed and unsigned flavors) as in the x86 or SPARC, and the case where
6253there are distinct signed and unsigned compare instructions and only
6254one set of conditional branch instructions as in the PowerPC.
6255
6256@end ifset
6257@ifset INTERNALS
6258@node Looping Patterns
6259@section Defining Looping Instruction Patterns
6260@cindex looping instruction patterns
6261@cindex defining looping instruction patterns
6262
6263Some machines have special jump instructions that can be utilized to
6264make loops more efficient.  A common example is the 68000 @samp{dbra}
6265instruction which performs a decrement of a register and a branch if the
6266result was greater than zero.  Other machines, in particular digital
6267signal processors (DSPs), have special block repeat instructions to
6268provide low-overhead loop support.  For example, the TI TMS320C3x/C4x
6269DSPs have a block repeat instruction that loads special registers to
6270mark the top and end of a loop and to count the number of loop
6271iterations.  This avoids the need for fetching and executing a
6272@samp{dbra}-like instruction and avoids pipeline stalls associated with
6273the jump.
6274
6275GCC has three special named patterns to support low overhead looping.
6276They are @samp{decrement_and_branch_until_zero}, @samp{doloop_begin},
6277and @samp{doloop_end}.  The first pattern,
6278@samp{decrement_and_branch_until_zero}, is not emitted during RTL
6279generation but may be emitted during the instruction combination phase.
6280This requires the assistance of the loop optimizer, using information
6281collected during strength reduction, to reverse a loop to count down to
6282zero.  Some targets also require the loop optimizer to add a
6283@code{REG_NONNEG} note to indicate that the iteration count is always
6284positive.  This is needed if the target performs a signed loop
6285termination test.  For example, the 68000 uses a pattern similar to the
6286following for its @code{dbra} instruction:
6287
6288@smallexample
6289@group
6290(define_insn "decrement_and_branch_until_zero"
6291  [(set (pc)
6292        (if_then_else
6293          (ge (plus:SI (match_operand:SI 0 "general_operand" "+d*am")
6294                       (const_int -1))
6295              (const_int 0))
6296          (label_ref (match_operand 1 "" ""))
6297          (pc)))
6298   (set (match_dup 0)
6299        (plus:SI (match_dup 0)
6300                 (const_int -1)))]
6301  "find_reg_note (insn, REG_NONNEG, 0)"
6302  "@dots{}")
6303@end group
6304@end smallexample
6305
6306Note that since the insn is both a jump insn and has an output, it must
6307deal with its own reloads, hence the `m' constraints.  Also note that
6308since this insn is generated by the instruction combination phase
6309combining two sequential insns together into an implicit parallel insn,
6310the iteration counter needs to be biased by the same amount as the
6311decrement operation, in this case @minus{}1.  Note that the following similar
6312pattern will not be matched by the combiner.
6313
6314@smallexample
6315@group
6316(define_insn "decrement_and_branch_until_zero"
6317  [(set (pc)
6318        (if_then_else
6319          (ge (match_operand:SI 0 "general_operand" "+d*am")
6320              (const_int 1))
6321          (label_ref (match_operand 1 "" ""))
6322          (pc)))
6323   (set (match_dup 0)
6324        (plus:SI (match_dup 0)
6325                 (const_int -1)))]
6326  "find_reg_note (insn, REG_NONNEG, 0)"
6327  "@dots{}")
6328@end group
6329@end smallexample
6330
6331The other two special looping patterns, @samp{doloop_begin} and
6332@samp{doloop_end}, are emitted by the loop optimizer for certain
6333well-behaved loops with a finite number of loop iterations using
6334information collected during strength reduction.
6335
6336The @samp{doloop_end} pattern describes the actual looping instruction
6337(or the implicit looping operation) and the @samp{doloop_begin} pattern
6338is an optional companion pattern that can be used for initialization
6339needed for some low-overhead looping instructions.
6340
6341Note that some machines require the actual looping instruction to be
6342emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs).  Emitting
6343the true RTL for a looping instruction at the top of the loop can cause
6344problems with flow analysis.  So instead, a dummy @code{doloop} insn is
6345emitted at the end of the loop.  The machine dependent reorg pass checks
6346for the presence of this @code{doloop} insn and then searches back to
6347the top of the loop, where it inserts the true looping insn (provided
6348there are no instructions in the loop which would cause problems).  Any
6349additional labels can be emitted at this point.  In addition, if the
6350desired special iteration counter register was not allocated, this
6351machine dependent reorg pass could emit a traditional compare and jump
6352instruction pair.
6353
6354The essential difference between the
6355@samp{decrement_and_branch_until_zero} and the @samp{doloop_end}
6356patterns is that the loop optimizer allocates an additional pseudo
6357register for the latter as an iteration counter.  This pseudo register
6358cannot be used within the loop (i.e., general induction variables cannot
6359be derived from it), however, in many cases the loop induction variable
6360may become redundant and removed by the flow pass.
6361
6362
6363@end ifset
6364@ifset INTERNALS
6365@node Insn Canonicalizations
6366@section Canonicalization of Instructions
6367@cindex canonicalization of instructions
6368@cindex insn canonicalization
6369
6370There are often cases where multiple RTL expressions could represent an
6371operation performed by a single machine instruction.  This situation is
6372most commonly encountered with logical, branch, and multiply-accumulate
6373instructions.  In such cases, the compiler attempts to convert these
6374multiple RTL expressions into a single canonical form to reduce the
6375number of insn patterns required.
6376
6377In addition to algebraic simplifications, following canonicalizations
6378are performed:
6379
6380@itemize @bullet
6381@item
6382For commutative and comparison operators, a constant is always made the
6383second operand.  If a machine only supports a constant as the second
6384operand, only patterns that match a constant in the second operand need
6385be supplied.
6386
6387@item
6388For associative operators, a sequence of operators will always chain
6389to the left; for instance, only the left operand of an integer @code{plus}
6390can itself be a @code{plus}.  @code{and}, @code{ior}, @code{xor},
6391@code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
6392@code{umax} are associative when applied to integers, and sometimes to
6393floating-point.
6394
6395@item
6396@cindex @code{neg}, canonicalization of
6397@cindex @code{not}, canonicalization of
6398@cindex @code{mult}, canonicalization of
6399@cindex @code{plus}, canonicalization of
6400@cindex @code{minus}, canonicalization of
6401For these operators, if only one operand is a @code{neg}, @code{not},
6402@code{mult}, @code{plus}, or @code{minus} expression, it will be the
6403first operand.
6404
6405@item
6406In combinations of @code{neg}, @code{mult}, @code{plus}, and
6407@code{minus}, the @code{neg} operations (if any) will be moved inside
6408the operations as far as possible.  For instance,
6409@code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
6410@code{(plus (mult (neg B) C) A)} is canonicalized as
6411@code{(minus A (mult B C))}.
6412
6413@cindex @code{compare}, canonicalization of
6414@item
6415For the @code{compare} operator, a constant is always the second operand
6416if the first argument is a condition code register or @code{(cc0)}.
6417
6418@item
6419An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
6420@code{minus} is made the first operand under the same conditions as
6421above.
6422
6423@item
6424@code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
6425@code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
6426of @code{ltu}.
6427
6428@item
6429@code{(minus @var{x} (const_int @var{n}))} is converted to
6430@code{(plus @var{x} (const_int @var{-n}))}.
6431
6432@item
6433Within address computations (i.e., inside @code{mem}), a left shift is
6434converted into the appropriate multiplication by a power of two.
6435
6436@cindex @code{ior}, canonicalization of
6437@cindex @code{and}, canonicalization of
6438@cindex De Morgan's law
6439@item
6440De Morgan's Law is used to move bitwise negation inside a bitwise
6441logical-and or logical-or operation.  If this results in only one
6442operand being a @code{not} expression, it will be the first one.
6443
6444A machine that has an instruction that performs a bitwise logical-and of one
6445operand with the bitwise negation of the other should specify the pattern
6446for that instruction as
6447
6448@smallexample
6449(define_insn ""
6450  [(set (match_operand:@var{m} 0 @dots{})
6451        (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
6452                     (match_operand:@var{m} 2 @dots{})))]
6453  "@dots{}"
6454  "@dots{}")
6455@end smallexample
6456
6457@noindent
6458Similarly, a pattern for a ``NAND'' instruction should be written
6459
6460@smallexample
6461(define_insn ""
6462  [(set (match_operand:@var{m} 0 @dots{})
6463        (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
6464                     (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
6465  "@dots{}"
6466  "@dots{}")
6467@end smallexample
6468
6469In both cases, it is not necessary to include patterns for the many
6470logically equivalent RTL expressions.
6471
6472@cindex @code{xor}, canonicalization of
6473@item
6474The only possible RTL expressions involving both bitwise exclusive-or
6475and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
6476and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
6477
6478@item
6479The sum of three items, one of which is a constant, will only appear in
6480the form
6481
6482@smallexample
6483(plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
6484@end smallexample
6485
6486@cindex @code{zero_extract}, canonicalization of
6487@cindex @code{sign_extract}, canonicalization of
6488@item
6489Equality comparisons of a group of bits (usually a single bit) with zero
6490will be written using @code{zero_extract} rather than the equivalent
6491@code{and} or @code{sign_extract} operations.
6492
6493@cindex @code{mult}, canonicalization of
6494@item
6495@code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
6496(sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
6497(sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
6498for @code{zero_extend}.
6499
6500@item
6501@code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
6502@var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
6503to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
6504@var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
6505patterns using @code{zero_extend} and @code{lshiftrt}.  If the second
6506operand of @code{mult} is also a shift, then that is extended also.
6507This transformation is only applied when it can be proven that the
6508original operation had sufficient precision to prevent overflow.
6509
6510@end itemize
6511
6512Further canonicalization rules are defined in the function
6513@code{commutative_operand_precedence} in @file{gcc/rtlanal.c}.
6514
6515@end ifset
6516@ifset INTERNALS
6517@node Expander Definitions
6518@section Defining RTL Sequences for Code Generation
6519@cindex expander definitions
6520@cindex code generation RTL sequences
6521@cindex defining RTL sequences for code generation
6522
6523On some target machines, some standard pattern names for RTL generation
6524cannot be handled with single insn, but a sequence of RTL insns can
6525represent them.  For these target machines, you can write a
6526@code{define_expand} to specify how to generate the sequence of RTL@.
6527
6528@findex define_expand
6529A @code{define_expand} is an RTL expression that looks almost like a
6530@code{define_insn}; but, unlike the latter, a @code{define_expand} is used
6531only for RTL generation and it can produce more than one RTL insn.
6532
6533A @code{define_expand} RTX has four operands:
6534
6535@itemize @bullet
6536@item
6537The name.  Each @code{define_expand} must have a name, since the only
6538use for it is to refer to it by name.
6539
6540@item
6541The RTL template.  This is a vector of RTL expressions representing
6542a sequence of separate instructions.  Unlike @code{define_insn}, there
6543is no implicit surrounding @code{PARALLEL}.
6544
6545@item
6546The condition, a string containing a C expression.  This expression is
6547used to express how the availability of this pattern depends on
6548subclasses of target machine, selected by command-line options when GCC
6549is run.  This is just like the condition of a @code{define_insn} that
6550has a standard name.  Therefore, the condition (if present) may not
6551depend on the data in the insn being matched, but only the
6552target-machine-type flags.  The compiler needs to test these conditions
6553during initialization in order to learn exactly which named instructions
6554are available in a particular run.
6555
6556@item
6557The preparation statements, a string containing zero or more C
6558statements which are to be executed before RTL code is generated from
6559the RTL template.
6560
6561Usually these statements prepare temporary registers for use as
6562internal operands in the RTL template, but they can also generate RTL
6563insns directly by calling routines such as @code{emit_insn}, etc.
6564Any such insns precede the ones that come from the RTL template.
6565@end itemize
6566
6567Every RTL insn emitted by a @code{define_expand} must match some
6568@code{define_insn} in the machine description.  Otherwise, the compiler
6569will crash when trying to generate code for the insn or trying to optimize
6570it.
6571
6572The RTL template, in addition to controlling generation of RTL insns,
6573also describes the operands that need to be specified when this pattern
6574is used.  In particular, it gives a predicate for each operand.
6575
6576A true operand, which needs to be specified in order to generate RTL from
6577the pattern, should be described with a @code{match_operand} in its first
6578occurrence in the RTL template.  This enters information on the operand's
6579predicate into the tables that record such things.  GCC uses the
6580information to preload the operand into a register if that is required for
6581valid RTL code.  If the operand is referred to more than once, subsequent
6582references should use @code{match_dup}.
6583
6584The RTL template may also refer to internal ``operands'' which are
6585temporary registers or labels used only within the sequence made by the
6586@code{define_expand}.  Internal operands are substituted into the RTL
6587template with @code{match_dup}, never with @code{match_operand}.  The
6588values of the internal operands are not passed in as arguments by the
6589compiler when it requests use of this pattern.  Instead, they are computed
6590within the pattern, in the preparation statements.  These statements
6591compute the values and store them into the appropriate elements of
6592@code{operands} so that @code{match_dup} can find them.
6593
6594There are two special macros defined for use in the preparation statements:
6595@code{DONE} and @code{FAIL}.  Use them with a following semicolon,
6596as a statement.
6597
6598@table @code
6599
6600@findex DONE
6601@item DONE
6602Use the @code{DONE} macro to end RTL generation for the pattern.  The
6603only RTL insns resulting from the pattern on this occasion will be
6604those already emitted by explicit calls to @code{emit_insn} within the
6605preparation statements; the RTL template will not be generated.
6606
6607@findex FAIL
6608@item FAIL
6609Make the pattern fail on this occasion.  When a pattern fails, it means
6610that the pattern was not truly available.  The calling routines in the
6611compiler will try other strategies for code generation using other patterns.
6612
6613Failure is currently supported only for binary (addition, multiplication,
6614shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
6615operations.
6616@end table
6617
6618If the preparation falls through (invokes neither @code{DONE} nor
6619@code{FAIL}), then the @code{define_expand} acts like a
6620@code{define_insn} in that the RTL template is used to generate the
6621insn.
6622
6623The RTL template is not used for matching, only for generating the
6624initial insn list.  If the preparation statement always invokes
6625@code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
6626list of operands, such as this example:
6627
6628@smallexample
6629@group
6630(define_expand "addsi3"
6631  [(match_operand:SI 0 "register_operand" "")
6632   (match_operand:SI 1 "register_operand" "")
6633   (match_operand:SI 2 "register_operand" "")]
6634@end group
6635@group
6636  ""
6637  "
6638@{
6639  handle_add (operands[0], operands[1], operands[2]);
6640  DONE;
6641@}")
6642@end group
6643@end smallexample
6644
6645Here is an example, the definition of left-shift for the SPUR chip:
6646
6647@smallexample
6648@group
6649(define_expand "ashlsi3"
6650  [(set (match_operand:SI 0 "register_operand" "")
6651        (ashift:SI
6652@end group
6653@group
6654          (match_operand:SI 1 "register_operand" "")
6655          (match_operand:SI 2 "nonmemory_operand" "")))]
6656  ""
6657  "
6658@end group
6659@end smallexample
6660
6661@smallexample
6662@group
6663@{
6664  if (GET_CODE (operands[2]) != CONST_INT
6665      || (unsigned) INTVAL (operands[2]) > 3)
6666    FAIL;
6667@}")
6668@end group
6669@end smallexample
6670
6671@noindent
6672This example uses @code{define_expand} so that it can generate an RTL insn
6673for shifting when the shift-count is in the supported range of 0 to 3 but
6674fail in other cases where machine insns aren't available.  When it fails,
6675the compiler tries another strategy using different patterns (such as, a
6676library call).
6677
6678If the compiler were able to handle nontrivial condition-strings in
6679patterns with names, then it would be possible to use a
6680@code{define_insn} in that case.  Here is another case (zero-extension
6681on the 68000) which makes more use of the power of @code{define_expand}:
6682
6683@smallexample
6684(define_expand "zero_extendhisi2"
6685  [(set (match_operand:SI 0 "general_operand" "")
6686        (const_int 0))
6687   (set (strict_low_part
6688          (subreg:HI
6689            (match_dup 0)
6690            0))
6691        (match_operand:HI 1 "general_operand" ""))]
6692  ""
6693  "operands[1] = make_safe_from (operands[1], operands[0]);")
6694@end smallexample
6695
6696@noindent
6697@findex make_safe_from
6698Here two RTL insns are generated, one to clear the entire output operand
6699and the other to copy the input operand into its low half.  This sequence
6700is incorrect if the input operand refers to [the old value of] the output
6701operand, so the preparation statement makes sure this isn't so.  The
6702function @code{make_safe_from} copies the @code{operands[1]} into a
6703temporary register if it refers to @code{operands[0]}.  It does this
6704by emitting another RTL insn.
6705
6706Finally, a third example shows the use of an internal operand.
6707Zero-extension on the SPUR chip is done by @code{and}-ing the result
6708against a halfword mask.  But this mask cannot be represented by a
6709@code{const_int} because the constant value is too large to be legitimate
6710on this machine.  So it must be copied into a register with
6711@code{force_reg} and then the register used in the @code{and}.
6712
6713@smallexample
6714(define_expand "zero_extendhisi2"
6715  [(set (match_operand:SI 0 "register_operand" "")
6716        (and:SI (subreg:SI
6717                  (match_operand:HI 1 "register_operand" "")
6718                  0)
6719                (match_dup 2)))]
6720  ""
6721  "operands[2]
6722     = force_reg (SImode, GEN_INT (65535)); ")
6723@end smallexample
6724
6725@emph{Note:} If the @code{define_expand} is used to serve a
6726standard binary or unary arithmetic operation or a bit-field operation,
6727then the last insn it generates must not be a @code{code_label},
6728@code{barrier} or @code{note}.  It must be an @code{insn},
6729@code{jump_insn} or @code{call_insn}.  If you don't need a real insn
6730at the end, emit an insn to copy the result of the operation into
6731itself.  Such an insn will generate no code, but it can avoid problems
6732in the compiler.
6733
6734@end ifset
6735@ifset INTERNALS
6736@node Insn Splitting
6737@section Defining How to Split Instructions
6738@cindex insn splitting
6739@cindex instruction splitting
6740@cindex splitting instructions
6741
6742There are two cases where you should specify how to split a pattern
6743into multiple insns.  On machines that have instructions requiring
6744delay slots (@pxref{Delay Slots}) or that have instructions whose
6745output is not available for multiple cycles (@pxref{Processor pipeline
6746description}), the compiler phases that optimize these cases need to
6747be able to move insns into one-instruction delay slots.  However, some
6748insns may generate more than one machine instruction.  These insns
6749cannot be placed into a delay slot.
6750
6751Often you can rewrite the single insn as a list of individual insns,
6752each corresponding to one machine instruction.  The disadvantage of
6753doing so is that it will cause the compilation to be slower and require
6754more space.  If the resulting insns are too complex, it may also
6755suppress some optimizations.  The compiler splits the insn if there is a
6756reason to believe that it might improve instruction or delay slot
6757scheduling.
6758
6759The insn combiner phase also splits putative insns.  If three insns are
6760merged into one insn with a complex expression that cannot be matched by
6761some @code{define_insn} pattern, the combiner phase attempts to split
6762the complex pattern into two insns that are recognized.  Usually it can
6763break the complex pattern into two patterns by splitting out some
6764subexpression.  However, in some other cases, such as performing an
6765addition of a large constant in two insns on a RISC machine, the way to
6766split the addition into two insns is machine-dependent.
6767
6768@findex define_split
6769The @code{define_split} definition tells the compiler how to split a
6770complex insn into several simpler insns.  It looks like this:
6771
6772@smallexample
6773(define_split
6774  [@var{insn-pattern}]
6775  "@var{condition}"
6776  [@var{new-insn-pattern-1}
6777   @var{new-insn-pattern-2}
6778   @dots{}]
6779  "@var{preparation-statements}")
6780@end smallexample
6781
6782@var{insn-pattern} is a pattern that needs to be split and
6783@var{condition} is the final condition to be tested, as in a
6784@code{define_insn}.  When an insn matching @var{insn-pattern} and
6785satisfying @var{condition} is found, it is replaced in the insn list
6786with the insns given by @var{new-insn-pattern-1},
6787@var{new-insn-pattern-2}, etc.
6788
6789The @var{preparation-statements} are similar to those statements that
6790are specified for @code{define_expand} (@pxref{Expander Definitions})
6791and are executed before the new RTL is generated to prepare for the
6792generated code or emit some insns whose pattern is not fixed.  Unlike
6793those in @code{define_expand}, however, these statements must not
6794generate any new pseudo-registers.  Once reload has completed, they also
6795must not allocate any space in the stack frame.
6796
6797Patterns are matched against @var{insn-pattern} in two different
6798circumstances.  If an insn needs to be split for delay slot scheduling
6799or insn scheduling, the insn is already known to be valid, which means
6800that it must have been matched by some @code{define_insn} and, if
6801@code{reload_completed} is nonzero, is known to satisfy the constraints
6802of that @code{define_insn}.  In that case, the new insn patterns must
6803also be insns that are matched by some @code{define_insn} and, if
6804@code{reload_completed} is nonzero, must also satisfy the constraints
6805of those definitions.
6806
6807As an example of this usage of @code{define_split}, consider the following
6808example from @file{a29k.md}, which splits a @code{sign_extend} from
6809@code{HImode} to @code{SImode} into a pair of shift insns:
6810
6811@smallexample
6812(define_split
6813  [(set (match_operand:SI 0 "gen_reg_operand" "")
6814        (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
6815  ""
6816  [(set (match_dup 0)
6817        (ashift:SI (match_dup 1)
6818                   (const_int 16)))
6819   (set (match_dup 0)
6820        (ashiftrt:SI (match_dup 0)
6821                     (const_int 16)))]
6822  "
6823@{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
6824@end smallexample
6825
6826When the combiner phase tries to split an insn pattern, it is always the
6827case that the pattern is @emph{not} matched by any @code{define_insn}.
6828The combiner pass first tries to split a single @code{set} expression
6829and then the same @code{set} expression inside a @code{parallel}, but
6830followed by a @code{clobber} of a pseudo-reg to use as a scratch
6831register.  In these cases, the combiner expects exactly two new insn
6832patterns to be generated.  It will verify that these patterns match some
6833@code{define_insn} definitions, so you need not do this test in the
6834@code{define_split} (of course, there is no point in writing a
6835@code{define_split} that will never produce insns that match).
6836
6837Here is an example of this use of @code{define_split}, taken from
6838@file{rs6000.md}:
6839
6840@smallexample
6841(define_split
6842  [(set (match_operand:SI 0 "gen_reg_operand" "")
6843        (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
6844                 (match_operand:SI 2 "non_add_cint_operand" "")))]
6845  ""
6846  [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
6847   (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
6848"
6849@{
6850  int low = INTVAL (operands[2]) & 0xffff;
6851  int high = (unsigned) INTVAL (operands[2]) >> 16;
6852
6853  if (low & 0x8000)
6854    high++, low |= 0xffff0000;
6855
6856  operands[3] = GEN_INT (high << 16);
6857  operands[4] = GEN_INT (low);
6858@}")
6859@end smallexample
6860
6861Here the predicate @code{non_add_cint_operand} matches any
6862@code{const_int} that is @emph{not} a valid operand of a single add
6863insn.  The add with the smaller displacement is written so that it
6864can be substituted into the address of a subsequent operation.
6865
6866An example that uses a scratch register, from the same file, generates
6867an equality comparison of a register and a large constant:
6868
6869@smallexample
6870(define_split
6871  [(set (match_operand:CC 0 "cc_reg_operand" "")
6872        (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
6873                    (match_operand:SI 2 "non_short_cint_operand" "")))
6874   (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
6875  "find_single_use (operands[0], insn, 0)
6876   && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
6877       || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
6878  [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
6879   (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
6880  "
6881@{
6882  /* @r{Get the constant we are comparing against, C, and see what it
6883     looks like sign-extended to 16 bits.  Then see what constant
6884     could be XOR'ed with C to get the sign-extended value.}  */
6885
6886  int c = INTVAL (operands[2]);
6887  int sextc = (c << 16) >> 16;
6888  int xorv = c ^ sextc;
6889
6890  operands[4] = GEN_INT (xorv);
6891  operands[5] = GEN_INT (sextc);
6892@}")
6893@end smallexample
6894
6895To avoid confusion, don't write a single @code{define_split} that
6896accepts some insns that match some @code{define_insn} as well as some
6897insns that don't.  Instead, write two separate @code{define_split}
6898definitions, one for the insns that are valid and one for the insns that
6899are not valid.
6900
6901The splitter is allowed to split jump instructions into sequence of
6902jumps or create new jumps in while splitting non-jump instructions.  As
6903the central flowgraph and branch prediction information needs to be updated,
6904several restriction apply.
6905
6906Splitting of jump instruction into sequence that over by another jump
6907instruction is always valid, as compiler expect identical behavior of new
6908jump.  When new sequence contains multiple jump instructions or new labels,
6909more assistance is needed.  Splitter is required to create only unconditional
6910jumps, or simple conditional jump instructions.  Additionally it must attach a
6911@code{REG_BR_PROB} note to each conditional jump.  A global variable
6912@code{split_branch_probability} holds the probability of the original branch in case
6913it was a simple conditional jump, @minus{}1 otherwise.  To simplify
6914recomputing of edge frequencies, the new sequence is required to have only
6915forward jumps to the newly created labels.
6916
6917@findex define_insn_and_split
6918For the common case where the pattern of a define_split exactly matches the
6919pattern of a define_insn, use @code{define_insn_and_split}.  It looks like
6920this:
6921
6922@smallexample
6923(define_insn_and_split
6924  [@var{insn-pattern}]
6925  "@var{condition}"
6926  "@var{output-template}"
6927  "@var{split-condition}"
6928  [@var{new-insn-pattern-1}
6929   @var{new-insn-pattern-2}
6930   @dots{}]
6931  "@var{preparation-statements}"
6932  [@var{insn-attributes}])
6933
6934@end smallexample
6935
6936@var{insn-pattern}, @var{condition}, @var{output-template}, and
6937@var{insn-attributes} are used as in @code{define_insn}.  The
6938@var{new-insn-pattern} vector and the @var{preparation-statements} are used as
6939in a @code{define_split}.  The @var{split-condition} is also used as in
6940@code{define_split}, with the additional behavior that if the condition starts
6941with @samp{&&}, the condition used for the split will be the constructed as a
6942logical ``and'' of the split condition with the insn condition.  For example,
6943from i386.md:
6944
6945@smallexample
6946(define_insn_and_split "zero_extendhisi2_and"
6947  [(set (match_operand:SI 0 "register_operand" "=r")
6948     (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
6949   (clobber (reg:CC 17))]
6950  "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
6951  "#"
6952  "&& reload_completed"
6953  [(parallel [(set (match_dup 0)
6954                   (and:SI (match_dup 0) (const_int 65535)))
6955              (clobber (reg:CC 17))])]
6956  ""
6957  [(set_attr "type" "alu1")])
6958
6959@end smallexample
6960
6961In this case, the actual split condition will be
6962@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
6963
6964The @code{define_insn_and_split} construction provides exactly the same
6965functionality as two separate @code{define_insn} and @code{define_split}
6966patterns.  It exists for compactness, and as a maintenance tool to prevent
6967having to ensure the two patterns' templates match.
6968
6969@end ifset
6970@ifset INTERNALS
6971@node Including Patterns
6972@section Including Patterns in Machine Descriptions.
6973@cindex insn includes
6974
6975@findex include
6976The @code{include} pattern tells the compiler tools where to
6977look for patterns that are in files other than in the file
6978@file{.md}.  This is used only at build time and there is no preprocessing allowed.
6979
6980It looks like:
6981
6982@smallexample
6983
6984(include
6985  @var{pathname})
6986@end smallexample
6987
6988For example:
6989
6990@smallexample
6991
6992(include "filestuff")
6993
6994@end smallexample
6995
6996Where @var{pathname} is a string that specifies the location of the file,
6997specifies the include file to be in @file{gcc/config/target/filestuff}.  The
6998directory @file{gcc/config/target} is regarded as the default directory.
6999
7000
7001Machine descriptions may be split up into smaller more manageable subsections
7002and placed into subdirectories.
7003
7004By specifying:
7005
7006@smallexample
7007
7008(include "BOGUS/filestuff")
7009
7010@end smallexample
7011
7012the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.
7013
7014Specifying an absolute path for the include file such as;
7015@smallexample
7016
7017(include "/u2/BOGUS/filestuff")
7018
7019@end smallexample
7020is permitted but is not encouraged.
7021
7022@subsection RTL Generation Tool Options for Directory Search
7023@cindex directory options .md
7024@cindex options, directory search
7025@cindex search options
7026
7027The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
7028For example:
7029
7030@smallexample
7031
7032genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
7033
7034@end smallexample
7035
7036
7037Add the directory @var{dir} to the head of the list of directories to be
7038searched for header files.  This can be used to override a system machine definition
7039file, substituting your own version, since these directories are
7040searched before the default machine description file directories.  If you use more than
7041one @option{-I} option, the directories are scanned in left-to-right
7042order; the standard default directory come after.
7043
7044
7045@end ifset
7046@ifset INTERNALS
7047@node Peephole Definitions
7048@section Machine-Specific Peephole Optimizers
7049@cindex peephole optimizer definitions
7050@cindex defining peephole optimizers
7051
7052In addition to instruction patterns the @file{md} file may contain
7053definitions of machine-specific peephole optimizations.
7054
7055The combiner does not notice certain peephole optimizations when the data
7056flow in the program does not suggest that it should try them.  For example,
7057sometimes two consecutive insns related in purpose can be combined even
7058though the second one does not appear to use a register computed in the
7059first one.  A machine-specific peephole optimizer can detect such
7060opportunities.
7061
7062There are two forms of peephole definitions that may be used.  The
7063original @code{define_peephole} is run at assembly output time to
7064match insns and substitute assembly text.  Use of @code{define_peephole}
7065is deprecated.
7066
7067A newer @code{define_peephole2} matches insns and substitutes new
7068insns.  The @code{peephole2} pass is run after register allocation
7069but before scheduling, which may result in much better code for
7070targets that do scheduling.
7071
7072@menu
7073* define_peephole::     RTL to Text Peephole Optimizers
7074* define_peephole2::    RTL to RTL Peephole Optimizers
7075@end menu
7076
7077@end ifset
7078@ifset INTERNALS
7079@node define_peephole
7080@subsection RTL to Text Peephole Optimizers
7081@findex define_peephole
7082
7083@need 1000
7084A definition looks like this:
7085
7086@smallexample
7087(define_peephole
7088  [@var{insn-pattern-1}
7089   @var{insn-pattern-2}
7090   @dots{}]
7091  "@var{condition}"
7092  "@var{template}"
7093  "@var{optional-insn-attributes}")
7094@end smallexample
7095
7096@noindent
7097The last string operand may be omitted if you are not using any
7098machine-specific information in this machine description.  If present,
7099it must obey the same rules as in a @code{define_insn}.
7100
7101In this skeleton, @var{insn-pattern-1} and so on are patterns to match
7102consecutive insns.  The optimization applies to a sequence of insns when
7103@var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
7104the next, and so on.
7105
7106Each of the insns matched by a peephole must also match a
7107@code{define_insn}.  Peepholes are checked only at the last stage just
7108before code generation, and only optionally.  Therefore, any insn which
7109would match a peephole but no @code{define_insn} will cause a crash in code
7110generation in an unoptimized compilation, or at various optimization
7111stages.
7112
7113The operands of the insns are matched with @code{match_operands},
7114@code{match_operator}, and @code{match_dup}, as usual.  What is not
7115usual is that the operand numbers apply to all the insn patterns in the
7116definition.  So, you can check for identical operands in two insns by
7117using @code{match_operand} in one insn and @code{match_dup} in the
7118other.
7119
7120The operand constraints used in @code{match_operand} patterns do not have
7121any direct effect on the applicability of the peephole, but they will
7122be validated afterward, so make sure your constraints are general enough
7123to apply whenever the peephole matches.  If the peephole matches
7124but the constraints are not satisfied, the compiler will crash.
7125
7126It is safe to omit constraints in all the operands of the peephole; or
7127you can write constraints which serve as a double-check on the criteria
7128previously tested.
7129
7130Once a sequence of insns matches the patterns, the @var{condition} is
7131checked.  This is a C expression which makes the final decision whether to
7132perform the optimization (we do so if the expression is nonzero).  If
7133@var{condition} is omitted (in other words, the string is empty) then the
7134optimization is applied to every sequence of insns that matches the
7135patterns.
7136
7137The defined peephole optimizations are applied after register allocation
7138is complete.  Therefore, the peephole definition can check which
7139operands have ended up in which kinds of registers, just by looking at
7140the operands.
7141
7142@findex prev_active_insn
7143The way to refer to the operands in @var{condition} is to write
7144@code{operands[@var{i}]} for operand number @var{i} (as matched by
7145@code{(match_operand @var{i} @dots{})}).  Use the variable @code{insn}
7146to refer to the last of the insns being matched; use
7147@code{prev_active_insn} to find the preceding insns.
7148
7149@findex dead_or_set_p
7150When optimizing computations with intermediate results, you can use
7151@var{condition} to match only when the intermediate results are not used
7152elsewhere.  Use the C expression @code{dead_or_set_p (@var{insn},
7153@var{op})}, where @var{insn} is the insn in which you expect the value
7154to be used for the last time (from the value of @code{insn}, together
7155with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
7156value (from @code{operands[@var{i}]}).
7157
7158Applying the optimization means replacing the sequence of insns with one
7159new insn.  The @var{template} controls ultimate output of assembler code
7160for this combined insn.  It works exactly like the template of a
7161@code{define_insn}.  Operand numbers in this template are the same ones
7162used in matching the original sequence of insns.
7163
7164The result of a defined peephole optimizer does not need to match any of
7165the insn patterns in the machine description; it does not even have an
7166opportunity to match them.  The peephole optimizer definition itself serves
7167as the insn pattern to control how the insn is output.
7168
7169Defined peephole optimizers are run as assembler code is being output,
7170so the insns they produce are never combined or rearranged in any way.
7171
7172Here is an example, taken from the 68000 machine description:
7173
7174@smallexample
7175(define_peephole
7176  [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
7177   (set (match_operand:DF 0 "register_operand" "=f")
7178        (match_operand:DF 1 "register_operand" "ad"))]
7179  "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
7180@{
7181  rtx xoperands[2];
7182  xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
7183#ifdef MOTOROLA
7184  output_asm_insn ("move.l %1,(sp)", xoperands);
7185  output_asm_insn ("move.l %1,-(sp)", operands);
7186  return "fmove.d (sp)+,%0";
7187#else
7188  output_asm_insn ("movel %1,sp@@", xoperands);
7189  output_asm_insn ("movel %1,sp@@-", operands);
7190  return "fmoved sp@@+,%0";
7191#endif
7192@})
7193@end smallexample
7194
7195@need 1000
7196The effect of this optimization is to change
7197
7198@smallexample
7199@group
7200jbsr _foobar
7201addql #4,sp
7202movel d1,sp@@-
7203movel d0,sp@@-
7204fmoved sp@@+,fp0
7205@end group
7206@end smallexample
7207
7208@noindent
7209into
7210
7211@smallexample
7212@group
7213jbsr _foobar
7214movel d1,sp@@
7215movel d0,sp@@-
7216fmoved sp@@+,fp0
7217@end group
7218@end smallexample
7219
7220@ignore
7221@findex CC_REVERSED
7222If a peephole matches a sequence including one or more jump insns, you must
7223take account of the flags such as @code{CC_REVERSED} which specify that the
7224condition codes are represented in an unusual manner.  The compiler
7225automatically alters any ordinary conditional jumps which occur in such
7226situations, but the compiler cannot alter jumps which have been replaced by
7227peephole optimizations.  So it is up to you to alter the assembler code
7228that the peephole produces.  Supply C code to write the assembler output,
7229and in this C code check the condition code status flags and change the
7230assembler code as appropriate.
7231@end ignore
7232
7233@var{insn-pattern-1} and so on look @emph{almost} like the second
7234operand of @code{define_insn}.  There is one important difference: the
7235second operand of @code{define_insn} consists of one or more RTX's
7236enclosed in square brackets.  Usually, there is only one: then the same
7237action can be written as an element of a @code{define_peephole}.  But
7238when there are multiple actions in a @code{define_insn}, they are
7239implicitly enclosed in a @code{parallel}.  Then you must explicitly
7240write the @code{parallel}, and the square brackets within it, in the
7241@code{define_peephole}.  Thus, if an insn pattern looks like this,
7242
7243@smallexample
7244(define_insn "divmodsi4"
7245  [(set (match_operand:SI 0 "general_operand" "=d")
7246        (div:SI (match_operand:SI 1 "general_operand" "0")
7247                (match_operand:SI 2 "general_operand" "dmsK")))
7248   (set (match_operand:SI 3 "general_operand" "=d")
7249        (mod:SI (match_dup 1) (match_dup 2)))]
7250  "TARGET_68020"
7251  "divsl%.l %2,%3:%0")
7252@end smallexample
7253
7254@noindent
7255then the way to mention this insn in a peephole is as follows:
7256
7257@smallexample
7258(define_peephole
7259  [@dots{}
7260   (parallel
7261    [(set (match_operand:SI 0 "general_operand" "=d")
7262          (div:SI (match_operand:SI 1 "general_operand" "0")
7263                  (match_operand:SI 2 "general_operand" "dmsK")))
7264     (set (match_operand:SI 3 "general_operand" "=d")
7265          (mod:SI (match_dup 1) (match_dup 2)))])
7266   @dots{}]
7267  @dots{})
7268@end smallexample
7269
7270@end ifset
7271@ifset INTERNALS
7272@node define_peephole2
7273@subsection RTL to RTL Peephole Optimizers
7274@findex define_peephole2
7275
7276The @code{define_peephole2} definition tells the compiler how to
7277substitute one sequence of instructions for another sequence,
7278what additional scratch registers may be needed and what their
7279lifetimes must be.
7280
7281@smallexample
7282(define_peephole2
7283  [@var{insn-pattern-1}
7284   @var{insn-pattern-2}
7285   @dots{}]
7286  "@var{condition}"
7287  [@var{new-insn-pattern-1}
7288   @var{new-insn-pattern-2}
7289   @dots{}]
7290  "@var{preparation-statements}")
7291@end smallexample
7292
7293The definition is almost identical to @code{define_split}
7294(@pxref{Insn Splitting}) except that the pattern to match is not a
7295single instruction, but a sequence of instructions.
7296
7297It is possible to request additional scratch registers for use in the
7298output template.  If appropriate registers are not free, the pattern
7299will simply not match.
7300
7301@findex match_scratch
7302@findex match_dup
7303Scratch registers are requested with a @code{match_scratch} pattern at
7304the top level of the input pattern.  The allocated register (initially) will
7305be dead at the point requested within the original sequence.  If the scratch
7306is used at more than a single point, a @code{match_dup} pattern at the
7307top level of the input pattern marks the last position in the input sequence
7308at which the register must be available.
7309
7310Here is an example from the IA-32 machine description:
7311
7312@smallexample
7313(define_peephole2
7314  [(match_scratch:SI 2 "r")
7315   (parallel [(set (match_operand:SI 0 "register_operand" "")
7316                   (match_operator:SI 3 "arith_or_logical_operator"
7317                     [(match_dup 0)
7318                      (match_operand:SI 1 "memory_operand" "")]))
7319              (clobber (reg:CC 17))])]
7320  "! optimize_size && ! TARGET_READ_MODIFY"
7321  [(set (match_dup 2) (match_dup 1))
7322   (parallel [(set (match_dup 0)
7323                   (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
7324              (clobber (reg:CC 17))])]
7325  "")
7326@end smallexample
7327
7328@noindent
7329This pattern tries to split a load from its use in the hopes that we'll be
7330able to schedule around the memory load latency.  It allocates a single
7331@code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
7332to be live only at the point just before the arithmetic.
7333
7334A real example requiring extended scratch lifetimes is harder to come by,
7335so here's a silly made-up example:
7336
7337@smallexample
7338(define_peephole2
7339  [(match_scratch:SI 4 "r")
7340   (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
7341   (set (match_operand:SI 2 "" "") (match_dup 1))
7342   (match_dup 4)
7343   (set (match_operand:SI 3 "" "") (match_dup 1))]
7344  "/* @r{determine 1 does not overlap 0 and 2} */"
7345  [(set (match_dup 4) (match_dup 1))
7346   (set (match_dup 0) (match_dup 4))
7347   (set (match_dup 2) (match_dup 4))]
7348   (set (match_dup 3) (match_dup 4))]
7349  "")
7350@end smallexample
7351
7352@noindent
7353If we had not added the @code{(match_dup 4)} in the middle of the input
7354sequence, it might have been the case that the register we chose at the
7355beginning of the sequence is killed by the first or second @code{set}.
7356
7357@end ifset
7358@ifset INTERNALS
7359@node Insn Attributes
7360@section Instruction Attributes
7361@cindex insn attributes
7362@cindex instruction attributes
7363
7364In addition to describing the instruction supported by the target machine,
7365the @file{md} file also defines a group of @dfn{attributes} and a set of
7366values for each.  Every generated insn is assigned a value for each attribute.
7367One possible attribute would be the effect that the insn has on the machine's
7368condition code.  This attribute can then be used by @code{NOTICE_UPDATE_CC}
7369to track the condition codes.
7370
7371@menu
7372* Defining Attributes:: Specifying attributes and their values.
7373* Expressions::         Valid expressions for attribute values.
7374* Tagging Insns::       Assigning attribute values to insns.
7375* Attr Example::        An example of assigning attributes.
7376* Insn Lengths::        Computing the length of insns.
7377* Constant Attributes:: Defining attributes that are constant.
7378* Delay Slots::         Defining delay slots required for a machine.
7379* Processor pipeline description:: Specifying information for insn scheduling.
7380@end menu
7381
7382@end ifset
7383@ifset INTERNALS
7384@node Defining Attributes
7385@subsection Defining Attributes and their Values
7386@cindex defining attributes and their values
7387@cindex attributes, defining
7388
7389@findex define_attr
7390The @code{define_attr} expression is used to define each attribute required
7391by the target machine.  It looks like:
7392
7393@smallexample
7394(define_attr @var{name} @var{list-of-values} @var{default})
7395@end smallexample
7396
7397@var{name} is a string specifying the name of the attribute being defined.
7398Some attributes are used in a special way by the rest of the compiler. The
7399@code{enabled} attribute can be used to conditionally enable or disable
7400insn alternatives (@pxref{Disable Insn Alternatives}). The @code{predicable}
7401attribute, together with a suitable @code{define_cond_exec}
7402(@pxref{Conditional Execution}), can be used to automatically generate
7403conditional variants of instruction patterns. The compiler internally uses
7404the names @code{ce_enabled} and @code{nonce_enabled}, so they should not be
7405used elsewhere as alternative names.
7406
7407@var{list-of-values} is either a string that specifies a comma-separated
7408list of values that can be assigned to the attribute, or a null string to
7409indicate that the attribute takes numeric values.
7410
7411@var{default} is an attribute expression that gives the value of this
7412attribute for insns that match patterns whose definition does not include
7413an explicit value for this attribute.  @xref{Attr Example}, for more
7414information on the handling of defaults.  @xref{Constant Attributes},
7415for information on attributes that do not depend on any particular insn.
7416
7417@findex insn-attr.h
7418For each defined attribute, a number of definitions are written to the
7419@file{insn-attr.h} file.  For cases where an explicit set of values is
7420specified for an attribute, the following are defined:
7421
7422@itemize @bullet
7423@item
7424A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
7425
7426@item
7427An enumerated class is defined for @samp{attr_@var{name}} with
7428elements of the form @samp{@var{upper-name}_@var{upper-value}} where
7429the attribute name and value are first converted to uppercase.
7430
7431@item
7432A function @samp{get_attr_@var{name}} is defined that is passed an insn and
7433returns the attribute value for that insn.
7434@end itemize
7435
7436For example, if the following is present in the @file{md} file:
7437
7438@smallexample
7439(define_attr "type" "branch,fp,load,store,arith" @dots{})
7440@end smallexample
7441
7442@noindent
7443the following lines will be written to the file @file{insn-attr.h}.
7444
7445@smallexample
7446#define HAVE_ATTR_type
7447enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
7448                 TYPE_STORE, TYPE_ARITH@};
7449extern enum attr_type get_attr_type ();
7450@end smallexample
7451
7452If the attribute takes numeric values, no @code{enum} type will be
7453defined and the function to obtain the attribute's value will return
7454@code{int}.
7455
7456There are attributes which are tied to a specific meaning.  These
7457attributes are not free to use for other purposes:
7458
7459@table @code
7460@item length
7461The @code{length} attribute is used to calculate the length of emitted
7462code chunks.  This is especially important when verifying branch
7463distances. @xref{Insn Lengths}.
7464
7465@item enabled
7466The @code{enabled} attribute can be defined to prevent certain
7467alternatives of an insn definition from being used during code
7468generation. @xref{Disable Insn Alternatives}.
7469@end table
7470
7471@findex define_enum_attr
7472@anchor{define_enum_attr}
7473Another way of defining an attribute is to use:
7474
7475@smallexample
7476(define_enum_attr "@var{attr}" "@var{enum}" @var{default})
7477@end smallexample
7478
7479This works in just the same way as @code{define_attr}, except that
7480the list of values is taken from a separate enumeration called
7481@var{enum} (@pxref{define_enum}).  This form allows you to use
7482the same list of values for several attributes without having to
7483repeat the list each time.  For example:
7484
7485@smallexample
7486(define_enum "processor" [
7487  model_a
7488  model_b
7489  @dots{}
7490])
7491(define_enum_attr "arch" "processor"
7492  (const (symbol_ref "target_arch")))
7493(define_enum_attr "tune" "processor"
7494  (const (symbol_ref "target_tune")))
7495@end smallexample
7496
7497defines the same attributes as:
7498
7499@smallexample
7500(define_attr "arch" "model_a,model_b,@dots{}"
7501  (const (symbol_ref "target_arch")))
7502(define_attr "tune" "model_a,model_b,@dots{}"
7503  (const (symbol_ref "target_tune")))
7504@end smallexample
7505
7506but without duplicating the processor list.  The second example defines two
7507separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
7508defines a single C enum (@code{processor}).
7509@end ifset
7510@ifset INTERNALS
7511@node Expressions
7512@subsection Attribute Expressions
7513@cindex attribute expressions
7514
7515RTL expressions used to define attributes use the codes described above
7516plus a few specific to attribute definitions, to be discussed below.
7517Attribute value expressions must have one of the following forms:
7518
7519@table @code
7520@cindex @code{const_int} and attributes
7521@item (const_int @var{i})
7522The integer @var{i} specifies the value of a numeric attribute.  @var{i}
7523must be non-negative.
7524
7525The value of a numeric attribute can be specified either with a
7526@code{const_int}, or as an integer represented as a string in
7527@code{const_string}, @code{eq_attr} (see below), @code{attr},
7528@code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
7529overrides on specific instructions (@pxref{Tagging Insns}).
7530
7531@cindex @code{const_string} and attributes
7532@item (const_string @var{value})
7533The string @var{value} specifies a constant attribute value.
7534If @var{value} is specified as @samp{"*"}, it means that the default value of
7535the attribute is to be used for the insn containing this expression.
7536@samp{"*"} obviously cannot be used in the @var{default} expression
7537of a @code{define_attr}.
7538
7539If the attribute whose value is being specified is numeric, @var{value}
7540must be a string containing a non-negative integer (normally
7541@code{const_int} would be used in this case).  Otherwise, it must
7542contain one of the valid values for the attribute.
7543
7544@cindex @code{if_then_else} and attributes
7545@item (if_then_else @var{test} @var{true-value} @var{false-value})
7546@var{test} specifies an attribute test, whose format is defined below.
7547The value of this expression is @var{true-value} if @var{test} is true,
7548otherwise it is @var{false-value}.
7549
7550@cindex @code{cond} and attributes
7551@item (cond [@var{test1} @var{value1} @dots{}] @var{default})
7552The first operand of this expression is a vector containing an even
7553number of expressions and consisting of pairs of @var{test} and @var{value}
7554expressions.  The value of the @code{cond} expression is that of the
7555@var{value} corresponding to the first true @var{test} expression.  If
7556none of the @var{test} expressions are true, the value of the @code{cond}
7557expression is that of the @var{default} expression.
7558@end table
7559
7560@var{test} expressions can have one of the following forms:
7561
7562@table @code
7563@cindex @code{const_int} and attribute tests
7564@item (const_int @var{i})
7565This test is true if @var{i} is nonzero and false otherwise.
7566
7567@cindex @code{not} and attributes
7568@cindex @code{ior} and attributes
7569@cindex @code{and} and attributes
7570@item (not @var{test})
7571@itemx (ior @var{test1} @var{test2})
7572@itemx (and @var{test1} @var{test2})
7573These tests are true if the indicated logical function is true.
7574
7575@cindex @code{match_operand} and attributes
7576@item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
7577This test is true if operand @var{n} of the insn whose attribute value
7578is being determined has mode @var{m} (this part of the test is ignored
7579if @var{m} is @code{VOIDmode}) and the function specified by the string
7580@var{pred} returns a nonzero value when passed operand @var{n} and mode
7581@var{m} (this part of the test is ignored if @var{pred} is the null
7582string).
7583
7584The @var{constraints} operand is ignored and should be the null string.
7585
7586@cindex @code{match_test} and attributes
7587@item (match_test @var{c-expr})
7588The test is true if C expression @var{c-expr} is true.  In non-constant
7589attributes, @var{c-expr} has access to the following variables:
7590
7591@table @var
7592@item insn
7593The rtl instruction under test.
7594@item which_alternative
7595The @code{define_insn} alternative that @var{insn} matches.
7596@xref{Output Statement}.
7597@item operands
7598An array of @var{insn}'s rtl operands.
7599@end table
7600
7601@var{c-expr} behaves like the condition in a C @code{if} statement,
7602so there is no need to explicitly convert the expression into a boolean
76030 or 1 value.  For example, the following two tests are equivalent:
7604
7605@smallexample
7606(match_test "x & 2")
7607(match_test "(x & 2) != 0")
7608@end smallexample
7609
7610@cindex @code{le} and attributes
7611@cindex @code{leu} and attributes
7612@cindex @code{lt} and attributes
7613@cindex @code{gt} and attributes
7614@cindex @code{gtu} and attributes
7615@cindex @code{ge} and attributes
7616@cindex @code{geu} and attributes
7617@cindex @code{ne} and attributes
7618@cindex @code{eq} and attributes
7619@cindex @code{plus} and attributes
7620@cindex @code{minus} and attributes
7621@cindex @code{mult} and attributes
7622@cindex @code{div} and attributes
7623@cindex @code{mod} and attributes
7624@cindex @code{abs} and attributes
7625@cindex @code{neg} and attributes
7626@cindex @code{ashift} and attributes
7627@cindex @code{lshiftrt} and attributes
7628@cindex @code{ashiftrt} and attributes
7629@item (le @var{arith1} @var{arith2})
7630@itemx (leu @var{arith1} @var{arith2})
7631@itemx (lt @var{arith1} @var{arith2})
7632@itemx (ltu @var{arith1} @var{arith2})
7633@itemx (gt @var{arith1} @var{arith2})
7634@itemx (gtu @var{arith1} @var{arith2})
7635@itemx (ge @var{arith1} @var{arith2})
7636@itemx (geu @var{arith1} @var{arith2})
7637@itemx (ne @var{arith1} @var{arith2})
7638@itemx (eq @var{arith1} @var{arith2})
7639These tests are true if the indicated comparison of the two arithmetic
7640expressions is true.  Arithmetic expressions are formed with
7641@code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
7642@code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
7643@code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.
7644
7645@findex get_attr
7646@code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
7647Lengths},for additional forms).  @code{symbol_ref} is a string
7648denoting a C expression that yields an @code{int} when evaluated by the
7649@samp{get_attr_@dots{}} routine.  It should normally be a global
7650variable.
7651
7652@findex eq_attr
7653@item (eq_attr @var{name} @var{value})
7654@var{name} is a string specifying the name of an attribute.
7655
7656@var{value} is a string that is either a valid value for attribute
7657@var{name}, a comma-separated list of values, or @samp{!} followed by a
7658value or list.  If @var{value} does not begin with a @samp{!}, this
7659test is true if the value of the @var{name} attribute of the current
7660insn is in the list specified by @var{value}.  If @var{value} begins
7661with a @samp{!}, this test is true if the attribute's value is
7662@emph{not} in the specified list.
7663
7664For example,
7665
7666@smallexample
7667(eq_attr "type" "load,store")
7668@end smallexample
7669
7670@noindent
7671is equivalent to
7672
7673@smallexample
7674(ior (eq_attr "type" "load") (eq_attr "type" "store"))
7675@end smallexample
7676
7677If @var{name} specifies an attribute of @samp{alternative}, it refers to the
7678value of the compiler variable @code{which_alternative}
7679(@pxref{Output Statement}) and the values must be small integers.  For
7680example,
7681
7682@smallexample
7683(eq_attr "alternative" "2,3")
7684@end smallexample
7685
7686@noindent
7687is equivalent to
7688
7689@smallexample
7690(ior (eq (symbol_ref "which_alternative") (const_int 2))
7691     (eq (symbol_ref "which_alternative") (const_int 3)))
7692@end smallexample
7693
7694Note that, for most attributes, an @code{eq_attr} test is simplified in cases
7695where the value of the attribute being tested is known for all insns matching
7696a particular pattern.  This is by far the most common case.
7697
7698@findex attr_flag
7699@item (attr_flag @var{name})
7700The value of an @code{attr_flag} expression is true if the flag
7701specified by @var{name} is true for the @code{insn} currently being
7702scheduled.
7703
7704@var{name} is a string specifying one of a fixed set of flags to test.
7705Test the flags @code{forward} and @code{backward} to determine the
7706direction of a conditional branch.  Test the flags @code{very_likely},
7707@code{likely}, @code{very_unlikely}, and @code{unlikely} to determine
7708if a conditional branch is expected to be taken.
7709
7710If the @code{very_likely} flag is true, then the @code{likely} flag is also
7711true.  Likewise for the @code{very_unlikely} and @code{unlikely} flags.
7712
7713This example describes a conditional branch delay slot which
7714can be nullified for forward branches that are taken (annul-true) or
7715for backward branches which are not taken (annul-false).
7716
7717@smallexample
7718(define_delay (eq_attr "type" "cbranch")
7719  [(eq_attr "in_branch_delay" "true")
7720   (and (eq_attr "in_branch_delay" "true")
7721        (attr_flag "forward"))
7722   (and (eq_attr "in_branch_delay" "true")
7723        (attr_flag "backward"))])
7724@end smallexample
7725
7726The @code{forward} and @code{backward} flags are false if the current
7727@code{insn} being scheduled is not a conditional branch.
7728
7729The @code{very_likely} and @code{likely} flags are true if the
7730@code{insn} being scheduled is not a conditional branch.
7731The @code{very_unlikely} and @code{unlikely} flags are false if the
7732@code{insn} being scheduled is not a conditional branch.
7733
7734@code{attr_flag} is only used during delay slot scheduling and has no
7735meaning to other passes of the compiler.
7736
7737@findex attr
7738@item (attr @var{name})
7739The value of another attribute is returned.  This is most useful
7740for numeric attributes, as @code{eq_attr} and @code{attr_flag}
7741produce more efficient code for non-numeric attributes.
7742@end table
7743
7744@end ifset
7745@ifset INTERNALS
7746@node Tagging Insns
7747@subsection Assigning Attribute Values to Insns
7748@cindex tagging insns
7749@cindex assigning attribute values to insns
7750
7751The value assigned to an attribute of an insn is primarily determined by
7752which pattern is matched by that insn (or which @code{define_peephole}
7753generated it).  Every @code{define_insn} and @code{define_peephole} can
7754have an optional last argument to specify the values of attributes for
7755matching insns.  The value of any attribute not specified in a particular
7756insn is set to the default value for that attribute, as specified in its
7757@code{define_attr}.  Extensive use of default values for attributes
7758permits the specification of the values for only one or two attributes
7759in the definition of most insn patterns, as seen in the example in the
7760next section.
7761
7762The optional last argument of @code{define_insn} and
7763@code{define_peephole} is a vector of expressions, each of which defines
7764the value for a single attribute.  The most general way of assigning an
7765attribute's value is to use a @code{set} expression whose first operand is an
7766@code{attr} expression giving the name of the attribute being set.  The
7767second operand of the @code{set} is an attribute expression
7768(@pxref{Expressions}) giving the value of the attribute.
7769
7770When the attribute value depends on the @samp{alternative} attribute
7771(i.e., which is the applicable alternative in the constraint of the
7772insn), the @code{set_attr_alternative} expression can be used.  It
7773allows the specification of a vector of attribute expressions, one for
7774each alternative.
7775
7776@findex set_attr
7777When the generality of arbitrary attribute expressions is not required,
7778the simpler @code{set_attr} expression can be used, which allows
7779specifying a string giving either a single attribute value or a list
7780of attribute values, one for each alternative.
7781
7782The form of each of the above specifications is shown below.  In each case,
7783@var{name} is a string specifying the attribute to be set.
7784
7785@table @code
7786@item (set_attr @var{name} @var{value-string})
7787@var{value-string} is either a string giving the desired attribute value,
7788or a string containing a comma-separated list giving the values for
7789succeeding alternatives.  The number of elements must match the number
7790of alternatives in the constraint of the insn pattern.
7791
7792Note that it may be useful to specify @samp{*} for some alternative, in
7793which case the attribute will assume its default value for insns matching
7794that alternative.
7795
7796@findex set_attr_alternative
7797@item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
7798Depending on the alternative of the insn, the value will be one of the
7799specified values.  This is a shorthand for using a @code{cond} with
7800tests on the @samp{alternative} attribute.
7801
7802@findex attr
7803@item (set (attr @var{name}) @var{value})
7804The first operand of this @code{set} must be the special RTL expression
7805@code{attr}, whose sole operand is a string giving the name of the
7806attribute being set.  @var{value} is the value of the attribute.
7807@end table
7808
7809The following shows three different ways of representing the same
7810attribute value specification:
7811
7812@smallexample
7813(set_attr "type" "load,store,arith")
7814
7815(set_attr_alternative "type"
7816                      [(const_string "load") (const_string "store")
7817                       (const_string "arith")])
7818
7819(set (attr "type")
7820     (cond [(eq_attr "alternative" "1") (const_string "load")
7821            (eq_attr "alternative" "2") (const_string "store")]
7822           (const_string "arith")))
7823@end smallexample
7824
7825@need 1000
7826@findex define_asm_attributes
7827The @code{define_asm_attributes} expression provides a mechanism to
7828specify the attributes assigned to insns produced from an @code{asm}
7829statement.  It has the form:
7830
7831@smallexample
7832(define_asm_attributes [@var{attr-sets}])
7833@end smallexample
7834
7835@noindent
7836where @var{attr-sets} is specified the same as for both the
7837@code{define_insn} and the @code{define_peephole} expressions.
7838
7839These values will typically be the ``worst case'' attribute values.  For
7840example, they might indicate that the condition code will be clobbered.
7841
7842A specification for a @code{length} attribute is handled specially.  The
7843way to compute the length of an @code{asm} insn is to multiply the
7844length specified in the expression @code{define_asm_attributes} by the
7845number of machine instructions specified in the @code{asm} statement,
7846determined by counting the number of semicolons and newlines in the
7847string.  Therefore, the value of the @code{length} attribute specified
7848in a @code{define_asm_attributes} should be the maximum possible length
7849of a single machine instruction.
7850
7851@end ifset
7852@ifset INTERNALS
7853@node Attr Example
7854@subsection Example of Attribute Specifications
7855@cindex attribute specifications example
7856@cindex attribute specifications
7857
7858The judicious use of defaulting is important in the efficient use of
7859insn attributes.  Typically, insns are divided into @dfn{types} and an
7860attribute, customarily called @code{type}, is used to represent this
7861value.  This attribute is normally used only to define the default value
7862for other attributes.  An example will clarify this usage.
7863
7864Assume we have a RISC machine with a condition code and in which only
7865full-word operations are performed in registers.  Let us assume that we
7866can divide all insns into loads, stores, (integer) arithmetic
7867operations, floating point operations, and branches.
7868
7869Here we will concern ourselves with determining the effect of an insn on
7870the condition code and will limit ourselves to the following possible
7871effects:  The condition code can be set unpredictably (clobbered), not
7872be changed, be set to agree with the results of the operation, or only
7873changed if the item previously set into the condition code has been
7874modified.
7875
7876Here is part of a sample @file{md} file for such a machine:
7877
7878@smallexample
7879(define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
7880
7881(define_attr "cc" "clobber,unchanged,set,change0"
7882             (cond [(eq_attr "type" "load")
7883                        (const_string "change0")
7884                    (eq_attr "type" "store,branch")
7885                        (const_string "unchanged")
7886                    (eq_attr "type" "arith")
7887                        (if_then_else (match_operand:SI 0 "" "")
7888                                      (const_string "set")
7889                                      (const_string "clobber"))]
7890                   (const_string "clobber")))
7891
7892(define_insn ""
7893  [(set (match_operand:SI 0 "general_operand" "=r,r,m")
7894        (match_operand:SI 1 "general_operand" "r,m,r"))]
7895  ""
7896  "@@
7897   move %0,%1
7898   load %0,%1
7899   store %0,%1"
7900  [(set_attr "type" "arith,load,store")])
7901@end smallexample
7902
7903Note that we assume in the above example that arithmetic operations
7904performed on quantities smaller than a machine word clobber the condition
7905code since they will set the condition code to a value corresponding to the
7906full-word result.
7907
7908@end ifset
7909@ifset INTERNALS
7910@node Insn Lengths
7911@subsection Computing the Length of an Insn
7912@cindex insn lengths, computing
7913@cindex computing the length of an insn
7914
7915For many machines, multiple types of branch instructions are provided, each
7916for different length branch displacements.  In most cases, the assembler
7917will choose the correct instruction to use.  However, when the assembler
7918cannot do so, GCC can when a special attribute, the @code{length}
7919attribute, is defined.  This attribute must be defined to have numeric
7920values by specifying a null string in its @code{define_attr}.
7921
7922In the case of the @code{length} attribute, two additional forms of
7923arithmetic terms are allowed in test expressions:
7924
7925@table @code
7926@cindex @code{match_dup} and attributes
7927@item (match_dup @var{n})
7928This refers to the address of operand @var{n} of the current insn, which
7929must be a @code{label_ref}.
7930
7931@cindex @code{pc} and attributes
7932@item (pc)
7933This refers to the address of the @emph{current} insn.  It might have
7934been more consistent with other usage to make this the address of the
7935@emph{next} insn but this would be confusing because the length of the
7936current insn is to be computed.
7937@end table
7938
7939@cindex @code{addr_vec}, length of
7940@cindex @code{addr_diff_vec}, length of
7941For normal insns, the length will be determined by value of the
7942@code{length} attribute.  In the case of @code{addr_vec} and
7943@code{addr_diff_vec} insn patterns, the length is computed as
7944the number of vectors multiplied by the size of each vector.
7945
7946Lengths are measured in addressable storage units (bytes).
7947
7948The following macros can be used to refine the length computation:
7949
7950@table @code
7951@findex ADJUST_INSN_LENGTH
7952@item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
7953If defined, modifies the length assigned to instruction @var{insn} as a
7954function of the context in which it is used.  @var{length} is an lvalue
7955that contains the initially computed length of the insn and should be
7956updated with the correct length of the insn.
7957
7958This macro will normally not be required.  A case in which it is
7959required is the ROMP@.  On this machine, the size of an @code{addr_vec}
7960insn must be increased by two to compensate for the fact that alignment
7961may be required.
7962@end table
7963
7964@findex get_attr_length
7965The routine that returns @code{get_attr_length} (the value of the
7966@code{length} attribute) can be used by the output routine to
7967determine the form of the branch instruction to be written, as the
7968example below illustrates.
7969
7970As an example of the specification of variable-length branches, consider
7971the IBM 360.  If we adopt the convention that a register will be set to
7972the starting address of a function, we can jump to labels within 4k of
7973the start using a four-byte instruction.  Otherwise, we need a six-byte
7974sequence to load the address from memory and then branch to it.
7975
7976On such a machine, a pattern for a branch instruction might be specified
7977as follows:
7978
7979@smallexample
7980(define_insn "jump"
7981  [(set (pc)
7982        (label_ref (match_operand 0 "" "")))]
7983  ""
7984@{
7985   return (get_attr_length (insn) == 4
7986           ? "b %l0" : "l r15,=a(%l0); br r15");
7987@}
7988  [(set (attr "length")
7989        (if_then_else (lt (match_dup 0) (const_int 4096))
7990                      (const_int 4)
7991                      (const_int 6)))])
7992@end smallexample
7993
7994@end ifset
7995@ifset INTERNALS
7996@node Constant Attributes
7997@subsection Constant Attributes
7998@cindex constant attributes
7999
8000A special form of @code{define_attr}, where the expression for the
8001default value is a @code{const} expression, indicates an attribute that
8002is constant for a given run of the compiler.  Constant attributes may be
8003used to specify which variety of processor is used.  For example,
8004
8005@smallexample
8006(define_attr "cpu" "m88100,m88110,m88000"
8007 (const
8008  (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
8009         (symbol_ref "TARGET_88110") (const_string "m88110")]
8010        (const_string "m88000"))))
8011
8012(define_attr "memory" "fast,slow"
8013 (const
8014  (if_then_else (symbol_ref "TARGET_FAST_MEM")
8015                (const_string "fast")
8016                (const_string "slow"))))
8017@end smallexample
8018
8019The routine generated for constant attributes has no parameters as it
8020does not depend on any particular insn.  RTL expressions used to define
8021the value of a constant attribute may use the @code{symbol_ref} form,
8022but may not use either the @code{match_operand} form or @code{eq_attr}
8023forms involving insn attributes.
8024
8025@end ifset
8026@ifset INTERNALS
8027@node Delay Slots
8028@subsection Delay Slot Scheduling
8029@cindex delay slots, defining
8030
8031The insn attribute mechanism can be used to specify the requirements for
8032delay slots, if any, on a target machine.  An instruction is said to
8033require a @dfn{delay slot} if some instructions that are physically
8034after the instruction are executed as if they were located before it.
8035Classic examples are branch and call instructions, which often execute
8036the following instruction before the branch or call is performed.
8037
8038On some machines, conditional branch instructions can optionally
8039@dfn{annul} instructions in the delay slot.  This means that the
8040instruction will not be executed for certain branch outcomes.  Both
8041instructions that annul if the branch is true and instructions that
8042annul if the branch is false are supported.
8043
8044Delay slot scheduling differs from instruction scheduling in that
8045determining whether an instruction needs a delay slot is dependent only
8046on the type of instruction being generated, not on data flow between the
8047instructions.  See the next section for a discussion of data-dependent
8048instruction scheduling.
8049
8050@findex define_delay
8051The requirement of an insn needing one or more delay slots is indicated
8052via the @code{define_delay} expression.  It has the following form:
8053
8054@smallexample
8055(define_delay @var{test}
8056              [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
8057               @var{delay-2} @var{annul-true-2} @var{annul-false-2}
8058               @dots{}])
8059@end smallexample
8060
8061@var{test} is an attribute test that indicates whether this
8062@code{define_delay} applies to a particular insn.  If so, the number of
8063required delay slots is determined by the length of the vector specified
8064as the second argument.  An insn placed in delay slot @var{n} must
8065satisfy attribute test @var{delay-n}.  @var{annul-true-n} is an
8066attribute test that specifies which insns may be annulled if the branch
8067is true.  Similarly, @var{annul-false-n} specifies which insns in the
8068delay slot may be annulled if the branch is false.  If annulling is not
8069supported for that delay slot, @code{(nil)} should be coded.
8070
8071For example, in the common case where branch and call insns require
8072a single delay slot, which may contain any insn other than a branch or
8073call, the following would be placed in the @file{md} file:
8074
8075@smallexample
8076(define_delay (eq_attr "type" "branch,call")
8077              [(eq_attr "type" "!branch,call") (nil) (nil)])
8078@end smallexample
8079
8080Multiple @code{define_delay} expressions may be specified.  In this
8081case, each such expression specifies different delay slot requirements
8082and there must be no insn for which tests in two @code{define_delay}
8083expressions are both true.
8084
8085For example, if we have a machine that requires one delay slot for branches
8086but two for calls,  no delay slot can contain a branch or call insn,
8087and any valid insn in the delay slot for the branch can be annulled if the
8088branch is true, we might represent this as follows:
8089
8090@smallexample
8091(define_delay (eq_attr "type" "branch")
8092   [(eq_attr "type" "!branch,call")
8093    (eq_attr "type" "!branch,call")
8094    (nil)])
8095
8096(define_delay (eq_attr "type" "call")
8097              [(eq_attr "type" "!branch,call") (nil) (nil)
8098               (eq_attr "type" "!branch,call") (nil) (nil)])
8099@end smallexample
8100@c the above is *still* too long.  --mew 4feb93
8101
8102@end ifset
8103@ifset INTERNALS
8104@node Processor pipeline description
8105@subsection Specifying processor pipeline description
8106@cindex processor pipeline description
8107@cindex processor functional units
8108@cindex instruction latency time
8109@cindex interlock delays
8110@cindex data dependence delays
8111@cindex reservation delays
8112@cindex pipeline hazard recognizer
8113@cindex automaton based pipeline description
8114@cindex regular expressions
8115@cindex deterministic finite state automaton
8116@cindex automaton based scheduler
8117@cindex RISC
8118@cindex VLIW
8119
8120To achieve better performance, most modern processors
8121(super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
8122processors) have many @dfn{functional units} on which several
8123instructions can be executed simultaneously.  An instruction starts
8124execution if its issue conditions are satisfied.  If not, the
8125instruction is stalled until its conditions are satisfied.  Such
8126@dfn{interlock (pipeline) delay} causes interruption of the fetching
8127of successor instructions (or demands nop instructions, e.g.@: for some
8128MIPS processors).
8129
8130There are two major kinds of interlock delays in modern processors.
8131The first one is a data dependence delay determining @dfn{instruction
8132latency time}.  The instruction execution is not started until all
8133source data have been evaluated by prior instructions (there are more
8134complex cases when the instruction execution starts even when the data
8135are not available but will be ready in given time after the
8136instruction execution start).  Taking the data dependence delays into
8137account is simple.  The data dependence (true, output, and
8138anti-dependence) delay between two instructions is given by a
8139constant.  In most cases this approach is adequate.  The second kind
8140of interlock delays is a reservation delay.  The reservation delay
8141means that two instructions under execution will be in need of shared
8142processors resources, i.e.@: buses, internal registers, and/or
8143functional units, which are reserved for some time.  Taking this kind
8144of delay into account is complex especially for modern @acronym{RISC}
8145processors.
8146
8147The task of exploiting more processor parallelism is solved by an
8148instruction scheduler.  For a better solution to this problem, the
8149instruction scheduler has to have an adequate description of the
8150processor parallelism (or @dfn{pipeline description}).  GCC
8151machine descriptions describe processor parallelism and functional
8152unit reservations for groups of instructions with the aid of
8153@dfn{regular expressions}.
8154
8155The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
8156figure out the possibility of the instruction issue by the processor
8157on a given simulated processor cycle.  The pipeline hazard recognizer is
8158automatically generated from the processor pipeline description.  The
8159pipeline hazard recognizer generated from the machine description
8160is based on a deterministic finite state automaton (@acronym{DFA}):
8161the instruction issue is possible if there is a transition from one
8162automaton state to another one.  This algorithm is very fast, and
8163furthermore, its speed is not dependent on processor
8164complexity@footnote{However, the size of the automaton depends on
8165processor complexity.  To limit this effect, machine descriptions
8166can split orthogonal parts of the machine description among several
8167automata: but then, since each of these must be stepped independently,
8168this does cause a small decrease in the algorithm's performance.}.
8169
8170@cindex automaton based pipeline description
8171The rest of this section describes the directives that constitute
8172an automaton-based processor pipeline description.  The order of
8173these constructions within the machine description file is not
8174important.
8175
8176@findex define_automaton
8177@cindex pipeline hazard recognizer
8178The following optional construction describes names of automata
8179generated and used for the pipeline hazards recognition.  Sometimes
8180the generated finite state automaton used by the pipeline hazard
8181recognizer is large.  If we use more than one automaton and bind functional
8182units to the automata, the total size of the automata is usually
8183less than the size of the single automaton.  If there is no one such
8184construction, only one finite state automaton is generated.
8185
8186@smallexample
8187(define_automaton @var{automata-names})
8188@end smallexample
8189
8190@var{automata-names} is a string giving names of the automata.  The
8191names are separated by commas.  All the automata should have unique names.
8192The automaton name is used in the constructions @code{define_cpu_unit} and
8193@code{define_query_cpu_unit}.
8194
8195@findex define_cpu_unit
8196@cindex processor functional units
8197Each processor functional unit used in the description of instruction
8198reservations should be described by the following construction.
8199
8200@smallexample
8201(define_cpu_unit @var{unit-names} [@var{automaton-name}])
8202@end smallexample
8203
8204@var{unit-names} is a string giving the names of the functional units
8205separated by commas.  Don't use name @samp{nothing}, it is reserved
8206for other goals.
8207
8208@var{automaton-name} is a string giving the name of the automaton with
8209which the unit is bound.  The automaton should be described in
8210construction @code{define_automaton}.  You should give
8211@dfn{automaton-name}, if there is a defined automaton.
8212
8213The assignment of units to automata are constrained by the uses of the
8214units in insn reservations.  The most important constraint is: if a
8215unit reservation is present on a particular cycle of an alternative
8216for an insn reservation, then some unit from the same automaton must
8217be present on the same cycle for the other alternatives of the insn
8218reservation.  The rest of the constraints are mentioned in the
8219description of the subsequent constructions.
8220
8221@findex define_query_cpu_unit
8222@cindex querying function unit reservations
8223The following construction describes CPU functional units analogously
8224to @code{define_cpu_unit}.  The reservation of such units can be
8225queried for an automaton state.  The instruction scheduler never
8226queries reservation of functional units for given automaton state.  So
8227as a rule, you don't need this construction.  This construction could
8228be used for future code generation goals (e.g.@: to generate
8229@acronym{VLIW} insn templates).
8230
8231@smallexample
8232(define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
8233@end smallexample
8234
8235@var{unit-names} is a string giving names of the functional units
8236separated by commas.
8237
8238@var{automaton-name} is a string giving the name of the automaton with
8239which the unit is bound.
8240
8241@findex define_insn_reservation
8242@cindex instruction latency time
8243@cindex regular expressions
8244@cindex data bypass
8245The following construction is the major one to describe pipeline
8246characteristics of an instruction.
8247
8248@smallexample
8249(define_insn_reservation @var{insn-name} @var{default_latency}
8250                         @var{condition} @var{regexp})
8251@end smallexample
8252
8253@var{default_latency} is a number giving latency time of the
8254instruction.  There is an important difference between the old
8255description and the automaton based pipeline description.  The latency
8256time is used for all dependencies when we use the old description.  In
8257the automaton based pipeline description, the given latency time is only
8258used for true dependencies.  The cost of anti-dependencies is always
8259zero and the cost of output dependencies is the difference between
8260latency times of the producing and consuming insns (if the difference
8261is negative, the cost is considered to be zero).  You can always
8262change the default costs for any description by using the target hook
8263@code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
8264
8265@var{insn-name} is a string giving the internal name of the insn.  The
8266internal names are used in constructions @code{define_bypass} and in
8267the automaton description file generated for debugging.  The internal
8268name has nothing in common with the names in @code{define_insn}.  It is a
8269good practice to use insn classes described in the processor manual.
8270
8271@var{condition} defines what RTL insns are described by this
8272construction.  You should remember that you will be in trouble if
8273@var{condition} for two or more different
8274@code{define_insn_reservation} constructions is TRUE for an insn.  In
8275this case what reservation will be used for the insn is not defined.
8276Such cases are not checked during generation of the pipeline hazards
8277recognizer because in general recognizing that two conditions may have
8278the same value is quite difficult (especially if the conditions
8279contain @code{symbol_ref}).  It is also not checked during the
8280pipeline hazard recognizer work because it would slow down the
8281recognizer considerably.
8282
8283@var{regexp} is a string describing the reservation of the cpu's functional
8284units by the instruction.  The reservations are described by a regular
8285expression according to the following syntax:
8286
8287@smallexample
8288       regexp = regexp "," oneof
8289              | oneof
8290
8291       oneof = oneof "|" allof
8292             | allof
8293
8294       allof = allof "+" repeat
8295             | repeat
8296
8297       repeat = element "*" number
8298              | element
8299
8300       element = cpu_function_unit_name
8301               | reservation_name
8302               | result_name
8303               | "nothing"
8304               | "(" regexp ")"
8305@end smallexample
8306
8307@itemize @bullet
8308@item
8309@samp{,} is used for describing the start of the next cycle in
8310the reservation.
8311
8312@item
8313@samp{|} is used for describing a reservation described by the first
8314regular expression @strong{or} a reservation described by the second
8315regular expression @strong{or} etc.
8316
8317@item
8318@samp{+} is used for describing a reservation described by the first
8319regular expression @strong{and} a reservation described by the
8320second regular expression @strong{and} etc.
8321
8322@item
8323@samp{*} is used for convenience and simply means a sequence in which
8324the regular expression are repeated @var{number} times with cycle
8325advancing (see @samp{,}).
8326
8327@item
8328@samp{cpu_function_unit_name} denotes reservation of the named
8329functional unit.
8330
8331@item
8332@samp{reservation_name} --- see description of construction
8333@samp{define_reservation}.
8334
8335@item
8336@samp{nothing} denotes no unit reservations.
8337@end itemize
8338
8339@findex define_reservation
8340Sometimes unit reservations for different insns contain common parts.
8341In such case, you can simplify the pipeline description by describing
8342the common part by the following construction
8343
8344@smallexample
8345(define_reservation @var{reservation-name} @var{regexp})
8346@end smallexample
8347
8348@var{reservation-name} is a string giving name of @var{regexp}.
8349Functional unit names and reservation names are in the same name
8350space.  So the reservation names should be different from the
8351functional unit names and can not be the reserved name @samp{nothing}.
8352
8353@findex define_bypass
8354@cindex instruction latency time
8355@cindex data bypass
8356The following construction is used to describe exceptions in the
8357latency time for given instruction pair.  This is so called bypasses.
8358
8359@smallexample
8360(define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
8361               [@var{guard}])
8362@end smallexample
8363
8364@var{number} defines when the result generated by the instructions
8365given in string @var{out_insn_names} will be ready for the
8366instructions given in string @var{in_insn_names}.  Each of these
8367strings is a comma-separated list of filename-style globs and
8368they refer to the names of @code{define_insn_reservation}s.
8369For example:
8370@smallexample
8371(define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
8372@end smallexample
8373defines a bypass between instructions that start with
8374@samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
8375@samp{cpu1_load_}.
8376
8377@var{guard} is an optional string giving the name of a C function which
8378defines an additional guard for the bypass.  The function will get the
8379two insns as parameters.  If the function returns zero the bypass will
8380be ignored for this case.  The additional guard is necessary to
8381recognize complicated bypasses, e.g.@: when the consumer is only an address
8382of insn @samp{store} (not a stored value).
8383
8384If there are more one bypass with the same output and input insns, the
8385chosen bypass is the first bypass with a guard in description whose
8386guard function returns nonzero.  If there is no such bypass, then
8387bypass without the guard function is chosen.
8388
8389@findex exclusion_set
8390@findex presence_set
8391@findex final_presence_set
8392@findex absence_set
8393@findex final_absence_set
8394@cindex VLIW
8395@cindex RISC
8396The following five constructions are usually used to describe
8397@acronym{VLIW} processors, or more precisely, to describe a placement
8398of small instructions into @acronym{VLIW} instruction slots.  They
8399can be used for @acronym{RISC} processors, too.
8400
8401@smallexample
8402(exclusion_set @var{unit-names} @var{unit-names})
8403(presence_set @var{unit-names} @var{patterns})
8404(final_presence_set @var{unit-names} @var{patterns})
8405(absence_set @var{unit-names} @var{patterns})
8406(final_absence_set @var{unit-names} @var{patterns})
8407@end smallexample
8408
8409@var{unit-names} is a string giving names of functional units
8410separated by commas.
8411
8412@var{patterns} is a string giving patterns of functional units
8413separated by comma.  Currently pattern is one unit or units
8414separated by white-spaces.
8415
8416The first construction (@samp{exclusion_set}) means that each
8417functional unit in the first string can not be reserved simultaneously
8418with a unit whose name is in the second string and vice versa.  For
8419example, the construction is useful for describing processors
8420(e.g.@: some SPARC processors) with a fully pipelined floating point
8421functional unit which can execute simultaneously only single floating
8422point insns or only double floating point insns.
8423
8424The second construction (@samp{presence_set}) means that each
8425functional unit in the first string can not be reserved unless at
8426least one of pattern of units whose names are in the second string is
8427reserved.  This is an asymmetric relation.  For example, it is useful
8428for description that @acronym{VLIW} @samp{slot1} is reserved after
8429@samp{slot0} reservation.  We could describe it by the following
8430construction
8431
8432@smallexample
8433(presence_set "slot1" "slot0")
8434@end smallexample
8435
8436Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
8437reservation.  In this case we could write
8438
8439@smallexample
8440(presence_set "slot1" "slot0 b0")
8441@end smallexample
8442
8443The third construction (@samp{final_presence_set}) is analogous to
8444@samp{presence_set}.  The difference between them is when checking is
8445done.  When an instruction is issued in given automaton state
8446reflecting all current and planned unit reservations, the automaton
8447state is changed.  The first state is a source state, the second one
8448is a result state.  Checking for @samp{presence_set} is done on the
8449source state reservation, checking for @samp{final_presence_set} is
8450done on the result reservation.  This construction is useful to
8451describe a reservation which is actually two subsequent reservations.
8452For example, if we use
8453
8454@smallexample
8455(presence_set "slot1" "slot0")
8456@end smallexample
8457
8458the following insn will be never issued (because @samp{slot1} requires
8459@samp{slot0} which is absent in the source state).
8460
8461@smallexample
8462(define_reservation "insn_and_nop" "slot0 + slot1")
8463@end smallexample
8464
8465but it can be issued if we use analogous @samp{final_presence_set}.
8466
8467The forth construction (@samp{absence_set}) means that each functional
8468unit in the first string can be reserved only if each pattern of units
8469whose names are in the second string is not reserved.  This is an
8470asymmetric relation (actually @samp{exclusion_set} is analogous to
8471this one but it is symmetric).  For example it might be useful in a
8472@acronym{VLIW} description to say that @samp{slot0} cannot be reserved
8473after either @samp{slot1} or @samp{slot2} have been reserved.  This
8474can be described as:
8475
8476@smallexample
8477(absence_set "slot0" "slot1, slot2")
8478@end smallexample
8479
8480Or @samp{slot2} can not be reserved if @samp{slot0} and unit @samp{b0}
8481are reserved or @samp{slot1} and unit @samp{b1} are reserved.  In
8482this case we could write
8483
8484@smallexample
8485(absence_set "slot2" "slot0 b0, slot1 b1")
8486@end smallexample
8487
8488All functional units mentioned in a set should belong to the same
8489automaton.
8490
8491The last construction (@samp{final_absence_set}) is analogous to
8492@samp{absence_set} but checking is done on the result (state)
8493reservation.  See comments for @samp{final_presence_set}.
8494
8495@findex automata_option
8496@cindex deterministic finite state automaton
8497@cindex nondeterministic finite state automaton
8498@cindex finite state automaton minimization
8499You can control the generator of the pipeline hazard recognizer with
8500the following construction.
8501
8502@smallexample
8503(automata_option @var{options})
8504@end smallexample
8505
8506@var{options} is a string giving options which affect the generated
8507code.  Currently there are the following options:
8508
8509@itemize @bullet
8510@item
8511@dfn{no-minimization} makes no minimization of the automaton.  This is
8512only worth to do when we are debugging the description and need to
8513look more accurately at reservations of states.
8514
8515@item
8516@dfn{time} means printing time statistics about the generation of
8517automata.
8518
8519@item
8520@dfn{stats} means printing statistics about the generated automata
8521such as the number of DFA states, NDFA states and arcs.
8522
8523@item
8524@dfn{v} means a generation of the file describing the result automata.
8525The file has suffix @samp{.dfa} and can be used for the description
8526verification and debugging.
8527
8528@item
8529@dfn{w} means a generation of warning instead of error for
8530non-critical errors.
8531
8532@item
8533@dfn{no-comb-vect} prevents the automaton generator from generating
8534two data structures and comparing them for space efficiency.  Using
8535a comb vector to represent transitions may be better, but it can be
8536very expensive to construct.  This option is useful if the build
8537process spends an unacceptably long time in genautomata.
8538
8539@item
8540@dfn{ndfa} makes nondeterministic finite state automata.  This affects
8541the treatment of operator @samp{|} in the regular expressions.  The
8542usual treatment of the operator is to try the first alternative and,
8543if the reservation is not possible, the second alternative.  The
8544nondeterministic treatment means trying all alternatives, some of them
8545may be rejected by reservations in the subsequent insns.
8546
8547@item
8548@dfn{collapse-ndfa} modifies the behaviour of the generator when
8549producing an automaton.  An additional state transition to collapse a
8550nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
8551state is generated.  It can be triggered by passing @code{const0_rtx} to
8552state_transition.  In such an automaton, cycle advance transitions are
8553available only for these collapsed states.  This option is useful for
8554ports that want to use the @code{ndfa} option, but also want to use
8555@code{define_query_cpu_unit} to assign units to insns issued in a cycle.
8556
8557@item
8558@dfn{progress} means output of a progress bar showing how many states
8559were generated so far for automaton being processed.  This is useful
8560during debugging a @acronym{DFA} description.  If you see too many
8561generated states, you could interrupt the generator of the pipeline
8562hazard recognizer and try to figure out a reason for generation of the
8563huge automaton.
8564@end itemize
8565
8566As an example, consider a superscalar @acronym{RISC} machine which can
8567issue three insns (two integer insns and one floating point insn) on
8568the cycle but can finish only two insns.  To describe this, we define
8569the following functional units.
8570
8571@smallexample
8572(define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
8573(define_cpu_unit "port0, port1")
8574@end smallexample
8575
8576All simple integer insns can be executed in any integer pipeline and
8577their result is ready in two cycles.  The simple integer insns are
8578issued into the first pipeline unless it is reserved, otherwise they
8579are issued into the second pipeline.  Integer division and
8580multiplication insns can be executed only in the second integer
8581pipeline and their results are ready correspondingly in 8 and 4
8582cycles.  The integer division is not pipelined, i.e.@: the subsequent
8583integer division insn can not be issued until the current division
8584insn finished.  Floating point insns are fully pipelined and their
8585results are ready in 3 cycles.  Where the result of a floating point
8586insn is used by an integer insn, an additional delay of one cycle is
8587incurred.  To describe all of this we could specify
8588
8589@smallexample
8590(define_cpu_unit "div")
8591
8592(define_insn_reservation "simple" 2 (eq_attr "type" "int")
8593                         "(i0_pipeline | i1_pipeline), (port0 | port1)")
8594
8595(define_insn_reservation "mult" 4 (eq_attr "type" "mult")
8596                         "i1_pipeline, nothing*2, (port0 | port1)")
8597
8598(define_insn_reservation "div" 8 (eq_attr "type" "div")
8599                         "i1_pipeline, div*7, div + (port0 | port1)")
8600
8601(define_insn_reservation "float" 3 (eq_attr "type" "float")
8602                         "f_pipeline, nothing, (port0 | port1))
8603
8604(define_bypass 4 "float" "simple,mult,div")
8605@end smallexample
8606
8607To simplify the description we could describe the following reservation
8608
8609@smallexample
8610(define_reservation "finish" "port0|port1")
8611@end smallexample
8612
8613and use it in all @code{define_insn_reservation} as in the following
8614construction
8615
8616@smallexample
8617(define_insn_reservation "simple" 2 (eq_attr "type" "int")
8618                         "(i0_pipeline | i1_pipeline), finish")
8619@end smallexample
8620
8621
8622@end ifset
8623@ifset INTERNALS
8624@node Conditional Execution
8625@section Conditional Execution
8626@cindex conditional execution
8627@cindex predication
8628
8629A number of architectures provide for some form of conditional
8630execution, or predication.  The hallmark of this feature is the
8631ability to nullify most of the instructions in the instruction set.
8632When the instruction set is large and not entirely symmetric, it
8633can be quite tedious to describe these forms directly in the
8634@file{.md} file.  An alternative is the @code{define_cond_exec} template.
8635
8636@findex define_cond_exec
8637@smallexample
8638(define_cond_exec
8639  [@var{predicate-pattern}]
8640  "@var{condition}"
8641  "@var{output-template}")
8642@end smallexample
8643
8644@var{predicate-pattern} is the condition that must be true for the
8645insn to be executed at runtime and should match a relational operator.
8646One can use @code{match_operator} to match several relational operators
8647at once.  Any @code{match_operand} operands must have no more than one
8648alternative.
8649
8650@var{condition} is a C expression that must be true for the generated
8651pattern to match.
8652
8653@findex current_insn_predicate
8654@var{output-template} is a string similar to the @code{define_insn}
8655output template (@pxref{Output Template}), except that the @samp{*}
8656and @samp{@@} special cases do not apply.  This is only useful if the
8657assembly text for the predicate is a simple prefix to the main insn.
8658In order to handle the general case, there is a global variable
8659@code{current_insn_predicate} that will contain the entire predicate
8660if the current insn is predicated, and will otherwise be @code{NULL}.
8661
8662When @code{define_cond_exec} is used, an implicit reference to
8663the @code{predicable} instruction attribute is made.
8664@xref{Insn Attributes}.  This attribute must be a boolean (i.e.@: have
8665exactly two elements in its @var{list-of-values}), with the possible
8666values being @code{no} and @code{yes}.  The default and all uses in
8667the insns must be a simple constant, not a complex expressions.  It
8668may, however, depend on the alternative, by using a comma-separated
8669list of values.  If that is the case, the port should also define an
8670@code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
8671should also allow only @code{no} and @code{yes} as its values.
8672
8673For each @code{define_insn} for which the @code{predicable}
8674attribute is true, a new @code{define_insn} pattern will be
8675generated that matches a predicated version of the instruction.
8676For example,
8677
8678@smallexample
8679(define_insn "addsi"
8680  [(set (match_operand:SI 0 "register_operand" "r")
8681        (plus:SI (match_operand:SI 1 "register_operand" "r")
8682                 (match_operand:SI 2 "register_operand" "r")))]
8683  "@var{test1}"
8684  "add %2,%1,%0")
8685
8686(define_cond_exec
8687  [(ne (match_operand:CC 0 "register_operand" "c")
8688       (const_int 0))]
8689  "@var{test2}"
8690  "(%0)")
8691@end smallexample
8692
8693@noindent
8694generates a new pattern
8695
8696@smallexample
8697(define_insn ""
8698  [(cond_exec
8699     (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
8700     (set (match_operand:SI 0 "register_operand" "r")
8701          (plus:SI (match_operand:SI 1 "register_operand" "r")
8702                   (match_operand:SI 2 "register_operand" "r"))))]
8703  "(@var{test2}) && (@var{test1})"
8704  "(%3) add %2,%1,%0")
8705@end smallexample
8706
8707@end ifset
8708@ifset INTERNALS
8709@node Constant Definitions
8710@section Constant Definitions
8711@cindex constant definitions
8712@findex define_constants
8713
8714Using literal constants inside instruction patterns reduces legibility and
8715can be a maintenance problem.
8716
8717To overcome this problem, you may use the @code{define_constants}
8718expression.  It contains a vector of name-value pairs.  From that
8719point on, wherever any of the names appears in the MD file, it is as
8720if the corresponding value had been written instead.  You may use
8721@code{define_constants} multiple times; each appearance adds more
8722constants to the table.  It is an error to redefine a constant with
8723a different value.
8724
8725To come back to the a29k load multiple example, instead of
8726
8727@smallexample
8728(define_insn ""
8729  [(match_parallel 0 "load_multiple_operation"
8730     [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
8731           (match_operand:SI 2 "memory_operand" "m"))
8732      (use (reg:SI 179))
8733      (clobber (reg:SI 179))])]
8734  ""
8735  "loadm 0,0,%1,%2")
8736@end smallexample
8737
8738You could write:
8739
8740@smallexample
8741(define_constants [
8742    (R_BP 177)
8743    (R_FC 178)
8744    (R_CR 179)
8745    (R_Q  180)
8746])
8747
8748(define_insn ""
8749  [(match_parallel 0 "load_multiple_operation"
8750     [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
8751           (match_operand:SI 2 "memory_operand" "m"))
8752      (use (reg:SI R_CR))
8753      (clobber (reg:SI R_CR))])]
8754  ""
8755  "loadm 0,0,%1,%2")
8756@end smallexample
8757
8758The constants that are defined with a define_constant are also output
8759in the insn-codes.h header file as #defines.
8760
8761@cindex enumerations
8762@findex define_c_enum
8763You can also use the machine description file to define enumerations.
8764Like the constants defined by @code{define_constant}, these enumerations
8765are visible to both the machine description file and the main C code.
8766
8767The syntax is as follows:
8768
8769@smallexample
8770(define_c_enum "@var{name}" [
8771  @var{value0}
8772  @var{value1}
8773  @dots{}
8774  @var{valuen}
8775])
8776@end smallexample
8777
8778This definition causes the equivalent of the following C code to appear
8779in @file{insn-constants.h}:
8780
8781@smallexample
8782enum @var{name} @{
8783  @var{value0} = 0,
8784  @var{value1} = 1,
8785  @dots{}
8786  @var{valuen} = @var{n}
8787@};
8788#define NUM_@var{cname}_VALUES (@var{n} + 1)
8789@end smallexample
8790
8791where @var{cname} is the capitalized form of @var{name}.
8792It also makes each @var{valuei} available in the machine description
8793file, just as if it had been declared with:
8794
8795@smallexample
8796(define_constants [(@var{valuei} @var{i})])
8797@end smallexample
8798
8799Each @var{valuei} is usually an upper-case identifier and usually
8800begins with @var{cname}.
8801
8802You can split the enumeration definition into as many statements as
8803you like.  The above example is directly equivalent to:
8804
8805@smallexample
8806(define_c_enum "@var{name}" [@var{value0}])
8807(define_c_enum "@var{name}" [@var{value1}])
8808@dots{}
8809(define_c_enum "@var{name}" [@var{valuen}])
8810@end smallexample
8811
8812Splitting the enumeration helps to improve the modularity of each
8813individual @code{.md} file.  For example, if a port defines its
8814synchronization instructions in a separate @file{sync.md} file,
8815it is convenient to define all synchronization-specific enumeration
8816values in @file{sync.md} rather than in the main @file{.md} file.
8817
8818Some enumeration names have special significance to GCC:
8819
8820@table @code
8821@item unspecv
8822@findex unspec_volatile
8823If an enumeration called @code{unspecv} is defined, GCC will use it
8824when printing out @code{unspec_volatile} expressions.  For example:
8825
8826@smallexample
8827(define_c_enum "unspecv" [
8828  UNSPECV_BLOCKAGE
8829])
8830@end smallexample
8831
8832causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:
8833
8834@smallexample
8835(unspec_volatile ... UNSPECV_BLOCKAGE)
8836@end smallexample
8837
8838@item unspec
8839@findex unspec
8840If an enumeration called @code{unspec} is defined, GCC will use
8841it when printing out @code{unspec} expressions.  GCC will also use
8842it when printing out @code{unspec_volatile} expressions unless an
8843@code{unspecv} enumeration is also defined.  You can therefore
8844decide whether to keep separate enumerations for volatile and
8845non-volatile expressions or whether to use the same enumeration
8846for both.
8847@end table
8848
8849@findex define_enum
8850@anchor{define_enum}
8851Another way of defining an enumeration is to use @code{define_enum}:
8852
8853@smallexample
8854(define_enum "@var{name}" [
8855  @var{value0}
8856  @var{value1}
8857  @dots{}
8858  @var{valuen}
8859])
8860@end smallexample
8861
8862This directive implies:
8863
8864@smallexample
8865(define_c_enum "@var{name}" [
8866  @var{cname}_@var{cvalue0}
8867  @var{cname}_@var{cvalue1}
8868  @dots{}
8869  @var{cname}_@var{cvaluen}
8870])
8871@end smallexample
8872
8873@findex define_enum_attr
8874where @var{cvaluei} is the capitalized form of @var{valuei}.
8875However, unlike @code{define_c_enum}, the enumerations defined
8876by @code{define_enum} can be used in attribute specifications
8877(@pxref{define_enum_attr}).
8878@end ifset
8879@ifset INTERNALS
8880@node Iterators
8881@section Iterators
8882@cindex iterators in @file{.md} files
8883
8884Ports often need to define similar patterns for more than one machine
8885mode or for more than one rtx code.  GCC provides some simple iterator
8886facilities to make this process easier.
8887
8888@menu
8889* Mode Iterators::         Generating variations of patterns for different modes.
8890* Code Iterators::         Doing the same for codes.
8891@end menu
8892
8893@node Mode Iterators
8894@subsection Mode Iterators
8895@cindex mode iterators in @file{.md} files
8896
8897Ports often need to define similar patterns for two or more different modes.
8898For example:
8899
8900@itemize @bullet
8901@item
8902If a processor has hardware support for both single and double
8903floating-point arithmetic, the @code{SFmode} patterns tend to be
8904very similar to the @code{DFmode} ones.
8905
8906@item
8907If a port uses @code{SImode} pointers in one configuration and
8908@code{DImode} pointers in another, it will usually have very similar
8909@code{SImode} and @code{DImode} patterns for manipulating pointers.
8910@end itemize
8911
8912Mode iterators allow several patterns to be instantiated from one
8913@file{.md} file template.  They can be used with any type of
8914rtx-based construct, such as a @code{define_insn},
8915@code{define_split}, or @code{define_peephole2}.
8916
8917@menu
8918* Defining Mode Iterators:: Defining a new mode iterator.
8919* Substitutions::           Combining mode iterators with substitutions
8920* Examples::                Examples
8921@end menu
8922
8923@node Defining Mode Iterators
8924@subsubsection Defining Mode Iterators
8925@findex define_mode_iterator
8926
8927The syntax for defining a mode iterator is:
8928
8929@smallexample
8930(define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
8931@end smallexample
8932
8933This allows subsequent @file{.md} file constructs to use the mode suffix
8934@code{:@var{name}}.  Every construct that does so will be expanded
8935@var{n} times, once with every use of @code{:@var{name}} replaced by
8936@code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
8937and so on.  In the expansion for a particular @var{modei}, every
8938C condition will also require that @var{condi} be true.
8939
8940For example:
8941
8942@smallexample
8943(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
8944@end smallexample
8945
8946defines a new mode suffix @code{:P}.  Every construct that uses
8947@code{:P} will be expanded twice, once with every @code{:P} replaced
8948by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
8949The @code{:SI} version will only apply if @code{Pmode == SImode} and
8950the @code{:DI} version will only apply if @code{Pmode == DImode}.
8951
8952As with other @file{.md} conditions, an empty string is treated
8953as ``always true''.  @code{(@var{mode} "")} can also be abbreviated
8954to @code{@var{mode}}.  For example:
8955
8956@smallexample
8957(define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
8958@end smallexample
8959
8960means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
8961but that the @code{:SI} expansion has no such constraint.
8962
8963Iterators are applied in the order they are defined.  This can be
8964significant if two iterators are used in a construct that requires
8965substitutions.  @xref{Substitutions}.
8966
8967@node Substitutions
8968@subsubsection Substitution in Mode Iterators
8969@findex define_mode_attr
8970
8971If an @file{.md} file construct uses mode iterators, each version of the
8972construct will often need slightly different strings or modes.  For
8973example:
8974
8975@itemize @bullet
8976@item
8977When a @code{define_expand} defines several @code{add@var{m}3} patterns
8978(@pxref{Standard Names}), each expander will need to use the
8979appropriate mode name for @var{m}.
8980
8981@item
8982When a @code{define_insn} defines several instruction patterns,
8983each instruction will often use a different assembler mnemonic.
8984
8985@item
8986When a @code{define_insn} requires operands with different modes,
8987using an iterator for one of the operand modes usually requires a specific
8988mode for the other operand(s).
8989@end itemize
8990
8991GCC supports such variations through a system of ``mode attributes''.
8992There are two standard attributes: @code{mode}, which is the name of
8993the mode in lower case, and @code{MODE}, which is the same thing in
8994upper case.  You can define other attributes using:
8995
8996@smallexample
8997(define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
8998@end smallexample
8999
9000where @var{name} is the name of the attribute and @var{valuei}
9001is the value associated with @var{modei}.
9002
9003When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
9004each string and mode in the pattern for sequences of the form
9005@code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
9006mode attribute.  If the attribute is defined for @var{mode}, the whole
9007@code{<@dots{}>} sequence will be replaced by the appropriate attribute
9008value.
9009
9010For example, suppose an @file{.md} file has:
9011
9012@smallexample
9013(define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
9014(define_mode_attr load [(SI "lw") (DI "ld")])
9015@end smallexample
9016
9017If one of the patterns that uses @code{:P} contains the string
9018@code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
9019will use @code{"lw\t%0,%1"} and the @code{DI} version will use
9020@code{"ld\t%0,%1"}.
9021
9022Here is an example of using an attribute for a mode:
9023
9024@smallexample
9025(define_mode_iterator LONG [SI DI])
9026(define_mode_attr SHORT [(SI "HI") (DI "SI")])
9027(define_insn @dots{}
9028  (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
9029@end smallexample
9030
9031The @code{@var{iterator}:} prefix may be omitted, in which case the
9032substitution will be attempted for every iterator expansion.
9033
9034@node Examples
9035@subsubsection Mode Iterator Examples
9036
9037Here is an example from the MIPS port.  It defines the following
9038modes and attributes (among others):
9039
9040@smallexample
9041(define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
9042(define_mode_attr d [(SI "") (DI "d")])
9043@end smallexample
9044
9045and uses the following template to define both @code{subsi3}
9046and @code{subdi3}:
9047
9048@smallexample
9049(define_insn "sub<mode>3"
9050  [(set (match_operand:GPR 0 "register_operand" "=d")
9051        (minus:GPR (match_operand:GPR 1 "register_operand" "d")
9052                   (match_operand:GPR 2 "register_operand" "d")))]
9053  ""
9054  "<d>subu\t%0,%1,%2"
9055  [(set_attr "type" "arith")
9056   (set_attr "mode" "<MODE>")])
9057@end smallexample
9058
9059This is exactly equivalent to:
9060
9061@smallexample
9062(define_insn "subsi3"
9063  [(set (match_operand:SI 0 "register_operand" "=d")
9064        (minus:SI (match_operand:SI 1 "register_operand" "d")
9065                  (match_operand:SI 2 "register_operand" "d")))]
9066  ""
9067  "subu\t%0,%1,%2"
9068  [(set_attr "type" "arith")
9069   (set_attr "mode" "SI")])
9070
9071(define_insn "subdi3"
9072  [(set (match_operand:DI 0 "register_operand" "=d")
9073        (minus:DI (match_operand:DI 1 "register_operand" "d")
9074                  (match_operand:DI 2 "register_operand" "d")))]
9075  ""
9076  "dsubu\t%0,%1,%2"
9077  [(set_attr "type" "arith")
9078   (set_attr "mode" "DI")])
9079@end smallexample
9080
9081@node Code Iterators
9082@subsection Code Iterators
9083@cindex code iterators in @file{.md} files
9084@findex define_code_iterator
9085@findex define_code_attr
9086
9087Code iterators operate in a similar way to mode iterators.  @xref{Mode Iterators}.
9088
9089The construct:
9090
9091@smallexample
9092(define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
9093@end smallexample
9094
9095defines a pseudo rtx code @var{name} that can be instantiated as
9096@var{codei} if condition @var{condi} is true.  Each @var{codei}
9097must have the same rtx format.  @xref{RTL Classes}.
9098
9099As with mode iterators, each pattern that uses @var{name} will be
9100expanded @var{n} times, once with all uses of @var{name} replaced by
9101@var{code1}, once with all uses replaced by @var{code2}, and so on.
9102@xref{Defining Mode Iterators}.
9103
9104It is possible to define attributes for codes as well as for modes.
9105There are two standard code attributes: @code{code}, the name of the
9106code in lower case, and @code{CODE}, the name of the code in upper case.
9107Other attributes are defined using:
9108
9109@smallexample
9110(define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
9111@end smallexample
9112
9113Here's an example of code iterators in action, taken from the MIPS port:
9114
9115@smallexample
9116(define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
9117                                eq ne gt ge lt le gtu geu ltu leu])
9118
9119(define_expand "b<code>"
9120  [(set (pc)
9121        (if_then_else (any_cond:CC (cc0)
9122                                   (const_int 0))
9123                      (label_ref (match_operand 0 ""))
9124                      (pc)))]
9125  ""
9126@{
9127  gen_conditional_branch (operands, <CODE>);
9128  DONE;
9129@})
9130@end smallexample
9131
9132This is equivalent to:
9133
9134@smallexample
9135(define_expand "bunordered"
9136  [(set (pc)
9137        (if_then_else (unordered:CC (cc0)
9138                                    (const_int 0))
9139                      (label_ref (match_operand 0 ""))
9140                      (pc)))]
9141  ""
9142@{
9143  gen_conditional_branch (operands, UNORDERED);
9144  DONE;
9145@})
9146
9147(define_expand "bordered"
9148  [(set (pc)
9149        (if_then_else (ordered:CC (cc0)
9150                                  (const_int 0))
9151                      (label_ref (match_operand 0 ""))
9152                      (pc)))]
9153  ""
9154@{
9155  gen_conditional_branch (operands, ORDERED);
9156  DONE;
9157@})
9158
9159@dots{}
9160@end smallexample
9161
9162@end ifset
9163