tree-optimization/112450 - avoid AVX512 style masking for BImode masks
[official-gcc.git] / gcc / doc / md.texi
bloba5c1d1faf929e8e08a2704415d2a84e884f18cb1
1 @c Copyright (C) 1988-2023 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
5 @ifset INTERNALS
6 @node Machine Desc
7 @chapter Machine Descriptions
8 @cindex machine descriptions
10 A machine description has two parts: a file of instruction patterns
11 (@file{.md} file) and a C header file of macro definitions.
13 The @file{.md} file for a target machine contains a pattern for each
14 instruction that the target machine supports (or at least each instruction
15 that is worth telling the compiler about).  It may also contain comments.
16 A semicolon causes the rest of the line to be a comment, unless the semicolon
17 is inside a quoted string.
19 See the next chapter for information on the C header file.
21 @menu
22 * Overview::            How the machine description is used.
23 * Patterns::            How to write instruction patterns.
24 * Example::             An explained example of a @code{define_insn} pattern.
25 * RTL Template::        The RTL template defines what insns match a pattern.
26 * Output Template::     The output template says how to make assembler code
27                         from such an insn.
28 * Output Statement::    For more generality, write C code to output
29                         the assembler code.
30 * Compact Syntax::      Compact syntax for writing machine descriptors.
31 * Predicates::          Controlling what kinds of operands can be used
32                         for an insn.
33 * Constraints::         Fine-tuning operand selection.
34 * Standard Names::      Names mark patterns to use for code generation.
35 * Pattern Ordering::    When the order of patterns makes a difference.
36 * Dependent Patterns::  Having one pattern may make you need another.
37 * Jump Patterns::       Special considerations for patterns for jump insns.
38 * Looping Patterns::    How to define patterns for special looping insns.
39 * Insn Canonicalizations::Canonicalization of Instructions
40 * Expander Definitions::Generating a sequence of several RTL insns
41                         for a standard operation.
42 * Insn Splitting::      Splitting Instructions into Multiple Instructions.
43 * Including Patterns::  Including Patterns in Machine Descriptions.
44 * Peephole Definitions::Defining machine-specific peephole optimizations.
45 * Insn Attributes::     Specifying the value of attributes for generated insns.
46 * Conditional Execution::Generating @code{define_insn} patterns for
47                          predication.
48 * Define Subst::        Generating @code{define_insn} and @code{define_expand}
49                         patterns from other patterns.
50 * Constant Definitions::Defining symbolic constants that can be used in the
51                         md file.
52 * Iterators::           Using iterators to generate patterns from a template.
53 @end menu
55 @node Overview
56 @section Overview of How the Machine Description is Used
58 There are three main conversions that happen in the compiler:
60 @enumerate
62 @item
63 The front end reads the source code and builds a parse tree.
65 @item
66 The parse tree is used to generate an RTL insn list based on named
67 instruction patterns.
69 @item
70 The insn list is matched against the RTL templates to produce assembler
71 code.
73 @end enumerate
75 For the generate pass, only the names of the insns matter, from either a
76 named @code{define_insn} or a @code{define_expand}.  The compiler will
77 choose the pattern with the right name and apply the operands according
78 to the documentation later in this chapter, without regard for the RTL
79 template or operand constraints.  Note that the names the compiler looks
80 for are hard-coded in the compiler---it will ignore unnamed patterns and
81 patterns with names it doesn't know about, but if you don't provide a
82 named pattern it needs, it will abort.
84 If a @code{define_insn} is used, the template given is inserted into the
85 insn list.  If a @code{define_expand} is used, one of three things
86 happens, based on the condition logic.  The condition logic may manually
87 create new insns for the insn list, say via @code{emit_insn()}, and
88 invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
89 compiler to use an alternate way of performing that task.  If it invokes
90 neither @code{DONE} nor @code{FAIL}, the template given in the pattern
91 is inserted, as if the @code{define_expand} were a @code{define_insn}.
93 Once the insn list is generated, various optimization passes convert,
94 replace, and rearrange the insns in the insn list.  This is where the
95 @code{define_split} and @code{define_peephole} patterns get used, for
96 example.
98 Finally, the insn list's RTL is matched up with the RTL templates in the
99 @code{define_insn} patterns, and those patterns are used to emit the
100 final assembly code.  For this purpose, each named @code{define_insn}
101 acts like it's unnamed, since the names are ignored.
103 @node Patterns
104 @section Everything about Instruction Patterns
105 @cindex patterns
106 @cindex instruction patterns
108 @findex define_insn
109 A @code{define_insn} expression is used to define instruction patterns
110 to which insns may be matched.  A @code{define_insn} expression contains
111 an incomplete RTL expression, with pieces to be filled in later, operand
112 constraints that restrict how the pieces can be filled in, and an output
113 template or C code to generate the assembler output.
115 A @code{define_insn} is an RTL expression containing four or five operands:
117 @enumerate
118 @item
119 An optional name @var{n}.  When a name is present, the compiler
120 automically generates a C++ function @samp{gen_@var{n}} that takes
121 the operands of the instruction as arguments and returns the instruction's
122 rtx pattern.  The compiler also assigns the instruction a unique code
123 @samp{CODE_FOR_@var{n}}, with all such codes belonging to an enum
124 called @code{insn_code}.
126 These names serve one of two purposes.  The first is to indicate that the
127 instruction performs a certain standard job for the RTL-generation
128 pass of the compiler, such as a move, an addition, or a conditional
129 jump.  The second is to help the target generate certain target-specific
130 operations, such as when implementing target-specific intrinsic functions.
132 It is better to prefix target-specific names with the name of the
133 target, to avoid any clash with current or future standard names.
135 The absence of a name is indicated by writing an empty string
136 where the name should go.  Nameless instruction patterns are never
137 used for generating RTL code, but they may permit several simpler insns
138 to be combined later on.
140 For the purpose of debugging the compiler, you may also specify a
141 name beginning with the @samp{*} character.  Such a name is used only
142 for identifying the instruction in RTL dumps; it is equivalent to having
143 a nameless pattern for all other purposes.  Names beginning with the
144 @samp{*} character are not required to be unique.
146 The name may also have the form @samp{@@@var{n}}.  This has the same
147 effect as a name @samp{@var{n}}, but in addition tells the compiler to
148 generate further helper functions; see @ref{Parameterized Names} for details.
150 @item
151 The @dfn{RTL template}: This is a vector of incomplete RTL expressions
152 which describe the semantics of the instruction (@pxref{RTL Template}).
153 It is incomplete because it may contain @code{match_operand},
154 @code{match_operator}, and @code{match_dup} expressions that stand for
155 operands of the instruction.
157 If the vector has multiple elements, the RTL template is treated as a
158 @code{parallel} expression.
160 @cindex pattern conditions
161 @cindex conditions, in patterns
162 @item
163 The condition: This is a string which contains a C expression.  When the
164 compiler attempts to match RTL against a pattern, the condition is
165 evaluated.  If the condition evaluates to @code{true}, the match is
166 permitted.  The condition may be an empty string, which is treated
167 as always @code{true}.
169 @cindex named patterns and conditions
170 For a named pattern, the condition may not depend on the data in the
171 insn being matched, but only the target-machine-type flags.  The compiler
172 needs to test these conditions during initialization in order to learn
173 exactly which named instructions are available in a particular run.
175 @findex operands
176 For nameless patterns, the condition is applied only when matching an
177 individual insn, and only after the insn has matched the pattern's
178 recognition template.  The insn's operands may be found in the vector
179 @code{operands}.
181 An instruction condition cannot become more restrictive as compilation
182 progresses.  If the condition accepts a particular RTL instruction at
183 one stage of compilation, it must continue to accept that instruction
184 until the final pass.  For example, @samp{!reload_completed} and
185 @samp{can_create_pseudo_p ()} are both invalid instruction conditions,
186 because they are true during the earlier RTL passes and false during
187 the later ones.  For the same reason, if a condition accepts an
188 instruction before register allocation, it cannot later try to control
189 register allocation by excluding certain register or value combinations.
191 Although a condition cannot become more restrictive as compilation
192 progresses, the condition for a nameless pattern @emph{can} become
193 more permissive.  For example, a nameless instruction can require
194 @samp{reload_completed} to be true, in which case it only matches
195 after register allocation.
197 @item
198 The @dfn{output template} or @dfn{output statement}: This is either
199 a string, or a fragment of C code which returns a string.
201 When simple substitution isn't general enough, you can specify a piece
202 of C code to compute the output.  @xref{Output Statement}.
204 @item
205 The @dfn{insn attributes}: This is an optional vector containing the values of
206 attributes for insns matching this pattern (@pxref{Insn Attributes}).
207 @end enumerate
209 @node Example
210 @section Example of @code{define_insn}
211 @cindex @code{define_insn} example
213 Here is an example of an instruction pattern, taken from the machine
214 description for the 68000/68020.
216 @smallexample
217 (define_insn "tstsi"
218   [(set (cc0)
219         (match_operand:SI 0 "general_operand" "rm"))]
220   ""
221   "*
223   if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
224     return \"tstl %0\";
225   return \"cmpl #0,%0\";
226 @}")
227 @end smallexample
229 @noindent
230 This can also be written using braced strings:
232 @smallexample
233 (define_insn "tstsi"
234   [(set (cc0)
235         (match_operand:SI 0 "general_operand" "rm"))]
236   ""
238   if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
239     return "tstl %0";
240   return "cmpl #0,%0";
242 @end smallexample
244 This describes an instruction which sets the condition codes based on the
245 value of a general operand.  It has no condition, so any insn with an RTL
246 description of the form shown may be matched to this pattern.  The name
247 @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
248 generation pass that, when it is necessary to test such a value, an insn
249 to do so can be constructed using this pattern.
251 The output control string is a piece of C code which chooses which
252 output template to return based on the kind of operand and the specific
253 type of CPU for which code is being generated.
255 @samp{"rm"} is an operand constraint.  Its meaning is explained below.
257 @node RTL Template
258 @section RTL Template
259 @cindex RTL insn template
260 @cindex generating insns
261 @cindex insns, generating
262 @cindex recognizing insns
263 @cindex insns, recognizing
265 The RTL template is used to define which insns match the particular pattern
266 and how to find their operands.  For named patterns, the RTL template also
267 says how to construct an insn from specified operands.
269 Construction involves substituting specified operands into a copy of the
270 template.  Matching involves determining the values that serve as the
271 operands in the insn being matched.  Both of these activities are
272 controlled by special expression types that direct matching and
273 substitution of the operands.
275 @table @code
276 @findex match_operand
277 @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
278 This expression is a placeholder for operand number @var{n} of
279 the insn.  When constructing an insn, operand number @var{n}
280 will be substituted at this point.  When matching an insn, whatever
281 appears at this position in the insn will be taken as operand
282 number @var{n}; but it must satisfy @var{predicate} or this instruction
283 pattern will not match at all.
285 Operand numbers must be chosen consecutively counting from zero in
286 each instruction pattern.  There may be only one @code{match_operand}
287 expression in the pattern for each operand number.  Usually operands
288 are numbered in the order of appearance in @code{match_operand}
289 expressions.  In the case of a @code{define_expand}, any operand numbers
290 used only in @code{match_dup} expressions have higher values than all
291 other operand numbers.
293 @var{predicate} is a string that is the name of a function that
294 accepts two arguments, an expression and a machine mode.
295 @xref{Predicates}.  During matching, the function will be called with
296 the putative operand as the expression and @var{m} as the mode
297 argument (if @var{m} is not specified, @code{VOIDmode} will be used,
298 which normally causes @var{predicate} to accept any mode).  If it
299 returns zero, this instruction pattern fails to match.
300 @var{predicate} may be an empty string; then it means no test is to be
301 done on the operand, so anything which occurs in this position is
302 valid.
304 Most of the time, @var{predicate} will reject modes other than @var{m}---but
305 not always.  For example, the predicate @code{address_operand} uses
306 @var{m} as the mode of memory ref that the address should be valid for.
307 Many predicates accept @code{const_int} nodes even though their mode is
308 @code{VOIDmode}.
310 @var{constraint} controls reloading and the choice of the best register
311 class to use for a value, as explained later (@pxref{Constraints}).
312 If the constraint would be an empty string, it can be omitted.
314 People are often unclear on the difference between the constraint and the
315 predicate.  The predicate helps decide whether a given insn matches the
316 pattern.  The constraint plays no role in this decision; instead, it
317 controls various decisions in the case of an insn which does match.
319 @findex match_scratch
320 @item (match_scratch:@var{m} @var{n} @var{constraint})
321 This expression is also a placeholder for operand number @var{n}
322 and indicates that operand must be a @code{scratch} or @code{reg}
323 expression.
325 When matching patterns, this is equivalent to
327 @smallexample
328 (match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
329 @end smallexample
331 but, when generating RTL, it produces a (@code{scratch}:@var{m})
332 expression.
334 If the last few expressions in a @code{parallel} are @code{clobber}
335 expressions whose operands are either a hard register or
336 @code{match_scratch}, the combiner can add or delete them when
337 necessary.  @xref{Side Effects}.
339 @findex match_dup
340 @item (match_dup @var{n})
341 This expression is also a placeholder for operand number @var{n}.
342 It is used when the operand needs to appear more than once in the
343 insn.
345 In construction, @code{match_dup} acts just like @code{match_operand}:
346 the operand is substituted into the insn being constructed.  But in
347 matching, @code{match_dup} behaves differently.  It assumes that operand
348 number @var{n} has already been determined by a @code{match_operand}
349 appearing earlier in the recognition template, and it matches only an
350 identical-looking expression.
352 Note that @code{match_dup} should not be used to tell the compiler that
353 a particular register is being used for two operands (example:
354 @code{add} that adds one register to another; the second register is
355 both an input operand and the output operand).  Use a matching
356 constraint (@pxref{Simple Constraints}) for those.  @code{match_dup} is for the cases where one
357 operand is used in two places in the template, such as an instruction
358 that computes both a quotient and a remainder, where the opcode takes
359 two input operands but the RTL template has to refer to each of those
360 twice; once for the quotient pattern and once for the remainder pattern.
362 @findex match_operator
363 @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
364 This pattern is a kind of placeholder for a variable RTL expression
365 code.
367 When constructing an insn, it stands for an RTL expression whose
368 expression code is taken from that of operand @var{n}, and whose
369 operands are constructed from the patterns @var{operands}.
371 When matching an expression, it matches an expression if the function
372 @var{predicate} returns nonzero on that expression @emph{and} the
373 patterns @var{operands} match the operands of the expression.
375 Suppose that the function @code{commutative_operator} is defined as
376 follows, to match any expression whose operator is one of the
377 commutative arithmetic operators of RTL and whose mode is @var{mode}:
379 @smallexample
381 commutative_operator (x, mode)
382      rtx x;
383      machine_mode mode;
385   enum rtx_code code = GET_CODE (x);
386   if (GET_MODE (x) != mode)
387     return 0;
388   return (GET_RTX_CLASS (code) == RTX_COMM_ARITH
389           || code == EQ || code == NE);
391 @end smallexample
393 Then the following pattern will match any RTL expression consisting
394 of a commutative operator applied to two general operands:
396 @smallexample
397 (match_operator:SI 3 "commutative_operator"
398   [(match_operand:SI 1 "general_operand" "g")
399    (match_operand:SI 2 "general_operand" "g")])
400 @end smallexample
402 Here the vector @code{[@var{operands}@dots{}]} contains two patterns
403 because the expressions to be matched all contain two operands.
405 When this pattern does match, the two operands of the commutative
406 operator are recorded as operands 1 and 2 of the insn.  (This is done
407 by the two instances of @code{match_operand}.)  Operand 3 of the insn
408 will be the entire commutative expression: use @code{GET_CODE
409 (operands[3])} to see which commutative operator was used.
411 The machine mode @var{m} of @code{match_operator} works like that of
412 @code{match_operand}: it is passed as the second argument to the
413 predicate function, and that function is solely responsible for
414 deciding whether the expression to be matched ``has'' that mode.
416 When constructing an insn, argument 3 of the gen-function will specify
417 the operation (i.e.@: the expression code) for the expression to be
418 made.  It should be an RTL expression, whose expression code is copied
419 into a new expression whose operands are arguments 1 and 2 of the
420 gen-function.  The subexpressions of argument 3 are not used;
421 only its expression code matters.
423 When @code{match_operator} is used in a pattern for matching an insn,
424 it usually best if the operand number of the @code{match_operator}
425 is higher than that of the actual operands of the insn.  This improves
426 register allocation because the register allocator often looks at
427 operands 1 and 2 of insns to see if it can do register tying.
429 There is no way to specify constraints in @code{match_operator}.  The
430 operand of the insn which corresponds to the @code{match_operator}
431 never has any constraints because it is never reloaded as a whole.
432 However, if parts of its @var{operands} are matched by
433 @code{match_operand} patterns, those parts may have constraints of
434 their own.
436 @findex match_op_dup
437 @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
438 Like @code{match_dup}, except that it applies to operators instead of
439 operands.  When constructing an insn, operand number @var{n} will be
440 substituted at this point.  But in matching, @code{match_op_dup} behaves
441 differently.  It assumes that operand number @var{n} has already been
442 determined by a @code{match_operator} appearing earlier in the
443 recognition template, and it matches only an identical-looking
444 expression.
446 @findex match_parallel
447 @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
448 This pattern is a placeholder for an insn that consists of a
449 @code{parallel} expression with a variable number of elements.  This
450 expression should only appear at the top level of an insn pattern.
452 When constructing an insn, operand number @var{n} will be substituted at
453 this point.  When matching an insn, it matches if the body of the insn
454 is a @code{parallel} expression with at least as many elements as the
455 vector of @var{subpat} expressions in the @code{match_parallel}, if each
456 @var{subpat} matches the corresponding element of the @code{parallel},
457 @emph{and} the function @var{predicate} returns nonzero on the
458 @code{parallel} that is the body of the insn.  It is the responsibility
459 of the predicate to validate elements of the @code{parallel} beyond
460 those listed in the @code{match_parallel}.
462 A typical use of @code{match_parallel} is to match load and store
463 multiple expressions, which can contain a variable number of elements
464 in a @code{parallel}.  For example,
466 @smallexample
467 (define_insn ""
468   [(match_parallel 0 "load_multiple_operation"
469      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
470            (match_operand:SI 2 "memory_operand" "m"))
471       (use (reg:SI 179))
472       (clobber (reg:SI 179))])]
473   ""
474   "loadm 0,0,%1,%2")
475 @end smallexample
477 This example comes from @file{a29k.md}.  The function
478 @code{load_multiple_operation} is defined in @file{a29k.c} and checks
479 that subsequent elements in the @code{parallel} are the same as the
480 @code{set} in the pattern, except that they are referencing subsequent
481 registers and memory locations.
483 An insn that matches this pattern might look like:
485 @smallexample
486 (parallel
487  [(set (reg:SI 20) (mem:SI (reg:SI 100)))
488   (use (reg:SI 179))
489   (clobber (reg:SI 179))
490   (set (reg:SI 21)
491        (mem:SI (plus:SI (reg:SI 100)
492                         (const_int 4))))
493   (set (reg:SI 22)
494        (mem:SI (plus:SI (reg:SI 100)
495                         (const_int 8))))])
496 @end smallexample
498 @findex match_par_dup
499 @item (match_par_dup @var{n} [@var{subpat}@dots{}])
500 Like @code{match_op_dup}, but for @code{match_parallel} instead of
501 @code{match_operator}.
503 @end table
505 @node Output Template
506 @section Output Templates and Operand Substitution
507 @cindex output templates
508 @cindex operand substitution
510 @cindex @samp{%} in template
511 @cindex percent sign
512 The @dfn{output template} is a string which specifies how to output the
513 assembler code for an instruction pattern.  Most of the template is a
514 fixed string which is output literally.  The character @samp{%} is used
515 to specify where to substitute an operand; it can also be used to
516 identify places where different variants of the assembler require
517 different syntax.
519 In the simplest case, a @samp{%} followed by a digit @var{n} says to output
520 operand @var{n} at that point in the string.
522 @samp{%} followed by a letter and a digit says to output an operand in an
523 alternate fashion.  Four letters have standard, built-in meanings described
524 below.  The machine description macro @code{PRINT_OPERAND} can define
525 additional letters with nonstandard meanings.
527 @samp{%c@var{digit}} can be used to substitute an operand that is a
528 constant value without the syntax that normally indicates an immediate
529 operand.
531 @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
532 the constant is negated before printing.
534 @samp{%a@var{digit}} can be used to substitute an operand as if it were a
535 memory reference, with the actual operand treated as the address.  This may
536 be useful when outputting a ``load address'' instruction, because often the
537 assembler syntax for such an instruction requires you to write the operand
538 as if it were a memory reference.
540 @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
541 instruction.
543 @samp{%=} outputs a number which is unique to each instruction in the
544 entire compilation.  This is useful for making local labels to be
545 referred to more than once in a single template that generates multiple
546 assembler instructions.
548 @samp{%} followed by a punctuation character specifies a substitution that
549 does not use an operand.  Only one case is standard: @samp{%%} outputs a
550 @samp{%} into the assembler code.  Other nonstandard cases can be
551 defined in the @code{PRINT_OPERAND} macro.  You must also define
552 which punctuation characters are valid with the
553 @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
555 @cindex \
556 @cindex backslash
557 The template may generate multiple assembler instructions.  Write the text
558 for the instructions, with @samp{\;} between them.
560 @cindex matching operands
561 When the RTL contains two operands which are required by constraint to match
562 each other, the output template must refer only to the lower-numbered operand.
563 Matching operands are not always identical, and the rest of the compiler
564 arranges to put the proper RTL expression for printing into the lower-numbered
565 operand.
567 One use of nonstandard letters or punctuation following @samp{%} is to
568 distinguish between different assembler languages for the same machine; for
569 example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
570 requires periods in most opcode names, while MIT syntax does not.  For
571 example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
572 syntax.  The same file of patterns is used for both kinds of output syntax,
573 but the character sequence @samp{%.} is used in each place where Motorola
574 syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
575 defines the sequence to output a period; the macro for MIT syntax defines
576 it to do nothing.
578 @cindex @code{#} in template
579 As a special case, a template consisting of the single character @code{#}
580 instructs the compiler to first split the insn, and then output the
581 resulting instructions separately.  This helps eliminate redundancy in the
582 output templates.   If you have a @code{define_insn} that needs to emit
583 multiple assembler instructions, and there is a matching @code{define_split}
584 already defined, then you can simply use @code{#} as the output template
585 instead of writing an output template that emits the multiple assembler
586 instructions.
588 Note that @code{#} only has an effect while generating assembly code;
589 it does not affect whether a split occurs earlier.  An associated
590 @code{define_split} must exist and it must be suitable for use after
591 register allocation.
593 If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
594 of the form @samp{@{option0|option1|option2@}} in the templates.  These
595 describe multiple variants of assembler language syntax.
596 @xref{Instruction Output}.
598 @node Output Statement
599 @section C Statements for Assembler Output
600 @cindex output statements
601 @cindex C statements for assembler output
602 @cindex generating assembler output
604 Often a single fixed template string cannot produce correct and efficient
605 assembler code for all the cases that are recognized by a single
606 instruction pattern.  For example, the opcodes may depend on the kinds of
607 operands; or some unfortunate combinations of operands may require extra
608 machine instructions.
610 If the output control string starts with a @samp{@@}, then it is actually
611 a series of templates, each on a separate line.  (Blank lines and
612 leading spaces and tabs are ignored.)  The templates correspond to the
613 pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
614 if a target machine has a two-address add instruction @samp{addr} to add
615 into a register and another @samp{addm} to add a register to memory, you
616 might write this pattern:
618 @smallexample
619 (define_insn "addsi3"
620   [(set (match_operand:SI 0 "general_operand" "=r,m")
621         (plus:SI (match_operand:SI 1 "general_operand" "0,0")
622                  (match_operand:SI 2 "general_operand" "g,r")))]
623   ""
624   "@@
625    addr %2,%0
626    addm %2,%0")
627 @end smallexample
629 @cindex @code{*} in template
630 @cindex asterisk in template
631 If the output control string starts with a @samp{*}, then it is not an
632 output template but rather a piece of C program that should compute a
633 template.  It should execute a @code{return} statement to return the
634 template-string you want.  Most such templates use C string literals, which
635 require doublequote characters to delimit them.  To include these
636 doublequote characters in the string, prefix each one with @samp{\}.
638 If the output control string is written as a brace block instead of a
639 double-quoted string, it is automatically assumed to be C code.  In that
640 case, it is not necessary to put in a leading asterisk, or to escape the
641 doublequotes surrounding C string literals.
643 The operands may be found in the array @code{operands}, whose C data type
644 is @code{rtx []}.
646 It is very common to select different ways of generating assembler code
647 based on whether an immediate operand is within a certain range.  Be
648 careful when doing this, because the result of @code{INTVAL} is an
649 integer on the host machine.  If the host machine has more bits in an
650 @code{int} than the target machine has in the mode in which the constant
651 will be used, then some of the bits you get from @code{INTVAL} will be
652 superfluous.  For proper results, you must carefully disregard the
653 values of those bits.
655 @findex output_asm_insn
656 It is possible to output an assembler instruction and then go on to output
657 or compute more of them, using the subroutine @code{output_asm_insn}.  This
658 receives two arguments: a template-string and a vector of operands.  The
659 vector may be @code{operands}, or it may be another array of @code{rtx}
660 that you declare locally and initialize yourself.
662 @findex which_alternative
663 When an insn pattern has multiple alternatives in its constraints, often
664 the appearance of the assembler code is determined mostly by which alternative
665 was matched.  When this is so, the C code can test the variable
666 @code{which_alternative}, which is the ordinal number of the alternative
667 that was actually satisfied (0 for the first, 1 for the second alternative,
668 etc.).
670 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
671 for registers and @samp{clrmem} for memory locations.  Here is how
672 a pattern could use @code{which_alternative} to choose between them:
674 @smallexample
675 (define_insn ""
676   [(set (match_operand:SI 0 "general_operand" "=r,m")
677         (const_int 0))]
678   ""
679   @{
680   return (which_alternative == 0
681           ? "clrreg %0" : "clrmem %0");
682   @})
683 @end smallexample
685 The example above, where the assembler code to generate was
686 @emph{solely} determined by the alternative, could also have been specified
687 as follows, having the output control string start with a @samp{@@}:
689 @smallexample
690 @group
691 (define_insn ""
692   [(set (match_operand:SI 0 "general_operand" "=r,m")
693         (const_int 0))]
694   ""
695   "@@
696    clrreg %0
697    clrmem %0")
698 @end group
699 @end smallexample
701 If you just need a little bit of C code in one (or a few) alternatives,
702 you can use @samp{*} inside of a @samp{@@} multi-alternative template:
704 @smallexample
705 @group
706 (define_insn ""
707   [(set (match_operand:SI 0 "general_operand" "=r,<,m")
708         (const_int 0))]
709   ""
710   "@@
711    clrreg %0
712    * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\";
713    clrmem %0")
714 @end group
715 @end smallexample
717 @node Compact Syntax
718 @section Compact Syntax
719 @cindex compact syntax
721 When a @code{define_insn} or @code{define_insn_and_split} has multiple
722 alternatives it may be beneficial to use the compact syntax when specifying
723 alternatives.
725 This syntax puts the constraints and attributes on the same horizontal line as
726 the instruction assembly template.
728 As an example
730 @smallexample
731 @group
732 (define_insn_and_split ""
733   [(set (match_operand:SI 0 "nonimmediate_operand" "=r,k,r,r,r,r")
734         (match_operand:SI 1 "aarch64_mov_operand"  " r,r,k,M,n,Usv"))]
735   ""
736   "@@
737    mov\\t%w0, %w1
738    mov\\t%w0, %w1
739    mov\\t%w0, %w1
740    mov\\t%w0, %1
741    #
742    * return aarch64_output_sve_cnt_immediate ('cnt', '%x0', operands[1]);"
743   "&& true"
744    [(const_int 0)]
745   @{
746      aarch64_expand_mov_immediate (operands[0], operands[1]);
747      DONE;
748   @}
749   [(set_attr "type" "mov_reg,mov_reg,mov_reg,mov_imm,mov_imm,mov_imm")
750    (set_attr "arch"   "*,*,*,*,*,sve")
751    (set_attr "length" "4,4,4,4,*,  4")
754 @end group
755 @end smallexample
757 can be better expressed as:
759 @smallexample
760 @group
761 (define_insn_and_split ""
762   [(set (match_operand:SI 0 "nonimmediate_operand")
763         (match_operand:SI 1 "aarch64_mov_operand"))]
764   ""
765   @{@@ [cons: =0, 1; attrs: type, arch, length]
766      [r , r  ; mov_reg  , *   , 4] mov\t%w0, %w1
767      [k , r  ; mov_reg  , *   , 4] ^
768      [r , k  ; mov_reg  , *   , 4] ^
769      [r , M  ; mov_imm  , *   , 4] mov\t%w0, %1
770      [r , n  ; mov_imm  , *   , *] #
771      [r , Usv; mov_imm  , sve , 4] << aarch64_output_sve_cnt_immediate ("cnt", "%x0", operands[1]);
772   @}
773   "&& true"
774   [(const_int 0)]
775   @{
776     aarch64_expand_mov_immediate (operands[0], operands[1]);
777     DONE;
778   @}
780 @end group
781 @end smallexample
783 The syntax rules are as follows:
784 @itemize @bullet
785 @item
786 Templates must start with @samp{@{@@} to use the new syntax.
788 @item
789 @samp{@{@@} is followed by a layout in square brackets which is @samp{cons:}
790 followed by a comma-separated list of @code{match_operand}/@code{match_scratch}
791 operand numbers, then a semicolon, followed by the same for attributes
792 (@samp{attrs:}).  Operand modifiers like @code{=} and @code{+} can be placed
793 before an operand number.
794 Both sections are optional (so you can use only @samp{cons}, or only
795 @samp{attrs}, or both), and @samp{cons} must come before @samp{attrs} if
796 present.
798 @item
799 Each alternative begins with any amount of whitespace.
801 @item
802 Following the whitespace is a comma-separated list of "constraints" and/or
803 "attributes" within brackets @code{[]}, with sections separated by a semicolon.
805 @item
806 Should you want to copy the previous asm line, the symbol @code{^} can be used.
807 This allows less copy pasting between alternative and reduces the number of
808 lines to update on changes.
810 @item
811 When using C functions for output, the idiom @samp{* return @var{function};}
812 can be replaced with the shorthand @samp{<< @var{function};}.
814 @item
815 Following the closing @samp{]} is any amount of whitespace, and then the actual
816 asm output.
818 @item
819 Spaces are allowed in the list (they will simply be removed).
821 @item
822 All constraint alternatives should be specified.  For example, a list of
823 of three blank alternatives should be written @samp{[,,]} rather than
824 @samp{[]}.
826 @item
827 All attribute alternatives should be non-empty, with @samp{*}
828 representing the default attribute value.  For example, a list of three
829 default attribute values should be written @samp{[*,*,*]} rather than
830 @samp{[]}.
832 @item
833 Within an @samp{@{@@} block both multiline and singleline C comments are
834 allowed, but when used outside of a C block they must be the only non-whitespace
835 blocks on the line.
837 @item
838 Within an @samp{@{@@} block, any iterators that do not get expanded will result
839 in an error.  If for some reason it is required to have @code{<} or @code{>} in
840 the output then these must be escaped using @samp{\}.
842 @item
843 It is possible to use the @samp{attrs} list to specify some attributes and to
844 use the normal @code{set_attr} syntax to specify other attributes.  There must
845 not be any overlap between the two lists.
847 In other words, the following is valid:
848 @smallexample
849 @group
850 (define_insn_and_split ""
851   [(set (match_operand:SI 0 "nonimmediate_operand")
852         (match_operand:SI 1 "aarch64_mov_operand"))]
853   ""
854   @{@@ [cons: 0, 1; attrs: type, arch, length]@}
855   @dots{} 
856   [(set_attr "foo" "mov_imm")]
858 @end group
859 @end smallexample
861 but this is not valid:
862 @smallexample
863 @group
864 (define_insn_and_split ""
865   [(set (match_operand:SI 0 "nonimmediate_operand")
866         (match_operand:SI 1 "aarch64_mov_operand"))]
867   ""
868   @{@@ [cons: 0, 1; attrs: type, arch, length]@}
869   @dots{} 
870   [(set_attr "arch" "bar")
871    (set_attr "foo" "mov_imm")]
873 @end group
874 @end smallexample
876 because it specifies @code{arch} twice.
877 @end itemize
879 @node Predicates
880 @section Predicates
881 @cindex predicates
882 @cindex operand predicates
883 @cindex operator predicates
885 A predicate determines whether a @code{match_operand} or
886 @code{match_operator} expression matches, and therefore whether the
887 surrounding instruction pattern will be used for that combination of
888 operands.  GCC has a number of machine-independent predicates, and you
889 can define machine-specific predicates as needed.  By convention,
890 predicates used with @code{match_operand} have names that end in
891 @samp{_operand}, and those used with @code{match_operator} have names
892 that end in @samp{_operator}.
894 All predicates are boolean functions (in the mathematical sense) of
895 two arguments: the RTL expression that is being considered at that
896 position in the instruction pattern, and the machine mode that the
897 @code{match_operand} or @code{match_operator} specifies.  In this
898 section, the first argument is called @var{op} and the second argument
899 @var{mode}.  Predicates can be called from C as ordinary two-argument
900 functions; this can be useful in output templates or other
901 machine-specific code.
903 Operand predicates can allow operands that are not actually acceptable
904 to the hardware, as long as the constraints give reload the ability to
905 fix them up (@pxref{Constraints}).  However, GCC will usually generate
906 better code if the predicates specify the requirements of the machine
907 instructions as closely as possible.  Reload cannot fix up operands
908 that must be constants (``immediate operands''); you must use a
909 predicate that allows only constants, or else enforce the requirement
910 in the extra condition.
912 @cindex predicates and machine modes
913 @cindex normal predicates
914 @cindex special predicates
915 Most predicates handle their @var{mode} argument in a uniform manner.
916 If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
917 any mode.  If @var{mode} is anything else, then @var{op} must have the
918 same mode, unless @var{op} is a @code{CONST_INT} or integer
919 @code{CONST_DOUBLE}.  These RTL expressions always have
920 @code{VOIDmode}, so it would be counterproductive to check that their
921 mode matches.  Instead, predicates that accept @code{CONST_INT} and/or
922 integer @code{CONST_DOUBLE} check that the value stored in the
923 constant will fit in the requested mode.
925 Predicates with this behavior are called @dfn{normal}.
926 @command{genrecog} can optimize the instruction recognizer based on
927 knowledge of how normal predicates treat modes.  It can also diagnose
928 certain kinds of common errors in the use of normal predicates; for
929 instance, it is almost always an error to use a normal predicate
930 without specifying a mode.
932 Predicates that do something different with their @var{mode} argument
933 are called @dfn{special}.  The generic predicates
934 @code{address_operand} and @code{pmode_register_operand} are special
935 predicates.  @command{genrecog} does not do any optimizations or
936 diagnosis when special predicates are used.
938 @menu
939 * Machine-Independent Predicates::  Predicates available to all back ends.
940 * Defining Predicates::             How to write machine-specific predicate
941                                     functions.
942 @end menu
944 @node Machine-Independent Predicates
945 @subsection Machine-Independent Predicates
946 @cindex machine-independent predicates
947 @cindex generic predicates
949 These are the generic predicates available to all back ends.  They are
950 defined in @file{recog.cc}.  The first category of predicates allow
951 only constant, or @dfn{immediate}, operands.
953 @defun immediate_operand
954 This predicate allows any sort of constant that fits in @var{mode}.
955 It is an appropriate choice for instructions that take operands that
956 must be constant.
957 @end defun
959 @defun const_int_operand
960 This predicate allows any @code{CONST_INT} expression that fits in
961 @var{mode}.  It is an appropriate choice for an immediate operand that
962 does not allow a symbol or label.
963 @end defun
965 @defun const_double_operand
966 This predicate accepts any @code{CONST_DOUBLE} expression that has
967 exactly @var{mode}.  If @var{mode} is @code{VOIDmode}, it will also
968 accept @code{CONST_INT}.  It is intended for immediate floating point
969 constants.
970 @end defun
972 @noindent
973 The second category of predicates allow only some kind of machine
974 register.
976 @defun register_operand
977 This predicate allows any @code{REG} or @code{SUBREG} expression that
978 is valid for @var{mode}.  It is often suitable for arithmetic
979 instruction operands on a RISC machine.
980 @end defun
982 @defun pmode_register_operand
983 This is a slight variant on @code{register_operand} which works around
984 a limitation in the machine-description reader.
986 @smallexample
987 (match_operand @var{n} "pmode_register_operand" @var{constraint})
988 @end smallexample
990 @noindent
991 means exactly what
993 @smallexample
994 (match_operand:P @var{n} "register_operand" @var{constraint})
995 @end smallexample
997 @noindent
998 would mean, if the machine-description reader accepted @samp{:P}
999 mode suffixes.  Unfortunately, it cannot, because @code{Pmode} is an
1000 alias for some other mode, and might vary with machine-specific
1001 options.  @xref{Misc}.
1002 @end defun
1004 @defun scratch_operand
1005 This predicate allows hard registers and @code{SCRATCH} expressions,
1006 but not pseudo-registers.  It is used internally by @code{match_scratch};
1007 it should not be used directly.
1008 @end defun
1010 @noindent
1011 The third category of predicates allow only some kind of memory reference.
1013 @defun memory_operand
1014 This predicate allows any valid reference to a quantity of mode
1015 @var{mode} in memory, as determined by the weak form of
1016 @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
1017 @end defun
1019 @defun address_operand
1020 This predicate is a little unusual; it allows any operand that is a
1021 valid expression for the @emph{address} of a quantity of mode
1022 @var{mode}, again determined by the weak form of
1023 @code{GO_IF_LEGITIMATE_ADDRESS}.  To first order, if
1024 @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
1025 @code{memory_operand}, then @var{exp} is acceptable to
1026 @code{address_operand}.  Note that @var{exp} does not necessarily have
1027 the mode @var{mode}.
1028 @end defun
1030 @defun indirect_operand
1031 This is a stricter form of @code{memory_operand} which allows only
1032 memory references with a @code{general_operand} as the address
1033 expression.  New uses of this predicate are discouraged, because
1034 @code{general_operand} is very permissive, so it's hard to tell what
1035 an @code{indirect_operand} does or does not allow.  If a target has
1036 different requirements for memory operands for different instructions,
1037 it is better to define target-specific predicates which enforce the
1038 hardware's requirements explicitly.
1039 @end defun
1041 @defun push_operand
1042 This predicate allows a memory reference suitable for pushing a value
1043 onto the stack.  This will be a @code{MEM} which refers to
1044 @code{stack_pointer_rtx}, with a side effect in its address expression
1045 (@pxref{Incdec}); which one is determined by the
1046 @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
1047 @end defun
1049 @defun pop_operand
1050 This predicate allows a memory reference suitable for popping a value
1051 off the stack.  Again, this will be a @code{MEM} referring to
1052 @code{stack_pointer_rtx}, with a side effect in its address
1053 expression.  However, this time @code{STACK_POP_CODE} is expected.
1054 @end defun
1056 @noindent
1057 The fourth category of predicates allow some combination of the above
1058 operands.
1060 @defun nonmemory_operand
1061 This predicate allows any immediate or register operand valid for @var{mode}.
1062 @end defun
1064 @defun nonimmediate_operand
1065 This predicate allows any register or memory operand valid for @var{mode}.
1066 @end defun
1068 @defun general_operand
1069 This predicate allows any immediate, register, or memory operand
1070 valid for @var{mode}.
1071 @end defun
1073 @noindent
1074 Finally, there are two generic operator predicates.
1076 @defun comparison_operator
1077 This predicate matches any expression which performs an arithmetic
1078 comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the
1079 expression code.
1080 @end defun
1082 @defun ordered_comparison_operator
1083 This predicate matches any expression which performs an arithmetic
1084 comparison in @var{mode} and whose expression code is valid for integer
1085 modes; that is, the expression code will be one of @code{eq}, @code{ne},
1086 @code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu},
1087 @code{ge}, @code{geu}.
1088 @end defun
1090 @node Defining Predicates
1091 @subsection Defining Machine-Specific Predicates
1092 @cindex defining predicates
1093 @findex define_predicate
1094 @findex define_special_predicate
1096 Many machines have requirements for their operands that cannot be
1097 expressed precisely using the generic predicates.  You can define
1098 additional predicates using @code{define_predicate} and
1099 @code{define_special_predicate} expressions.  These expressions have
1100 three operands:
1102 @itemize @bullet
1103 @item
1104 The name of the predicate, as it will be referred to in
1105 @code{match_operand} or @code{match_operator} expressions.
1107 @item
1108 An RTL expression which evaluates to true if the predicate allows the
1109 operand @var{op}, false if it does not.  This expression can only use
1110 the following RTL codes:
1112 @table @code
1113 @item MATCH_OPERAND
1114 When written inside a predicate expression, a @code{MATCH_OPERAND}
1115 expression evaluates to true if the predicate it names would allow
1116 @var{op}.  The operand number and constraint are ignored.  Due to
1117 limitations in @command{genrecog}, you can only refer to generic
1118 predicates and predicates that have already been defined.
1120 @item MATCH_CODE
1121 This expression evaluates to true if @var{op} or a specified
1122 subexpression of @var{op} has one of a given list of RTX codes.
1124 The first operand of this expression is a string constant containing a
1125 comma-separated list of RTX code names (in lower case).  These are the
1126 codes for which the @code{MATCH_CODE} will be true.
1128 The second operand is a string constant which indicates what
1129 subexpression of @var{op} to examine.  If it is absent or the empty
1130 string, @var{op} itself is examined.  Otherwise, the string constant
1131 must be a sequence of digits and/or lowercase letters.  Each character
1132 indicates a subexpression to extract from the current expression; for
1133 the first character this is @var{op}, for the second and subsequent
1134 characters it is the result of the previous character.  A digit
1135 @var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
1136 extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
1137 alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on).  The
1138 @code{MATCH_CODE} then examines the RTX code of the subexpression
1139 extracted by the complete string.  It is not possible to extract
1140 components of an @code{rtvec} that is not at position 0 within its RTX
1141 object.
1143 @item MATCH_TEST
1144 This expression has one operand, a string constant containing a C
1145 expression.  The predicate's arguments, @var{op} and @var{mode}, are
1146 available with those names in the C expression.  The @code{MATCH_TEST}
1147 evaluates to true if the C expression evaluates to a nonzero value.
1148 @code{MATCH_TEST} expressions must not have side effects.
1150 @item  AND
1151 @itemx IOR
1152 @itemx NOT
1153 @itemx IF_THEN_ELSE
1154 The basic @samp{MATCH_} expressions can be combined using these
1155 logical operators, which have the semantics of the C operators
1156 @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively.  As
1157 in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
1158 arbitrary number of arguments; this has exactly the same effect as
1159 writing a chain of two-argument @code{AND} or @code{IOR} expressions.
1160 @end table
1162 @item
1163 An optional block of C code, which should execute
1164 @samp{@w{return true}} if the predicate is found to match and
1165 @samp{@w{return false}} if it does not.  It must not have any side
1166 effects.  The predicate arguments, @var{op} and @var{mode}, are
1167 available with those names.
1169 If a code block is present in a predicate definition, then the RTL
1170 expression must evaluate to true @emph{and} the code block must
1171 execute @samp{@w{return true}} for the predicate to allow the operand.
1172 The RTL expression is evaluated first; do not re-check anything in the
1173 code block that was checked in the RTL expression.
1174 @end itemize
1176 The program @command{genrecog} scans @code{define_predicate} and
1177 @code{define_special_predicate} expressions to determine which RTX
1178 codes are possibly allowed.  You should always make this explicit in
1179 the RTL predicate expression, using @code{MATCH_OPERAND} and
1180 @code{MATCH_CODE}.
1182 Here is an example of a simple predicate definition, from the IA64
1183 machine description:
1185 @smallexample
1186 @group
1187 ;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.}
1188 (define_predicate "small_addr_symbolic_operand"
1189   (and (match_code "symbol_ref")
1190        (match_test "SYMBOL_REF_SMALL_ADDR_P (op)")))
1191 @end group
1192 @end smallexample
1194 @noindent
1195 And here is another, showing the use of the C block.
1197 @smallexample
1198 @group
1199 ;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.}
1200 (define_predicate "gr_register_operand"
1201   (match_operand 0 "register_operand")
1203   unsigned int regno;
1204   if (GET_CODE (op) == SUBREG)
1205     op = SUBREG_REG (op);
1207   regno = REGNO (op);
1208   return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno));
1210 @end group
1211 @end smallexample
1213 Predicates written with @code{define_predicate} automatically include
1214 a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same
1215 mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
1216 @code{CONST_DOUBLE}.  They do @emph{not} check specifically for
1217 integer @code{CONST_DOUBLE}, nor do they test that the value of either
1218 kind of constant fits in the requested mode.  This is because
1219 target-specific predicates that take constants usually have to do more
1220 stringent value checks anyway.  If you need the exact same treatment
1221 of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
1222 provide, use a @code{MATCH_OPERAND} subexpression to call
1223 @code{const_int_operand}, @code{const_double_operand}, or
1224 @code{immediate_operand}.
1226 Predicates written with @code{define_special_predicate} do not get any
1227 automatic mode checks, and are treated as having special mode handling
1228 by @command{genrecog}.
1230 The program @command{genpreds} is responsible for generating code to
1231 test predicates.  It also writes a header file containing function
1232 declarations for all machine-specific predicates.  It is not necessary
1233 to declare these predicates in @file{@var{cpu}-protos.h}.
1234 @end ifset
1236 @c Most of this node appears by itself (in a different place) even
1237 @c when the INTERNALS flag is clear.  Passages that require the internals
1238 @c manual's context are conditionalized to appear only in the internals manual.
1239 @ifset INTERNALS
1240 @node Constraints
1241 @section Operand Constraints
1242 @cindex operand constraints
1243 @cindex constraints
1245 Each @code{match_operand} in an instruction pattern can specify
1246 constraints for the operands allowed.  The constraints allow you to
1247 fine-tune matching within the set of operands allowed by the
1248 predicate.
1250 @end ifset
1251 @ifclear INTERNALS
1252 @node Constraints
1253 @section Constraints for @code{asm} Operands
1254 @cindex operand constraints, @code{asm}
1255 @cindex constraints, @code{asm}
1256 @cindex @code{asm} constraints
1258 Here are specific details on what constraint letters you can use with
1259 @code{asm} operands.
1260 @end ifclear
1261 Constraints can say whether
1262 an operand may be in a register, and which kinds of register; whether the
1263 operand can be a memory reference, and which kinds of address; whether the
1264 operand may be an immediate constant, and which possible values it may
1265 have.  Constraints can also require two operands to match.
1266 Side-effects aren't allowed in operands of inline @code{asm}, unless
1267 @samp{<} or @samp{>} constraints are used, because there is no guarantee
1268 that the side effects will happen exactly once in an instruction that can update
1269 the addressing register.
1271 @ifset INTERNALS
1272 @menu
1273 * Simple Constraints::  Basic use of constraints.
1274 * Multi-Alternative::   When an insn has two alternative constraint-patterns.
1275 * Class Preferences::   Constraints guide which hard register to put things in.
1276 * Modifiers::           More precise control over effects of constraints.
1277 * Machine Constraints:: Existing constraints for some particular machines.
1278 * Disable Insn Alternatives:: Disable insn alternatives using attributes.
1279 * Define Constraints::  How to define machine-specific constraints.
1280 * C Constraint Interface:: How to test constraints from C code.
1281 @end menu
1282 @end ifset
1284 @ifclear INTERNALS
1285 @menu
1286 * Simple Constraints::  Basic use of constraints.
1287 * Multi-Alternative::   When an insn has two alternative constraint-patterns.
1288 * Modifiers::           More precise control over effects of constraints.
1289 * Machine Constraints:: Special constraints for some particular machines.
1290 @end menu
1291 @end ifclear
1293 @node Simple Constraints
1294 @subsection Simple Constraints
1295 @cindex simple constraints
1297 The simplest kind of constraint is a string full of letters, each of
1298 which describes one kind of operand that is permitted.  Here are
1299 the letters that are allowed:
1301 @table @asis
1302 @item whitespace
1303 Whitespace characters are ignored and can be inserted at any position
1304 except the first.  This enables each alternative for different operands to
1305 be visually aligned in the machine description even if they have different
1306 number of constraints and modifiers.
1308 @cindex @samp{m} in constraint
1309 @cindex memory references in constraints
1310 @item @samp{m}
1311 A memory operand is allowed, with any kind of address that the machine
1312 supports in general.
1313 Note that the letter used for the general memory constraint can be
1314 re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro.
1316 @cindex offsettable address
1317 @cindex @samp{o} in constraint
1318 @item @samp{o}
1319 A memory operand is allowed, but only if the address is
1320 @dfn{offsettable}.  This means that adding a small integer (actually,
1321 the width in bytes of the operand, as determined by its machine mode)
1322 may be added to the address and the result is also a valid memory
1323 address.
1325 @cindex autoincrement/decrement addressing
1326 For example, an address which is constant is offsettable; so is an
1327 address that is the sum of a register and a constant (as long as a
1328 slightly larger constant is also within the range of address-offsets
1329 supported by the machine); but an autoincrement or autodecrement
1330 address is not offsettable.  More complicated indirect/indexed
1331 addresses may or may not be offsettable depending on the other
1332 addressing modes that the machine supports.
1334 Note that in an output operand which can be matched by another
1335 operand, the constraint letter @samp{o} is valid only when accompanied
1336 by both @samp{<} (if the target machine has predecrement addressing)
1337 and @samp{>} (if the target machine has preincrement addressing).
1339 @cindex @samp{V} in constraint
1340 @item @samp{V}
1341 A memory operand that is not offsettable.  In other words, anything that
1342 would fit the @samp{m} constraint but not the @samp{o} constraint.
1344 @cindex @samp{<} in constraint
1345 @item @samp{<}
1346 A memory operand with autodecrement addressing (either predecrement or
1347 postdecrement) is allowed.  In inline @code{asm} this constraint is only
1348 allowed if the operand is used exactly once in an instruction that can
1349 handle the side effects.  Not using an operand with @samp{<} in constraint
1350 string in the inline @code{asm} pattern at all or using it in multiple
1351 instructions isn't valid, because the side effects wouldn't be performed
1352 or would be performed more than once.  Furthermore, on some targets
1353 the operand with @samp{<} in constraint string must be accompanied by
1354 special instruction suffixes like @code{%U0} instruction suffix on PowerPC
1355 or @code{%P0} on IA-64.
1357 @cindex @samp{>} in constraint
1358 @item @samp{>}
1359 A memory operand with autoincrement addressing (either preincrement or
1360 postincrement) is allowed.  In inline @code{asm} the same restrictions
1361 as for @samp{<} apply.
1363 @cindex @samp{r} in constraint
1364 @cindex registers in constraints
1365 @item @samp{r}
1366 A register operand is allowed provided that it is in a general
1367 register.
1369 @cindex constants in constraints
1370 @cindex @samp{i} in constraint
1371 @item @samp{i}
1372 An immediate integer operand (one with constant value) is allowed.
1373 This includes symbolic constants whose values will be known only at
1374 assembly time or later.
1376 @cindex @samp{n} in constraint
1377 @item @samp{n}
1378 An immediate integer operand with a known numeric value is allowed.
1379 Many systems cannot support assembly-time constants for operands less
1380 than a word wide.  Constraints for these operands should use @samp{n}
1381 rather than @samp{i}.
1383 @cindex @samp{I} in constraint
1384 @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
1385 Other letters in the range @samp{I} through @samp{P} may be defined in
1386 a machine-dependent fashion to permit immediate integer operands with
1387 explicit integer values in specified ranges.  For example, on the
1388 68000, @samp{I} is defined to stand for the range of values 1 to 8.
1389 This is the range permitted as a shift count in the shift
1390 instructions.
1392 @cindex @samp{E} in constraint
1393 @item @samp{E}
1394 An immediate floating operand (expression code @code{const_double}) is
1395 allowed, but only if the target floating point format is the same as
1396 that of the host machine (on which the compiler is running).
1398 @cindex @samp{F} in constraint
1399 @item @samp{F}
1400 An immediate floating operand (expression code @code{const_double} or
1401 @code{const_vector}) is allowed.
1403 @cindex @samp{G} in constraint
1404 @cindex @samp{H} in constraint
1405 @item @samp{G}, @samp{H}
1406 @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
1407 permit immediate floating operands in particular ranges of values.
1409 @cindex @samp{s} in constraint
1410 @item @samp{s}
1411 An immediate integer operand whose value is not an explicit integer is
1412 allowed.
1414 This might appear strange; if an insn allows a constant operand with a
1415 value not known at compile time, it certainly must allow any known
1416 value.  So why use @samp{s} instead of @samp{i}?  Sometimes it allows
1417 better code to be generated.
1419 For example, on the 68000 in a fullword instruction it is possible to
1420 use an immediate operand; but if the immediate value is between @minus{}128
1421 and 127, better code results from loading the value into a register and
1422 using the register.  This is because the load into the register can be
1423 done with a @samp{moveq} instruction.  We arrange for this to happen
1424 by defining the letter @samp{K} to mean ``any integer outside the
1425 range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
1426 constraints.
1428 @cindex @samp{g} in constraint
1429 @item @samp{g}
1430 Any register, memory or immediate integer operand is allowed, except for
1431 registers that are not general registers.
1433 @cindex @samp{X} in constraint
1434 @item @samp{X}
1435 @ifset INTERNALS
1436 Any operand whatsoever is allowed, even if it does not satisfy
1437 @code{general_operand}.  This is normally used in the constraint of
1438 a @code{match_scratch} when certain alternatives will not actually
1439 require a scratch register.
1440 @end ifset
1441 @ifclear INTERNALS
1442 Any operand whatsoever is allowed.
1443 @end ifclear
1445 @cindex @samp{0} in constraint
1446 @cindex digits in constraint
1447 @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
1448 An operand that matches the specified operand number is allowed.  If a
1449 digit is used together with letters within the same alternative, the
1450 digit should come last.
1452 This number is allowed to be more than a single digit.  If multiple
1453 digits are encountered consecutively, they are interpreted as a single
1454 decimal integer.  There is scant chance for ambiguity, since to-date
1455 it has never been desirable that @samp{10} be interpreted as matching
1456 either operand 1 @emph{or} operand 0.  Should this be desired, one
1457 can use multiple alternatives instead.
1459 @cindex matching constraint
1460 @cindex constraint, matching
1461 This is called a @dfn{matching constraint} and what it really means is
1462 that the assembler has only a single operand that fills two roles
1463 @ifset INTERNALS
1464 considered separate in the RTL insn.  For example, an add insn has two
1465 input operands and one output operand in the RTL, but on most CISC
1466 @end ifset
1467 @ifclear INTERNALS
1468 which @code{asm} distinguishes.  For example, an add instruction uses
1469 two input operands and an output operand, but on most CISC
1470 @end ifclear
1471 machines an add instruction really has only two operands, one of them an
1472 input-output operand:
1474 @smallexample
1475 addl #35,r12
1476 @end smallexample
1478 Matching constraints are used in these circumstances.
1479 More precisely, the two operands that match must include one input-only
1480 operand and one output-only operand.  Moreover, the digit must be a
1481 smaller number than the number of the operand that uses it in the
1482 constraint.
1484 @ifset INTERNALS
1485 For operands to match in a particular case usually means that they
1486 are identical-looking RTL expressions.  But in a few special cases
1487 specific kinds of dissimilarity are allowed.  For example, @code{*x}
1488 as an input operand will match @code{*x++} as an output operand.
1489 For proper results in such cases, the output template should always
1490 use the output-operand's number when printing the operand.
1491 @end ifset
1493 @cindex load address instruction
1494 @cindex push address instruction
1495 @cindex address constraints
1496 @cindex @samp{p} in constraint
1497 @item @samp{p}
1498 An operand that is a valid memory address is allowed.  This is
1499 for ``load address'' and ``push address'' instructions.
1501 @findex address_operand
1502 @samp{p} in the constraint must be accompanied by @code{address_operand}
1503 as the predicate in the @code{match_operand}.  This predicate interprets
1504 the mode specified in the @code{match_operand} as the mode of the memory
1505 reference for which the address would be valid.
1507 @cindex other register constraints
1508 @cindex extensible constraints
1509 @item @var{other-letters}
1510 Other letters can be defined in machine-dependent fashion to stand for
1511 particular classes of registers or other arbitrary operand types.
1512 @samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
1513 for data, address and floating point registers.
1514 @end table
1516 @ifset INTERNALS
1517 In order to have valid assembler code, each operand must satisfy
1518 its constraint.  But a failure to do so does not prevent the pattern
1519 from applying to an insn.  Instead, it directs the compiler to modify
1520 the code so that the constraint will be satisfied.  Usually this is
1521 done by copying an operand into a register.
1523 Contrast, therefore, the two instruction patterns that follow:
1525 @smallexample
1526 (define_insn ""
1527   [(set (match_operand:SI 0 "general_operand" "=r")
1528         (plus:SI (match_dup 0)
1529                  (match_operand:SI 1 "general_operand" "r")))]
1530   ""
1531   "@dots{}")
1532 @end smallexample
1534 @noindent
1535 which has two operands, one of which must appear in two places, and
1537 @smallexample
1538 (define_insn ""
1539   [(set (match_operand:SI 0 "general_operand" "=r")
1540         (plus:SI (match_operand:SI 1 "general_operand" "0")
1541                  (match_operand:SI 2 "general_operand" "r")))]
1542   ""
1543   "@dots{}")
1544 @end smallexample
1546 @noindent
1547 which has three operands, two of which are required by a constraint to be
1548 identical.  If we are considering an insn of the form
1550 @smallexample
1551 (insn @var{n} @var{prev} @var{next}
1552   (set (reg:SI 3)
1553        (plus:SI (reg:SI 6) (reg:SI 109)))
1554   @dots{})
1555 @end smallexample
1557 @noindent
1558 the first pattern would not apply at all, because this insn does not
1559 contain two identical subexpressions in the right place.  The pattern would
1560 say, ``That does not look like an add instruction; try other patterns''.
1561 The second pattern would say, ``Yes, that's an add instruction, but there
1562 is something wrong with it''.  It would direct the reload pass of the
1563 compiler to generate additional insns to make the constraint true.  The
1564 results might look like this:
1566 @smallexample
1567 (insn @var{n2} @var{prev} @var{n}
1568   (set (reg:SI 3) (reg:SI 6))
1569   @dots{})
1571 (insn @var{n} @var{n2} @var{next}
1572   (set (reg:SI 3)
1573        (plus:SI (reg:SI 3) (reg:SI 109)))
1574   @dots{})
1575 @end smallexample
1577 It is up to you to make sure that each operand, in each pattern, has
1578 constraints that can handle any RTL expression that could be present for
1579 that operand.  (When multiple alternatives are in use, each pattern must,
1580 for each possible combination of operand expressions, have at least one
1581 alternative which can handle that combination of operands.)  The
1582 constraints don't need to @emph{allow} any possible operand---when this is
1583 the case, they do not constrain---but they must at least point the way to
1584 reloading any possible operand so that it will fit.
1586 @itemize @bullet
1587 @item
1588 If the constraint accepts whatever operands the predicate permits,
1589 there is no problem: reloading is never necessary for this operand.
1591 For example, an operand whose constraints permit everything except
1592 registers is safe provided its predicate rejects registers.
1594 An operand whose predicate accepts only constant values is safe
1595 provided its constraints include the letter @samp{i}.  If any possible
1596 constant value is accepted, then nothing less than @samp{i} will do;
1597 if the predicate is more selective, then the constraints may also be
1598 more selective.
1600 @item
1601 Any operand expression can be reloaded by copying it into a register.
1602 So if an operand's constraints allow some kind of register, it is
1603 certain to be safe.  It need not permit all classes of registers; the
1604 compiler knows how to copy a register into another register of the
1605 proper class in order to make an instruction valid.
1607 @cindex nonoffsettable memory reference
1608 @cindex memory reference, nonoffsettable
1609 @item
1610 A nonoffsettable memory reference can be reloaded by copying the
1611 address into a register.  So if the constraint uses the letter
1612 @samp{o}, all memory references are taken care of.
1614 @item
1615 A constant operand can be reloaded by allocating space in memory to
1616 hold it as preinitialized data.  Then the memory reference can be used
1617 in place of the constant.  So if the constraint uses the letters
1618 @samp{o} or @samp{m}, constant operands are not a problem.
1620 @item
1621 If the constraint permits a constant and a pseudo register used in an insn
1622 was not allocated to a hard register and is equivalent to a constant,
1623 the register will be replaced with the constant.  If the predicate does
1624 not permit a constant and the insn is re-recognized for some reason, the
1625 compiler will crash.  Thus the predicate must always recognize any
1626 objects allowed by the constraint.
1627 @end itemize
1629 If the operand's predicate can recognize registers, but the constraint does
1630 not permit them, it can make the compiler crash.  When this operand happens
1631 to be a register, the reload pass will be stymied, because it does not know
1632 how to copy a register temporarily into memory.
1634 If the predicate accepts a unary operator, the constraint applies to the
1635 operand.  For example, the MIPS processor at ISA level 3 supports an
1636 instruction which adds two registers in @code{SImode} to produce a
1637 @code{DImode} result, but only if the registers are correctly sign
1638 extended.  This predicate for the input operands accepts a
1639 @code{sign_extend} of an @code{SImode} register.  Write the constraint
1640 to indicate the type of register that is required for the operand of the
1641 @code{sign_extend}.
1642 @end ifset
1644 @node Multi-Alternative
1645 @subsection Multiple Alternative Constraints
1646 @cindex multiple alternative constraints
1648 Sometimes a single instruction has multiple alternative sets of possible
1649 operands.  For example, on the 68000, a logical-or instruction can combine
1650 register or an immediate value into memory, or it can combine any kind of
1651 operand into a register; but it cannot combine one memory location into
1652 another.
1654 These constraints are represented as multiple alternatives.  An alternative
1655 can be described by a series of letters for each operand.  The overall
1656 constraint for an operand is made from the letters for this operand
1657 from the first alternative, a comma, the letters for this operand from
1658 the second alternative, a comma, and so on until the last alternative.
1659 All operands for a single instruction must have the same number of 
1660 alternatives.
1661 @ifset INTERNALS
1662 Here is how it is done for fullword logical-or on the 68000:
1664 @smallexample
1665 (define_insn "iorsi3"
1666   [(set (match_operand:SI 0 "general_operand" "=m,d")
1667         (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1668                 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1669   @dots{})
1670 @end smallexample
1672 The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1673 operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
1674 2.  The second alternative has @samp{d} (data register) for operand 0,
1675 @samp{0} for operand 1, and @samp{dmKs} for operand 2.  The @samp{=} and
1676 @samp{%} in the constraints apply to all the alternatives; their
1677 meaning is explained in a later section (@pxref{Modifiers}).
1679 If all the operands fit any one alternative, the instruction is valid.
1680 Otherwise, for each alternative, the compiler counts how many instructions
1681 must be added to copy the operands so that that alternative applies.
1682 The alternative requiring the least copying is chosen.  If two alternatives
1683 need the same amount of copying, the one that comes first is chosen.
1684 These choices can be altered with the @samp{?} and @samp{!} characters:
1686 @table @code
1687 @cindex @samp{?} in constraint
1688 @cindex question mark
1689 @item ?
1690 Disparage slightly the alternative that the @samp{?} appears in,
1691 as a choice when no alternative applies exactly.  The compiler regards
1692 this alternative as one unit more costly for each @samp{?} that appears
1693 in it.
1695 @cindex @samp{!} in constraint
1696 @cindex exclamation point
1697 @item !
1698 Disparage severely the alternative that the @samp{!} appears in.
1699 This alternative can still be used if it fits without reloading,
1700 but if reloading is needed, some other alternative will be used.
1702 @cindex @samp{^} in constraint
1703 @cindex caret
1704 @item ^
1705 This constraint is analogous to @samp{?} but it disparages slightly
1706 the alternative only if the operand with the @samp{^} needs a reload.
1708 @cindex @samp{$} in constraint
1709 @cindex dollar sign
1710 @item $
1711 This constraint is analogous to @samp{!} but it disparages severely
1712 the alternative only if the operand with the @samp{$} needs a reload.
1713 @end table
1715 When an insn pattern has multiple alternatives in its constraints, often
1716 the appearance of the assembler code is determined mostly by which
1717 alternative was matched.  When this is so, the C code for writing the
1718 assembler code can use the variable @code{which_alternative}, which is
1719 the ordinal number of the alternative that was actually satisfied (0 for
1720 the first, 1 for the second alternative, etc.).  @xref{Output Statement}.
1721 @end ifset
1722 @ifclear INTERNALS
1724 So the first alternative for the 68000's logical-or could be written as 
1725 @code{"+m" (output) : "ir" (input)}.  The second could be @code{"+r" 
1726 (output): "irm" (input)}.  However, the fact that two memory locations 
1727 cannot be used in a single instruction prevents simply using @code{"+rm" 
1728 (output) : "irm" (input)}.  Using multi-alternatives, this might be 
1729 written as @code{"+m,r" (output) : "ir,irm" (input)}.  This describes
1730 all the available alternatives to the compiler, allowing it to choose 
1731 the most efficient one for the current conditions.
1733 There is no way within the template to determine which alternative was 
1734 chosen.  However you may be able to wrap your @code{asm} statements with 
1735 builtins such as @code{__builtin_constant_p} to achieve the desired results.
1736 @end ifclear
1738 @ifset INTERNALS
1739 @node Class Preferences
1740 @subsection Register Class Preferences
1741 @cindex class preference constraints
1742 @cindex register class preference constraints
1744 @cindex voting between constraint alternatives
1745 The operand constraints have another function: they enable the compiler
1746 to decide which kind of hardware register a pseudo register is best
1747 allocated to.  The compiler examines the constraints that apply to the
1748 insns that use the pseudo register, looking for the machine-dependent
1749 letters such as @samp{d} and @samp{a} that specify classes of registers.
1750 The pseudo register is put in whichever class gets the most ``votes''.
1751 The constraint letters @samp{g} and @samp{r} also vote: they vote in
1752 favor of a general register.  The machine description says which registers
1753 are considered general.
1755 Of course, on some machines all registers are equivalent, and no register
1756 classes are defined.  Then none of this complexity is relevant.
1757 @end ifset
1759 @node Modifiers
1760 @subsection Constraint Modifier Characters
1761 @cindex modifiers in constraints
1762 @cindex constraint modifier characters
1764 @c prevent bad page break with this line
1765 Here are constraint modifier characters.
1767 @table @samp
1768 @cindex @samp{=} in constraint
1769 @item =
1770 Means that this operand is written to by this instruction:
1771 the previous value is discarded and replaced by new data.
1773 @cindex @samp{+} in constraint
1774 @item +
1775 Means that this operand is both read and written by the instruction.
1777 When the compiler fixes up the operands to satisfy the constraints,
1778 it needs to know which operands are read by the instruction and
1779 which are written by it.  @samp{=} identifies an operand which is only
1780 written; @samp{+} identifies an operand that is both read and written; all
1781 other operands are assumed to only be read.
1783 If you specify @samp{=} or @samp{+} in a constraint, you put it in the
1784 first character of the constraint string.
1786 @cindex @samp{&} in constraint
1787 @cindex earlyclobber operand
1788 @item &
1789 Means (in a particular alternative) that this operand is an
1790 @dfn{earlyclobber} operand, which is written before the instruction is
1791 finished using the input operands.  Therefore, this operand may not lie
1792 in a register that is read by the instruction or as part of any memory
1793 address.
1795 @samp{&} applies only to the alternative in which it is written.  In
1796 constraints with multiple alternatives, sometimes one alternative
1797 requires @samp{&} while others do not.  See, for example, the
1798 @samp{movdf} insn of the 68000.
1800 An operand which is read by the instruction can be tied to an earlyclobber
1801 operand if its only use as an input occurs before the early result is
1802 written.  Adding alternatives of this form often allows GCC to produce
1803 better code when only some of the read operands can be affected by the
1804 earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@.
1806 Furthermore, if the @dfn{earlyclobber} operand is also a read/write
1807 operand, then that operand is written only after it's used.
1809 @samp{&} does not obviate the need to write @samp{=} or @samp{+}.  As
1810 @dfn{earlyclobber} operands are always written, a read-only
1811 @dfn{earlyclobber} operand is ill-formed and will be rejected by the
1812 compiler.
1814 @cindex @samp{%} in constraint
1815 @item %
1816 Declares the instruction to be commutative for this operand and the
1817 following operand.  This means that the compiler may interchange the
1818 two operands if that is the cheapest way to make all operands fit the
1819 constraints.  @samp{%} applies to all alternatives and must appear as
1820 the first character in the constraint.  Only read-only operands can use
1821 @samp{%}.
1823 @ifset INTERNALS
1824 This is often used in patterns for addition instructions
1825 that really have only two operands: the result must go in one of the
1826 arguments.  Here for example, is how the 68000 halfword-add
1827 instruction is defined:
1829 @smallexample
1830 (define_insn "addhi3"
1831   [(set (match_operand:HI 0 "general_operand" "=m,r")
1832      (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1833               (match_operand:HI 2 "general_operand" "di,g")))]
1834   @dots{})
1835 @end smallexample
1836 @end ifset
1837 GCC can only handle one commutative pair in an asm; if you use more,
1838 the compiler may fail.  Note that you need not use the modifier if
1839 the two alternatives are strictly identical; this would only waste
1840 time in the reload pass.
1841 @ifset INTERNALS
1842 The modifier is not operational after
1843 register allocation, so the result of @code{define_peephole2}
1844 and @code{define_split}s performed after reload cannot rely on
1845 @samp{%} to make the intended insn match.
1847 @cindex @samp{#} in constraint
1848 @item #
1849 Says that all following characters, up to the next comma, are to be
1850 ignored as a constraint.  They are significant only for choosing
1851 register preferences.
1853 @cindex @samp{*} in constraint
1854 @item *
1855 Says that the following character should be ignored when choosing
1856 register preferences.  @samp{*} has no effect on the meaning of the
1857 constraint as a constraint, and no effect on reloading.  For LRA
1858 @samp{*} additionally disparages slightly the alternative if the
1859 following character matches the operand.
1861 Here is an example: the 68000 has an instruction to sign-extend a
1862 halfword in a data register, and can also sign-extend a value by
1863 copying it into an address register.  While either kind of register is
1864 acceptable, the constraints on an address-register destination are
1865 less strict, so it is best if register allocation makes an address
1866 register its goal.  Therefore, @samp{*} is used so that the @samp{d}
1867 constraint letter (for data register) is ignored when computing
1868 register preferences.
1870 @smallexample
1871 (define_insn "extendhisi2"
1872   [(set (match_operand:SI 0 "general_operand" "=*d,a")
1873         (sign_extend:SI
1874          (match_operand:HI 1 "general_operand" "0,g")))]
1875   @dots{})
1876 @end smallexample
1877 @end ifset
1878 @end table
1880 @node Machine Constraints
1881 @subsection Constraints for Particular Machines
1882 @cindex machine specific constraints
1883 @cindex constraints, machine specific
1885 Whenever possible, you should use the general-purpose constraint letters
1886 in @code{asm} arguments, since they will convey meaning more readily to
1887 people reading your code.  Failing that, use the constraint letters
1888 that usually have very similar meanings across architectures.  The most
1889 commonly used constraints are @samp{m} and @samp{r} (for memory and
1890 general-purpose registers respectively; @pxref{Simple Constraints}), and
1891 @samp{I}, usually the letter indicating the most common
1892 immediate-constant format.
1894 Each architecture defines additional constraints.  These constraints
1895 are used by the compiler itself for instruction generation, as well as
1896 for @code{asm} statements; therefore, some of the constraints are not
1897 particularly useful for @code{asm}.  Here is a summary of some of the
1898 machine-dependent constraints available on some particular machines;
1899 it includes both constraints that are useful for @code{asm} and
1900 constraints that aren't.  The compiler source file mentioned in the
1901 table heading for each architecture is the definitive reference for
1902 the meanings of that architecture's constraints.
1904 @c Please keep this table alphabetized by target!
1905 @table @emph
1906 @item AArch64 family---@file{config/aarch64/constraints.md}
1907 @table @code
1908 @item k
1909 The stack pointer register (@code{SP})
1911 @item w
1912 Floating point register, Advanced SIMD vector register or SVE vector register
1914 @item x
1915 Like @code{w}, but restricted to registers 0 to 15 inclusive.
1917 @item y
1918 Like @code{w}, but restricted to registers 0 to 7 inclusive.
1920 @item Upl
1921 One of the low eight SVE predicate registers (@code{P0} to @code{P7})
1923 @item Upa
1924 Any of the SVE predicate registers (@code{P0} to @code{P15})
1926 @item I
1927 Integer constant that is valid as an immediate operand in an @code{ADD}
1928 instruction
1930 @item J
1931 Integer constant that is valid as an immediate operand in a @code{SUB}
1932 instruction (once negated)
1934 @item K
1935 Integer constant that can be used with a 32-bit logical instruction
1937 @item L
1938 Integer constant that can be used with a 64-bit logical instruction
1940 @item M
1941 Integer constant that is valid as an immediate operand in a 32-bit @code{MOV}
1942 pseudo instruction. The @code{MOV} may be assembled to one of several different
1943 machine instructions depending on the value
1945 @item N
1946 Integer constant that is valid as an immediate operand in a 64-bit @code{MOV}
1947 pseudo instruction
1949 @item S
1950 An absolute symbolic address or a label reference
1952 @item Y
1953 Floating point constant zero
1955 @item Z
1956 Integer constant zero
1958 @item Ush
1959 The high part (bits 12 and upwards) of the pc-relative address of a symbol
1960 within 4GB of the instruction
1962 @item Q
1963 A memory address which uses a single base register with no offset
1965 @item Ump
1966 A memory address suitable for a load/store pair instruction in SI, DI, SF and
1967 DF modes
1969 @end table
1972 @item AMD GCN ---@file{config/gcn/constraints.md}
1973 @table @code
1974 @item I
1975 Immediate integer in the range @minus{}16 to 64
1977 @item J
1978 Immediate 16-bit signed integer
1980 @item Kf
1981 Immediate constant @minus{}1
1983 @item L
1984 Immediate 15-bit unsigned integer
1986 @item A
1987 Immediate constant that can be inlined in an instruction encoding: integer
1988 @minus{}16..64, or float 0.0, +/@minus{}0.5, +/@minus{}1.0, +/@minus{}2.0,
1989 +/@minus{}4.0, 1.0/(2.0*PI)
1991 @item B
1992 Immediate 32-bit signed integer that can be attached to an instruction encoding
1994 @item C
1995 Immediate 32-bit integer in range @minus{}16..4294967295 (i.e. 32-bit unsigned
1996 integer or @samp{A} constraint)
1998 @item DA
1999 Immediate 64-bit constant that can be split into two @samp{A} constants
2001 @item DB
2002 Immediate 64-bit constant that can be split into two @samp{B} constants
2004 @item U
2005 Any @code{unspec}
2007 @item Y
2008 Any @code{symbol_ref} or @code{label_ref}
2010 @item v
2011 VGPR register
2013 @item Sg
2014 SGPR register
2016 @item SD
2017 SGPR registers valid for instruction destinations, including VCC, M0 and EXEC
2019 @item SS
2020 SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC
2022 @item Sm
2023 SGPR registers valid as a source for scalar memory instructions (excludes M0
2024 and EXEC)
2026 @item Sv
2027 SGPR registers valid as a source or destination for vector instructions
2028 (excludes EXEC)
2030 @item ca
2031 All condition registers: SCC, VCCZ, EXECZ
2033 @item cs
2034 Scalar condition register: SCC
2036 @item cV
2037 Vector condition register: VCC, VCC_LO, VCC_HI
2039 @item e
2040 EXEC register (EXEC_LO and EXEC_HI)
2042 @item RB
2043 Memory operand with address space suitable for @code{buffer_*} instructions
2045 @item RF
2046 Memory operand with address space suitable for @code{flat_*} instructions
2048 @item RS
2049 Memory operand with address space suitable for @code{s_*} instructions
2051 @item RL
2052 Memory operand with address space suitable for @code{ds_*} LDS instructions
2054 @item RG
2055 Memory operand with address space suitable for @code{ds_*} GDS instructions
2057 @item RD
2058 Memory operand with address space suitable for any @code{ds_*} instructions
2060 @item RM
2061 Memory operand with address space suitable for @code{global_*} instructions
2063 @end table
2066 @item ARC ---@file{config/arc/constraints.md}
2067 @table @code
2068 @item q
2069 Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3},
2070 @code{r12}-@code{r15}.  This constraint can only match when the @option{-mq}
2071 option is in effect.
2073 @item e
2074 Registers usable as base-regs of memory addresses in ARCompact 16-bit memory
2075 instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}.
2076 This constraint can only match when the @option{-mq}
2077 option is in effect.
2078 @item D
2079 ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}.
2081 @item I
2082 A signed 12-bit integer constant.
2084 @item Cal
2085 constant for arithmetic/logical operations.  This might be any constant
2086 that can be put into a long immediate by the assmbler or linker without
2087 involving a PIC relocation.
2089 @item K
2090 A 3-bit unsigned integer constant.
2092 @item L
2093 A 6-bit unsigned integer constant.
2095 @item CnL
2096 One's complement of a 6-bit unsigned integer constant.
2098 @item CmL
2099 Two's complement of a 6-bit unsigned integer constant.
2101 @item M
2102 A 5-bit unsigned integer constant.
2104 @item O
2105 A 7-bit unsigned integer constant.
2107 @item P
2108 A 8-bit unsigned integer constant.
2110 @item H
2111 Any const_double value.
2112 @end table
2114 @item ARM family---@file{config/arm/constraints.md}
2115 @table @code
2117 @item h
2118 In Thumb state, the core registers @code{r8}-@code{r15}.
2120 @item k
2121 The stack pointer register.
2123 @item l
2124 In Thumb State the core registers @code{r0}-@code{r7}.  In ARM state this
2125 is an alias for the @code{r} constraint.
2127 @item t
2128 VFP floating-point registers @code{s0}-@code{s31}.  Used for 32 bit values.
2130 @item w
2131 VFP floating-point registers @code{d0}-@code{d31} and the appropriate
2132 subset @code{d0}-@code{d15} based on command line options.
2133 Used for 64 bit values only.  Not valid for Thumb1.
2135 @item y
2136 The iWMMX co-processor registers.
2138 @item z
2139 The iWMMX GR registers.
2141 @item G
2142 The floating-point constant 0.0
2144 @item I
2145 Integer that is valid as an immediate operand in a data processing
2146 instruction.  That is, an integer in the range 0 to 255 rotated by a
2147 multiple of 2
2149 @item J
2150 Integer in the range @minus{}4095 to 4095
2152 @item K
2153 Integer that satisfies constraint @samp{I} when inverted (ones complement)
2155 @item L
2156 Integer that satisfies constraint @samp{I} when negated (twos complement)
2158 @item M
2159 Integer in the range 0 to 32
2161 @item Q
2162 A memory reference where the exact address is in a single register
2163 (`@samp{m}' is preferable for @code{asm} statements)
2165 @item R
2166 An item in the constant pool
2168 @item S
2169 A symbol in the text segment of the current file
2171 @item Uv
2172 A memory reference suitable for VFP load/store insns (reg+constant offset)
2174 @item Uy
2175 A memory reference suitable for iWMMXt load/store instructions.
2177 @item Uq
2178 A memory reference suitable for the ARMv4 ldrsb instruction.
2179 @end table
2181 @item AVR family---@file{config/avr/constraints.md}
2182 @table @code
2183 @item l
2184 Registers from r0 to r15
2186 @item a
2187 Registers from r16 to r23
2189 @item d
2190 Registers from r16 to r31
2192 @item w
2193 Registers from r24 to r31.  These registers can be used in @samp{adiw} command
2195 @item e
2196 Pointer register (r26--r31)
2198 @item b
2199 Base pointer register (r28--r31)
2201 @item q
2202 Stack pointer register (SPH:SPL)
2204 @item t
2205 Temporary register r0
2207 @item x
2208 Register pair X (r27:r26)
2210 @item y
2211 Register pair Y (r29:r28)
2213 @item z
2214 Register pair Z (r31:r30)
2216 @item I
2217 Constant greater than @minus{}1, less than 64
2219 @item J
2220 Constant greater than @minus{}64, less than 1
2222 @item K
2223 Constant integer 2
2225 @item L
2226 Constant integer 0
2228 @item M
2229 Constant that fits in 8 bits
2231 @item N
2232 Constant integer @minus{}1
2234 @item O
2235 Constant integer 8, 16, or 24
2237 @item P
2238 Constant integer 1
2240 @item G
2241 A floating point constant 0.0
2243 @item Q
2244 A memory address based on Y or Z pointer with displacement.
2245 @end table
2247 @item Blackfin family---@file{config/bfin/constraints.md}
2248 @table @code
2249 @item a
2250 P register
2252 @item d
2253 D register
2255 @item z
2256 A call clobbered P register.
2258 @item q@var{n}
2259 A single register.  If @var{n} is in the range 0 to 7, the corresponding D
2260 register.  If it is @code{A}, then the register P0.
2262 @item D
2263 Even-numbered D register
2265 @item W
2266 Odd-numbered D register
2268 @item e
2269 Accumulator register.
2271 @item A
2272 Even-numbered accumulator register.
2274 @item B
2275 Odd-numbered accumulator register.
2277 @item b
2278 I register
2280 @item v
2281 B register
2283 @item f
2284 M register
2286 @item c
2287 Registers used for circular buffering, i.e.@: I, B, or L registers.
2289 @item C
2290 The CC register.
2292 @item t
2293 LT0 or LT1.
2295 @item k
2296 LC0 or LC1.
2298 @item u
2299 LB0 or LB1.
2301 @item x
2302 Any D, P, B, M, I or L register.
2304 @item y
2305 Additional registers typically used only in prologues and epilogues: RETS,
2306 RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP.
2308 @item w
2309 Any register except accumulators or CC.
2311 @item Ksh
2312 Signed 16 bit integer (in the range @minus{}32768 to 32767)
2314 @item Kuh
2315 Unsigned 16 bit integer (in the range 0 to 65535)
2317 @item Ks7
2318 Signed 7 bit integer (in the range @minus{}64 to 63)
2320 @item Ku7
2321 Unsigned 7 bit integer (in the range 0 to 127)
2323 @item Ku5
2324 Unsigned 5 bit integer (in the range 0 to 31)
2326 @item Ks4
2327 Signed 4 bit integer (in the range @minus{}8 to 7)
2329 @item Ks3
2330 Signed 3 bit integer (in the range @minus{}3 to 4)
2332 @item Ku3
2333 Unsigned 3 bit integer (in the range 0 to 7)
2335 @item P@var{n}
2336 Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4.
2338 @item PA
2339 An integer equal to one of the MACFLAG_XXX constants that is suitable for
2340 use with either accumulator.
2342 @item PB
2343 An integer equal to one of the MACFLAG_XXX constants that is suitable for
2344 use only with accumulator A1.
2346 @item M1
2347 Constant 255.
2349 @item M2
2350 Constant 65535.
2352 @item J
2353 An integer constant with exactly a single bit set.
2355 @item L
2356 An integer constant with all bits set except exactly one.
2358 @item H
2359 @itemx Q
2360 Any SYMBOL_REF.
2361 @end table
2363 @item C-SKY---@file{config/csky/constraints.md}
2364 @table @code
2366 @item a
2367 The mini registers r0 - r7.
2369 @item b
2370 The low registers r0 - r15.
2372 @item c
2373 C register.
2375 @item y
2376 HI and LO registers.
2378 @item l
2379 LO register.
2381 @item h
2382 HI register.
2384 @item v
2385 Vector registers.
2387 @item z
2388 Stack pointer register (SP).
2390 @item Q
2391 A memory address which uses a base register with a short offset
2392 or with a index register with its scale.
2394 @item W
2395 A memory address which uses a base register with a index register
2396 with its scale.
2397 @end table
2399 @ifset INTERNALS
2400 The C-SKY back end supports a large set of additional constraints
2401 that are only useful for instruction selection or splitting rather
2402 than inline asm, such as constraints representing constant integer
2403 ranges accepted by particular instruction encodings.
2404 Refer to the source code for details.
2405 @end ifset
2407 @item Epiphany---@file{config/epiphany/constraints.md}
2408 @table @code
2409 @item U16
2410 An unsigned 16-bit constant.
2412 @item K
2413 An unsigned 5-bit constant.
2415 @item L
2416 A signed 11-bit constant.
2418 @item Cm1
2419 A signed 11-bit constant added to @minus{}1.
2420 Can only match when the @option{-m1reg-@var{reg}} option is active.
2422 @item Cl1
2423 Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
2424 being a block of trailing zeroes.
2425 Can only match when the @option{-m1reg-@var{reg}} option is active.
2427 @item Cr1
2428 Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
2429 rest being zeroes.  Or to put it another way, one less than a power of two.
2430 Can only match when the @option{-m1reg-@var{reg}} option is active.
2432 @item Cal
2433 Constant for arithmetic/logical operations.
2434 This is like @code{i}, except that for position independent code,
2435 no symbols / expressions needing relocations are allowed.
2437 @item Csy
2438 Symbolic constant for call/jump instruction.
2440 @item Rcs
2441 The register class usable in short insns.  This is a register class
2442 constraint, and can thus drive register allocation.
2443 This constraint won't match unless @option{-mprefer-short-insn-regs} is
2444 in effect.
2446 @item Rsc
2447 The register class of registers that can be used to hold a
2448 sibcall call address.  I.e., a caller-saved register.
2450 @item Rct
2451 Core control register class.
2453 @item Rgs
2454 The register group usable in short insns.
2455 This constraint does not use a register class, so that it only
2456 passively matches suitable registers, and doesn't drive register allocation.
2458 @ifset INTERNALS
2459 @item Car
2460 Constant suitable for the addsi3_r pattern.  This is a valid offset
2461 For byte, halfword, or word addressing.
2462 @end ifset
2464 @item Rra
2465 Matches the return address if it can be replaced with the link register.
2467 @item Rcc
2468 Matches the integer condition code register.
2470 @item Sra
2471 Matches the return address if it is in a stack slot.
2473 @item Cfm
2474 Matches control register values to switch fp mode, which are encapsulated in
2475 @code{UNSPEC_FP_MODE}.
2476 @end table
2478 @item FRV---@file{config/frv/frv.h}
2479 @table @code
2480 @item a
2481 Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
2483 @item b
2484 Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
2486 @item c
2487 Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
2488 @code{icc0} to @code{icc3}).
2490 @item d
2491 Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
2493 @item e
2494 Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
2495 Odd registers are excluded not in the class but through the use of a machine
2496 mode larger than 4 bytes.
2498 @item f
2499 Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
2501 @item h
2502 Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
2503 Odd registers are excluded not in the class but through the use of a machine
2504 mode larger than 4 bytes.
2506 @item l
2507 Register in the class @code{LR_REG} (the @code{lr} register).
2509 @item q
2510 Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
2511 Register numbers not divisible by 4 are excluded not in the class but through
2512 the use of a machine mode larger than 8 bytes.
2514 @item t
2515 Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
2517 @item u
2518 Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
2520 @item v
2521 Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
2523 @item w
2524 Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
2526 @item x
2527 Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
2528 Register numbers not divisible by 4 are excluded not in the class but through
2529 the use of a machine mode larger than 8 bytes.
2531 @item z
2532 Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
2534 @item A
2535 Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
2537 @item B
2538 Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
2540 @item C
2541 Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
2543 @item G
2544 Floating point constant zero
2546 @item I
2547 6-bit signed integer constant
2549 @item J
2550 10-bit signed integer constant
2552 @item L
2553 16-bit signed integer constant
2555 @item M
2556 16-bit unsigned integer constant
2558 @item N
2559 12-bit signed integer constant that is negative---i.e.@: in the
2560 range of @minus{}2048 to @minus{}1
2562 @item O
2563 Constant zero
2565 @item P
2566 12-bit signed integer constant that is greater than zero---i.e.@: in the
2567 range of 1 to 2047.
2569 @end table
2571 @item FT32---@file{config/ft32/constraints.md}
2572 @table @code
2573 @item A
2574 An absolute address
2576 @item B
2577 An offset address
2579 @item W
2580 A register indirect memory operand
2582 @item e
2583 An offset address.
2585 @item f
2586 An offset address.
2588 @item O
2589 The constant zero or one
2591 @item I
2592 A 16-bit signed constant (@minus{}32768 @dots{} 32767)
2594 @item w
2595 A bitfield mask suitable for bext or bins
2597 @item x
2598 An inverted bitfield mask suitable for bext or bins
2600 @item L
2601 A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532)
2603 @item S
2604 A 20-bit signed constant (@minus{}524288 @dots{} 524287)
2606 @item b
2607 A constant for a bitfield width (1 @dots{} 16)
2609 @item KA
2610 A 10-bit signed constant (@minus{}512 @dots{} 511)
2612 @end table
2614 @item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
2615 @table @code
2616 @item a
2617 General register 1
2619 @item f
2620 Floating point register
2622 @item q
2623 Shift amount register
2625 @item x
2626 Floating point register (deprecated)
2628 @item y
2629 Upper floating point register (32-bit), floating point register (64-bit)
2631 @item Z
2632 Any register
2634 @item I
2635 Signed 11-bit integer constant
2637 @item J
2638 Signed 14-bit integer constant
2640 @item K
2641 Integer constant that can be deposited with a @code{zdepi} instruction
2643 @item L
2644 Signed 5-bit integer constant
2646 @item M
2647 Integer constant 0
2649 @item N
2650 Integer constant that can be loaded with a @code{ldil} instruction
2652 @item O
2653 Integer constant whose value plus one is a power of 2
2655 @item P
2656 Integer constant that can be used for @code{and} operations in @code{depi}
2657 and @code{extru} instructions
2659 @item S
2660 Integer constant 31
2662 @item U
2663 Integer constant 63
2665 @item G
2666 Floating-point constant 0.0
2668 @item A
2669 A @code{lo_sum} data-linkage-table memory operand
2671 @item Q
2672 A memory operand that can be used as the destination operand of an
2673 integer store instruction
2675 @item R
2676 A scaled or unscaled indexed memory operand
2678 @item T
2679 A memory operand for floating-point loads and stores
2681 @item W
2682 A register indirect memory operand
2683 @end table
2685 @item Intel IA-64---@file{config/ia64/ia64.h}
2686 @table @code
2687 @item a
2688 General register @code{r0} to @code{r3} for @code{addl} instruction
2690 @item b
2691 Branch register
2693 @item c
2694 Predicate register (@samp{c} as in ``conditional'')
2696 @item d
2697 Application register residing in M-unit
2699 @item e
2700 Application register residing in I-unit
2702 @item f
2703 Floating-point register
2705 @item m
2706 Memory operand.  If used together with @samp{<} or @samp{>},
2707 the operand can have postincrement and postdecrement which
2708 require printing with @samp{%Pn} on IA-64.
2710 @item G
2711 Floating-point constant 0.0 or 1.0
2713 @item I
2714 14-bit signed integer constant
2716 @item J
2717 22-bit signed integer constant
2719 @item K
2720 8-bit signed integer constant for logical instructions
2722 @item L
2723 8-bit adjusted signed integer constant for compare pseudo-ops
2725 @item M
2726 6-bit unsigned integer constant for shift counts
2728 @item N
2729 9-bit signed integer constant for load and store postincrements
2731 @item O
2732 The constant zero
2734 @item P
2735 0 or @minus{}1 for @code{dep} instruction
2737 @item Q
2738 Non-volatile memory for floating-point loads and stores
2740 @item R
2741 Integer constant in the range 1 to 4 for @code{shladd} instruction
2743 @item S
2744 Memory operand except postincrement and postdecrement.  This is
2745 now roughly the same as @samp{m} when not used together with @samp{<}
2746 or @samp{>}.
2747 @end table
2749 @item M32C---@file{config/m32c/m32c.cc}
2750 @table @code
2751 @item Rsp
2752 @itemx Rfb
2753 @itemx Rsb
2754 @samp{$sp}, @samp{$fb}, @samp{$sb}.
2756 @item Rcr
2757 Any control register, when they're 16 bits wide (nothing if control
2758 registers are 24 bits wide)
2760 @item Rcl
2761 Any control register, when they're 24 bits wide.
2763 @item R0w
2764 @itemx R1w
2765 @itemx R2w
2766 @itemx R3w
2767 $r0, $r1, $r2, $r3.
2769 @item R02
2770 $r0 or $r2, or $r2r0 for 32 bit values.
2772 @item R13
2773 $r1 or $r3, or $r3r1 for 32 bit values.
2775 @item Rdi
2776 A register that can hold a 64 bit value.
2778 @item Rhl
2779 $r0 or $r1 (registers with addressable high/low bytes)
2781 @item R23
2782 $r2 or $r3
2784 @item Raa
2785 Address registers
2787 @item Raw
2788 Address registers when they're 16 bits wide.
2790 @item Ral
2791 Address registers when they're 24 bits wide.
2793 @item Rqi
2794 Registers that can hold QI values.
2796 @item Rad
2797 Registers that can be used with displacements ($a0, $a1, $sb).
2799 @item Rsi
2800 Registers that can hold 32 bit values.
2802 @item Rhi
2803 Registers that can hold 16 bit values.
2805 @item Rhc
2806 Registers chat can hold 16 bit values, including all control
2807 registers.
2809 @item Rra
2810 $r0 through R1, plus $a0 and $a1.
2812 @item Rfl
2813 The flags register.
2815 @item Rmm
2816 The memory-based pseudo-registers $mem0 through $mem15.
2818 @item Rpi
2819 Registers that can hold pointers (16 bit registers for r8c, m16c; 24
2820 bit registers for m32cm, m32c).
2822 @item Rpa
2823 Matches multiple registers in a PARALLEL to form a larger register.
2824 Used to match function return values.
2826 @item Is3
2827 @minus{}8 @dots{} 7
2829 @item IS1
2830 @minus{}128 @dots{} 127
2832 @item IS2
2833 @minus{}32768 @dots{} 32767
2835 @item IU2
2836 0 @dots{} 65535
2838 @item In4
2839 @minus{}8 @dots{} @minus{}1 or 1 @dots{} 8
2841 @item In5
2842 @minus{}16 @dots{} @minus{}1 or 1 @dots{} 16
2844 @item In6
2845 @minus{}32 @dots{} @minus{}1 or 1 @dots{} 32
2847 @item IM2
2848 @minus{}65536 @dots{} @minus{}1
2850 @item Ilb
2851 An 8 bit value with exactly one bit set.
2853 @item Ilw
2854 A 16 bit value with exactly one bit set.
2856 @item Sd
2857 The common src/dest memory addressing modes.
2859 @item Sa
2860 Memory addressed using $a0 or $a1.
2862 @item Si
2863 Memory addressed with immediate addresses.
2865 @item Ss
2866 Memory addressed using the stack pointer ($sp).
2868 @item Sf
2869 Memory addressed using the frame base register ($fb).
2871 @item Ss
2872 Memory addressed using the small base register ($sb).
2874 @item S1
2875 $r1h
2876 @end table
2878 @item LoongArch---@file{config/loongarch/constraints.md}
2879 @table @code
2880 @item f
2881 A floating-point register (if available).
2882 @item k
2883 A memory operand whose address is formed by a base register and
2884 (optionally scaled) index register.
2885 @item l
2886 A signed 16-bit constant.
2887 @item m
2888 A memory operand whose address is formed by a base register and offset
2889 that is suitable for use in instructions with the same addressing mode
2890 as @code{st.w} and @code{ld.w}.
2891 @item I
2892 A signed 12-bit constant (for arithmetic instructions).
2893 @item K
2894 An unsigned 12-bit constant (for logic instructions).
2895 @item M
2896 A constant that cannot be loaded using @code{lui}, @code{addiu}
2897 or @code{ori}.
2898 @item N
2899 A constant in the range -65535 to -1 (inclusive).
2900 @item O
2901 A signed 15-bit constant.
2902 @item P
2903 A constant in the range 1 to 65535 (inclusive).
2904 @item R
2905 An address that can be used in a non-macro load or store.
2906 @item ZB
2907 An address that is held in a general-purpose register.
2908 The offset is zero.
2909 @item ZC
2910 A memory operand whose address is formed by a base register and offset
2911 that is suitable for use in instructions with the same addressing mode
2912 as @code{ll.w} and @code{sc.w}.
2913 @end table
2915 @item MicroBlaze---@file{config/microblaze/constraints.md}
2916 @table @code
2917 @item d
2918 A general register (@code{r0} to @code{r31}).
2920 @item z
2921 A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
2923 @end table
2925 @item MIPS---@file{config/mips/constraints.md}
2926 @table @code
2927 @item d
2928 A general-purpose register.  This is equivalent to @code{r} unless
2929 generating MIPS16 code, in which case the MIPS16 register set is used.
2931 @item f
2932 A floating-point register (if available).
2934 @item h
2935 Formerly the @code{hi} register.  This constraint is no longer supported.
2937 @item l
2938 The @code{lo} register.  Use this register to store values that are
2939 no bigger than a word.
2941 @item x
2942 The concatenated @code{hi} and @code{lo} registers.  Use this register
2943 to store doubleword values.
2945 @item c
2946 A register suitable for use in an indirect jump.  This will always be
2947 @code{$25} for @option{-mabicalls}.
2949 @item v
2950 Register @code{$3}.  Do not use this constraint in new code;
2951 it is retained only for compatibility with glibc.
2953 @item y
2954 Equivalent to @code{r}; retained for backwards compatibility.
2956 @item z
2957 A floating-point condition code register.
2959 @item I
2960 A signed 16-bit constant (for arithmetic instructions).
2962 @item J
2963 Integer zero.
2965 @item K
2966 An unsigned 16-bit constant (for logic instructions).
2968 @item L
2969 A signed 32-bit constant in which the lower 16 bits are zero.
2970 Such constants can be loaded using @code{lui}.
2972 @item M
2973 A constant that cannot be loaded using @code{lui}, @code{addiu}
2974 or @code{ori}.
2976 @item N
2977 A constant in the range @minus{}65535 to @minus{}1 (inclusive).
2979 @item O
2980 A signed 15-bit constant.
2982 @item P
2983 A constant in the range 1 to 65535 (inclusive).
2985 @item G
2986 Floating-point zero.
2988 @item R
2989 An address that can be used in a non-macro load or store.
2991 @item ZC
2992 A memory operand whose address is formed by a base register and offset
2993 that is suitable for use in instructions with the same addressing mode
2994 as @code{ll} and @code{sc}.
2996 @item ZD
2997 An address suitable for a @code{prefetch} instruction, or for any other
2998 instruction with the same addressing mode as @code{prefetch}.
2999 @end table
3001 @item Motorola 680x0---@file{config/m68k/constraints.md}
3002 @table @code
3003 @item a
3004 Address register
3006 @item d
3007 Data register
3009 @item f
3010 68881 floating-point register, if available
3012 @item I
3013 Integer in the range 1 to 8
3015 @item J
3016 16-bit signed number
3018 @item K
3019 Signed number whose magnitude is greater than 0x80
3021 @item L
3022 Integer in the range @minus{}8 to @minus{}1
3024 @item M
3025 Signed number whose magnitude is greater than 0x100
3027 @item N
3028 Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate
3030 @item O
3031 16 (for rotate using swap)
3033 @item P
3034 Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate
3036 @item R
3037 Numbers that mov3q can handle
3039 @item G
3040 Floating point constant that is not a 68881 constant
3042 @item S
3043 Operands that satisfy 'm' when -mpcrel is in effect
3045 @item T
3046 Operands that satisfy 's' when -mpcrel is not in effect
3048 @item Q
3049 Address register indirect addressing mode
3051 @item U
3052 Register offset addressing
3054 @item W
3055 const_call_operand
3057 @item Cs
3058 symbol_ref or const
3060 @item Ci
3061 const_int
3063 @item C0
3064 const_int 0
3066 @item Cj
3067 Range of signed numbers that don't fit in 16 bits
3069 @item Cmvq
3070 Integers valid for mvq
3072 @item Capsw
3073 Integers valid for a moveq followed by a swap
3075 @item Cmvz
3076 Integers valid for mvz
3078 @item Cmvs
3079 Integers valid for mvs
3081 @item Ap
3082 push_operand
3084 @item Ac
3085 Non-register operands allowed in clr
3087 @end table
3089 @item Moxie---@file{config/moxie/constraints.md}
3090 @table @code
3091 @item A
3092 An absolute address
3094 @item B
3095 An offset address
3097 @item W
3098 A register indirect memory operand
3100 @item I
3101 A constant in the range of 0 to 255.
3103 @item N
3104 A constant in the range of 0 to @minus{}255.
3106 @end table
3108 @item MSP430--@file{config/msp430/constraints.md}
3109 @table @code
3111 @item R12
3112 Register R12.
3114 @item R13
3115 Register R13.
3117 @item K
3118 Integer constant 1.
3120 @item L
3121 Integer constant -1^20..1^19.
3123 @item M
3124 Integer constant 1-4.
3126 @item Ya
3127 Memory references which do not require an extended MOVX instruction.
3129 @item Yl
3130 Memory reference, labels only.
3132 @item Ys
3133 Memory reference, stack only.
3135 @end table
3137 @item NDS32---@file{config/nds32/constraints.md}
3138 @table @code
3139 @item w
3140 LOW register class $r0 to $r7 constraint for V3/V3M ISA.
3141 @item l
3142 LOW register class $r0 to $r7.
3143 @item d
3144 MIDDLE register class $r0 to $r11, $r16 to $r19.
3145 @item h
3146 HIGH register class $r12 to $r14, $r20 to $r31.
3147 @item t
3148 Temporary assist register $ta (i.e.@: $r15).
3149 @item k
3150 Stack register $sp.
3151 @item Iu03
3152 Unsigned immediate 3-bit value.
3153 @item In03
3154 Negative immediate 3-bit value in the range of @minus{}7--0.
3155 @item Iu04
3156 Unsigned immediate 4-bit value.
3157 @item Is05
3158 Signed immediate 5-bit value.
3159 @item Iu05
3160 Unsigned immediate 5-bit value.
3161 @item In05
3162 Negative immediate 5-bit value in the range of @minus{}31--0.
3163 @item Ip05
3164 Unsigned immediate 5-bit value for movpi45 instruction with range 16--47.
3165 @item Iu06
3166 Unsigned immediate 6-bit value constraint for addri36.sp instruction.
3167 @item Iu08
3168 Unsigned immediate 8-bit value.
3169 @item Iu09
3170 Unsigned immediate 9-bit value.
3171 @item Is10
3172 Signed immediate 10-bit value.
3173 @item Is11
3174 Signed immediate 11-bit value.
3175 @item Is15
3176 Signed immediate 15-bit value.
3177 @item Iu15
3178 Unsigned immediate 15-bit value.
3179 @item Ic15
3180 A constant which is not in the range of imm15u but ok for bclr instruction.
3181 @item Ie15
3182 A constant which is not in the range of imm15u but ok for bset instruction.
3183 @item It15
3184 A constant which is not in the range of imm15u but ok for btgl instruction.
3185 @item Ii15
3186 A constant whose compliment value is in the range of imm15u
3187 and ok for bitci instruction.
3188 @item Is16
3189 Signed immediate 16-bit value.
3190 @item Is17
3191 Signed immediate 17-bit value.
3192 @item Is19
3193 Signed immediate 19-bit value.
3194 @item Is20
3195 Signed immediate 20-bit value.
3196 @item Ihig
3197 The immediate value that can be simply set high 20-bit.
3198 @item Izeb
3199 The immediate value 0xff.
3200 @item Izeh
3201 The immediate value 0xffff.
3202 @item Ixls
3203 The immediate value 0x01.
3204 @item Ix11
3205 The immediate value 0x7ff.
3206 @item Ibms
3207 The immediate value with power of 2.
3208 @item Ifex
3209 The immediate value with power of 2 minus 1.
3210 @item U33
3211 Memory constraint for 333 format.
3212 @item U45
3213 Memory constraint for 45 format.
3214 @item U37
3215 Memory constraint for 37 format.
3216 @end table
3218 @item Nios II family---@file{config/nios2/constraints.md}
3219 @table @code
3221 @item I
3222 Integer that is valid as an immediate operand in an
3223 instruction taking a signed 16-bit number. Range
3224 @minus{}32768 to 32767.
3226 @item J
3227 Integer that is valid as an immediate operand in an
3228 instruction taking an unsigned 16-bit number. Range
3229 0 to 65535.
3231 @item K
3232 Integer that is valid as an immediate operand in an
3233 instruction taking only the upper 16-bits of a
3234 32-bit number. Range 32-bit numbers with the lower
3235 16-bits being 0.
3237 @item L
3238 Integer that is valid as an immediate operand for a 
3239 shift instruction. Range 0 to 31.
3241 @item M
3242 Integer that is valid as an immediate operand for
3243 only the value 0. Can be used in conjunction with
3244 the format modifier @code{z} to use @code{r0}
3245 instead of @code{0} in the assembly output.
3247 @item N
3248 Integer that is valid as an immediate operand for
3249 a custom instruction opcode. Range 0 to 255.
3251 @item P
3252 An immediate operand for R2 andchi/andci instructions. 
3254 @item S
3255 Matches immediates which are addresses in the small
3256 data section and therefore can be added to @code{gp}
3257 as a 16-bit immediate to re-create their 32-bit value.
3259 @item U
3260 Matches constants suitable as an operand for the rdprs and
3261 cache instructions.
3263 @item v
3264 A memory operand suitable for Nios II R2 load/store
3265 exclusive instructions.
3267 @item w
3268 A memory operand suitable for load/store IO and cache
3269 instructions.
3271 @ifset INTERNALS
3272 @item T
3273 A @code{const} wrapped @code{UNSPEC} expression,
3274 representing a supported PIC or TLS relocation.
3275 @end ifset
3277 @end table
3279 @item OpenRISC---@file{config/or1k/constraints.md}
3280 @table @code
3281 @item I
3282 Integer that is valid as an immediate operand in an
3283 instruction taking a signed 16-bit number. Range
3284 @minus{}32768 to 32767.
3286 @item K
3287 Integer that is valid as an immediate operand in an
3288 instruction taking an unsigned 16-bit number. Range
3289 0 to 65535.
3291 @item M
3292 Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi})
3294 @item O
3295 Zero
3297 @ifset INTERNALS
3298 @item c
3299 Register usable for sibcalls.
3300 @end ifset
3302 @end table
3304 @item PDP-11---@file{config/pdp11/constraints.md}
3305 @table @code
3306 @item a
3307 Floating point registers AC0 through AC3.  These can be loaded from/to
3308 memory with a single instruction.
3310 @item d
3311 Odd numbered general registers (R1, R3, R5).  These are used for
3312 16-bit multiply operations.
3314 @item D
3315 A memory reference that is encoded within the opcode, but not
3316 auto-increment or auto-decrement.
3318 @item f
3319 Any of the floating point registers (AC0 through AC5).
3321 @item G
3322 Floating point constant 0.
3324 @item h
3325 Floating point registers AC4 and AC5.  These cannot be loaded from/to
3326 memory with a single instruction.
3328 @item I
3329 An integer constant that fits in 16 bits.
3331 @item J
3332 An integer constant whose low order 16 bits are zero.
3334 @item K
3335 An integer constant that does not meet the constraints for codes
3336 @samp{I} or @samp{J}.
3338 @item L
3339 The integer constant 1.
3341 @item M
3342 The integer constant @minus{}1.
3344 @item N
3345 The integer constant 0.
3347 @item O
3348 Integer constants 0 through 3; shifts by these
3349 amounts are handled as multiple single-bit shifts rather than a single
3350 variable-length shift.
3352 @item Q
3353 A memory reference which requires an additional word (address or
3354 offset) after the opcode.
3356 @item R
3357 A memory reference that is encoded within the opcode.
3359 @end table
3361 @item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md}
3362 @table @code
3363 @item r
3364 A general purpose register (GPR), @code{r0}@dots{}@code{r31}.
3366 @item b
3367 A base register.  Like @code{r}, but @code{r0} is not allowed, so
3368 @code{r1}@dots{}@code{r31}.
3370 @item f
3371 A floating point register (FPR), @code{f0}@dots{}@code{f31}.
3373 @item d
3374 A floating point register.  This is the same as @code{f} nowadays;
3375 historically @code{f} was for single-precision and @code{d} was for
3376 double-precision floating point.
3378 @item v
3379 An Altivec vector register (VR), @code{v0}@dots{}@code{v31}.
3381 @item wa
3382 A VSX register (VSR), @code{vs0}@dots{}@code{vs63}.  This is either an
3383 FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR
3384 (@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}).
3386 When using @code{wa}, you should use the @code{%x} output modifier, so that
3387 the correct register number is printed.  For example:
3389 @smallexample
3390 asm ("xvadddp %x0,%x1,%x2"
3391      : "=wa" (v1)
3392      : "wa" (v2), "wa" (v3));
3393 @end smallexample
3395 You should not use @code{%x} for @code{v} operands:
3397 @smallexample
3398 asm ("xsaddqp %0,%1,%2"
3399      : "=v" (v1)
3400      : "v" (v2), "v" (v3));
3401 @end smallexample
3403 @ifset INTERNALS
3404 @item h
3405 A special register (@code{vrsave}, @code{ctr}, or @code{lr}).
3406 @end ifset
3408 @item c
3409 The count register, @code{ctr}.
3411 @item l
3412 The link register, @code{lr}.
3414 @item x
3415 Condition register field 0, @code{cr0}.
3417 @item y
3418 Any condition register field, @code{cr0}@dots{}@code{cr7}.
3420 @ifset INTERNALS
3421 @item z
3422 The carry bit, @code{XER[CA]}.
3424 @item we
3425 Like @code{wa}, if @option{-mpower9-vector} and @option{-m64} are used;
3426 otherwise, @code{NO_REGS}.
3428 @item wn
3429 No register (@code{NO_REGS}).
3431 @item wr
3432 Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3434 @item wx
3435 Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}.
3437 @item wA
3438 Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3440 @item wB
3441 Signed 5-bit constant integer that can be loaded into an Altivec register.
3443 @item wE
3444 Vector constant that can be loaded with the XXSPLTIB instruction.
3446 @item wF
3447 Memory operand suitable for power8 GPR load fusion.
3449 @item wL
3450 Int constant that is the element number mfvsrld accesses in a vector.
3452 @item wM
3453 Match vector constant with all 1's if the XXLORC instruction is available.
3455 @item wO
3456 Memory operand suitable for the ISA 3.0 vector d-form instructions.
3458 @item wQ
3459 Memory operand suitable for the load/store quad instructions.
3461 @item wS
3462 Vector constant that can be loaded with XXSPLTIB & sign extension.
3464 @item wY
3465 A memory operand for a DS-form instruction.
3467 @item wZ
3468 An indexed or indirect memory operand, ignoring the bottom 4 bits.
3469 @end ifset
3471 @item I
3472 A signed 16-bit constant.
3474 @item J
3475 An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead
3476 for @code{SImode} constants).
3478 @item K
3479 An unsigned 16-bit constant.
3481 @item L
3482 A signed 16-bit constant shifted left 16 bits.
3484 @ifset INTERNALS
3485 @item M
3486 An integer constant greater than 31.
3488 @item N
3489 An exact power of 2.
3491 @item O
3492 The integer constant zero.
3494 @item P
3495 A constant whose negation is a signed 16-bit constant.
3496 @end ifset
3498 @item eI
3499 A signed 34-bit integer constant if prefixed instructions are supported.
3501 @item eP
3502 A scalar floating point constant or a vector constant that can be
3503 loaded to a VSX register with one prefixed instruction.
3505 @item eQ
3506 An IEEE 128-bit constant that can be loaded into a VSX register with
3507 the @code{lxvkq} instruction.
3509 @ifset INTERNALS
3510 @item G
3511 A floating point constant that can be loaded into a register with one
3512 instruction per word.
3514 @item H
3515 A floating point constant that can be loaded into a register using
3516 three instructions.
3517 @end ifset
3519 @item m
3520 A memory operand.
3521 Normally, @code{m} does not allow addresses that update the base register.
3522 If the @code{<} or @code{>} constraint is also used, they are allowed and
3523 therefore on PowerPC targets in that case it is only safe
3524 to use @code{m<>} in an @code{asm} statement if that @code{asm} statement
3525 accesses the operand exactly once.  The @code{asm} statement must also
3526 use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
3527 corresponding load or store instruction.  For example:
3529 @smallexample
3530 asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
3531 @end smallexample
3533 is correct but:
3535 @smallexample
3536 asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
3537 @end smallexample
3539 is not.
3541 @ifset INTERNALS
3542 @item es
3543 A ``stable'' memory operand; that is, one which does not include any
3544 automodification of the base register.  This used to be useful when
3545 @code{m} allowed automodification of the base register, but as those
3546 are now only allowed when @code{<} or @code{>} is used, @code{es} is
3547 basically the same as @code{m} without @code{<} and @code{>}.
3548 @end ifset
3550 @item Q
3551 A memory operand addressed by just a base register.
3553 @ifset INTERNALS
3554 @item Y
3555 A memory operand for a DQ-form instruction.
3556 @end ifset
3558 @item Z
3559 A memory operand accessed with indexed or indirect addressing.
3561 @ifset INTERNALS
3562 @item R
3563 An AIX TOC entry.
3564 @end ifset
3566 @item a
3567 An indexed or indirect address.
3569 @ifset INTERNALS
3570 @item U
3571 A V.4 small data reference.
3573 @item W
3574 A vector constant that does not require memory.
3576 @item j
3577 The zero vector constant.
3578 @end ifset
3580 @end table
3582 @item PRU---@file{config/pru/constraints.md}
3583 @table @code
3584 @item I
3585 An unsigned 8-bit integer constant.
3587 @item J
3588 An unsigned 16-bit integer constant.
3590 @item L
3591 An unsigned 5-bit integer constant (for shift counts).
3593 @item T
3594 A text segment (program memory) constant label.
3596 @item Z
3597 Integer constant zero.
3599 @end table
3601 @item RL78---@file{config/rl78/constraints.md}
3602 @table @code
3604 @item Int3
3605 An integer constant in the range 1 @dots{} 7.
3606 @item Int8
3607 An integer constant in the range 0 @dots{} 255.
3608 @item J
3609 An integer constant in the range @minus{}255 @dots{} 0
3610 @item K
3611 The integer constant 1.
3612 @item L
3613 The integer constant -1.
3614 @item M
3615 The integer constant 0.
3616 @item N
3617 The integer constant 2.
3618 @item O
3619 The integer constant -2.
3620 @item P
3621 An integer constant in the range 1 @dots{} 15.
3622 @item Qbi
3623 The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
3624 @item Qsc
3625 The synthetic compare types--gt, lt, ge, and le.
3626 @item Wab
3627 A memory reference with an absolute address.
3628 @item Wbc
3629 A memory reference using @code{BC} as a base register, with an optional offset.
3630 @item Wca
3631 A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
3632 @item Wcv
3633 A memory reference using any 16-bit register pair for the address, for calls.
3634 @item Wd2
3635 A memory reference using @code{DE} as a base register, with an optional offset.
3636 @item Wde
3637 A memory reference using @code{DE} as a base register, without any offset.
3638 @item Wfr
3639 Any memory reference to an address in the far address space.
3640 @item Wh1
3641 A memory reference using @code{HL} as a base register, with an optional one-byte offset.
3642 @item Whb
3643 A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
3644 @item Whl
3645 A memory reference using @code{HL} as a base register, without any offset.
3646 @item Ws1
3647 A memory reference using @code{SP} as a base register, with an optional one-byte offset.
3648 @item Y
3649 Any memory reference to an address in the near address space.
3650 @item A
3651 The @code{AX} register.
3652 @item B
3653 The @code{BC} register.
3654 @item D
3655 The @code{DE} register.
3656 @item R
3657 @code{A} through @code{L} registers.
3658 @item S
3659 The @code{SP} register.
3660 @item T
3661 The @code{HL} register.
3662 @item Z08W
3663 The 16-bit @code{R8} register.
3664 @item Z10W
3665 The 16-bit @code{R10} register.
3666 @item Zint
3667 The registers reserved for interrupts (@code{R24} to @code{R31}).
3668 @item a
3669 The @code{A} register.
3670 @item b
3671 The @code{B} register.
3672 @item c
3673 The @code{C} register.
3674 @item d
3675 The @code{D} register.
3676 @item e
3677 The @code{E} register.
3678 @item h
3679 The @code{H} register.
3680 @item l
3681 The @code{L} register.
3682 @item v
3683 The virtual registers.
3684 @item w
3685 The @code{PSW} register.
3686 @item x
3687 The @code{X} register.
3689 @end table
3691 @item RISC-V---@file{config/riscv/constraints.md}
3692 @table @code
3694 @item f
3695 A floating-point register (if available).
3697 @item I
3698 An I-type 12-bit signed immediate.
3700 @item J
3701 Integer zero.
3703 @item K
3704 A 5-bit unsigned immediate for CSR access instructions.
3706 @item A
3707 An address that is held in a general-purpose register.
3709 @item S
3710 A constraint that matches an absolute symbolic address.
3712 @item vr
3713 A vector register (if available)..
3715 @item vd
3716 A vector register, excluding v0 (if available).
3718 @item vm
3719 A vector register, only v0 (if available).
3721 @end table
3723 @item RX---@file{config/rx/constraints.md}
3724 @table @code
3725 @item Q
3726 An address which does not involve register indirect addressing or
3727 pre/post increment/decrement addressing.
3729 @item Symbol
3730 A symbol reference.
3732 @item Int08
3733 A constant in the range @minus{}256 to 255, inclusive.
3735 @item Sint08
3736 A constant in the range @minus{}128 to 127, inclusive.
3738 @item Sint16
3739 A constant in the range @minus{}32768 to 32767, inclusive.
3741 @item Sint24
3742 A constant in the range @minus{}8388608 to 8388607, inclusive.
3744 @item Uint04
3745 A constant in the range 0 to 15, inclusive.
3747 @end table
3749 @item S/390 and zSeries---@file{config/s390/s390.h}
3750 @table @code
3751 @item a
3752 Address register (general purpose register except r0)
3754 @item c
3755 Condition code register
3757 @item d
3758 Data register (arbitrary general purpose register)
3760 @item f
3761 Floating-point register
3763 @item I
3764 Unsigned 8-bit constant (0--255)
3766 @item J
3767 Unsigned 12-bit constant (0--4095)
3769 @item K
3770 Signed 16-bit constant (@minus{}32768--32767)
3772 @item L
3773 Value appropriate as displacement.
3774 @table @code
3775 @item (0..4095)
3776 for short displacement
3777 @item (@minus{}524288..524287)
3778 for long displacement
3779 @end table
3781 @item M
3782 Constant integer with a value of 0x7fffffff.
3784 @item N
3785 Multiple letter constraint followed by 4 parameter letters.
3786 @table @code
3787 @item 0..9:
3788 number of the part counting from most to least significant
3789 @item H,Q:
3790 mode of the part
3791 @item D,S,H:
3792 mode of the containing operand
3793 @item 0,F:
3794 value of the other parts (F---all bits set)
3795 @end table
3796 The constraint matches if the specified part of a constant
3797 has a value different from its other parts.
3799 @item Q
3800 Memory reference without index register and with short displacement.
3802 @item R
3803 Memory reference with index register and short displacement.
3805 @item S
3806 Memory reference without index register but with long displacement.
3808 @item T
3809 Memory reference with index register and long displacement.
3811 @item U
3812 Pointer with short displacement.
3814 @item W
3815 Pointer with long displacement.
3817 @item Y
3818 Shift count operand.
3820 @end table
3822 @need 1000
3823 @item SPARC---@file{config/sparc/sparc.h}
3824 @table @code
3825 @item f
3826 Floating-point register on the SPARC-V8 architecture and
3827 lower floating-point register on the SPARC-V9 architecture.
3829 @item e
3830 Floating-point register.  It is equivalent to @samp{f} on the
3831 SPARC-V8 architecture and contains both lower and upper
3832 floating-point registers on the SPARC-V9 architecture.
3834 @item c
3835 Floating-point condition code register.
3837 @item d
3838 Lower floating-point register.  It is only valid on the SPARC-V9
3839 architecture when the Visual Instruction Set is available.
3841 @item b
3842 Floating-point register.  It is only valid on the SPARC-V9 architecture
3843 when the Visual Instruction Set is available.
3845 @item h
3846 64-bit global or out register for the SPARC-V8+ architecture.
3848 @item C
3849 The constant all-ones, for floating-point.
3851 @item A
3852 Signed 5-bit constant
3854 @item D
3855 A vector constant
3857 @item I
3858 Signed 13-bit constant
3860 @item J
3861 Zero
3863 @item K
3864 32-bit constant with the low 12 bits clear (a constant that can be
3865 loaded with the @code{sethi} instruction)
3867 @item L
3868 A constant in the range supported by @code{movcc} instructions (11-bit
3869 signed immediate)
3871 @item M
3872 A constant in the range supported by @code{movrcc} instructions (10-bit
3873 signed immediate)
3875 @item N
3876 Same as @samp{K}, except that it verifies that bits that are not in the
3877 lower 32-bit range are all zero.  Must be used instead of @samp{K} for
3878 modes wider than @code{SImode}
3880 @item O
3881 The constant 4096
3883 @item G
3884 Floating-point zero
3886 @item H
3887 Signed 13-bit constant, sign-extended to 32 or 64 bits
3889 @item P
3890 The constant -1
3892 @item Q
3893 Floating-point constant whose integral representation can
3894 be moved into an integer register using a single sethi
3895 instruction
3897 @item R
3898 Floating-point constant whose integral representation can
3899 be moved into an integer register using a single mov
3900 instruction
3902 @item S
3903 Floating-point constant whose integral representation can
3904 be moved into an integer register using a high/lo_sum
3905 instruction sequence
3907 @item T
3908 Memory address aligned to an 8-byte boundary
3910 @item U
3911 Even register
3913 @item W
3914 Memory address for @samp{e} constraint registers
3916 @item w
3917 Memory address with only a base register
3919 @item Y
3920 Vector zero
3922 @end table
3924 @item TI C6X family---@file{config/c6x/constraints.md}
3925 @table @code
3926 @item a
3927 Register file A (A0--A31).
3929 @item b
3930 Register file B (B0--B31).
3932 @item A
3933 Predicate registers in register file A (A0--A2 on C64X and
3934 higher, A1 and A2 otherwise).
3936 @item B
3937 Predicate registers in register file B (B0--B2).
3939 @item C
3940 A call-used register in register file B (B0--B9, B16--B31).
3942 @item Da
3943 Register file A, excluding predicate registers (A3--A31,
3944 plus A0 if not C64X or higher).
3946 @item Db
3947 Register file B, excluding predicate registers (B3--B31).
3949 @item Iu4
3950 Integer constant in the range 0 @dots{} 15.
3952 @item Iu5
3953 Integer constant in the range 0 @dots{} 31.
3955 @item In5
3956 Integer constant in the range @minus{}31 @dots{} 0.
3958 @item Is5
3959 Integer constant in the range @minus{}16 @dots{} 15.
3961 @item I5x
3962 Integer constant that can be the operand of an ADDA or a SUBA insn.
3964 @item IuB
3965 Integer constant in the range 0 @dots{} 65535.
3967 @item IsB
3968 Integer constant in the range @minus{}32768 @dots{} 32767.
3970 @item IsC
3971 Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.
3973 @item Jc
3974 Integer constant that is a valid mask for the clr instruction.
3976 @item Js
3977 Integer constant that is a valid mask for the set instruction.
3979 @item Q
3980 Memory location with A base register.
3982 @item R
3983 Memory location with B base register.
3985 @ifset INTERNALS
3986 @item S0
3987 On C64x+ targets, a GP-relative small data reference.
3989 @item S1
3990 Any kind of @code{SYMBOL_REF}, for use in a call address.
3992 @item Si
3993 Any kind of immediate operand, unless it matches the S0 constraint.
3995 @item T
3996 Memory location with B base register, but not using a long offset.
3998 @item W
3999 A memory operand with an address that cannot be used in an unaligned access.
4001 @end ifset
4002 @item Z
4003 Register B14 (aka DP).
4005 @end table
4007 @item Visium---@file{config/visium/constraints.md}
4008 @table @code
4009 @item b
4010 EAM register @code{mdb}
4012 @item c
4013 EAM register @code{mdc}
4015 @item f
4016 Floating point register
4018 @ifset INTERNALS
4019 @item k
4020 Register for sibcall optimization
4021 @end ifset
4023 @item l
4024 General register, but not @code{r29}, @code{r30} and @code{r31}
4026 @item t
4027 Register @code{r1}
4029 @item u
4030 Register @code{r2}
4032 @item v
4033 Register @code{r3}
4035 @item G
4036 Floating-point constant 0.0
4038 @item J
4039 Integer constant in the range 0 .. 65535 (16-bit immediate)
4041 @item K
4042 Integer constant in the range 1 .. 31 (5-bit immediate)
4044 @item L
4045 Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate)
4047 @item M
4048 Integer constant @minus{}1
4050 @item O
4051 Integer constant 0
4053 @item P
4054 Integer constant 32
4055 @end table
4057 @item x86 family---@file{config/i386/constraints.md}
4058 @table @code
4059 @item R
4060 Legacy register---the eight integer registers available on all
4061 i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
4062 @code{si}, @code{di}, @code{bp}, @code{sp}).
4064 @item q
4065 Any register accessible as @code{@var{r}l}.  In 32-bit mode, @code{a},
4066 @code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.
4068 @item Q
4069 Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
4070 @code{c}, and @code{d}.
4072 @ifset INTERNALS
4073 @item l
4074 Any register that can be used as the index in a base+index memory
4075 access: that is, any general register except the stack pointer.
4076 @end ifset
4078 @item a
4079 The @code{a} register.
4081 @item b
4082 The @code{b} register.
4084 @item c
4085 The @code{c} register.
4087 @item d
4088 The @code{d} register.
4090 @item S
4091 The @code{si} register.
4093 @item D
4094 The @code{di} register.
4096 @item A
4097 The @code{a} and @code{d} registers.  This class is used for instructions
4098 that return double word results in the @code{ax:dx} register pair.  Single
4099 word values will be allocated either in @code{ax} or @code{dx}.
4100 For example on i386 the following implements @code{rdtsc}:
4102 @smallexample
4103 unsigned long long rdtsc (void)
4105   unsigned long long tick;
4106   __asm__ __volatile__("rdtsc":"=A"(tick));
4107   return tick;
4109 @end smallexample
4111 This is not correct on x86-64 as it would allocate tick in either @code{ax}
4112 or @code{dx}.  You have to use the following variant instead:
4114 @smallexample
4115 unsigned long long rdtsc (void)
4117   unsigned int tickl, tickh;
4118   __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
4119   return ((unsigned long long)tickh << 32)|tickl;
4121 @end smallexample
4123 @item U
4124 The call-clobbered integer registers.
4126 @item f
4127 Any 80387 floating-point (stack) register.
4129 @item t
4130 Top of 80387 floating-point stack (@code{%st(0)}).
4132 @item u
4133 Second from top of 80387 floating-point stack (@code{%st(1)}).
4135 @ifset INTERNALS
4136 @item Yk
4137 Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}.
4139 @item k
4140 Any mask register.
4141 @end ifset
4143 @item y
4144 Any MMX register.
4146 @item x
4147 Any SSE register.
4149 @item v
4150 Any EVEX encodable SSE register (@code{%xmm0-%xmm31}).
4152 @ifset INTERNALS
4153 @item w
4154 Any bound register.
4155 @end ifset
4157 @item Yz
4158 First SSE register (@code{%xmm0}).
4160 @ifset INTERNALS
4161 @item Yi
4162 Any SSE register, when SSE2 and inter-unit moves are enabled.
4164 @item Yj
4165 Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled.
4167 @item Ym
4168 Any MMX register, when inter-unit moves are enabled.
4170 @item Yn
4171 Any MMX register, when inter-unit moves from vector registers are enabled.
4173 @item Yp
4174 Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled.
4176 @item Ya
4177 Any integer register when zero extensions with @code{AND} are disabled.
4179 @item Yb
4180 Any register that can be used as the GOT base when calling@*
4181 @code{___tls_get_addr}: that is, any general register except @code{a}
4182 and @code{sp} registers, for @option{-fno-plt} if linker supports it.
4183 Otherwise, @code{b} register.
4185 @item Yf
4186 Any x87 register when 80387 floating-point arithmetic is enabled.
4188 @item Yr
4189 Lower SSE register when avoiding REX prefix and all SSE registers otherwise.
4191 @item Yv
4192 For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}),
4193 otherwise any SSE register.
4195 @item Yh
4196 Any EVEX-encodable SSE register, that has number factor of four.
4198 @item Bf
4199 Flags register operand.
4201 @item Bg
4202 GOT memory operand.
4204 @item Bm
4205 Vector memory operand.
4207 @item Bc
4208 Constant memory operand.
4210 @item Bn
4211 Memory operand without REX prefix.
4213 @item Bs
4214 Sibcall memory operand.
4216 @item Bw
4217 Call memory operand.
4219 @item Bz
4220 Constant call address operand.
4222 @item BC
4223 SSE constant -1 operand.
4224 @end ifset
4226 @item I
4227 Integer constant in the range 0 @dots{} 31, for 32-bit shifts.
4229 @item J
4230 Integer constant in the range 0 @dots{} 63, for 64-bit shifts.
4232 @item K
4233 Signed 8-bit integer constant.
4235 @item L
4236 @code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.
4238 @item M
4239 0, 1, 2, or 3 (shifts for the @code{lea} instruction).
4241 @item N
4242 Unsigned 8-bit integer constant (for @code{in} and @code{out}
4243 instructions).
4245 @ifset INTERNALS
4246 @item O
4247 Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
4248 @end ifset
4250 @item G
4251 Standard 80387 floating point constant.
4253 @item C
4254 SSE constant zero operand.
4256 @item e
4257 32-bit signed integer constant, or a symbolic reference known
4258 to fit that range (for immediate operands in sign-extending x86-64
4259 instructions).
4261 @item We
4262 32-bit signed integer constant, or a symbolic reference known
4263 to fit that range (for sign-extending conversion operations that
4264 require non-@code{VOIDmode} immediate operands).
4266 @item Wz
4267 32-bit unsigned integer constant, or a symbolic reference known
4268 to fit that range (for zero-extending conversion operations that
4269 require non-@code{VOIDmode} immediate operands).
4271 @item Wd
4272 128-bit integer constant where both the high and low 64-bit word
4273 satisfy the @code{e} constraint.
4275 @item Z
4276 32-bit unsigned integer constant, or a symbolic reference known
4277 to fit that range (for immediate operands in zero-extending x86-64
4278 instructions).
4280 @item Tv
4281 VSIB address operand.
4283 @item Ts
4284 Address operand without segment register.
4286 @end table
4288 @item Xstormy16---@file{config/stormy16/stormy16.h}
4289 @table @code
4290 @item a
4291 Register r0.
4293 @item b
4294 Register r1.
4296 @item c
4297 Register r2.
4299 @item d
4300 Register r8.
4302 @item e
4303 Registers r0 through r7.
4305 @item t
4306 Registers r0 and r1.
4308 @item y
4309 The carry register.
4311 @item z
4312 Registers r8 and r9.
4314 @item I
4315 A constant between 0 and 3 inclusive.
4317 @item J
4318 A constant that has exactly one bit set.
4320 @item K
4321 A constant that has exactly one bit clear.
4323 @item L
4324 A constant between 0 and 255 inclusive.
4326 @item M
4327 A constant between @minus{}255 and 0 inclusive.
4329 @item N
4330 A constant between @minus{}3 and 0 inclusive.
4332 @item O
4333 A constant between 1 and 4 inclusive.
4335 @item P
4336 A constant between @minus{}4 and @minus{}1 inclusive.
4338 @item Q
4339 A memory reference that is a stack push.
4341 @item R
4342 A memory reference that is a stack pop.
4344 @item S
4345 A memory reference that refers to a constant address of known value.
4347 @item T
4348 The register indicated by Rx (not implemented yet).
4350 @item U
4351 A constant that is not between 2 and 15 inclusive.
4353 @item Z
4354 The constant 0.
4356 @end table
4358 @item Xtensa---@file{config/xtensa/constraints.md}
4359 @table @code
4360 @item a
4361 General-purpose 32-bit register
4363 @item b
4364 One-bit boolean register
4366 @item A
4367 MAC16 40-bit accumulator register
4369 @item I
4370 Signed 12-bit integer constant, for use in MOVI instructions
4372 @item J
4373 Signed 8-bit integer constant, for use in ADDI instructions
4375 @item K
4376 Integer constant valid for BccI instructions
4378 @item L
4379 Unsigned constant valid for BccUI instructions
4381 @end table
4383 @end table
4385 @ifset INTERNALS
4386 @node Disable Insn Alternatives
4387 @subsection Disable insn alternatives using the @code{enabled} attribute
4388 @cindex enabled
4390 There are three insn attributes that may be used to selectively disable
4391 instruction alternatives:
4393 @table @code
4394 @item enabled
4395 Says whether an alternative is available on the current subtarget.
4397 @item preferred_for_size
4398 Says whether an enabled alternative should be used in code that is
4399 optimized for size.
4401 @item preferred_for_speed
4402 Says whether an enabled alternative should be used in code that is
4403 optimized for speed.
4404 @end table
4406 All these attributes should use @code{(const_int 1)} to allow an alternative
4407 or @code{(const_int 0)} to disallow it.  The attributes must be a static
4408 property of the subtarget; they cannot for example depend on the
4409 current operands, on the current optimization level, on the location
4410 of the insn within the body of a loop, on whether register allocation
4411 has finished, or on the current compiler pass.
4413 The @code{enabled} attribute is a correctness property.  It tells GCC to act
4414 as though the disabled alternatives were never defined in the first place.
4415 This is useful when adding new instructions to an existing pattern in
4416 cases where the new instructions are only available for certain cpu
4417 architecture levels (typically mapped to the @code{-march=} command-line
4418 option).
4420 In contrast, the @code{preferred_for_size} and @code{preferred_for_speed}
4421 attributes are strong optimization hints rather than correctness properties.
4422 @code{preferred_for_size} tells GCC which alternatives to consider when
4423 adding or modifying an instruction that GCC wants to optimize for size.
4424 @code{preferred_for_speed} does the same thing for speed.  Note that things
4425 like code motion can lead to cases where code optimized for size uses
4426 alternatives that are not preferred for size, and similarly for speed.
4428 Although @code{define_insn}s can in principle specify the @code{enabled}
4429 attribute directly, it is often clearer to have subsiduary attributes
4430 for each architectural feature of interest.  The @code{define_insn}s
4431 can then use these subsiduary attributes to say which alternatives
4432 require which features.  The example below does this for @code{cpu_facility}.
4434 E.g. the following two patterns could easily be merged using the @code{enabled}
4435 attribute:
4437 @smallexample
4439 (define_insn "*movdi_old"
4440   [(set (match_operand:DI 0 "register_operand" "=d")
4441         (match_operand:DI 1 "register_operand" " d"))]
4442   "!TARGET_NEW"
4443   "lgr %0,%1")
4445 (define_insn "*movdi_new"
4446   [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4447         (match_operand:DI 1 "register_operand" " d,d,f"))]
4448   "TARGET_NEW"
4449   "@@
4450    lgr  %0,%1
4451    ldgr %0,%1
4452    lgdr %0,%1")
4454 @end smallexample
4458 @smallexample
4460 (define_insn "*movdi_combined"
4461   [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4462         (match_operand:DI 1 "register_operand" " d,d,f"))]
4463   ""
4464   "@@
4465    lgr  %0,%1
4466    ldgr %0,%1
4467    lgdr %0,%1"
4468   [(set_attr "cpu_facility" "*,new,new")])
4470 @end smallexample
4472 with the @code{enabled} attribute defined like this:
4474 @smallexample
4476 (define_attr "cpu_facility" "standard,new" (const_string "standard"))
4478 (define_attr "enabled" ""
4479   (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
4480          (and (eq_attr "cpu_facility" "new")
4481               (ne (symbol_ref "TARGET_NEW") (const_int 0)))
4482          (const_int 1)]
4483         (const_int 0)))
4485 @end smallexample
4487 @end ifset
4489 @ifset INTERNALS
4490 @node Define Constraints
4491 @subsection Defining Machine-Specific Constraints
4492 @cindex defining constraints
4493 @cindex constraints, defining
4495 Machine-specific constraints fall into two categories: register and
4496 non-register constraints.  Within the latter category, constraints
4497 which allow subsets of all possible memory or address operands should
4498 be specially marked, to give @code{reload} more information.
4500 Machine-specific constraints can be given names of arbitrary length,
4501 but they must be entirely composed of letters, digits, underscores
4502 (@samp{_}), and angle brackets (@samp{< >}).  Like C identifiers, they
4503 must begin with a letter or underscore.
4505 In order to avoid ambiguity in operand constraint strings, no
4506 constraint can have a name that begins with any other constraint's
4507 name.  For example, if @code{x} is defined as a constraint name,
4508 @code{xy} may not be, and vice versa.  As a consequence of this rule,
4509 no constraint may begin with one of the generic constraint letters:
4510 @samp{E F V X g i m n o p r s}.
4512 Register constraints correspond directly to register classes.
4513 @xref{Register Classes}.  There is thus not much flexibility in their
4514 definitions.
4516 @deffn {MD Expression} define_register_constraint name regclass docstring
4517 All three arguments are string constants.
4518 @var{name} is the name of the constraint, as it will appear in
4519 @code{match_operand} expressions.  If @var{name} is a multi-letter
4520 constraint its length shall be the same for all constraints starting
4521 with the same letter.  @var{regclass} can be either the
4522 name of the corresponding register class (@pxref{Register Classes}),
4523 or a C expression which evaluates to the appropriate register class.
4524 If it is an expression, it must have no side effects, and it cannot
4525 look at the operand.  The usual use of expressions is to map some
4526 register constraints to @code{NO_REGS} when the register class
4527 is not available on a given subarchitecture.
4529 @var{docstring} is a sentence documenting the meaning of the
4530 constraint.  Docstrings are explained further below.
4531 @end deffn
4533 Non-register constraints are more like predicates: the constraint
4534 definition gives a boolean expression which indicates whether the
4535 constraint matches.
4537 @deffn {MD Expression} define_constraint name docstring exp
4538 The @var{name} and @var{docstring} arguments are the same as for
4539 @code{define_register_constraint}, but note that the docstring comes
4540 immediately after the name for these expressions.  @var{exp} is an RTL
4541 expression, obeying the same rules as the RTL expressions in predicate
4542 definitions.  @xref{Defining Predicates}, for details.  If it
4543 evaluates true, the constraint matches; if it evaluates false, it
4544 doesn't. Constraint expressions should indicate which RTL codes they
4545 might match, just like predicate expressions.
4547 @code{match_test} C expressions have access to the
4548 following variables:
4550 @table @var
4551 @item op
4552 The RTL object defining the operand.
4553 @item mode
4554 The machine mode of @var{op}.
4555 @item ival
4556 @samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
4557 @item hval
4558 @samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
4559 @code{const_double}.
4560 @item lval
4561 @samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
4562 @code{const_double}.
4563 @item rval
4564 @samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
4565 @code{const_double}.
4566 @end table
4568 The @var{*val} variables should only be used once another piece of the
4569 expression has verified that @var{op} is the appropriate kind of RTL
4570 object.
4571 @end deffn
4573 Most non-register constraints should be defined with
4574 @code{define_constraint}.  The remaining two definition expressions
4575 are only appropriate for constraints that should be handled specially
4576 by @code{reload} if they fail to match.
4578 @deffn {MD Expression} define_memory_constraint name docstring exp
4579 Use this expression for constraints that match a subset of all memory
4580 operands: that is, @code{reload} can make them match by converting the
4581 operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
4582 base register (from the register class specified by
4583 @code{BASE_REG_CLASS}, @pxref{Register Classes}).
4585 For example, on the S/390, some instructions do not accept arbitrary
4586 memory references, but only those that do not make use of an index
4587 register.  The constraint letter @samp{Q} is defined to represent a
4588 memory address of this type.  If @samp{Q} is defined with
4589 @code{define_memory_constraint}, a @samp{Q} constraint can handle any
4590 memory operand, because @code{reload} knows it can simply copy the
4591 memory address into a base register if required.  This is analogous to
4592 the way an @samp{o} constraint can handle any memory operand.
4594 The syntax and semantics are otherwise identical to
4595 @code{define_constraint}.
4596 @end deffn
4598 @deffn {MD Expression} define_special_memory_constraint name docstring exp
4599 Use this expression for constraints that match a subset of all memory
4600 operands: that is, @code{reload} cannot make them match by reloading
4601 the address as it is described for @code{define_memory_constraint} or
4602 such address reload is undesirable with the performance point of view.
4604 For example, @code{define_special_memory_constraint} can be useful if
4605 specifically aligned memory is necessary or desirable for some insn
4606 operand.
4608 The syntax and semantics are otherwise identical to
4609 @code{define_memory_constraint}.
4610 @end deffn
4612 @deffn {MD Expression} define_relaxed_memory_constraint name docstring exp
4613 The test expression in a @code{define_memory_constraint} can assume
4614 that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside
4615 a @code{mem} rtx and so it does not need to test this condition itself.
4616 In other words, a @code{define_memory_constraint} test of the form:
4618 @smallexample
4619 (match_test "mem")
4620 @end smallexample
4622 is enough to test whether an rtx is a @code{mem} @emph{and} whether
4623 its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually
4624 @samp{'m'}).  Thus the conditions imposed by a @code{define_memory_constraint}
4625 always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}.
4627 However, it is sometimes useful to define memory constraints that allow
4628 addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}.
4629 @code{define_relaxed_memory_constraint} exists for this case.
4630 The test expression in a @code{define_relaxed_memory_constraint} is
4631 applied with no preconditions, so that the expression can determine
4632 ``from scratch'' exactly which addresses are valid and which are not.
4634 The syntax and semantics are otherwise identical to
4635 @code{define_memory_constraint}.
4636 @end deffn
4638 @deffn {MD Expression} define_address_constraint name docstring exp
4639 Use this expression for constraints that match a subset of all address
4640 operands: that is, @code{reload} can make the constraint match by
4641 converting the operand to the form @samp{@w{(reg @var{X})}}, again
4642 with @var{X} a base register.
4644 Constraints defined with @code{define_address_constraint} can only be
4645 used with the @code{address_operand} predicate, or machine-specific
4646 predicates that work the same way.  They are treated analogously to
4647 the generic @samp{p} constraint.
4649 The syntax and semantics are otherwise identical to
4650 @code{define_constraint}.
4651 @end deffn
4653 For historical reasons, names beginning with the letters @samp{G H}
4654 are reserved for constraints that match only @code{const_double}s, and
4655 names beginning with the letters @samp{I J K L M N O P} are reserved
4656 for constraints that match only @code{const_int}s.  This may change in
4657 the future.  For the time being, constraints with these names must be
4658 written in a stylized form, so that @code{genpreds} can tell you did
4659 it correctly:
4661 @smallexample
4662 @group
4663 (define_constraint "[@var{GHIJKLMNOP}]@dots{}"
4664   "@var{doc}@dots{}"
4665   (and (match_code "const_int")  ; @r{@code{const_double} for G/H}
4666        @var{condition}@dots{}))            ; @r{usually a @code{match_test}}
4667 @end group
4668 @end smallexample
4669 @c the semicolons line up in the formatted manual
4671 It is fine to use names beginning with other letters for constraints
4672 that match @code{const_double}s or @code{const_int}s.
4674 Each docstring in a constraint definition should be one or more complete
4675 sentences, marked up in Texinfo format.  @emph{They are currently unused.}
4676 In the future they will be copied into the GCC manual, in @ref{Machine
4677 Constraints}, replacing the hand-maintained tables currently found in
4678 that section.  Also, in the future the compiler may use this to give
4679 more helpful diagnostics when poor choice of @code{asm} constraints
4680 causes a reload failure.
4682 If you put the pseudo-Texinfo directive @samp{@@internal} at the
4683 beginning of a docstring, then (in the future) it will appear only in
4684 the internals manual's version of the machine-specific constraint tables.
4685 Use this for constraints that should not appear in @code{asm} statements.
4687 @node C Constraint Interface
4688 @subsection Testing constraints from C
4689 @cindex testing constraints
4690 @cindex constraints, testing
4692 It is occasionally useful to test a constraint from C code rather than
4693 implicitly via the constraint string in a @code{match_operand}.  The
4694 generated file @file{tm_p.h} declares a few interfaces for working
4695 with constraints.  At present these are defined for all constraints
4696 except @code{g} (which is equivalent to @code{general_operand}).
4698 Some valid constraint names are not valid C identifiers, so there is a
4699 mangling scheme for referring to them from C@.  Constraint names that
4700 do not contain angle brackets or underscores are left unchanged.
4701 Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and
4702 each @samp{>} with @samp{_g}.  Here are some examples:
4704 @c the @c's prevent double blank lines in the printed manual.
4705 @example
4706 @multitable {Original} {Mangled}
4707 @item @strong{Original} @tab @strong{Mangled}  @c
4708 @item @code{x}     @tab @code{x}       @c
4709 @item @code{P42x}  @tab @code{P42x}    @c
4710 @item @code{P4_x}  @tab @code{P4__x}   @c
4711 @item @code{P4>x}  @tab @code{P4_gx}   @c
4712 @item @code{P4>>}  @tab @code{P4_g_g}  @c
4713 @item @code{P4_g>} @tab @code{P4__g_g} @c
4714 @end multitable
4715 @end example
4717 Throughout this section, the variable @var{c} is either a constraint
4718 in the abstract sense, or a constant from @code{enum constraint_num};
4719 the variable @var{m} is a mangled constraint name (usually as part of
4720 a larger identifier).
4722 @deftp Enum constraint_num
4723 For each constraint except @code{g}, there is a corresponding
4724 enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
4725 constraint.  Functions that take an @code{enum constraint_num} as an
4726 argument expect one of these constants.
4727 @end deftp
4729 @deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
4730 For each non-register constraint @var{m} except @code{g}, there is
4731 one of these functions; it returns @code{true} if @var{exp} satisfies the
4732 constraint.  These functions are only visible if @file{rtl.h} was included
4733 before @file{tm_p.h}.
4734 @end deftypefun
4736 @deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
4737 Like the @code{satisfies_constraint_@var{m}} functions, but the
4738 constraint to test is given as an argument, @var{c}.  If @var{c}
4739 specifies a register constraint, this function will always return
4740 @code{false}.
4741 @end deftypefun
4743 @deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c})
4744 Returns the register class associated with @var{c}.  If @var{c} is not
4745 a register constraint, or those registers are not available for the
4746 currently selected subtarget, returns @code{NO_REGS}.
4747 @end deftypefun
4749 Here is an example use of @code{satisfies_constraint_@var{m}}.  In
4750 peephole optimizations (@pxref{Peephole Definitions}), operand
4751 constraint strings are ignored, so if there are relevant constraints,
4752 they must be tested in the C condition.  In the example, the
4753 optimization is applied if operand 2 does @emph{not} satisfy the
4754 @samp{K} constraint.  (This is a simplified version of a peephole
4755 definition from the i386 machine description.)
4757 @smallexample
4758 (define_peephole2
4759   [(match_scratch:SI 3 "r")
4760    (set (match_operand:SI 0 "register_operand" "")
4761         (mult:SI (match_operand:SI 1 "memory_operand" "")
4762                  (match_operand:SI 2 "immediate_operand" "")))]
4764   "!satisfies_constraint_K (operands[2])"
4766   [(set (match_dup 3) (match_dup 1))
4767    (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]
4769   "")
4770 @end smallexample
4772 @node Standard Names
4773 @section Standard Pattern Names For Generation
4774 @cindex standard pattern names
4775 @cindex pattern names
4776 @cindex names, pattern
4778 Here is a table of the instruction names that are meaningful in the RTL
4779 generation pass of the compiler.  Giving one of these names to an
4780 instruction pattern tells the RTL generation pass that it can use the
4781 pattern to accomplish a certain task.
4783 @table @asis
4784 @cindex @code{mov@var{m}} instruction pattern
4785 @item @samp{mov@var{m}}
4786 Here @var{m} stands for a two-letter machine mode name, in lowercase.
4787 This instruction pattern moves data with that machine mode from operand
4788 1 to operand 0.  For example, @samp{movsi} moves full-word data.
4790 If operand 0 is a @code{subreg} with mode @var{m} of a register whose
4791 own mode is wider than @var{m}, the effect of this instruction is
4792 to store the specified value in the part of the register that corresponds
4793 to mode @var{m}.  Bits outside of @var{m}, but which are within the
4794 same target word as the @code{subreg} are undefined.  Bits which are
4795 outside the target word are left unchanged.
4797 This class of patterns is special in several ways.  First of all, each
4798 of these names up to and including full word size @emph{must} be defined,
4799 because there is no other way to copy a datum from one place to another.
4800 If there are patterns accepting operands in larger modes,
4801 @samp{mov@var{m}} must be defined for integer modes of those sizes.
4803 Second, these patterns are not used solely in the RTL generation pass.
4804 Even the reload pass can generate move insns to copy values from stack
4805 slots into temporary registers.  When it does so, one of the operands is
4806 a hard register and the other is an operand that can need to be reloaded
4807 into a register.
4809 @findex force_reg
4810 Therefore, when given such a pair of operands, the pattern must generate
4811 RTL which needs no reloading and needs no temporary registers---no
4812 registers other than the operands.  For example, if you support the
4813 pattern with a @code{define_expand}, then in such a case the
4814 @code{define_expand} mustn't call @code{force_reg} or any other such
4815 function which might generate new pseudo registers.
4817 This requirement exists even for subword modes on a RISC machine where
4818 fetching those modes from memory normally requires several insns and
4819 some temporary registers.
4821 @findex change_address
4822 During reload a memory reference with an invalid address may be passed
4823 as an operand.  Such an address will be replaced with a valid address
4824 later in the reload pass.  In this case, nothing may be done with the
4825 address except to use it as it stands.  If it is copied, it will not be
4826 replaced with a valid address.  No attempt should be made to make such
4827 an address into a valid address and no routine (such as
4828 @code{change_address}) that will do so may be called.  Note that
4829 @code{general_operand} will fail when applied to such an address.
4831 @findex reload_in_progress
4832 The global variable @code{reload_in_progress} (which must be explicitly
4833 declared if required) can be used to determine whether such special
4834 handling is required.
4836 The variety of operands that have reloads depends on the rest of the
4837 machine description, but typically on a RISC machine these can only be
4838 pseudo registers that did not get hard registers, while on other
4839 machines explicit memory references will get optional reloads.
4841 If a scratch register is required to move an object to or from memory,
4842 it can be allocated using @code{gen_reg_rtx} prior to life analysis.
4844 If there are cases which need scratch registers during or after reload,
4845 you must provide an appropriate secondary_reload target hook.
4847 @findex can_create_pseudo_p
4848 The macro @code{can_create_pseudo_p} can be used to determine if it
4849 is unsafe to create new pseudo registers.  If this variable is nonzero, then
4850 it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
4852 The constraints on a @samp{mov@var{m}} must permit moving any hard
4853 register to any other hard register provided that
4854 @code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
4855 @code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
4856 of 2.
4858 It is obligatory to support floating point @samp{mov@var{m}}
4859 instructions into and out of any registers that can hold fixed point
4860 values, because unions and structures (which have modes @code{SImode} or
4861 @code{DImode}) can be in those registers and they may have floating
4862 point members.
4864 There may also be a need to support fixed point @samp{mov@var{m}}
4865 instructions in and out of floating point registers.  Unfortunately, I
4866 have forgotten why this was so, and I don't know whether it is still
4867 true.  If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in
4868 floating point registers, then the constraints of the fixed point
4869 @samp{mov@var{m}} instructions must be designed to avoid ever trying to
4870 reload into a floating point register.
4872 @cindex @code{reload_in} instruction pattern
4873 @cindex @code{reload_out} instruction pattern
4874 @item @samp{reload_in@var{m}}
4875 @itemx @samp{reload_out@var{m}}
4876 These named patterns have been obsoleted by the target hook
4877 @code{secondary_reload}.
4879 Like @samp{mov@var{m}}, but used when a scratch register is required to
4880 move between operand 0 and operand 1.  Operand 2 describes the scratch
4881 register.  See the discussion of the @code{SECONDARY_RELOAD_CLASS}
4882 macro in @pxref{Register Classes}.
4884 There are special restrictions on the form of the @code{match_operand}s
4885 used in these patterns.  First, only the predicate for the reload
4886 operand is examined, i.e., @code{reload_in} examines operand 1, but not
4887 the predicates for operand 0 or 2.  Second, there may be only one
4888 alternative in the constraints.  Third, only a single register class
4889 letter may be used for the constraint; subsequent constraint letters
4890 are ignored.  As a special exception, an empty constraint string
4891 matches the @code{ALL_REGS} register class.  This may relieve ports
4892 of the burden of defining an @code{ALL_REGS} constraint letter just
4893 for these patterns.
4895 @cindex @code{movstrict@var{m}} instruction pattern
4896 @item @samp{movstrict@var{m}}
4897 Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
4898 with mode @var{m} of a register whose natural mode is wider,
4899 the @samp{movstrict@var{m}} instruction is guaranteed not to alter
4900 any of the register except the part which belongs to mode @var{m}.
4902 @cindex @code{movmisalign@var{m}} instruction pattern
4903 @item @samp{movmisalign@var{m}}
4904 This variant of a move pattern is designed to load or store a value
4905 from a memory address that is not naturally aligned for its mode.
4906 For a store, the memory will be in operand 0; for a load, the memory
4907 will be in operand 1.  The other operand is guaranteed not to be a
4908 memory, so that it's easy to tell whether this is a load or store.
4910 This pattern is used by the autovectorizer, and when expanding a
4911 @code{MISALIGNED_INDIRECT_REF} expression.
4913 @cindex @code{load_multiple} instruction pattern
4914 @item @samp{load_multiple}
4915 Load several consecutive memory locations into consecutive registers.
4916 Operand 0 is the first of the consecutive registers, operand 1
4917 is the first memory location, and operand 2 is a constant: the
4918 number of consecutive registers.
4920 Define this only if the target machine really has such an instruction;
4921 do not define this if the most efficient way of loading consecutive
4922 registers from memory is to do them one at a time.
4924 On some machines, there are restrictions as to which consecutive
4925 registers can be stored into memory, such as particular starting or
4926 ending register numbers or only a range of valid counts.  For those
4927 machines, use a @code{define_expand} (@pxref{Expander Definitions})
4928 and make the pattern fail if the restrictions are not met.
4930 Write the generated insn as a @code{parallel} with elements being a
4931 @code{set} of one register from the appropriate memory location (you may
4932 also need @code{use} or @code{clobber} elements).  Use a
4933 @code{match_parallel} (@pxref{RTL Template}) to recognize the insn.  See
4934 @file{rs6000.md} for examples of the use of this insn pattern.
4936 @cindex @samp{store_multiple} instruction pattern
4937 @item @samp{store_multiple}
4938 Similar to @samp{load_multiple}, but store several consecutive registers
4939 into consecutive memory locations.  Operand 0 is the first of the
4940 consecutive memory locations, operand 1 is the first register, and
4941 operand 2 is a constant: the number of consecutive registers.
4943 @cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
4944 @item @samp{vec_load_lanes@var{m}@var{n}}
4945 Perform an interleaved load of several vectors from memory operand 1
4946 into register operand 0.  Both operands have mode @var{m}.  The register
4947 operand is viewed as holding consecutive vectors of mode @var{n},
4948 while the memory operand is a flat array that contains the same number
4949 of elements.  The operation is equivalent to:
4951 @smallexample
4952 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4953 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4954   for (i = 0; i < c; i++)
4955     operand0[i][j] = operand1[j * c + i];
4956 @end smallexample
4958 For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
4959 from memory into a register of mode @samp{TI}@.  The register
4960 contains two consecutive vectors of mode @samp{V4HI}@.
4962 This pattern can only be used if:
4963 @smallexample
4964 TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
4965 @end smallexample
4966 is true.  GCC assumes that, if a target supports this kind of
4967 instruction for some mode @var{n}, it also supports unaligned
4968 loads for vectors of mode @var{n}.
4970 This pattern is not allowed to @code{FAIL}.
4972 @cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern
4973 @item @samp{vec_mask_load_lanes@var{m}@var{n}}
4974 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
4975 mask operand (operand 2) that specifies which elements of the destination
4976 vectors should be loaded.  Other elements of the destination
4977 vectors are set to zero.  The operation is equivalent to:
4979 @smallexample
4980 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4981 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4982   if (operand2[j])
4983     for (i = 0; i < c; i++)
4984       operand0[i][j] = operand1[j * c + i];
4985   else
4986     for (i = 0; i < c; i++)
4987       operand0[i][j] = 0;
4988 @end smallexample
4990 This pattern is not allowed to @code{FAIL}.
4992 @cindex @code{vec_mask_len_load_lanes@var{m}@var{n}} instruction pattern
4993 @item @samp{vec_mask_len_load_lanes@var{m}@var{n}}
4994 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
4995 mask operand (operand 2), length operand (operand 3) as well as bias operand (operand 4)
4996 that specifies which elements of the destination vectors should be loaded.
4997 Other elements of the destination vectors are undefined.  The operation is equivalent to:
4999 @smallexample
5000 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5001 for (j = 0; j < operand3 + operand4; j++)
5002   if (operand2[j])
5003     for (i = 0; i < c; i++)
5004       operand0[i][j] = operand1[j * c + i];
5005 @end smallexample
5007 This pattern is not allowed to @code{FAIL}.
5009 @cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
5010 @item @samp{vec_store_lanes@var{m}@var{n}}
5011 Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
5012 and register operands reversed.  That is, the instruction is
5013 equivalent to:
5015 @smallexample
5016 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5017 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5018   for (i = 0; i < c; i++)
5019     operand0[j * c + i] = operand1[i][j];
5020 @end smallexample
5022 for a memory operand 0 and register operand 1.
5024 This pattern is not allowed to @code{FAIL}.
5026 @cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern
5027 @item @samp{vec_mask_store_lanes@var{m}@var{n}}
5028 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
5029 mask operand (operand 2) that specifies which elements of the source
5030 vectors should be stored.  The operation is equivalent to:
5032 @smallexample
5033 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5034 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5035   if (operand2[j])
5036     for (i = 0; i < c; i++)
5037       operand0[j * c + i] = operand1[i][j];
5038 @end smallexample
5040 This pattern is not allowed to @code{FAIL}.
5042 @cindex @code{vec_mask_len_store_lanes@var{m}@var{n}} instruction pattern
5043 @item @samp{vec_mask_len_store_lanes@var{m}@var{n}}
5044 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
5045 mask operand (operand 2), length operand (operand 3) as well as bias operand (operand 4)
5046 that specifies which elements of the source vectors should be stored.
5047 The operation is equivalent to:
5049 @smallexample
5050 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5051 for (j = 0; j < operand3 + operand4; j++)
5052   if (operand2[j])
5053     for (i = 0; i < c; i++)
5054       operand0[j * c + i] = operand1[i][j];
5055 @end smallexample
5057 This pattern is not allowed to @code{FAIL}.
5059 @cindex @code{gather_load@var{m}@var{n}} instruction pattern
5060 @item @samp{gather_load@var{m}@var{n}}
5061 Load several separate memory locations into a vector of mode @var{m}.
5062 Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n}
5063 containing offsets from that base.  Operand 0 is a destination vector with
5064 the same number of elements as @var{n}.  For each element index @var{i}:
5066 @itemize @bullet
5067 @item
5068 extend the offset element @var{i} to address width, using zero
5069 extension if operand 3 is 1 and sign extension if operand 3 is zero;
5070 @item
5071 multiply the extended offset by operand 4;
5072 @item
5073 add the result to the base; and
5074 @item
5075 load the value at that address into element @var{i} of operand 0.
5076 @end itemize
5078 The value of operand 3 does not matter if the offsets are already
5079 address width.
5081 @cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern
5082 @item @samp{mask_gather_load@var{m}@var{n}}
5083 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as
5084 operand 5.  Bit @var{i} of the mask is set if element @var{i}
5085 of the result should be loaded from memory and clear if element @var{i}
5086 of the result should be set to zero.
5088 @cindex @code{mask_len_gather_load@var{m}@var{n}} instruction pattern
5089 @item @samp{mask_len_gather_load@var{m}@var{n}}
5090 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand (operand 5),
5091 a len operand (operand 6) as well as a bias operand (operand 7).  Similar to mask_len_load,
5092 the instruction loads at most (operand 6 + operand 7) elements from memory.
5093 Bit @var{i} of the mask is set if element @var{i} of the result should
5094 be loaded from memory and clear if element @var{i} of the result should be undefined.
5095 Mask elements @var{i} with @var{i} > (operand 6 + operand 7) are ignored.
5097 @cindex @code{scatter_store@var{m}@var{n}} instruction pattern
5098 @item @samp{scatter_store@var{m}@var{n}}
5099 Store a vector of mode @var{m} into several distinct memory locations.
5100 Operand 0 is a scalar base address and operand 1 is a vector of mode
5101 @var{n} containing offsets from that base.  Operand 4 is the vector of
5102 values that should be stored, which has the same number of elements as
5103 @var{n}.  For each element index @var{i}:
5105 @itemize @bullet
5106 @item
5107 extend the offset element @var{i} to address width, using zero
5108 extension if operand 2 is 1 and sign extension if operand 2 is zero;
5109 @item
5110 multiply the extended offset by operand 3;
5111 @item
5112 add the result to the base; and
5113 @item
5114 store element @var{i} of operand 4 to that address.
5115 @end itemize
5117 The value of operand 2 does not matter if the offsets are already
5118 address width.
5120 @cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern
5121 @item @samp{mask_scatter_store@var{m}@var{n}}
5122 Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as
5123 operand 5.  Bit @var{i} of the mask is set if element @var{i}
5124 of the result should be stored to memory.
5126 @cindex @code{mask_len_scatter_store@var{m}@var{n}} instruction pattern
5127 @item @samp{mask_len_scatter_store@var{m}@var{n}}
5128 Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand (operand 5),
5129 a len operand (operand 6) as well as a bias operand (operand 7).  The instruction stores
5130 at most (operand 6 + operand 7) elements of (operand 4) to memory.
5131 Bit @var{i} of the mask is set if element @var{i} of (operand 4) should be stored.
5132 Mask elements @var{i} with @var{i} > (operand 6 + operand 7) are ignored.
5134 @cindex @code{vec_set@var{m}} instruction pattern
5135 @item @samp{vec_set@var{m}}
5136 Set given field in the vector value.  Operand 0 is the vector to modify,
5137 operand 1 is new value of field and operand 2 specify the field index.
5139 This pattern is not allowed to @code{FAIL}.
5141 @cindex @code{vec_extract@var{m}@var{n}} instruction pattern
5142 @item @samp{vec_extract@var{m}@var{n}}
5143 Extract given field from the vector value.  Operand 1 is the vector, operand 2
5144 specify field index and operand 0 place to store value into.  The
5145 @var{n} mode is the mode of the field or vector of fields that should be
5146 extracted, should be either element mode of the vector mode @var{m}, or
5147 a vector mode with the same element mode and smaller number of elements.
5148 If @var{n} is a vector mode the index is counted in multiples of
5149 mode @var{n}.
5151 This pattern is not allowed to @code{FAIL}.
5153 @cindex @code{vec_init@var{m}@var{n}} instruction pattern
5154 @item @samp{vec_init@var{m}@var{n}}
5155 Initialize the vector to given values.  Operand 0 is the vector to initialize
5156 and operand 1 is parallel containing values for individual fields.  The
5157 @var{n} mode is the mode of the elements, should be either element mode of
5158 the vector mode @var{m}, or a vector mode with the same element mode and
5159 smaller number of elements.
5161 @cindex @code{vec_duplicate@var{m}} instruction pattern
5162 @item @samp{vec_duplicate@var{m}}
5163 Initialize vector output operand 0 so that each element has the value given
5164 by scalar input operand 1.  The vector has mode @var{m} and the scalar has
5165 the mode appropriate for one element of @var{m}.
5167 This pattern only handles duplicates of non-constant inputs.  Constant
5168 vectors go through the @code{mov@var{m}} pattern instead.
5170 This pattern is not allowed to @code{FAIL}.
5172 @cindex @code{vec_series@var{m}} instruction pattern
5173 @item @samp{vec_series@var{m}}
5174 Initialize vector output operand 0 so that element @var{i} is equal to
5175 operand 1 plus @var{i} times operand 2.  In other words, create a linear
5176 series whose base value is operand 1 and whose step is operand 2.
5178 The vector output has mode @var{m} and the scalar inputs have the mode
5179 appropriate for one element of @var{m}.  This pattern is not used for
5180 floating-point vectors, in order to avoid having to specify the
5181 rounding behavior for @var{i} > 1.
5183 This pattern is not allowed to @code{FAIL}.
5185 @cindex @code{while_ult@var{m}@var{n}} instruction pattern
5186 @item @code{while_ult@var{m}@var{n}}
5187 Set operand 0 to a mask that is true while incrementing operand 1
5188 gives a value that is less than operand 2, for a vector length up to operand 3.
5189 Operand 0 has mode @var{n} and operands 1 and 2 are scalar integers of mode
5190 @var{m}.  Operand 3 should be omitted when @var{n} is a vector mode, and
5191 a @code{CONST_INT} otherwise.  The operation for vector modes is equivalent to:
5193 @smallexample
5194 operand0[0] = operand1 < operand2;
5195 for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++)
5196   operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
5197 @end smallexample
5199 And for non-vector modes the operation is equivalent to:
5201 @smallexample
5202 operand0[0] = operand1 < operand2;
5203 for (i = 1; i < operand3; i++)
5204   operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
5205 @end smallexample
5207 @cindex @code{select_vl@var{m}} instruction pattern
5208 @item @code{select_vl@var{m}}
5209 Set operand 0 to the number of scalar iterations that should be handled
5210 by one iteration of a vector loop.  Operand 1 is the total number of
5211 scalar iterations that the loop needs to process and operand 2 is a
5212 maximum bound on the result (also known as the maximum ``vectorization
5213 factor'').
5215 The maximum value of operand 0 is given by:
5216 @smallexample
5217 operand0 = MIN (operand1, operand2)
5218 @end smallexample
5219 However, targets might choose a lower value than this, based on
5220 target-specific criteria.  Each iteration of the vector loop might
5221 therefore process a different number of scalar iterations, which in turn
5222 means that induction variables will have a variable step.  Because of
5223 this, it is generally not useful to define this instruction if it will
5224 always calculate the maximum value.
5226 This optab is only useful on targets that implement @samp{len_load_@var{m}}
5227 and/or @samp{len_store_@var{m}}.
5229 @cindex @code{check_raw_ptrs@var{m}} instruction pattern
5230 @item @samp{check_raw_ptrs@var{m}}
5231 Check whether, given two pointers @var{a} and @var{b} and a length @var{len},
5232 a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes
5233 at @var{b} can be split into interleaved byte accesses
5234 @samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}}
5235 without affecting the dependencies between the bytes.  Set operand 0
5236 to true if the split is possible and false otherwise.
5238 Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len}
5239 respectively.  Operand 4 is a constant integer that provides the known
5240 common alignment of @var{a} and @var{b}.  All inputs have mode @var{m}.
5242 This split is possible if:
5244 @smallexample
5245 @var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a}
5246 @end smallexample
5248 You should only define this pattern if the target has a way of accelerating
5249 the test without having to do the individual comparisons.
5251 @cindex @code{check_war_ptrs@var{m}} instruction pattern
5252 @item @samp{check_war_ptrs@var{m}}
5253 Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round.
5254 The split is possible in this case if:
5256 @smallexample
5257 @var{b} <= @var{a} || @var{a} + @var{len} <= @var{b}
5258 @end smallexample
5260 @cindex @code{vec_cmp@var{m}@var{n}} instruction pattern
5261 @item @samp{vec_cmp@var{m}@var{n}}
5262 Output a vector comparison.  Operand 0 of mode @var{n} is the destination for
5263 predicate in operand 1 which is a signed vector comparison with operands of
5264 mode @var{m} in operands 2 and 3.  Predicate is computed by element-wise
5265 evaluation of the vector comparison with a truth value of all-ones and a false
5266 value of all-zeros.
5268 @cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern
5269 @item @samp{vec_cmpu@var{m}@var{n}}
5270 Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison.
5272 @cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern
5273 @item @samp{vec_cmpeq@var{m}@var{n}}
5274 Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality
5275 vector comparison only.  If @code{vec_cmp@var{m}@var{n}}
5276 or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported,
5277 it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is
5278 no need to define this instruction pattern if the others are supported.
5280 @cindex @code{vcond@var{m}@var{n}} instruction pattern
5281 @item @samp{vcond@var{m}@var{n}}
5282 Output a conditional vector move.  Operand 0 is the destination to
5283 receive a combination of operand 1 and operand 2, which are of mode @var{m},
5284 dependent on the outcome of the predicate in operand 3 which is a signed
5285 vector comparison with operands of mode @var{n} in operands 4 and 5.  The
5286 modes @var{m} and @var{n} should have the same size.  Operand 0
5287 will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk}
5288 where @var{msk} is computed by element-wise evaluation of the vector
5289 comparison with a truth value of all-ones and a false value of all-zeros.
5291 @cindex @code{vcondu@var{m}@var{n}} instruction pattern
5292 @item @samp{vcondu@var{m}@var{n}}
5293 Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector
5294 comparison.
5296 @cindex @code{vcondeq@var{m}@var{n}} instruction pattern
5297 @item @samp{vcondeq@var{m}@var{n}}
5298 Similar to @code{vcond@var{m}@var{n}} but performs equality or
5299 non-equality vector comparison only.  If @code{vcond@var{m}@var{n}}
5300 or @code{vcondu@var{m}@var{n}} instruction pattern is supported,
5301 it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is
5302 no need to define this instruction pattern if the others are supported.
5304 @cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern
5305 @item @samp{vcond_mask_@var{m}@var{n}}
5306 Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed
5307 result of vector comparison.
5309 @cindex @code{vcond_mask_len_@var{m}@var{n}} instruction pattern
5310 @item @samp{vcond_mask_@var{m}@var{n}}
5311 Set each element of operand 0 to the corresponding element of operand 2
5312 or operand 3.  Choose operand 2 if both the element index is less than
5313 operand 4 plus operand 5 and the corresponding element of operand 1
5314 is nonzero:
5316 @smallexample
5317 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
5318   op0[i] = i < op4 + op5 && op1[i] ? op2[i] : op3[i];
5319 @end smallexample
5321 Operands 0, 2 and 3 have mode @var{m}.  Operand 1 has mode @var{n}.
5322 Operands 4 and 5 have a target-dependent scalar integer mode.
5324 @cindex @code{maskload@var{m}@var{n}} instruction pattern
5325 @item @samp{maskload@var{m}@var{n}}
5326 Perform a masked load of vector from memory operand 1 of mode @var{m}
5327 into register operand 0.  Mask is provided in register operand 2 of
5328 mode @var{n}.
5330 This pattern is not allowed to @code{FAIL}.
5332 @cindex @code{maskstore@var{m}@var{n}} instruction pattern
5333 @item @samp{maskstore@var{m}@var{n}}
5334 Perform a masked store of vector from register operand 1 of mode @var{m}
5335 into memory operand 0.  Mask is provided in register operand 2 of
5336 mode @var{n}.
5338 This pattern is not allowed to @code{FAIL}.
5340 @cindex @code{len_load_@var{m}} instruction pattern
5341 @item @samp{len_load_@var{m}}
5342 Load (operand 2 + operand 3) elements from memory operand 1
5343 into vector register operand 0, setting the other elements of
5344 operand 0 to undefined values.  Operands 0 and 1 have mode @var{m},
5345 which must be a vector mode.  Operand 2 has whichever integer mode the
5346 target prefers.  Operand 3 conceptually has mode @code{QI}.
5348 Operand 2 can be a variable or a constant amount.  Operand 3 specifies a
5349 constant bias: it is either a constant 0 or a constant -1.  The predicate on
5350 operand 3 must only accept the bias values that the target actually supports.
5351 GCC handles a bias of 0 more efficiently than a bias of -1.
5353 If (operand 2 + operand 3) exceeds the number of elements in mode
5354 @var{m}, the behavior is undefined.
5356 If the target prefers the length to be measured in bytes rather than
5357 elements, it should only implement this pattern for vectors of @code{QI}
5358 elements.
5360 This pattern is not allowed to @code{FAIL}.
5362 @cindex @code{len_store_@var{m}} instruction pattern
5363 @item @samp{len_store_@var{m}}
5364 Store (operand 2 + operand 3) vector elements from vector register operand 1
5365 into memory operand 0, leaving the other elements of
5366 operand 0 unchanged.  Operands 0 and 1 have mode @var{m}, which must be
5367 a vector mode.  Operand 2 has whichever integer mode the target prefers.
5368 Operand 3 conceptually has mode @code{QI}.
5370 Operand 2 can be a variable or a constant amount.  Operand 3 specifies a
5371 constant bias: it is either a constant 0 or a constant -1.  The predicate on
5372 operand 3 must only accept the bias values that the target actually supports.
5373 GCC handles a bias of 0 more efficiently than a bias of -1.
5375 If (operand 2 + operand 3) exceeds the number of elements in mode
5376 @var{m}, the behavior is undefined.
5378 If the target prefers the length to be measured in bytes
5379 rather than elements, it should only implement this pattern for vectors
5380 of @code{QI} elements.
5382 This pattern is not allowed to @code{FAIL}.
5384 @cindex @code{mask_len_load@var{m}@var{n}} instruction pattern
5385 @item @samp{mask_len_load@var{m}@var{n}}
5386 Perform a masked load from the memory location pointed to by operand 1
5387 into register operand 0.  (operand 3 + operand 4) elements are loaded from
5388 memory and other elements in operand 0 are set to undefined values.
5389 This is a combination of len_load and maskload.
5390 Operands 0 and 1 have mode @var{m}, which must be a vector mode.  Operand 3
5391 has whichever integer mode the target prefers.  A mask is specified in
5392 operand 2 which must be of type @var{n}.  The mask has lower precedence than
5393 the length and is itself subject to length masking,
5394 i.e. only mask indices < (operand 3 + operand 4) are used.
5395 Operand 4 conceptually has mode @code{QI}.
5397 Operand 2 can be a variable or a constant amount.  Operand 4 specifies a
5398 constant bias: it is either a constant 0 or a constant -1.  The predicate on
5399 operand 4 must only accept the bias values that the target actually supports.
5400 GCC handles a bias of 0 more efficiently than a bias of -1.
5402 If (operand 2 + operand 4) exceeds the number of elements in mode
5403 @var{m}, the behavior is undefined.
5405 If the target prefers the length to be measured in bytes
5406 rather than elements, it should only implement this pattern for vectors
5407 of @code{QI} elements.
5409 This pattern is not allowed to @code{FAIL}.
5411 @cindex @code{mask_len_store@var{m}@var{n}} instruction pattern
5412 @item @samp{mask_len_store@var{m}@var{n}}
5413 Perform a masked store from vector register operand 1 into memory operand 0.
5414 (operand 3 + operand 4) elements are stored to memory
5415 and leave the other elements of operand 0 unchanged.
5416 This is a combination of len_store and maskstore.
5417 Operands 0 and 1 have mode @var{m}, which must be a vector mode.  Operand 3 has whichever
5418 integer mode the target prefers.  A mask is specified in operand 2 which must be
5419 of type @var{n}.  The mask has lower precedence than the length and is itself subject to
5420 length masking, i.e. only mask indices < (operand 3 + operand 4) are used.
5421 Operand 4 conceptually has mode @code{QI}.
5423 Operand 2 can be a variable or a constant amount.  Operand 3 specifies a
5424 constant bias: it is either a constant 0 or a constant -1.  The predicate on
5425 operand 4 must only accept the bias values that the target actually supports.
5426 GCC handles a bias of 0 more efficiently than a bias of -1.
5428 If (operand 2 + operand 4) exceeds the number of elements in mode
5429 @var{m}, the behavior is undefined.
5431 If the target prefers the length to be measured in bytes
5432 rather than elements, it should only implement this pattern for vectors
5433 of @code{QI} elements.
5435 This pattern is not allowed to @code{FAIL}.
5437 @cindex @code{vec_perm@var{m}} instruction pattern
5438 @item @samp{vec_perm@var{m}}
5439 Output a (variable) vector permutation.  Operand 0 is the destination
5440 to receive elements from operand 1 and operand 2, which are of mode
5441 @var{m}.  Operand 3 is the @dfn{selector}.  It is an integral mode
5442 vector of the same width and number of elements as mode @var{m}.
5444 The input elements are numbered from 0 in operand 1 through
5445 @math{2*@var{N}-1} in operand 2.  The elements of the selector must
5446 be computed modulo @math{2*@var{N}}.  Note that if
5447 @code{rtx_equal_p(operand1, operand2)}, this can be implemented
5448 with just operand 1 and selector elements modulo @var{N}.
5450 In order to make things easy for a number of targets, if there is no
5451 @samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
5452 where @var{q} is a vector of @code{QImode} of the same width as @var{m},
5453 the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
5454 mode @var{q}.
5456 See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs
5457 the analogous operation for constant selectors.
5459 @cindex @code{push@var{m}1} instruction pattern
5460 @item @samp{push@var{m}1}
5461 Output a push instruction.  Operand 0 is value to push.  Used only when
5462 @code{PUSH_ROUNDING} is defined.  For historical reason, this pattern may be
5463 missing and in such case an @code{mov} expander is used instead, with a
5464 @code{MEM} expression forming the push operation.  The @code{mov} expander
5465 method is deprecated.
5467 @cindex @code{add@var{m}3} instruction pattern
5468 @item @samp{add@var{m}3}
5469 Add operand 2 and operand 1, storing the result in operand 0.  All operands
5470 must have mode @var{m}.  This can be used even on two-address machines, by
5471 means of constraints requiring operands 1 and 0 to be the same location.
5473 @cindex @code{ssadd@var{m}3} instruction pattern
5474 @cindex @code{usadd@var{m}3} instruction pattern
5475 @cindex @code{sub@var{m}3} instruction pattern
5476 @cindex @code{sssub@var{m}3} instruction pattern
5477 @cindex @code{ussub@var{m}3} instruction pattern
5478 @cindex @code{mul@var{m}3} instruction pattern
5479 @cindex @code{ssmul@var{m}3} instruction pattern
5480 @cindex @code{usmul@var{m}3} instruction pattern
5481 @cindex @code{div@var{m}3} instruction pattern
5482 @cindex @code{ssdiv@var{m}3} instruction pattern
5483 @cindex @code{udiv@var{m}3} instruction pattern
5484 @cindex @code{usdiv@var{m}3} instruction pattern
5485 @cindex @code{mod@var{m}3} instruction pattern
5486 @cindex @code{umod@var{m}3} instruction pattern
5487 @cindex @code{umin@var{m}3} instruction pattern
5488 @cindex @code{umax@var{m}3} instruction pattern
5489 @cindex @code{and@var{m}3} instruction pattern
5490 @cindex @code{ior@var{m}3} instruction pattern
5491 @cindex @code{xor@var{m}3} instruction pattern
5492 @item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
5493 @itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
5494 @itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
5495 @itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
5496 @itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
5497 @itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
5498 @itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
5499 @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
5500 Similar, for other arithmetic operations.
5502 @cindex @code{addv@var{m}4} instruction pattern
5503 @item @samp{addv@var{m}4}
5504 Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and
5505 emits code to jump to it if signed overflow occurs during the addition.
5506 This pattern is used to implement the built-in functions performing
5507 signed integer addition with overflow checking.
5509 @cindex @code{subv@var{m}4} instruction pattern
5510 @cindex @code{mulv@var{m}4} instruction pattern
5511 @item @samp{subv@var{m}4}, @samp{mulv@var{m}4}
5512 Similar, for other signed arithmetic operations.
5514 @cindex @code{uaddv@var{m}4} instruction pattern
5515 @item @samp{uaddv@var{m}4}
5516 Like @code{addv@var{m}4} but for unsigned addition.  That is to
5517 say, the operation is the same as signed addition but the jump
5518 is taken only on unsigned overflow.
5520 @cindex @code{usubv@var{m}4} instruction pattern
5521 @cindex @code{umulv@var{m}4} instruction pattern
5522 @item @samp{usubv@var{m}4}, @samp{umulv@var{m}4}
5523 Similar, for other unsigned arithmetic operations.
5525 @cindex @code{uaddc@var{m}5} instruction pattern
5526 @item @samp{uaddc@var{m}5}
5527 Adds unsigned operands 2, 3 and 4 (where the last operand is guaranteed to
5528 have only values 0 or 1) together, sets operand 0 to the result of the
5529 addition of the 3 operands and sets operand 1 to 1 iff there was
5530 overflow on the unsigned additions, and to 0 otherwise.  So, it is
5531 an addition with carry in (operand 4) and carry out (operand 1).
5532 All operands have the same mode.
5534 @cindex @code{usubc@var{m}5} instruction pattern
5535 @item @samp{usubc@var{m}5}
5536 Similarly to @samp{uaddc@var{m}5}, except subtracts unsigned operands 3
5537 and 4 from operand 2 instead of adding them.  So, it is
5538 a subtraction with carry/borrow in (operand 4) and carry/borrow out
5539 (operand 1).  All operands have the same mode.
5541 @cindex @code{addptr@var{m}3} instruction pattern
5542 @item @samp{addptr@var{m}3}
5543 Like @code{add@var{m}3} but is guaranteed to only be used for address
5544 calculations.  The expanded code is not allowed to clobber the
5545 condition code.  It only needs to be defined if @code{add@var{m}3}
5546 sets the condition code.  If adds used for address calculations and
5547 normal adds are not compatible it is required to expand a distinct
5548 pattern (e.g.@: using an unspec).  The pattern is used by LRA to emit
5549 address calculations.  @code{add@var{m}3} is used if
5550 @code{addptr@var{m}3} is not defined.
5552 @cindex @code{fma@var{m}4} instruction pattern
5553 @item @samp{fma@var{m}4}
5554 Multiply operand 2 and operand 1, then add operand 3, storing the
5555 result in operand 0 without doing an intermediate rounding step.  All
5556 operands must have mode @var{m}.  This pattern is used to implement
5557 the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from
5558 the ISO C99 standard.
5560 @cindex @code{fms@var{m}4} instruction pattern
5561 @item @samp{fms@var{m}4}
5562 Like @code{fma@var{m}4}, except operand 3 subtracted from the
5563 product instead of added to the product.  This is represented
5564 in the rtl as
5566 @smallexample
5567 (fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
5568 @end smallexample
5570 @cindex @code{fnma@var{m}4} instruction pattern
5571 @item @samp{fnma@var{m}4}
5572 Like @code{fma@var{m}4} except that the intermediate product
5573 is negated before being added to operand 3.  This is represented
5574 in the rtl as
5576 @smallexample
5577 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
5578 @end smallexample
5580 @cindex @code{fnms@var{m}4} instruction pattern
5581 @item @samp{fnms@var{m}4}
5582 Like @code{fms@var{m}4} except that the intermediate product
5583 is negated before subtracting operand 3.  This is represented
5584 in the rtl as
5586 @smallexample
5587 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
5588 @end smallexample
5590 @cindex @code{min@var{m}3} instruction pattern
5591 @cindex @code{max@var{m}3} instruction pattern
5592 @item @samp{smin@var{m}3}, @samp{smax@var{m}3}
5593 Signed minimum and maximum operations.  When used with floating point,
5594 if both operands are zeros, or if either operand is @code{NaN}, then
5595 it is unspecified which of the two operands is returned as the result.
5597 @cindex @code{fmin@var{m}3} instruction pattern
5598 @cindex @code{fmax@var{m}3} instruction pattern
5599 @item @samp{fmin@var{m}3}, @samp{fmax@var{m}3}
5600 IEEE-conformant minimum and maximum operations.  If one operand is a quiet
5601 @code{NaN}, then the other operand is returned.  If both operands are quiet
5602 @code{NaN}, then a quiet @code{NaN} is returned.  In the case when gcc supports
5603 signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is
5604 raised and a quiet @code{NaN} is returned.
5606 All operands have mode @var{m}, which is a scalar or vector
5607 floating-point mode.  These patterns are not allowed to @code{FAIL}.
5609 @cindex @code{reduc_smin_scal_@var{m}} instruction pattern
5610 @cindex @code{reduc_smax_scal_@var{m}} instruction pattern
5611 @item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}}
5612 Find the signed minimum/maximum of the elements of a vector. The vector is
5613 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5614 the elements of the input vector.
5616 @cindex @code{reduc_umin_scal_@var{m}} instruction pattern
5617 @cindex @code{reduc_umax_scal_@var{m}} instruction pattern
5618 @item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}}
5619 Find the unsigned minimum/maximum of the elements of a vector. The vector is
5620 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5621 the elements of the input vector.
5623 @cindex @code{reduc_fmin_scal_@var{m}} instruction pattern
5624 @cindex @code{reduc_fmax_scal_@var{m}} instruction pattern
5625 @item @samp{reduc_fmin_scal_@var{m}}, @samp{reduc_fmax_scal_@var{m}}
5626 Find the floating-point minimum/maximum of the elements of a vector,
5627 using the same rules as @code{fmin@var{m}3} and @code{fmax@var{m}3}.
5628 Operand 1 is a vector of mode @var{m} and operand 0 is the scalar
5629 result, which has mode @code{GET_MODE_INNER (@var{m})}.
5631 @cindex @code{reduc_plus_scal_@var{m}} instruction pattern
5632 @item @samp{reduc_plus_scal_@var{m}}
5633 Compute the sum of the elements of a vector. The vector is operand 1, and
5634 operand 0 is the scalar result, with mode equal to the mode of the elements of
5635 the input vector.
5637 @cindex @code{reduc_and_scal_@var{m}} instruction pattern
5638 @cindex @code{reduc_ior_scal_@var{m}} instruction pattern
5639 @cindex @code{reduc_xor_scal_@var{m}} instruction pattern
5640 @item @samp{reduc_and_scal_@var{m}}
5641 @itemx @samp{reduc_ior_scal_@var{m}}
5642 @itemx @samp{reduc_xor_scal_@var{m}}
5643 Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements
5644 of a vector of mode @var{m}.  Operand 1 is the vector input and operand 0
5645 is the scalar result.  The mode of the scalar result is the same as one
5646 element of @var{m}.
5648 @cindex @code{extract_last_@var{m}} instruction pattern
5649 @item @code{extract_last_@var{m}}
5650 Find the last set bit in mask operand 1 and extract the associated element
5651 of vector operand 2.  Store the result in scalar operand 0.  Operand 2
5652 has vector mode @var{m} while operand 0 has the mode appropriate for one
5653 element of @var{m}.  Operand 1 has the usual mask mode for vectors of mode
5654 @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5656 @cindex @code{fold_extract_last_@var{m}} instruction pattern
5657 @item @code{fold_extract_last_@var{m}}
5658 If any bits of mask operand 2 are set, find the last set bit, extract
5659 the associated element from vector operand 3, and store the result
5660 in operand 0.  Store operand 1 in operand 0 otherwise.  Operand 3
5661 has mode @var{m} and operands 0 and 1 have the mode appropriate for
5662 one element of @var{m}.  Operand 2 has the usual mask mode for vectors
5663 of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5665 @cindex @code{len_fold_extract_last_@var{m}} instruction pattern
5666 @item @code{len_fold_extract_last_@var{m}}
5667 Like @samp{fold_extract_last_@var{m}}, but takes an extra length operand as
5668 operand 4 and an extra bias operand as operand 5.  The last associated element
5669 is extracted should have the index i < len (operand 4) + bias (operand 5).
5671 @cindex @code{fold_left_plus_@var{m}} instruction pattern
5672 @item @code{fold_left_plus_@var{m}}
5673 Take scalar operand 1 and successively add each element from vector
5674 operand 2.  Store the result in scalar operand 0.  The vector has
5675 mode @var{m} and the scalars have the mode appropriate for one
5676 element of @var{m}.  The operation is strictly in-order: there is
5677 no reassociation.
5679 @cindex @code{mask_fold_left_plus_@var{m}} instruction pattern
5680 @item @code{mask_fold_left_plus_@var{m}}
5681 Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
5682 (operand 3) that specifies which elements of the source vector should be added.
5684 @cindex @code{mask_len_fold_left_plus_@var{m}} instruction pattern
5685 @item @code{mask_len_fold_left_plus_@var{m}}
5686 Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
5687 (operand 3), len operand (operand 4) and bias operand (operand 5) that
5688 performs following operations strictly in-order (no reassociation):
5690 @smallexample
5691 operand0 = operand1;
5692 for (i = 0; i < LEN + BIAS; i++)
5693   if (operand3[i])
5694     operand0 += operand2[i];
5695 @end smallexample
5697 @cindex @code{sdot_prod@var{m}} instruction pattern
5698 @item @samp{sdot_prod@var{m}}
5700 Compute the sum of the products of two signed elements.
5701 Operand 1 and operand 2 are of the same mode. Their
5702 product, which is of a wider mode, is computed and added to operand 3.
5703 Operand 3 is of a mode equal or wider than the mode of the product. The
5704 result is placed in operand 0, which is of the same mode as operand 3.
5706 Semantically the expressions perform the multiplication in the following signs
5708 @smallexample
5709 sdot<signed op0, signed op1, signed op2, signed op3> ==
5710    op0 = sign-ext (op1) * sign-ext (op2) + op3
5711 @dots{}
5712 @end smallexample
5714 @cindex @code{udot_prod@var{m}} instruction pattern
5715 @item @samp{udot_prod@var{m}}
5717 Compute the sum of the products of two unsigned elements.
5718 Operand 1 and operand 2 are of the same mode. Their
5719 product, which is of a wider mode, is computed and added to operand 3.
5720 Operand 3 is of a mode equal or wider than the mode of the product. The
5721 result is placed in operand 0, which is of the same mode as operand 3.
5723 Semantically the expressions perform the multiplication in the following signs
5725 @smallexample
5726 udot<unsigned op0, unsigned op1, unsigned op2, unsigned op3> ==
5727    op0 = zero-ext (op1) * zero-ext (op2) + op3
5728 @dots{}
5729 @end smallexample
5731 @cindex @code{usdot_prod@var{m}} instruction pattern
5732 @item @samp{usdot_prod@var{m}}
5733 Compute the sum of the products of elements of different signs.
5734 Operand 1 must be unsigned and operand 2 signed. Their
5735 product, which is of a wider mode, is computed and added to operand 3.
5736 Operand 3 is of a mode equal or wider than the mode of the product. The
5737 result is placed in operand 0, which is of the same mode as operand 3.
5739 Semantically the expressions perform the multiplication in the following signs
5741 @smallexample
5742 usdot<signed op0, unsigned op1, signed op2, signed op3> ==
5743    op0 = ((signed-conv) zero-ext (op1)) * sign-ext (op2) + op3
5744 @dots{}
5745 @end smallexample
5747 @cindex @code{ssad@var{m}} instruction pattern
5748 @cindex @code{usad@var{m}} instruction pattern
5749 @item @samp{ssad@var{m}}
5750 @item @samp{usad@var{m}}
5751 Compute the sum of absolute differences of two signed/unsigned elements.
5752 Operand 1 and operand 2 are of the same mode. Their absolute difference, which
5753 is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode
5754 equal or wider than the mode of the absolute difference. The result is placed
5755 in operand 0, which is of the same mode as operand 3.
5757 @cindex @code{widen_ssum@var{m3}} instruction pattern
5758 @cindex @code{widen_usum@var{m3}} instruction pattern
5759 @item @samp{widen_ssum@var{m3}}
5760 @itemx @samp{widen_usum@var{m3}}
5761 Operands 0 and 2 are of the same mode, which is wider than the mode of
5762 operand 1. Add operand 1 to operand 2 and place the widened result in
5763 operand 0. (This is used express accumulation of elements into an accumulator
5764 of a wider mode.)
5766 @cindex @code{smulhs@var{m3}} instruction pattern
5767 @cindex @code{umulhs@var{m3}} instruction pattern
5768 @item @samp{smulhs@var{m3}}
5769 @itemx @samp{umulhs@var{m3}}
5770 Signed/unsigned multiply high with scale. This is equivalent to the C code:
5771 @smallexample
5772 narrow op0, op1, op2;
5773 @dots{}
5774 op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1));
5775 @end smallexample
5776 where the sign of @samp{narrow} determines whether this is a signed
5777 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5779 @cindex @code{smulhrs@var{m3}} instruction pattern
5780 @cindex @code{umulhrs@var{m3}} instruction pattern
5781 @item @samp{smulhrs@var{m3}}
5782 @itemx @samp{umulhrs@var{m3}}
5783 Signed/unsigned multiply high with round and scale. This is
5784 equivalent to the C code:
5785 @smallexample
5786 narrow op0, op1, op2;
5787 @dots{}
5788 op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1);
5789 @end smallexample
5790 where the sign of @samp{narrow} determines whether this is a signed
5791 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5793 @cindex @code{sdiv_pow2@var{m3}} instruction pattern
5794 @cindex @code{sdiv_pow2@var{m3}} instruction pattern
5795 @item @samp{sdiv_pow2@var{m3}}
5796 @itemx @samp{sdiv_pow2@var{m3}}
5797 Signed division by power-of-2 immediate. Equivalent to:
5798 @smallexample
5799 signed op0, op1;
5800 @dots{}
5801 op0 = op1 / (1 << imm);
5802 @end smallexample
5804 @cindex @code{vec_shl_insert_@var{m}} instruction pattern
5805 @item @samp{vec_shl_insert_@var{m}}
5806 Shift the elements in vector input operand 1 left one element (i.e.@:
5807 away from element 0) and fill the vacated element 0 with the scalar
5808 in operand 2.  Store the result in vector output operand 0.  Operands
5809 0 and 1 have mode @var{m} and operand 2 has the mode appropriate for
5810 one element of @var{m}.
5812 @cindex @code{vec_shl_@var{m}} instruction pattern
5813 @item @samp{vec_shl_@var{m}}
5814 Whole vector left shift in bits, i.e.@: away from element 0.
5815 Operand 1 is a vector to be shifted.
5816 Operand 2 is an integer shift amount in bits.
5817 Operand 0 is where the resulting shifted vector is stored.
5818 The output and input vectors should have the same modes.
5820 @cindex @code{vec_shr_@var{m}} instruction pattern
5821 @item @samp{vec_shr_@var{m}}
5822 Whole vector right shift in bits, i.e.@: towards element 0.
5823 Operand 1 is a vector to be shifted.
5824 Operand 2 is an integer shift amount in bits.
5825 Operand 0 is where the resulting shifted vector is stored.
5826 The output and input vectors should have the same modes.
5828 @cindex @code{vec_pack_trunc_@var{m}} instruction pattern
5829 @item @samp{vec_pack_trunc_@var{m}}
5830 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5831 are vectors of the same mode having N integral or floating point elements
5832 of size S@.  Operand 0 is the resulting vector in which 2*N elements of
5833 size S/2 are concatenated after narrowing them down using truncation.
5835 @cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern
5836 @item @samp{vec_pack_sbool_trunc_@var{m}}
5837 Narrow and merge the elements of two vectors.  Operands 1 and 2 are vectors
5838 of the same type having N boolean elements.  Operand 0 is the resulting
5839 vector in which 2*N elements are concatenated.  The last operand (operand 3)
5840 is the number of elements in the output vector 2*N as a @code{CONST_INT}.
5841 This instruction pattern is used when all the vector input and output
5842 operands have the same scalar mode @var{m} and thus using
5843 @code{vec_pack_trunc_@var{m}} would be ambiguous.
5845 @cindex @code{vec_pack_ssat_@var{m}} instruction pattern
5846 @cindex @code{vec_pack_usat_@var{m}} instruction pattern
5847 @item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
5848 Narrow (demote) and merge the elements of two vectors.  Operands 1 and 2
5849 are vectors of the same mode having N integral elements of size S.
5850 Operand 0 is the resulting vector in which the elements of the two input
5851 vectors are concatenated after narrowing them down using signed/unsigned
5852 saturating arithmetic.
5854 @cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
5855 @cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
5856 @item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
5857 Narrow, convert to signed/unsigned integral type and merge the elements
5858 of two vectors.  Operands 1 and 2 are vectors of the same mode having N
5859 floating point elements of size S@.  Operand 0 is the resulting vector
5860 in which 2*N elements of size S/2 are concatenated.
5862 @cindex @code{vec_packs_float_@var{m}} instruction pattern
5863 @cindex @code{vec_packu_float_@var{m}} instruction pattern
5864 @item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}}
5865 Narrow, convert to floating point type and merge the elements
5866 of two vectors.  Operands 1 and 2 are vectors of the same mode having N
5867 signed/unsigned integral elements of size S@.  Operand 0 is the resulting vector
5868 in which 2*N elements of size S/2 are concatenated.
5870 @cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
5871 @cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
5872 @item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
5873 Extract and widen (promote) the high/low part of a vector of signed
5874 integral or floating point elements.  The input vector (operand 1) has N
5875 elements of size S@.  Widen (promote) the high/low elements of the vector
5876 using signed or floating point extension and place the resulting N/2
5877 values of size 2*S in the output vector (operand 0).
5879 @cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
5880 @cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
5881 @item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
5882 Extract and widen (promote) the high/low part of a vector of unsigned
5883 integral elements.  The input vector (operand 1) has N elements of size S.
5884 Widen (promote) the high/low elements of the vector using zero extension and
5885 place the resulting N/2 values of size 2*S in the output vector (operand 0).
5887 @cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern
5888 @cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern
5889 @item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}}
5890 Extract the high/low part of a vector of boolean elements that have scalar
5891 mode @var{m}.  The input vector (operand 1) has N elements, the output
5892 vector (operand 0) has N/2 elements.  The last operand (operand 2) is the
5893 number of elements of the input vector N as a @code{CONST_INT}.  These
5894 patterns are used if both the input and output vectors have the same scalar
5895 mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or
5896 @code{vec_unpacks_lo_@var{m}} would be ambiguous.
5898 @cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
5899 @cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
5900 @cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
5901 @cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
5902 @item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
5903 @itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
5904 Extract, convert to floating point type and widen the high/low part of a
5905 vector of signed/unsigned integral elements.  The input vector (operand 1)
5906 has N elements of size S@.  Convert the high/low elements of the vector using
5907 floating point conversion and place the resulting N/2 values of size 2*S in
5908 the output vector (operand 0).
5910 @cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern
5911 @cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern
5912 @cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern
5913 @cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern
5914 @item @samp{vec_unpack_sfix_trunc_hi_@var{m}},
5915 @itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}}
5916 @itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}}
5917 @itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}}
5918 Extract, convert to signed/unsigned integer type and widen the high/low part of a
5919 vector of floating point elements.  The input vector (operand 1)
5920 has N elements of size S@.  Convert the high/low elements of the vector
5921 to integers and place the resulting N/2 values of size 2*S in
5922 the output vector (operand 0).
5924 @cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
5925 @cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern
5926 @cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
5927 @cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
5928 @cindex @code{vec_widen_umult_even_@var{m}} instruction pattern
5929 @cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern
5930 @cindex @code{vec_widen_smult_even_@var{m}} instruction pattern
5931 @cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern
5932 @item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
5933 @itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
5934 @itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}}
5935 @itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}}
5936 Signed/Unsigned widening multiplication.  The two inputs (operands 1 and 2)
5937 are vectors with N signed/unsigned elements of size S@.  Multiply the high/low
5938 or even/odd elements of the two vectors, and put the N/2 products of size 2*S
5939 in the output vector (operand 0). A target shouldn't implement even/odd pattern
5940 pair if it is less efficient than lo/hi one.
5942 @cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
5943 @cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
5944 @cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
5945 @cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
5946 @item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
5947 @itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
5948 Signed/Unsigned widening shift left.  The first input (operand 1) is a vector
5949 with N signed/unsigned elements of size S@.  Operand 2 is a constant.  Shift
5950 the high/low elements of operand 1, and put the N/2 results of size 2*S in the
5951 output vector (operand 0).
5953 @cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern
5954 @cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern
5955 @cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern
5956 @cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern
5957 @item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}}
5958 @itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}}
5959 Signed/Unsigned widening add long.  Operands 1 and 2 are vectors with N
5960 signed/unsigned elements of size S@.  Add the high/low elements of 1 and 2
5961 together, widen the resulting elements and put the N/2 results of size 2*S in
5962 the output vector (operand 0).
5964 @cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern
5965 @cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern
5966 @cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern
5967 @cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern
5968 @item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}}
5969 @itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}}
5970 Signed/Unsigned widening subtract long.  Operands 1 and 2 are vectors with N
5971 signed/unsigned elements of size S@.  Subtract the high/low elements of 2 from
5972 1 and widen the resulting elements. Put the N/2 results of size 2*S in the
5973 output vector (operand 0).
5975 @cindex @code{vec_widen_sabd_hi_@var{m}} instruction pattern
5976 @cindex @code{vec_widen_sabd_lo_@var{m}} instruction pattern
5977 @cindex @code{vec_widen_sabd_odd_@var{m}} instruction pattern
5978 @cindex @code{vec_widen_sabd_even_@var{m}} instruction pattern
5979 @cindex @code{vec_widen_uabd_hi_@var{m}} instruction pattern
5980 @cindex @code{vec_widen_uabd_lo_@var{m}} instruction pattern
5981 @cindex @code{vec_widen_uabd_odd_@var{m}} instruction pattern
5982 @cindex @code{vec_widen_uabd_even_@var{m}} instruction pattern
5983 @item @samp{vec_widen_uabd_hi_@var{m}}, @samp{vec_widen_uabd_lo_@var{m}}
5984 @itemx @samp{vec_widen_uabd_odd_@var{m}}, @samp{vec_widen_uabd_even_@var{m}}
5985 @itemx @samp{vec_widen_sabd_hi_@var{m}}, @samp{vec_widen_sabd_lo_@var{m}}
5986 @itemx @samp{vec_widen_sabd_odd_@var{m}}, @samp{vec_widen_sabd_even_@var{m}}
5987 Signed/Unsigned widening absolute difference.  Operands 1 and 2 are
5988 vectors with N signed/unsigned elements of size S@.  Find the absolute
5989 difference between operands 1 and 2 and widen the resulting elements.
5990 Put the N/2 results of size 2*S in the output vector (operand 0).
5992 @cindex @code{vec_addsub@var{m}3} instruction pattern
5993 @item @samp{vec_addsub@var{m}3}
5994 Alternating subtract, add with even lanes doing subtract and odd
5995 lanes doing addition.  Operands 1 and 2 and the outout operand are vectors
5996 with mode @var{m}.
5998 @cindex @code{vec_fmaddsub@var{m}4} instruction pattern
5999 @item @samp{vec_fmaddsub@var{m}4}
6000 Alternating multiply subtract, add with even lanes doing subtract and odd
6001 lanes doing addition of the third operand to the multiplication result
6002 of the first two operands.  Operands 1, 2 and 3 and the outout operand are vectors
6003 with mode @var{m}.
6005 @cindex @code{vec_fmsubadd@var{m}4} instruction pattern
6006 @item @samp{vec_fmsubadd@var{m}4}
6007 Alternating multiply add, subtract with even lanes doing addition and odd
6008 lanes doing subtraction of the third operand to the multiplication result
6009 of the first two operands.  Operands 1, 2 and 3 and the outout operand are vectors
6010 with mode @var{m}.
6012 These instructions are not allowed to @code{FAIL}.
6014 @cindex @code{mulhisi3} instruction pattern
6015 @item @samp{mulhisi3}
6016 Multiply operands 1 and 2, which have mode @code{HImode}, and store
6017 a @code{SImode} product in operand 0.
6019 @cindex @code{mulqihi3} instruction pattern
6020 @cindex @code{mulsidi3} instruction pattern
6021 @item @samp{mulqihi3}, @samp{mulsidi3}
6022 Similar widening-multiplication instructions of other widths.
6024 @cindex @code{umulqihi3} instruction pattern
6025 @cindex @code{umulhisi3} instruction pattern
6026 @cindex @code{umulsidi3} instruction pattern
6027 @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
6028 Similar widening-multiplication instructions that do unsigned
6029 multiplication.
6031 @cindex @code{usmulqihi3} instruction pattern
6032 @cindex @code{usmulhisi3} instruction pattern
6033 @cindex @code{usmulsidi3} instruction pattern
6034 @item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
6035 Similar widening-multiplication instructions that interpret the first
6036 operand as unsigned and the second operand as signed, then do a signed
6037 multiplication.
6039 @cindex @code{smul@var{m}3_highpart} instruction pattern
6040 @item @samp{smul@var{m}3_highpart}
6041 Perform a signed multiplication of operands 1 and 2, which have mode
6042 @var{m}, and store the most significant half of the product in operand 0.
6043 The least significant half of the product is discarded.  This may be
6044 represented in RTL using a @code{smul_highpart} RTX expression.
6046 @cindex @code{umul@var{m}3_highpart} instruction pattern
6047 @item @samp{umul@var{m}3_highpart}
6048 Similar, but the multiplication is unsigned.  This may be represented
6049 in RTL using an @code{umul_highpart} RTX expression.
6051 @cindex @code{madd@var{m}@var{n}4} instruction pattern
6052 @item @samp{madd@var{m}@var{n}4}
6053 Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
6054 operand 3, and store the result in operand 0.  Operands 1 and 2
6055 have mode @var{m} and operands 0 and 3 have mode @var{n}.
6056 Both modes must be integer or fixed-point modes and @var{n} must be twice
6057 the size of @var{m}.
6059 In other words, @code{madd@var{m}@var{n}4} is like
6060 @code{mul@var{m}@var{n}3} except that it also adds operand 3.
6062 These instructions are not allowed to @code{FAIL}.
6064 @cindex @code{umadd@var{m}@var{n}4} instruction pattern
6065 @item @samp{umadd@var{m}@var{n}4}
6066 Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
6067 operands instead of sign-extending them.
6069 @cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
6070 @item @samp{ssmadd@var{m}@var{n}4}
6071 Like @code{madd@var{m}@var{n}4}, but all involved operations must be
6072 signed-saturating.
6074 @cindex @code{usmadd@var{m}@var{n}4} instruction pattern
6075 @item @samp{usmadd@var{m}@var{n}4}
6076 Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
6077 unsigned-saturating.
6079 @cindex @code{msub@var{m}@var{n}4} instruction pattern
6080 @item @samp{msub@var{m}@var{n}4}
6081 Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
6082 result from operand 3, and store the result in operand 0.  Operands 1 and 2
6083 have mode @var{m} and operands 0 and 3 have mode @var{n}.
6084 Both modes must be integer or fixed-point modes and @var{n} must be twice
6085 the size of @var{m}.
6087 In other words, @code{msub@var{m}@var{n}4} is like
6088 @code{mul@var{m}@var{n}3} except that it also subtracts the result
6089 from operand 3.
6091 These instructions are not allowed to @code{FAIL}.
6093 @cindex @code{umsub@var{m}@var{n}4} instruction pattern
6094 @item @samp{umsub@var{m}@var{n}4}
6095 Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
6096 operands instead of sign-extending them.
6098 @cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
6099 @item @samp{ssmsub@var{m}@var{n}4}
6100 Like @code{msub@var{m}@var{n}4}, but all involved operations must be
6101 signed-saturating.
6103 @cindex @code{usmsub@var{m}@var{n}4} instruction pattern
6104 @item @samp{usmsub@var{m}@var{n}4}
6105 Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
6106 unsigned-saturating.
6108 @cindex @code{divmod@var{m}4} instruction pattern
6109 @item @samp{divmod@var{m}4}
6110 Signed division that produces both a quotient and a remainder.
6111 Operand 1 is divided by operand 2 to produce a quotient stored
6112 in operand 0 and a remainder stored in operand 3.
6114 For machines with an instruction that produces both a quotient and a
6115 remainder, provide a pattern for @samp{divmod@var{m}4} but do not
6116 provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}.  This
6117 allows optimization in the relatively common case when both the quotient
6118 and remainder are computed.
6120 If an instruction that just produces a quotient or just a remainder
6121 exists and is more efficient than the instruction that produces both,
6122 write the output routine of @samp{divmod@var{m}4} to call
6123 @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
6124 quotient or remainder and generate the appropriate instruction.
6126 @cindex @code{udivmod@var{m}4} instruction pattern
6127 @item @samp{udivmod@var{m}4}
6128 Similar, but does unsigned division.
6130 @anchor{shift patterns}
6131 @cindex @code{ashl@var{m}3} instruction pattern
6132 @cindex @code{ssashl@var{m}3} instruction pattern
6133 @cindex @code{usashl@var{m}3} instruction pattern
6134 @item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
6135 Arithmetic-shift operand 1 left by a number of bits specified by operand
6136 2, and store the result in operand 0.  Here @var{m} is the mode of
6137 operand 0 and operand 1; operand 2's mode is specified by the
6138 instruction pattern, and the compiler will convert the operand to that
6139 mode before generating the instruction.  The shift or rotate expander
6140 or instruction pattern should explicitly specify the mode of the operand 2,
6141 it should never be @code{VOIDmode}.  The meaning of out-of-range shift
6142 counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
6143 @xref{TARGET_SHIFT_TRUNCATION_MASK}.  Operand 2 is always a scalar type.
6145 @cindex @code{ashr@var{m}3} instruction pattern
6146 @cindex @code{lshr@var{m}3} instruction pattern
6147 @cindex @code{rotl@var{m}3} instruction pattern
6148 @cindex @code{rotr@var{m}3} instruction pattern
6149 @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
6150 Other shift and rotate instructions, analogous to the
6151 @code{ashl@var{m}3} instructions.  Operand 2 is always a scalar type.
6153 @cindex @code{vashl@var{m}3} instruction pattern
6154 @cindex @code{vashr@var{m}3} instruction pattern
6155 @cindex @code{vlshr@var{m}3} instruction pattern
6156 @cindex @code{vrotl@var{m}3} instruction pattern
6157 @cindex @code{vrotr@var{m}3} instruction pattern
6158 @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}
6159 Vector shift and rotate instructions that take vectors as operand 2
6160 instead of a scalar type.
6162 @cindex @code{uabd@var{m}} instruction pattern
6163 @cindex @code{sabd@var{m}} instruction pattern
6164 @item @samp{uabd@var{m}}, @samp{sabd@var{m}}
6165 Signed and unsigned absolute difference instructions.  These
6166 instructions find the difference between operands 1 and 2
6167 then return the absolute value.  A C code equivalent would be:
6168 @smallexample
6169 op0 = op1 > op2 ? op1 - op2 : op2 - op1;
6170 @end smallexample
6172 @cindex @code{avg@var{m}3_floor} instruction pattern
6173 @cindex @code{uavg@var{m}3_floor} instruction pattern
6174 @item @samp{avg@var{m}3_floor}
6175 @itemx @samp{uavg@var{m}3_floor}
6176 Signed and unsigned average instructions.  These instructions add
6177 operands 1 and 2 without truncation, divide the result by 2,
6178 round towards -Inf, and store the result in operand 0.  This is
6179 equivalent to the C code:
6180 @smallexample
6181 narrow op0, op1, op2;
6182 @dots{}
6183 op0 = (narrow) (((wide) op1 + (wide) op2) >> 1);
6184 @end smallexample
6185 where the sign of @samp{narrow} determines whether this is a signed
6186 or unsigned operation.
6188 @cindex @code{avg@var{m}3_ceil} instruction pattern
6189 @cindex @code{uavg@var{m}3_ceil} instruction pattern
6190 @item @samp{avg@var{m}3_ceil}
6191 @itemx @samp{uavg@var{m}3_ceil}
6192 Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round
6193 towards +Inf.  This is equivalent to the C code:
6194 @smallexample
6195 narrow op0, op1, op2;
6196 @dots{}
6197 op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1);
6198 @end smallexample
6200 @cindex @code{bswap@var{m}2} instruction pattern
6201 @item @samp{bswap@var{m}2}
6202 Reverse the order of bytes of operand 1 and store the result in operand 0.
6204 @cindex @code{neg@var{m}2} instruction pattern
6205 @cindex @code{ssneg@var{m}2} instruction pattern
6206 @cindex @code{usneg@var{m}2} instruction pattern
6207 @item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
6208 Negate operand 1 and store the result in operand 0.
6210 @cindex @code{negv@var{m}3} instruction pattern
6211 @item @samp{negv@var{m}3}
6212 Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and
6213 emits code to jump to it if signed overflow occurs during the negation.
6215 @cindex @code{abs@var{m}2} instruction pattern
6216 @item @samp{abs@var{m}2}
6217 Store the absolute value of operand 1 into operand 0.
6219 @cindex @code{sqrt@var{m}2} instruction pattern
6220 @item @samp{sqrt@var{m}2}
6221 Store the square root of operand 1 into operand 0.  Both operands have
6222 mode @var{m}, which is a scalar or vector floating-point mode.
6224 This pattern is not allowed to @code{FAIL}.
6226 @cindex @code{rsqrt@var{m}2} instruction pattern
6227 @item @samp{rsqrt@var{m}2}
6228 Store the reciprocal of the square root of operand 1 into operand 0.
6229 Both operands have mode @var{m}, which is a scalar or vector
6230 floating-point mode.
6232 On most architectures this pattern is only approximate, so either
6233 its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should
6234 check for the appropriate math flags.  (Using the C condition is
6235 more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful
6236 if a target-specific built-in also uses the @samp{rsqrt@var{m}2}
6237 pattern.)
6239 This pattern is not allowed to @code{FAIL}.
6241 @cindex @code{fmod@var{m}3} instruction pattern
6242 @item @samp{fmod@var{m}3}
6243 Store the remainder of dividing operand 1 by operand 2 into
6244 operand 0, rounded towards zero to an integer.  All operands have
6245 mode @var{m}, which is a scalar or vector floating-point mode.
6247 This pattern is not allowed to @code{FAIL}.
6249 @cindex @code{remainder@var{m}3} instruction pattern
6250 @item @samp{remainder@var{m}3}
6251 Store the remainder of dividing operand 1 by operand 2 into
6252 operand 0, rounded to the nearest integer.  All operands have
6253 mode @var{m}, which is a scalar or vector floating-point mode.
6255 This pattern is not allowed to @code{FAIL}.
6257 @cindex @code{scalb@var{m}3} instruction pattern
6258 @item @samp{scalb@var{m}3}
6259 Raise @code{FLT_RADIX} to the power of operand 2, multiply it by
6260 operand 1, and store the result in operand 0.  All operands have
6261 mode @var{m}, which is a scalar or vector floating-point mode.
6263 This pattern is not allowed to @code{FAIL}.
6265 @cindex @code{ldexp@var{m}3} instruction pattern
6266 @item @samp{ldexp@var{m}3}
6267 Raise 2 to the power of operand 2, multiply it by operand 1, and store
6268 the result in operand 0.  Operands 0 and 1 have mode @var{m}, which is
6269 a scalar or vector floating-point mode.  Operand 2's mode has
6270 the same number of elements as @var{m} and each element is wide
6271 enough to store an @code{int}.  The integers are signed.
6273 This pattern is not allowed to @code{FAIL}.
6275 @cindex @code{cos@var{m}2} instruction pattern
6276 @item @samp{cos@var{m}2}
6277 Store the cosine of operand 1 into operand 0.  Both operands have
6278 mode @var{m}, which is a scalar or vector floating-point mode.
6280 This pattern is not allowed to @code{FAIL}.
6282 @cindex @code{sin@var{m}2} instruction pattern
6283 @item @samp{sin@var{m}2}
6284 Store the sine of operand 1 into operand 0.  Both operands have
6285 mode @var{m}, which is a scalar or vector floating-point mode.
6287 This pattern is not allowed to @code{FAIL}.
6289 @cindex @code{sincos@var{m}3} instruction pattern
6290 @item @samp{sincos@var{m}3}
6291 Store the cosine of operand 2 into operand 0 and the sine of
6292 operand 2 into operand 1.  All operands have mode @var{m},
6293 which is a scalar or vector floating-point mode.
6295 Targets that can calculate the sine and cosine simultaneously can
6296 implement this pattern as opposed to implementing individual
6297 @code{sin@var{m}2} and @code{cos@var{m}2} patterns.  The @code{sin}
6298 and @code{cos} built-in functions will then be expanded to the
6299 @code{sincos@var{m}3} pattern, with one of the output values
6300 left unused.
6302 @cindex @code{tan@var{m}2} instruction pattern
6303 @item @samp{tan@var{m}2}
6304 Store the tangent of operand 1 into operand 0.  Both operands have
6305 mode @var{m}, which is a scalar or vector floating-point mode.
6307 This pattern is not allowed to @code{FAIL}.
6309 @cindex @code{asin@var{m}2} instruction pattern
6310 @item @samp{asin@var{m}2}
6311 Store the arc sine of operand 1 into operand 0.  Both operands have
6312 mode @var{m}, which is a scalar or vector floating-point mode.
6314 This pattern is not allowed to @code{FAIL}.
6316 @cindex @code{acos@var{m}2} instruction pattern
6317 @item @samp{acos@var{m}2}
6318 Store the arc cosine of operand 1 into operand 0.  Both operands have
6319 mode @var{m}, which is a scalar or vector floating-point mode.
6321 This pattern is not allowed to @code{FAIL}.
6323 @cindex @code{atan@var{m}2} instruction pattern
6324 @item @samp{atan@var{m}2}
6325 Store the arc tangent of operand 1 into operand 0.  Both operands have
6326 mode @var{m}, which is a scalar or vector floating-point mode.
6328 This pattern is not allowed to @code{FAIL}.
6330 @cindex @code{fegetround@var{m}} instruction pattern
6331 @item @samp{fegetround@var{m}}
6332 Store the current machine floating-point rounding mode into operand 0.
6333 Operand 0 has mode @var{m}, which is scalar.  This pattern is used to
6334 implement the @code{fegetround} function from the ISO C99 standard.
6336 @cindex @code{feclearexcept@var{m}} instruction pattern
6337 @cindex @code{feraiseexcept@var{m}} instruction pattern
6338 @item @samp{feclearexcept@var{m}}
6339 @item @samp{feraiseexcept@var{m}}
6340 Clears or raises the supported machine floating-point exceptions
6341 represented by the bits in operand 1.  Error status is stored as
6342 nonzero value in operand 0.  Both operands have mode @var{m}, which is
6343 a scalar.  These patterns are used to implement the
6344 @code{feclearexcept} and @code{feraiseexcept} functions from the ISO
6345 C99 standard.
6347 @cindex @code{exp@var{m}2} instruction pattern
6348 @item @samp{exp@var{m}2}
6349 Raise e (the base of natural logarithms) to the power of operand 1
6350 and store the result in operand 0.  Both operands have mode @var{m},
6351 which is a scalar or vector floating-point mode.
6353 This pattern is not allowed to @code{FAIL}.
6355 @cindex @code{expm1@var{m}2} instruction pattern
6356 @item @samp{expm1@var{m}2}
6357 Raise e (the base of natural logarithms) to the power of operand 1,
6358 subtract 1, and store the result in operand 0.  Both operands have
6359 mode @var{m}, which is a scalar or vector floating-point mode.
6361 For inputs close to zero, the pattern is expected to be more
6362 accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3}
6363 would be.
6365 This pattern is not allowed to @code{FAIL}.
6367 @cindex @code{exp10@var{m}2} instruction pattern
6368 @item @samp{exp10@var{m}2}
6369 Raise 10 to the power of operand 1 and store the result in operand 0.
6370 Both operands have mode @var{m}, which is a scalar or vector
6371 floating-point mode.
6373 This pattern is not allowed to @code{FAIL}.
6375 @cindex @code{exp2@var{m}2} instruction pattern
6376 @item @samp{exp2@var{m}2}
6377 Raise 2 to the power of operand 1 and store the result in operand 0.
6378 Both operands have mode @var{m}, which is a scalar or vector
6379 floating-point mode.
6381 This pattern is not allowed to @code{FAIL}.
6383 @cindex @code{log@var{m}2} instruction pattern
6384 @item @samp{log@var{m}2}
6385 Store the natural logarithm of operand 1 into operand 0.  Both operands
6386 have mode @var{m}, which is a scalar or vector floating-point mode.
6388 This pattern is not allowed to @code{FAIL}.
6390 @cindex @code{log1p@var{m}2} instruction pattern
6391 @item @samp{log1p@var{m}2}
6392 Add 1 to operand 1, compute the natural logarithm, and store
6393 the result in operand 0.  Both operands have mode @var{m}, which is
6394 a scalar or vector floating-point mode.
6396 For inputs close to zero, the pattern is expected to be more
6397 accurate than a separate @code{add@var{m}3} and @code{log@var{m}2}
6398 would be.
6400 This pattern is not allowed to @code{FAIL}.
6402 @cindex @code{log10@var{m}2} instruction pattern
6403 @item @samp{log10@var{m}2}
6404 Store the base-10 logarithm of operand 1 into operand 0.  Both operands
6405 have mode @var{m}, which is a scalar or vector floating-point mode.
6407 This pattern is not allowed to @code{FAIL}.
6409 @cindex @code{log2@var{m}2} instruction pattern
6410 @item @samp{log2@var{m}2}
6411 Store the base-2 logarithm of operand 1 into operand 0.  Both operands
6412 have mode @var{m}, which is a scalar or vector floating-point mode.
6414 This pattern is not allowed to @code{FAIL}.
6416 @cindex @code{logb@var{m}2} instruction pattern
6417 @item @samp{logb@var{m}2}
6418 Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0.
6419 Both operands have mode @var{m}, which is a scalar or vector
6420 floating-point mode.
6422 This pattern is not allowed to @code{FAIL}.
6424 @cindex @code{signbit@var{m}2} instruction pattern
6425 @item @samp{signbit@var{m}2}
6426 Store the sign bit of floating-point operand 1 in operand 0.
6427 @var{m} is either a scalar or vector mode.  When it is a scalar,
6428 operand 1 has mode @var{m} but operand 0 must have mode @code{SImode}.
6429 When @var{m} is a vector, operand 1 has the mode @var{m}.
6430 operand 0's mode should be an vector integer mode which has
6431 the same number of elements and the same size as mode @var{m}.
6433 This pattern is not allowed to @code{FAIL}.
6435 @cindex @code{significand@var{m}2} instruction pattern
6436 @item @samp{significand@var{m}2}
6437 Store the significand of floating-point operand 1 in operand 0.
6438 Both operands have mode @var{m}, which is a scalar or vector
6439 floating-point mode.
6441 This pattern is not allowed to @code{FAIL}.
6443 @cindex @code{pow@var{m}3} instruction pattern
6444 @item @samp{pow@var{m}3}
6445 Store the value of operand 1 raised to the exponent operand 2
6446 into operand 0.  All operands have mode @var{m}, which is a scalar
6447 or vector floating-point mode.
6449 This pattern is not allowed to @code{FAIL}.
6451 @cindex @code{atan2@var{m}3} instruction pattern
6452 @item @samp{atan2@var{m}3}
6453 Store the arc tangent (inverse tangent) of operand 1 divided by
6454 operand 2 into operand 0, using the signs of both arguments to
6455 determine the quadrant of the result.  All operands have mode
6456 @var{m}, which is a scalar or vector floating-point mode.
6458 This pattern is not allowed to @code{FAIL}.
6460 @cindex @code{floor@var{m}2} instruction pattern
6461 @item @samp{floor@var{m}2}
6462 Store the largest integral value not greater than operand 1 in operand 0.
6463 Both operands have mode @var{m}, which is a scalar or vector
6464 floating-point mode.  If @option{-ffp-int-builtin-inexact} is in
6465 effect, the ``inexact'' exception may be raised for noninteger
6466 operands; otherwise, it may not.
6468 This pattern is not allowed to @code{FAIL}.
6470 @cindex @code{btrunc@var{m}2} instruction pattern
6471 @item @samp{btrunc@var{m}2}
6472 Round operand 1 to an integer, towards zero, and store the result in
6473 operand 0.  Both operands have mode @var{m}, which is a scalar or
6474 vector floating-point mode.  If @option{-ffp-int-builtin-inexact} is
6475 in effect, the ``inexact'' exception may be raised for noninteger
6476 operands; otherwise, it may not.
6478 This pattern is not allowed to @code{FAIL}.
6480 @cindex @code{round@var{m}2} instruction pattern
6481 @item @samp{round@var{m}2}
6482 Round operand 1 to the nearest integer, rounding away from zero in the
6483 event of a tie, and store the result in operand 0.  Both operands have
6484 mode @var{m}, which is a scalar or vector floating-point mode.  If
6485 @option{-ffp-int-builtin-inexact} is in effect, the ``inexact''
6486 exception may be raised for noninteger operands; otherwise, it may
6487 not.
6489 This pattern is not allowed to @code{FAIL}.
6491 @cindex @code{ceil@var{m}2} instruction pattern
6492 @item @samp{ceil@var{m}2}
6493 Store the smallest integral value not less than operand 1 in operand 0.
6494 Both operands have mode @var{m}, which is a scalar or vector
6495 floating-point mode.  If @option{-ffp-int-builtin-inexact} is in
6496 effect, the ``inexact'' exception may be raised for noninteger
6497 operands; otherwise, it may not.
6499 This pattern is not allowed to @code{FAIL}.
6501 @cindex @code{nearbyint@var{m}2} instruction pattern
6502 @item @samp{nearbyint@var{m}2}
6503 Round operand 1 to an integer, using the current rounding mode, and
6504 store the result in operand 0.  Do not raise an inexact condition when
6505 the result is different from the argument.  Both operands have mode
6506 @var{m}, which is a scalar or vector floating-point mode.
6508 This pattern is not allowed to @code{FAIL}.
6510 @cindex @code{rint@var{m}2} instruction pattern
6511 @item @samp{rint@var{m}2}
6512 Round operand 1 to an integer, using the current rounding mode, and
6513 store the result in operand 0.  Raise an inexact condition when
6514 the result is different from the argument.  Both operands have mode
6515 @var{m}, which is a scalar or vector floating-point mode.
6517 This pattern is not allowed to @code{FAIL}.
6519 @cindex @code{lrint@var{m}@var{n}2}
6520 @item @samp{lrint@var{m}@var{n}2}
6521 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6522 point mode @var{n} as a signed number according to the current
6523 rounding mode and store in operand 0 (which has mode @var{n}).
6525 @cindex @code{lround@var{m}@var{n}2}
6526 @item @samp{lround@var{m}@var{n}2}
6527 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6528 point mode @var{n} as a signed number rounding to nearest and away
6529 from zero and store in operand 0 (which has mode @var{n}).
6531 @cindex @code{lfloor@var{m}@var{n}2}
6532 @item @samp{lfloor@var{m}@var{n}2}
6533 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6534 point mode @var{n} as a signed number rounding down and store in
6535 operand 0 (which has mode @var{n}).
6537 @cindex @code{lceil@var{m}@var{n}2}
6538 @item @samp{lceil@var{m}@var{n}2}
6539 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6540 point mode @var{n} as a signed number rounding up and store in
6541 operand 0 (which has mode @var{n}).
6543 @cindex @code{copysign@var{m}3} instruction pattern
6544 @item @samp{copysign@var{m}3}
6545 Store a value with the magnitude of operand 1 and the sign of operand
6546 2 into operand 0.  All operands have mode @var{m}, which is a scalar or
6547 vector floating-point mode.
6549 This pattern is not allowed to @code{FAIL}.
6551 @cindex @code{xorsign@var{m}3} instruction pattern
6552 @item @samp{xorsign@var{m}3}
6553 Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with
6554 the magnitude of operand 1 and the sign of operand 2 into operand 0.
6555 All operands have mode @var{m}, which is a scalar or vector
6556 floating-point mode.
6558 This pattern is not allowed to @code{FAIL}.
6560 @cindex @code{issignaling@var{m}2} instruction pattern
6561 @item @samp{issignaling@var{m}2}
6562 Set operand 0 to 1 if operand 1 is a signaling NaN and to 0 otherwise.
6564 @cindex @code{cadd90@var{m}3} instruction pattern
6565 @item @samp{cadd90@var{m}3}
6566 Perform vector add and subtract on even/odd number pairs.  The operation being
6567 matched is semantically described as
6569 @smallexample
6570   for (int i = 0; i < N; i += 2)
6571     @{
6572       c[i] = a[i] - b[i+1];
6573       c[i+1] = a[i+1] + b[i];
6574     @}
6575 @end smallexample
6577 This operation is semantically equivalent to performing a vector addition of
6578 complex numbers in operand 1 with operand 2 rotated by 90 degrees around
6579 the argand plane and storing the result in operand 0.
6581 In GCC lane ordering the real part of the number must be in the even lanes with
6582 the imaginary part in the odd lanes.
6584 The operation is only supported for vector modes @var{m}.
6586 This pattern is not allowed to @code{FAIL}.
6588 @cindex @code{cadd270@var{m}3} instruction pattern
6589 @item @samp{cadd270@var{m}3}
6590 Perform vector add and subtract on even/odd number pairs.  The operation being
6591 matched is semantically described as
6593 @smallexample
6594   for (int i = 0; i < N; i += 2)
6595     @{
6596       c[i] = a[i] + b[i+1];
6597       c[i+1] = a[i+1] - b[i];
6598     @}
6599 @end smallexample
6601 This operation is semantically equivalent to performing a vector addition of
6602 complex numbers in operand 1 with operand 2 rotated by 270 degrees around
6603 the argand plane and storing the result in operand 0.
6605 In GCC lane ordering the real part of the number must be in the even lanes with
6606 the imaginary part in the odd lanes.
6608 The operation is only supported for vector modes @var{m}.
6610 This pattern is not allowed to @code{FAIL}.
6612 @cindex @code{cmla@var{m}4} instruction pattern
6613 @item @samp{cmla@var{m}4}
6614 Perform a vector multiply and accumulate that is semantically the same as
6615 a multiply and accumulate of complex numbers.
6617 @smallexample
6618   complex TYPE op0[N];
6619   complex TYPE op1[N];
6620   complex TYPE op2[N];
6621   complex TYPE op3[N];
6622   for (int i = 0; i < N; i += 1)
6623     @{
6624       op0[i] = op1[i] * op2[i] + op3[i];
6625     @}
6626 @end smallexample
6628 In GCC lane ordering the real part of the number must be in the even lanes with
6629 the imaginary part in the odd lanes.
6631 The operation is only supported for vector modes @var{m}.
6633 This pattern is not allowed to @code{FAIL}.
6635 @cindex @code{cmla_conj@var{m}4} instruction pattern
6636 @item @samp{cmla_conj@var{m}4}
6637 Perform a vector multiply by conjugate and accumulate that is semantically
6638 the same as a multiply and accumulate of complex numbers where the second
6639 multiply arguments is conjugated.
6641 @smallexample
6642   complex TYPE op0[N];
6643   complex TYPE op1[N];
6644   complex TYPE op2[N];
6645   complex TYPE op3[N];
6646   for (int i = 0; i < N; i += 1)
6647     @{
6648       op0[i] = op1[i] * conj (op2[i]) + op3[i];
6649     @}
6650 @end smallexample
6652 In GCC lane ordering the real part of the number must be in the even lanes with
6653 the imaginary part in the odd lanes.
6655 The operation is only supported for vector modes @var{m}.
6657 This pattern is not allowed to @code{FAIL}.
6659 @cindex @code{cmls@var{m}4} instruction pattern
6660 @item @samp{cmls@var{m}4}
6661 Perform a vector multiply and subtract that is semantically the same as
6662 a multiply and subtract of complex numbers.
6664 @smallexample
6665   complex TYPE op0[N];
6666   complex TYPE op1[N];
6667   complex TYPE op2[N];
6668   complex TYPE op3[N];
6669   for (int i = 0; i < N; i += 1)
6670     @{
6671       op0[i] = op1[i] * op2[i] - op3[i];
6672     @}
6673 @end smallexample
6675 In GCC lane ordering the real part of the number must be in the even lanes with
6676 the imaginary part in the odd lanes.
6678 The operation is only supported for vector modes @var{m}.
6680 This pattern is not allowed to @code{FAIL}.
6682 @cindex @code{cmls_conj@var{m}4} instruction pattern
6683 @item @samp{cmls_conj@var{m}4}
6684 Perform a vector multiply by conjugate and subtract that is semantically
6685 the same as a multiply and subtract of complex numbers where the second
6686 multiply arguments is conjugated.
6688 @smallexample
6689   complex TYPE op0[N];
6690   complex TYPE op1[N];
6691   complex TYPE op2[N];
6692   complex TYPE op3[N];
6693   for (int i = 0; i < N; i += 1)
6694     @{
6695       op0[i] = op1[i] * conj (op2[i]) - op3[i];
6696     @}
6697 @end smallexample
6699 In GCC lane ordering the real part of the number must be in the even lanes with
6700 the imaginary part in the odd lanes.
6702 The operation is only supported for vector modes @var{m}.
6704 This pattern is not allowed to @code{FAIL}.
6706 @cindex @code{cmul@var{m}4} instruction pattern
6707 @item @samp{cmul@var{m}4}
6708 Perform a vector multiply that is semantically the same as multiply of
6709 complex numbers.
6711 @smallexample
6712   complex TYPE op0[N];
6713   complex TYPE op1[N];
6714   complex TYPE op2[N];
6715   for (int i = 0; i < N; i += 1)
6716     @{
6717       op0[i] = op1[i] * op2[i];
6718     @}
6719 @end smallexample
6721 In GCC lane ordering the real part of the number must be in the even lanes with
6722 the imaginary part in the odd lanes.
6724 The operation is only supported for vector modes @var{m}.
6726 This pattern is not allowed to @code{FAIL}.
6728 @cindex @code{cmul_conj@var{m}4} instruction pattern
6729 @item @samp{cmul_conj@var{m}4}
6730 Perform a vector multiply by conjugate that is semantically the same as a
6731 multiply of complex numbers where the second multiply arguments is conjugated.
6733 @smallexample
6734   complex TYPE op0[N];
6735   complex TYPE op1[N];
6736   complex TYPE op2[N];
6737   for (int i = 0; i < N; i += 1)
6738     @{
6739       op0[i] = op1[i] * conj (op2[i]);
6740     @}
6741 @end smallexample
6743 In GCC lane ordering the real part of the number must be in the even lanes with
6744 the imaginary part in the odd lanes.
6746 The operation is only supported for vector modes @var{m}.
6748 This pattern is not allowed to @code{FAIL}.
6750 @cindex @code{ffs@var{m}2} instruction pattern
6751 @item @samp{ffs@var{m}2}
6752 Store into operand 0 one plus the index of the least significant 1-bit
6753 of operand 1.  If operand 1 is zero, store zero.
6755 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
6756 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6757 integer mode is suitable for the target.  The compiler will insert
6758 conversion instructions as necessary (typically to convert the result
6759 to the same width as @code{int}).  When @var{m} is a vector, both
6760 operands must have mode @var{m}.
6762 This pattern is not allowed to @code{FAIL}.
6764 @cindex @code{clrsb@var{m}2} instruction pattern
6765 @item @samp{clrsb@var{m}2}
6766 Count leading redundant sign bits.
6767 Store into operand 0 the number of redundant sign bits in operand 1, starting
6768 at the most significant bit position.
6769 A redundant sign bit is defined as any sign bit after the first. As such,
6770 this count will be one less than the count of leading sign bits.
6772 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
6773 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6774 integer mode is suitable for the target.  The compiler will insert
6775 conversion instructions as necessary (typically to convert the result
6776 to the same width as @code{int}).  When @var{m} is a vector, both
6777 operands must have mode @var{m}.
6779 This pattern is not allowed to @code{FAIL}.
6781 @cindex @code{clz@var{m}2} instruction pattern
6782 @item @samp{clz@var{m}2}
6783 Store into operand 0 the number of leading 0-bits in operand 1, starting
6784 at the most significant bit position.  If operand 1 is 0, the
6785 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6786 the result is undefined or has a useful value.
6788 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
6789 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6790 integer mode is suitable for the target.  The compiler will insert
6791 conversion instructions as necessary (typically to convert the result
6792 to the same width as @code{int}).  When @var{m} is a vector, both
6793 operands must have mode @var{m}.
6795 This pattern is not allowed to @code{FAIL}.
6797 @cindex @code{ctz@var{m}2} instruction pattern
6798 @item @samp{ctz@var{m}2}
6799 Store into operand 0 the number of trailing 0-bits in operand 1, starting
6800 at the least significant bit position.  If operand 1 is 0, the
6801 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6802 the result is undefined or has a useful value.
6804 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
6805 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6806 integer mode is suitable for the target.  The compiler will insert
6807 conversion instructions as necessary (typically to convert the result
6808 to the same width as @code{int}).  When @var{m} is a vector, both
6809 operands must have mode @var{m}.
6811 This pattern is not allowed to @code{FAIL}.
6813 @cindex @code{popcount@var{m}2} instruction pattern
6814 @item @samp{popcount@var{m}2}
6815 Store into operand 0 the number of 1-bits in operand 1.
6817 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
6818 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6819 integer mode is suitable for the target.  The compiler will insert
6820 conversion instructions as necessary (typically to convert the result
6821 to the same width as @code{int}).  When @var{m} is a vector, both
6822 operands must have mode @var{m}.
6824 This pattern is not allowed to @code{FAIL}.
6826 @cindex @code{parity@var{m}2} instruction pattern
6827 @item @samp{parity@var{m}2}
6828 Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
6829 in operand 1 modulo 2.
6831 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
6832 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6833 integer mode is suitable for the target.  The compiler will insert
6834 conversion instructions as necessary (typically to convert the result
6835 to the same width as @code{int}).  When @var{m} is a vector, both
6836 operands must have mode @var{m}.
6838 This pattern is not allowed to @code{FAIL}.
6840 @cindex @code{one_cmpl@var{m}2} instruction pattern
6841 @item @samp{one_cmpl@var{m}2}
6842 Store the bitwise-complement of operand 1 into operand 0.
6844 @cindex @code{cpymem@var{m}} instruction pattern
6845 @item @samp{cpymem@var{m}}
6846 Block copy instruction.  The destination and source blocks of memory
6847 are the first two operands, and both are @code{mem:BLK}s with an
6848 address in mode @code{Pmode}.
6850 The number of bytes to copy is the third operand, in mode @var{m}.
6851 Usually, you specify @code{Pmode} for @var{m}.  However, if you can
6852 generate better code knowing the range of valid lengths is smaller than
6853 those representable in a full Pmode pointer, you should provide
6854 a pattern with a
6855 mode corresponding to the range of values you can handle efficiently
6856 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6857 that appear negative) and also a pattern with @code{Pmode}.
6859 The fourth operand is the known shared alignment of the source and
6860 destination, in the form of a @code{const_int} rtx.  Thus, if the
6861 compiler knows that both source and destination are word-aligned,
6862 it may provide the value 4 for this operand.
6864 Optional operands 5 and 6 specify expected alignment and size of block
6865 respectively.  The expected alignment differs from alignment in operand 4
6866 in a way that the blocks are not required to be aligned according to it in
6867 all cases. This expected alignment is also in bytes, just like operand 4.
6868 Expected size, when unknown, is set to @code{(const_int -1)}.
6870 Descriptions of multiple @code{cpymem@var{m}} patterns can only be
6871 beneficial if the patterns for smaller modes have fewer restrictions
6872 on their first, second and fourth operands.  Note that the mode @var{m}
6873 in @code{cpymem@var{m}} does not impose any restriction on the mode of
6874 individually copied data units in the block.
6876 The @code{cpymem@var{m}} patterns need not give special consideration
6877 to the possibility that the source and destination strings might
6878 overlap. These patterns are used to do inline expansion of
6879 @code{__builtin_memcpy}.
6881 @cindex @code{movmem@var{m}} instruction pattern
6882 @item @samp{movmem@var{m}}
6883 Block move instruction.  The destination and source blocks of memory
6884 are the first two operands, and both are @code{mem:BLK}s with an
6885 address in mode @code{Pmode}.
6887 The number of bytes to copy is the third operand, in mode @var{m}.
6888 Usually, you specify @code{Pmode} for @var{m}.  However, if you can
6889 generate better code knowing the range of valid lengths is smaller than
6890 those representable in a full Pmode pointer, you should provide
6891 a pattern with a
6892 mode corresponding to the range of values you can handle efficiently
6893 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6894 that appear negative) and also a pattern with @code{Pmode}.
6896 The fourth operand is the known shared alignment of the source and
6897 destination, in the form of a @code{const_int} rtx.  Thus, if the
6898 compiler knows that both source and destination are word-aligned,
6899 it may provide the value 4 for this operand.
6901 Optional operands 5 and 6 specify expected alignment and size of block
6902 respectively.  The expected alignment differs from alignment in operand 4
6903 in a way that the blocks are not required to be aligned according to it in
6904 all cases. This expected alignment is also in bytes, just like operand 4.
6905 Expected size, when unknown, is set to @code{(const_int -1)}.
6907 Descriptions of multiple @code{movmem@var{m}} patterns can only be
6908 beneficial if the patterns for smaller modes have fewer restrictions
6909 on their first, second and fourth operands.  Note that the mode @var{m}
6910 in @code{movmem@var{m}} does not impose any restriction on the mode of
6911 individually copied data units in the block.
6913 The @code{movmem@var{m}} patterns must correctly handle the case where
6914 the source and destination strings overlap. These patterns are used to
6915 do inline expansion of @code{__builtin_memmove}.
6917 @cindex @code{movstr} instruction pattern
6918 @item @samp{movstr}
6919 String copy instruction, with @code{stpcpy} semantics.  Operand 0 is
6920 an output operand in mode @code{Pmode}.  The addresses of the
6921 destination and source strings are operands 1 and 2, and both are
6922 @code{mem:BLK}s with addresses in mode @code{Pmode}.  The execution of
6923 the expansion of this pattern should store in operand 0 the address in
6924 which the @code{NUL} terminator was stored in the destination string.
6926 This pattern has also several optional operands that are same as in
6927 @code{setmem}.
6929 @cindex @code{setmem@var{m}} instruction pattern
6930 @item @samp{setmem@var{m}}
6931 Block set instruction.  The destination string is the first operand,
6932 given as a @code{mem:BLK} whose address is in mode @code{Pmode}.  The
6933 number of bytes to set is the second operand, in mode @var{m}.  The value to
6934 initialize the memory with is the third operand. Targets that only support the
6935 clearing of memory should reject any value that is not the constant 0.  See
6936 @samp{cpymem@var{m}} for a discussion of the choice of mode.
6938 The fourth operand is the known alignment of the destination, in the form
6939 of a @code{const_int} rtx.  Thus, if the compiler knows that the
6940 destination is word-aligned, it may provide the value 4 for this
6941 operand.
6943 Optional operands 5 and 6 specify expected alignment and size of block
6944 respectively.  The expected alignment differs from alignment in operand 4
6945 in a way that the blocks are not required to be aligned according to it in
6946 all cases. This expected alignment is also in bytes, just like operand 4.
6947 Expected size, when unknown, is set to @code{(const_int -1)}.
6948 Operand 7 is the minimal size of the block and operand 8 is the
6949 maximal size of the block (NULL if it cannot be represented as CONST_INT).
6950 Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for
6951 correctness, but it can be used for choosing proper code sequence for a
6952 given size).
6954 The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}.
6956 @cindex @code{cmpstrn@var{m}} instruction pattern
6957 @item @samp{cmpstrn@var{m}}
6958 String compare instruction, with five operands.  Operand 0 is the output;
6959 it has mode @var{m}.  The remaining four operands are like the operands
6960 of @samp{cpymem@var{m}}.  The two memory blocks specified are compared
6961 byte by byte in lexicographic order starting at the beginning of each
6962 string.  The instruction is not allowed to prefetch more than one byte
6963 at a time since either string may end in the first byte and reading past
6964 that may access an invalid page or segment and cause a fault.  The
6965 comparison terminates early if the fetched bytes are different or if
6966 they are equal to zero.  The effect of the instruction is to store a
6967 value in operand 0 whose sign indicates the result of the comparison.
6969 @cindex @code{cmpstr@var{m}} instruction pattern
6970 @item @samp{cmpstr@var{m}}
6971 String compare instruction, without known maximum length.  Operand 0 is the
6972 output; it has mode @var{m}.  The second and third operand are the blocks of
6973 memory to be compared; both are @code{mem:BLK} with an address in mode
6974 @code{Pmode}.
6976 The fourth operand is the known shared alignment of the source and
6977 destination, in the form of a @code{const_int} rtx.  Thus, if the
6978 compiler knows that both source and destination are word-aligned,
6979 it may provide the value 4 for this operand.
6981 The two memory blocks specified are compared byte by byte in lexicographic
6982 order starting at the beginning of each string.  The instruction is not allowed
6983 to prefetch more than one byte at a time since either string may end in the
6984 first byte and reading past that may access an invalid page or segment and
6985 cause a fault.  The comparison will terminate when the fetched bytes
6986 are different or if they are equal to zero.  The effect of the
6987 instruction is to store a value in operand 0 whose sign indicates the
6988 result of the comparison.
6990 @cindex @code{cmpmem@var{m}} instruction pattern
6991 @item @samp{cmpmem@var{m}}
6992 Block compare instruction, with five operands like the operands
6993 of @samp{cmpstr@var{m}}.  The two memory blocks specified are compared
6994 byte by byte in lexicographic order starting at the beginning of each
6995 block.  Unlike @samp{cmpstr@var{m}} the instruction can prefetch
6996 any bytes in the two memory blocks.  Also unlike @samp{cmpstr@var{m}}
6997 the comparison will not stop if both bytes are zero.  The effect of
6998 the instruction is to store a value in operand 0 whose sign indicates
6999 the result of the comparison.
7001 @cindex @code{strlen@var{m}} instruction pattern
7002 @item @samp{strlen@var{m}}
7003 Compute the length of a string, with three operands.
7004 Operand 0 is the result (of mode @var{m}), operand 1 is
7005 a @code{mem} referring to the first character of the string,
7006 operand 2 is the character to search for (normally zero),
7007 and operand 3 is a constant describing the known alignment
7008 of the beginning of the string.
7010 @cindex @code{rawmemchr@var{m}} instruction pattern
7011 @item @samp{rawmemchr@var{m}}
7012 Scan memory referred to by operand 1 for the first occurrence of operand 2.
7013 Operand 1 is a @code{mem} and operand 2 a @code{const_int} of mode @var{m}.
7014 Operand 0 is the result, i.e., a pointer to the first occurrence of operand 2
7015 in the memory block given by operand 1.
7017 @cindex @code{float@var{m}@var{n}2} instruction pattern
7018 @item @samp{float@var{m}@var{n}2}
7019 Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
7020 floating point mode @var{n} and store in operand 0 (which has mode
7021 @var{n}).
7023 @cindex @code{floatuns@var{m}@var{n}2} instruction pattern
7024 @item @samp{floatuns@var{m}@var{n}2}
7025 Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
7026 to floating point mode @var{n} and store in operand 0 (which has mode
7027 @var{n}).
7029 @cindex @code{fix@var{m}@var{n}2} instruction pattern
7030 @item @samp{fix@var{m}@var{n}2}
7031 Convert operand 1 (valid for floating point mode @var{m}) to fixed
7032 point mode @var{n} as a signed number and store in operand 0 (which
7033 has mode @var{n}).  This instruction's result is defined only when
7034 the value of operand 1 is an integer.
7036 If the machine description defines this pattern, it also needs to
7037 define the @code{ftrunc} pattern.
7039 @cindex @code{fixuns@var{m}@var{n}2} instruction pattern
7040 @item @samp{fixuns@var{m}@var{n}2}
7041 Convert operand 1 (valid for floating point mode @var{m}) to fixed
7042 point mode @var{n} as an unsigned number and store in operand 0 (which
7043 has mode @var{n}).  This instruction's result is defined only when the
7044 value of operand 1 is an integer.
7046 @cindex @code{ftrunc@var{m}2} instruction pattern
7047 @item @samp{ftrunc@var{m}2}
7048 Convert operand 1 (valid for floating point mode @var{m}) to an
7049 integer value, still represented in floating point mode @var{m}, and
7050 store it in operand 0 (valid for floating point mode @var{m}).
7052 @cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
7053 @item @samp{fix_trunc@var{m}@var{n}2}
7054 Like @samp{fix@var{m}@var{n}2} but works for any floating point value
7055 of mode @var{m} by converting the value to an integer.
7057 @cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
7058 @item @samp{fixuns_trunc@var{m}@var{n}2}
7059 Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
7060 value of mode @var{m} by converting the value to an integer.
7062 @cindex @code{trunc@var{m}@var{n}2} instruction pattern
7063 @item @samp{trunc@var{m}@var{n}2}
7064 Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
7065 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
7066 point or both floating point.
7068 @cindex @code{extend@var{m}@var{n}2} instruction pattern
7069 @item @samp{extend@var{m}@var{n}2}
7070 Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
7071 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
7072 point or both floating point.
7074 @cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
7075 @item @samp{zero_extend@var{m}@var{n}2}
7076 Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
7077 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
7078 point.
7080 @cindex @code{fract@var{m}@var{n}2} instruction pattern
7081 @item @samp{fract@var{m}@var{n}2}
7082 Convert operand 1 of mode @var{m} to mode @var{n} and store in
7083 operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
7084 could be fixed-point to fixed-point, signed integer to fixed-point,
7085 fixed-point to signed integer, floating-point to fixed-point,
7086 or fixed-point to floating-point.
7087 When overflows or underflows happen, the results are undefined.
7089 @cindex @code{satfract@var{m}@var{n}2} instruction pattern
7090 @item @samp{satfract@var{m}@var{n}2}
7091 Convert operand 1 of mode @var{m} to mode @var{n} and store in
7092 operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
7093 could be fixed-point to fixed-point, signed integer to fixed-point,
7094 or floating-point to fixed-point.
7095 When overflows or underflows happen, the instruction saturates the
7096 results to the maximum or the minimum.
7098 @cindex @code{fractuns@var{m}@var{n}2} instruction pattern
7099 @item @samp{fractuns@var{m}@var{n}2}
7100 Convert operand 1 of mode @var{m} to mode @var{n} and store in
7101 operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
7102 could be unsigned integer to fixed-point, or
7103 fixed-point to unsigned integer.
7104 When overflows or underflows happen, the results are undefined.
7106 @cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
7107 @item @samp{satfractuns@var{m}@var{n}2}
7108 Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
7109 @var{n} and store in operand 0 (which has mode @var{n}).
7110 When overflows or underflows happen, the instruction saturates the
7111 results to the maximum or the minimum.
7113 @cindex @code{extv@var{m}} instruction pattern
7114 @item @samp{extv@var{m}}
7115 Extract a bit-field from register operand 1, sign-extend it, and store
7116 it in operand 0.  Operand 2 specifies the width of the field in bits
7117 and operand 3 the starting bit, which counts from the most significant
7118 bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit
7119 otherwise.
7121 Operands 0 and 1 both have mode @var{m}.  Operands 2 and 3 have a
7122 target-specific mode.
7124 @cindex @code{extvmisalign@var{m}} instruction pattern
7125 @item @samp{extvmisalign@var{m}}
7126 Extract a bit-field from memory operand 1, sign extend it, and store
7127 it in operand 0.  Operand 2 specifies the width in bits and operand 3
7128 the starting bit.  The starting bit is always somewhere in the first byte of
7129 operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
7130 is true and from the least significant bit otherwise.
7132 Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode.
7133 Operands 2 and 3 have a target-specific mode.
7135 The instruction must not read beyond the last byte of the bit-field.
7137 @cindex @code{extzv@var{m}} instruction pattern
7138 @item @samp{extzv@var{m}}
7139 Like @samp{extv@var{m}} except that the bit-field value is zero-extended.
7141 @cindex @code{extzvmisalign@var{m}} instruction pattern
7142 @item @samp{extzvmisalign@var{m}}
7143 Like @samp{extvmisalign@var{m}} except that the bit-field value is
7144 zero-extended.
7146 @cindex @code{insv@var{m}} instruction pattern
7147 @item @samp{insv@var{m}}
7148 Insert operand 3 into a bit-field of register operand 0.  Operand 1
7149 specifies the width of the field in bits and operand 2 the starting bit,
7150 which counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
7151 is true and from the least significant bit otherwise.
7153 Operands 0 and 3 both have mode @var{m}.  Operands 1 and 2 have a
7154 target-specific mode.
7156 @cindex @code{insvmisalign@var{m}} instruction pattern
7157 @item @samp{insvmisalign@var{m}}
7158 Insert operand 3 into a bit-field of memory operand 0.  Operand 1
7159 specifies the width of the field in bits and operand 2 the starting bit.
7160 The starting bit is always somewhere in the first byte of operand 0;
7161 it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
7162 is true and from the least significant bit otherwise.
7164 Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode.
7165 Operands 1 and 2 have a target-specific mode.
7167 The instruction must not read or write beyond the last byte of the bit-field.
7169 @cindex @code{extv} instruction pattern
7170 @item @samp{extv}
7171 Extract a bit-field from operand 1 (a register or memory operand), where
7172 operand 2 specifies the width in bits and operand 3 the starting bit,
7173 and store it in operand 0.  Operand 0 must have mode @code{word_mode}.
7174 Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
7175 @code{word_mode} is allowed only for registers.  Operands 2 and 3 must
7176 be valid for @code{word_mode}.
7178 The RTL generation pass generates this instruction only with constants
7179 for operands 2 and 3 and the constant is never zero for operand 2.
7181 The bit-field value is sign-extended to a full word integer
7182 before it is stored in operand 0.
7184 This pattern is deprecated; please use @samp{extv@var{m}} and
7185 @code{extvmisalign@var{m}} instead.
7187 @cindex @code{extzv} instruction pattern
7188 @item @samp{extzv}
7189 Like @samp{extv} except that the bit-field value is zero-extended.
7191 This pattern is deprecated; please use @samp{extzv@var{m}} and
7192 @code{extzvmisalign@var{m}} instead.
7194 @cindex @code{insv} instruction pattern
7195 @item @samp{insv}
7196 Store operand 3 (which must be valid for @code{word_mode}) into a
7197 bit-field in operand 0, where operand 1 specifies the width in bits and
7198 operand 2 the starting bit.  Operand 0 may have mode @code{byte_mode} or
7199 @code{word_mode}; often @code{word_mode} is allowed only for registers.
7200 Operands 1 and 2 must be valid for @code{word_mode}.
7202 The RTL generation pass generates this instruction only with constants
7203 for operands 1 and 2 and the constant is never zero for operand 1.
7205 This pattern is deprecated; please use @samp{insv@var{m}} and
7206 @code{insvmisalign@var{m}} instead.
7208 @cindex @code{mov@var{mode}cc} instruction pattern
7209 @item @samp{mov@var{mode}cc}
7210 Conditionally move operand 2 or operand 3 into operand 0 according to the
7211 comparison in operand 1.  If the comparison is true, operand 2 is moved
7212 into operand 0, otherwise operand 3 is moved.
7214 The mode of the operands being compared need not be the same as the operands
7215 being moved.  Some machines, sparc64 for example, have instructions that
7216 conditionally move an integer value based on the floating point condition
7217 codes and vice versa.
7219 If the machine does not have conditional move instructions, do not
7220 define these patterns.
7222 @cindex @code{add@var{mode}cc} instruction pattern
7223 @item @samp{add@var{mode}cc}
7224 Similar to @samp{mov@var{mode}cc} but for conditional addition.  Conditionally
7225 move operand 2 or (operands 2 + operand 3) into operand 0 according to the
7226 comparison in operand 1.  If the comparison is false, operand 2 is moved into
7227 operand 0, otherwise (operand 2 + operand 3) is moved.
7229 @cindex @code{cond_neg@var{mode}} instruction pattern
7230 @cindex @code{cond_one_cmpl@var{mode}} instruction pattern
7231 @item @samp{cond_neg@var{mode}}
7232 @itemx @samp{cond_one_cmpl@var{mode}}
7233 When operand 1 is true, perform an operation on operands 2 and
7234 store the result in operand 0, otherwise store operand 3 in operand 0.
7235 The operation works elementwise if the operands are vectors.
7237 The scalar case is equivalent to:
7239 @smallexample
7240 op0 = op1 ? @var{op} op2 : op3;
7241 @end smallexample
7243 while the vector case is equivalent to:
7245 @smallexample
7246 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7247   op0[i] = op1[i] ? @var{op} op2[i] : op3[i];
7248 @end smallexample
7250 where, for example, @var{op} is @code{~} for @samp{cond_one_cmpl@var{mode}}.
7252 When defined for floating-point modes, the contents of @samp{op2[i]}
7253 are not interpreted if @samp{op1[i]} is false, just like they would not
7254 be in a normal C @samp{?:} condition.
7256 Operands 0, 2, and 3 all have mode @var{m}.  Operand 1 is a scalar
7257 integer if @var{m} is scalar, otherwise it has the mode returned by
7258 @code{TARGET_VECTORIZE_GET_MASK_MODE}.
7260 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
7261 form of @samp{@var{op}@var{mode}2}.
7263 @cindex @code{cond_add@var{mode}} instruction pattern
7264 @cindex @code{cond_sub@var{mode}} instruction pattern
7265 @cindex @code{cond_mul@var{mode}} instruction pattern
7266 @cindex @code{cond_div@var{mode}} instruction pattern
7267 @cindex @code{cond_udiv@var{mode}} instruction pattern
7268 @cindex @code{cond_mod@var{mode}} instruction pattern
7269 @cindex @code{cond_umod@var{mode}} instruction pattern
7270 @cindex @code{cond_and@var{mode}} instruction pattern
7271 @cindex @code{cond_ior@var{mode}} instruction pattern
7272 @cindex @code{cond_xor@var{mode}} instruction pattern
7273 @cindex @code{cond_smin@var{mode}} instruction pattern
7274 @cindex @code{cond_smax@var{mode}} instruction pattern
7275 @cindex @code{cond_umin@var{mode}} instruction pattern
7276 @cindex @code{cond_umax@var{mode}} instruction pattern
7277 @cindex @code{cond_fmin@var{mode}} instruction pattern
7278 @cindex @code{cond_fmax@var{mode}} instruction pattern
7279 @cindex @code{cond_ashl@var{mode}} instruction pattern
7280 @cindex @code{cond_ashr@var{mode}} instruction pattern
7281 @cindex @code{cond_lshr@var{mode}} instruction pattern
7282 @item @samp{cond_add@var{mode}}
7283 @itemx @samp{cond_sub@var{mode}}
7284 @itemx @samp{cond_mul@var{mode}}
7285 @itemx @samp{cond_div@var{mode}}
7286 @itemx @samp{cond_udiv@var{mode}}
7287 @itemx @samp{cond_mod@var{mode}}
7288 @itemx @samp{cond_umod@var{mode}}
7289 @itemx @samp{cond_and@var{mode}}
7290 @itemx @samp{cond_ior@var{mode}}
7291 @itemx @samp{cond_xor@var{mode}}
7292 @itemx @samp{cond_smin@var{mode}}
7293 @itemx @samp{cond_smax@var{mode}}
7294 @itemx @samp{cond_umin@var{mode}}
7295 @itemx @samp{cond_umax@var{mode}}
7296 @itemx @samp{cond_fmin@var{mode}}
7297 @itemx @samp{cond_fmax@var{mode}}
7298 @itemx @samp{cond_ashl@var{mode}}
7299 @itemx @samp{cond_ashr@var{mode}}
7300 @itemx @samp{cond_lshr@var{mode}}
7301 When operand 1 is true, perform an operation on operands 2 and 3 and
7302 store the result in operand 0, otherwise store operand 4 in operand 0.
7303 The operation works elementwise if the operands are vectors.
7305 The scalar case is equivalent to:
7307 @smallexample
7308 op0 = op1 ? op2 @var{op} op3 : op4;
7309 @end smallexample
7311 while the vector case is equivalent to:
7313 @smallexample
7314 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7315   op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i];
7316 @end smallexample
7318 where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}.
7320 When defined for floating-point modes, the contents of @samp{op3[i]}
7321 are not interpreted if @samp{op1[i]} is false, just like they would not
7322 be in a normal C @samp{?:} condition.
7324 Operands 0, 2, 3 and 4 all have mode @var{m}.  Operand 1 is a scalar
7325 integer if @var{m} is scalar, otherwise it has the mode returned by
7326 @code{TARGET_VECTORIZE_GET_MASK_MODE}.
7328 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
7329 form of @samp{@var{op}@var{mode}3}.  As an exception, the vector forms
7330 of shifts correspond to patterns like @code{vashl@var{mode}3} rather
7331 than patterns like @code{ashl@var{mode}3}.
7333 @cindex @code{cond_fma@var{mode}} instruction pattern
7334 @cindex @code{cond_fms@var{mode}} instruction pattern
7335 @cindex @code{cond_fnma@var{mode}} instruction pattern
7336 @cindex @code{cond_fnms@var{mode}} instruction pattern
7337 @item @samp{cond_fma@var{mode}}
7338 @itemx @samp{cond_fms@var{mode}}
7339 @itemx @samp{cond_fnma@var{mode}}
7340 @itemx @samp{cond_fnms@var{mode}}
7341 Like @samp{cond_add@var{m}}, except that the conditional operation
7342 takes 3 operands rather than two.  For example, the vector form of
7343 @samp{cond_fma@var{mode}} is equivalent to:
7345 @smallexample
7346 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7347   op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i];
7348 @end smallexample
7350 @cindex @code{cond_len_neg@var{mode}} instruction pattern
7351 @cindex @code{cond_len_one_cmpl@var{mode}} instruction pattern
7352 @item @samp{cond_len_neg@var{mode}}
7353 @itemx @samp{cond_len_one_cmpl@var{mode}}
7354 When operand 1 is true and element index < operand 4 + operand 5, perform an operation on operands 1 and
7355 store the result in operand 0, otherwise store operand 2 in operand 0.
7356 The operation only works for the operands are vectors.
7358 @smallexample
7359 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7360   op0[i] = (i < ops[4] + ops[5] && op1[i]
7361             ? @var{op} op2[i]
7362             : op3[i]);
7363 @end smallexample
7365 where, for example, @var{op} is @code{~} for @samp{cond_len_one_cmpl@var{mode}}.
7367 When defined for floating-point modes, the contents of @samp{op2[i]}
7368 are not interpreted if @samp{op1[i]} is false, just like they would not
7369 be in a normal C @samp{?:} condition.
7371 Operands 0, 2, and 3 all have mode @var{m}.  Operand 1 is a scalar
7372 integer if @var{m} is scalar, otherwise it has the mode returned by
7373 @code{TARGET_VECTORIZE_GET_MASK_MODE}.  Operand 4 has whichever
7374 integer mode the target prefers.
7376 @samp{cond_len_@var{op}@var{mode}} generally corresponds to a conditional
7377 form of @samp{@var{op}@var{mode}2}.
7380 @cindex @code{cond_len_add@var{mode}} instruction pattern
7381 @cindex @code{cond_len_sub@var{mode}} instruction pattern
7382 @cindex @code{cond_len_mul@var{mode}} instruction pattern
7383 @cindex @code{cond_len_div@var{mode}} instruction pattern
7384 @cindex @code{cond_len_udiv@var{mode}} instruction pattern
7385 @cindex @code{cond_len_mod@var{mode}} instruction pattern
7386 @cindex @code{cond_len_umod@var{mode}} instruction pattern
7387 @cindex @code{cond_len_and@var{mode}} instruction pattern
7388 @cindex @code{cond_len_ior@var{mode}} instruction pattern
7389 @cindex @code{cond_len_xor@var{mode}} instruction pattern
7390 @cindex @code{cond_len_smin@var{mode}} instruction pattern
7391 @cindex @code{cond_len_smax@var{mode}} instruction pattern
7392 @cindex @code{cond_len_umin@var{mode}} instruction pattern
7393 @cindex @code{cond_len_umax@var{mode}} instruction pattern
7394 @cindex @code{cond_len_fmin@var{mode}} instruction pattern
7395 @cindex @code{cond_len_fmax@var{mode}} instruction pattern
7396 @cindex @code{cond_len_ashl@var{mode}} instruction pattern
7397 @cindex @code{cond_len_ashr@var{mode}} instruction pattern
7398 @cindex @code{cond_len_lshr@var{mode}} instruction pattern
7399 @item @samp{cond_len_add@var{mode}}
7400 @itemx @samp{cond_len_sub@var{mode}}
7401 @itemx @samp{cond_len_mul@var{mode}}
7402 @itemx @samp{cond_len_div@var{mode}}
7403 @itemx @samp{cond_len_udiv@var{mode}}
7404 @itemx @samp{cond_len_mod@var{mode}}
7405 @itemx @samp{cond_len_umod@var{mode}}
7406 @itemx @samp{cond_len_and@var{mode}}
7407 @itemx @samp{cond_len_ior@var{mode}}
7408 @itemx @samp{cond_len_xor@var{mode}}
7409 @itemx @samp{cond_len_smin@var{mode}}
7410 @itemx @samp{cond_len_smax@var{mode}}
7411 @itemx @samp{cond_len_umin@var{mode}}
7412 @itemx @samp{cond_len_umax@var{mode}}
7413 @itemx @samp{cond_len_fmin@var{mode}}
7414 @itemx @samp{cond_len_fmax@var{mode}}
7415 @itemx @samp{cond_len_ashl@var{mode}}
7416 @itemx @samp{cond_len_ashr@var{mode}}
7417 @itemx @samp{cond_len_lshr@var{mode}}
7418 When operand 1 is true and element index < operand 5 + operand 6, perform an operation on operands 2 and 3 and
7419 store the result in operand 0, otherwise store operand 4 in operand 0.
7420 The operation only works for the operands are vectors.
7422 @smallexample
7423 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7424   op0[i] = (i < ops[5] + ops[6] && op1[i]
7425             ? op2[i] @var{op} op3[i]
7426             : op4[i]);
7427 @end smallexample
7429 where, for example, @var{op} is @code{+} for @samp{cond_len_add@var{mode}}.
7431 When defined for floating-point modes, the contents of @samp{op3[i]}
7432 are not interpreted if @samp{op1[i]} is false, just like they would not
7433 be in a normal C @samp{?:} condition.
7435 Operands 0, 2, 3 and 4 all have mode @var{m}.  Operand 1 is a scalar
7436 integer if @var{m} is scalar, otherwise it has the mode returned by
7437 @code{TARGET_VECTORIZE_GET_MASK_MODE}.  Operand 5 has whichever
7438 integer mode the target prefers.
7440 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
7441 form of @samp{@var{op}@var{mode}3}.  As an exception, the vector forms
7442 of shifts correspond to patterns like @code{vashl@var{mode}3} rather
7443 than patterns like @code{ashl@var{mode}3}.
7445 @cindex @code{cond_len_fma@var{mode}} instruction pattern
7446 @cindex @code{cond_len_fms@var{mode}} instruction pattern
7447 @cindex @code{cond_len_fnma@var{mode}} instruction pattern
7448 @cindex @code{cond_len_fnms@var{mode}} instruction pattern
7449 @item @samp{cond_len_fma@var{mode}}
7450 @itemx @samp{cond_len_fms@var{mode}}
7451 @itemx @samp{cond_len_fnma@var{mode}}
7452 @itemx @samp{cond_len_fnms@var{mode}}
7453 Like @samp{cond_len_add@var{m}}, except that the conditional operation
7454 takes 3 operands rather than two.  For example, the vector form of
7455 @samp{cond_len_fma@var{mode}} is equivalent to:
7457 @smallexample
7458 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7459   op0[i] = (i < ops[6] + ops[7] && op1[i]
7460             ? fma (op2[i], op3[i], op4[i])
7461             : op5[i]);
7462 @end smallexample
7464 @cindex @code{neg@var{mode}cc} instruction pattern
7465 @item @samp{neg@var{mode}cc}
7466 Similar to @samp{mov@var{mode}cc} but for conditional negation.  Conditionally
7467 move the negation of operand 2 or the unchanged operand 3 into operand 0
7468 according to the comparison in operand 1.  If the comparison is true, the negation
7469 of operand 2 is moved into operand 0, otherwise operand 3 is moved.
7471 @cindex @code{not@var{mode}cc} instruction pattern
7472 @item @samp{not@var{mode}cc}
7473 Similar to @samp{neg@var{mode}cc} but for conditional complement.
7474 Conditionally move the bitwise complement of operand 2 or the unchanged
7475 operand 3 into operand 0 according to the comparison in operand 1.
7476 If the comparison is true, the complement of operand 2 is moved into
7477 operand 0, otherwise operand 3 is moved.
7479 @cindex @code{cstore@var{mode}4} instruction pattern
7480 @item @samp{cstore@var{mode}4}
7481 Store zero or nonzero in operand 0 according to whether a comparison
7482 is true.  Operand 1 is a comparison operator.  Operand 2 and operand 3
7483 are the first and second operand of the comparison, respectively.
7484 You specify the mode that operand 0 must have when you write the
7485 @code{match_operand} expression.  The compiler automatically sees which
7486 mode you have used and supplies an operand of that mode.
7488 The value stored for a true condition must have 1 as its low bit, or
7489 else must be negative.  Otherwise the instruction is not suitable and
7490 you should omit it from the machine description.  You describe to the
7491 compiler exactly which value is stored by defining the macro
7492 @code{STORE_FLAG_VALUE} (@pxref{Misc}).  If a description cannot be
7493 found that can be used for all the possible comparison operators, you
7494 should pick one and use a @code{define_expand} to map all results
7495 onto the one you chose.
7497 These operations may @code{FAIL}, but should do so only in relatively
7498 uncommon cases; if they would @code{FAIL} for common cases involving
7499 integer comparisons, it is best to restrict the predicates to not
7500 allow these operands.  Likewise if a given comparison operator will
7501 always fail, independent of the operands (for floating-point modes, the
7502 @code{ordered_comparison_operator} predicate is often useful in this case).
7504 If this pattern is omitted, the compiler will generate a conditional
7505 branch---for example, it may copy a constant one to the target and branching
7506 around an assignment of zero to the target---or a libcall.  If the predicate
7507 for operand 1 only rejects some operators, it will also try reordering the
7508 operands and/or inverting the result value (e.g.@: by an exclusive OR).
7509 These possibilities could be cheaper or equivalent to the instructions
7510 used for the @samp{cstore@var{mode}4} pattern followed by those required
7511 to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
7512 case, you can and should make operand 1's predicate reject some operators
7513 in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
7514 from the machine description.
7516 @cindex @code{tbranch_@var{op}@var{mode}3} instruction pattern
7517 @item @samp{tbranch_@var{op}@var{mode}3}
7518 Conditional branch instruction combined with a bit test-and-compare
7519 instruction. Operand 0 is the operand of the comparison.  Operand 1 is the bit
7520 position of Operand 1 to test.  Operand 3 is the @code{code_label} to jump to.
7521 @var{op} is one of @var{eq} or @var{ne}.
7523 @cindex @code{cbranch@var{mode}4} instruction pattern
7524 @item @samp{cbranch@var{mode}4}
7525 Conditional branch instruction combined with a compare instruction.
7526 Operand 0 is a comparison operator.  Operand 1 and operand 2 are the
7527 first and second operands of the comparison, respectively.  Operand 3
7528 is the @code{code_label} to jump to.
7530 @cindex @code{jump} instruction pattern
7531 @item @samp{jump}
7532 A jump inside a function; an unconditional branch.  Operand 0 is the
7533 @code{code_label} to jump to.  This pattern name is mandatory on all
7534 machines.
7536 @cindex @code{call} instruction pattern
7537 @item @samp{call}
7538 Subroutine call instruction returning no value.  Operand 0 is the
7539 function to call; operand 1 is the number of bytes of arguments pushed
7540 as a @code{const_int}.  Operand 2 is the result of calling the target
7541 hook @code{TARGET_FUNCTION_ARG} with the second argument @code{arg}
7542 yielding true for @code{arg.end_marker_p ()}, in a call after all
7543 parameters have been passed to that hook.  By default this is the first
7544 register beyond those used for arguments in the call, or @code{NULL} if
7545 all the argument-registers are used in the call.
7547 On most machines, operand 2 is not actually stored into the RTL
7548 pattern.  It is supplied for the sake of some RISC machines which need
7549 to put this information into the assembler code; they can put it in
7550 the RTL instead of operand 1.
7552 Operand 0 should be a @code{mem} RTX whose address is the address of the
7553 function.  Note, however, that this address can be a @code{symbol_ref}
7554 expression even if it would not be a legitimate memory address on the
7555 target machine.  If it is also not a valid argument for a call
7556 instruction, the pattern for this operation should be a
7557 @code{define_expand} (@pxref{Expander Definitions}) that places the
7558 address into a register and uses that register in the call instruction.
7560 @cindex @code{call_value} instruction pattern
7561 @item @samp{call_value}
7562 Subroutine call instruction returning a value.  Operand 0 is the hard
7563 register in which the value is returned.  There are three more
7564 operands, the same as the three operands of the @samp{call}
7565 instruction (but with numbers increased by one).
7567 Subroutines that return @code{BLKmode} objects use the @samp{call}
7568 insn.
7570 @cindex @code{call_pop} instruction pattern
7571 @cindex @code{call_value_pop} instruction pattern
7572 @item @samp{call_pop}, @samp{call_value_pop}
7573 Similar to @samp{call} and @samp{call_value}, except used if defined and
7574 if @code{RETURN_POPS_ARGS} is nonzero.  They should emit a @code{parallel}
7575 that contains both the function call and a @code{set} to indicate the
7576 adjustment made to the frame pointer.
7578 For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
7579 patterns increases the number of functions for which the frame pointer
7580 can be eliminated, if desired.
7582 @cindex @code{untyped_call} instruction pattern
7583 @item @samp{untyped_call}
7584 Subroutine call instruction returning a value of any type.  Operand 0 is
7585 the function to call; operand 1 is a memory location where the result of
7586 calling the function is to be stored; operand 2 is a @code{parallel}
7587 expression where each element is a @code{set} expression that indicates
7588 the saving of a function return value into the result block.
7590 This instruction pattern should be defined to support
7591 @code{__builtin_apply} on machines where special instructions are needed
7592 to call a subroutine with arbitrary arguments or to save the value
7593 returned.  This instruction pattern is required on machines that have
7594 multiple registers that can hold a return value
7595 (i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
7597 @cindex @code{return} instruction pattern
7598 @item @samp{return}
7599 Subroutine return instruction.  This instruction pattern name should be
7600 defined only if a single instruction can do all the work of returning
7601 from a function.
7603 Like the @samp{mov@var{m}} patterns, this pattern is also used after the
7604 RTL generation phase.  In this case it is to support machines where
7605 multiple instructions are usually needed to return from a function, but
7606 some class of functions only requires one instruction to implement a
7607 return.  Normally, the applicable functions are those which do not need
7608 to save any registers or allocate stack space.
7610 It is valid for this pattern to expand to an instruction using
7611 @code{simple_return} if no epilogue is required.
7613 @cindex @code{simple_return} instruction pattern
7614 @item @samp{simple_return}
7615 Subroutine return instruction.  This instruction pattern name should be
7616 defined only if a single instruction can do all the work of returning
7617 from a function on a path where no epilogue is required.  This pattern
7618 is very similar to the @code{return} instruction pattern, but it is emitted
7619 only by the shrink-wrapping optimization on paths where the function
7620 prologue has not been executed, and a function return should occur without
7621 any of the effects of the epilogue.  Additional uses may be introduced on
7622 paths where both the prologue and the epilogue have executed.
7624 @findex reload_completed
7625 @findex leaf_function_p
7626 For such machines, the condition specified in this pattern should only
7627 be true when @code{reload_completed} is nonzero and the function's
7628 epilogue would only be a single instruction.  For machines with register
7629 windows, the routine @code{leaf_function_p} may be used to determine if
7630 a register window push is required.
7632 Machines that have conditional return instructions should define patterns
7633 such as
7635 @smallexample
7636 (define_insn ""
7637   [(set (pc)
7638         (if_then_else (match_operator
7639                          0 "comparison_operator"
7640                          [(reg:CC CC_REG) (const_int 0)])
7641                       (return)
7642                       (pc)))]
7643   "@var{condition}"
7644   "@dots{}")
7645 @end smallexample
7647 where @var{condition} would normally be the same condition specified on the
7648 named @samp{return} pattern.
7650 @cindex @code{untyped_return} instruction pattern
7651 @item @samp{untyped_return}
7652 Untyped subroutine return instruction.  This instruction pattern should
7653 be defined to support @code{__builtin_return} on machines where special
7654 instructions are needed to return a value of any type.
7656 Operand 0 is a memory location where the result of calling a function
7657 with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
7658 expression where each element is a @code{set} expression that indicates
7659 the restoring of a function return value from the result block.
7661 @cindex @code{nop} instruction pattern
7662 @item @samp{nop}
7663 No-op instruction.  This instruction pattern name should always be defined
7664 to output a no-op in assembler code.  @code{(const_int 0)} will do as an
7665 RTL pattern.
7667 @cindex @code{indirect_jump} instruction pattern
7668 @item @samp{indirect_jump}
7669 An instruction to jump to an address which is operand zero.
7670 This pattern name is mandatory on all machines.
7672 @cindex @code{casesi} instruction pattern
7673 @item @samp{casesi}
7674 Instruction to jump through a dispatch table, including bounds checking.
7675 This instruction takes five operands:
7677 @enumerate
7678 @item
7679 The index to dispatch on, which has mode @code{SImode}.
7681 @item
7682 The lower bound for indices in the table, an integer constant.
7684 @item
7685 The total range of indices in the table---the largest index
7686 minus the smallest one (both inclusive).
7688 @item
7689 A label that precedes the table itself.
7691 @item
7692 A label to jump to if the index has a value outside the bounds.
7693 @end enumerate
7695 The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
7696 @code{jump_table_data}.  The number of elements in the table is one plus the
7697 difference between the upper bound and the lower bound.
7699 @cindex @code{tablejump} instruction pattern
7700 @item @samp{tablejump}
7701 Instruction to jump to a variable address.  This is a low-level
7702 capability which can be used to implement a dispatch table when there
7703 is no @samp{casesi} pattern.
7705 This pattern requires two operands: the address or offset, and a label
7706 which should immediately precede the jump table.  If the macro
7707 @code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
7708 operand is an offset which counts from the address of the table; otherwise,
7709 it is an absolute address to jump to.  In either case, the first operand has
7710 mode @code{Pmode}.
7712 The @samp{tablejump} insn is always the last insn before the jump
7713 table it uses.  Its assembler code normally has no need to use the
7714 second operand, but you should incorporate it in the RTL pattern so
7715 that the jump optimizer will not delete the table as unreachable code.
7718 @cindex @code{doloop_end} instruction pattern
7719 @item @samp{doloop_end}
7720 Conditional branch instruction that decrements a register and
7721 jumps if the register is nonzero.  Operand 0 is the register to
7722 decrement and test; operand 1 is the label to jump to if the
7723 register is nonzero.
7724 @xref{Looping Patterns}.
7726 This optional instruction pattern should be defined for machines with
7727 low-overhead looping instructions as the loop optimizer will try to
7728 modify suitable loops to utilize it.  The target hook
7729 @code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which
7730 low-overhead loops can be used.
7732 @cindex @code{doloop_begin} instruction pattern
7733 @item @samp{doloop_begin}
7734 Companion instruction to @code{doloop_end} required for machines that
7735 need to perform some initialization, such as loading a special counter
7736 register.  Operand 1 is the associated @code{doloop_end} pattern and
7737 operand 0 is the register that it decrements.
7739 If initialization insns do not always need to be emitted, use a
7740 @code{define_expand} (@pxref{Expander Definitions}) and make it fail.
7742 @cindex @code{canonicalize_funcptr_for_compare} instruction pattern
7743 @item @samp{canonicalize_funcptr_for_compare}
7744 Canonicalize the function pointer in operand 1 and store the result
7745 into operand 0.
7747 Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
7748 may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
7749 and also has mode @code{Pmode}.
7751 Canonicalization of a function pointer usually involves computing
7752 the address of the function which would be called if the function
7753 pointer were used in an indirect call.
7755 Only define this pattern if function pointers on the target machine
7756 can have different values but still call the same function when
7757 used in an indirect call.
7759 @cindex @code{save_stack_block} instruction pattern
7760 @cindex @code{save_stack_function} instruction pattern
7761 @cindex @code{save_stack_nonlocal} instruction pattern
7762 @cindex @code{restore_stack_block} instruction pattern
7763 @cindex @code{restore_stack_function} instruction pattern
7764 @cindex @code{restore_stack_nonlocal} instruction pattern
7765 @item @samp{save_stack_block}
7766 @itemx @samp{save_stack_function}
7767 @itemx @samp{save_stack_nonlocal}
7768 @itemx @samp{restore_stack_block}
7769 @itemx @samp{restore_stack_function}
7770 @itemx @samp{restore_stack_nonlocal}
7771 Most machines save and restore the stack pointer by copying it to or
7772 from an object of mode @code{Pmode}.  Do not define these patterns on
7773 such machines.
7775 Some machines require special handling for stack pointer saves and
7776 restores.  On those machines, define the patterns corresponding to the
7777 non-standard cases by using a @code{define_expand} (@pxref{Expander
7778 Definitions}) that produces the required insns.  The three types of
7779 saves and restores are:
7781 @enumerate
7782 @item
7783 @samp{save_stack_block} saves the stack pointer at the start of a block
7784 that allocates a variable-sized object, and @samp{restore_stack_block}
7785 restores the stack pointer when the block is exited.
7787 @item
7788 @samp{save_stack_function} and @samp{restore_stack_function} do a
7789 similar job for the outermost block of a function and are used when the
7790 function allocates variable-sized objects or calls @code{alloca}.  Only
7791 the epilogue uses the restored stack pointer, allowing a simpler save or
7792 restore sequence on some machines.
7794 @item
7795 @samp{save_stack_nonlocal} is used in functions that contain labels
7796 branched to by nested functions.  It saves the stack pointer in such a
7797 way that the inner function can use @samp{restore_stack_nonlocal} to
7798 restore the stack pointer.  The compiler generates code to restore the
7799 frame and argument pointer registers, but some machines require saving
7800 and restoring additional data such as register window information or
7801 stack backchains.  Place insns in these patterns to save and restore any
7802 such required data.
7803 @end enumerate
7805 When saving the stack pointer, operand 0 is the save area and operand 1
7806 is the stack pointer.  The mode used to allocate the save area defaults
7807 to @code{Pmode} but you can override that choice by defining the
7808 @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}).  You must
7809 specify an integral mode, or @code{VOIDmode} if no save area is needed
7810 for a particular type of save (either because no save is needed or
7811 because a machine-specific save area can be used).  Operand 0 is the
7812 stack pointer and operand 1 is the save area for restore operations.  If
7813 @samp{save_stack_block} is defined, operand 0 must not be
7814 @code{VOIDmode} since these saves can be arbitrarily nested.
7816 A save area is a @code{mem} that is at a constant offset from
7817 @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
7818 nonlocal gotos and a @code{reg} in the other two cases.
7820 @cindex @code{allocate_stack} instruction pattern
7821 @item @samp{allocate_stack}
7822 Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
7823 the stack pointer to create space for dynamically allocated data.
7825 Store the resultant pointer to this space into operand 0.  If you
7826 are allocating space from the main stack, do this by emitting a
7827 move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
7828 If you are allocating the space elsewhere, generate code to copy the
7829 location of the space to operand 0.  In the latter case, you must
7830 ensure this space gets freed when the corresponding space on the main
7831 stack is free.
7833 Do not define this pattern if all that must be done is the subtraction.
7834 Some machines require other operations such as stack probes or
7835 maintaining the back chain.  Define this pattern to emit those
7836 operations in addition to updating the stack pointer.
7838 @cindex @code{check_stack} instruction pattern
7839 @item @samp{check_stack}
7840 If stack checking (@pxref{Stack Checking}) cannot be done on your system by
7841 probing the stack, define this pattern to perform the needed check and signal
7842 an error if the stack has overflowed.  The single operand is the address in
7843 the stack farthest from the current stack pointer that you need to validate.
7844 Normally, on platforms where this pattern is needed, you would obtain the
7845 stack limit from a global or thread-specific variable or register.
7847 @cindex @code{probe_stack_address} instruction pattern
7848 @item @samp{probe_stack_address}
7849 If stack checking (@pxref{Stack Checking}) can be done on your system by
7850 probing the stack but without the need to actually access it, define this
7851 pattern and signal an error if the stack has overflowed.  The single operand
7852 is the memory address in the stack that needs to be probed.
7854 @cindex @code{probe_stack} instruction pattern
7855 @item @samp{probe_stack}
7856 If stack checking (@pxref{Stack Checking}) can be done on your system by
7857 probing the stack but doing it with a ``store zero'' instruction is not valid
7858 or optimal, define this pattern to do the probing differently and signal an
7859 error if the stack has overflowed.  The single operand is the memory reference
7860 in the stack that needs to be probed.
7862 @cindex @code{nonlocal_goto} instruction pattern
7863 @item @samp{nonlocal_goto}
7864 Emit code to generate a non-local goto, e.g., a jump from one function
7865 to a label in an outer function.  This pattern has four arguments,
7866 each representing a value to be used in the jump.  The first
7867 argument is to be loaded into the frame pointer, the second is
7868 the address to branch to (code to dispatch to the actual label),
7869 the third is the address of a location where the stack is saved,
7870 and the last is the address of the label, to be placed in the
7871 location for the incoming static chain.
7873 On most machines you need not define this pattern, since GCC will
7874 already generate the correct code, which is to load the frame pointer
7875 and static chain, restore the stack (using the
7876 @samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
7877 to the dispatcher.  You need only define this pattern if this code will
7878 not work on your machine.
7880 @cindex @code{nonlocal_goto_receiver} instruction pattern
7881 @item @samp{nonlocal_goto_receiver}
7882 This pattern, if defined, contains code needed at the target of a
7883 nonlocal goto after the code already generated by GCC@.  You will not
7884 normally need to define this pattern.  A typical reason why you might
7885 need this pattern is if some value, such as a pointer to a global table,
7886 must be restored when the frame pointer is restored.  Note that a nonlocal
7887 goto only occurs within a unit-of-translation, so a global table pointer
7888 that is shared by all functions of a given module need not be restored.
7889 There are no arguments.
7891 @cindex @code{exception_receiver} instruction pattern
7892 @item @samp{exception_receiver}
7893 This pattern, if defined, contains code needed at the site of an
7894 exception handler that isn't needed at the site of a nonlocal goto.  You
7895 will not normally need to define this pattern.  A typical reason why you
7896 might need this pattern is if some value, such as a pointer to a global
7897 table, must be restored after control flow is branched to the handler of
7898 an exception.  There are no arguments.
7900 @cindex @code{builtin_setjmp_setup} instruction pattern
7901 @item @samp{builtin_setjmp_setup}
7902 This pattern, if defined, contains additional code needed to initialize
7903 the @code{jmp_buf}.  You will not normally need to define this pattern.
7904 A typical reason why you might need this pattern is if some value, such
7905 as a pointer to a global table, must be restored.  Though it is
7906 preferred that the pointer value be recalculated if possible (given the
7907 address of a label for instance).  The single argument is a pointer to
7908 the @code{jmp_buf}.  Note that the buffer is five words long and that
7909 the first three are normally used by the generic mechanism.
7911 @cindex @code{builtin_setjmp_receiver} instruction pattern
7912 @item @samp{builtin_setjmp_receiver}
7913 This pattern, if defined, contains code needed at the site of a
7914 built-in setjmp that isn't needed at the site of a nonlocal goto.  You
7915 will not normally need to define this pattern.  A typical reason why you
7916 might need this pattern is if some value, such as a pointer to a global
7917 table, must be restored.  It takes one argument, which is the label
7918 to which builtin_longjmp transferred control; this pattern may be emitted
7919 at a small offset from that label.
7921 @cindex @code{builtin_longjmp} instruction pattern
7922 @item @samp{builtin_longjmp}
7923 This pattern, if defined, performs the entire action of the longjmp.
7924 You will not normally need to define this pattern unless you also define
7925 @code{builtin_setjmp_setup}.  The single argument is a pointer to the
7926 @code{jmp_buf}.
7928 @cindex @code{eh_return} instruction pattern
7929 @item @samp{eh_return}
7930 This pattern, if defined, affects the way @code{__builtin_eh_return},
7931 and thence the call frame exception handling library routines, are
7932 built.  It is intended to handle non-trivial actions needed along
7933 the abnormal return path.
7935 The address of the exception handler to which the function should return
7936 is passed as operand to this pattern.  It will normally need to copied by
7937 the pattern to some special register or memory location.
7938 If the pattern needs to determine the location of the target call
7939 frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
7940 if defined; it will have already been assigned.
7942 If this pattern is not defined, the default action will be to simply
7943 copy the return address to @code{EH_RETURN_HANDLER_RTX}.  Either
7944 that macro or this pattern needs to be defined if call frame exception
7945 handling is to be used.
7947 @cindex @code{prologue} instruction pattern
7948 @anchor{prologue instruction pattern}
7949 @item @samp{prologue}
7950 This pattern, if defined, emits RTL for entry to a function.  The function
7951 entry is responsible for setting up the stack frame, initializing the frame
7952 pointer register, saving callee saved registers, etc.
7954 Using a prologue pattern is generally preferred over defining
7955 @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
7957 The @code{prologue} pattern is particularly useful for targets which perform
7958 instruction scheduling.
7960 @cindex @code{window_save} instruction pattern
7961 @anchor{window_save instruction pattern}
7962 @item @samp{window_save}
7963 This pattern, if defined, emits RTL for a register window save.  It should
7964 be defined if the target machine has register windows but the window events
7965 are decoupled from calls to subroutines.  The canonical example is the SPARC
7966 architecture.
7968 @cindex @code{epilogue} instruction pattern
7969 @anchor{epilogue instruction pattern}
7970 @item @samp{epilogue}
7971 This pattern emits RTL for exit from a function.  The function
7972 exit is responsible for deallocating the stack frame, restoring callee saved
7973 registers and emitting the return instruction.
7975 Using an epilogue pattern is generally preferred over defining
7976 @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
7978 The @code{epilogue} pattern is particularly useful for targets which perform
7979 instruction scheduling or which have delay slots for their return instruction.
7981 @cindex @code{sibcall_epilogue} instruction pattern
7982 @item @samp{sibcall_epilogue}
7983 This pattern, if defined, emits RTL for exit from a function without the final
7984 branch back to the calling function.  This pattern will be emitted before any
7985 sibling call (aka tail call) sites.
7987 The @code{sibcall_epilogue} pattern must not clobber any arguments used for
7988 parameter passing or any stack slots for arguments passed to the current
7989 function.
7991 @cindex @code{trap} instruction pattern
7992 @item @samp{trap}
7993 This pattern, if defined, signals an error, typically by causing some
7994 kind of signal to be raised.
7996 @cindex @code{ctrap@var{MM}4} instruction pattern
7997 @item @samp{ctrap@var{MM}4}
7998 Conditional trap instruction.  Operand 0 is a piece of RTL which
7999 performs a comparison, and operands 1 and 2 are the arms of the
8000 comparison.  Operand 3 is the trap code, an integer.
8002 A typical @code{ctrap} pattern looks like
8004 @smallexample
8005 (define_insn "ctrapsi4"
8006   [(trap_if (match_operator 0 "trap_operator"
8007              [(match_operand 1 "register_operand")
8008               (match_operand 2 "immediate_operand")])
8009             (match_operand 3 "const_int_operand" "i"))]
8010   ""
8011   "@dots{}")
8012 @end smallexample
8014 @cindex @code{prefetch} instruction pattern
8015 @item @samp{prefetch}
8016 This pattern, if defined, emits code for a non-faulting data prefetch
8017 instruction.  Operand 0 is the address of the memory to prefetch.  Operand 1
8018 is a constant 1 if the prefetch is preparing for a write to the memory
8019 address, or a constant 0 otherwise.  Operand 2 is the expected degree of
8020 temporal locality of the data and is a value between 0 and 3, inclusive; 0
8021 means that the data has no temporal locality, so it need not be left in the
8022 cache after the access; 3 means that the data has a high degree of temporal
8023 locality and should be left in all levels of cache possible;  1 and 2 mean,
8024 respectively, a low or moderate degree of temporal locality.
8026 Targets that do not support write prefetches or locality hints can ignore
8027 the values of operands 1 and 2.
8029 @cindex @code{blockage} instruction pattern
8030 @item @samp{blockage}
8031 This pattern defines a pseudo insn that prevents the instruction
8032 scheduler and other passes from moving instructions and using register
8033 equivalences across the boundary defined by the blockage insn.
8034 This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM.
8036 @cindex @code{memory_blockage} instruction pattern
8037 @item @samp{memory_blockage}
8038 This pattern, if defined, represents a compiler memory barrier, and will be
8039 placed at points across which RTL passes may not propagate memory accesses.
8040 This instruction needs to read and write volatile BLKmode memory.  It does
8041 not need to generate any machine instruction.  If this pattern is not defined,
8042 the compiler falls back to emitting an instruction corresponding
8043 to @code{asm volatile ("" ::: "memory")}.
8045 @cindex @code{memory_barrier} instruction pattern
8046 @item @samp{memory_barrier}
8047 If the target memory model is not fully synchronous, then this pattern
8048 should be defined to an instruction that orders both loads and stores
8049 before the instruction with respect to loads and stores after the instruction.
8050 This pattern has no operands.
8052 @cindex @code{speculation_barrier} instruction pattern
8053 @item @samp{speculation_barrier}
8054 If the target can support speculative execution, then this pattern should
8055 be defined to an instruction that will block subsequent execution until
8056 any prior speculation conditions has been resolved.  The pattern must also
8057 ensure that the compiler cannot move memory operations past the barrier,
8058 so it needs to be an UNSPEC_VOLATILE pattern.  The pattern has no
8059 operands.
8061 If this pattern is not defined then the default expansion of
8062 @code{__builtin_speculation_safe_value} will emit a warning.  You can
8063 suppress this warning by defining this pattern with a final condition
8064 of @code{0} (zero), which tells the compiler that a speculation
8065 barrier is not needed for this target.
8067 @cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
8068 @item @samp{sync_compare_and_swap@var{mode}}
8069 This pattern, if defined, emits code for an atomic compare-and-swap
8070 operation.  Operand 1 is the memory on which the atomic operation is
8071 performed.  Operand 2 is the ``old'' value to be compared against the
8072 current contents of the memory location.  Operand 3 is the ``new'' value
8073 to store in the memory if the compare succeeds.  Operand 0 is the result
8074 of the operation; it should contain the contents of the memory
8075 before the operation.  If the compare succeeds, this should obviously be
8076 a copy of operand 2.
8078 This pattern must show that both operand 0 and operand 1 are modified.
8080 This pattern must issue any memory barrier instructions such that all
8081 memory operations before the atomic operation occur before the atomic
8082 operation and all memory operations after the atomic operation occur
8083 after the atomic operation.
8085 For targets where the success or failure of the compare-and-swap
8086 operation is available via the status flags, it is possible to
8087 avoid a separate compare operation and issue the subsequent
8088 branch or store-flag operation immediately after the compare-and-swap.
8089 To this end, GCC will look for a @code{MODE_CC} set in the
8090 output of @code{sync_compare_and_swap@var{mode}}; if the machine
8091 description includes such a set, the target should also define special
8092 @code{cbranchcc4} and/or @code{cstorecc4} instructions.  GCC will then
8093 be able to take the destination of the @code{MODE_CC} set and pass it
8094 to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
8095 operand of the comparison (the second will be @code{(const_int 0)}).
8097 For targets where the operating system may provide support for this
8098 operation via library calls, the @code{sync_compare_and_swap_optab}
8099 may be initialized to a function with the same interface as the
8100 @code{__sync_val_compare_and_swap_@var{n}} built-in.  If the entire
8101 set of @var{__sync} builtins are supported via library calls, the
8102 target can initialize all of the optabs at once with
8103 @code{init_sync_libfuncs}.
8104 For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
8105 assumed that these library calls do @emph{not} use any kind of
8106 interruptable locking.
8108 @cindex @code{sync_add@var{mode}} instruction pattern
8109 @cindex @code{sync_sub@var{mode}} instruction pattern
8110 @cindex @code{sync_ior@var{mode}} instruction pattern
8111 @cindex @code{sync_and@var{mode}} instruction pattern
8112 @cindex @code{sync_xor@var{mode}} instruction pattern
8113 @cindex @code{sync_nand@var{mode}} instruction pattern
8114 @item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
8115 @itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
8116 @itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
8117 These patterns emit code for an atomic operation on memory.
8118 Operand 0 is the memory on which the atomic operation is performed.
8119 Operand 1 is the second operand to the binary operator.
8121 This pattern must issue any memory barrier instructions such that all
8122 memory operations before the atomic operation occur before the atomic
8123 operation and all memory operations after the atomic operation occur
8124 after the atomic operation.
8126 If these patterns are not defined, the operation will be constructed
8127 from a compare-and-swap operation, if defined.
8129 @cindex @code{sync_old_add@var{mode}} instruction pattern
8130 @cindex @code{sync_old_sub@var{mode}} instruction pattern
8131 @cindex @code{sync_old_ior@var{mode}} instruction pattern
8132 @cindex @code{sync_old_and@var{mode}} instruction pattern
8133 @cindex @code{sync_old_xor@var{mode}} instruction pattern
8134 @cindex @code{sync_old_nand@var{mode}} instruction pattern
8135 @item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
8136 @itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
8137 @itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
8138 These patterns emit code for an atomic operation on memory,
8139 and return the value that the memory contained before the operation.
8140 Operand 0 is the result value, operand 1 is the memory on which the
8141 atomic operation is performed, and operand 2 is the second operand
8142 to the binary operator.
8144 This pattern must issue any memory barrier instructions such that all
8145 memory operations before the atomic operation occur before the atomic
8146 operation and all memory operations after the atomic operation occur
8147 after the atomic operation.
8149 If these patterns are not defined, the operation will be constructed
8150 from a compare-and-swap operation, if defined.
8152 @cindex @code{sync_new_add@var{mode}} instruction pattern
8153 @cindex @code{sync_new_sub@var{mode}} instruction pattern
8154 @cindex @code{sync_new_ior@var{mode}} instruction pattern
8155 @cindex @code{sync_new_and@var{mode}} instruction pattern
8156 @cindex @code{sync_new_xor@var{mode}} instruction pattern
8157 @cindex @code{sync_new_nand@var{mode}} instruction pattern
8158 @item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
8159 @itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
8160 @itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
8161 These patterns are like their @code{sync_old_@var{op}} counterparts,
8162 except that they return the value that exists in the memory location
8163 after the operation, rather than before the operation.
8165 @cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
8166 @item @samp{sync_lock_test_and_set@var{mode}}
8167 This pattern takes two forms, based on the capabilities of the target.
8168 In either case, operand 0 is the result of the operand, operand 1 is
8169 the memory on which the atomic operation is performed, and operand 2
8170 is the value to set in the lock.
8172 In the ideal case, this operation is an atomic exchange operation, in
8173 which the previous value in memory operand is copied into the result
8174 operand, and the value operand is stored in the memory operand.
8176 For less capable targets, any value operand that is not the constant 1
8177 should be rejected with @code{FAIL}.  In this case the target may use
8178 an atomic test-and-set bit operation.  The result operand should contain
8179 1 if the bit was previously set and 0 if the bit was previously clear.
8180 The true contents of the memory operand are implementation defined.
8182 This pattern must issue any memory barrier instructions such that the
8183 pattern as a whole acts as an acquire barrier, that is all memory
8184 operations after the pattern do not occur until the lock is acquired.
8186 If this pattern is not defined, the operation will be constructed from
8187 a compare-and-swap operation, if defined.
8189 @cindex @code{sync_lock_release@var{mode}} instruction pattern
8190 @item @samp{sync_lock_release@var{mode}}
8191 This pattern, if defined, releases a lock set by
8192 @code{sync_lock_test_and_set@var{mode}}.  Operand 0 is the memory
8193 that contains the lock; operand 1 is the value to store in the lock.
8195 If the target doesn't implement full semantics for
8196 @code{sync_lock_test_and_set@var{mode}}, any value operand which is not
8197 the constant 0 should be rejected with @code{FAIL}, and the true contents
8198 of the memory operand are implementation defined.
8200 This pattern must issue any memory barrier instructions such that the
8201 pattern as a whole acts as a release barrier, that is the lock is
8202 released only after all previous memory operations have completed.
8204 If this pattern is not defined, then a @code{memory_barrier} pattern
8205 will be emitted, followed by a store of the value to the memory operand.
8207 @cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
8208 @item @samp{atomic_compare_and_swap@var{mode}} 
8209 This pattern, if defined, emits code for an atomic compare-and-swap
8210 operation with memory model semantics.  Operand 2 is the memory on which
8211 the atomic operation is performed.  Operand 0 is an output operand which
8212 is set to true or false based on whether the operation succeeded.  Operand
8213 1 is an output operand which is set to the contents of the memory before
8214 the operation was attempted.  Operand 3 is the value that is expected to
8215 be in memory.  Operand 4 is the value to put in memory if the expected
8216 value is found there.  Operand 5 is set to 1 if this compare and swap is to
8217 be treated as a weak operation.  Operand 6 is the memory model to be used
8218 if the operation is a success.  Operand 7 is the memory model to be used
8219 if the operation fails.
8221 If memory referred to in operand 2 contains the value in operand 3, then
8222 operand 4 is stored in memory pointed to by operand 2 and fencing based on
8223 the memory model in operand 6 is issued.  
8225 If memory referred to in operand 2 does not contain the value in operand 3,
8226 then fencing based on the memory model in operand 7 is issued.
8228 If a target does not support weak compare-and-swap operations, or the port
8229 elects not to implement weak operations, the argument in operand 5 can be
8230 ignored.  Note a strong implementation must be provided.
8232 If this pattern is not provided, the @code{__atomic_compare_exchange}
8233 built-in functions will utilize the legacy @code{sync_compare_and_swap}
8234 pattern with an @code{__ATOMIC_SEQ_CST} memory model.
8236 @cindex @code{atomic_load@var{mode}} instruction pattern
8237 @item @samp{atomic_load@var{mode}}
8238 This pattern implements an atomic load operation with memory model
8239 semantics.  Operand 1 is the memory address being loaded from.  Operand 0
8240 is the result of the load.  Operand 2 is the memory model to be used for
8241 the load operation.
8243 If not present, the @code{__atomic_load} built-in function will either
8244 resort to a normal load with memory barriers, or a compare-and-swap
8245 operation if a normal load would not be atomic.
8247 @cindex @code{atomic_store@var{mode}} instruction pattern
8248 @item @samp{atomic_store@var{mode}}
8249 This pattern implements an atomic store operation with memory model
8250 semantics.  Operand 0 is the memory address being stored to.  Operand 1
8251 is the value to be written.  Operand 2 is the memory model to be used for
8252 the operation.
8254 If not present, the @code{__atomic_store} built-in function will attempt to
8255 perform a normal store and surround it with any required memory fences.  If
8256 the store would not be atomic, then an @code{__atomic_exchange} is
8257 attempted with the result being ignored.
8259 @cindex @code{atomic_exchange@var{mode}} instruction pattern
8260 @item @samp{atomic_exchange@var{mode}}
8261 This pattern implements an atomic exchange operation with memory model
8262 semantics.  Operand 1 is the memory location the operation is performed on.
8263 Operand 0 is an output operand which is set to the original value contained
8264 in the memory pointed to by operand 1.  Operand 2 is the value to be
8265 stored.  Operand 3 is the memory model to be used.
8267 If this pattern is not present, the built-in function
8268 @code{__atomic_exchange} will attempt to preform the operation with a
8269 compare and swap loop.
8271 @cindex @code{atomic_add@var{mode}} instruction pattern
8272 @cindex @code{atomic_sub@var{mode}} instruction pattern
8273 @cindex @code{atomic_or@var{mode}} instruction pattern
8274 @cindex @code{atomic_and@var{mode}} instruction pattern
8275 @cindex @code{atomic_xor@var{mode}} instruction pattern
8276 @cindex @code{atomic_nand@var{mode}} instruction pattern
8277 @item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
8278 @itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
8279 @itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
8280 These patterns emit code for an atomic operation on memory with memory
8281 model semantics. Operand 0 is the memory on which the atomic operation is
8282 performed.  Operand 1 is the second operand to the binary operator.
8283 Operand 2 is the memory model to be used by the operation.
8285 If these patterns are not defined, attempts will be made to use legacy
8286 @code{sync} patterns, or equivalent patterns which return a result.  If
8287 none of these are available a compare-and-swap loop will be used.
8289 @cindex @code{atomic_fetch_add@var{mode}} instruction pattern
8290 @cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
8291 @cindex @code{atomic_fetch_or@var{mode}} instruction pattern
8292 @cindex @code{atomic_fetch_and@var{mode}} instruction pattern
8293 @cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
8294 @cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
8295 @item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
8296 @itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
8297 @itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
8298 These patterns emit code for an atomic operation on memory with memory
8299 model semantics, and return the original value. Operand 0 is an output 
8300 operand which contains the value of the memory location before the 
8301 operation was performed.  Operand 1 is the memory on which the atomic 
8302 operation is performed.  Operand 2 is the second operand to the binary
8303 operator.  Operand 3 is the memory model to be used by the operation.
8305 If these patterns are not defined, attempts will be made to use legacy
8306 @code{sync} patterns.  If none of these are available a compare-and-swap
8307 loop will be used.
8309 @cindex @code{atomic_add_fetch@var{mode}} instruction pattern
8310 @cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
8311 @cindex @code{atomic_or_fetch@var{mode}} instruction pattern
8312 @cindex @code{atomic_and_fetch@var{mode}} instruction pattern
8313 @cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
8314 @cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
8315 @item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
8316 @itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
8317 @itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
8318 These patterns emit code for an atomic operation on memory with memory
8319 model semantics and return the result after the operation is performed.
8320 Operand 0 is an output operand which contains the value after the
8321 operation.  Operand 1 is the memory on which the atomic operation is
8322 performed.  Operand 2 is the second operand to the binary operator.
8323 Operand 3 is the memory model to be used by the operation.
8325 If these patterns are not defined, attempts will be made to use legacy
8326 @code{sync} patterns, or equivalent patterns which return the result before
8327 the operation followed by the arithmetic operation required to produce the
8328 result.  If none of these are available a compare-and-swap loop will be
8329 used.
8331 @cindex @code{atomic_test_and_set} instruction pattern
8332 @item @samp{atomic_test_and_set}
8333 This pattern emits code for @code{__builtin_atomic_test_and_set}.
8334 Operand 0 is an output operand which is set to true if the previous
8335 previous contents of the byte was "set", and false otherwise.  Operand 1
8336 is the @code{QImode} memory to be modified.  Operand 2 is the memory
8337 model to be used.
8339 The specific value that defines "set" is implementation defined, and
8340 is normally based on what is performed by the native atomic test and set
8341 instruction.
8343 @cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern
8344 @cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern
8345 @cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern
8346 @item @samp{atomic_bit_test_and_set@var{mode}}
8347 @itemx @samp{atomic_bit_test_and_complement@var{mode}}
8348 @itemx @samp{atomic_bit_test_and_reset@var{mode}}
8349 These patterns emit code for an atomic bitwise operation on memory with memory
8350 model semantics, and return the original value of the specified bit.
8351 Operand 0 is an output operand which contains the value of the specified bit
8352 from the memory location before the operation was performed.  Operand 1 is the
8353 memory on which the atomic operation is performed.  Operand 2 is the bit within
8354 the operand, starting with least significant bit.  Operand 3 is the memory model
8355 to be used by the operation.  Operand 4 is a flag - it is @code{const1_rtx}
8356 if operand 0 should contain the original value of the specified bit in the
8357 least significant bit of the operand, and @code{const0_rtx} if the bit should
8358 be in its original position in the operand.
8359 @code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after
8360 remembering its original value, @code{atomic_bit_test_and_complement@var{mode}}
8361 inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears
8362 the specified bit.
8364 If these patterns are not defined, attempts will be made to use
8365 @code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or
8366 @code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync}
8367 counterparts.  If none of these are available a compare-and-swap
8368 loop will be used.
8370 @cindex @code{atomic_add_fetch_cmp_0@var{mode}} instruction pattern
8371 @cindex @code{atomic_sub_fetch_cmp_0@var{mode}} instruction pattern
8372 @cindex @code{atomic_and_fetch_cmp_0@var{mode}} instruction pattern
8373 @cindex @code{atomic_or_fetch_cmp_0@var{mode}} instruction pattern
8374 @cindex @code{atomic_xor_fetch_cmp_0@var{mode}} instruction pattern
8375 @item @samp{atomic_add_fetch_cmp_0@var{mode}}
8376 @itemx @samp{atomic_sub_fetch_cmp_0@var{mode}}
8377 @itemx @samp{atomic_and_fetch_cmp_0@var{mode}}
8378 @itemx @samp{atomic_or_fetch_cmp_0@var{mode}}
8379 @itemx @samp{atomic_xor_fetch_cmp_0@var{mode}}
8380 These patterns emit code for an atomic operation on memory with memory
8381 model semantics if the fetch result is used only in a comparison against
8382 zero.
8383 Operand 0 is an output operand which contains a boolean result of comparison
8384 of the value after the operation against zero.  Operand 1 is the memory on
8385 which the atomic operation is performed.  Operand 2 is the second operand
8386 to the binary operator.  Operand 3 is the memory model to be used by the
8387 operation.  Operand 4 is an integer holding the comparison code, one of
8388 @code{EQ}, @code{NE}, @code{LT}, @code{GT}, @code{LE} or @code{GE}.
8390 If these patterns are not defined, attempts will be made to use separate
8391 atomic operation and fetch pattern followed by comparison of the result
8392 against zero.
8394 @cindex @code{mem_thread_fence} instruction pattern
8395 @item @samp{mem_thread_fence}
8396 This pattern emits code required to implement a thread fence with
8397 memory model semantics.  Operand 0 is the memory model to be used.
8399 For the @code{__ATOMIC_RELAXED} model no instructions need to be issued
8400 and this expansion is not invoked.
8402 The compiler always emits a compiler memory barrier regardless of what
8403 expanding this pattern produced.
8405 If this pattern is not defined, the compiler falls back to expanding the
8406 @code{memory_barrier} pattern, then to emitting @code{__sync_synchronize}
8407 library call, and finally to just placing a compiler memory barrier.
8409 @cindex @code{get_thread_pointer@var{mode}} instruction pattern
8410 @cindex @code{set_thread_pointer@var{mode}} instruction pattern
8411 @item @samp{get_thread_pointer@var{mode}}
8412 @itemx @samp{set_thread_pointer@var{mode}}
8413 These patterns emit code that reads/sets the TLS thread pointer. Currently,
8414 these are only needed if the target needs to support the
8415 @code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer}
8416 builtins.
8418 The get/set patterns have a single output/input operand respectively,
8419 with @var{mode} intended to be @code{Pmode}.
8421 @cindex @code{stack_protect_combined_set} instruction pattern
8422 @item @samp{stack_protect_combined_set}
8423 This pattern, if defined, moves a @code{ptr_mode} value from an address
8424 whose declaration RTX is given in operand 1 to the memory in operand 0
8425 without leaving the value in a register afterward.  If several
8426 instructions are needed by the target to perform the operation (eg. to
8427 load the address from a GOT entry then load the @code{ptr_mode} value
8428 and finally store it), it is the backend's responsibility to ensure no
8429 intermediate result gets spilled.  This is to avoid leaking the value
8430 some place that an attacker might use to rewrite the stack guard slot
8431 after having clobbered it.
8433 If this pattern is not defined, then the address declaration is
8434 expanded first in the standard way and a @code{stack_protect_set}
8435 pattern is then generated to move the value from that address to the
8436 address in operand 0.
8438 @cindex @code{stack_protect_set} instruction pattern
8439 @item @samp{stack_protect_set}
8440 This pattern, if defined, moves a @code{ptr_mode} value from the valid
8441 memory location in operand 1 to the memory in operand 0 without leaving
8442 the value in a register afterward.  This is to avoid leaking the value
8443 some place that an attacker might use to rewrite the stack guard slot
8444 after having clobbered it.
8446 Note: on targets where the addressing modes do not allow to load
8447 directly from stack guard address, the address is expanded in a standard
8448 way first which could cause some spills.
8450 If this pattern is not defined, then a plain move pattern is generated.
8452 @cindex @code{stack_protect_combined_test} instruction pattern
8453 @item @samp{stack_protect_combined_test}
8454 This pattern, if defined, compares a @code{ptr_mode} value from an
8455 address whose declaration RTX is given in operand 1 with the memory in
8456 operand 0 without leaving the value in a register afterward and
8457 branches to operand 2 if the values were equal.  If several
8458 instructions are needed by the target to perform the operation (eg. to
8459 load the address from a GOT entry then load the @code{ptr_mode} value
8460 and finally store it), it is the backend's responsibility to ensure no
8461 intermediate result gets spilled.  This is to avoid leaking the value
8462 some place that an attacker might use to rewrite the stack guard slot
8463 after having clobbered it.
8465 If this pattern is not defined, then the address declaration is
8466 expanded first in the standard way and a @code{stack_protect_test}
8467 pattern is then generated to compare the value from that address to the
8468 value at the memory in operand 0.
8470 @cindex @code{stack_protect_test} instruction pattern
8471 @item @samp{stack_protect_test}
8472 This pattern, if defined, compares a @code{ptr_mode} value from the
8473 valid memory location in operand 1 with the memory in operand 0 without
8474 leaving the value in a register afterward and branches to operand 2 if
8475 the values were equal.
8477 If this pattern is not defined, then a plain compare pattern and
8478 conditional branch pattern is used.
8480 @cindex @code{clear_cache} instruction pattern
8481 @item @samp{clear_cache}
8482 This pattern, if defined, flushes the instruction cache for a region of
8483 memory.  The region is bounded to by the Pmode pointers in operand 0
8484 inclusive and operand 1 exclusive.
8486 If this pattern is not defined, a call to the library function
8487 @code{__clear_cache} is used.
8489 @cindex @code{spaceship@var{m}3} instruction pattern
8490 @item @samp{spaceship@var{m}3}
8491 Initialize output operand 0 with mode of integer type to -1, 0, 1 or 2
8492 if operand 1 with mode @var{m} compares less than operand 2, equal to
8493 operand 2, greater than operand 2 or is unordered with operand 2.
8494 @var{m} should be a scalar floating point mode.
8496 This pattern is not allowed to @code{FAIL}.
8498 @end table
8500 @end ifset
8501 @c Each of the following nodes are wrapped in separate
8502 @c "@ifset INTERNALS" to work around memory limits for the default
8503 @c configuration in older tetex distributions.  Known to not work:
8504 @c tetex-1.0.7, known to work: tetex-2.0.2.
8505 @ifset INTERNALS
8506 @node Pattern Ordering
8507 @section When the Order of Patterns Matters
8508 @cindex Pattern Ordering
8509 @cindex Ordering of Patterns
8511 Sometimes an insn can match more than one instruction pattern.  Then the
8512 pattern that appears first in the machine description is the one used.
8513 Therefore, more specific patterns (patterns that will match fewer things)
8514 and faster instructions (those that will produce better code when they
8515 do match) should usually go first in the description.
8517 In some cases the effect of ordering the patterns can be used to hide
8518 a pattern when it is not valid.  For example, the 68000 has an
8519 instruction for converting a fullword to floating point and another
8520 for converting a byte to floating point.  An instruction converting
8521 an integer to floating point could match either one.  We put the
8522 pattern to convert the fullword first to make sure that one will
8523 be used rather than the other.  (Otherwise a large integer might
8524 be generated as a single-byte immediate quantity, which would not work.)
8525 Instead of using this pattern ordering it would be possible to make the
8526 pattern for convert-a-byte smart enough to deal properly with any
8527 constant value.
8529 @end ifset
8530 @ifset INTERNALS
8531 @node Dependent Patterns
8532 @section Interdependence of Patterns
8533 @cindex Dependent Patterns
8534 @cindex Interdependence of Patterns
8536 In some cases machines support instructions identical except for the
8537 machine mode of one or more operands.  For example, there may be
8538 ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
8539 patterns are
8541 @smallexample
8542 (set (match_operand:SI 0 @dots{})
8543      (extend:SI (match_operand:HI 1 @dots{})))
8545 (set (match_operand:SI 0 @dots{})
8546      (extend:SI (match_operand:QI 1 @dots{})))
8547 @end smallexample
8549 @noindent
8550 Constant integers do not specify a machine mode, so an instruction to
8551 extend a constant value could match either pattern.  The pattern it
8552 actually will match is the one that appears first in the file.  For correct
8553 results, this must be the one for the widest possible mode (@code{HImode},
8554 here).  If the pattern matches the @code{QImode} instruction, the results
8555 will be incorrect if the constant value does not actually fit that mode.
8557 Such instructions to extend constants are rarely generated because they are
8558 optimized away, but they do occasionally happen in nonoptimized
8559 compilations.
8561 If a constraint in a pattern allows a constant, the reload pass may
8562 replace a register with a constant permitted by the constraint in some
8563 cases.  Similarly for memory references.  Because of this substitution,
8564 you should not provide separate patterns for increment and decrement
8565 instructions.  Instead, they should be generated from the same pattern
8566 that supports register-register add insns by examining the operands and
8567 generating the appropriate machine instruction.
8569 @end ifset
8570 @ifset INTERNALS
8571 @node Jump Patterns
8572 @section Defining Jump Instruction Patterns
8573 @cindex jump instruction patterns
8574 @cindex defining jump instruction patterns
8576 GCC does not assume anything about how the machine realizes jumps.
8577 The machine description should define a single pattern, usually
8578 a @code{define_expand}, which expands to all the required insns.
8580 Usually, this would be a comparison insn to set the condition code
8581 and a separate branch insn testing the condition code and branching
8582 or not according to its value.  For many machines, however,
8583 separating compares and branches is limiting, which is why the
8584 more flexible approach with one @code{define_expand} is used in GCC.
8585 The machine description becomes clearer for architectures that
8586 have compare-and-branch instructions but no condition code.  It also
8587 works better when different sets of comparison operators are supported
8588 by different kinds of conditional branches (e.g.@: integer vs.@:
8589 floating-point), or by conditional branches with respect to conditional stores.
8591 Two separate insns are always used on most machines that use a separate
8592 condition code register (@pxref{Condition Code}).
8594 Even in this case having a single entry point for conditional branches
8595 is advantageous, because it handles equally well the case where a single
8596 comparison instruction records the results of both signed and unsigned
8597 comparison of the given operands (with the branch insns coming in distinct
8598 signed and unsigned flavors) as in the x86 or SPARC, and the case where
8599 there are distinct signed and unsigned compare instructions and only
8600 one set of conditional branch instructions as in the PowerPC.
8602 @end ifset
8603 @ifset INTERNALS
8604 @node Looping Patterns
8605 @section Defining Looping Instruction Patterns
8606 @cindex looping instruction patterns
8607 @cindex defining looping instruction patterns
8609 Some machines have special jump instructions that can be utilized to
8610 make loops more efficient.  A common example is the 68000 @samp{dbra}
8611 instruction which performs a decrement of a register and a branch if the
8612 result was greater than zero.  Other machines, in particular digital
8613 signal processors (DSPs), have special block repeat instructions to
8614 provide low-overhead loop support.  For example, the TI TMS320C3x/C4x
8615 DSPs have a block repeat instruction that loads special registers to
8616 mark the top and end of a loop and to count the number of loop
8617 iterations.  This avoids the need for fetching and executing a
8618 @samp{dbra}-like instruction and avoids pipeline stalls associated with
8619 the jump.
8621 GCC has two special named patterns to support low overhead looping.
8622 They are @samp{doloop_begin} and @samp{doloop_end}.  These are emitted
8623 by the loop optimizer for certain well-behaved loops with a finite
8624 number of loop iterations using information collected during strength
8625 reduction.
8627 The @samp{doloop_end} pattern describes the actual looping instruction
8628 (or the implicit looping operation) and the @samp{doloop_begin} pattern
8629 is an optional companion pattern that can be used for initialization
8630 needed for some low-overhead looping instructions.
8632 Note that some machines require the actual looping instruction to be
8633 emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs).  Emitting
8634 the true RTL for a looping instruction at the top of the loop can cause
8635 problems with flow analysis.  So instead, a dummy @code{doloop} insn is
8636 emitted at the end of the loop.  The machine dependent reorg pass checks
8637 for the presence of this @code{doloop} insn and then searches back to
8638 the top of the loop, where it inserts the true looping insn (provided
8639 there are no instructions in the loop which would cause problems).  Any
8640 additional labels can be emitted at this point.  In addition, if the
8641 desired special iteration counter register was not allocated, this
8642 machine dependent reorg pass could emit a traditional compare and jump
8643 instruction pair.
8645 For the @samp{doloop_end} pattern, the loop optimizer allocates an
8646 additional pseudo register as an iteration counter.  This pseudo
8647 register cannot be used within the loop (i.e., general induction
8648 variables cannot be derived from it), however, in many cases the loop
8649 induction variable may become redundant and removed by the flow pass.
8651 The @samp{doloop_end} pattern must have a specific structure to be
8652 handled correctly by GCC.  The example below is taken (slightly
8653 simplified) from the PDP-11 target:
8655 @smallexample
8656 @group
8657 (define_expand "doloop_end"
8658   [(parallel [(set (pc)
8659                    (if_then_else
8660                     (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8661                         (const_int 1))
8662                     (label_ref (match_operand 1 "" ""))
8663                     (pc)))
8664               (set (match_dup 0)
8665                    (plus:HI (match_dup 0)
8666                          (const_int -1)))])]
8667   ""
8668   "@{
8669     if (GET_MODE (operands[0]) != HImode)
8670       FAIL;
8671   @}")
8673 (define_insn "doloop_end_insn"
8674   [(set (pc)
8675         (if_then_else
8676          (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8677              (const_int 1))
8678          (label_ref (match_operand 1 "" ""))
8679          (pc)))
8680    (set (match_dup 0)
8681         (plus:HI (match_dup 0)
8682               (const_int -1)))]
8683   ""
8684   
8685   @{
8686     if (which_alternative == 0)
8687       return "sob %0,%l1";
8689     /* emulate sob */
8690     output_asm_insn ("dec %0", operands);
8691     return "bne %l1";
8692   @})
8693 @end group
8694 @end smallexample
8696 The first part of the pattern describes the branch condition.  GCC
8697 supports three cases for the way the target machine handles the loop
8698 counter:
8699 @itemize @bullet
8700 @item Loop terminates when the loop register decrements to zero.  This
8701 is represented by a @code{ne} comparison of the register (its old value)
8702 with constant 1 (as in the example above).
8703 @item Loop terminates when the loop register decrements to @minus{}1.
8704 This is represented by a @code{ne} comparison of the register with
8705 constant zero.
8706 @item Loop terminates when the loop register decrements to a negative
8707 value.  This is represented by a @code{ge} comparison of the register
8708 with constant zero.  For this case, GCC will attach a @code{REG_NONNEG}
8709 note to the @code{doloop_end} insn if it can determine that the register
8710 will be non-negative.
8711 @end itemize
8713 Since the @code{doloop_end} insn is a jump insn that also has an output,
8714 the reload pass does not handle the output operand.  Therefore, the
8715 constraint must allow for that operand to be in memory rather than a
8716 register.  In the example shown above, that is handled (in the
8717 @code{doloop_end_insn} pattern) by using a loop instruction sequence
8718 that can handle memory operands when the memory alternative appears.
8720 GCC does not check the mode of the loop register operand when generating
8721 the @code{doloop_end} pattern.  If the pattern is only valid for some
8722 modes but not others, the pattern should be a @code{define_expand}
8723 pattern that checks the operand mode in the preparation code, and issues
8724 @code{FAIL} if an unsupported mode is found.  The example above does
8725 this, since the machine instruction to be used only exists for
8726 @code{HImode}.
8728 If the @code{doloop_end} pattern is a @code{define_expand}, there must
8729 also be a @code{define_insn} or @code{define_insn_and_split} matching
8730 the generated pattern.  Otherwise, the compiler will fail during loop
8731 optimization.
8733 @end ifset
8734 @ifset INTERNALS
8735 @node Insn Canonicalizations
8736 @section Canonicalization of Instructions
8737 @cindex canonicalization of instructions
8738 @cindex insn canonicalization
8740 There are often cases where multiple RTL expressions could represent an
8741 operation performed by a single machine instruction.  This situation is
8742 most commonly encountered with logical, branch, and multiply-accumulate
8743 instructions.  In such cases, the compiler attempts to convert these
8744 multiple RTL expressions into a single canonical form to reduce the
8745 number of insn patterns required.
8747 In addition to algebraic simplifications, following canonicalizations
8748 are performed:
8750 @itemize @bullet
8751 @item
8752 For commutative and comparison operators, a constant is always made the
8753 second operand.  If a machine only supports a constant as the second
8754 operand, only patterns that match a constant in the second operand need
8755 be supplied.
8757 @cindex @code{vec_merge}, canonicalization of
8758 @item
8759 For the @code{vec_merge} with constant mask(the third operand), the first
8760 and the second operand can be exchanged by inverting the mask. In such cases,
8761 a constant is always made the second operand, otherwise the least significant
8762 bit of the mask is always set(select the first operand first).
8764 @item
8765 For associative operators, a sequence of operators will always chain
8766 to the left; for instance, only the left operand of an integer @code{plus}
8767 can itself be a @code{plus}.  @code{and}, @code{ior}, @code{xor},
8768 @code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
8769 @code{umax} are associative when applied to integers, and sometimes to
8770 floating-point.
8772 @cindex @code{neg}, canonicalization of
8773 @cindex @code{not}, canonicalization of
8774 @cindex @code{mult}, canonicalization of
8775 @cindex @code{plus}, canonicalization of
8776 @cindex @code{minus}, canonicalization of
8777 @item
8778 For these operators, if only one operand is a @code{neg}, @code{not},
8779 @code{mult}, @code{plus}, or @code{minus} expression, it will be the
8780 first operand.
8782 @item
8783 In combinations of @code{neg}, @code{mult}, @code{plus}, and
8784 @code{minus}, the @code{neg} operations (if any) will be moved inside
8785 the operations as far as possible.  For instance,
8786 @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
8787 @code{(plus (mult (neg B) C) A)} is canonicalized as
8788 @code{(minus A (mult B C))}.
8790 @cindex @code{compare}, canonicalization of
8791 @item
8792 For the @code{compare} operator, a constant is always the second operand
8793 if the first argument is a condition code register.
8795 @item
8796 For instructions that inherently set a condition code register, the
8797 @code{compare} operator is always written as the first RTL expression of
8798 the @code{parallel} instruction pattern.  For example,
8800 @smallexample
8801 (define_insn ""
8802   [(set (reg:CCZ FLAGS_REG)
8803         (compare:CCZ
8804           (plus:SI
8805             (match_operand:SI 1 "register_operand" "%r")
8806             (match_operand:SI 2 "register_operand" "r"))
8807           (const_int 0)))
8808    (set (match_operand:SI 0 "register_operand" "=r")
8809         (plus:SI (match_dup 1) (match_dup 2)))]
8810   ""
8811   "addl %0, %1, %2")
8812 @end smallexample
8814 @item
8815 An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
8816 @code{minus} is made the first operand under the same conditions as
8817 above.
8819 @item
8820 @code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
8821 @code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
8822 of @code{ltu}.
8824 @item
8825 @code{(minus @var{x} (const_int @var{n}))} is converted to
8826 @code{(plus @var{x} (const_int @var{-n}))}.
8828 @item
8829 Within address computations (i.e., inside @code{mem}), a left shift is
8830 converted into the appropriate multiplication by a power of two.
8832 @cindex @code{ior}, canonicalization of
8833 @cindex @code{and}, canonicalization of
8834 @cindex De Morgan's law
8835 @item
8836 De Morgan's Law is used to move bitwise negation inside a bitwise
8837 logical-and or logical-or operation.  If this results in only one
8838 operand being a @code{not} expression, it will be the first one.
8840 A machine that has an instruction that performs a bitwise logical-and of one
8841 operand with the bitwise negation of the other should specify the pattern
8842 for that instruction as
8844 @smallexample
8845 (define_insn ""
8846   [(set (match_operand:@var{m} 0 @dots{})
8847         (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8848                      (match_operand:@var{m} 2 @dots{})))]
8849   "@dots{}"
8850   "@dots{}")
8851 @end smallexample
8853 @noindent
8854 Similarly, a pattern for a ``NAND'' instruction should be written
8856 @smallexample
8857 (define_insn ""
8858   [(set (match_operand:@var{m} 0 @dots{})
8859         (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8860                      (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
8861   "@dots{}"
8862   "@dots{}")
8863 @end smallexample
8865 In both cases, it is not necessary to include patterns for the many
8866 logically equivalent RTL expressions.
8868 @cindex @code{xor}, canonicalization of
8869 @item
8870 The only possible RTL expressions involving both bitwise exclusive-or
8871 and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
8872 and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
8874 @item
8875 The sum of three items, one of which is a constant, will only appear in
8876 the form
8878 @smallexample
8879 (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
8880 @end smallexample
8882 @cindex @code{zero_extract}, canonicalization of
8883 @cindex @code{sign_extract}, canonicalization of
8884 @item
8885 Equality comparisons of a group of bits (usually a single bit) with zero
8886 will be written using @code{zero_extract} rather than the equivalent
8887 @code{and} or @code{sign_extract} operations.
8889 @cindex @code{mult}, canonicalization of
8890 @item
8891 @code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
8892 (sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
8893 (sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
8894 for @code{zero_extend}.
8896 @item
8897 @code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
8898 @var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
8899 to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
8900 @var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
8901 patterns using @code{zero_extend} and @code{lshiftrt}.  If the second
8902 operand of @code{mult} is also a shift, then that is extended also.
8903 This transformation is only applied when it can be proven that the
8904 original operation had sufficient precision to prevent overflow.
8906 @end itemize
8908 Further canonicalization rules are defined in the function
8909 @code{commutative_operand_precedence} in @file{gcc/rtlanal.cc}.
8911 @end ifset
8912 @ifset INTERNALS
8913 @node Expander Definitions
8914 @section Defining RTL Sequences for Code Generation
8915 @cindex expander definitions
8916 @cindex code generation RTL sequences
8917 @cindex defining RTL sequences for code generation
8919 On some target machines, some standard pattern names for RTL generation
8920 cannot be handled with single insn, but a sequence of RTL insns can
8921 represent them.  For these target machines, you can write a
8922 @code{define_expand} to specify how to generate the sequence of RTL@.
8924 @findex define_expand
8925 A @code{define_expand} is an RTL expression that looks almost like a
8926 @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
8927 only for RTL generation and it can produce more than one RTL insn.
8929 A @code{define_expand} RTX has four operands:
8931 @itemize @bullet
8932 @item
8933 The name.  Each @code{define_expand} must have a name, since the only
8934 use for it is to refer to it by name.
8936 @item
8937 The RTL template.  This is a vector of RTL expressions representing
8938 a sequence of separate instructions.  Unlike @code{define_insn}, there
8939 is no implicit surrounding @code{PARALLEL}.
8941 @item
8942 The condition, a string containing a C expression.  This expression is
8943 used to express how the availability of this pattern depends on
8944 subclasses of target machine, selected by command-line options when GCC
8945 is run.  This is just like the condition of a @code{define_insn} that
8946 has a standard name.  Therefore, the condition (if present) may not
8947 depend on the data in the insn being matched, but only the
8948 target-machine-type flags.  The compiler needs to test these conditions
8949 during initialization in order to learn exactly which named instructions
8950 are available in a particular run.
8952 @item
8953 The preparation statements, a string containing zero or more C
8954 statements which are to be executed before RTL code is generated from
8955 the RTL template.
8957 Usually these statements prepare temporary registers for use as
8958 internal operands in the RTL template, but they can also generate RTL
8959 insns directly by calling routines such as @code{emit_insn}, etc.
8960 Any such insns precede the ones that come from the RTL template.
8962 @item
8963 Optionally, a vector containing the values of attributes. @xref{Insn
8964 Attributes}.
8965 @end itemize
8967 Every RTL insn emitted by a @code{define_expand} must match some
8968 @code{define_insn} in the machine description.  Otherwise, the compiler
8969 will crash when trying to generate code for the insn or trying to optimize
8972 The RTL template, in addition to controlling generation of RTL insns,
8973 also describes the operands that need to be specified when this pattern
8974 is used.  In particular, it gives a predicate for each operand.
8976 A true operand, which needs to be specified in order to generate RTL from
8977 the pattern, should be described with a @code{match_operand} in its first
8978 occurrence in the RTL template.  This enters information on the operand's
8979 predicate into the tables that record such things.  GCC uses the
8980 information to preload the operand into a register if that is required for
8981 valid RTL code.  If the operand is referred to more than once, subsequent
8982 references should use @code{match_dup}.
8984 The RTL template may also refer to internal ``operands'' which are
8985 temporary registers or labels used only within the sequence made by the
8986 @code{define_expand}.  Internal operands are substituted into the RTL
8987 template with @code{match_dup}, never with @code{match_operand}.  The
8988 values of the internal operands are not passed in as arguments by the
8989 compiler when it requests use of this pattern.  Instead, they are computed
8990 within the pattern, in the preparation statements.  These statements
8991 compute the values and store them into the appropriate elements of
8992 @code{operands} so that @code{match_dup} can find them.
8994 There are two special macros defined for use in the preparation statements:
8995 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
8996 as a statement.
8998 @table @code
9000 @findex DONE
9001 @item DONE
9002 Use the @code{DONE} macro to end RTL generation for the pattern.  The
9003 only RTL insns resulting from the pattern on this occasion will be
9004 those already emitted by explicit calls to @code{emit_insn} within the
9005 preparation statements; the RTL template will not be generated.
9007 @findex FAIL
9008 @item FAIL
9009 Make the pattern fail on this occasion.  When a pattern fails, it means
9010 that the pattern was not truly available.  The calling routines in the
9011 compiler will try other strategies for code generation using other patterns.
9013 Failure is currently supported only for binary (addition, multiplication,
9014 shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
9015 operations.
9016 @end table
9018 If the preparation falls through (invokes neither @code{DONE} nor
9019 @code{FAIL}), then the @code{define_expand} acts like a
9020 @code{define_insn} in that the RTL template is used to generate the
9021 insn.
9023 The RTL template is not used for matching, only for generating the
9024 initial insn list.  If the preparation statement always invokes
9025 @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
9026 list of operands, such as this example:
9028 @smallexample
9029 @group
9030 (define_expand "addsi3"
9031   [(match_operand:SI 0 "register_operand" "")
9032    (match_operand:SI 1 "register_operand" "")
9033    (match_operand:SI 2 "register_operand" "")]
9034   ""
9035   "
9037   handle_add (operands[0], operands[1], operands[2]);
9038   DONE;
9039 @}")
9040 @end group
9041 @end smallexample
9043 Here is an example, the definition of left-shift for the SPUR chip:
9045 @smallexample
9046 @group
9047 (define_expand "ashlsi3"
9048   [(set (match_operand:SI 0 "register_operand" "")
9049         (ashift:SI
9050           (match_operand:SI 1 "register_operand" "")
9051           (match_operand:SI 2 "nonmemory_operand" "")))]
9052   ""
9053   "
9055   if (GET_CODE (operands[2]) != CONST_INT
9056       || (unsigned) INTVAL (operands[2]) > 3)
9057     FAIL;
9058 @}")
9059 @end group
9060 @end smallexample
9062 @noindent
9063 This example uses @code{define_expand} so that it can generate an RTL insn
9064 for shifting when the shift-count is in the supported range of 0 to 3 but
9065 fail in other cases where machine insns aren't available.  When it fails,
9066 the compiler tries another strategy using different patterns (such as, a
9067 library call).
9069 If the compiler were able to handle nontrivial condition-strings in
9070 patterns with names, then it would be possible to use a
9071 @code{define_insn} in that case.  Here is another case (zero-extension
9072 on the 68000) which makes more use of the power of @code{define_expand}:
9074 @smallexample
9075 (define_expand "zero_extendhisi2"
9076   [(set (match_operand:SI 0 "general_operand" "")
9077         (const_int 0))
9078    (set (strict_low_part
9079           (subreg:HI
9080             (match_dup 0)
9081             0))
9082         (match_operand:HI 1 "general_operand" ""))]
9083   ""
9084   "operands[1] = make_safe_from (operands[1], operands[0]);")
9085 @end smallexample
9087 @noindent
9088 @findex make_safe_from
9089 Here two RTL insns are generated, one to clear the entire output operand
9090 and the other to copy the input operand into its low half.  This sequence
9091 is incorrect if the input operand refers to [the old value of] the output
9092 operand, so the preparation statement makes sure this isn't so.  The
9093 function @code{make_safe_from} copies the @code{operands[1]} into a
9094 temporary register if it refers to @code{operands[0]}.  It does this
9095 by emitting another RTL insn.
9097 Finally, a third example shows the use of an internal operand.
9098 Zero-extension on the SPUR chip is done by @code{and}-ing the result
9099 against a halfword mask.  But this mask cannot be represented by a
9100 @code{const_int} because the constant value is too large to be legitimate
9101 on this machine.  So it must be copied into a register with
9102 @code{force_reg} and then the register used in the @code{and}.
9104 @smallexample
9105 (define_expand "zero_extendhisi2"
9106   [(set (match_operand:SI 0 "register_operand" "")
9107         (and:SI (subreg:SI
9108                   (match_operand:HI 1 "register_operand" "")
9109                   0)
9110                 (match_dup 2)))]
9111   ""
9112   "operands[2]
9113      = force_reg (SImode, GEN_INT (65535)); ")
9114 @end smallexample
9116 @emph{Note:} If the @code{define_expand} is used to serve a
9117 standard binary or unary arithmetic operation or a bit-field operation,
9118 then the last insn it generates must not be a @code{code_label},
9119 @code{barrier} or @code{note}.  It must be an @code{insn},
9120 @code{jump_insn} or @code{call_insn}.  If you don't need a real insn
9121 at the end, emit an insn to copy the result of the operation into
9122 itself.  Such an insn will generate no code, but it can avoid problems
9123 in the compiler.
9125 @end ifset
9126 @ifset INTERNALS
9127 @node Insn Splitting
9128 @section Defining How to Split Instructions
9129 @cindex insn splitting
9130 @cindex instruction splitting
9131 @cindex splitting instructions
9133 There are two cases where you should specify how to split a pattern
9134 into multiple insns.  On machines that have instructions requiring
9135 delay slots (@pxref{Delay Slots}) or that have instructions whose
9136 output is not available for multiple cycles (@pxref{Processor pipeline
9137 description}), the compiler phases that optimize these cases need to
9138 be able to move insns into one-instruction delay slots.  However, some
9139 insns may generate more than one machine instruction.  These insns
9140 cannot be placed into a delay slot.
9142 Often you can rewrite the single insn as a list of individual insns,
9143 each corresponding to one machine instruction.  The disadvantage of
9144 doing so is that it will cause the compilation to be slower and require
9145 more space.  If the resulting insns are too complex, it may also
9146 suppress some optimizations.  The compiler splits the insn if there is a
9147 reason to believe that it might improve instruction or delay slot
9148 scheduling.
9150 The insn combiner phase also splits putative insns.  If three insns are
9151 merged into one insn with a complex expression that cannot be matched by
9152 some @code{define_insn} pattern, the combiner phase attempts to split
9153 the complex pattern into two insns that are recognized.  Usually it can
9154 break the complex pattern into two patterns by splitting out some
9155 subexpression.  However, in some other cases, such as performing an
9156 addition of a large constant in two insns on a RISC machine, the way to
9157 split the addition into two insns is machine-dependent.
9159 @findex define_split
9160 The @code{define_split} definition tells the compiler how to split a
9161 complex insn into several simpler insns.  It looks like this:
9163 @smallexample
9164 (define_split
9165   [@var{insn-pattern}]
9166   "@var{condition}"
9167   [@var{new-insn-pattern-1}
9168    @var{new-insn-pattern-2}
9169    @dots{}]
9170   "@var{preparation-statements}")
9171 @end smallexample
9173 @var{insn-pattern} is a pattern that needs to be split and
9174 @var{condition} is the final condition to be tested, as in a
9175 @code{define_insn}.  When an insn matching @var{insn-pattern} and
9176 satisfying @var{condition} is found, it is replaced in the insn list
9177 with the insns given by @var{new-insn-pattern-1},
9178 @var{new-insn-pattern-2}, etc.
9180 The @var{preparation-statements} are similar to those statements that
9181 are specified for @code{define_expand} (@pxref{Expander Definitions})
9182 and are executed before the new RTL is generated to prepare for the
9183 generated code or emit some insns whose pattern is not fixed.  Unlike
9184 those in @code{define_expand}, however, these statements must not
9185 generate any new pseudo-registers.  Once reload has completed, they also
9186 must not allocate any space in the stack frame.
9188 There are two special macros defined for use in the preparation statements:
9189 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
9190 as a statement.
9192 @table @code
9194 @findex DONE
9195 @item DONE
9196 Use the @code{DONE} macro to end RTL generation for the splitter.  The
9197 only RTL insns generated as replacement for the matched input insn will
9198 be those already emitted by explicit calls to @code{emit_insn} within
9199 the preparation statements; the replacement pattern is not used.
9201 @findex FAIL
9202 @item FAIL
9203 Make the @code{define_split} fail on this occasion.  When a @code{define_split}
9204 fails, it means that the splitter was not truly available for the inputs
9205 it was given, and the input insn will not be split.
9206 @end table
9208 If the preparation falls through (invokes neither @code{DONE} nor
9209 @code{FAIL}), then the @code{define_split} uses the replacement
9210 template.
9212 Patterns are matched against @var{insn-pattern} in two different
9213 circumstances.  If an insn needs to be split for delay slot scheduling
9214 or insn scheduling, the insn is already known to be valid, which means
9215 that it must have been matched by some @code{define_insn} and, if
9216 @code{reload_completed} is nonzero, is known to satisfy the constraints
9217 of that @code{define_insn}.  In that case, the new insn patterns must
9218 also be insns that are matched by some @code{define_insn} and, if
9219 @code{reload_completed} is nonzero, must also satisfy the constraints
9220 of those definitions.
9222 As an example of this usage of @code{define_split}, consider the following
9223 example from @file{a29k.md}, which splits a @code{sign_extend} from
9224 @code{HImode} to @code{SImode} into a pair of shift insns:
9226 @smallexample
9227 (define_split
9228   [(set (match_operand:SI 0 "gen_reg_operand" "")
9229         (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
9230   ""
9231   [(set (match_dup 0)
9232         (ashift:SI (match_dup 1)
9233                    (const_int 16)))
9234    (set (match_dup 0)
9235         (ashiftrt:SI (match_dup 0)
9236                      (const_int 16)))]
9237   "
9238 @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
9239 @end smallexample
9241 When the combiner phase tries to split an insn pattern, it is always the
9242 case that the pattern is @emph{not} matched by any @code{define_insn}.
9243 The combiner pass first tries to split a single @code{set} expression
9244 and then the same @code{set} expression inside a @code{parallel}, but
9245 followed by a @code{clobber} of a pseudo-reg to use as a scratch
9246 register.  In these cases, the combiner expects exactly one or two new insn
9247 patterns to be generated.  It will verify that these patterns match some
9248 @code{define_insn} definitions, so you need not do this test in the
9249 @code{define_split} (of course, there is no point in writing a
9250 @code{define_split} that will never produce insns that match).
9252 Here is an example of this use of @code{define_split}, taken from
9253 @file{rs6000.md}:
9255 @smallexample
9256 (define_split
9257   [(set (match_operand:SI 0 "gen_reg_operand" "")
9258         (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
9259                  (match_operand:SI 2 "non_add_cint_operand" "")))]
9260   ""
9261   [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
9262    (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
9265   int low = INTVAL (operands[2]) & 0xffff;
9266   int high = (unsigned) INTVAL (operands[2]) >> 16;
9268   if (low & 0x8000)
9269     high++, low |= 0xffff0000;
9271   operands[3] = GEN_INT (high << 16);
9272   operands[4] = GEN_INT (low);
9273 @}")
9274 @end smallexample
9276 Here the predicate @code{non_add_cint_operand} matches any
9277 @code{const_int} that is @emph{not} a valid operand of a single add
9278 insn.  The add with the smaller displacement is written so that it
9279 can be substituted into the address of a subsequent operation.
9281 An example that uses a scratch register, from the same file, generates
9282 an equality comparison of a register and a large constant:
9284 @smallexample
9285 (define_split
9286   [(set (match_operand:CC 0 "cc_reg_operand" "")
9287         (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
9288                     (match_operand:SI 2 "non_short_cint_operand" "")))
9289    (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
9290   "find_single_use (operands[0], insn, 0)
9291    && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
9292        || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
9293   [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
9294    (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
9295   "
9297   /* @r{Get the constant we are comparing against, C, and see what it
9298      looks like sign-extended to 16 bits.  Then see what constant
9299      could be XOR'ed with C to get the sign-extended value.}  */
9301   int c = INTVAL (operands[2]);
9302   int sextc = (c << 16) >> 16;
9303   int xorv = c ^ sextc;
9305   operands[4] = GEN_INT (xorv);
9306   operands[5] = GEN_INT (sextc);
9307 @}")
9308 @end smallexample
9310 To avoid confusion, don't write a single @code{define_split} that
9311 accepts some insns that match some @code{define_insn} as well as some
9312 insns that don't.  Instead, write two separate @code{define_split}
9313 definitions, one for the insns that are valid and one for the insns that
9314 are not valid.
9316 The splitter is allowed to split jump instructions into a sequence of jumps or
9317 create new jumps while splitting non-jump instructions.  As the control flow
9318 graph and branch prediction information needs to be updated after the splitter
9319 runs, several restrictions apply.
9321 Splitting of a jump instruction into a sequence that has another jump
9322 instruction to the same label is always valid, as the compiler expects
9323 identical behavior of the new jump.  When the new sequence contains multiple
9324 jump instructions or new labels, more assistance is needed.  The splitter is
9325 permitted to create only unconditional jumps, or simple conditional jump
9326 instructions.  Additionally it must attach a @code{REG_BR_PROB} note to each
9327 conditional jump.  A global variable @code{split_branch_probability} holds the
9328 probability of the original branch in case it was a simple conditional jump,
9329 @minus{}1 otherwise.  To simplify recomputing of edge frequencies, the new
9330 sequence is permitted to have only forward jumps to the newly-created labels.
9332 @findex define_insn_and_split
9333 For the common case where the pattern of a define_split exactly matches the
9334 pattern of a define_insn, use @code{define_insn_and_split}.  It looks like
9335 this:
9337 @smallexample
9338 (define_insn_and_split
9339   [@var{insn-pattern}]
9340   "@var{condition}"
9341   "@var{output-template}"
9342   "@var{split-condition}"
9343   [@var{new-insn-pattern-1}
9344    @var{new-insn-pattern-2}
9345    @dots{}]
9346   "@var{preparation-statements}"
9347   [@var{insn-attributes}])
9349 @end smallexample
9351 @var{insn-pattern}, @var{condition}, @var{output-template}, and
9352 @var{insn-attributes} are used as in @code{define_insn}.  The
9353 @var{new-insn-pattern} vector and the @var{preparation-statements} are used as
9354 in a @code{define_split}.  The @var{split-condition} is also used as in
9355 @code{define_split}, with the additional behavior that if the condition starts
9356 with @samp{&&}, the condition used for the split will be the constructed as a
9357 logical ``and'' of the split condition with the insn condition.  For example,
9358 from i386.md:
9360 @smallexample
9361 (define_insn_and_split "zero_extendhisi2_and"
9362   [(set (match_operand:SI 0 "register_operand" "=r")
9363      (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
9364    (clobber (reg:CC 17))]
9365   "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
9366   "#"
9367   "&& reload_completed"
9368   [(parallel [(set (match_dup 0)
9369                    (and:SI (match_dup 0) (const_int 65535)))
9370               (clobber (reg:CC 17))])]
9371   ""
9372   [(set_attr "type" "alu1")])
9374 @end smallexample
9376 In this case, the actual split condition will be
9377 @samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
9379 The @code{define_insn_and_split} construction provides exactly the same
9380 functionality as two separate @code{define_insn} and @code{define_split}
9381 patterns.  It exists for compactness, and as a maintenance tool to prevent
9382 having to ensure the two patterns' templates match.
9384 @findex define_insn_and_rewrite
9385 It is sometimes useful to have a @code{define_insn_and_split}
9386 that replaces specific operands of an instruction but leaves the
9387 rest of the instruction pattern unchanged.  You can do this directly
9388 with a @code{define_insn_and_split}, but it requires a
9389 @var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}.
9390 There is also the complication that an implicit @code{parallel} in
9391 @var{insn-pattern} must become an explicit @code{parallel} in
9392 @var{new-insn-pattern-1}, which is easy to overlook.
9393 A simpler alternative is to use @code{define_insn_and_rewrite}, which
9394 is a form of @code{define_insn_and_split} that automatically generates
9395 @var{new-insn-pattern-1} by replacing each @code{match_operand}
9396 in @var{insn-pattern} with a corresponding @code{match_dup}, and each
9397 @code{match_operator} in the pattern with a corresponding @code{match_op_dup}.
9398 The arguments are otherwise identical to @code{define_insn_and_split}:
9400 @smallexample
9401 (define_insn_and_rewrite
9402   [@var{insn-pattern}]
9403   "@var{condition}"
9404   "@var{output-template}"
9405   "@var{split-condition}"
9406   "@var{preparation-statements}"
9407   [@var{insn-attributes}])
9408 @end smallexample
9410 The @code{match_dup}s and @code{match_op_dup}s in the new
9411 instruction pattern use any new operand values that the
9412 @var{preparation-statements} store in the @code{operands} array,
9413 as for a normal @code{define_insn_and_split}.  @var{preparation-statements}
9414 can also emit additional instructions before the new instruction.
9415 They can even emit an entirely different sequence of instructions and
9416 use @code{DONE} to avoid emitting a new form of the original
9417 instruction.
9419 The split in a @code{define_insn_and_rewrite} is only intended
9420 to apply to existing instructions that match @var{insn-pattern}.
9421 @var{split-condition} must therefore start with @code{&&},
9422 so that the split condition applies on top of @var{condition}.
9424 Here is an example from the AArch64 SVE port, in which operand 1 is
9425 known to be equivalent to an all-true constant and isn't used by the
9426 output template:
9428 @smallexample
9429 (define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
9430   [(set (reg:CC CC_REGNUM)
9431         (compare:CC
9432           (unspec:SI [(match_operand:PRED_ALL 1)
9433                       (unspec:PRED_ALL
9434                         [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
9435                          (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
9436                         UNSPEC_WHILE_LO)]
9437                      UNSPEC_PTEST_PTRUE)
9438           (const_int 0)))
9439    (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
9440         (unspec:PRED_ALL [(match_dup 2)
9441                           (match_dup 3)]
9442                          UNSPEC_WHILE_LO))]
9443   "TARGET_SVE"
9444   "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
9445   ;; Force the compiler to drop the unused predicate operand, so that we
9446   ;; don't have an unnecessary PTRUE.
9447   "&& !CONSTANT_P (operands[1])"
9448   @{
9449     operands[1] = CONSTM1_RTX (<MODE>mode);
9450   @}
9452 @end smallexample
9454 The splitter in this case simply replaces operand 1 with the constant
9455 value that it is known to have.  The equivalent @code{define_insn_and_split}
9456 would be:
9458 @smallexample
9459 (define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
9460   [(set (reg:CC CC_REGNUM)
9461         (compare:CC
9462           (unspec:SI [(match_operand:PRED_ALL 1)
9463                       (unspec:PRED_ALL
9464                         [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
9465                          (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
9466                         UNSPEC_WHILE_LO)]
9467                      UNSPEC_PTEST_PTRUE)
9468           (const_int 0)))
9469    (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
9470         (unspec:PRED_ALL [(match_dup 2)
9471                           (match_dup 3)]
9472                          UNSPEC_WHILE_LO))]
9473   "TARGET_SVE"
9474   "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
9475   ;; Force the compiler to drop the unused predicate operand, so that we
9476   ;; don't have an unnecessary PTRUE.
9477   "&& !CONSTANT_P (operands[1])"
9478   [(parallel
9479      [(set (reg:CC CC_REGNUM)
9480            (compare:CC
9481              (unspec:SI [(match_dup 1)
9482                          (unspec:PRED_ALL [(match_dup 2)
9483                                            (match_dup 3)]
9484                                           UNSPEC_WHILE_LO)]
9485                         UNSPEC_PTEST_PTRUE)
9486              (const_int 0)))
9487       (set (match_dup 0)
9488            (unspec:PRED_ALL [(match_dup 2)
9489                              (match_dup 3)]
9490                             UNSPEC_WHILE_LO))])]
9491   @{
9492     operands[1] = CONSTM1_RTX (<MODE>mode);
9493   @}
9495 @end smallexample
9497 @end ifset
9498 @ifset INTERNALS
9499 @node Including Patterns
9500 @section Including Patterns in Machine Descriptions.
9501 @cindex insn includes
9503 @findex include
9504 The @code{include} pattern tells the compiler tools where to
9505 look for patterns that are in files other than in the file
9506 @file{.md}.  This is used only at build time and there is no preprocessing allowed.
9508 It looks like:
9510 @smallexample
9512 (include @var{pathname})
9513 @end smallexample
9515 For example:
9517 @smallexample
9519 (include "filestuff")
9521 @end smallexample
9523 Where @var{pathname} is a string that specifies the location of the file,
9524 specifies the include file to be in @file{gcc/config/target/filestuff}.  The
9525 directory @file{gcc/config/target} is regarded as the default directory.
9528 Machine descriptions may be split up into smaller more manageable subsections
9529 and placed into subdirectories.
9531 By specifying:
9533 @smallexample
9535 (include "BOGUS/filestuff")
9537 @end smallexample
9539 the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.
9541 Specifying an absolute path for the include file such as;
9542 @smallexample
9544 (include "/u2/BOGUS/filestuff")
9546 @end smallexample
9547 is permitted but is not encouraged.
9549 @subsection RTL Generation Tool Options for Directory Search
9550 @cindex directory options .md
9551 @cindex options, directory search
9552 @cindex search options
9554 The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
9555 For example:
9557 @smallexample
9559 genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
9561 @end smallexample
9564 Add the directory @var{dir} to the head of the list of directories to be
9565 searched for header files.  This can be used to override a system machine definition
9566 file, substituting your own version, since these directories are
9567 searched before the default machine description file directories.  If you use more than
9568 one @option{-I} option, the directories are scanned in left-to-right
9569 order; the standard default directory come after.
9572 @end ifset
9573 @ifset INTERNALS
9574 @node Peephole Definitions
9575 @section Machine-Specific Peephole Optimizers
9576 @cindex peephole optimizer definitions
9577 @cindex defining peephole optimizers
9579 In addition to instruction patterns the @file{md} file may contain
9580 definitions of machine-specific peephole optimizations.
9582 The combiner does not notice certain peephole optimizations when the data
9583 flow in the program does not suggest that it should try them.  For example,
9584 sometimes two consecutive insns related in purpose can be combined even
9585 though the second one does not appear to use a register computed in the
9586 first one.  A machine-specific peephole optimizer can detect such
9587 opportunities.
9589 There are two forms of peephole definitions that may be used.  The
9590 original @code{define_peephole} is run at assembly output time to
9591 match insns and substitute assembly text.  Use of @code{define_peephole}
9592 is deprecated.
9594 A newer @code{define_peephole2} matches insns and substitutes new
9595 insns.  The @code{peephole2} pass is run after register allocation
9596 but before scheduling, which may result in much better code for
9597 targets that do scheduling.
9599 @menu
9600 * define_peephole::     RTL to Text Peephole Optimizers
9601 * define_peephole2::    RTL to RTL Peephole Optimizers
9602 @end menu
9604 @end ifset
9605 @ifset INTERNALS
9606 @node define_peephole
9607 @subsection RTL to Text Peephole Optimizers
9608 @findex define_peephole
9610 @need 1000
9611 A definition looks like this:
9613 @smallexample
9614 (define_peephole
9615   [@var{insn-pattern-1}
9616    @var{insn-pattern-2}
9617    @dots{}]
9618   "@var{condition}"
9619   "@var{template}"
9620   "@var{optional-insn-attributes}")
9621 @end smallexample
9623 @noindent
9624 The last string operand may be omitted if you are not using any
9625 machine-specific information in this machine description.  If present,
9626 it must obey the same rules as in a @code{define_insn}.
9628 In this skeleton, @var{insn-pattern-1} and so on are patterns to match
9629 consecutive insns.  The optimization applies to a sequence of insns when
9630 @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
9631 the next, and so on.
9633 Each of the insns matched by a peephole must also match a
9634 @code{define_insn}.  Peepholes are checked only at the last stage just
9635 before code generation, and only optionally.  Therefore, any insn which
9636 would match a peephole but no @code{define_insn} will cause a crash in code
9637 generation in an unoptimized compilation, or at various optimization
9638 stages.
9640 The operands of the insns are matched with @code{match_operands},
9641 @code{match_operator}, and @code{match_dup}, as usual.  What is not
9642 usual is that the operand numbers apply to all the insn patterns in the
9643 definition.  So, you can check for identical operands in two insns by
9644 using @code{match_operand} in one insn and @code{match_dup} in the
9645 other.
9647 The operand constraints used in @code{match_operand} patterns do not have
9648 any direct effect on the applicability of the peephole, but they will
9649 be validated afterward, so make sure your constraints are general enough
9650 to apply whenever the peephole matches.  If the peephole matches
9651 but the constraints are not satisfied, the compiler will crash.
9653 It is safe to omit constraints in all the operands of the peephole; or
9654 you can write constraints which serve as a double-check on the criteria
9655 previously tested.
9657 Once a sequence of insns matches the patterns, the @var{condition} is
9658 checked.  This is a C expression which makes the final decision whether to
9659 perform the optimization (we do so if the expression is nonzero).  If
9660 @var{condition} is omitted (in other words, the string is empty) then the
9661 optimization is applied to every sequence of insns that matches the
9662 patterns.
9664 The defined peephole optimizations are applied after register allocation
9665 is complete.  Therefore, the peephole definition can check which
9666 operands have ended up in which kinds of registers, just by looking at
9667 the operands.
9669 @findex prev_active_insn
9670 The way to refer to the operands in @var{condition} is to write
9671 @code{operands[@var{i}]} for operand number @var{i} (as matched by
9672 @code{(match_operand @var{i} @dots{})}).  Use the variable @code{insn}
9673 to refer to the last of the insns being matched; use
9674 @code{prev_active_insn} to find the preceding insns.
9676 @findex dead_or_set_p
9677 When optimizing computations with intermediate results, you can use
9678 @var{condition} to match only when the intermediate results are not used
9679 elsewhere.  Use the C expression @code{dead_or_set_p (@var{insn},
9680 @var{op})}, where @var{insn} is the insn in which you expect the value
9681 to be used for the last time (from the value of @code{insn}, together
9682 with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
9683 value (from @code{operands[@var{i}]}).
9685 Applying the optimization means replacing the sequence of insns with one
9686 new insn.  The @var{template} controls ultimate output of assembler code
9687 for this combined insn.  It works exactly like the template of a
9688 @code{define_insn}.  Operand numbers in this template are the same ones
9689 used in matching the original sequence of insns.
9691 The result of a defined peephole optimizer does not need to match any of
9692 the insn patterns in the machine description; it does not even have an
9693 opportunity to match them.  The peephole optimizer definition itself serves
9694 as the insn pattern to control how the insn is output.
9696 Defined peephole optimizers are run as assembler code is being output,
9697 so the insns they produce are never combined or rearranged in any way.
9699 Here is an example, taken from the 68000 machine description:
9701 @smallexample
9702 (define_peephole
9703   [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
9704    (set (match_operand:DF 0 "register_operand" "=f")
9705         (match_operand:DF 1 "register_operand" "ad"))]
9706   "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
9708   rtx xoperands[2];
9709   xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
9710 #ifdef MOTOROLA
9711   output_asm_insn ("move.l %1,(sp)", xoperands);
9712   output_asm_insn ("move.l %1,-(sp)", operands);
9713   return "fmove.d (sp)+,%0";
9714 #else
9715   output_asm_insn ("movel %1,sp@@", xoperands);
9716   output_asm_insn ("movel %1,sp@@-", operands);
9717   return "fmoved sp@@+,%0";
9718 #endif
9720 @end smallexample
9722 @need 1000
9723 The effect of this optimization is to change
9725 @smallexample
9726 @group
9727 jbsr _foobar
9728 addql #4,sp
9729 movel d1,sp@@-
9730 movel d0,sp@@-
9731 fmoved sp@@+,fp0
9732 @end group
9733 @end smallexample
9735 @noindent
9736 into
9738 @smallexample
9739 @group
9740 jbsr _foobar
9741 movel d1,sp@@
9742 movel d0,sp@@-
9743 fmoved sp@@+,fp0
9744 @end group
9745 @end smallexample
9747 @ignore
9748 @findex CC_REVERSED
9749 If a peephole matches a sequence including one or more jump insns, you must
9750 take account of the flags such as @code{CC_REVERSED} which specify that the
9751 condition codes are represented in an unusual manner.  The compiler
9752 automatically alters any ordinary conditional jumps which occur in such
9753 situations, but the compiler cannot alter jumps which have been replaced by
9754 peephole optimizations.  So it is up to you to alter the assembler code
9755 that the peephole produces.  Supply C code to write the assembler output,
9756 and in this C code check the condition code status flags and change the
9757 assembler code as appropriate.
9758 @end ignore
9760 @var{insn-pattern-1} and so on look @emph{almost} like the second
9761 operand of @code{define_insn}.  There is one important difference: the
9762 second operand of @code{define_insn} consists of one or more RTX's
9763 enclosed in square brackets.  Usually, there is only one: then the same
9764 action can be written as an element of a @code{define_peephole}.  But
9765 when there are multiple actions in a @code{define_insn}, they are
9766 implicitly enclosed in a @code{parallel}.  Then you must explicitly
9767 write the @code{parallel}, and the square brackets within it, in the
9768 @code{define_peephole}.  Thus, if an insn pattern looks like this,
9770 @smallexample
9771 (define_insn "divmodsi4"
9772   [(set (match_operand:SI 0 "general_operand" "=d")
9773         (div:SI (match_operand:SI 1 "general_operand" "0")
9774                 (match_operand:SI 2 "general_operand" "dmsK")))
9775    (set (match_operand:SI 3 "general_operand" "=d")
9776         (mod:SI (match_dup 1) (match_dup 2)))]
9777   "TARGET_68020"
9778   "divsl%.l %2,%3:%0")
9779 @end smallexample
9781 @noindent
9782 then the way to mention this insn in a peephole is as follows:
9784 @smallexample
9785 (define_peephole
9786   [@dots{}
9787    (parallel
9788     [(set (match_operand:SI 0 "general_operand" "=d")
9789           (div:SI (match_operand:SI 1 "general_operand" "0")
9790                   (match_operand:SI 2 "general_operand" "dmsK")))
9791      (set (match_operand:SI 3 "general_operand" "=d")
9792           (mod:SI (match_dup 1) (match_dup 2)))])
9793    @dots{}]
9794   @dots{})
9795 @end smallexample
9797 @end ifset
9798 @ifset INTERNALS
9799 @node define_peephole2
9800 @subsection RTL to RTL Peephole Optimizers
9801 @findex define_peephole2
9803 The @code{define_peephole2} definition tells the compiler how to
9804 substitute one sequence of instructions for another sequence,
9805 what additional scratch registers may be needed and what their
9806 lifetimes must be.
9808 @smallexample
9809 (define_peephole2
9810   [@var{insn-pattern-1}
9811    @var{insn-pattern-2}
9812    @dots{}]
9813   "@var{condition}"
9814   [@var{new-insn-pattern-1}
9815    @var{new-insn-pattern-2}
9816    @dots{}]
9817   "@var{preparation-statements}")
9818 @end smallexample
9820 The definition is almost identical to @code{define_split}
9821 (@pxref{Insn Splitting}) except that the pattern to match is not a
9822 single instruction, but a sequence of instructions.
9824 It is possible to request additional scratch registers for use in the
9825 output template.  If appropriate registers are not free, the pattern
9826 will simply not match.
9828 @findex match_scratch
9829 @findex match_dup
9830 Scratch registers are requested with a @code{match_scratch} pattern at
9831 the top level of the input pattern.  The allocated register (initially) will
9832 be dead at the point requested within the original sequence.  If the scratch
9833 is used at more than a single point, a @code{match_dup} pattern at the
9834 top level of the input pattern marks the last position in the input sequence
9835 at which the register must be available.
9837 Here is an example from the IA-32 machine description:
9839 @smallexample
9840 (define_peephole2
9841   [(match_scratch:SI 2 "r")
9842    (parallel [(set (match_operand:SI 0 "register_operand" "")
9843                    (match_operator:SI 3 "arith_or_logical_operator"
9844                      [(match_dup 0)
9845                       (match_operand:SI 1 "memory_operand" "")]))
9846               (clobber (reg:CC 17))])]
9847   "! optimize_size && ! TARGET_READ_MODIFY"
9848   [(set (match_dup 2) (match_dup 1))
9849    (parallel [(set (match_dup 0)
9850                    (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
9851               (clobber (reg:CC 17))])]
9852   "")
9853 @end smallexample
9855 @noindent
9856 This pattern tries to split a load from its use in the hopes that we'll be
9857 able to schedule around the memory load latency.  It allocates a single
9858 @code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
9859 to be live only at the point just before the arithmetic.
9861 A real example requiring extended scratch lifetimes is harder to come by,
9862 so here's a silly made-up example:
9864 @smallexample
9865 (define_peephole2
9866   [(match_scratch:SI 4 "r")
9867    (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
9868    (set (match_operand:SI 2 "" "") (match_dup 1))
9869    (match_dup 4)
9870    (set (match_operand:SI 3 "" "") (match_dup 1))]
9871   "/* @r{determine 1 does not overlap 0 and 2} */"
9872   [(set (match_dup 4) (match_dup 1))
9873    (set (match_dup 0) (match_dup 4))
9874    (set (match_dup 2) (match_dup 4))
9875    (set (match_dup 3) (match_dup 4))]
9876   "")
9877 @end smallexample
9879 @noindent
9880 If we had not added the @code{(match_dup 4)} in the middle of the input
9881 sequence, it might have been the case that the register we chose at the
9882 beginning of the sequence is killed by the first or second @code{set}.
9884 There are two special macros defined for use in the preparation statements:
9885 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
9886 as a statement.
9888 @table @code
9890 @findex DONE
9891 @item DONE
9892 Use the @code{DONE} macro to end RTL generation for the peephole.  The
9893 only RTL insns generated as replacement for the matched input insn will
9894 be those already emitted by explicit calls to @code{emit_insn} within
9895 the preparation statements; the replacement pattern is not used.
9897 @findex FAIL
9898 @item FAIL
9899 Make the @code{define_peephole2} fail on this occasion.  When a @code{define_peephole2}
9900 fails, it means that the replacement was not truly available for the
9901 particular inputs it was given.  In that case, GCC may still apply a
9902 later @code{define_peephole2} that also matches the given insn pattern.
9903 (Note that this is different from @code{define_split}, where @code{FAIL}
9904 prevents the input insn from being split at all.)
9905 @end table
9907 If the preparation falls through (invokes neither @code{DONE} nor
9908 @code{FAIL}), then the @code{define_peephole2} uses the replacement
9909 template.
9911 Insns are scanned in forward order from beginning to end for each basic
9912 block.  Matches are attempted in order of @code{define_peephole2}
9913 appearance in the @file{md} file.  After a successful replacement,
9914 scanning for further opportunities for @code{define_peephole2}, resumes
9915 with the first generated replacement insn as the first insn to be
9916 matched against all @code{define_peephole2}.  For the example above,
9917 after its successful replacement, the first insn that can be matched by
9918 a @code{define_peephole2} is @code{(set (match_dup 4) (match_dup 1))}.
9920 @end ifset
9921 @ifset INTERNALS
9922 @node Insn Attributes
9923 @section Instruction Attributes
9924 @cindex insn attributes
9925 @cindex instruction attributes
9927 In addition to describing the instruction supported by the target machine,
9928 the @file{md} file also defines a group of @dfn{attributes} and a set of
9929 values for each.  Every generated insn is assigned a value for each attribute.
9930 One possible attribute would be the effect that the insn has on the machine's
9931 condition code.
9933 @menu
9934 * Defining Attributes:: Specifying attributes and their values.
9935 * Expressions::         Valid expressions for attribute values.
9936 * Tagging Insns::       Assigning attribute values to insns.
9937 * Attr Example::        An example of assigning attributes.
9938 * Insn Lengths::        Computing the length of insns.
9939 * Constant Attributes:: Defining attributes that are constant.
9940 * Mnemonic Attribute::  Obtain the instruction mnemonic as attribute value.
9941 * Delay Slots::         Defining delay slots required for a machine.
9942 * Processor pipeline description:: Specifying information for insn scheduling.
9943 @end menu
9945 @end ifset
9946 @ifset INTERNALS
9947 @node Defining Attributes
9948 @subsection Defining Attributes and their Values
9949 @cindex defining attributes and their values
9950 @cindex attributes, defining
9952 @findex define_attr
9953 The @code{define_attr} expression is used to define each attribute required
9954 by the target machine.  It looks like:
9956 @smallexample
9957 (define_attr @var{name} @var{list-of-values} @var{default})
9958 @end smallexample
9960 @var{name} is a string specifying the name of the attribute being
9961 defined.  Some attributes are used in a special way by the rest of the
9962 compiler. The @code{enabled} attribute can be used to conditionally
9963 enable or disable insn alternatives (@pxref{Disable Insn
9964 Alternatives}). The @code{predicable} attribute, together with a
9965 suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can
9966 be used to automatically generate conditional variants of instruction
9967 patterns. The @code{mnemonic} attribute can be used to check for the
9968 instruction mnemonic (@pxref{Mnemonic Attribute}).  The compiler
9969 internally uses the names @code{ce_enabled} and @code{nonce_enabled},
9970 so they should not be used elsewhere as alternative names.
9972 @var{list-of-values} is either a string that specifies a comma-separated
9973 list of values that can be assigned to the attribute, or a null string to
9974 indicate that the attribute takes numeric values.
9976 @var{default} is an attribute expression that gives the value of this
9977 attribute for insns that match patterns whose definition does not include
9978 an explicit value for this attribute.  @xref{Attr Example}, for more
9979 information on the handling of defaults.  @xref{Constant Attributes},
9980 for information on attributes that do not depend on any particular insn.
9982 @findex insn-attr.h
9983 For each defined attribute, a number of definitions are written to the
9984 @file{insn-attr.h} file.  For cases where an explicit set of values is
9985 specified for an attribute, the following are defined:
9987 @itemize @bullet
9988 @item
9989 A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
9991 @item
9992 An enumerated class is defined for @samp{attr_@var{name}} with
9993 elements of the form @samp{@var{upper-name}_@var{upper-value}} where
9994 the attribute name and value are first converted to uppercase.
9996 @item
9997 A function @samp{get_attr_@var{name}} is defined that is passed an insn and
9998 returns the attribute value for that insn.
9999 @end itemize
10001 For example, if the following is present in the @file{md} file:
10003 @smallexample
10004 (define_attr "type" "branch,fp,load,store,arith" @dots{})
10005 @end smallexample
10007 @noindent
10008 the following lines will be written to the file @file{insn-attr.h}.
10010 @smallexample
10011 #define HAVE_ATTR_type 1
10012 enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
10013                  TYPE_STORE, TYPE_ARITH@};
10014 extern enum attr_type get_attr_type ();
10015 @end smallexample
10017 If the attribute takes numeric values, no @code{enum} type will be
10018 defined and the function to obtain the attribute's value will return
10019 @code{int}.
10021 There are attributes which are tied to a specific meaning.  These
10022 attributes are not free to use for other purposes:
10024 @table @code
10025 @item length
10026 The @code{length} attribute is used to calculate the length of emitted
10027 code chunks.  This is especially important when verifying branch
10028 distances. @xref{Insn Lengths}.
10030 @item enabled
10031 The @code{enabled} attribute can be defined to prevent certain
10032 alternatives of an insn definition from being used during code
10033 generation. @xref{Disable Insn Alternatives}.
10035 @item mnemonic
10036 The @code{mnemonic} attribute can be defined to implement instruction
10037 specific checks in e.g.@: the pipeline description.
10038 @xref{Mnemonic Attribute}.
10039 @end table
10041 For each of these special attributes, the corresponding
10042 @samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the
10043 attribute is not defined; in that case, it is defined as @samp{0}.
10045 @findex define_enum_attr
10046 @anchor{define_enum_attr}
10047 Another way of defining an attribute is to use:
10049 @smallexample
10050 (define_enum_attr "@var{attr}" "@var{enum}" @var{default})
10051 @end smallexample
10053 This works in just the same way as @code{define_attr}, except that
10054 the list of values is taken from a separate enumeration called
10055 @var{enum} (@pxref{define_enum}).  This form allows you to use
10056 the same list of values for several attributes without having to
10057 repeat the list each time.  For example:
10059 @smallexample
10060 (define_enum "processor" [
10061   model_a
10062   model_b
10063   @dots{}
10065 (define_enum_attr "arch" "processor"
10066   (const (symbol_ref "target_arch")))
10067 (define_enum_attr "tune" "processor"
10068   (const (symbol_ref "target_tune")))
10069 @end smallexample
10071 defines the same attributes as:
10073 @smallexample
10074 (define_attr "arch" "model_a,model_b,@dots{}"
10075   (const (symbol_ref "target_arch")))
10076 (define_attr "tune" "model_a,model_b,@dots{}"
10077   (const (symbol_ref "target_tune")))
10078 @end smallexample
10080 but without duplicating the processor list.  The second example defines two
10081 separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
10082 defines a single C enum (@code{processor}).
10083 @end ifset
10084 @ifset INTERNALS
10085 @node Expressions
10086 @subsection Attribute Expressions
10087 @cindex attribute expressions
10089 RTL expressions used to define attributes use the codes described above
10090 plus a few specific to attribute definitions, to be discussed below.
10091 Attribute value expressions must have one of the following forms:
10093 @table @code
10094 @cindex @code{const_int} and attributes
10095 @item (const_int @var{i})
10096 The integer @var{i} specifies the value of a numeric attribute.  @var{i}
10097 must be non-negative.
10099 The value of a numeric attribute can be specified either with a
10100 @code{const_int}, or as an integer represented as a string in
10101 @code{const_string}, @code{eq_attr} (see below), @code{attr},
10102 @code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
10103 overrides on specific instructions (@pxref{Tagging Insns}).
10105 @cindex @code{const_string} and attributes
10106 @item (const_string @var{value})
10107 The string @var{value} specifies a constant attribute value.
10108 If @var{value} is specified as @samp{"*"}, it means that the default value of
10109 the attribute is to be used for the insn containing this expression.
10110 @samp{"*"} obviously cannot be used in the @var{default} expression
10111 of a @code{define_attr}.
10113 If the attribute whose value is being specified is numeric, @var{value}
10114 must be a string containing a non-negative integer (normally
10115 @code{const_int} would be used in this case).  Otherwise, it must
10116 contain one of the valid values for the attribute.
10118 @cindex @code{if_then_else} and attributes
10119 @item (if_then_else @var{test} @var{true-value} @var{false-value})
10120 @var{test} specifies an attribute test, whose format is defined below.
10121 The value of this expression is @var{true-value} if @var{test} is true,
10122 otherwise it is @var{false-value}.
10124 @cindex @code{cond} and attributes
10125 @item (cond [@var{test1} @var{value1} @dots{}] @var{default})
10126 The first operand of this expression is a vector containing an even
10127 number of expressions and consisting of pairs of @var{test} and @var{value}
10128 expressions.  The value of the @code{cond} expression is that of the
10129 @var{value} corresponding to the first true @var{test} expression.  If
10130 none of the @var{test} expressions are true, the value of the @code{cond}
10131 expression is that of the @var{default} expression.
10132 @end table
10134 @var{test} expressions can have one of the following forms:
10136 @table @code
10137 @cindex @code{const_int} and attribute tests
10138 @item (const_int @var{i})
10139 This test is true if @var{i} is nonzero and false otherwise.
10141 @cindex @code{not} and attributes
10142 @cindex @code{ior} and attributes
10143 @cindex @code{and} and attributes
10144 @item (not @var{test})
10145 @itemx (ior @var{test1} @var{test2})
10146 @itemx (and @var{test1} @var{test2})
10147 These tests are true if the indicated logical function is true.
10149 @cindex @code{match_operand} and attributes
10150 @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
10151 This test is true if operand @var{n} of the insn whose attribute value
10152 is being determined has mode @var{m} (this part of the test is ignored
10153 if @var{m} is @code{VOIDmode}) and the function specified by the string
10154 @var{pred} returns a nonzero value when passed operand @var{n} and mode
10155 @var{m} (this part of the test is ignored if @var{pred} is the null
10156 string).
10158 The @var{constraints} operand is ignored and should be the null string.
10160 @cindex @code{match_test} and attributes
10161 @item (match_test @var{c-expr})
10162 The test is true if C expression @var{c-expr} is true.  In non-constant
10163 attributes, @var{c-expr} has access to the following variables:
10165 @table @var
10166 @item insn
10167 The rtl instruction under test.
10168 @item which_alternative
10169 The @code{define_insn} alternative that @var{insn} matches.
10170 @xref{Output Statement}.
10171 @item operands
10172 An array of @var{insn}'s rtl operands.
10173 @end table
10175 @var{c-expr} behaves like the condition in a C @code{if} statement,
10176 so there is no need to explicitly convert the expression into a boolean
10177 0 or 1 value.  For example, the following two tests are equivalent:
10179 @smallexample
10180 (match_test "x & 2")
10181 (match_test "(x & 2) != 0")
10182 @end smallexample
10184 @cindex @code{le} and attributes
10185 @cindex @code{leu} and attributes
10186 @cindex @code{lt} and attributes
10187 @cindex @code{gt} and attributes
10188 @cindex @code{gtu} and attributes
10189 @cindex @code{ge} and attributes
10190 @cindex @code{geu} and attributes
10191 @cindex @code{ne} and attributes
10192 @cindex @code{eq} and attributes
10193 @cindex @code{plus} and attributes
10194 @cindex @code{minus} and attributes
10195 @cindex @code{mult} and attributes
10196 @cindex @code{div} and attributes
10197 @cindex @code{mod} and attributes
10198 @cindex @code{abs} and attributes
10199 @cindex @code{neg} and attributes
10200 @cindex @code{ashift} and attributes
10201 @cindex @code{lshiftrt} and attributes
10202 @cindex @code{ashiftrt} and attributes
10203 @item (le @var{arith1} @var{arith2})
10204 @itemx (leu @var{arith1} @var{arith2})
10205 @itemx (lt @var{arith1} @var{arith2})
10206 @itemx (ltu @var{arith1} @var{arith2})
10207 @itemx (gt @var{arith1} @var{arith2})
10208 @itemx (gtu @var{arith1} @var{arith2})
10209 @itemx (ge @var{arith1} @var{arith2})
10210 @itemx (geu @var{arith1} @var{arith2})
10211 @itemx (ne @var{arith1} @var{arith2})
10212 @itemx (eq @var{arith1} @var{arith2})
10213 These tests are true if the indicated comparison of the two arithmetic
10214 expressions is true.  Arithmetic expressions are formed with
10215 @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
10216 @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
10217 @code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.
10219 @findex get_attr
10220 @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
10221 Lengths},for additional forms).  @code{symbol_ref} is a string
10222 denoting a C expression that yields an @code{int} when evaluated by the
10223 @samp{get_attr_@dots{}} routine.  It should normally be a global
10224 variable.
10226 @findex eq_attr
10227 @item (eq_attr @var{name} @var{value})
10228 @var{name} is a string specifying the name of an attribute.
10230 @var{value} is a string that is either a valid value for attribute
10231 @var{name}, a comma-separated list of values, or @samp{!} followed by a
10232 value or list.  If @var{value} does not begin with a @samp{!}, this
10233 test is true if the value of the @var{name} attribute of the current
10234 insn is in the list specified by @var{value}.  If @var{value} begins
10235 with a @samp{!}, this test is true if the attribute's value is
10236 @emph{not} in the specified list.
10238 For example,
10240 @smallexample
10241 (eq_attr "type" "load,store")
10242 @end smallexample
10244 @noindent
10245 is equivalent to
10247 @smallexample
10248 (ior (eq_attr "type" "load") (eq_attr "type" "store"))
10249 @end smallexample
10251 If @var{name} specifies an attribute of @samp{alternative}, it refers to the
10252 value of the compiler variable @code{which_alternative}
10253 (@pxref{Output Statement}) and the values must be small integers.  For
10254 example,
10256 @smallexample
10257 (eq_attr "alternative" "2,3")
10258 @end smallexample
10260 @noindent
10261 is equivalent to
10263 @smallexample
10264 (ior (eq (symbol_ref "which_alternative") (const_int 2))
10265      (eq (symbol_ref "which_alternative") (const_int 3)))
10266 @end smallexample
10268 Note that, for most attributes, an @code{eq_attr} test is simplified in cases
10269 where the value of the attribute being tested is known for all insns matching
10270 a particular pattern.  This is by far the most common case.
10272 @findex attr_flag
10273 @item (attr_flag @var{name})
10274 The value of an @code{attr_flag} expression is true if the flag
10275 specified by @var{name} is true for the @code{insn} currently being
10276 scheduled.
10278 @var{name} is a string specifying one of a fixed set of flags to test.
10279 Test the flags @code{forward} and @code{backward} to determine the
10280 direction of a conditional branch.
10282 This example describes a conditional branch delay slot which
10283 can be nullified for forward branches that are taken (annul-true) or
10284 for backward branches which are not taken (annul-false).
10286 @smallexample
10287 (define_delay (eq_attr "type" "cbranch")
10288   [(eq_attr "in_branch_delay" "true")
10289    (and (eq_attr "in_branch_delay" "true")
10290         (attr_flag "forward"))
10291    (and (eq_attr "in_branch_delay" "true")
10292         (attr_flag "backward"))])
10293 @end smallexample
10295 The @code{forward} and @code{backward} flags are false if the current
10296 @code{insn} being scheduled is not a conditional branch.
10298 @code{attr_flag} is only used during delay slot scheduling and has no
10299 meaning to other passes of the compiler.
10301 @findex attr
10302 @item (attr @var{name})
10303 The value of another attribute is returned.  This is most useful
10304 for numeric attributes, as @code{eq_attr} and @code{attr_flag}
10305 produce more efficient code for non-numeric attributes.
10306 @end table
10308 @end ifset
10309 @ifset INTERNALS
10310 @node Tagging Insns
10311 @subsection Assigning Attribute Values to Insns
10312 @cindex tagging insns
10313 @cindex assigning attribute values to insns
10315 The value assigned to an attribute of an insn is primarily determined by
10316 which pattern is matched by that insn (or which @code{define_peephole}
10317 generated it).  Every @code{define_insn} and @code{define_peephole} can
10318 have an optional last argument to specify the values of attributes for
10319 matching insns.  The value of any attribute not specified in a particular
10320 insn is set to the default value for that attribute, as specified in its
10321 @code{define_attr}.  Extensive use of default values for attributes
10322 permits the specification of the values for only one or two attributes
10323 in the definition of most insn patterns, as seen in the example in the
10324 next section.
10326 The optional last argument of @code{define_insn} and
10327 @code{define_peephole} is a vector of expressions, each of which defines
10328 the value for a single attribute.  The most general way of assigning an
10329 attribute's value is to use a @code{set} expression whose first operand is an
10330 @code{attr} expression giving the name of the attribute being set.  The
10331 second operand of the @code{set} is an attribute expression
10332 (@pxref{Expressions}) giving the value of the attribute.
10334 When the attribute value depends on the @samp{alternative} attribute
10335 (i.e., which is the applicable alternative in the constraint of the
10336 insn), the @code{set_attr_alternative} expression can be used.  It
10337 allows the specification of a vector of attribute expressions, one for
10338 each alternative.
10340 @findex set_attr
10341 When the generality of arbitrary attribute expressions is not required,
10342 the simpler @code{set_attr} expression can be used, which allows
10343 specifying a string giving either a single attribute value or a list
10344 of attribute values, one for each alternative.
10346 The form of each of the above specifications is shown below.  In each case,
10347 @var{name} is a string specifying the attribute to be set.
10349 @table @code
10350 @item (set_attr @var{name} @var{value-string})
10351 @var{value-string} is either a string giving the desired attribute value,
10352 or a string containing a comma-separated list giving the values for
10353 succeeding alternatives.  The number of elements must match the number
10354 of alternatives in the constraint of the insn pattern.
10356 Note that it may be useful to specify @samp{*} for some alternative, in
10357 which case the attribute will assume its default value for insns matching
10358 that alternative.
10360 @findex set_attr_alternative
10361 @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
10362 Depending on the alternative of the insn, the value will be one of the
10363 specified values.  This is a shorthand for using a @code{cond} with
10364 tests on the @samp{alternative} attribute.
10366 @findex attr
10367 @item (set (attr @var{name}) @var{value})
10368 The first operand of this @code{set} must be the special RTL expression
10369 @code{attr}, whose sole operand is a string giving the name of the
10370 attribute being set.  @var{value} is the value of the attribute.
10371 @end table
10373 The following shows three different ways of representing the same
10374 attribute value specification:
10376 @smallexample
10377 (set_attr "type" "load,store,arith")
10379 (set_attr_alternative "type"
10380                       [(const_string "load") (const_string "store")
10381                        (const_string "arith")])
10383 (set (attr "type")
10384      (cond [(eq_attr "alternative" "1") (const_string "load")
10385             (eq_attr "alternative" "2") (const_string "store")]
10386            (const_string "arith")))
10387 @end smallexample
10389 @need 1000
10390 @findex define_asm_attributes
10391 The @code{define_asm_attributes} expression provides a mechanism to
10392 specify the attributes assigned to insns produced from an @code{asm}
10393 statement.  It has the form:
10395 @smallexample
10396 (define_asm_attributes [@var{attr-sets}])
10397 @end smallexample
10399 @noindent
10400 where @var{attr-sets} is specified the same as for both the
10401 @code{define_insn} and the @code{define_peephole} expressions.
10403 These values will typically be the ``worst case'' attribute values.  For
10404 example, they might indicate that the condition code will be clobbered.
10406 A specification for a @code{length} attribute is handled specially.  The
10407 way to compute the length of an @code{asm} insn is to multiply the
10408 length specified in the expression @code{define_asm_attributes} by the
10409 number of machine instructions specified in the @code{asm} statement,
10410 determined by counting the number of semicolons and newlines in the
10411 string.  Therefore, the value of the @code{length} attribute specified
10412 in a @code{define_asm_attributes} should be the maximum possible length
10413 of a single machine instruction.
10415 @end ifset
10416 @ifset INTERNALS
10417 @node Attr Example
10418 @subsection Example of Attribute Specifications
10419 @cindex attribute specifications example
10420 @cindex attribute specifications
10422 The judicious use of defaulting is important in the efficient use of
10423 insn attributes.  Typically, insns are divided into @dfn{types} and an
10424 attribute, customarily called @code{type}, is used to represent this
10425 value.  This attribute is normally used only to define the default value
10426 for other attributes.  An example will clarify this usage.
10428 Assume we have a RISC machine with a condition code and in which only
10429 full-word operations are performed in registers.  Let us assume that we
10430 can divide all insns into loads, stores, (integer) arithmetic
10431 operations, floating point operations, and branches.
10433 Here we will concern ourselves with determining the effect of an insn on
10434 the condition code and will limit ourselves to the following possible
10435 effects:  The condition code can be set unpredictably (clobbered), not
10436 be changed, be set to agree with the results of the operation, or only
10437 changed if the item previously set into the condition code has been
10438 modified.
10440 Here is part of a sample @file{md} file for such a machine:
10442 @smallexample
10443 (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
10445 (define_attr "cc" "clobber,unchanged,set,change0"
10446              (cond [(eq_attr "type" "load")
10447                         (const_string "change0")
10448                     (eq_attr "type" "store,branch")
10449                         (const_string "unchanged")
10450                     (eq_attr "type" "arith")
10451                         (if_then_else (match_operand:SI 0 "" "")
10452                                       (const_string "set")
10453                                       (const_string "clobber"))]
10454                    (const_string "clobber")))
10456 (define_insn ""
10457   [(set (match_operand:SI 0 "general_operand" "=r,r,m")
10458         (match_operand:SI 1 "general_operand" "r,m,r"))]
10459   ""
10460   "@@
10461    move %0,%1
10462    load %0,%1
10463    store %0,%1"
10464   [(set_attr "type" "arith,load,store")])
10465 @end smallexample
10467 Note that we assume in the above example that arithmetic operations
10468 performed on quantities smaller than a machine word clobber the condition
10469 code since they will set the condition code to a value corresponding to the
10470 full-word result.
10472 @end ifset
10473 @ifset INTERNALS
10474 @node Insn Lengths
10475 @subsection Computing the Length of an Insn
10476 @cindex insn lengths, computing
10477 @cindex computing the length of an insn
10479 For many machines, multiple types of branch instructions are provided, each
10480 for different length branch displacements.  In most cases, the assembler
10481 will choose the correct instruction to use.  However, when the assembler
10482 cannot do so, GCC can when a special attribute, the @code{length}
10483 attribute, is defined.  This attribute must be defined to have numeric
10484 values by specifying a null string in its @code{define_attr}.
10486 In the case of the @code{length} attribute, two additional forms of
10487 arithmetic terms are allowed in test expressions:
10489 @table @code
10490 @cindex @code{match_dup} and attributes
10491 @item (match_dup @var{n})
10492 This refers to the address of operand @var{n} of the current insn, which
10493 must be a @code{label_ref}.
10495 @cindex @code{pc} and attributes
10496 @item (pc)
10497 For non-branch instructions and backward branch instructions, this refers
10498 to the address of the current insn.  But for forward branch instructions,
10499 this refers to the address of the next insn, because the length of the
10500 current insn is to be computed.
10501 @end table
10503 @cindex @code{addr_vec}, length of
10504 @cindex @code{addr_diff_vec}, length of
10505 For normal insns, the length will be determined by value of the
10506 @code{length} attribute.  In the case of @code{addr_vec} and
10507 @code{addr_diff_vec} insn patterns, the length is computed as
10508 the number of vectors multiplied by the size of each vector.
10510 Lengths are measured in addressable storage units (bytes).
10512 Note that it is possible to call functions via the @code{symbol_ref}
10513 mechanism to compute the length of an insn.  However, if you use this
10514 mechanism you must provide dummy clauses to express the maximum length
10515 without using the function call.  You can see an example of this in the
10516 @code{pa} machine description for the @code{call_symref} pattern.
10518 The following macros can be used to refine the length computation:
10520 @table @code
10521 @findex ADJUST_INSN_LENGTH
10522 @item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
10523 If defined, modifies the length assigned to instruction @var{insn} as a
10524 function of the context in which it is used.  @var{length} is an lvalue
10525 that contains the initially computed length of the insn and should be
10526 updated with the correct length of the insn.
10528 This macro will normally not be required.  A case in which it is
10529 required is the ROMP@.  On this machine, the size of an @code{addr_vec}
10530 insn must be increased by two to compensate for the fact that alignment
10531 may be required.
10532 @end table
10534 @findex get_attr_length
10535 The routine that returns @code{get_attr_length} (the value of the
10536 @code{length} attribute) can be used by the output routine to
10537 determine the form of the branch instruction to be written, as the
10538 example below illustrates.
10540 As an example of the specification of variable-length branches, consider
10541 the IBM 360.  If we adopt the convention that a register will be set to
10542 the starting address of a function, we can jump to labels within 4k of
10543 the start using a four-byte instruction.  Otherwise, we need a six-byte
10544 sequence to load the address from memory and then branch to it.
10546 On such a machine, a pattern for a branch instruction might be specified
10547 as follows:
10549 @smallexample
10550 (define_insn "jump"
10551   [(set (pc)
10552         (label_ref (match_operand 0 "" "")))]
10553   ""
10555    return (get_attr_length (insn) == 4
10556            ? "b %l0" : "l r15,=a(%l0); br r15");
10558   [(set (attr "length")
10559         (if_then_else (lt (match_dup 0) (const_int 4096))
10560                       (const_int 4)
10561                       (const_int 6)))])
10562 @end smallexample
10564 @end ifset
10565 @ifset INTERNALS
10566 @node Constant Attributes
10567 @subsection Constant Attributes
10568 @cindex constant attributes
10570 A special form of @code{define_attr}, where the expression for the
10571 default value is a @code{const} expression, indicates an attribute that
10572 is constant for a given run of the compiler.  Constant attributes may be
10573 used to specify which variety of processor is used.  For example,
10575 @smallexample
10576 (define_attr "cpu" "m88100,m88110,m88000"
10577  (const
10578   (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
10579          (symbol_ref "TARGET_88110") (const_string "m88110")]
10580         (const_string "m88000"))))
10582 (define_attr "memory" "fast,slow"
10583  (const
10584   (if_then_else (symbol_ref "TARGET_FAST_MEM")
10585                 (const_string "fast")
10586                 (const_string "slow"))))
10587 @end smallexample
10589 The routine generated for constant attributes has no parameters as it
10590 does not depend on any particular insn.  RTL expressions used to define
10591 the value of a constant attribute may use the @code{symbol_ref} form,
10592 but may not use either the @code{match_operand} form or @code{eq_attr}
10593 forms involving insn attributes.
10595 @end ifset
10596 @ifset INTERNALS
10597 @node Mnemonic Attribute
10598 @subsection Mnemonic Attribute
10599 @cindex mnemonic attribute
10601 The @code{mnemonic} attribute is a string type attribute holding the
10602 instruction mnemonic for an insn alternative.  The attribute values
10603 will automatically be generated by the machine description parser if
10604 there is an attribute definition in the md file:
10606 @smallexample
10607 (define_attr "mnemonic" "unknown" (const_string "unknown"))
10608 @end smallexample
10610 The default value can be freely chosen as long as it does not collide
10611 with any of the instruction mnemonics.  This value will be used
10612 whenever the machine description parser is not able to determine the
10613 mnemonic string.  This might be the case for output templates
10614 containing more than a single instruction as in
10615 @code{"mvcle\t%0,%1,0\;jo\t.-4"}.
10617 The @code{mnemonic} attribute set is not generated automatically if the
10618 instruction string is generated via C code.
10620 An existing @code{mnemonic} attribute set in an insn definition will not
10621 be overriden by the md file parser.  That way it is possible to
10622 manually set the instruction mnemonics for the cases where the md file
10623 parser fails to determine it automatically.
10625 The @code{mnemonic} attribute is useful for dealing with instruction
10626 specific properties in the pipeline description without defining
10627 additional insn attributes.
10629 @smallexample
10630 (define_attr "ooo_expanded" ""
10631   (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
10632          (const_int 1)]
10633         (const_int 0)))
10634 @end smallexample
10636 @end ifset
10637 @ifset INTERNALS
10638 @node Delay Slots
10639 @subsection Delay Slot Scheduling
10640 @cindex delay slots, defining
10642 The insn attribute mechanism can be used to specify the requirements for
10643 delay slots, if any, on a target machine.  An instruction is said to
10644 require a @dfn{delay slot} if some instructions that are physically
10645 after the instruction are executed as if they were located before it.
10646 Classic examples are branch and call instructions, which often execute
10647 the following instruction before the branch or call is performed.
10649 On some machines, conditional branch instructions can optionally
10650 @dfn{annul} instructions in the delay slot.  This means that the
10651 instruction will not be executed for certain branch outcomes.  Both
10652 instructions that annul if the branch is true and instructions that
10653 annul if the branch is false are supported.
10655 Delay slot scheduling differs from instruction scheduling in that
10656 determining whether an instruction needs a delay slot is dependent only
10657 on the type of instruction being generated, not on data flow between the
10658 instructions.  See the next section for a discussion of data-dependent
10659 instruction scheduling.
10661 @findex define_delay
10662 The requirement of an insn needing one or more delay slots is indicated
10663 via the @code{define_delay} expression.  It has the following form:
10665 @smallexample
10666 (define_delay @var{test}
10667               [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
10668                @var{delay-2} @var{annul-true-2} @var{annul-false-2}
10669                @dots{}])
10670 @end smallexample
10672 @var{test} is an attribute test that indicates whether this
10673 @code{define_delay} applies to a particular insn.  If so, the number of
10674 required delay slots is determined by the length of the vector specified
10675 as the second argument.  An insn placed in delay slot @var{n} must
10676 satisfy attribute test @var{delay-n}.  @var{annul-true-n} is an
10677 attribute test that specifies which insns may be annulled if the branch
10678 is true.  Similarly, @var{annul-false-n} specifies which insns in the
10679 delay slot may be annulled if the branch is false.  If annulling is not
10680 supported for that delay slot, @code{(nil)} should be coded.
10682 For example, in the common case where branch and call insns require
10683 a single delay slot, which may contain any insn other than a branch or
10684 call, the following would be placed in the @file{md} file:
10686 @smallexample
10687 (define_delay (eq_attr "type" "branch,call")
10688               [(eq_attr "type" "!branch,call") (nil) (nil)])
10689 @end smallexample
10691 Multiple @code{define_delay} expressions may be specified.  In this
10692 case, each such expression specifies different delay slot requirements
10693 and there must be no insn for which tests in two @code{define_delay}
10694 expressions are both true.
10696 For example, if we have a machine that requires one delay slot for branches
10697 but two for calls,  no delay slot can contain a branch or call insn,
10698 and any valid insn in the delay slot for the branch can be annulled if the
10699 branch is true, we might represent this as follows:
10701 @smallexample
10702 (define_delay (eq_attr "type" "branch")
10703    [(eq_attr "type" "!branch,call")
10704     (eq_attr "type" "!branch,call")
10705     (nil)])
10707 (define_delay (eq_attr "type" "call")
10708               [(eq_attr "type" "!branch,call") (nil) (nil)
10709                (eq_attr "type" "!branch,call") (nil) (nil)])
10710 @end smallexample
10711 @c the above is *still* too long.  --mew 4feb93
10713 @end ifset
10714 @ifset INTERNALS
10715 @node Processor pipeline description
10716 @subsection Specifying processor pipeline description
10717 @cindex processor pipeline description
10718 @cindex processor functional units
10719 @cindex instruction latency time
10720 @cindex interlock delays
10721 @cindex data dependence delays
10722 @cindex reservation delays
10723 @cindex pipeline hazard recognizer
10724 @cindex automaton based pipeline description
10725 @cindex regular expressions
10726 @cindex deterministic finite state automaton
10727 @cindex automaton based scheduler
10728 @cindex RISC
10729 @cindex VLIW
10731 To achieve better performance, most modern processors
10732 (super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
10733 processors) have many @dfn{functional units} on which several
10734 instructions can be executed simultaneously.  An instruction starts
10735 execution if its issue conditions are satisfied.  If not, the
10736 instruction is stalled until its conditions are satisfied.  Such
10737 @dfn{interlock (pipeline) delay} causes interruption of the fetching
10738 of successor instructions (or demands nop instructions, e.g.@: for some
10739 MIPS processors).
10741 There are two major kinds of interlock delays in modern processors.
10742 The first one is a data dependence delay determining @dfn{instruction
10743 latency time}.  The instruction execution is not started until all
10744 source data have been evaluated by prior instructions (there are more
10745 complex cases when the instruction execution starts even when the data
10746 are not available but will be ready in given time after the
10747 instruction execution start).  Taking the data dependence delays into
10748 account is simple.  The data dependence (true, output, and
10749 anti-dependence) delay between two instructions is given by a
10750 constant.  In most cases this approach is adequate.  The second kind
10751 of interlock delays is a reservation delay.  The reservation delay
10752 means that two instructions under execution will be in need of shared
10753 processors resources, i.e.@: buses, internal registers, and/or
10754 functional units, which are reserved for some time.  Taking this kind
10755 of delay into account is complex especially for modern @acronym{RISC}
10756 processors.
10758 The task of exploiting more processor parallelism is solved by an
10759 instruction scheduler.  For a better solution to this problem, the
10760 instruction scheduler has to have an adequate description of the
10761 processor parallelism (or @dfn{pipeline description}).  GCC
10762 machine descriptions describe processor parallelism and functional
10763 unit reservations for groups of instructions with the aid of
10764 @dfn{regular expressions}.
10766 The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
10767 figure out the possibility of the instruction issue by the processor
10768 on a given simulated processor cycle.  The pipeline hazard recognizer is
10769 automatically generated from the processor pipeline description.  The
10770 pipeline hazard recognizer generated from the machine description
10771 is based on a deterministic finite state automaton (@acronym{DFA}):
10772 the instruction issue is possible if there is a transition from one
10773 automaton state to another one.  This algorithm is very fast, and
10774 furthermore, its speed is not dependent on processor
10775 complexity@footnote{However, the size of the automaton depends on
10776 processor complexity.  To limit this effect, machine descriptions
10777 can split orthogonal parts of the machine description among several
10778 automata: but then, since each of these must be stepped independently,
10779 this does cause a small decrease in the algorithm's performance.}.
10781 @cindex automaton based pipeline description
10782 The rest of this section describes the directives that constitute
10783 an automaton-based processor pipeline description.  The order of
10784 these constructions within the machine description file is not
10785 important.
10787 @findex define_automaton
10788 @cindex pipeline hazard recognizer
10789 The following optional construction describes names of automata
10790 generated and used for the pipeline hazards recognition.  Sometimes
10791 the generated finite state automaton used by the pipeline hazard
10792 recognizer is large.  If we use more than one automaton and bind functional
10793 units to the automata, the total size of the automata is usually
10794 less than the size of the single automaton.  If there is no one such
10795 construction, only one finite state automaton is generated.
10797 @smallexample
10798 (define_automaton @var{automata-names})
10799 @end smallexample
10801 @var{automata-names} is a string giving names of the automata.  The
10802 names are separated by commas.  All the automata should have unique names.
10803 The automaton name is used in the constructions @code{define_cpu_unit} and
10804 @code{define_query_cpu_unit}.
10806 @findex define_cpu_unit
10807 @cindex processor functional units
10808 Each processor functional unit used in the description of instruction
10809 reservations should be described by the following construction.
10811 @smallexample
10812 (define_cpu_unit @var{unit-names} [@var{automaton-name}])
10813 @end smallexample
10815 @var{unit-names} is a string giving the names of the functional units
10816 separated by commas.  Don't use name @samp{nothing}, it is reserved
10817 for other goals.
10819 @var{automaton-name} is a string giving the name of the automaton with
10820 which the unit is bound.  The automaton should be described in
10821 construction @code{define_automaton}.  You should give
10822 @dfn{automaton-name}, if there is a defined automaton.
10824 The assignment of units to automata are constrained by the uses of the
10825 units in insn reservations.  The most important constraint is: if a
10826 unit reservation is present on a particular cycle of an alternative
10827 for an insn reservation, then some unit from the same automaton must
10828 be present on the same cycle for the other alternatives of the insn
10829 reservation.  The rest of the constraints are mentioned in the
10830 description of the subsequent constructions.
10832 @findex define_query_cpu_unit
10833 @cindex querying function unit reservations
10834 The following construction describes CPU functional units analogously
10835 to @code{define_cpu_unit}.  The reservation of such units can be
10836 queried for an automaton state.  The instruction scheduler never
10837 queries reservation of functional units for given automaton state.  So
10838 as a rule, you don't need this construction.  This construction could
10839 be used for future code generation goals (e.g.@: to generate
10840 @acronym{VLIW} insn templates).
10842 @smallexample
10843 (define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
10844 @end smallexample
10846 @var{unit-names} is a string giving names of the functional units
10847 separated by commas.
10849 @var{automaton-name} is a string giving the name of the automaton with
10850 which the unit is bound.
10852 @findex define_insn_reservation
10853 @cindex instruction latency time
10854 @cindex regular expressions
10855 @cindex data bypass
10856 The following construction is the major one to describe pipeline
10857 characteristics of an instruction.
10859 @smallexample
10860 (define_insn_reservation @var{insn-name} @var{default_latency}
10861                          @var{condition} @var{regexp})
10862 @end smallexample
10864 @var{default_latency} is a number giving latency time of the
10865 instruction.  There is an important difference between the old
10866 description and the automaton based pipeline description.  The latency
10867 time is used for all dependencies when we use the old description.  In
10868 the automaton based pipeline description, the given latency time is only
10869 used for true dependencies.  The cost of anti-dependencies is always
10870 zero and the cost of output dependencies is the difference between
10871 latency times of the producing and consuming insns (if the difference
10872 is negative, the cost is considered to be zero).  You can always
10873 change the default costs for any description by using the target hook
10874 @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
10876 @var{insn-name} is a string giving the internal name of the insn.  The
10877 internal names are used in constructions @code{define_bypass} and in
10878 the automaton description file generated for debugging.  The internal
10879 name has nothing in common with the names in @code{define_insn}.  It is a
10880 good practice to use insn classes described in the processor manual.
10882 @var{condition} defines what RTL insns are described by this
10883 construction.  You should remember that you will be in trouble if
10884 @var{condition} for two or more different
10885 @code{define_insn_reservation} constructions is TRUE for an insn.  In
10886 this case what reservation will be used for the insn is not defined.
10887 Such cases are not checked during generation of the pipeline hazards
10888 recognizer because in general recognizing that two conditions may have
10889 the same value is quite difficult (especially if the conditions
10890 contain @code{symbol_ref}).  It is also not checked during the
10891 pipeline hazard recognizer work because it would slow down the
10892 recognizer considerably.
10894 @var{regexp} is a string describing the reservation of the cpu's functional
10895 units by the instruction.  The reservations are described by a regular
10896 expression according to the following syntax:
10898 @smallexample
10899        regexp = regexp "," oneof
10900               | oneof
10902        oneof = oneof "|" allof
10903              | allof
10905        allof = allof "+" repeat
10906              | repeat
10908        repeat = element "*" number
10909               | element
10911        element = cpu_function_unit_name
10912                | reservation_name
10913                | result_name
10914                | "nothing"
10915                | "(" regexp ")"
10916 @end smallexample
10918 @itemize @bullet
10919 @item
10920 @samp{,} is used for describing the start of the next cycle in
10921 the reservation.
10923 @item
10924 @samp{|} is used for describing a reservation described by the first
10925 regular expression @strong{or} a reservation described by the second
10926 regular expression @strong{or} etc.
10928 @item
10929 @samp{+} is used for describing a reservation described by the first
10930 regular expression @strong{and} a reservation described by the
10931 second regular expression @strong{and} etc.
10933 @item
10934 @samp{*} is used for convenience and simply means a sequence in which
10935 the regular expression are repeated @var{number} times with cycle
10936 advancing (see @samp{,}).
10938 @item
10939 @samp{cpu_function_unit_name} denotes reservation of the named
10940 functional unit.
10942 @item
10943 @samp{reservation_name} --- see description of construction
10944 @samp{define_reservation}.
10946 @item
10947 @samp{nothing} denotes no unit reservations.
10948 @end itemize
10950 @findex define_reservation
10951 Sometimes unit reservations for different insns contain common parts.
10952 In such case, you can simplify the pipeline description by describing
10953 the common part by the following construction
10955 @smallexample
10956 (define_reservation @var{reservation-name} @var{regexp})
10957 @end smallexample
10959 @var{reservation-name} is a string giving name of @var{regexp}.
10960 Functional unit names and reservation names are in the same name
10961 space.  So the reservation names should be different from the
10962 functional unit names and cannot be the reserved name @samp{nothing}.
10964 @findex define_bypass
10965 @cindex instruction latency time
10966 @cindex data bypass
10967 The following construction is used to describe exceptions in the
10968 latency time for given instruction pair.  This is so called bypasses.
10970 @smallexample
10971 (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
10972                [@var{guard}])
10973 @end smallexample
10975 @var{number} defines when the result generated by the instructions
10976 given in string @var{out_insn_names} will be ready for the
10977 instructions given in string @var{in_insn_names}.  Each of these
10978 strings is a comma-separated list of filename-style globs and
10979 they refer to the names of @code{define_insn_reservation}s.
10980 For example:
10981 @smallexample
10982 (define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
10983 @end smallexample
10984 defines a bypass between instructions that start with
10985 @samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
10986 @samp{cpu1_load_}.
10988 @var{guard} is an optional string giving the name of a C function which
10989 defines an additional guard for the bypass.  The function will get the
10990 two insns as parameters.  If the function returns zero the bypass will
10991 be ignored for this case.  The additional guard is necessary to
10992 recognize complicated bypasses, e.g.@: when the consumer is only an address
10993 of insn @samp{store} (not a stored value).
10995 If there are more one bypass with the same output and input insns, the
10996 chosen bypass is the first bypass with a guard in description whose
10997 guard function returns nonzero.  If there is no such bypass, then
10998 bypass without the guard function is chosen.
11000 @findex exclusion_set
11001 @findex presence_set
11002 @findex final_presence_set
11003 @findex absence_set
11004 @findex final_absence_set
11005 @cindex VLIW
11006 @cindex RISC
11007 The following five constructions are usually used to describe
11008 @acronym{VLIW} processors, or more precisely, to describe a placement
11009 of small instructions into @acronym{VLIW} instruction slots.  They
11010 can be used for @acronym{RISC} processors, too.
11012 @smallexample
11013 (exclusion_set @var{unit-names} @var{unit-names})
11014 (presence_set @var{unit-names} @var{patterns})
11015 (final_presence_set @var{unit-names} @var{patterns})
11016 (absence_set @var{unit-names} @var{patterns})
11017 (final_absence_set @var{unit-names} @var{patterns})
11018 @end smallexample
11020 @var{unit-names} is a string giving names of functional units
11021 separated by commas.
11023 @var{patterns} is a string giving patterns of functional units
11024 separated by comma.  Currently pattern is one unit or units
11025 separated by white-spaces.
11027 The first construction (@samp{exclusion_set}) means that each
11028 functional unit in the first string cannot be reserved simultaneously
11029 with a unit whose name is in the second string and vice versa.  For
11030 example, the construction is useful for describing processors
11031 (e.g.@: some SPARC processors) with a fully pipelined floating point
11032 functional unit which can execute simultaneously only single floating
11033 point insns or only double floating point insns.
11035 The second construction (@samp{presence_set}) means that each
11036 functional unit in the first string cannot be reserved unless at
11037 least one of pattern of units whose names are in the second string is
11038 reserved.  This is an asymmetric relation.  For example, it is useful
11039 for description that @acronym{VLIW} @samp{slot1} is reserved after
11040 @samp{slot0} reservation.  We could describe it by the following
11041 construction
11043 @smallexample
11044 (presence_set "slot1" "slot0")
11045 @end smallexample
11047 Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
11048 reservation.  In this case we could write
11050 @smallexample
11051 (presence_set "slot1" "slot0 b0")
11052 @end smallexample
11054 The third construction (@samp{final_presence_set}) is analogous to
11055 @samp{presence_set}.  The difference between them is when checking is
11056 done.  When an instruction is issued in given automaton state
11057 reflecting all current and planned unit reservations, the automaton
11058 state is changed.  The first state is a source state, the second one
11059 is a result state.  Checking for @samp{presence_set} is done on the
11060 source state reservation, checking for @samp{final_presence_set} is
11061 done on the result reservation.  This construction is useful to
11062 describe a reservation which is actually two subsequent reservations.
11063 For example, if we use
11065 @smallexample
11066 (presence_set "slot1" "slot0")
11067 @end smallexample
11069 the following insn will be never issued (because @samp{slot1} requires
11070 @samp{slot0} which is absent in the source state).
11072 @smallexample
11073 (define_reservation "insn_and_nop" "slot0 + slot1")
11074 @end smallexample
11076 but it can be issued if we use analogous @samp{final_presence_set}.
11078 The forth construction (@samp{absence_set}) means that each functional
11079 unit in the first string can be reserved only if each pattern of units
11080 whose names are in the second string is not reserved.  This is an
11081 asymmetric relation (actually @samp{exclusion_set} is analogous to
11082 this one but it is symmetric).  For example it might be useful in a
11083 @acronym{VLIW} description to say that @samp{slot0} cannot be reserved
11084 after either @samp{slot1} or @samp{slot2} have been reserved.  This
11085 can be described as:
11087 @smallexample
11088 (absence_set "slot0" "slot1, slot2")
11089 @end smallexample
11091 Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0}
11092 are reserved or @samp{slot1} and unit @samp{b1} are reserved.  In
11093 this case we could write
11095 @smallexample
11096 (absence_set "slot2" "slot0 b0, slot1 b1")
11097 @end smallexample
11099 All functional units mentioned in a set should belong to the same
11100 automaton.
11102 The last construction (@samp{final_absence_set}) is analogous to
11103 @samp{absence_set} but checking is done on the result (state)
11104 reservation.  See comments for @samp{final_presence_set}.
11106 @findex automata_option
11107 @cindex deterministic finite state automaton
11108 @cindex nondeterministic finite state automaton
11109 @cindex finite state automaton minimization
11110 You can control the generator of the pipeline hazard recognizer with
11111 the following construction.
11113 @smallexample
11114 (automata_option @var{options})
11115 @end smallexample
11117 @var{options} is a string giving options which affect the generated
11118 code.  Currently there are the following options:
11120 @itemize @bullet
11121 @item
11122 @dfn{no-minimization} makes no minimization of the automaton.  This is
11123 only worth to do when we are debugging the description and need to
11124 look more accurately at reservations of states.
11126 @item
11127 @dfn{time} means printing time statistics about the generation of
11128 automata.
11130 @item
11131 @dfn{stats} means printing statistics about the generated automata
11132 such as the number of DFA states, NDFA states and arcs.
11134 @item
11135 @dfn{v} means a generation of the file describing the result automata.
11136 The file has suffix @samp{.dfa} and can be used for the description
11137 verification and debugging.
11139 @item
11140 @dfn{w} means a generation of warning instead of error for
11141 non-critical errors.
11143 @item
11144 @dfn{no-comb-vect} prevents the automaton generator from generating
11145 two data structures and comparing them for space efficiency.  Using
11146 a comb vector to represent transitions may be better, but it can be
11147 very expensive to construct.  This option is useful if the build
11148 process spends an unacceptably long time in genautomata.
11150 @item
11151 @dfn{ndfa} makes nondeterministic finite state automata.  This affects
11152 the treatment of operator @samp{|} in the regular expressions.  The
11153 usual treatment of the operator is to try the first alternative and,
11154 if the reservation is not possible, the second alternative.  The
11155 nondeterministic treatment means trying all alternatives, some of them
11156 may be rejected by reservations in the subsequent insns.
11158 @item
11159 @dfn{collapse-ndfa} modifies the behavior of the generator when
11160 producing an automaton.  An additional state transition to collapse a
11161 nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
11162 state is generated.  It can be triggered by passing @code{const0_rtx} to
11163 state_transition.  In such an automaton, cycle advance transitions are
11164 available only for these collapsed states.  This option is useful for
11165 ports that want to use the @code{ndfa} option, but also want to use
11166 @code{define_query_cpu_unit} to assign units to insns issued in a cycle.
11168 @item
11169 @dfn{progress} means output of a progress bar showing how many states
11170 were generated so far for automaton being processed.  This is useful
11171 during debugging a @acronym{DFA} description.  If you see too many
11172 generated states, you could interrupt the generator of the pipeline
11173 hazard recognizer and try to figure out a reason for generation of the
11174 huge automaton.
11175 @end itemize
11177 As an example, consider a superscalar @acronym{RISC} machine which can
11178 issue three insns (two integer insns and one floating point insn) on
11179 the cycle but can finish only two insns.  To describe this, we define
11180 the following functional units.
11182 @smallexample
11183 (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
11184 (define_cpu_unit "port0, port1")
11185 @end smallexample
11187 All simple integer insns can be executed in any integer pipeline and
11188 their result is ready in two cycles.  The simple integer insns are
11189 issued into the first pipeline unless it is reserved, otherwise they
11190 are issued into the second pipeline.  Integer division and
11191 multiplication insns can be executed only in the second integer
11192 pipeline and their results are ready correspondingly in 9 and 4
11193 cycles.  The integer division is not pipelined, i.e.@: the subsequent
11194 integer division insn cannot be issued until the current division
11195 insn finished.  Floating point insns are fully pipelined and their
11196 results are ready in 3 cycles.  Where the result of a floating point
11197 insn is used by an integer insn, an additional delay of one cycle is
11198 incurred.  To describe all of this we could specify
11200 @smallexample
11201 (define_cpu_unit "div")
11203 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
11204                          "(i0_pipeline | i1_pipeline), (port0 | port1)")
11206 (define_insn_reservation "mult" 4 (eq_attr "type" "mult")
11207                          "i1_pipeline, nothing*2, (port0 | port1)")
11209 (define_insn_reservation "div" 9 (eq_attr "type" "div")
11210                          "i1_pipeline, div*7, div + (port0 | port1)")
11212 (define_insn_reservation "float" 3 (eq_attr "type" "float")
11213                          "f_pipeline, nothing, (port0 | port1))
11215 (define_bypass 4 "float" "simple,mult,div")
11216 @end smallexample
11218 To simplify the description we could describe the following reservation
11220 @smallexample
11221 (define_reservation "finish" "port0|port1")
11222 @end smallexample
11224 and use it in all @code{define_insn_reservation} as in the following
11225 construction
11227 @smallexample
11228 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
11229                          "(i0_pipeline | i1_pipeline), finish")
11230 @end smallexample
11233 @end ifset
11234 @ifset INTERNALS
11235 @node Conditional Execution
11236 @section Conditional Execution
11237 @cindex conditional execution
11238 @cindex predication
11240 A number of architectures provide for some form of conditional
11241 execution, or predication.  The hallmark of this feature is the
11242 ability to nullify most of the instructions in the instruction set.
11243 When the instruction set is large and not entirely symmetric, it
11244 can be quite tedious to describe these forms directly in the
11245 @file{.md} file.  An alternative is the @code{define_cond_exec} template.
11247 @findex define_cond_exec
11248 @smallexample
11249 (define_cond_exec
11250   [@var{predicate-pattern}]
11251   "@var{condition}"
11252   "@var{output-template}"
11253   "@var{optional-insn-attribues}")
11254 @end smallexample
11256 @var{predicate-pattern} is the condition that must be true for the
11257 insn to be executed at runtime and should match a relational operator.
11258 One can use @code{match_operator} to match several relational operators
11259 at once.  Any @code{match_operand} operands must have no more than one
11260 alternative.
11262 @var{condition} is a C expression that must be true for the generated
11263 pattern to match.
11265 @findex current_insn_predicate
11266 @var{output-template} is a string similar to the @code{define_insn}
11267 output template (@pxref{Output Template}), except that the @samp{*}
11268 and @samp{@@} special cases do not apply.  This is only useful if the
11269 assembly text for the predicate is a simple prefix to the main insn.
11270 In order to handle the general case, there is a global variable
11271 @code{current_insn_predicate} that will contain the entire predicate
11272 if the current insn is predicated, and will otherwise be @code{NULL}.
11274 @var{optional-insn-attributes} is an optional vector of attributes that gets
11275 appended to the insn attributes of the produced cond_exec rtx. It can
11276 be used to add some distinguishing attribute to cond_exec rtxs produced
11277 that way. An example usage would be to use this attribute in conjunction
11278 with attributes on the main pattern to disable particular alternatives under
11279 certain conditions.
11281 When @code{define_cond_exec} is used, an implicit reference to
11282 the @code{predicable} instruction attribute is made.
11283 @xref{Insn Attributes}.  This attribute must be a boolean (i.e.@: have
11284 exactly two elements in its @var{list-of-values}), with the possible
11285 values being @code{no} and @code{yes}.  The default and all uses in
11286 the insns must be a simple constant, not a complex expressions.  It
11287 may, however, depend on the alternative, by using a comma-separated
11288 list of values.  If that is the case, the port should also define an
11289 @code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
11290 should also allow only @code{no} and @code{yes} as its values.
11292 For each @code{define_insn} for which the @code{predicable}
11293 attribute is true, a new @code{define_insn} pattern will be
11294 generated that matches a predicated version of the instruction.
11295 For example,
11297 @smallexample
11298 (define_insn "addsi"
11299   [(set (match_operand:SI 0 "register_operand" "r")
11300         (plus:SI (match_operand:SI 1 "register_operand" "r")
11301                  (match_operand:SI 2 "register_operand" "r")))]
11302   "@var{test1}"
11303   "add %2,%1,%0")
11305 (define_cond_exec
11306   [(ne (match_operand:CC 0 "register_operand" "c")
11307        (const_int 0))]
11308   "@var{test2}"
11309   "(%0)")
11310 @end smallexample
11312 @noindent
11313 generates a new pattern
11315 @smallexample
11316 (define_insn ""
11317   [(cond_exec
11318      (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
11319      (set (match_operand:SI 0 "register_operand" "r")
11320           (plus:SI (match_operand:SI 1 "register_operand" "r")
11321                    (match_operand:SI 2 "register_operand" "r"))))]
11322   "(@var{test2}) && (@var{test1})"
11323   "(%3) add %2,%1,%0")
11324 @end smallexample
11326 @end ifset
11327 @ifset INTERNALS
11328 @node Define Subst
11329 @section RTL Templates Transformations
11330 @cindex define_subst
11332 For some hardware architectures there are common cases when the RTL
11333 templates for the instructions can be derived from the other RTL
11334 templates using simple transformations.  E.g., @file{i386.md} contains
11335 an RTL template for the ordinary @code{sub} instruction---
11336 @code{*subsi_1}, and for the @code{sub} instruction with subsequent
11337 zero-extension---@code{*subsi_1_zext}.  Such cases can be easily
11338 implemented by a single meta-template capable of generating a modified
11339 case based on the initial one:
11341 @findex define_subst
11342 @smallexample
11343 (define_subst "@var{name}"
11344   [@var{input-template}]
11345   "@var{condition}"
11346   [@var{output-template}])
11347 @end smallexample
11348 @var{input-template} is a pattern describing the source RTL template,
11349 which will be transformed.
11351 @var{condition} is a C expression that is conjunct with the condition
11352 from the input-template to generate a condition to be used in the
11353 output-template.
11355 @var{output-template} is a pattern that will be used in the resulting
11356 template.
11358 @code{define_subst} mechanism is tightly coupled with the notion of the
11359 subst attribute (@pxref{Subst Iterators}).  The use of
11360 @code{define_subst} is triggered by a reference to a subst attribute in
11361 the transforming RTL template.  This reference initiates duplication of
11362 the source RTL template and substitution of the attributes with their
11363 values.  The source RTL template is left unchanged, while the copy is
11364 transformed by @code{define_subst}.  This transformation can fail in the
11365 case when the source RTL template is not matched against the
11366 input-template of the @code{define_subst}.  In such case the copy is
11367 deleted.
11369 @code{define_subst} can be used only in @code{define_insn} and
11370 @code{define_expand}, it cannot be used in other expressions (e.g.@: in
11371 @code{define_insn_and_split}).
11373 @menu
11374 * Define Subst Example::            Example of @code{define_subst} work.
11375 * Define Subst Pattern Matching::   Process of template comparison.
11376 * Define Subst Output Template::    Generation of output template.
11377 @end menu
11379 @node Define Subst Example
11380 @subsection @code{define_subst} Example
11381 @cindex define_subst
11383 To illustrate how @code{define_subst} works, let us examine a simple
11384 template transformation.
11386 Suppose there are two kinds of instructions: one that touches flags and
11387 the other that does not.  The instructions of the second type could be
11388 generated with the following @code{define_subst}:
11390 @smallexample
11391 (define_subst "add_clobber_subst"
11392   [(set (match_operand:SI 0 "" "")
11393         (match_operand:SI 1 "" ""))]
11394   ""
11395   [(set (match_dup 0)
11396         (match_dup 1))
11397    (clobber (reg:CC FLAGS_REG))])
11398 @end smallexample
11400 This @code{define_subst} can be applied to any RTL pattern containing
11401 @code{set} of mode SI and generates a copy with clobber when it is
11402 applied.
11404 Assume there is an RTL template for a @code{max} instruction to be used
11405 in @code{define_subst} mentioned above:
11407 @smallexample
11408 (define_insn "maxsi"
11409   [(set (match_operand:SI 0 "register_operand" "=r")
11410         (max:SI
11411           (match_operand:SI 1 "register_operand" "r")
11412           (match_operand:SI 2 "register_operand" "r")))]
11413   ""
11414   "max\t@{%2, %1, %0|%0, %1, %2@}"
11415  [@dots{}])
11416 @end smallexample
11418 To mark the RTL template for @code{define_subst} application,
11419 subst-attributes are used.  They should be declared in advance:
11421 @smallexample
11422 (define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber")
11423 @end smallexample
11425 Here @samp{add_clobber_name} is the attribute name,
11426 @samp{add_clobber_subst} is the name of the corresponding
11427 @code{define_subst}, the third argument (@samp{_noclobber}) is the
11428 attribute value that would be substituted into the unchanged version of
11429 the source RTL template, and the last argument (@samp{_clobber}) is the
11430 value that would be substituted into the second, transformed,
11431 version of the RTL template.
11433 Once the subst-attribute has been defined, it should be used in RTL
11434 templates which need to be processed by the @code{define_subst}.  So,
11435 the original RTL template should be changed:
11437 @smallexample
11438 (define_insn "maxsi<add_clobber_name>"
11439   [(set (match_operand:SI 0 "register_operand" "=r")
11440         (max:SI
11441           (match_operand:SI 1 "register_operand" "r")
11442           (match_operand:SI 2 "register_operand" "r")))]
11443   ""
11444   "max\t@{%2, %1, %0|%0, %1, %2@}"
11445  [@dots{}])
11446 @end smallexample
11448 The result of the @code{define_subst} usage would look like the following:
11450 @smallexample
11451 (define_insn "maxsi_noclobber"
11452   [(set (match_operand:SI 0 "register_operand" "=r")
11453         (max:SI
11454           (match_operand:SI 1 "register_operand" "r")
11455           (match_operand:SI 2 "register_operand" "r")))]
11456   ""
11457   "max\t@{%2, %1, %0|%0, %1, %2@}"
11458  [@dots{}])
11459 (define_insn "maxsi_clobber"
11460   [(set (match_operand:SI 0 "register_operand" "=r")
11461         (max:SI
11462           (match_operand:SI 1 "register_operand" "r")
11463           (match_operand:SI 2 "register_operand" "r")))
11464    (clobber (reg:CC FLAGS_REG))]
11465   ""
11466   "max\t@{%2, %1, %0|%0, %1, %2@}"
11467  [@dots{}])
11468 @end smallexample
11470 @node Define Subst Pattern Matching
11471 @subsection Pattern Matching in @code{define_subst}
11472 @cindex define_subst
11474 All expressions, allowed in @code{define_insn} or @code{define_expand},
11475 are allowed in the input-template of @code{define_subst}, except
11476 @code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The
11477 meanings of expressions in the input-template were changed:
11479 @code{match_operand} matches any expression (possibly, a subtree in
11480 RTL-template), if modes of the @code{match_operand} and this expression
11481 are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or
11482 this expression is @code{match_dup}, @code{match_op_dup}.  If the
11483 expression is @code{match_operand} too, and predicate of
11484 @code{match_operand} from the input pattern is not empty, then the
11485 predicates are compared.  That can be used for more accurate filtering
11486 of accepted RTL-templates.
11488 @code{match_operator} matches common operators (like @code{plus},
11489 @code{minus}), @code{unspec}, @code{unspec_volatile} operators and
11490 @code{match_operator}s from the original pattern if the modes match and
11491 @code{match_operator} from the input pattern has the same number of
11492 operands as the operator from the original pattern.
11494 @node Define Subst Output Template
11495 @subsection Generation of output template in @code{define_subst}
11496 @cindex define_subst
11498 If all necessary checks for @code{define_subst} application pass, a new
11499 RTL-pattern, based on the output-template, is created to replace the old
11500 template.  Like in input-patterns, meanings of some RTL expressions are
11501 changed when they are used in output-patterns of a @code{define_subst}.
11502 Thus, @code{match_dup} is used for copying the whole expression from the
11503 original pattern, which matched corresponding @code{match_operand} from
11504 the input pattern.
11506 @code{match_dup N} is used in the output template to be replaced with
11507 the expression from the original pattern, which matched
11508 @code{match_operand N} from the input pattern.  As a consequence,
11509 @code{match_dup} cannot be used to point to @code{match_operand}s from
11510 the output pattern, it should always refer to a @code{match_operand}
11511 from the input pattern.  If a @code{match_dup N} occurs more than once
11512 in the output template, its first occurrence is replaced with the
11513 expression from the original pattern, and the subsequent expressions
11514 are replaced with @code{match_dup N}, i.e., a reference to the first
11515 expression.
11517 In the output template one can refer to the expressions from the
11518 original pattern and create new ones.  For instance, some operands could
11519 be added by means of standard @code{match_operand}.
11521 After replacing @code{match_dup} with some RTL-subtree from the original
11522 pattern, it could happen that several @code{match_operand}s in the
11523 output pattern have the same indexes.  It is unknown, how many and what
11524 indexes would be used in the expression which would replace
11525 @code{match_dup}, so such conflicts in indexes are inevitable.  To
11526 overcome this issue, @code{match_operands} and @code{match_operators},
11527 which were introduced into the output pattern, are renumerated when all
11528 @code{match_dup}s are replaced.
11530 Number of alternatives in @code{match_operand}s introduced into the
11531 output template @code{M} could differ from the number of alternatives in
11532 the original pattern @code{N}, so in the resultant pattern there would
11533 be @code{N*M} alternatives.  Thus, constraints from the original pattern
11534 would be duplicated @code{N} times, constraints from the output pattern
11535 would be duplicated @code{M} times, producing all possible combinations.
11536 @end ifset
11538 @ifset INTERNALS
11539 @node Constant Definitions
11540 @section Constant Definitions
11541 @cindex constant definitions
11542 @findex define_constants
11544 Using literal constants inside instruction patterns reduces legibility and
11545 can be a maintenance problem.
11547 To overcome this problem, you may use the @code{define_constants}
11548 expression.  It contains a vector of name-value pairs.  From that
11549 point on, wherever any of the names appears in the MD file, it is as
11550 if the corresponding value had been written instead.  You may use
11551 @code{define_constants} multiple times; each appearance adds more
11552 constants to the table.  It is an error to redefine a constant with
11553 a different value.
11555 To come back to the a29k load multiple example, instead of
11557 @smallexample
11558 (define_insn ""
11559   [(match_parallel 0 "load_multiple_operation"
11560      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11561            (match_operand:SI 2 "memory_operand" "m"))
11562       (use (reg:SI 179))
11563       (clobber (reg:SI 179))])]
11564   ""
11565   "loadm 0,0,%1,%2")
11566 @end smallexample
11568 You could write:
11570 @smallexample
11571 (define_constants [
11572     (R_BP 177)
11573     (R_FC 178)
11574     (R_CR 179)
11575     (R_Q  180)
11578 (define_insn ""
11579   [(match_parallel 0 "load_multiple_operation"
11580      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11581            (match_operand:SI 2 "memory_operand" "m"))
11582       (use (reg:SI R_CR))
11583       (clobber (reg:SI R_CR))])]
11584   ""
11585   "loadm 0,0,%1,%2")
11586 @end smallexample
11588 The constants that are defined with a define_constant are also output
11589 in the insn-codes.h header file as #defines.
11591 @cindex enumerations
11592 @findex define_c_enum
11593 You can also use the machine description file to define enumerations.
11594 Like the constants defined by @code{define_constant}, these enumerations
11595 are visible to both the machine description file and the main C code.
11597 The syntax is as follows:
11599 @smallexample
11600 (define_c_enum "@var{name}" [
11601   @var{value0}
11602   @var{value1}
11603   (@var{value32} 32)
11604   @var{value33}
11605   @dots{}
11606   @var{valuen}
11608 @end smallexample
11610 This definition causes the equivalent of the following C code to appear
11611 in @file{insn-constants.h}:
11613 @smallexample
11614 enum @var{name} @{
11615   @var{value0} = 0,
11616   @var{value1} = 1,
11617   @var{value32} = 32,
11618   @var{value33} = 33,
11619   @dots{}
11620   @var{valuen} = @var{n}
11622 #define NUM_@var{cname}_VALUES (@var{n} + 1)
11623 @end smallexample
11625 where @var{cname} is the capitalized form of @var{name}.
11626 It also makes each @var{valuei} available in the machine description
11627 file, just as if it had been declared with:
11629 @smallexample
11630 (define_constants [(@var{valuei} @var{i})])
11631 @end smallexample
11633 Each @var{valuei} is usually an upper-case identifier and usually
11634 begins with @var{cname}.
11636 You can split the enumeration definition into as many statements as
11637 you like.  The above example is directly equivalent to:
11639 @smallexample
11640 (define_c_enum "@var{name}" [@var{value0}])
11641 (define_c_enum "@var{name}" [@var{value1}])
11642 @dots{}
11643 (define_c_enum "@var{name}" [@var{valuen}])
11644 @end smallexample
11646 Splitting the enumeration helps to improve the modularity of each
11647 individual @code{.md} file.  For example, if a port defines its
11648 synchronization instructions in a separate @file{sync.md} file,
11649 it is convenient to define all synchronization-specific enumeration
11650 values in @file{sync.md} rather than in the main @file{.md} file.
11652 Some enumeration names have special significance to GCC:
11654 @table @code
11655 @findex unspec_volatile
11656 @item unspecv
11657 If an enumeration called @code{unspecv} is defined, GCC will use it
11658 when printing out @code{unspec_volatile} expressions.  For example:
11660 @smallexample
11661 (define_c_enum "unspecv" [
11662   UNSPECV_BLOCKAGE
11664 @end smallexample
11666 causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:
11668 @smallexample
11669 (unspec_volatile ... UNSPECV_BLOCKAGE)
11670 @end smallexample
11672 @findex unspec
11673 @item unspec
11674 If an enumeration called @code{unspec} is defined, GCC will use
11675 it when printing out @code{unspec} expressions.  GCC will also use
11676 it when printing out @code{unspec_volatile} expressions unless an
11677 @code{unspecv} enumeration is also defined.  You can therefore
11678 decide whether to keep separate enumerations for volatile and
11679 non-volatile expressions or whether to use the same enumeration
11680 for both.
11681 @end table
11683 @findex define_enum
11684 @anchor{define_enum}
11685 Another way of defining an enumeration is to use @code{define_enum}:
11687 @smallexample
11688 (define_enum "@var{name}" [
11689   @var{value0}
11690   @var{value1}
11691   @dots{}
11692   @var{valuen}
11694 @end smallexample
11696 This directive implies:
11698 @smallexample
11699 (define_c_enum "@var{name}" [
11700   @var{cname}_@var{cvalue0}
11701   @var{cname}_@var{cvalue1}
11702   @dots{}
11703   @var{cname}_@var{cvaluen}
11705 @end smallexample
11707 @findex define_enum_attr
11708 where @var{cvaluei} is the capitalized form of @var{valuei}.
11709 However, unlike @code{define_c_enum}, the enumerations defined
11710 by @code{define_enum} can be used in attribute specifications
11711 (@pxref{define_enum_attr}).
11712 @end ifset
11713 @ifset INTERNALS
11714 @node Iterators
11715 @section Iterators
11716 @cindex iterators in @file{.md} files
11718 Ports often need to define similar patterns for more than one machine
11719 mode or for more than one rtx code.  GCC provides some simple iterator
11720 facilities to make this process easier.
11722 @menu
11723 * Mode Iterators::         Generating variations of patterns for different modes.
11724 * Code Iterators::         Doing the same for codes.
11725 * Int Iterators::          Doing the same for integers.
11726 * Subst Iterators::        Generating variations of patterns for define_subst.
11727 * Parameterized Names::    Specifying iterator values in C++ code.
11728 @end menu
11730 @node Mode Iterators
11731 @subsection Mode Iterators
11732 @cindex mode iterators in @file{.md} files
11734 Ports often need to define similar patterns for two or more different modes.
11735 For example:
11737 @itemize @bullet
11738 @item
11739 If a processor has hardware support for both single and double
11740 floating-point arithmetic, the @code{SFmode} patterns tend to be
11741 very similar to the @code{DFmode} ones.
11743 @item
11744 If a port uses @code{SImode} pointers in one configuration and
11745 @code{DImode} pointers in another, it will usually have very similar
11746 @code{SImode} and @code{DImode} patterns for manipulating pointers.
11747 @end itemize
11749 Mode iterators allow several patterns to be instantiated from one
11750 @file{.md} file template.  They can be used with any type of
11751 rtx-based construct, such as a @code{define_insn},
11752 @code{define_split}, or @code{define_peephole2}.
11754 @menu
11755 * Defining Mode Iterators:: Defining a new mode iterator.
11756 * Substitutions::           Combining mode iterators with substitutions
11757 * Examples::                Examples
11758 @end menu
11760 @node Defining Mode Iterators
11761 @subsubsection Defining Mode Iterators
11762 @findex define_mode_iterator
11764 The syntax for defining a mode iterator is:
11766 @smallexample
11767 (define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
11768 @end smallexample
11770 This allows subsequent @file{.md} file constructs to use the mode suffix
11771 @code{:@var{name}}.  Every construct that does so will be expanded
11772 @var{n} times, once with every use of @code{:@var{name}} replaced by
11773 @code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
11774 and so on.  In the expansion for a particular @var{modei}, every
11775 C condition will also require that @var{condi} be true.
11777 For example:
11779 @smallexample
11780 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11781 @end smallexample
11783 defines a new mode suffix @code{:P}.  Every construct that uses
11784 @code{:P} will be expanded twice, once with every @code{:P} replaced
11785 by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
11786 The @code{:SI} version will only apply if @code{Pmode == SImode} and
11787 the @code{:DI} version will only apply if @code{Pmode == DImode}.
11789 As with other @file{.md} conditions, an empty string is treated
11790 as ``always true''.  @code{(@var{mode} "")} can also be abbreviated
11791 to @code{@var{mode}}.  For example:
11793 @smallexample
11794 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11795 @end smallexample
11797 means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
11798 but that the @code{:SI} expansion has no such constraint.
11800 Iterators are applied in the order they are defined.  This can be
11801 significant if two iterators are used in a construct that requires
11802 substitutions.  @xref{Substitutions}.
11804 @node Substitutions
11805 @subsubsection Substitution in Mode Iterators
11806 @findex define_mode_attr
11808 If an @file{.md} file construct uses mode iterators, each version of the
11809 construct will often need slightly different strings or modes.  For
11810 example:
11812 @itemize @bullet
11813 @item
11814 When a @code{define_expand} defines several @code{add@var{m}3} patterns
11815 (@pxref{Standard Names}), each expander will need to use the
11816 appropriate mode name for @var{m}.
11818 @item
11819 When a @code{define_insn} defines several instruction patterns,
11820 each instruction will often use a different assembler mnemonic.
11822 @item
11823 When a @code{define_insn} requires operands with different modes,
11824 using an iterator for one of the operand modes usually requires a specific
11825 mode for the other operand(s).
11826 @end itemize
11828 GCC supports such variations through a system of ``mode attributes''.
11829 There are two standard attributes: @code{mode}, which is the name of
11830 the mode in lower case, and @code{MODE}, which is the same thing in
11831 upper case.  You can define other attributes using:
11833 @smallexample
11834 (define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
11835 @end smallexample
11837 where @var{name} is the name of the attribute and @var{valuei}
11838 is the value associated with @var{modei}.
11840 When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
11841 each string and mode in the pattern for sequences of the form
11842 @code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
11843 mode attribute.  If the attribute is defined for @var{mode}, the whole
11844 @code{<@dots{}>} sequence will be replaced by the appropriate attribute
11845 value.
11847 For example, suppose an @file{.md} file has:
11849 @smallexample
11850 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11851 (define_mode_attr load [(SI "lw") (DI "ld")])
11852 @end smallexample
11854 If one of the patterns that uses @code{:P} contains the string
11855 @code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
11856 will use @code{"lw\t%0,%1"} and the @code{DI} version will use
11857 @code{"ld\t%0,%1"}.
11859 Here is an example of using an attribute for a mode:
11861 @smallexample
11862 (define_mode_iterator LONG [SI DI])
11863 (define_mode_attr SHORT [(SI "HI") (DI "SI")])
11864 (define_insn @dots{}
11865   (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
11866 @end smallexample
11868 The @code{@var{iterator}:} prefix may be omitted, in which case the
11869 substitution will be attempted for every iterator expansion.
11871 @node Examples
11872 @subsubsection Mode Iterator Examples
11874 Here is an example from the MIPS port.  It defines the following
11875 modes and attributes (among others):
11877 @smallexample
11878 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11879 (define_mode_attr d [(SI "") (DI "d")])
11880 @end smallexample
11882 and uses the following template to define both @code{subsi3}
11883 and @code{subdi3}:
11885 @smallexample
11886 (define_insn "sub<mode>3"
11887   [(set (match_operand:GPR 0 "register_operand" "=d")
11888         (minus:GPR (match_operand:GPR 1 "register_operand" "d")
11889                    (match_operand:GPR 2 "register_operand" "d")))]
11890   ""
11891   "<d>subu\t%0,%1,%2"
11892   [(set_attr "type" "arith")
11893    (set_attr "mode" "<MODE>")])
11894 @end smallexample
11896 This is exactly equivalent to:
11898 @smallexample
11899 (define_insn "subsi3"
11900   [(set (match_operand:SI 0 "register_operand" "=d")
11901         (minus:SI (match_operand:SI 1 "register_operand" "d")
11902                   (match_operand:SI 2 "register_operand" "d")))]
11903   ""
11904   "subu\t%0,%1,%2"
11905   [(set_attr "type" "arith")
11906    (set_attr "mode" "SI")])
11908 (define_insn "subdi3"
11909   [(set (match_operand:DI 0 "register_operand" "=d")
11910         (minus:DI (match_operand:DI 1 "register_operand" "d")
11911                   (match_operand:DI 2 "register_operand" "d")))]
11912   "TARGET_64BIT"
11913   "dsubu\t%0,%1,%2"
11914   [(set_attr "type" "arith")
11915    (set_attr "mode" "DI")])
11916 @end smallexample
11918 @node Code Iterators
11919 @subsection Code Iterators
11920 @cindex code iterators in @file{.md} files
11921 @findex define_code_iterator
11922 @findex define_code_attr
11924 Code iterators operate in a similar way to mode iterators.  @xref{Mode Iterators}.
11926 The construct:
11928 @smallexample
11929 (define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
11930 @end smallexample
11932 defines a pseudo rtx code @var{name} that can be instantiated as
11933 @var{codei} if condition @var{condi} is true.  Each @var{codei}
11934 must have the same rtx format.  @xref{RTL Classes}.
11936 As with mode iterators, each pattern that uses @var{name} will be
11937 expanded @var{n} times, once with all uses of @var{name} replaced by
11938 @var{code1}, once with all uses replaced by @var{code2}, and so on.
11939 @xref{Defining Mode Iterators}.
11941 It is possible to define attributes for codes as well as for modes.
11942 There are two standard code attributes: @code{code}, the name of the
11943 code in lower case, and @code{CODE}, the name of the code in upper case.
11944 Other attributes are defined using:
11946 @smallexample
11947 (define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
11948 @end smallexample
11950 Instruction patterns can use code attributes as rtx codes, which can be
11951 useful if two sets of codes act in tandem.  For example, the following
11952 @code{define_insn} defines two patterns, one calculating a signed absolute
11953 difference and another calculating an unsigned absolute difference:
11955 @smallexample
11956 (define_code_iterator any_max [smax umax])
11957 (define_code_attr paired_min [(smax "smin") (umax "umin")])
11958 (define_insn @dots{}
11959   [(set (match_operand:SI 0 @dots{})
11960         (minus:SI (any_max:SI (match_operand:SI 1 @dots{})
11961                               (match_operand:SI 2 @dots{}))
11962                   (<paired_min>:SI (match_dup 1) (match_dup 2))))]
11963   @dots{})
11964 @end smallexample
11966 The signed version of the instruction uses @code{smax} and @code{smin}
11967 while the unsigned version uses @code{umax} and @code{umin}.  There
11968 are no versions that pair @code{smax} with @code{umin} or @code{umax}
11969 with @code{smin}.
11971 Here's an example of code iterators in action, taken from the MIPS port:
11973 @smallexample
11974 (define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
11975                                 eq ne gt ge lt le gtu geu ltu leu])
11977 (define_expand "b<code>"
11978   [(set (pc)
11979         (if_then_else (any_cond:CC (cc0)
11980                                    (const_int 0))
11981                       (label_ref (match_operand 0 ""))
11982                       (pc)))]
11983   ""
11985   gen_conditional_branch (operands, <CODE>);
11986   DONE;
11988 @end smallexample
11990 This is equivalent to:
11992 @smallexample
11993 (define_expand "bunordered"
11994   [(set (pc)
11995         (if_then_else (unordered:CC (cc0)
11996                                     (const_int 0))
11997                       (label_ref (match_operand 0 ""))
11998                       (pc)))]
11999   ""
12001   gen_conditional_branch (operands, UNORDERED);
12002   DONE;
12005 (define_expand "bordered"
12006   [(set (pc)
12007         (if_then_else (ordered:CC (cc0)
12008                                   (const_int 0))
12009                       (label_ref (match_operand 0 ""))
12010                       (pc)))]
12011   ""
12013   gen_conditional_branch (operands, ORDERED);
12014   DONE;
12017 @dots{}
12018 @end smallexample
12020 @node Int Iterators
12021 @subsection Int Iterators
12022 @cindex int iterators in @file{.md} files
12023 @findex define_int_iterator
12024 @findex define_int_attr
12026 Int iterators operate in a similar way to code iterators.  @xref{Code Iterators}.
12028 The construct:
12030 @smallexample
12031 (define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")])
12032 @end smallexample
12034 defines a pseudo integer constant @var{name} that can be instantiated as
12035 @var{inti} if condition @var{condi} is true.  Int iterators can appear in
12036 only those rtx fields that have `i', `n', `w', or `p' as the specifier.
12037 This means that each @var{int} has to be a constant defined using
12038 @samp{define_constant} or @samp{define_c_enum}.
12040 As with mode and code iterators, each pattern that uses @var{name} will be
12041 expanded @var{n} times, once with all uses of @var{name} replaced by
12042 @var{int1}, once with all uses replaced by @var{int2}, and so on.
12043 @xref{Defining Mode Iterators}.
12045 It is possible to define attributes for ints as well as for codes and modes.
12046 Attributes are defined using:
12048 @smallexample
12049 (define_int_attr @var{attr_name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")])
12050 @end smallexample
12052 In additon to these user-defined attributes, it is possible to use
12053 @samp{<@var{name}>} to refer to the current expansion of iterator
12054 @var{name} (such as @var{int1}, @var{int2}, and so on).
12056 Here's an example of int iterators in action, taken from the ARM port:
12058 @smallexample
12059 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
12061 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
12063 (define_insn "neon_vq<absneg><mode>"
12064   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12065         (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12066                        (match_operand:SI 2 "immediate_operand" "i")]
12067                       QABSNEG))]
12068   "TARGET_NEON"
12069   "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
12070   [(set_attr "type" "neon_vqneg_vqabs")]
12073 @end smallexample
12075 This is equivalent to:
12077 @smallexample
12078 (define_insn "neon_vqabs<mode>"
12079   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12080         (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12081                        (match_operand:SI 2 "immediate_operand" "i")]
12082                       UNSPEC_VQABS))]
12083   "TARGET_NEON"
12084   "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
12085   [(set_attr "type" "neon_vqneg_vqabs")]
12088 (define_insn "neon_vqneg<mode>"
12089   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12090         (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12091                        (match_operand:SI 2 "immediate_operand" "i")]
12092                       UNSPEC_VQNEG))]
12093   "TARGET_NEON"
12094   "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
12095   [(set_attr "type" "neon_vqneg_vqabs")]
12098 @end smallexample
12100 @node Subst Iterators
12101 @subsection Subst Iterators
12102 @cindex subst iterators in @file{.md} files
12103 @findex define_subst
12104 @findex define_subst_attr
12106 Subst iterators are special type of iterators with the following
12107 restrictions: they could not be declared explicitly, they always have
12108 only two values, and they do not have explicit dedicated name.
12109 Subst-iterators are triggered only when corresponding subst-attribute is
12110 used in RTL-pattern.
12112 Subst iterators transform templates in the following way: the templates
12113 are duplicated, the subst-attributes in these templates are replaced
12114 with the corresponding values, and a new attribute is implicitly added
12115 to the given @code{define_insn}/@code{define_expand}.  The name of the
12116 added attribute matches the name of @code{define_subst}.  Such
12117 attributes are declared implicitly, and it is not allowed to have a
12118 @code{define_attr} named as a @code{define_subst}.
12120 Each subst iterator is linked to a @code{define_subst}.  It is declared
12121 implicitly by the first appearance of the corresponding
12122 @code{define_subst_attr}, and it is not allowed to define it explicitly.
12124 Declarations of subst-attributes have the following syntax:
12126 @findex define_subst_attr
12127 @smallexample
12128 (define_subst_attr "@var{name}"
12129   "@var{subst-name}"
12130   "@var{no-subst-value}"
12131   "@var{subst-applied-value}")
12132 @end smallexample
12134 @var{name} is a string with which the given subst-attribute could be
12135 referred to.
12137 @var{subst-name} shows which @code{define_subst} should be applied to an
12138 RTL-template if the given subst-attribute is present in the
12139 RTL-template.
12141 @var{no-subst-value} is a value with which subst-attribute would be
12142 replaced in the first copy of the original RTL-template.
12144 @var{subst-applied-value} is a value with which subst-attribute would be
12145 replaced in the second copy of the original RTL-template.
12147 @node Parameterized Names
12148 @subsection Parameterized Names
12149 @cindex @samp{@@} in instruction pattern names
12150 Ports sometimes need to apply iterators using C++ code, in order to
12151 get the code or RTL pattern for a specific instruction.  For example,
12152 suppose we have the @samp{neon_vq<absneg><mode>} pattern given above:
12154 @smallexample
12155 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
12157 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
12159 (define_insn "neon_vq<absneg><mode>"
12160   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12161         (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12162                        (match_operand:SI 2 "immediate_operand" "i")]
12163                       QABSNEG))]
12164   @dots{}
12166 @end smallexample
12168 A port might need to generate this pattern for a variable
12169 @samp{QABSNEG} value and a variable @samp{VDQIW} mode.  There are two
12170 ways of doing this.  The first is to build the rtx for the pattern
12171 directly from C++ code; this is a valid technique and avoids any risk
12172 of combinatorial explosion.  The second is to prefix the instruction
12173 name with the special character @samp{@@}, which tells GCC to generate
12174 the four additional functions below.  In each case, @var{name} is the
12175 name of the instruction without the leading @samp{@@} character,
12176 without the @samp{<@dots{}>} placeholders, and with any underscore
12177 before a @samp{<@dots{}>} placeholder removed if keeping it would
12178 lead to a double or trailing underscore.
12180 @table @samp
12181 @item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
12182 See whether replacing the first @samp{<@dots{}>} placeholder with
12183 iterator value @var{i1}, the second with iterator value @var{i2}, and
12184 so on, gives a valid instruction.  Return its code if so, otherwise
12185 return @code{CODE_FOR_nothing}.
12187 @item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
12188 Same, but abort the compiler if the requested instruction does not exist.
12190 @item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
12191 Check for a valid instruction in the same way as
12192 @code{maybe_code_for_@var{name}}.  If the instruction exists,
12193 generate an instance of it using the operand values given by @var{op0},
12194 @var{op1}, and so on, otherwise return null.
12196 @item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
12197 Same, but abort the compiler if the requested instruction does not exist,
12198 or if the instruction generator invoked the @code{FAIL} macro.
12199 @end table
12201 For example, changing the pattern above to:
12203 @smallexample
12204 (define_insn "@@neon_vq<absneg><mode>"
12205   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
12206         (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
12207                        (match_operand:SI 2 "immediate_operand" "i")]
12208                       QABSNEG))]
12209   @dots{}
12211 @end smallexample
12213 would define the same patterns as before, but in addition would generate
12214 the four functions below:
12216 @smallexample
12217 insn_code maybe_code_for_neon_vq (int, machine_mode);
12218 insn_code code_for_neon_vq (int, machine_mode);
12219 rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
12220 rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
12221 @end smallexample
12223 Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)}
12224 would then give @code{CODE_FOR_neon_vqabsv8qi}.
12226 It is possible to have multiple @samp{@@} patterns with the same
12227 name and same types of iterator.  For example:
12229 @smallexample
12230 (define_insn "@@some_arithmetic_op<mode>"
12231   [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})]
12232   @dots{}
12235 (define_insn "@@some_arithmetic_op<mode>"
12236   [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})]
12237   @dots{}
12239 @end smallexample
12241 would produce a single set of functions that handles both
12242 @code{INTEGER_MODES} and @code{FLOAT_MODES}.
12244 It is also possible for these @samp{@@} patterns to have different
12245 numbers of operands from each other.  For example, patterns with
12246 a binary rtl code might take three operands (one output and two inputs)
12247 while patterns with a ternary rtl code might take four operands (one
12248 output and three inputs).  This combination would produce separate
12249 @samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for
12250 each operand count, but it would still produce a single
12251 @samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}.
12253 @end ifset