Debian Codegraph @

gcc/doc/md.texi

raw
1 @c Copyright (C) 1988-2022 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
4
5 @ifset INTERNALS
6 @node Machine Desc
7 @chapter Machine Descriptions
8 @cindex machine descriptions
9
10 A machine description has two parts: a file of instruction patterns
11 (@file{.md} file) and a C header file of macro definitions.
12
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.
18
19 See the next chapter for information on the C header file.
20
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 * Predicates:: Controlling what kinds of operands can be used
31 for an insn.
32 * Constraints:: Fine-tuning operand selection.
33 * Standard Names:: Names mark patterns to use for code generation.
34 * Pattern Ordering:: When the order of patterns makes a difference.
35 * Dependent Patterns:: Having one pattern may make you need another.
36 * Jump Patterns:: Special considerations for patterns for jump insns.
37 * Looping Patterns:: How to define patterns for special looping insns.
38 * Insn Canonicalizations::Canonicalization of Instructions
39 * Expander Definitions::Generating a sequence of several RTL insns
40 for a standard operation.
41 * Insn Splitting:: Splitting Instructions into Multiple Instructions.
42 * Including Patterns:: Including Patterns in Machine Descriptions.
43 * Peephole Definitions::Defining machine-specific peephole optimizations.
44 * Insn Attributes:: Specifying the value of attributes for generated insns.
45 * Conditional Execution::Generating @code{define_insn} patterns for
46 predication.
47 * Define Subst:: Generating @code{define_insn} and @code{define_expand}
48 patterns from other patterns.
49 * Constant Definitions::Defining symbolic constants that can be used in the
50 md file.
51 * Iterators:: Using iterators to generate patterns from a template.
52 @end menu
53
54 @node Overview
55 @section Overview of How the Machine Description is Used
56
57 There are three main conversions that happen in the compiler:
58
59 @enumerate
60
61 @item
62 The front end reads the source code and builds a parse tree.
63
64 @item
65 The parse tree is used to generate an RTL insn list based on named
66 instruction patterns.
67
68 @item
69 The insn list is matched against the RTL templates to produce assembler
70 code.
71
72 @end enumerate
73
74 For the generate pass, only the names of the insns matter, from either a
75 named @code{define_insn} or a @code{define_expand}. The compiler will
76 choose the pattern with the right name and apply the operands according
77 to the documentation later in this chapter, without regard for the RTL
78 template or operand constraints. Note that the names the compiler looks
79 for are hard-coded in the compiler---it will ignore unnamed patterns and
80 patterns with names it doesn't know about, but if you don't provide a
81 named pattern it needs, it will abort.
82
83 If a @code{define_insn} is used, the template given is inserted into the
84 insn list. If a @code{define_expand} is used, one of three things
85 happens, based on the condition logic. The condition logic may manually
86 create new insns for the insn list, say via @code{emit_insn()}, and
87 invoke @code{DONE}. For certain named patterns, it may invoke @code{FAIL} to tell the
88 compiler to use an alternate way of performing that task. If it invokes
89 neither @code{DONE} nor @code{FAIL}, the template given in the pattern
90 is inserted, as if the @code{define_expand} were a @code{define_insn}.
91
92 Once the insn list is generated, various optimization passes convert,
93 replace, and rearrange the insns in the insn list. This is where the
94 @code{define_split} and @code{define_peephole} patterns get used, for
95 example.
96
97 Finally, the insn list's RTL is matched up with the RTL templates in the
98 @code{define_insn} patterns, and those patterns are used to emit the
99 final assembly code. For this purpose, each named @code{define_insn}
100 acts like it's unnamed, since the names are ignored.
101
102 @node Patterns
103 @section Everything about Instruction Patterns
104 @cindex patterns
105 @cindex instruction patterns
106
107 @findex define_insn
108 A @code{define_insn} expression is used to define instruction patterns
109 to which insns may be matched. A @code{define_insn} expression contains
110 an incomplete RTL expression, with pieces to be filled in later, operand
111 constraints that restrict how the pieces can be filled in, and an output
112 template or C code to generate the assembler output.
113
114 A @code{define_insn} is an RTL expression containing four or five operands:
115
116 @enumerate
117 @item
118 An optional name @var{n}. When a name is present, the compiler
119 automically generates a C++ function @samp{gen_@var{n}} that takes
120 the operands of the instruction as arguments and returns the instruction's
121 rtx pattern. The compiler also assigns the instruction a unique code
122 @samp{CODE_FOR_@var{n}}, with all such codes belonging to an enum
123 called @code{insn_code}.
124
125 These names serve one of two purposes. The first is to indicate that the
126 instruction performs a certain standard job for the RTL-generation
127 pass of the compiler, such as a move, an addition, or a conditional
128 jump. The second is to help the target generate certain target-specific
129 operations, such as when implementing target-specific intrinsic functions.
130
131 It is better to prefix target-specific names with the name of the
132 target, to avoid any clash with current or future standard names.
133
134 The absence of a name is indicated by writing an empty string
135 where the name should go. Nameless instruction patterns are never
136 used for generating RTL code, but they may permit several simpler insns
137 to be combined later on.
138
139 For the purpose of debugging the compiler, you may also specify a
140 name beginning with the @samp{*} character. Such a name is used only
141 for identifying the instruction in RTL dumps; it is equivalent to having
142 a nameless pattern for all other purposes. Names beginning with the
143 @samp{*} character are not required to be unique.
144
145 The name may also have the form @samp{@@@var{n}}. This has the same
146 effect as a name @samp{@var{n}}, but in addition tells the compiler to
147 generate further helper functions; see @ref{Parameterized Names} for details.
148
149 @item
150 The @dfn{RTL template}: This is a vector of incomplete RTL expressions
151 which describe the semantics of the instruction (@pxref{RTL Template}).
152 It is incomplete because it may contain @code{match_operand},
153 @code{match_operator}, and @code{match_dup} expressions that stand for
154 operands of the instruction.
155
156 If the vector has multiple elements, the RTL template is treated as a
157 @code{parallel} expression.
158
159 @item
160 @cindex pattern conditions
161 @cindex conditions, in patterns
162 The condition: This is a string which contains a C expression. When the
163 compiler attempts to match RTL against a pattern, the condition is
164 evaluated. If the condition evaluates to @code{true}, the match is
165 permitted. The condition may be an empty string, which is treated
166 as always @code{true}.
167
168 @cindex named patterns and conditions
169 For a named pattern, the condition may not depend on the data in the
170 insn being matched, but only the target-machine-type flags. The compiler
171 needs to test these conditions during initialization in order to learn
172 exactly which named instructions are available in a particular run.
173
174 @findex operands
175 For nameless patterns, the condition is applied only when matching an
176 individual insn, and only after the insn has matched the pattern's
177 recognition template. The insn's operands may be found in the vector
178 @code{operands}.
179
180 An instruction condition cannot become more restrictive as compilation
181 progresses. If the condition accepts a particular RTL instruction at
182 one stage of compilation, it must continue to accept that instruction
183 until the final pass. For example, @samp{!reload_completed} and
184 @samp{can_create_pseudo_p ()} are both invalid instruction conditions,
185 because they are true during the earlier RTL passes and false during
186 the later ones. For the same reason, if a condition accepts an
187 instruction before register allocation, it cannot later try to control
188 register allocation by excluding certain register or value combinations.
189
190 Although a condition cannot become more restrictive as compilation
191 progresses, the condition for a nameless pattern @emph{can} become
192 more permissive. For example, a nameless instruction can require
193 @samp{reload_completed} to be true, in which case it only matches
194 after register allocation.
195
196 @item
197 The @dfn{output template} or @dfn{output statement}: This is either
198 a string, or a fragment of C code which returns a string.
199
200 When simple substitution isn't general enough, you can specify a piece
201 of C code to compute the output. @xref{Output Statement}.
202
203 @item
204 The @dfn{insn attributes}: This is an optional vector containing the values of
205 attributes for insns matching this pattern (@pxref{Insn Attributes}).
206 @end enumerate
207
208 @node Example
209 @section Example of @code{define_insn}
210 @cindex @code{define_insn} example
211
212 Here is an example of an instruction pattern, taken from the machine
213 description for the 68000/68020.
214
215 @smallexample
216 (define_insn "tstsi"
217 [(set (cc0)
218 (match_operand:SI 0 "general_operand" "rm"))]
219 ""
220 "*
221 @{
222 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
223 return \"tstl %0\";
224 return \"cmpl #0,%0\";
225 @}")
226 @end smallexample
227
228 @noindent
229 This can also be written using braced strings:
230
231 @smallexample
232 (define_insn "tstsi"
233 [(set (cc0)
234 (match_operand:SI 0 "general_operand" "rm"))]
235 ""
236 @{
237 if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
238 return "tstl %0";
239 return "cmpl #0,%0";
240 @})
241 @end smallexample
242
243 This describes an instruction which sets the condition codes based on the
244 value of a general operand. It has no condition, so any insn with an RTL
245 description of the form shown may be matched to this pattern. The name
246 @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
247 generation pass that, when it is necessary to test such a value, an insn
248 to do so can be constructed using this pattern.
249
250 The output control string is a piece of C code which chooses which
251 output template to return based on the kind of operand and the specific
252 type of CPU for which code is being generated.
253
254 @samp{"rm"} is an operand constraint. Its meaning is explained below.
255
256 @node RTL Template
257 @section RTL Template
258 @cindex RTL insn template
259 @cindex generating insns
260 @cindex insns, generating
261 @cindex recognizing insns
262 @cindex insns, recognizing
263
264 The RTL template is used to define which insns match the particular pattern
265 and how to find their operands. For named patterns, the RTL template also
266 says how to construct an insn from specified operands.
267
268 Construction involves substituting specified operands into a copy of the
269 template. Matching involves determining the values that serve as the
270 operands in the insn being matched. Both of these activities are
271 controlled by special expression types that direct matching and
272 substitution of the operands.
273
274 @table @code
275 @findex match_operand
276 @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
277 This expression is a placeholder for operand number @var{n} of
278 the insn. When constructing an insn, operand number @var{n}
279 will be substituted at this point. When matching an insn, whatever
280 appears at this position in the insn will be taken as operand
281 number @var{n}; but it must satisfy @var{predicate} or this instruction
282 pattern will not match at all.
283
284 Operand numbers must be chosen consecutively counting from zero in
285 each instruction pattern. There may be only one @code{match_operand}
286 expression in the pattern for each operand number. Usually operands
287 are numbered in the order of appearance in @code{match_operand}
288 expressions. In the case of a @code{define_expand}, any operand numbers
289 used only in @code{match_dup} expressions have higher values than all
290 other operand numbers.
291
292 @var{predicate} is a string that is the name of a function that
293 accepts two arguments, an expression and a machine mode.
294 @xref{Predicates}. During matching, the function will be called with
295 the putative operand as the expression and @var{m} as the mode
296 argument (if @var{m} is not specified, @code{VOIDmode} will be used,
297 which normally causes @var{predicate} to accept any mode). If it
298 returns zero, this instruction pattern fails to match.
299 @var{predicate} may be an empty string; then it means no test is to be
300 done on the operand, so anything which occurs in this position is
301 valid.
302
303 Most of the time, @var{predicate} will reject modes other than @var{m}---but
304 not always. For example, the predicate @code{address_operand} uses
305 @var{m} as the mode of memory ref that the address should be valid for.
306 Many predicates accept @code{const_int} nodes even though their mode is
307 @code{VOIDmode}.
308
309 @var{constraint} controls reloading and the choice of the best register
310 class to use for a value, as explained later (@pxref{Constraints}).
311 If the constraint would be an empty string, it can be omitted.
312
313 People are often unclear on the difference between the constraint and the
314 predicate. The predicate helps decide whether a given insn matches the
315 pattern. The constraint plays no role in this decision; instead, it
316 controls various decisions in the case of an insn which does match.
317
318 @findex match_scratch
319 @item (match_scratch:@var{m} @var{n} @var{constraint})
320 This expression is also a placeholder for operand number @var{n}
321 and indicates that operand must be a @code{scratch} or @code{reg}
322 expression.
323
324 When matching patterns, this is equivalent to
325
326 @smallexample
327 (match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
328 @end smallexample
329
330 but, when generating RTL, it produces a (@code{scratch}:@var{m})
331 expression.
332
333 If the last few expressions in a @code{parallel} are @code{clobber}
334 expressions whose operands are either a hard register or
335 @code{match_scratch}, the combiner can add or delete them when
336 necessary. @xref{Side Effects}.
337
338 @findex match_dup
339 @item (match_dup @var{n})
340 This expression is also a placeholder for operand number @var{n}.
341 It is used when the operand needs to appear more than once in the
342 insn.
343
344 In construction, @code{match_dup} acts just like @code{match_operand}:
345 the operand is substituted into the insn being constructed. But in
346 matching, @code{match_dup} behaves differently. It assumes that operand
347 number @var{n} has already been determined by a @code{match_operand}
348 appearing earlier in the recognition template, and it matches only an
349 identical-looking expression.
350
351 Note that @code{match_dup} should not be used to tell the compiler that
352 a particular register is being used for two operands (example:
353 @code{add} that adds one register to another; the second register is
354 both an input operand and the output operand). Use a matching
355 constraint (@pxref{Simple Constraints}) for those. @code{match_dup} is for the cases where one
356 operand is used in two places in the template, such as an instruction
357 that computes both a quotient and a remainder, where the opcode takes
358 two input operands but the RTL template has to refer to each of those
359 twice; once for the quotient pattern and once for the remainder pattern.
360
361 @findex match_operator
362 @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
363 This pattern is a kind of placeholder for a variable RTL expression
364 code.
365
366 When constructing an insn, it stands for an RTL expression whose
367 expression code is taken from that of operand @var{n}, and whose
368 operands are constructed from the patterns @var{operands}.
369
370 When matching an expression, it matches an expression if the function
371 @var{predicate} returns nonzero on that expression @emph{and} the
372 patterns @var{operands} match the operands of the expression.
373
374 Suppose that the function @code{commutative_operator} is defined as
375 follows, to match any expression whose operator is one of the
376 commutative arithmetic operators of RTL and whose mode is @var{mode}:
377
378 @smallexample
379 int
380 commutative_integer_operator (x, mode)
381 rtx x;
382 machine_mode mode;
383 @{
384 enum rtx_code code = GET_CODE (x);
385 if (GET_MODE (x) != mode)
386 return 0;
387 return (GET_RTX_CLASS (code) == RTX_COMM_ARITH
388 || code == EQ || code == NE);
389 @}
390 @end smallexample
391
392 Then the following pattern will match any RTL expression consisting
393 of a commutative operator applied to two general operands:
394
395 @smallexample
396 (match_operator:SI 3 "commutative_operator"
397 [(match_operand:SI 1 "general_operand" "g")
398 (match_operand:SI 2 "general_operand" "g")])
399 @end smallexample
400
401 Here the vector @code{[@var{operands}@dots{}]} contains two patterns
402 because the expressions to be matched all contain two operands.
403
404 When this pattern does match, the two operands of the commutative
405 operator are recorded as operands 1 and 2 of the insn. (This is done
406 by the two instances of @code{match_operand}.) Operand 3 of the insn
407 will be the entire commutative expression: use @code{GET_CODE
408 (operands[3])} to see which commutative operator was used.
409
410 The machine mode @var{m} of @code{match_operator} works like that of
411 @code{match_operand}: it is passed as the second argument to the
412 predicate function, and that function is solely responsible for
413 deciding whether the expression to be matched ``has'' that mode.
414
415 When constructing an insn, argument 3 of the gen-function will specify
416 the operation (i.e.@: the expression code) for the expression to be
417 made. It should be an RTL expression, whose expression code is copied
418 into a new expression whose operands are arguments 1 and 2 of the
419 gen-function. The subexpressions of argument 3 are not used;
420 only its expression code matters.
421
422 When @code{match_operator} is used in a pattern for matching an insn,
423 it usually best if the operand number of the @code{match_operator}
424 is higher than that of the actual operands of the insn. This improves
425 register allocation because the register allocator often looks at
426 operands 1 and 2 of insns to see if it can do register tying.
427
428 There is no way to specify constraints in @code{match_operator}. The
429 operand of the insn which corresponds to the @code{match_operator}
430 never has any constraints because it is never reloaded as a whole.
431 However, if parts of its @var{operands} are matched by
432 @code{match_operand} patterns, those parts may have constraints of
433 their own.
434
435 @findex match_op_dup
436 @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
437 Like @code{match_dup}, except that it applies to operators instead of
438 operands. When constructing an insn, operand number @var{n} will be
439 substituted at this point. But in matching, @code{match_op_dup} behaves
440 differently. It assumes that operand number @var{n} has already been
441 determined by a @code{match_operator} appearing earlier in the
442 recognition template, and it matches only an identical-looking
443 expression.
444
445 @findex match_parallel
446 @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
447 This pattern is a placeholder for an insn that consists of a
448 @code{parallel} expression with a variable number of elements. This
449 expression should only appear at the top level of an insn pattern.
450
451 When constructing an insn, operand number @var{n} will be substituted at
452 this point. When matching an insn, it matches if the body of the insn
453 is a @code{parallel} expression with at least as many elements as the
454 vector of @var{subpat} expressions in the @code{match_parallel}, if each
455 @var{subpat} matches the corresponding element of the @code{parallel},
456 @emph{and} the function @var{predicate} returns nonzero on the
457 @code{parallel} that is the body of the insn. It is the responsibility
458 of the predicate to validate elements of the @code{parallel} beyond
459 those listed in the @code{match_parallel}.
460
461 A typical use of @code{match_parallel} is to match load and store
462 multiple expressions, which can contain a variable number of elements
463 in a @code{parallel}. For example,
464
465 @smallexample
466 (define_insn ""
467 [(match_parallel 0 "load_multiple_operation"
468 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
469 (match_operand:SI 2 "memory_operand" "m"))
470 (use (reg:SI 179))
471 (clobber (reg:SI 179))])]
472 ""
473 "loadm 0,0,%1,%2")
474 @end smallexample
475
476 This example comes from @file{a29k.md}. The function
477 @code{load_multiple_operation} is defined in @file{a29k.c} and checks
478 that subsequent elements in the @code{parallel} are the same as the
479 @code{set} in the pattern, except that they are referencing subsequent
480 registers and memory locations.
481
482 An insn that matches this pattern might look like:
483
484 @smallexample
485 (parallel
486 [(set (reg:SI 20) (mem:SI (reg:SI 100)))
487 (use (reg:SI 179))
488 (clobber (reg:SI 179))
489 (set (reg:SI 21)
490 (mem:SI (plus:SI (reg:SI 100)
491 (const_int 4))))
492 (set (reg:SI 22)
493 (mem:SI (plus:SI (reg:SI 100)
494 (const_int 8))))])
495 @end smallexample
496
497 @findex match_par_dup
498 @item (match_par_dup @var{n} [@var{subpat}@dots{}])
499 Like @code{match_op_dup}, but for @code{match_parallel} instead of
500 @code{match_operator}.
501
502 @end table
503
504 @node Output Template
505 @section Output Templates and Operand Substitution
506 @cindex output templates
507 @cindex operand substitution
508
509 @cindex @samp{%} in template
510 @cindex percent sign
511 The @dfn{output template} is a string which specifies how to output the
512 assembler code for an instruction pattern. Most of the template is a
513 fixed string which is output literally. The character @samp{%} is used
514 to specify where to substitute an operand; it can also be used to
515 identify places where different variants of the assembler require
516 different syntax.
517
518 In the simplest case, a @samp{%} followed by a digit @var{n} says to output
519 operand @var{n} at that point in the string.
520
521 @samp{%} followed by a letter and a digit says to output an operand in an
522 alternate fashion. Four letters have standard, built-in meanings described
523 below. The machine description macro @code{PRINT_OPERAND} can define
524 additional letters with nonstandard meanings.
525
526 @samp{%c@var{digit}} can be used to substitute an operand that is a
527 constant value without the syntax that normally indicates an immediate
528 operand.
529
530 @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
531 the constant is negated before printing.
532
533 @samp{%a@var{digit}} can be used to substitute an operand as if it were a
534 memory reference, with the actual operand treated as the address. This may
535 be useful when outputting a ``load address'' instruction, because often the
536 assembler syntax for such an instruction requires you to write the operand
537 as if it were a memory reference.
538
539 @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
540 instruction.
541
542 @samp{%=} outputs a number which is unique to each instruction in the
543 entire compilation. This is useful for making local labels to be
544 referred to more than once in a single template that generates multiple
545 assembler instructions.
546
547 @samp{%} followed by a punctuation character specifies a substitution that
548 does not use an operand. Only one case is standard: @samp{%%} outputs a
549 @samp{%} into the assembler code. Other nonstandard cases can be
550 defined in the @code{PRINT_OPERAND} macro. You must also define
551 which punctuation characters are valid with the
552 @code{PRINT_OPERAND_PUNCT_VALID_P} macro.
553
554 @cindex \
555 @cindex backslash
556 The template may generate multiple assembler instructions. Write the text
557 for the instructions, with @samp{\;} between them.
558
559 @cindex matching operands
560 When the RTL contains two operands which are required by constraint to match
561 each other, the output template must refer only to the lower-numbered operand.
562 Matching operands are not always identical, and the rest of the compiler
563 arranges to put the proper RTL expression for printing into the lower-numbered
564 operand.
565
566 One use of nonstandard letters or punctuation following @samp{%} is to
567 distinguish between different assembler languages for the same machine; for
568 example, Motorola syntax versus MIT syntax for the 68000. Motorola syntax
569 requires periods in most opcode names, while MIT syntax does not. For
570 example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
571 syntax. The same file of patterns is used for both kinds of output syntax,
572 but the character sequence @samp{%.} is used in each place where Motorola
573 syntax wants a period. The @code{PRINT_OPERAND} macro for Motorola syntax
574 defines the sequence to output a period; the macro for MIT syntax defines
575 it to do nothing.
576
577 @cindex @code{#} in template
578 As a special case, a template consisting of the single character @code{#}
579 instructs the compiler to first split the insn, and then output the
580 resulting instructions separately. This helps eliminate redundancy in the
581 output templates. If you have a @code{define_insn} that needs to emit
582 multiple assembler instructions, and there is a matching @code{define_split}
583 already defined, then you can simply use @code{#} as the output template
584 instead of writing an output template that emits the multiple assembler
585 instructions.
586
587 Note that @code{#} only has an effect while generating assembly code;
588 it does not affect whether a split occurs earlier. An associated
589 @code{define_split} must exist and it must be suitable for use after
590 register allocation.
591
592 If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
593 of the form @samp{@{option0|option1|option2@}} in the templates. These
594 describe multiple variants of assembler language syntax.
595 @xref{Instruction Output}.
596
597 @node Output Statement
598 @section C Statements for Assembler Output
599 @cindex output statements
600 @cindex C statements for assembler output
601 @cindex generating assembler output
602
603 Often a single fixed template string cannot produce correct and efficient
604 assembler code for all the cases that are recognized by a single
605 instruction pattern. For example, the opcodes may depend on the kinds of
606 operands; or some unfortunate combinations of operands may require extra
607 machine instructions.
608
609 If the output control string starts with a @samp{@@}, then it is actually
610 a series of templates, each on a separate line. (Blank lines and
611 leading spaces and tabs are ignored.) The templates correspond to the
612 pattern's constraint alternatives (@pxref{Multi-Alternative}). For example,
613 if a target machine has a two-address add instruction @samp{addr} to add
614 into a register and another @samp{addm} to add a register to memory, you
615 might write this pattern:
616
617 @smallexample
618 (define_insn "addsi3"
619 [(set (match_operand:SI 0 "general_operand" "=r,m")
620 (plus:SI (match_operand:SI 1 "general_operand" "0,0")
621 (match_operand:SI 2 "general_operand" "g,r")))]
622 ""
623 "@@
624 addr %2,%0
625 addm %2,%0")
626 @end smallexample
627
628 @cindex @code{*} in template
629 @cindex asterisk in template
630 If the output control string starts with a @samp{*}, then it is not an
631 output template but rather a piece of C program that should compute a
632 template. It should execute a @code{return} statement to return the
633 template-string you want. Most such templates use C string literals, which
634 require doublequote characters to delimit them. To include these
635 doublequote characters in the string, prefix each one with @samp{\}.
636
637 If the output control string is written as a brace block instead of a
638 double-quoted string, it is automatically assumed to be C code. In that
639 case, it is not necessary to put in a leading asterisk, or to escape the
640 doublequotes surrounding C string literals.
641
642 The operands may be found in the array @code{operands}, whose C data type
643 is @code{rtx []}.
644
645 It is very common to select different ways of generating assembler code
646 based on whether an immediate operand is within a certain range. Be
647 careful when doing this, because the result of @code{INTVAL} is an
648 integer on the host machine. If the host machine has more bits in an
649 @code{int} than the target machine has in the mode in which the constant
650 will be used, then some of the bits you get from @code{INTVAL} will be
651 superfluous. For proper results, you must carefully disregard the
652 values of those bits.
653
654 @findex output_asm_insn
655 It is possible to output an assembler instruction and then go on to output
656 or compute more of them, using the subroutine @code{output_asm_insn}. This
657 receives two arguments: a template-string and a vector of operands. The
658 vector may be @code{operands}, or it may be another array of @code{rtx}
659 that you declare locally and initialize yourself.
660
661 @findex which_alternative
662 When an insn pattern has multiple alternatives in its constraints, often
663 the appearance of the assembler code is determined mostly by which alternative
664 was matched. When this is so, the C code can test the variable
665 @code{which_alternative}, which is the ordinal number of the alternative
666 that was actually satisfied (0 for the first, 1 for the second alternative,
667 etc.).
668
669 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
670 for registers and @samp{clrmem} for memory locations. Here is how
671 a pattern could use @code{which_alternative} to choose between them:
672
673 @smallexample
674 (define_insn ""
675 [(set (match_operand:SI 0 "general_operand" "=r,m")
676 (const_int 0))]
677 ""
678 @{
679 return (which_alternative == 0
680 ? "clrreg %0" : "clrmem %0");
681 @})
682 @end smallexample
683
684 The example above, where the assembler code to generate was
685 @emph{solely} determined by the alternative, could also have been specified
686 as follows, having the output control string start with a @samp{@@}:
687
688 @smallexample
689 @group
690 (define_insn ""
691 [(set (match_operand:SI 0 "general_operand" "=r,m")
692 (const_int 0))]
693 ""
694 "@@
695 clrreg %0
696 clrmem %0")
697 @end group
698 @end smallexample
699
700 If you just need a little bit of C code in one (or a few) alternatives,
701 you can use @samp{*} inside of a @samp{@@} multi-alternative template:
702
703 @smallexample
704 @group
705 (define_insn ""
706 [(set (match_operand:SI 0 "general_operand" "=r,<,m")
707 (const_int 0))]
708 ""
709 "@@
710 clrreg %0
711 * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\";
712 clrmem %0")
713 @end group
714 @end smallexample
715
716 @node Predicates
717 @section Predicates
718 @cindex predicates
719 @cindex operand predicates
720 @cindex operator predicates
721
722 A predicate determines whether a @code{match_operand} or
723 @code{match_operator} expression matches, and therefore whether the
724 surrounding instruction pattern will be used for that combination of
725 operands. GCC has a number of machine-independent predicates, and you
726 can define machine-specific predicates as needed. By convention,
727 predicates used with @code{match_operand} have names that end in
728 @samp{_operand}, and those used with @code{match_operator} have names
729 that end in @samp{_operator}.
730
731 All predicates are boolean functions (in the mathematical sense) of
732 two arguments: the RTL expression that is being considered at that
733 position in the instruction pattern, and the machine mode that the
734 @code{match_operand} or @code{match_operator} specifies. In this
735 section, the first argument is called @var{op} and the second argument
736 @var{mode}. Predicates can be called from C as ordinary two-argument
737 functions; this can be useful in output templates or other
738 machine-specific code.
739
740 Operand predicates can allow operands that are not actually acceptable
741 to the hardware, as long as the constraints give reload the ability to
742 fix them up (@pxref{Constraints}). However, GCC will usually generate
743 better code if the predicates specify the requirements of the machine
744 instructions as closely as possible. Reload cannot fix up operands
745 that must be constants (``immediate operands''); you must use a
746 predicate that allows only constants, or else enforce the requirement
747 in the extra condition.
748
749 @cindex predicates and machine modes
750 @cindex normal predicates
751 @cindex special predicates
752 Most predicates handle their @var{mode} argument in a uniform manner.
753 If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
754 any mode. If @var{mode} is anything else, then @var{op} must have the
755 same mode, unless @var{op} is a @code{CONST_INT} or integer
756 @code{CONST_DOUBLE}. These RTL expressions always have
757 @code{VOIDmode}, so it would be counterproductive to check that their
758 mode matches. Instead, predicates that accept @code{CONST_INT} and/or
759 integer @code{CONST_DOUBLE} check that the value stored in the
760 constant will fit in the requested mode.
761
762 Predicates with this behavior are called @dfn{normal}.
763 @command{genrecog} can optimize the instruction recognizer based on
764 knowledge of how normal predicates treat modes. It can also diagnose
765 certain kinds of common errors in the use of normal predicates; for
766 instance, it is almost always an error to use a normal predicate
767 without specifying a mode.
768
769 Predicates that do something different with their @var{mode} argument
770 are called @dfn{special}. The generic predicates
771 @code{address_operand} and @code{pmode_register_operand} are special
772 predicates. @command{genrecog} does not do any optimizations or
773 diagnosis when special predicates are used.
774
775 @menu
776 * Machine-Independent Predicates:: Predicates available to all back ends.
777 * Defining Predicates:: How to write machine-specific predicate
778 functions.
779 @end menu
780
781 @node Machine-Independent Predicates
782 @subsection Machine-Independent Predicates
783 @cindex machine-independent predicates
784 @cindex generic predicates
785
786 These are the generic predicates available to all back ends. They are
787 defined in @file{recog.cc}. The first category of predicates allow
788 only constant, or @dfn{immediate}, operands.
789
790 @defun immediate_operand
791 This predicate allows any sort of constant that fits in @var{mode}.
792 It is an appropriate choice for instructions that take operands that
793 must be constant.
794 @end defun
795
796 @defun const_int_operand
797 This predicate allows any @code{CONST_INT} expression that fits in
798 @var{mode}. It is an appropriate choice for an immediate operand that
799 does not allow a symbol or label.
800 @end defun
801
802 @defun const_double_operand
803 This predicate accepts any @code{CONST_DOUBLE} expression that has
804 exactly @var{mode}. If @var{mode} is @code{VOIDmode}, it will also
805 accept @code{CONST_INT}. It is intended for immediate floating point
806 constants.
807 @end defun
808
809 @noindent
810 The second category of predicates allow only some kind of machine
811 register.
812
813 @defun register_operand
814 This predicate allows any @code{REG} or @code{SUBREG} expression that
815 is valid for @var{mode}. It is often suitable for arithmetic
816 instruction operands on a RISC machine.
817 @end defun
818
819 @defun pmode_register_operand
820 This is a slight variant on @code{register_operand} which works around
821 a limitation in the machine-description reader.
822
823 @smallexample
824 (match_operand @var{n} "pmode_register_operand" @var{constraint})
825 @end smallexample
826
827 @noindent
828 means exactly what
829
830 @smallexample
831 (match_operand:P @var{n} "register_operand" @var{constraint})
832 @end smallexample
833
834 @noindent
835 would mean, if the machine-description reader accepted @samp{:P}
836 mode suffixes. Unfortunately, it cannot, because @code{Pmode} is an
837 alias for some other mode, and might vary with machine-specific
838 options. @xref{Misc}.
839 @end defun
840
841 @defun scratch_operand
842 This predicate allows hard registers and @code{SCRATCH} expressions,
843 but not pseudo-registers. It is used internally by @code{match_scratch};
844 it should not be used directly.
845 @end defun
846
847 @noindent
848 The third category of predicates allow only some kind of memory reference.
849
850 @defun memory_operand
851 This predicate allows any valid reference to a quantity of mode
852 @var{mode} in memory, as determined by the weak form of
853 @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
854 @end defun
855
856 @defun address_operand
857 This predicate is a little unusual; it allows any operand that is a
858 valid expression for the @emph{address} of a quantity of mode
859 @var{mode}, again determined by the weak form of
860 @code{GO_IF_LEGITIMATE_ADDRESS}. To first order, if
861 @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
862 @code{memory_operand}, then @var{exp} is acceptable to
863 @code{address_operand}. Note that @var{exp} does not necessarily have
864 the mode @var{mode}.
865 @end defun
866
867 @defun indirect_operand
868 This is a stricter form of @code{memory_operand} which allows only
869 memory references with a @code{general_operand} as the address
870 expression. New uses of this predicate are discouraged, because
871 @code{general_operand} is very permissive, so it's hard to tell what
872 an @code{indirect_operand} does or does not allow. If a target has
873 different requirements for memory operands for different instructions,
874 it is better to define target-specific predicates which enforce the
875 hardware's requirements explicitly.
876 @end defun
877
878 @defun push_operand
879 This predicate allows a memory reference suitable for pushing a value
880 onto the stack. This will be a @code{MEM} which refers to
881 @code{stack_pointer_rtx}, with a side effect in its address expression
882 (@pxref{Incdec}); which one is determined by the
883 @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
884 @end defun
885
886 @defun pop_operand
887 This predicate allows a memory reference suitable for popping a value
888 off the stack. Again, this will be a @code{MEM} referring to
889 @code{stack_pointer_rtx}, with a side effect in its address
890 expression. However, this time @code{STACK_POP_CODE} is expected.
891 @end defun
892
893 @noindent
894 The fourth category of predicates allow some combination of the above
895 operands.
896
897 @defun nonmemory_operand
898 This predicate allows any immediate or register operand valid for @var{mode}.
899 @end defun
900
901 @defun nonimmediate_operand
902 This predicate allows any register or memory operand valid for @var{mode}.
903 @end defun
904
905 @defun general_operand
906 This predicate allows any immediate, register, or memory operand
907 valid for @var{mode}.
908 @end defun
909
910 @noindent
911 Finally, there are two generic operator predicates.
912
913 @defun comparison_operator
914 This predicate matches any expression which performs an arithmetic
915 comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the
916 expression code.
917 @end defun
918
919 @defun ordered_comparison_operator
920 This predicate matches any expression which performs an arithmetic
921 comparison in @var{mode} and whose expression code is valid for integer
922 modes; that is, the expression code will be one of @code{eq}, @code{ne},
923 @code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu},
924 @code{ge}, @code{geu}.
925 @end defun
926
927 @node Defining Predicates
928 @subsection Defining Machine-Specific Predicates
929 @cindex defining predicates
930 @findex define_predicate
931 @findex define_special_predicate
932
933 Many machines have requirements for their operands that cannot be
934 expressed precisely using the generic predicates. You can define
935 additional predicates using @code{define_predicate} and
936 @code{define_special_predicate} expressions. These expressions have
937 three operands:
938
939 @itemize @bullet
940 @item
941 The name of the predicate, as it will be referred to in
942 @code{match_operand} or @code{match_operator} expressions.
943
944 @item
945 An RTL expression which evaluates to true if the predicate allows the
946 operand @var{op}, false if it does not. This expression can only use
947 the following RTL codes:
948
949 @table @code
950 @item MATCH_OPERAND
951 When written inside a predicate expression, a @code{MATCH_OPERAND}
952 expression evaluates to true if the predicate it names would allow
953 @var{op}. The operand number and constraint are ignored. Due to
954 limitations in @command{genrecog}, you can only refer to generic
955 predicates and predicates that have already been defined.
956
957 @item MATCH_CODE
958 This expression evaluates to true if @var{op} or a specified
959 subexpression of @var{op} has one of a given list of RTX codes.
960
961 The first operand of this expression is a string constant containing a
962 comma-separated list of RTX code names (in lower case). These are the
963 codes for which the @code{MATCH_CODE} will be true.
964
965 The second operand is a string constant which indicates what
966 subexpression of @var{op} to examine. If it is absent or the empty
967 string, @var{op} itself is examined. Otherwise, the string constant
968 must be a sequence of digits and/or lowercase letters. Each character
969 indicates a subexpression to extract from the current expression; for
970 the first character this is @var{op}, for the second and subsequent
971 characters it is the result of the previous character. A digit
972 @var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
973 extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
974 alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on). The
975 @code{MATCH_CODE} then examines the RTX code of the subexpression
976 extracted by the complete string. It is not possible to extract
977 components of an @code{rtvec} that is not at position 0 within its RTX
978 object.
979
980 @item MATCH_TEST
981 This expression has one operand, a string constant containing a C
982 expression. The predicate's arguments, @var{op} and @var{mode}, are
983 available with those names in the C expression. The @code{MATCH_TEST}
984 evaluates to true if the C expression evaluates to a nonzero value.
985 @code{MATCH_TEST} expressions must not have side effects.
986
987 @item AND
988 @itemx IOR
989 @itemx NOT
990 @itemx IF_THEN_ELSE
991 The basic @samp{MATCH_} expressions can be combined using these
992 logical operators, which have the semantics of the C operators
993 @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively. As
994 in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
995 arbitrary number of arguments; this has exactly the same effect as
996 writing a chain of two-argument @code{AND} or @code{IOR} expressions.
997 @end table
998
999 @item
1000 An optional block of C code, which should execute
1001 @samp{@w{return true}} if the predicate is found to match and
1002 @samp{@w{return false}} if it does not. It must not have any side
1003 effects. The predicate arguments, @var{op} and @var{mode}, are
1004 available with those names.
1005
1006 If a code block is present in a predicate definition, then the RTL
1007 expression must evaluate to true @emph{and} the code block must
1008 execute @samp{@w{return true}} for the predicate to allow the operand.
1009 The RTL expression is evaluated first; do not re-check anything in the
1010 code block that was checked in the RTL expression.
1011 @end itemize
1012
1013 The program @command{genrecog} scans @code{define_predicate} and
1014 @code{define_special_predicate} expressions to determine which RTX
1015 codes are possibly allowed. You should always make this explicit in
1016 the RTL predicate expression, using @code{MATCH_OPERAND} and
1017 @code{MATCH_CODE}.
1018
1019 Here is an example of a simple predicate definition, from the IA64
1020 machine description:
1021
1022 @smallexample
1023 @group
1024 ;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.}
1025 (define_predicate "small_addr_symbolic_operand"
1026 (and (match_code "symbol_ref")
1027 (match_test "SYMBOL_REF_SMALL_ADDR_P (op)")))
1028 @end group
1029 @end smallexample
1030
1031 @noindent
1032 And here is another, showing the use of the C block.
1033
1034 @smallexample
1035 @group
1036 ;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.}
1037 (define_predicate "gr_register_operand"
1038 (match_operand 0 "register_operand")
1039 @{
1040 unsigned int regno;
1041 if (GET_CODE (op) == SUBREG)
1042 op = SUBREG_REG (op);
1043
1044 regno = REGNO (op);
1045 return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno));
1046 @})
1047 @end group
1048 @end smallexample
1049
1050 Predicates written with @code{define_predicate} automatically include
1051 a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same
1052 mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
1053 @code{CONST_DOUBLE}. They do @emph{not} check specifically for
1054 integer @code{CONST_DOUBLE}, nor do they test that the value of either
1055 kind of constant fits in the requested mode. This is because
1056 target-specific predicates that take constants usually have to do more
1057 stringent value checks anyway. If you need the exact same treatment
1058 of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
1059 provide, use a @code{MATCH_OPERAND} subexpression to call
1060 @code{const_int_operand}, @code{const_double_operand}, or
1061 @code{immediate_operand}.
1062
1063 Predicates written with @code{define_special_predicate} do not get any
1064 automatic mode checks, and are treated as having special mode handling
1065 by @command{genrecog}.
1066
1067 The program @command{genpreds} is responsible for generating code to
1068 test predicates. It also writes a header file containing function
1069 declarations for all machine-specific predicates. It is not necessary
1070 to declare these predicates in @file{@var{cpu}-protos.h}.
1071 @end ifset
1072
1073 @c Most of this node appears by itself (in a different place) even
1074 @c when the INTERNALS flag is clear. Passages that require the internals
1075 @c manual's context are conditionalized to appear only in the internals manual.
1076 @ifset INTERNALS
1077 @node Constraints
1078 @section Operand Constraints
1079 @cindex operand constraints
1080 @cindex constraints
1081
1082 Each @code{match_operand} in an instruction pattern can specify
1083 constraints for the operands allowed. The constraints allow you to
1084 fine-tune matching within the set of operands allowed by the
1085 predicate.
1086
1087 @end ifset
1088 @ifclear INTERNALS
1089 @node Constraints
1090 @section Constraints for @code{asm} Operands
1091 @cindex operand constraints, @code{asm}
1092 @cindex constraints, @code{asm}
1093 @cindex @code{asm} constraints
1094
1095 Here are specific details on what constraint letters you can use with
1096 @code{asm} operands.
1097 @end ifclear
1098 Constraints can say whether
1099 an operand may be in a register, and which kinds of register; whether the
1100 operand can be a memory reference, and which kinds of address; whether the
1101 operand may be an immediate constant, and which possible values it may
1102 have. Constraints can also require two operands to match.
1103 Side-effects aren't allowed in operands of inline @code{asm}, unless
1104 @samp{<} or @samp{>} constraints are used, because there is no guarantee
1105 that the side effects will happen exactly once in an instruction that can update
1106 the addressing register.
1107
1108 @ifset INTERNALS
1109 @menu
1110 * Simple Constraints:: Basic use of constraints.
1111 * Multi-Alternative:: When an insn has two alternative constraint-patterns.
1112 * Class Preferences:: Constraints guide which hard register to put things in.
1113 * Modifiers:: More precise control over effects of constraints.
1114 * Machine Constraints:: Existing constraints for some particular machines.
1115 * Disable Insn Alternatives:: Disable insn alternatives using attributes.
1116 * Define Constraints:: How to define machine-specific constraints.
1117 * C Constraint Interface:: How to test constraints from C code.
1118 @end menu
1119 @end ifset
1120
1121 @ifclear INTERNALS
1122 @menu
1123 * Simple Constraints:: Basic use of constraints.
1124 * Multi-Alternative:: When an insn has two alternative constraint-patterns.
1125 * Modifiers:: More precise control over effects of constraints.
1126 * Machine Constraints:: Special constraints for some particular machines.
1127 @end menu
1128 @end ifclear
1129
1130 @node Simple Constraints
1131 @subsection Simple Constraints
1132 @cindex simple constraints
1133
1134 The simplest kind of constraint is a string full of letters, each of
1135 which describes one kind of operand that is permitted. Here are
1136 the letters that are allowed:
1137
1138 @table @asis
1139 @item whitespace
1140 Whitespace characters are ignored and can be inserted at any position
1141 except the first. This enables each alternative for different operands to
1142 be visually aligned in the machine description even if they have different
1143 number of constraints and modifiers.
1144
1145 @cindex @samp{m} in constraint
1146 @cindex memory references in constraints
1147 @item @samp{m}
1148 A memory operand is allowed, with any kind of address that the machine
1149 supports in general.
1150 Note that the letter used for the general memory constraint can be
1151 re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro.
1152
1153 @cindex offsettable address
1154 @cindex @samp{o} in constraint
1155 @item @samp{o}
1156 A memory operand is allowed, but only if the address is
1157 @dfn{offsettable}. This means that adding a small integer (actually,
1158 the width in bytes of the operand, as determined by its machine mode)
1159 may be added to the address and the result is also a valid memory
1160 address.
1161
1162 @cindex autoincrement/decrement addressing
1163 For example, an address which is constant is offsettable; so is an
1164 address that is the sum of a register and a constant (as long as a
1165 slightly larger constant is also within the range of address-offsets
1166 supported by the machine); but an autoincrement or autodecrement
1167 address is not offsettable. More complicated indirect/indexed
1168 addresses may or may not be offsettable depending on the other
1169 addressing modes that the machine supports.
1170
1171 Note that in an output operand which can be matched by another
1172 operand, the constraint letter @samp{o} is valid only when accompanied
1173 by both @samp{<} (if the target machine has predecrement addressing)
1174 and @samp{>} (if the target machine has preincrement addressing).
1175
1176 @cindex @samp{V} in constraint
1177 @item @samp{V}
1178 A memory operand that is not offsettable. In other words, anything that
1179 would fit the @samp{m} constraint but not the @samp{o} constraint.
1180
1181 @cindex @samp{<} in constraint
1182 @item @samp{<}
1183 A memory operand with autodecrement addressing (either predecrement or
1184 postdecrement) is allowed. In inline @code{asm} this constraint is only
1185 allowed if the operand is used exactly once in an instruction that can
1186 handle the side effects. Not using an operand with @samp{<} in constraint
1187 string in the inline @code{asm} pattern at all or using it in multiple
1188 instructions isn't valid, because the side effects wouldn't be performed
1189 or would be performed more than once. Furthermore, on some targets
1190 the operand with @samp{<} in constraint string must be accompanied by
1191 special instruction suffixes like @code{%U0} instruction suffix on PowerPC
1192 or @code{%P0} on IA-64.
1193
1194 @cindex @samp{>} in constraint
1195 @item @samp{>}
1196 A memory operand with autoincrement addressing (either preincrement or
1197 postincrement) is allowed. In inline @code{asm} the same restrictions
1198 as for @samp{<} apply.
1199
1200 @cindex @samp{r} in constraint
1201 @cindex registers in constraints
1202 @item @samp{r}
1203 A register operand is allowed provided that it is in a general
1204 register.
1205
1206 @cindex constants in constraints
1207 @cindex @samp{i} in constraint
1208 @item @samp{i}
1209 An immediate integer operand (one with constant value) is allowed.
1210 This includes symbolic constants whose values will be known only at
1211 assembly time or later.
1212
1213 @cindex @samp{n} in constraint
1214 @item @samp{n}
1215 An immediate integer operand with a known numeric value is allowed.
1216 Many systems cannot support assembly-time constants for operands less
1217 than a word wide. Constraints for these operands should use @samp{n}
1218 rather than @samp{i}.
1219
1220 @cindex @samp{I} in constraint
1221 @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
1222 Other letters in the range @samp{I} through @samp{P} may be defined in
1223 a machine-dependent fashion to permit immediate integer operands with
1224 explicit integer values in specified ranges. For example, on the
1225 68000, @samp{I} is defined to stand for the range of values 1 to 8.
1226 This is the range permitted as a shift count in the shift
1227 instructions.
1228
1229 @cindex @samp{E} in constraint
1230 @item @samp{E}
1231 An immediate floating operand (expression code @code{const_double}) is
1232 allowed, but only if the target floating point format is the same as
1233 that of the host machine (on which the compiler is running).
1234
1235 @cindex @samp{F} in constraint
1236 @item @samp{F}
1237 An immediate floating operand (expression code @code{const_double} or
1238 @code{const_vector}) is allowed.
1239
1240 @cindex @samp{G} in constraint
1241 @cindex @samp{H} in constraint
1242 @item @samp{G}, @samp{H}
1243 @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
1244 permit immediate floating operands in particular ranges of values.
1245
1246 @cindex @samp{s} in constraint
1247 @item @samp{s}
1248 An immediate integer operand whose value is not an explicit integer is
1249 allowed.
1250
1251 This might appear strange; if an insn allows a constant operand with a
1252 value not known at compile time, it certainly must allow any known
1253 value. So why use @samp{s} instead of @samp{i}? Sometimes it allows
1254 better code to be generated.
1255
1256 For example, on the 68000 in a fullword instruction it is possible to
1257 use an immediate operand; but if the immediate value is between @minus{}128
1258 and 127, better code results from loading the value into a register and
1259 using the register. This is because the load into the register can be
1260 done with a @samp{moveq} instruction. We arrange for this to happen
1261 by defining the letter @samp{K} to mean ``any integer outside the
1262 range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
1263 constraints.
1264
1265 @cindex @samp{g} in constraint
1266 @item @samp{g}
1267 Any register, memory or immediate integer operand is allowed, except for
1268 registers that are not general registers.
1269
1270 @cindex @samp{X} in constraint
1271 @item @samp{X}
1272 @ifset INTERNALS
1273 Any operand whatsoever is allowed, even if it does not satisfy
1274 @code{general_operand}. This is normally used in the constraint of
1275 a @code{match_scratch} when certain alternatives will not actually
1276 require a scratch register.
1277 @end ifset
1278 @ifclear INTERNALS
1279 Any operand whatsoever is allowed.
1280 @end ifclear
1281
1282 @cindex @samp{0} in constraint
1283 @cindex digits in constraint
1284 @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
1285 An operand that matches the specified operand number is allowed. If a
1286 digit is used together with letters within the same alternative, the
1287 digit should come last.
1288
1289 This number is allowed to be more than a single digit. If multiple
1290 digits are encountered consecutively, they are interpreted as a single
1291 decimal integer. There is scant chance for ambiguity, since to-date
1292 it has never been desirable that @samp{10} be interpreted as matching
1293 either operand 1 @emph{or} operand 0. Should this be desired, one
1294 can use multiple alternatives instead.
1295
1296 @cindex matching constraint
1297 @cindex constraint, matching
1298 This is called a @dfn{matching constraint} and what it really means is
1299 that the assembler has only a single operand that fills two roles
1300 @ifset INTERNALS
1301 considered separate in the RTL insn. For example, an add insn has two
1302 input operands and one output operand in the RTL, but on most CISC
1303 @end ifset
1304 @ifclear INTERNALS
1305 which @code{asm} distinguishes. For example, an add instruction uses
1306 two input operands and an output operand, but on most CISC
1307 @end ifclear
1308 machines an add instruction really has only two operands, one of them an
1309 input-output operand:
1310
1311 @smallexample
1312 addl #35,r12
1313 @end smallexample
1314
1315 Matching constraints are used in these circumstances.
1316 More precisely, the two operands that match must include one input-only
1317 operand and one output-only operand. Moreover, the digit must be a
1318 smaller number than the number of the operand that uses it in the
1319 constraint.
1320
1321 @ifset INTERNALS
1322 For operands to match in a particular case usually means that they
1323 are identical-looking RTL expressions. But in a few special cases
1324 specific kinds of dissimilarity are allowed. For example, @code{*x}
1325 as an input operand will match @code{*x++} as an output operand.
1326 For proper results in such cases, the output template should always
1327 use the output-operand's number when printing the operand.
1328 @end ifset
1329
1330 @cindex load address instruction
1331 @cindex push address instruction
1332 @cindex address constraints
1333 @cindex @samp{p} in constraint
1334 @item @samp{p}
1335 An operand that is a valid memory address is allowed. This is
1336 for ``load address'' and ``push address'' instructions.
1337
1338 @findex address_operand
1339 @samp{p} in the constraint must be accompanied by @code{address_operand}
1340 as the predicate in the @code{match_operand}. This predicate interprets
1341 the mode specified in the @code{match_operand} as the mode of the memory
1342 reference for which the address would be valid.
1343
1344 @cindex other register constraints
1345 @cindex extensible constraints
1346 @item @var{other-letters}
1347 Other letters can be defined in machine-dependent fashion to stand for
1348 particular classes of registers or other arbitrary operand types.
1349 @samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
1350 for data, address and floating point registers.
1351 @end table
1352
1353 @ifset INTERNALS
1354 In order to have valid assembler code, each operand must satisfy
1355 its constraint. But a failure to do so does not prevent the pattern
1356 from applying to an insn. Instead, it directs the compiler to modify
1357 the code so that the constraint will be satisfied. Usually this is
1358 done by copying an operand into a register.
1359
1360 Contrast, therefore, the two instruction patterns that follow:
1361
1362 @smallexample
1363 (define_insn ""
1364 [(set (match_operand:SI 0 "general_operand" "=r")
1365 (plus:SI (match_dup 0)
1366 (match_operand:SI 1 "general_operand" "r")))]
1367 ""
1368 "@dots{}")
1369 @end smallexample
1370
1371 @noindent
1372 which has two operands, one of which must appear in two places, and
1373
1374 @smallexample
1375 (define_insn ""
1376 [(set (match_operand:SI 0 "general_operand" "=r")
1377 (plus:SI (match_operand:SI 1 "general_operand" "0")
1378 (match_operand:SI 2 "general_operand" "r")))]
1379 ""
1380 "@dots{}")
1381 @end smallexample
1382
1383 @noindent
1384 which has three operands, two of which are required by a constraint to be
1385 identical. If we are considering an insn of the form
1386
1387 @smallexample
1388 (insn @var{n} @var{prev} @var{next}
1389 (set (reg:SI 3)
1390 (plus:SI (reg:SI 6) (reg:SI 109)))
1391 @dots{})
1392 @end smallexample
1393
1394 @noindent
1395 the first pattern would not apply at all, because this insn does not
1396 contain two identical subexpressions in the right place. The pattern would
1397 say, ``That does not look like an add instruction; try other patterns''.
1398 The second pattern would say, ``Yes, that's an add instruction, but there
1399 is something wrong with it''. It would direct the reload pass of the
1400 compiler to generate additional insns to make the constraint true. The
1401 results might look like this:
1402
1403 @smallexample
1404 (insn @var{n2} @var{prev} @var{n}
1405 (set (reg:SI 3) (reg:SI 6))
1406 @dots{})
1407
1408 (insn @var{n} @var{n2} @var{next}
1409 (set (reg:SI 3)
1410 (plus:SI (reg:SI 3) (reg:SI 109)))
1411 @dots{})
1412 @end smallexample
1413
1414 It is up to you to make sure that each operand, in each pattern, has
1415 constraints that can handle any RTL expression that could be present for
1416 that operand. (When multiple alternatives are in use, each pattern must,
1417 for each possible combination of operand expressions, have at least one
1418 alternative which can handle that combination of operands.) The
1419 constraints don't need to @emph{allow} any possible operand---when this is
1420 the case, they do not constrain---but they must at least point the way to
1421 reloading any possible operand so that it will fit.
1422
1423 @itemize @bullet
1424 @item
1425 If the constraint accepts whatever operands the predicate permits,
1426 there is no problem: reloading is never necessary for this operand.
1427
1428 For example, an operand whose constraints permit everything except
1429 registers is safe provided its predicate rejects registers.
1430
1431 An operand whose predicate accepts only constant values is safe
1432 provided its constraints include the letter @samp{i}. If any possible
1433 constant value is accepted, then nothing less than @samp{i} will do;
1434 if the predicate is more selective, then the constraints may also be
1435 more selective.
1436
1437 @item
1438 Any operand expression can be reloaded by copying it into a register.
1439 So if an operand's constraints allow some kind of register, it is
1440 certain to be safe. It need not permit all classes of registers; the
1441 compiler knows how to copy a register into another register of the
1442 proper class in order to make an instruction valid.
1443
1444 @cindex nonoffsettable memory reference
1445 @cindex memory reference, nonoffsettable
1446 @item
1447 A nonoffsettable memory reference can be reloaded by copying the
1448 address into a register. So if the constraint uses the letter
1449 @samp{o}, all memory references are taken care of.
1450
1451 @item
1452 A constant operand can be reloaded by allocating space in memory to
1453 hold it as preinitialized data. Then the memory reference can be used
1454 in place of the constant. So if the constraint uses the letters
1455 @samp{o} or @samp{m}, constant operands are not a problem.
1456
1457 @item
1458 If the constraint permits a constant and a pseudo register used in an insn
1459 was not allocated to a hard register and is equivalent to a constant,
1460 the register will be replaced with the constant. If the predicate does
1461 not permit a constant and the insn is re-recognized for some reason, the
1462 compiler will crash. Thus the predicate must always recognize any
1463 objects allowed by the constraint.
1464 @end itemize
1465
1466 If the operand's predicate can recognize registers, but the constraint does
1467 not permit them, it can make the compiler crash. When this operand happens
1468 to be a register, the reload pass will be stymied, because it does not know
1469 how to copy a register temporarily into memory.
1470
1471 If the predicate accepts a unary operator, the constraint applies to the
1472 operand. For example, the MIPS processor at ISA level 3 supports an
1473 instruction which adds two registers in @code{SImode} to produce a
1474 @code{DImode} result, but only if the registers are correctly sign
1475 extended. This predicate for the input operands accepts a
1476 @code{sign_extend} of an @code{SImode} register. Write the constraint
1477 to indicate the type of register that is required for the operand of the
1478 @code{sign_extend}.
1479 @end ifset
1480
1481 @node Multi-Alternative
1482 @subsection Multiple Alternative Constraints
1483 @cindex multiple alternative constraints
1484
1485 Sometimes a single instruction has multiple alternative sets of possible
1486 operands. For example, on the 68000, a logical-or instruction can combine
1487 register or an immediate value into memory, or it can combine any kind of
1488 operand into a register; but it cannot combine one memory location into
1489 another.
1490
1491 These constraints are represented as multiple alternatives. An alternative
1492 can be described by a series of letters for each operand. The overall
1493 constraint for an operand is made from the letters for this operand
1494 from the first alternative, a comma, the letters for this operand from
1495 the second alternative, a comma, and so on until the last alternative.
1496 All operands for a single instruction must have the same number of
1497 alternatives.
1498 @ifset INTERNALS
1499 Here is how it is done for fullword logical-or on the 68000:
1500
1501 @smallexample
1502 (define_insn "iorsi3"
1503 [(set (match_operand:SI 0 "general_operand" "=m,d")
1504 (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
1505 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
1506 @dots{})
1507 @end smallexample
1508
1509 The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
1510 operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
1511 2. The second alternative has @samp{d} (data register) for operand 0,
1512 @samp{0} for operand 1, and @samp{dmKs} for operand 2. The @samp{=} and
1513 @samp{%} in the constraints apply to all the alternatives; their
1514 meaning is explained in the next section (@pxref{Class Preferences}).
1515
1516 If all the operands fit any one alternative, the instruction is valid.
1517 Otherwise, for each alternative, the compiler counts how many instructions
1518 must be added to copy the operands so that that alternative applies.
1519 The alternative requiring the least copying is chosen. If two alternatives
1520 need the same amount of copying, the one that comes first is chosen.
1521 These choices can be altered with the @samp{?} and @samp{!} characters:
1522
1523 @table @code
1524 @cindex @samp{?} in constraint
1525 @cindex question mark
1526 @item ?
1527 Disparage slightly the alternative that the @samp{?} appears in,
1528 as a choice when no alternative applies exactly. The compiler regards
1529 this alternative as one unit more costly for each @samp{?} that appears
1530 in it.
1531
1532 @cindex @samp{!} in constraint
1533 @cindex exclamation point
1534 @item !
1535 Disparage severely the alternative that the @samp{!} appears in.
1536 This alternative can still be used if it fits without reloading,
1537 but if reloading is needed, some other alternative will be used.
1538
1539 @cindex @samp{^} in constraint
1540 @cindex caret
1541 @item ^
1542 This constraint is analogous to @samp{?} but it disparages slightly
1543 the alternative only if the operand with the @samp{^} needs a reload.
1544
1545 @cindex @samp{$} in constraint
1546 @cindex dollar sign
1547 @item $
1548 This constraint is analogous to @samp{!} but it disparages severely
1549 the alternative only if the operand with the @samp{$} needs a reload.
1550 @end table
1551
1552 When an insn pattern has multiple alternatives in its constraints, often
1553 the appearance of the assembler code is determined mostly by which
1554 alternative was matched. When this is so, the C code for writing the
1555 assembler code can use the variable @code{which_alternative}, which is
1556 the ordinal number of the alternative that was actually satisfied (0 for
1557 the first, 1 for the second alternative, etc.). @xref{Output Statement}.
1558 @end ifset
1559 @ifclear INTERNALS
1560
1561 So the first alternative for the 68000's logical-or could be written as
1562 @code{"+m" (output) : "ir" (input)}. The second could be @code{"+r"
1563 (output): "irm" (input)}. However, the fact that two memory locations
1564 cannot be used in a single instruction prevents simply using @code{"+rm"
1565 (output) : "irm" (input)}. Using multi-alternatives, this might be
1566 written as @code{"+m,r" (output) : "ir,irm" (input)}. This describes
1567 all the available alternatives to the compiler, allowing it to choose
1568 the most efficient one for the current conditions.
1569
1570 There is no way within the template to determine which alternative was
1571 chosen. However you may be able to wrap your @code{asm} statements with
1572 builtins such as @code{__builtin_constant_p} to achieve the desired results.
1573 @end ifclear
1574
1575 @ifset INTERNALS
1576 @node Class Preferences
1577 @subsection Register Class Preferences
1578 @cindex class preference constraints
1579 @cindex register class preference constraints
1580
1581 @cindex voting between constraint alternatives
1582 The operand constraints have another function: they enable the compiler
1583 to decide which kind of hardware register a pseudo register is best
1584 allocated to. The compiler examines the constraints that apply to the
1585 insns that use the pseudo register, looking for the machine-dependent
1586 letters such as @samp{d} and @samp{a} that specify classes of registers.
1587 The pseudo register is put in whichever class gets the most ``votes''.
1588 The constraint letters @samp{g} and @samp{r} also vote: they vote in
1589 favor of a general register. The machine description says which registers
1590 are considered general.
1591
1592 Of course, on some machines all registers are equivalent, and no register
1593 classes are defined. Then none of this complexity is relevant.
1594 @end ifset
1595
1596 @node Modifiers
1597 @subsection Constraint Modifier Characters
1598 @cindex modifiers in constraints
1599 @cindex constraint modifier characters
1600
1601 @c prevent bad page break with this line
1602 Here are constraint modifier characters.
1603
1604 @table @samp
1605 @cindex @samp{=} in constraint
1606 @item =
1607 Means that this operand is written to by this instruction:
1608 the previous value is discarded and replaced by new data.
1609
1610 @cindex @samp{+} in constraint
1611 @item +
1612 Means that this operand is both read and written by the instruction.
1613
1614 When the compiler fixes up the operands to satisfy the constraints,
1615 it needs to know which operands are read by the instruction and
1616 which are written by it. @samp{=} identifies an operand which is only
1617 written; @samp{+} identifies an operand that is both read and written; all
1618 other operands are assumed to only be read.
1619
1620 If you specify @samp{=} or @samp{+} in a constraint, you put it in the
1621 first character of the constraint string.
1622
1623 @cindex @samp{&} in constraint
1624 @cindex earlyclobber operand
1625 @item &
1626 Means (in a particular alternative) that this operand is an
1627 @dfn{earlyclobber} operand, which is written before the instruction is
1628 finished using the input operands. Therefore, this operand may not lie
1629 in a register that is read by the instruction or as part of any memory
1630 address.
1631
1632 @samp{&} applies only to the alternative in which it is written. In
1633 constraints with multiple alternatives, sometimes one alternative
1634 requires @samp{&} while others do not. See, for example, the
1635 @samp{movdf} insn of the 68000.
1636
1637 An operand which is read by the instruction can be tied to an earlyclobber
1638 operand if its only use as an input occurs before the early result is
1639 written. Adding alternatives of this form often allows GCC to produce
1640 better code when only some of the read operands can be affected by the
1641 earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@.
1642
1643 Furthermore, if the @dfn{earlyclobber} operand is also a read/write
1644 operand, then that operand is written only after it's used.
1645
1646 @samp{&} does not obviate the need to write @samp{=} or @samp{+}. As
1647 @dfn{earlyclobber} operands are always written, a read-only
1648 @dfn{earlyclobber} operand is ill-formed and will be rejected by the
1649 compiler.
1650
1651 @cindex @samp{%} in constraint
1652 @item %
1653 Declares the instruction to be commutative for this operand and the
1654 following operand. This means that the compiler may interchange the
1655 two operands if that is the cheapest way to make all operands fit the
1656 constraints. @samp{%} applies to all alternatives and must appear as
1657 the first character in the constraint. Only read-only operands can use
1658 @samp{%}.
1659
1660 @ifset INTERNALS
1661 This is often used in patterns for addition instructions
1662 that really have only two operands: the result must go in one of the
1663 arguments. Here for example, is how the 68000 halfword-add
1664 instruction is defined:
1665
1666 @smallexample
1667 (define_insn "addhi3"
1668 [(set (match_operand:HI 0 "general_operand" "=m,r")
1669 (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
1670 (match_operand:HI 2 "general_operand" "di,g")))]
1671 @dots{})
1672 @end smallexample
1673 @end ifset
1674 GCC can only handle one commutative pair in an asm; if you use more,
1675 the compiler may fail. Note that you need not use the modifier if
1676 the two alternatives are strictly identical; this would only waste
1677 time in the reload pass.
1678 @ifset INTERNALS
1679 The modifier is not operational after
1680 register allocation, so the result of @code{define_peephole2}
1681 and @code{define_split}s performed after reload cannot rely on
1682 @samp{%} to make the intended insn match.
1683
1684 @cindex @samp{#} in constraint
1685 @item #
1686 Says that all following characters, up to the next comma, are to be
1687 ignored as a constraint. They are significant only for choosing
1688 register preferences.
1689
1690 @cindex @samp{*} in constraint
1691 @item *
1692 Says that the following character should be ignored when choosing
1693 register preferences. @samp{*} has no effect on the meaning of the
1694 constraint as a constraint, and no effect on reloading. For LRA
1695 @samp{*} additionally disparages slightly the alternative if the
1696 following character matches the operand.
1697
1698 Here is an example: the 68000 has an instruction to sign-extend a
1699 halfword in a data register, and can also sign-extend a value by
1700 copying it into an address register. While either kind of register is
1701 acceptable, the constraints on an address-register destination are
1702 less strict, so it is best if register allocation makes an address
1703 register its goal. Therefore, @samp{*} is used so that the @samp{d}
1704 constraint letter (for data register) is ignored when computing
1705 register preferences.
1706
1707 @smallexample
1708 (define_insn "extendhisi2"
1709 [(set (match_operand:SI 0 "general_operand" "=*d,a")
1710 (sign_extend:SI
1711 (match_operand:HI 1 "general_operand" "0,g")))]
1712 @dots{})
1713 @end smallexample
1714 @end ifset
1715 @end table
1716
1717 @node Machine Constraints
1718 @subsection Constraints for Particular Machines
1719 @cindex machine specific constraints
1720 @cindex constraints, machine specific
1721
1722 Whenever possible, you should use the general-purpose constraint letters
1723 in @code{asm} arguments, since they will convey meaning more readily to
1724 people reading your code. Failing that, use the constraint letters
1725 that usually have very similar meanings across architectures. The most
1726 commonly used constraints are @samp{m} and @samp{r} (for memory and
1727 general-purpose registers respectively; @pxref{Simple Constraints}), and
1728 @samp{I}, usually the letter indicating the most common
1729 immediate-constant format.
1730
1731 Each architecture defines additional constraints. These constraints
1732 are used by the compiler itself for instruction generation, as well as
1733 for @code{asm} statements; therefore, some of the constraints are not
1734 particularly useful for @code{asm}. Here is a summary of some of the
1735 machine-dependent constraints available on some particular machines;
1736 it includes both constraints that are useful for @code{asm} and
1737 constraints that aren't. The compiler source file mentioned in the
1738 table heading for each architecture is the definitive reference for
1739 the meanings of that architecture's constraints.
1740
1741 @c Please keep this table alphabetized by target!
1742 @table @emph
1743 @item AArch64 family---@file{config/aarch64/constraints.md}
1744 @table @code
1745 @item k
1746 The stack pointer register (@code{SP})
1747
1748 @item w
1749 Floating point register, Advanced SIMD vector register or SVE vector register
1750
1751 @item x
1752 Like @code{w}, but restricted to registers 0 to 15 inclusive.
1753
1754 @item y
1755 Like @code{w}, but restricted to registers 0 to 7 inclusive.
1756
1757 @item Upl
1758 One of the low eight SVE predicate registers (@code{P0} to @code{P7})
1759
1760 @item Upa
1761 Any of the SVE predicate registers (@code{P0} to @code{P15})
1762
1763 @item I
1764 Integer constant that is valid as an immediate operand in an @code{ADD}
1765 instruction
1766
1767 @item J
1768 Integer constant that is valid as an immediate operand in a @code{SUB}
1769 instruction (once negated)
1770
1771 @item K
1772 Integer constant that can be used with a 32-bit logical instruction
1773
1774 @item L
1775 Integer constant that can be used with a 64-bit logical instruction
1776
1777 @item M
1778 Integer constant that is valid as an immediate operand in a 32-bit @code{MOV}
1779 pseudo instruction. The @code{MOV} may be assembled to one of several different
1780 machine instructions depending on the value
1781
1782 @item N
1783 Integer constant that is valid as an immediate operand in a 64-bit @code{MOV}
1784 pseudo instruction
1785
1786 @item S
1787 An absolute symbolic address or a label reference
1788
1789 @item Y
1790 Floating point constant zero
1791
1792 @item Z
1793 Integer constant zero
1794
1795 @item Ush
1796 The high part (bits 12 and upwards) of the pc-relative address of a symbol
1797 within 4GB of the instruction
1798
1799 @item Q
1800 A memory address which uses a single base register with no offset
1801
1802 @item Ump
1803 A memory address suitable for a load/store pair instruction in SI, DI, SF and
1804 DF modes
1805
1806 @end table
1807
1808
1809 @item AMD GCN ---@file{config/gcn/constraints.md}
1810 @table @code
1811 @item I
1812 Immediate integer in the range @minus{}16 to 64
1813
1814 @item J
1815 Immediate 16-bit signed integer
1816
1817 @item Kf
1818 Immediate constant @minus{}1
1819
1820 @item L
1821 Immediate 15-bit unsigned integer
1822
1823 @item A
1824 Immediate constant that can be inlined in an instruction encoding: integer
1825 @minus{}16..64, or float 0.0, +/@minus{}0.5, +/@minus{}1.0, +/@minus{}2.0,
1826 +/@minus{}4.0, 1.0/(2.0*PI)
1827
1828 @item B
1829 Immediate 32-bit signed integer that can be attached to an instruction encoding
1830
1831 @item C
1832 Immediate 32-bit integer in range @minus{}16..4294967295 (i.e. 32-bit unsigned
1833 integer or @samp{A} constraint)
1834
1835 @item DA
1836 Immediate 64-bit constant that can be split into two @samp{A} constants
1837
1838 @item DB
1839 Immediate 64-bit constant that can be split into two @samp{B} constants
1840
1841 @item U
1842 Any @code{unspec}
1843
1844 @item Y
1845 Any @code{symbol_ref} or @code{label_ref}
1846
1847 @item v
1848 VGPR register
1849
1850 @item Sg
1851 SGPR register
1852
1853 @item SD
1854 SGPR registers valid for instruction destinations, including VCC, M0 and EXEC
1855
1856 @item SS
1857 SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC
1858
1859 @item Sm
1860 SGPR registers valid as a source for scalar memory instructions (excludes M0
1861 and EXEC)
1862
1863 @item Sv
1864 SGPR registers valid as a source or destination for vector instructions
1865 (excludes EXEC)
1866
1867 @item ca
1868 All condition registers: SCC, VCCZ, EXECZ
1869
1870 @item cs
1871 Scalar condition register: SCC
1872
1873 @item cV
1874 Vector condition register: VCC, VCC_LO, VCC_HI
1875
1876 @item e
1877 EXEC register (EXEC_LO and EXEC_HI)
1878
1879 @item RB
1880 Memory operand with address space suitable for @code{buffer_*} instructions
1881
1882 @item RF
1883 Memory operand with address space suitable for @code{flat_*} instructions
1884
1885 @item RS
1886 Memory operand with address space suitable for @code{s_*} instructions
1887
1888 @item RL
1889 Memory operand with address space suitable for @code{ds_*} LDS instructions
1890
1891 @item RG
1892 Memory operand with address space suitable for @code{ds_*} GDS instructions
1893
1894 @item RD
1895 Memory operand with address space suitable for any @code{ds_*} instructions
1896
1897 @item RM
1898 Memory operand with address space suitable for @code{global_*} instructions
1899
1900 @end table
1901
1902
1903 @item ARC ---@file{config/arc/constraints.md}
1904 @table @code
1905 @item q
1906 Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3},
1907 @code{r12}-@code{r15}. This constraint can only match when the @option{-mq}
1908 option is in effect.
1909
1910 @item e
1911 Registers usable as base-regs of memory addresses in ARCompact 16-bit memory
1912 instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}.
1913 This constraint can only match when the @option{-mq}
1914 option is in effect.
1915 @item D
1916 ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}.
1917
1918 @item I
1919 A signed 12-bit integer constant.
1920
1921 @item Cal
1922 constant for arithmetic/logical operations. This might be any constant
1923 that can be put into a long immediate by the assmbler or linker without
1924 involving a PIC relocation.
1925
1926 @item K
1927 A 3-bit unsigned integer constant.
1928
1929 @item L
1930 A 6-bit unsigned integer constant.
1931
1932 @item CnL
1933 One's complement of a 6-bit unsigned integer constant.
1934
1935 @item CmL
1936 Two's complement of a 6-bit unsigned integer constant.
1937
1938 @item M
1939 A 5-bit unsigned integer constant.
1940
1941 @item O
1942 A 7-bit unsigned integer constant.
1943
1944 @item P
1945 A 8-bit unsigned integer constant.
1946
1947 @item H
1948 Any const_double value.
1949 @end table
1950
1951 @item ARM family---@file{config/arm/constraints.md}
1952 @table @code
1953
1954 @item h
1955 In Thumb state, the core registers @code{r8}-@code{r15}.
1956
1957 @item k
1958 The stack pointer register.
1959
1960 @item l
1961 In Thumb State the core registers @code{r0}-@code{r7}. In ARM state this
1962 is an alias for the @code{r} constraint.
1963
1964 @item t
1965 VFP floating-point registers @code{s0}-@code{s31}. Used for 32 bit values.
1966
1967 @item w
1968 VFP floating-point registers @code{d0}-@code{d31} and the appropriate
1969 subset @code{d0}-@code{d15} based on command line options.
1970 Used for 64 bit values only. Not valid for Thumb1.
1971
1972 @item y
1973 The iWMMX co-processor registers.
1974
1975 @item z
1976 The iWMMX GR registers.
1977
1978 @item G
1979 The floating-point constant 0.0
1980
1981 @item I
1982 Integer that is valid as an immediate operand in a data processing
1983 instruction. That is, an integer in the range 0 to 255 rotated by a
1984 multiple of 2
1985
1986 @item J
1987 Integer in the range @minus{}4095 to 4095
1988
1989 @item K
1990 Integer that satisfies constraint @samp{I} when inverted (ones complement)
1991
1992 @item L
1993 Integer that satisfies constraint @samp{I} when negated (twos complement)
1994
1995 @item M
1996 Integer in the range 0 to 32
1997
1998 @item Q
1999 A memory reference where the exact address is in a single register
2000 (`@samp{m}' is preferable for @code{asm} statements)
2001
2002 @item R
2003 An item in the constant pool
2004
2005 @item S
2006 A symbol in the text segment of the current file
2007
2008 @item Uv
2009 A memory reference suitable for VFP load/store insns (reg+constant offset)
2010
2011 @item Uy
2012 A memory reference suitable for iWMMXt load/store instructions.
2013
2014 @item Uq
2015 A memory reference suitable for the ARMv4 ldrsb instruction.
2016 @end table
2017
2018 @item AVR family---@file{config/avr/constraints.md}
2019 @table @code
2020 @item l
2021 Registers from r0 to r15
2022
2023 @item a
2024 Registers from r16 to r23
2025
2026 @item d
2027 Registers from r16 to r31
2028
2029 @item w
2030 Registers from r24 to r31. These registers can be used in @samp{adiw} command
2031
2032 @item e
2033 Pointer register (r26--r31)
2034
2035 @item b
2036 Base pointer register (r28--r31)
2037
2038 @item q
2039 Stack pointer register (SPH:SPL)
2040
2041 @item t
2042 Temporary register r0
2043
2044 @item x
2045 Register pair X (r27:r26)
2046
2047 @item y
2048 Register pair Y (r29:r28)
2049
2050 @item z
2051 Register pair Z (r31:r30)
2052
2053 @item I
2054 Constant greater than @minus{}1, less than 64
2055
2056 @item J
2057 Constant greater than @minus{}64, less than 1
2058
2059 @item K
2060 Constant integer 2
2061
2062 @item L
2063 Constant integer 0
2064
2065 @item M
2066 Constant that fits in 8 bits
2067
2068 @item N
2069 Constant integer @minus{}1
2070
2071 @item O
2072 Constant integer 8, 16, or 24
2073
2074 @item P
2075 Constant integer 1
2076
2077 @item G
2078 A floating point constant 0.0
2079
2080 @item Q
2081 A memory address based on Y or Z pointer with displacement.
2082 @end table
2083
2084 @item Blackfin family---@file{config/bfin/constraints.md}
2085 @table @code
2086 @item a
2087 P register
2088
2089 @item d
2090 D register
2091
2092 @item z
2093 A call clobbered P register.
2094
2095 @item q@var{n}
2096 A single register. If @var{n} is in the range 0 to 7, the corresponding D
2097 register. If it is @code{A}, then the register P0.
2098
2099 @item D
2100 Even-numbered D register
2101
2102 @item W
2103 Odd-numbered D register
2104
2105 @item e
2106 Accumulator register.
2107
2108 @item A
2109 Even-numbered accumulator register.
2110
2111 @item B
2112 Odd-numbered accumulator register.
2113
2114 @item b
2115 I register
2116
2117 @item v
2118 B register
2119
2120 @item f
2121 M register
2122
2123 @item c
2124 Registers used for circular buffering, i.e.@: I, B, or L registers.
2125
2126 @item C
2127 The CC register.
2128
2129 @item t
2130 LT0 or LT1.
2131
2132 @item k
2133 LC0 or LC1.
2134
2135 @item u
2136 LB0 or LB1.
2137
2138 @item x
2139 Any D, P, B, M, I or L register.
2140
2141 @item y
2142 Additional registers typically used only in prologues and epilogues: RETS,
2143 RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP.
2144
2145 @item w
2146 Any register except accumulators or CC.
2147
2148 @item Ksh
2149 Signed 16 bit integer (in the range @minus{}32768 to 32767)
2150
2151 @item Kuh
2152 Unsigned 16 bit integer (in the range 0 to 65535)
2153
2154 @item Ks7
2155 Signed 7 bit integer (in the range @minus{}64 to 63)
2156
2157 @item Ku7
2158 Unsigned 7 bit integer (in the range 0 to 127)
2159
2160 @item Ku5
2161 Unsigned 5 bit integer (in the range 0 to 31)
2162
2163 @item Ks4
2164 Signed 4 bit integer (in the range @minus{}8 to 7)
2165
2166 @item Ks3
2167 Signed 3 bit integer (in the range @minus{}3 to 4)
2168
2169 @item Ku3
2170 Unsigned 3 bit integer (in the range 0 to 7)
2171
2172 @item P@var{n}
2173 Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4.
2174
2175 @item PA
2176 An integer equal to one of the MACFLAG_XXX constants that is suitable for
2177 use with either accumulator.
2178
2179 @item PB
2180 An integer equal to one of the MACFLAG_XXX constants that is suitable for
2181 use only with accumulator A1.
2182
2183 @item M1
2184 Constant 255.
2185
2186 @item M2
2187 Constant 65535.
2188
2189 @item J
2190 An integer constant with exactly a single bit set.
2191
2192 @item L
2193 An integer constant with all bits set except exactly one.
2194
2195 @item H
2196
2197 @item Q
2198 Any SYMBOL_REF.
2199 @end table
2200
2201 @item CR16 Architecture---@file{config/cr16/cr16.h}
2202 @table @code
2203
2204 @item b
2205 Registers from r0 to r14 (registers without stack pointer)
2206
2207 @item t
2208 Register from r0 to r11 (all 16-bit registers)
2209
2210 @item p
2211 Register from r12 to r15 (all 32-bit registers)
2212
2213 @item I
2214 Signed constant that fits in 4 bits
2215
2216 @item J
2217 Signed constant that fits in 5 bits
2218
2219 @item K
2220 Signed constant that fits in 6 bits
2221
2222 @item L
2223 Unsigned constant that fits in 4 bits
2224
2225 @item M
2226 Signed constant that fits in 32 bits
2227
2228 @item N
2229 Check for 64 bits wide constants for add/sub instructions
2230
2231 @item G
2232 Floating point constant that is legal for store immediate
2233 @end table
2234
2235 @item C-SKY---@file{config/csky/constraints.md}
2236 @table @code
2237
2238 @item a
2239 The mini registers r0 - r7.
2240
2241 @item b
2242 The low registers r0 - r15.
2243
2244 @item c
2245 C register.
2246
2247 @item y
2248 HI and LO registers.
2249
2250 @item l
2251 LO register.
2252
2253 @item h
2254 HI register.
2255
2256 @item v
2257 Vector registers.
2258
2259 @item z
2260 Stack pointer register (SP).
2261
2262 @item Q
2263 A memory address which uses a base register with a short offset
2264 or with a index register with its scale.
2265
2266 @item W
2267 A memory address which uses a base register with a index register
2268 with its scale.
2269 @end table
2270
2271 @ifset INTERNALS
2272 The C-SKY back end supports a large set of additional constraints
2273 that are only useful for instruction selection or splitting rather
2274 than inline asm, such as constraints representing constant integer
2275 ranges accepted by particular instruction encodings.
2276 Refer to the source code for details.
2277 @end ifset
2278
2279 @item Epiphany---@file{config/epiphany/constraints.md}
2280 @table @code
2281 @item U16
2282 An unsigned 16-bit constant.
2283
2284 @item K
2285 An unsigned 5-bit constant.
2286
2287 @item L
2288 A signed 11-bit constant.
2289
2290 @item Cm1
2291 A signed 11-bit constant added to @minus{}1.
2292 Can only match when the @option{-m1reg-@var{reg}} option is active.
2293
2294 @item Cl1
2295 Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
2296 being a block of trailing zeroes.
2297 Can only match when the @option{-m1reg-@var{reg}} option is active.
2298
2299 @item Cr1
2300 Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
2301 rest being zeroes. Or to put it another way, one less than a power of two.
2302 Can only match when the @option{-m1reg-@var{reg}} option is active.
2303
2304 @item Cal
2305 Constant for arithmetic/logical operations.
2306 This is like @code{i}, except that for position independent code,
2307 no symbols / expressions needing relocations are allowed.
2308
2309 @item Csy
2310 Symbolic constant for call/jump instruction.
2311
2312 @item Rcs
2313 The register class usable in short insns. This is a register class
2314 constraint, and can thus drive register allocation.
2315 This constraint won't match unless @option{-mprefer-short-insn-regs} is
2316 in effect.
2317
2318 @item Rsc
2319 The the register class of registers that can be used to hold a
2320 sibcall call address. I.e., a caller-saved register.
2321
2322 @item Rct
2323 Core control register class.
2324
2325 @item Rgs
2326 The register group usable in short insns.
2327 This constraint does not use a register class, so that it only
2328 passively matches suitable registers, and doesn't drive register allocation.
2329
2330 @ifset INTERNALS
2331 @item Car
2332 Constant suitable for the addsi3_r pattern. This is a valid offset
2333 For byte, halfword, or word addressing.
2334 @end ifset
2335
2336 @item Rra
2337 Matches the return address if it can be replaced with the link register.
2338
2339 @item Rcc
2340 Matches the integer condition code register.
2341
2342 @item Sra
2343 Matches the return address if it is in a stack slot.
2344
2345 @item Cfm
2346 Matches control register values to switch fp mode, which are encapsulated in
2347 @code{UNSPEC_FP_MODE}.
2348 @end table
2349
2350 @item FRV---@file{config/frv/frv.h}
2351 @table @code
2352 @item a
2353 Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
2354
2355 @item b
2356 Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
2357
2358 @item c
2359 Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
2360 @code{icc0} to @code{icc3}).
2361
2362 @item d
2363 Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
2364
2365 @item e
2366 Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
2367 Odd registers are excluded not in the class but through the use of a machine
2368 mode larger than 4 bytes.
2369
2370 @item f
2371 Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
2372
2373 @item h
2374 Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
2375 Odd registers are excluded not in the class but through the use of a machine
2376 mode larger than 4 bytes.
2377
2378 @item l
2379 Register in the class @code{LR_REG} (the @code{lr} register).
2380
2381 @item q
2382 Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
2383 Register numbers not divisible by 4 are excluded not in the class but through
2384 the use of a machine mode larger than 8 bytes.
2385
2386 @item t
2387 Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
2388
2389 @item u
2390 Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
2391
2392 @item v
2393 Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
2394
2395 @item w
2396 Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
2397
2398 @item x
2399 Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
2400 Register numbers not divisible by 4 are excluded not in the class but through
2401 the use of a machine mode larger than 8 bytes.
2402
2403 @item z
2404 Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
2405
2406 @item A
2407 Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
2408
2409 @item B
2410 Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
2411
2412 @item C
2413 Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
2414
2415 @item G
2416 Floating point constant zero
2417
2418 @item I
2419 6-bit signed integer constant
2420
2421 @item J
2422 10-bit signed integer constant
2423
2424 @item L
2425 16-bit signed integer constant
2426
2427 @item M
2428 16-bit unsigned integer constant
2429
2430 @item N
2431 12-bit signed integer constant that is negative---i.e.@: in the
2432 range of @minus{}2048 to @minus{}1
2433
2434 @item O
2435 Constant zero
2436
2437 @item P
2438 12-bit signed integer constant that is greater than zero---i.e.@: in the
2439 range of 1 to 2047.
2440
2441 @end table
2442
2443 @item FT32---@file{config/ft32/constraints.md}
2444 @table @code
2445 @item A
2446 An absolute address
2447
2448 @item B
2449 An offset address
2450
2451 @item W
2452 A register indirect memory operand
2453
2454 @item e
2455 An offset address.
2456
2457 @item f
2458 An offset address.
2459
2460 @item O
2461 The constant zero or one
2462
2463 @item I
2464 A 16-bit signed constant (@minus{}32768 @dots{} 32767)
2465
2466 @item w
2467 A bitfield mask suitable for bext or bins
2468
2469 @item x
2470 An inverted bitfield mask suitable for bext or bins
2471
2472 @item L
2473 A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532)
2474
2475 @item S
2476 A 20-bit signed constant (@minus{}524288 @dots{} 524287)
2477
2478 @item b
2479 A constant for a bitfield width (1 @dots{} 16)
2480
2481 @item KA
2482 A 10-bit signed constant (@minus{}512 @dots{} 511)
2483
2484 @end table
2485
2486 @item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
2487 @table @code
2488 @item a
2489 General register 1
2490
2491 @item f
2492 Floating point register
2493
2494 @item q
2495 Shift amount register
2496
2497 @item x
2498 Floating point register (deprecated)
2499
2500 @item y
2501 Upper floating point register (32-bit), floating point register (64-bit)
2502
2503 @item Z
2504 Any register
2505
2506 @item I
2507 Signed 11-bit integer constant
2508
2509 @item J
2510 Signed 14-bit integer constant
2511
2512 @item K
2513 Integer constant that can be deposited with a @code{zdepi} instruction
2514
2515 @item L
2516 Signed 5-bit integer constant
2517
2518 @item M
2519 Integer constant 0
2520
2521 @item N
2522 Integer constant that can be loaded with a @code{ldil} instruction
2523
2524 @item O
2525 Integer constant whose value plus one is a power of 2
2526
2527 @item P
2528 Integer constant that can be used for @code{and} operations in @code{depi}
2529 and @code{extru} instructions
2530
2531 @item S
2532 Integer constant 31
2533
2534 @item U
2535 Integer constant 63
2536
2537 @item G
2538 Floating-point constant 0.0
2539
2540 @item A
2541 A @code{lo_sum} data-linkage-table memory operand
2542
2543 @item Q
2544 A memory operand that can be used as the destination operand of an
2545 integer store instruction
2546
2547 @item R
2548 A scaled or unscaled indexed memory operand
2549
2550 @item T
2551 A memory operand for floating-point loads and stores
2552
2553 @item W
2554 A register indirect memory operand
2555 @end table
2556
2557 @item Intel IA-64---@file{config/ia64/ia64.h}
2558 @table @code
2559 @item a
2560 General register @code{r0} to @code{r3} for @code{addl} instruction
2561
2562 @item b
2563 Branch register
2564
2565 @item c
2566 Predicate register (@samp{c} as in ``conditional'')
2567
2568 @item d
2569 Application register residing in M-unit
2570
2571 @item e
2572 Application register residing in I-unit
2573
2574 @item f
2575 Floating-point register
2576
2577 @item m
2578 Memory operand. If used together with @samp{<} or @samp{>},
2579 the operand can have postincrement and postdecrement which
2580 require printing with @samp{%Pn} on IA-64.
2581
2582 @item G
2583 Floating-point constant 0.0 or 1.0
2584
2585 @item I
2586 14-bit signed integer constant
2587
2588 @item J
2589 22-bit signed integer constant
2590
2591 @item K
2592 8-bit signed integer constant for logical instructions
2593
2594 @item L
2595 8-bit adjusted signed integer constant for compare pseudo-ops
2596
2597 @item M
2598 6-bit unsigned integer constant for shift counts
2599
2600 @item N
2601 9-bit signed integer constant for load and store postincrements
2602
2603 @item O
2604 The constant zero
2605
2606 @item P
2607 0 or @minus{}1 for @code{dep} instruction
2608
2609 @item Q
2610 Non-volatile memory for floating-point loads and stores
2611
2612 @item R
2613 Integer constant in the range 1 to 4 for @code{shladd} instruction
2614
2615 @item S
2616 Memory operand except postincrement and postdecrement. This is
2617 now roughly the same as @samp{m} when not used together with @samp{<}
2618 or @samp{>}.
2619 @end table
2620
2621 @item M32C---@file{config/m32c/m32c.cc}
2622 @table @code
2623 @item Rsp
2624 @itemx Rfb
2625 @itemx Rsb
2626 @samp{$sp}, @samp{$fb}, @samp{$sb}.
2627
2628 @item Rcr
2629 Any control register, when they're 16 bits wide (nothing if control
2630 registers are 24 bits wide)
2631
2632 @item Rcl
2633 Any control register, when they're 24 bits wide.
2634
2635 @item R0w
2636 @itemx R1w
2637 @itemx R2w
2638 @itemx R3w
2639 $r0, $r1, $r2, $r3.
2640
2641 @item R02
2642 $r0 or $r2, or $r2r0 for 32 bit values.
2643
2644 @item R13
2645 $r1 or $r3, or $r3r1 for 32 bit values.
2646
2647 @item Rdi
2648 A register that can hold a 64 bit value.
2649
2650 @item Rhl
2651 $r0 or $r1 (registers with addressable high/low bytes)
2652
2653 @item R23
2654 $r2 or $r3
2655
2656 @item Raa
2657 Address registers
2658
2659 @item Raw
2660 Address registers when they're 16 bits wide.
2661
2662 @item Ral
2663 Address registers when they're 24 bits wide.
2664
2665 @item Rqi
2666 Registers that can hold QI values.
2667
2668 @item Rad
2669 Registers that can be used with displacements ($a0, $a1, $sb).
2670
2671 @item Rsi
2672 Registers that can hold 32 bit values.
2673
2674 @item Rhi
2675 Registers that can hold 16 bit values.
2676
2677 @item Rhc
2678 Registers chat can hold 16 bit values, including all control
2679 registers.
2680
2681 @item Rra
2682 $r0 through R1, plus $a0 and $a1.
2683
2684 @item Rfl
2685 The flags register.
2686
2687 @item Rmm
2688 The memory-based pseudo-registers $mem0 through $mem15.
2689
2690 @item Rpi
2691 Registers that can hold pointers (16 bit registers for r8c, m16c; 24
2692 bit registers for m32cm, m32c).
2693
2694 @item Rpa
2695 Matches multiple registers in a PARALLEL to form a larger register.
2696 Used to match function return values.
2697
2698 @item Is3
2699 @minus{}8 @dots{} 7
2700
2701 @item IS1
2702 @minus{}128 @dots{} 127
2703
2704 @item IS2
2705 @minus{}32768 @dots{} 32767
2706
2707 @item IU2
2708 0 @dots{} 65535
2709
2710 @item In4
2711 @minus{}8 @dots{} @minus{}1 or 1 @dots{} 8
2712
2713 @item In5
2714 @minus{}16 @dots{} @minus{}1 or 1 @dots{} 16
2715
2716 @item In6
2717 @minus{}32 @dots{} @minus{}1 or 1 @dots{} 32
2718
2719 @item IM2
2720 @minus{}65536 @dots{} @minus{}1
2721
2722 @item Ilb
2723 An 8 bit value with exactly one bit set.
2724
2725 @item Ilw
2726 A 16 bit value with exactly one bit set.
2727
2728 @item Sd
2729 The common src/dest memory addressing modes.
2730
2731 @item Sa
2732 Memory addressed using $a0 or $a1.
2733
2734 @item Si
2735 Memory addressed with immediate addresses.
2736
2737 @item Ss
2738 Memory addressed using the stack pointer ($sp).
2739
2740 @item Sf
2741 Memory addressed using the frame base register ($fb).
2742
2743 @item Ss
2744 Memory addressed using the small base register ($sb).
2745
2746 @item S1
2747 $r1h
2748 @end table
2749
2750 @item LoongArch---@file{config/loongarch/constraints.md}
2751 @table @code
2752 @item f
2753 A floating-point register (if available).
2754 @item k
2755 A memory operand whose address is formed by a base register and
2756 (optionally scaled) index register.
2757 @item l
2758 A signed 16-bit constant.
2759 @item m
2760 A memory operand whose address is formed by a base register and offset
2761 that is suitable for use in instructions with the same addressing mode
2762 as @code{st.w} and @code{ld.w}.
2763 @item I
2764 A signed 12-bit constant (for arithmetic instructions).
2765 @item K
2766 An unsigned 12-bit constant (for logic instructions).
2767 @item ZB
2768 An address that is held in a general-purpose register.
2769 The offset is zero.
2770 @item ZC
2771 A memory operand whose address is formed by a base register and offset
2772 that is suitable for use in instructions with the same addressing mode
2773 as @code{ll.w} and @code{sc.w}.
2774 @end table
2775
2776 @item MicroBlaze---@file{config/microblaze/constraints.md}
2777 @table @code
2778 @item d
2779 A general register (@code{r0} to @code{r31}).
2780
2781 @item z
2782 A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
2783
2784 @end table
2785
2786 @item MIPS---@file{config/mips/constraints.md}
2787 @table @code
2788 @item d
2789 A general-purpose register. This is equivalent to @code{r} unless
2790 generating MIPS16 code, in which case the MIPS16 register set is used.
2791
2792 @item f
2793 A floating-point register (if available).
2794
2795 @item h
2796 Formerly the @code{hi} register. This constraint is no longer supported.
2797
2798 @item l
2799 The @code{lo} register. Use this register to store values that are
2800 no bigger than a word.
2801
2802 @item x
2803 The concatenated @code{hi} and @code{lo} registers. Use this register
2804 to store doubleword values.
2805
2806 @item c
2807 A register suitable for use in an indirect jump. This will always be
2808 @code{$25} for @option{-mabicalls}.
2809
2810 @item v
2811 Register @code{$3}. Do not use this constraint in new code;
2812 it is retained only for compatibility with glibc.
2813
2814 @item y
2815 Equivalent to @code{r}; retained for backwards compatibility.
2816
2817 @item z
2818 A floating-point condition code register.
2819
2820 @item I
2821 A signed 16-bit constant (for arithmetic instructions).
2822
2823 @item J
2824 Integer zero.
2825
2826 @item K
2827 An unsigned 16-bit constant (for logic instructions).
2828
2829 @item L
2830 A signed 32-bit constant in which the lower 16 bits are zero.
2831 Such constants can be loaded using @code{lui}.
2832
2833 @item M
2834 A constant that cannot be loaded using @code{lui}, @code{addiu}
2835 or @code{ori}.
2836
2837 @item N
2838 A constant in the range @minus{}65535 to @minus{}1 (inclusive).
2839
2840 @item O
2841 A signed 15-bit constant.
2842
2843 @item P
2844 A constant in the range 1 to 65535 (inclusive).
2845
2846 @item G
2847 Floating-point zero.
2848
2849 @item R
2850 An address that can be used in a non-macro load or store.
2851
2852 @item ZC
2853 A memory operand whose address is formed by a base register and offset
2854 that is suitable for use in instructions with the same addressing mode
2855 as @code{ll} and @code{sc}.
2856
2857 @item ZD
2858 An address suitable for a @code{prefetch} instruction, or for any other
2859 instruction with the same addressing mode as @code{prefetch}.
2860 @end table
2861
2862 @item Motorola 680x0---@file{config/m68k/constraints.md}
2863 @table @code
2864 @item a
2865 Address register
2866
2867 @item d
2868 Data register
2869
2870 @item f
2871 68881 floating-point register, if available
2872
2873 @item I
2874 Integer in the range 1 to 8
2875
2876 @item J
2877 16-bit signed number
2878
2879 @item K
2880 Signed number whose magnitude is greater than 0x80
2881
2882 @item L
2883 Integer in the range @minus{}8 to @minus{}1
2884
2885 @item M
2886 Signed number whose magnitude is greater than 0x100
2887
2888 @item N
2889 Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate
2890
2891 @item O
2892 16 (for rotate using swap)
2893
2894 @item P
2895 Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate
2896
2897 @item R
2898 Numbers that mov3q can handle
2899
2900 @item G
2901 Floating point constant that is not a 68881 constant
2902
2903 @item S
2904 Operands that satisfy 'm' when -mpcrel is in effect
2905
2906 @item T
2907 Operands that satisfy 's' when -mpcrel is not in effect
2908
2909 @item Q
2910 Address register indirect addressing mode
2911
2912 @item U
2913 Register offset addressing
2914
2915 @item W
2916 const_call_operand
2917
2918 @item Cs
2919 symbol_ref or const
2920
2921 @item Ci
2922 const_int
2923
2924 @item C0
2925 const_int 0
2926
2927 @item Cj
2928 Range of signed numbers that don't fit in 16 bits
2929
2930 @item Cmvq
2931 Integers valid for mvq
2932
2933 @item Capsw
2934 Integers valid for a moveq followed by a swap
2935
2936 @item Cmvz
2937 Integers valid for mvz
2938
2939 @item Cmvs
2940 Integers valid for mvs
2941
2942 @item Ap
2943 push_operand
2944
2945 @item Ac
2946 Non-register operands allowed in clr
2947
2948 @end table
2949
2950 @item Moxie---@file{config/moxie/constraints.md}
2951 @table @code
2952 @item A
2953 An absolute address
2954
2955 @item B
2956 An offset address
2957
2958 @item W
2959 A register indirect memory operand
2960
2961 @item I
2962 A constant in the range of 0 to 255.
2963
2964 @item N
2965 A constant in the range of 0 to @minus{}255.
2966
2967 @end table
2968
2969 @item MSP430--@file{config/msp430/constraints.md}
2970 @table @code
2971
2972 @item R12
2973 Register R12.
2974
2975 @item R13
2976 Register R13.
2977
2978 @item K
2979 Integer constant 1.
2980
2981 @item L
2982 Integer constant -1^20..1^19.
2983
2984 @item M
2985 Integer constant 1-4.
2986
2987 @item Ya
2988 Memory references which do not require an extended MOVX instruction.
2989
2990 @item Yl
2991 Memory reference, labels only.
2992
2993 @item Ys
2994 Memory reference, stack only.
2995
2996 @end table
2997
2998 @item NDS32---@file{config/nds32/constraints.md}
2999 @table @code
3000 @item w
3001 LOW register class $r0 to $r7 constraint for V3/V3M ISA.
3002 @item l
3003 LOW register class $r0 to $r7.
3004 @item d
3005 MIDDLE register class $r0 to $r11, $r16 to $r19.
3006 @item h
3007 HIGH register class $r12 to $r14, $r20 to $r31.
3008 @item t
3009 Temporary assist register $ta (i.e.@: $r15).
3010 @item k
3011 Stack register $sp.
3012 @item Iu03
3013 Unsigned immediate 3-bit value.
3014 @item In03
3015 Negative immediate 3-bit value in the range of @minus{}7--0.
3016 @item Iu04
3017 Unsigned immediate 4-bit value.
3018 @item Is05
3019 Signed immediate 5-bit value.
3020 @item Iu05
3021 Unsigned immediate 5-bit value.
3022 @item In05
3023 Negative immediate 5-bit value in the range of @minus{}31--0.
3024 @item Ip05
3025 Unsigned immediate 5-bit value for movpi45 instruction with range 16--47.
3026 @item Iu06
3027 Unsigned immediate 6-bit value constraint for addri36.sp instruction.
3028 @item Iu08
3029 Unsigned immediate 8-bit value.
3030 @item Iu09
3031 Unsigned immediate 9-bit value.
3032 @item Is10
3033 Signed immediate 10-bit value.
3034 @item Is11
3035 Signed immediate 11-bit value.
3036 @item Is15
3037 Signed immediate 15-bit value.
3038 @item Iu15
3039 Unsigned immediate 15-bit value.
3040 @item Ic15
3041 A constant which is not in the range of imm15u but ok for bclr instruction.
3042 @item Ie15
3043 A constant which is not in the range of imm15u but ok for bset instruction.
3044 @item It15
3045 A constant which is not in the range of imm15u but ok for btgl instruction.
3046 @item Ii15
3047 A constant whose compliment value is in the range of imm15u
3048 and ok for bitci instruction.
3049 @item Is16
3050 Signed immediate 16-bit value.
3051 @item Is17
3052 Signed immediate 17-bit value.
3053 @item Is19
3054 Signed immediate 19-bit value.
3055 @item Is20
3056 Signed immediate 20-bit value.
3057 @item Ihig
3058 The immediate value that can be simply set high 20-bit.
3059 @item Izeb
3060 The immediate value 0xff.
3061 @item Izeh
3062 The immediate value 0xffff.
3063 @item Ixls
3064 The immediate value 0x01.
3065 @item Ix11
3066 The immediate value 0x7ff.
3067 @item Ibms
3068 The immediate value with power of 2.
3069 @item Ifex
3070 The immediate value with power of 2 minus 1.
3071 @item U33
3072 Memory constraint for 333 format.
3073 @item U45
3074 Memory constraint for 45 format.
3075 @item U37
3076 Memory constraint for 37 format.
3077 @end table
3078
3079 @item Nios II family---@file{config/nios2/constraints.md}
3080 @table @code
3081
3082 @item I
3083 Integer that is valid as an immediate operand in an
3084 instruction taking a signed 16-bit number. Range
3085 @minus{}32768 to 32767.
3086
3087 @item J
3088 Integer that is valid as an immediate operand in an
3089 instruction taking an unsigned 16-bit number. Range
3090 0 to 65535.
3091
3092 @item K
3093 Integer that is valid as an immediate operand in an
3094 instruction taking only the upper 16-bits of a
3095 32-bit number. Range 32-bit numbers with the lower
3096 16-bits being 0.
3097
3098 @item L
3099 Integer that is valid as an immediate operand for a
3100 shift instruction. Range 0 to 31.
3101
3102 @item M
3103 Integer that is valid as an immediate operand for
3104 only the value 0. Can be used in conjunction with
3105 the format modifier @code{z} to use @code{r0}
3106 instead of @code{0} in the assembly output.
3107
3108 @item N
3109 Integer that is valid as an immediate operand for
3110 a custom instruction opcode. Range 0 to 255.
3111
3112 @item P
3113 An immediate operand for R2 andchi/andci instructions.
3114
3115 @item S
3116 Matches immediates which are addresses in the small
3117 data section and therefore can be added to @code{gp}
3118 as a 16-bit immediate to re-create their 32-bit value.
3119
3120 @item U
3121 Matches constants suitable as an operand for the rdprs and
3122 cache instructions.
3123
3124 @item v
3125 A memory operand suitable for Nios II R2 load/store
3126 exclusive instructions.
3127
3128 @item w
3129 A memory operand suitable for load/store IO and cache
3130 instructions.
3131
3132 @ifset INTERNALS
3133 @item T
3134 A @code{const} wrapped @code{UNSPEC} expression,
3135 representing a supported PIC or TLS relocation.
3136 @end ifset
3137
3138 @end table
3139
3140 @item OpenRISC---@file{config/or1k/constraints.md}
3141 @table @code
3142 @item I
3143 Integer that is valid as an immediate operand in an
3144 instruction taking a signed 16-bit number. Range
3145 @minus{}32768 to 32767.
3146
3147 @item K
3148 Integer that is valid as an immediate operand in an
3149 instruction taking an unsigned 16-bit number. Range
3150 0 to 65535.
3151
3152 @item M
3153 Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi})
3154
3155 @item O
3156 Zero
3157
3158 @ifset INTERNALS
3159 @item c
3160 Register usable for sibcalls.
3161 @end ifset
3162
3163 @end table
3164
3165 @item PDP-11---@file{config/pdp11/constraints.md}
3166 @table @code
3167 @item a
3168 Floating point registers AC0 through AC3. These can be loaded from/to
3169 memory with a single instruction.
3170
3171 @item d
3172 Odd numbered general registers (R1, R3, R5). These are used for
3173 16-bit multiply operations.
3174
3175 @item D
3176 A memory reference that is encoded within the opcode, but not
3177 auto-increment or auto-decrement.
3178
3179 @item f
3180 Any of the floating point registers (AC0 through AC5).
3181
3182 @item G
3183 Floating point constant 0.
3184
3185 @item h
3186 Floating point registers AC4 and AC5. These cannot be loaded from/to
3187 memory with a single instruction.
3188
3189 @item I
3190 An integer constant that fits in 16 bits.
3191
3192 @item J
3193 An integer constant whose low order 16 bits are zero.
3194
3195 @item K
3196 An integer constant that does not meet the constraints for codes
3197 @samp{I} or @samp{J}.
3198
3199 @item L
3200 The integer constant 1.
3201
3202 @item M
3203 The integer constant @minus{}1.
3204
3205 @item N
3206 The integer constant 0.
3207
3208 @item O
3209 Integer constants 0 through 3; shifts by these
3210 amounts are handled as multiple single-bit shifts rather than a single
3211 variable-length shift.
3212
3213 @item Q
3214 A memory reference which requires an additional word (address or
3215 offset) after the opcode.
3216
3217 @item R
3218 A memory reference that is encoded within the opcode.
3219
3220 @end table
3221
3222 @item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md}
3223 @table @code
3224 @item r
3225 A general purpose register (GPR), @code{r0}@dots{}@code{r31}.
3226
3227 @item b
3228 A base register. Like @code{r}, but @code{r0} is not allowed, so
3229 @code{r1}@dots{}@code{r31}.
3230
3231 @item f
3232 A floating point register (FPR), @code{f0}@dots{}@code{f31}.
3233
3234 @item d
3235 A floating point register. This is the same as @code{f} nowadays;
3236 historically @code{f} was for single-precision and @code{d} was for
3237 double-precision floating point.
3238
3239 @item v
3240 An Altivec vector register (VR), @code{v0}@dots{}@code{v31}.
3241
3242 @item wa
3243 A VSX register (VSR), @code{vs0}@dots{}@code{vs63}. This is either an
3244 FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR
3245 (@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}).
3246
3247 When using @code{wa}, you should use the @code{%x} output modifier, so that
3248 the correct register number is printed. For example:
3249
3250 @smallexample
3251 asm ("xvadddp %x0,%x1,%x2"
3252 : "=wa" (v1)
3253 : "wa" (v2), "wa" (v3));
3254 @end smallexample
3255
3256 You should not use @code{%x} for @code{v} operands:
3257
3258 @smallexample
3259 asm ("xsaddqp %0,%1,%2"
3260 : "=v" (v1)
3261 : "v" (v2), "v" (v3));
3262 @end smallexample
3263
3264 @ifset INTERNALS
3265 @item h
3266 A special register (@code{vrsave}, @code{ctr}, or @code{lr}).
3267 @end ifset
3268
3269 @item c
3270 The count register, @code{ctr}.
3271
3272 @item l
3273 The link register, @code{lr}.
3274
3275 @item x
3276 Condition register field 0, @code{cr0}.
3277
3278 @item y
3279 Any condition register field, @code{cr0}@dots{}@code{cr7}.
3280
3281 @ifset INTERNALS
3282 @item z
3283 The carry bit, @code{XER[CA]}.
3284
3285 @item we
3286 Like @code{wa}, if @option{-mpower9-vector} and @option{-m64} are used;
3287 otherwise, @code{NO_REGS}.
3288
3289 @item wn
3290 No register (@code{NO_REGS}).
3291
3292 @item wr
3293 Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3294
3295 @item wx
3296 Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}.
3297
3298 @item wA
3299 Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3300
3301 @item wB
3302 Signed 5-bit constant integer that can be loaded into an Altivec register.
3303
3304 @item wD
3305 Int constant that is the element number of the 64-bit scalar in a vector.
3306
3307 @item wE
3308 Vector constant that can be loaded with the XXSPLTIB instruction.
3309
3310 @item wF
3311 Memory operand suitable for power8 GPR load fusion.
3312
3313 @item wL
3314 Int constant that is the element number mfvsrld accesses in a vector.
3315
3316 @item wM
3317 Match vector constant with all 1's if the XXLORC instruction is available.
3318
3319 @item wO
3320 Memory operand suitable for the ISA 3.0 vector d-form instructions.
3321
3322 @item wQ
3323 Memory operand suitable for the load/store quad instructions.
3324
3325 @item wS
3326 Vector constant that can be loaded with XXSPLTIB & sign extension.
3327
3328 @item wY
3329 A memory operand for a DS-form instruction.
3330
3331 @item wZ
3332 An indexed or indirect memory operand, ignoring the bottom 4 bits.
3333 @end ifset
3334
3335 @item I
3336 A signed 16-bit constant.
3337
3338 @item J
3339 An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead
3340 for @code{SImode} constants).
3341
3342 @item K
3343 An unsigned 16-bit constant.
3344
3345 @item L
3346 A signed 16-bit constant shifted left 16 bits.
3347
3348 @ifset INTERNALS
3349 @item M
3350 An integer constant greater than 31.
3351
3352 @item N
3353 An exact power of 2.
3354
3355 @item O
3356 The integer constant zero.
3357
3358 @item P
3359 A constant whose negation is a signed 16-bit constant.
3360 @end ifset
3361
3362 @item eI
3363 A signed 34-bit integer constant if prefixed instructions are supported.
3364
3365 @item eP
3366 A scalar floating point constant or a vector constant that can be
3367 loaded to a VSX register with one prefixed instruction.
3368
3369 @item eQ
3370 An IEEE 128-bit constant that can be loaded into a VSX register with
3371 the @code{lxvkq} instruction.
3372
3373 @ifset INTERNALS
3374 @item G
3375 A floating point constant that can be loaded into a register with one
3376 instruction per word.
3377
3378 @item H
3379 A floating point constant that can be loaded into a register using
3380 three instructions.
3381 @end ifset
3382
3383 @item m
3384 A memory operand.
3385 Normally, @code{m} does not allow addresses that update the base register.
3386 If the @code{<} or @code{>} constraint is also used, they are allowed and
3387 therefore on PowerPC targets in that case it is only safe
3388 to use @code{m<>} in an @code{asm} statement if that @code{asm} statement
3389 accesses the operand exactly once. The @code{asm} statement must also
3390 use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
3391 corresponding load or store instruction. For example:
3392
3393 @smallexample
3394 asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
3395 @end smallexample
3396
3397 is correct but:
3398
3399 @smallexample
3400 asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
3401 @end smallexample
3402
3403 is not.
3404
3405 @ifset INTERNALS
3406 @item es
3407 A ``stable'' memory operand; that is, one which does not include any
3408 automodification of the base register. This used to be useful when
3409 @code{m} allowed automodification of the base register, but as those
3410 are now only allowed when @code{<} or @code{>} is used, @code{es} is
3411 basically the same as @code{m} without @code{<} and @code{>}.
3412 @end ifset
3413
3414 @item Q
3415 A memory operand addressed by just a base register.
3416
3417 @ifset INTERNALS
3418 @item Y
3419 A memory operand for a DQ-form instruction.
3420 @end ifset
3421
3422 @item Z
3423 A memory operand accessed with indexed or indirect addressing.
3424
3425 @ifset INTERNALS
3426 @item R
3427 An AIX TOC entry.
3428 @end ifset
3429
3430 @item a
3431 An indexed or indirect address.
3432
3433 @ifset INTERNALS
3434 @item U
3435 A V.4 small data reference.
3436
3437 @item W
3438 A vector constant that does not require memory.
3439
3440 @item j
3441 The zero vector constant.
3442 @end ifset
3443
3444 @end table
3445
3446 @item PRU---@file{config/pru/constraints.md}
3447 @table @code
3448 @item I
3449 An unsigned 8-bit integer constant.
3450
3451 @item J
3452 An unsigned 16-bit integer constant.
3453
3454 @item L
3455 An unsigned 5-bit integer constant (for shift counts).
3456
3457 @item T
3458 A text segment (program memory) constant label.
3459
3460 @item Z
3461 Integer constant zero.
3462
3463 @end table
3464
3465 @item RL78---@file{config/rl78/constraints.md}
3466 @table @code
3467
3468 @item Int3
3469 An integer constant in the range 1 @dots{} 7.
3470 @item Int8
3471 An integer constant in the range 0 @dots{} 255.
3472 @item J
3473 An integer constant in the range @minus{}255 @dots{} 0
3474 @item K
3475 The integer constant 1.
3476 @item L
3477 The integer constant -1.
3478 @item M
3479 The integer constant 0.
3480 @item N
3481 The integer constant 2.
3482 @item O
3483 The integer constant -2.
3484 @item P
3485 An integer constant in the range 1 @dots{} 15.
3486 @item Qbi
3487 The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
3488 @item Qsc
3489 The synthetic compare types--gt, lt, ge, and le.
3490 @item Wab
3491 A memory reference with an absolute address.
3492 @item Wbc
3493 A memory reference using @code{BC} as a base register, with an optional offset.
3494 @item Wca
3495 A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
3496 @item Wcv
3497 A memory reference using any 16-bit register pair for the address, for calls.
3498 @item Wd2
3499 A memory reference using @code{DE} as a base register, with an optional offset.
3500 @item Wde
3501 A memory reference using @code{DE} as a base register, without any offset.
3502 @item Wfr
3503 Any memory reference to an address in the far address space.
3504 @item Wh1
3505 A memory reference using @code{HL} as a base register, with an optional one-byte offset.
3506 @item Whb
3507 A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
3508 @item Whl
3509 A memory reference using @code{HL} as a base register, without any offset.
3510 @item Ws1
3511 A memory reference using @code{SP} as a base register, with an optional one-byte offset.
3512 @item Y
3513 Any memory reference to an address in the near address space.
3514 @item A
3515 The @code{AX} register.
3516 @item B
3517 The @code{BC} register.
3518 @item D
3519 The @code{DE} register.
3520 @item R
3521 @code{A} through @code{L} registers.
3522 @item S
3523 The @code{SP} register.
3524 @item T
3525 The @code{HL} register.
3526 @item Z08W
3527 The 16-bit @code{R8} register.
3528 @item Z10W
3529 The 16-bit @code{R10} register.
3530 @item Zint
3531 The registers reserved for interrupts (@code{R24} to @code{R31}).
3532 @item a
3533 The @code{A} register.
3534 @item b
3535 The @code{B} register.
3536 @item c
3537 The @code{C} register.
3538 @item d
3539 The @code{D} register.
3540 @item e
3541 The @code{E} register.
3542 @item h
3543 The @code{H} register.
3544 @item l
3545 The @code{L} register.
3546 @item v
3547 The virtual registers.
3548 @item w
3549 The @code{PSW} register.
3550 @item x
3551 The @code{X} register.
3552
3553 @end table
3554
3555 @item RISC-V---@file{config/riscv/constraints.md}
3556 @table @code
3557
3558 @item f
3559 A floating-point register (if available).
3560
3561 @item I
3562 An I-type 12-bit signed immediate.
3563
3564 @item J
3565 Integer zero.
3566
3567 @item K
3568 A 5-bit unsigned immediate for CSR access instructions.
3569
3570 @item A
3571 An address that is held in a general-purpose register.
3572
3573 @item S
3574 A constraint that matches an absolute symbolic address.
3575
3576 @end table
3577
3578 @item RX---@file{config/rx/constraints.md}
3579 @table @code
3580 @item Q
3581 An address which does not involve register indirect addressing or
3582 pre/post increment/decrement addressing.
3583
3584 @item Symbol
3585 A symbol reference.
3586
3587 @item Int08
3588 A constant in the range @minus{}256 to 255, inclusive.
3589
3590 @item Sint08
3591 A constant in the range @minus{}128 to 127, inclusive.
3592
3593 @item Sint16
3594 A constant in the range @minus{}32768 to 32767, inclusive.
3595
3596 @item Sint24
3597 A constant in the range @minus{}8388608 to 8388607, inclusive.
3598
3599 @item Uint04
3600 A constant in the range 0 to 15, inclusive.
3601
3602 @end table
3603
3604 @item S/390 and zSeries---@file{config/s390/s390.h}
3605 @table @code
3606 @item a
3607 Address register (general purpose register except r0)
3608
3609 @item c
3610 Condition code register
3611
3612 @item d
3613 Data register (arbitrary general purpose register)
3614
3615 @item f
3616 Floating-point register
3617
3618 @item I
3619 Unsigned 8-bit constant (0--255)
3620
3621 @item J
3622 Unsigned 12-bit constant (0--4095)
3623
3624 @item K
3625 Signed 16-bit constant (@minus{}32768--32767)
3626
3627 @item L
3628 Value appropriate as displacement.
3629 @table @code
3630 @item (0..4095)
3631 for short displacement
3632 @item (@minus{}524288..524287)
3633 for long displacement
3634 @end table
3635
3636 @item M
3637 Constant integer with a value of 0x7fffffff.
3638
3639 @item N
3640 Multiple letter constraint followed by 4 parameter letters.
3641 @table @code
3642 @item 0..9:
3643 number of the part counting from most to least significant
3644 @item H,Q:
3645 mode of the part
3646 @item D,S,H:
3647 mode of the containing operand
3648 @item 0,F:
3649 value of the other parts (F---all bits set)
3650 @end table
3651 The constraint matches if the specified part of a constant
3652 has a value different from its other parts.
3653
3654 @item Q
3655 Memory reference without index register and with short displacement.
3656
3657 @item R
3658 Memory reference with index register and short displacement.
3659
3660 @item S
3661 Memory reference without index register but with long displacement.
3662
3663 @item T
3664 Memory reference with index register and long displacement.
3665
3666 @item U
3667 Pointer with short displacement.
3668
3669 @item W
3670 Pointer with long displacement.
3671
3672 @item Y
3673 Shift count operand.
3674
3675 @end table
3676
3677 @need 1000
3678 @item SPARC---@file{config/sparc/sparc.h}
3679 @table @code
3680 @item f
3681 Floating-point register on the SPARC-V8 architecture and
3682 lower floating-point register on the SPARC-V9 architecture.
3683
3684 @item e
3685 Floating-point register. It is equivalent to @samp{f} on the
3686 SPARC-V8 architecture and contains both lower and upper
3687 floating-point registers on the SPARC-V9 architecture.
3688
3689 @item c
3690 Floating-point condition code register.
3691
3692 @item d
3693 Lower floating-point register. It is only valid on the SPARC-V9
3694 architecture when the Visual Instruction Set is available.
3695
3696 @item b
3697 Floating-point register. It is only valid on the SPARC-V9 architecture
3698 when the Visual Instruction Set is available.
3699
3700 @item h
3701 64-bit global or out register for the SPARC-V8+ architecture.
3702
3703 @item C
3704 The constant all-ones, for floating-point.
3705
3706 @item A
3707 Signed 5-bit constant
3708
3709 @item D
3710 A vector constant
3711
3712 @item I
3713 Signed 13-bit constant
3714
3715 @item J
3716 Zero
3717
3718 @item K
3719 32-bit constant with the low 12 bits clear (a constant that can be
3720 loaded with the @code{sethi} instruction)
3721
3722 @item L
3723 A constant in the range supported by @code{movcc} instructions (11-bit
3724 signed immediate)
3725
3726 @item M
3727 A constant in the range supported by @code{movrcc} instructions (10-bit
3728 signed immediate)
3729
3730 @item N
3731 Same as @samp{K}, except that it verifies that bits that are not in the
3732 lower 32-bit range are all zero. Must be used instead of @samp{K} for
3733 modes wider than @code{SImode}
3734
3735 @item O
3736 The constant 4096
3737
3738 @item G
3739 Floating-point zero
3740
3741 @item H
3742 Signed 13-bit constant, sign-extended to 32 or 64 bits
3743
3744 @item P
3745 The constant -1
3746
3747 @item Q
3748 Floating-point constant whose integral representation can
3749 be moved into an integer register using a single sethi
3750 instruction
3751
3752 @item R
3753 Floating-point constant whose integral representation can
3754 be moved into an integer register using a single mov
3755 instruction
3756
3757 @item S
3758 Floating-point constant whose integral representation can
3759 be moved into an integer register using a high/lo_sum
3760 instruction sequence
3761
3762 @item T
3763 Memory address aligned to an 8-byte boundary
3764
3765 @item U
3766 Even register
3767
3768 @item W
3769 Memory address for @samp{e} constraint registers
3770
3771 @item w
3772 Memory address with only a base register
3773
3774 @item Y
3775 Vector zero
3776
3777 @end table
3778
3779 @item TI C6X family---@file{config/c6x/constraints.md}
3780 @table @code
3781 @item a
3782 Register file A (A0--A31).
3783
3784 @item b
3785 Register file B (B0--B31).
3786
3787 @item A
3788 Predicate registers in register file A (A0--A2 on C64X and
3789 higher, A1 and A2 otherwise).
3790
3791 @item B
3792 Predicate registers in register file B (B0--B2).
3793
3794 @item C
3795 A call-used register in register file B (B0--B9, B16--B31).
3796
3797 @item Da
3798 Register file A, excluding predicate registers (A3--A31,
3799 plus A0 if not C64X or higher).
3800
3801 @item Db
3802 Register file B, excluding predicate registers (B3--B31).
3803
3804 @item Iu4
3805 Integer constant in the range 0 @dots{} 15.
3806
3807 @item Iu5
3808 Integer constant in the range 0 @dots{} 31.
3809
3810 @item In5
3811 Integer constant in the range @minus{}31 @dots{} 0.
3812
3813 @item Is5
3814 Integer constant in the range @minus{}16 @dots{} 15.
3815
3816 @item I5x
3817 Integer constant that can be the operand of an ADDA or a SUBA insn.
3818
3819 @item IuB
3820 Integer constant in the range 0 @dots{} 65535.
3821
3822 @item IsB
3823 Integer constant in the range @minus{}32768 @dots{} 32767.
3824
3825 @item IsC
3826 Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.
3827
3828 @item Jc
3829 Integer constant that is a valid mask for the clr instruction.
3830
3831 @item Js
3832 Integer constant that is a valid mask for the set instruction.
3833
3834 @item Q
3835 Memory location with A base register.
3836
3837 @item R
3838 Memory location with B base register.
3839
3840 @ifset INTERNALS
3841 @item S0
3842 On C64x+ targets, a GP-relative small data reference.
3843
3844 @item S1
3845 Any kind of @code{SYMBOL_REF}, for use in a call address.
3846
3847 @item Si
3848 Any kind of immediate operand, unless it matches the S0 constraint.
3849
3850 @item T
3851 Memory location with B base register, but not using a long offset.
3852
3853 @item W
3854 A memory operand with an address that cannot be used in an unaligned access.
3855
3856 @end ifset
3857 @item Z
3858 Register B14 (aka DP).
3859
3860 @end table
3861
3862 @item TILE-Gx---@file{config/tilegx/constraints.md}
3863 @table @code
3864 @item R00
3865 @itemx R01
3866 @itemx R02
3867 @itemx R03
3868 @itemx R04
3869 @itemx R05
3870 @itemx R06
3871 @itemx R07
3872 @itemx R08
3873 @itemx R09
3874 @itemx R10
3875 Each of these represents a register constraint for an individual
3876 register, from r0 to r10.
3877
3878 @item I
3879 Signed 8-bit integer constant.
3880
3881 @item J
3882 Signed 16-bit integer constant.
3883
3884 @item K
3885 Unsigned 16-bit integer constant.
3886
3887 @item L
3888 Integer constant that fits in one signed byte when incremented by one
3889 (@minus{}129 @dots{} 126).
3890
3891 @item m
3892 Memory operand. If used together with @samp{<} or @samp{>}, the
3893 operand can have postincrement which requires printing with @samp{%In}
3894 and @samp{%in} on TILE-Gx. For example:
3895
3896 @smallexample
3897 asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val));
3898 @end smallexample
3899
3900 @item M
3901 A bit mask suitable for the BFINS instruction.
3902
3903 @item N
3904 Integer constant that is a byte tiled out eight times.
3905
3906 @item O
3907 The integer zero constant.
3908
3909 @item P
3910 Integer constant that is a sign-extended byte tiled out as four shorts.
3911
3912 @item Q
3913 Integer constant that fits in one signed byte when incremented
3914 (@minus{}129 @dots{} 126), but excluding -1.
3915
3916 @item S
3917 Integer constant that has all 1 bits consecutive and starting at bit 0.
3918
3919 @item T
3920 A 16-bit fragment of a got, tls, or pc-relative reference.
3921
3922 @item U
3923 Memory operand except postincrement. This is roughly the same as
3924 @samp{m} when not used together with @samp{<} or @samp{>}.
3925
3926 @item W
3927 An 8-element vector constant with identical elements.
3928
3929 @item Y
3930 A 4-element vector constant with identical elements.
3931
3932 @item Z0
3933 The integer constant 0xffffffff.
3934
3935 @item Z1
3936 The integer constant 0xffffffff00000000.
3937
3938 @end table
3939
3940 @item TILEPro---@file{config/tilepro/constraints.md}
3941 @table @code
3942 @item R00
3943 @itemx R01
3944 @itemx R02
3945 @itemx R03
3946 @itemx R04
3947 @itemx R05
3948 @itemx R06
3949 @itemx R07
3950 @itemx R08
3951 @itemx R09
3952 @itemx R10
3953 Each of these represents a register constraint for an individual
3954 register, from r0 to r10.
3955
3956 @item I
3957 Signed 8-bit integer constant.
3958
3959 @item J
3960 Signed 16-bit integer constant.
3961
3962 @item K
3963 Nonzero integer constant with low 16 bits zero.
3964
3965 @item L
3966 Integer constant that fits in one signed byte when incremented by one
3967 (@minus{}129 @dots{} 126).
3968
3969 @item m
3970 Memory operand. If used together with @samp{<} or @samp{>}, the
3971 operand can have postincrement which requires printing with @samp{%In}
3972 and @samp{%in} on TILEPro. For example:
3973
3974 @smallexample
3975 asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val));
3976 @end smallexample
3977
3978 @item M
3979 A bit mask suitable for the MM instruction.
3980
3981 @item N
3982 Integer constant that is a byte tiled out four times.
3983
3984 @item O
3985 The integer zero constant.
3986
3987 @item P
3988 Integer constant that is a sign-extended byte tiled out as two shorts.
3989
3990 @item Q
3991 Integer constant that fits in one signed byte when incremented
3992 (@minus{}129 @dots{} 126), but excluding -1.
3993
3994 @item T
3995 A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative
3996 reference.
3997
3998 @item U
3999 Memory operand except postincrement. This is roughly the same as
4000 @samp{m} when not used together with @samp{<} or @samp{>}.
4001
4002 @item W
4003 A 4-element vector constant with identical elements.
4004
4005 @item Y
4006 A 2-element vector constant with identical elements.
4007
4008 @end table
4009
4010 @item Visium---@file{config/visium/constraints.md}
4011 @table @code
4012 @item b
4013 EAM register @code{mdb}
4014
4015 @item c
4016 EAM register @code{mdc}
4017
4018 @item f
4019 Floating point register
4020
4021 @ifset INTERNALS
4022 @item k
4023 Register for sibcall optimization
4024 @end ifset
4025
4026 @item l
4027 General register, but not @code{r29}, @code{r30} and @code{r31}
4028
4029 @item t
4030 Register @code{r1}
4031
4032 @item u
4033 Register @code{r2}
4034
4035 @item v
4036 Register @code{r3}
4037
4038 @item G
4039 Floating-point constant 0.0
4040
4041 @item J
4042 Integer constant in the range 0 .. 65535 (16-bit immediate)
4043
4044 @item K
4045 Integer constant in the range 1 .. 31 (5-bit immediate)
4046
4047 @item L
4048 Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate)
4049
4050 @item M
4051 Integer constant @minus{}1
4052
4053 @item O
4054 Integer constant 0
4055
4056 @item P
4057 Integer constant 32
4058 @end table
4059
4060 @item x86 family---@file{config/i386/constraints.md}
4061 @table @code
4062 @item R
4063 Legacy register---the eight integer registers available on all
4064 i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
4065 @code{si}, @code{di}, @code{bp}, @code{sp}).
4066
4067 @item q
4068 Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a},
4069 @code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.
4070
4071 @item Q
4072 Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
4073 @code{c}, and @code{d}.
4074
4075 @ifset INTERNALS
4076 @item l
4077 Any register that can be used as the index in a base+index memory
4078 access: that is, any general register except the stack pointer.
4079 @end ifset
4080
4081 @item a
4082 The @code{a} register.
4083
4084 @item b
4085 The @code{b} register.
4086
4087 @item c
4088 The @code{c} register.
4089
4090 @item d
4091 The @code{d} register.
4092
4093 @item S
4094 The @code{si} register.
4095
4096 @item D
4097 The @code{di} register.
4098
4099 @item A
4100 The @code{a} and @code{d} registers. This class is used for instructions
4101 that return double word results in the @code{ax:dx} register pair. Single
4102 word values will be allocated either in @code{ax} or @code{dx}.
4103 For example on i386 the following implements @code{rdtsc}:
4104
4105 @smallexample
4106 unsigned long long rdtsc (void)
4107 @{
4108 unsigned long long tick;
4109 __asm__ __volatile__("rdtsc":"=A"(tick));
4110 return tick;
4111 @}
4112 @end smallexample
4113
4114 This is not correct on x86-64 as it would allocate tick in either @code{ax}
4115 or @code{dx}. You have to use the following variant instead:
4116
4117 @smallexample
4118 unsigned long long rdtsc (void)
4119 @{
4120 unsigned int tickl, tickh;
4121 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
4122 return ((unsigned long long)tickh << 32)|tickl;
4123 @}
4124 @end smallexample
4125
4126 @item U
4127 The call-clobbered integer registers.
4128
4129 @item f
4130 Any 80387 floating-point (stack) register.
4131
4132 @item t
4133 Top of 80387 floating-point stack (@code{%st(0)}).
4134
4135 @item u
4136 Second from top of 80387 floating-point stack (@code{%st(1)}).
4137
4138 @ifset INTERNALS
4139 @item Yk
4140 Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}.
4141
4142 @item k
4143 Any mask register.
4144 @end ifset
4145
4146 @item y
4147 Any MMX register.
4148
4149 @item x
4150 Any SSE register.
4151
4152 @item v
4153 Any EVEX encodable SSE register (@code{%xmm0-%xmm31}).
4154
4155 @ifset INTERNALS
4156 @item w
4157 Any bound register.
4158 @end ifset
4159
4160 @item Yz
4161 First SSE register (@code{%xmm0}).
4162
4163 @ifset INTERNALS
4164 @item Yi
4165 Any SSE register, when SSE2 and inter-unit moves are enabled.
4166
4167 @item Yj
4168 Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled.
4169
4170 @item Ym
4171 Any MMX register, when inter-unit moves are enabled.
4172
4173 @item Yn
4174 Any MMX register, when inter-unit moves from vector registers are enabled.
4175
4176 @item Yp
4177 Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled.
4178
4179 @item Ya
4180 Any integer register when zero extensions with @code{AND} are disabled.
4181
4182 @item Yb
4183 Any register that can be used as the GOT base when calling@*
4184 @code{___tls_get_addr}: that is, any general register except @code{a}
4185 and @code{sp} registers, for @option{-fno-plt} if linker supports it.
4186 Otherwise, @code{b} register.
4187
4188 @item Yf
4189 Any x87 register when 80387 floating-point arithmetic is enabled.
4190
4191 @item Yr
4192 Lower SSE register when avoiding REX prefix and all SSE registers otherwise.
4193
4194 @item Yv
4195 For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}),
4196 otherwise any SSE register.
4197
4198 @item Yh
4199 Any EVEX-encodable SSE register, that has number factor of four.
4200
4201 @item Bf
4202 Flags register operand.
4203
4204 @item Bg
4205 GOT memory operand.
4206
4207 @item Bm
4208 Vector memory operand.
4209
4210 @item Bc
4211 Constant memory operand.
4212
4213 @item Bn
4214 Memory operand without REX prefix.
4215
4216 @item Bs
4217 Sibcall memory operand.
4218
4219 @item Bw
4220 Call memory operand.
4221
4222 @item Bz
4223 Constant call address operand.
4224
4225 @item BC
4226 SSE constant -1 operand.
4227 @end ifset
4228
4229 @item I
4230 Integer constant in the range 0 @dots{} 31, for 32-bit shifts.
4231
4232 @item J
4233 Integer constant in the range 0 @dots{} 63, for 64-bit shifts.
4234
4235 @item K
4236 Signed 8-bit integer constant.
4237
4238 @item L
4239 @code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.
4240
4241 @item M
4242 0, 1, 2, or 3 (shifts for the @code{lea} instruction).
4243
4244 @item N
4245 Unsigned 8-bit integer constant (for @code{in} and @code{out}
4246 instructions).
4247
4248 @ifset INTERNALS
4249 @item O
4250 Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
4251 @end ifset
4252
4253 @item G
4254 Standard 80387 floating point constant.
4255
4256 @item C
4257 SSE constant zero operand.
4258
4259 @item e
4260 32-bit signed integer constant, or a symbolic reference known
4261 to fit that range (for immediate operands in sign-extending x86-64
4262 instructions).
4263
4264 @item We
4265 32-bit signed integer constant, or a symbolic reference known
4266 to fit that range (for sign-extending conversion operations that
4267 require non-@code{VOIDmode} immediate operands).
4268
4269 @item Wz
4270 32-bit unsigned integer constant, or a symbolic reference known
4271 to fit that range (for zero-extending conversion operations that
4272 require non-@code{VOIDmode} immediate operands).
4273
4274 @item Wd
4275 128-bit integer constant where both the high and low 64-bit word
4276 satisfy the @code{e} constraint.
4277
4278 @item Z
4279 32-bit unsigned integer constant, or a symbolic reference known
4280 to fit that range (for immediate operands in zero-extending x86-64
4281 instructions).
4282
4283 @item Tv
4284 VSIB address operand.
4285
4286 @item Ts
4287 Address operand without segment register.
4288
4289 @end table
4290
4291 @item Xstormy16---@file{config/stormy16/stormy16.h}
4292 @table @code
4293 @item a
4294 Register r0.
4295
4296 @item b
4297 Register r1.
4298
4299 @item c
4300 Register r2.
4301
4302 @item d
4303 Register r8.
4304
4305 @item e
4306 Registers r0 through r7.
4307
4308 @item t
4309 Registers r0 and r1.
4310
4311 @item y
4312 The carry register.
4313
4314 @item z
4315 Registers r8 and r9.
4316
4317 @item I
4318 A constant between 0 and 3 inclusive.
4319
4320 @item J
4321 A constant that has exactly one bit set.
4322
4323 @item K
4324 A constant that has exactly one bit clear.
4325
4326 @item L
4327 A constant between 0 and 255 inclusive.
4328
4329 @item M
4330 A constant between @minus{}255 and 0 inclusive.
4331
4332 @item N
4333 A constant between @minus{}3 and 0 inclusive.
4334
4335 @item O
4336 A constant between 1 and 4 inclusive.
4337
4338 @item P
4339 A constant between @minus{}4 and @minus{}1 inclusive.
4340
4341 @item Q
4342 A memory reference that is a stack push.
4343
4344 @item R
4345 A memory reference that is a stack pop.
4346
4347 @item S
4348 A memory reference that refers to a constant address of known value.
4349
4350 @item T
4351 The register indicated by Rx (not implemented yet).
4352
4353 @item U
4354 A constant that is not between 2 and 15 inclusive.
4355
4356 @item Z
4357 The constant 0.
4358
4359 @end table
4360
4361 @item Xtensa---@file{config/xtensa/constraints.md}
4362 @table @code
4363 @item a
4364 General-purpose 32-bit register
4365
4366 @item b
4367 One-bit boolean register
4368
4369 @item A
4370 MAC16 40-bit accumulator register
4371
4372 @item I
4373 Signed 12-bit integer constant, for use in MOVI instructions
4374
4375 @item J
4376 Signed 8-bit integer constant, for use in ADDI instructions
4377
4378 @item K
4379 Integer constant valid for BccI instructions
4380
4381 @item L
4382 Unsigned constant valid for BccUI instructions
4383
4384 @end table
4385
4386 @end table
4387
4388 @ifset INTERNALS
4389 @node Disable Insn Alternatives
4390 @subsection Disable insn alternatives using the @code{enabled} attribute
4391 @cindex enabled
4392
4393 There are three insn attributes that may be used to selectively disable
4394 instruction alternatives:
4395
4396 @table @code
4397 @item enabled
4398 Says whether an alternative is available on the current subtarget.
4399
4400 @item preferred_for_size
4401 Says whether an enabled alternative should be used in code that is
4402 optimized for size.
4403
4404 @item preferred_for_speed
4405 Says whether an enabled alternative should be used in code that is
4406 optimized for speed.
4407 @end table
4408
4409 All these attributes should use @code{(const_int 1)} to allow an alternative
4410 or @code{(const_int 0)} to disallow it. The attributes must be a static
4411 property of the subtarget; they cannot for example depend on the
4412 current operands, on the current optimization level, on the location
4413 of the insn within the body of a loop, on whether register allocation
4414 has finished, or on the current compiler pass.
4415
4416 The @code{enabled} attribute is a correctness property. It tells GCC to act
4417 as though the disabled alternatives were never defined in the first place.
4418 This is useful when adding new instructions to an existing pattern in
4419 cases where the new instructions are only available for certain cpu
4420 architecture levels (typically mapped to the @code{-march=} command-line
4421 option).
4422
4423 In contrast, the @code{preferred_for_size} and @code{preferred_for_speed}
4424 attributes are strong optimization hints rather than correctness properties.
4425 @code{preferred_for_size} tells GCC which alternatives to consider when
4426 adding or modifying an instruction that GCC wants to optimize for size.
4427 @code{preferred_for_speed} does the same thing for speed. Note that things
4428 like code motion can lead to cases where code optimized for size uses
4429 alternatives that are not preferred for size, and similarly for speed.
4430
4431 Although @code{define_insn}s can in principle specify the @code{enabled}
4432 attribute directly, it is often clearer to have subsiduary attributes
4433 for each architectural feature of interest. The @code{define_insn}s
4434 can then use these subsiduary attributes to say which alternatives
4435 require which features. The example below does this for @code{cpu_facility}.
4436
4437 E.g. the following two patterns could easily be merged using the @code{enabled}
4438 attribute:
4439
4440 @smallexample
4441
4442 (define_insn "*movdi_old"
4443 [(set (match_operand:DI 0 "register_operand" "=d")
4444 (match_operand:DI 1 "register_operand" " d"))]
4445 "!TARGET_NEW"
4446 "lgr %0,%1")
4447
4448 (define_insn "*movdi_new"
4449 [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4450 (match_operand:DI 1 "register_operand" " d,d,f"))]
4451 "TARGET_NEW"
4452 "@@
4453 lgr %0,%1
4454 ldgr %0,%1
4455 lgdr %0,%1")
4456
4457 @end smallexample
4458
4459 to:
4460
4461 @smallexample
4462
4463 (define_insn "*movdi_combined"
4464 [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4465 (match_operand:DI 1 "register_operand" " d,d,f"))]
4466 ""
4467 "@@
4468 lgr %0,%1
4469 ldgr %0,%1
4470 lgdr %0,%1"
4471 [(set_attr "cpu_facility" "*,new,new")])
4472
4473 @end smallexample
4474
4475 with the @code{enabled} attribute defined like this:
4476
4477 @smallexample
4478
4479 (define_attr "cpu_facility" "standard,new" (const_string "standard"))
4480
4481 (define_attr "enabled" ""
4482 (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
4483 (and (eq_attr "cpu_facility" "new")
4484 (ne (symbol_ref "TARGET_NEW") (const_int 0)))
4485 (const_int 1)]
4486 (const_int 0)))
4487
4488 @end smallexample
4489
4490 @end ifset
4491
4492 @ifset INTERNALS
4493 @node Define Constraints
4494 @subsection Defining Machine-Specific Constraints
4495 @cindex defining constraints
4496 @cindex constraints, defining
4497
4498 Machine-specific constraints fall into two categories: register and
4499 non-register constraints. Within the latter category, constraints
4500 which allow subsets of all possible memory or address operands should
4501 be specially marked, to give @code{reload} more information.
4502
4503 Machine-specific constraints can be given names of arbitrary length,
4504 but they must be entirely composed of letters, digits, underscores
4505 (@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they
4506 must begin with a letter or underscore.
4507
4508 In order to avoid ambiguity in operand constraint strings, no
4509 constraint can have a name that begins with any other constraint's
4510 name. For example, if @code{x} is defined as a constraint name,
4511 @code{xy} may not be, and vice versa. As a consequence of this rule,
4512 no constraint may begin with one of the generic constraint letters:
4513 @samp{E F V X g i m n o p r s}.
4514
4515 Register constraints correspond directly to register classes.
4516 @xref{Register Classes}. There is thus not much flexibility in their
4517 definitions.
4518
4519 @deffn {MD Expression} define_register_constraint name regclass docstring
4520 All three arguments are string constants.
4521 @var{name} is the name of the constraint, as it will appear in
4522 @code{match_operand} expressions. If @var{name} is a multi-letter
4523 constraint its length shall be the same for all constraints starting
4524 with the same letter. @var{regclass} can be either the
4525 name of the corresponding register class (@pxref{Register Classes}),
4526 or a C expression which evaluates to the appropriate register class.
4527 If it is an expression, it must have no side effects, and it cannot
4528 look at the operand. The usual use of expressions is to map some
4529 register constraints to @code{NO_REGS} when the register class
4530 is not available on a given subarchitecture.
4531
4532 @var{docstring} is a sentence documenting the meaning of the
4533 constraint. Docstrings are explained further below.
4534 @end deffn
4535
4536 Non-register constraints are more like predicates: the constraint
4537 definition gives a boolean expression which indicates whether the
4538 constraint matches.
4539
4540 @deffn {MD Expression} define_constraint name docstring exp
4541 The @var{name} and @var{docstring} arguments are the same as for
4542 @code{define_register_constraint}, but note that the docstring comes
4543 immediately after the name for these expressions. @var{exp} is an RTL
4544 expression, obeying the same rules as the RTL expressions in predicate
4545 definitions. @xref{Defining Predicates}, for details. If it
4546 evaluates true, the constraint matches; if it evaluates false, it
4547 doesn't. Constraint expressions should indicate which RTL codes they
4548 might match, just like predicate expressions.
4549
4550 @code{match_test} C expressions have access to the
4551 following variables:
4552
4553 @table @var
4554 @item op
4555 The RTL object defining the operand.
4556 @item mode
4557 The machine mode of @var{op}.
4558 @item ival
4559 @samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
4560 @item hval
4561 @samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
4562 @code{const_double}.
4563 @item lval
4564 @samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
4565 @code{const_double}.
4566 @item rval
4567 @samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
4568 @code{const_double}.
4569 @end table
4570
4571 The @var{*val} variables should only be used once another piece of the
4572 expression has verified that @var{op} is the appropriate kind of RTL
4573 object.
4574 @end deffn
4575
4576 Most non-register constraints should be defined with
4577 @code{define_constraint}. The remaining two definition expressions
4578 are only appropriate for constraints that should be handled specially
4579 by @code{reload} if they fail to match.
4580
4581 @deffn {MD Expression} define_memory_constraint name docstring exp
4582 Use this expression for constraints that match a subset of all memory
4583 operands: that is, @code{reload} can make them match by converting the
4584 operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
4585 base register (from the register class specified by
4586 @code{BASE_REG_CLASS}, @pxref{Register Classes}).
4587
4588 For example, on the S/390, some instructions do not accept arbitrary
4589 memory references, but only those that do not make use of an index
4590 register. The constraint letter @samp{Q} is defined to represent a
4591 memory address of this type. If @samp{Q} is defined with
4592 @code{define_memory_constraint}, a @samp{Q} constraint can handle any
4593 memory operand, because @code{reload} knows it can simply copy the
4594 memory address into a base register if required. This is analogous to
4595 the way an @samp{o} constraint can handle any memory operand.
4596
4597 The syntax and semantics are otherwise identical to
4598 @code{define_constraint}.
4599 @end deffn
4600
4601 @deffn {MD Expression} define_special_memory_constraint name docstring exp
4602 Use this expression for constraints that match a subset of all memory
4603 operands: that is, @code{reload} cannot make them match by reloading
4604 the address as it is described for @code{define_memory_constraint} or
4605 such address reload is undesirable with the performance point of view.
4606
4607 For example, @code{define_special_memory_constraint} can be useful if
4608 specifically aligned memory is necessary or desirable for some insn
4609 operand.
4610
4611 The syntax and semantics are otherwise identical to
4612 @code{define_memory_constraint}.
4613 @end deffn
4614
4615 @deffn {MD Expression} define_relaxed_memory_constraint name docstring exp
4616 The test expression in a @code{define_memory_constraint} can assume
4617 that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside
4618 a @code{mem} rtx and so it does not need to test this condition itself.
4619 In other words, a @code{define_memory_constraint} test of the form:
4620
4621 @smallexample
4622 (match_test "mem")
4623 @end smallexample
4624
4625 is enough to test whether an rtx is a @code{mem} @emph{and} whether
4626 its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually
4627 @samp{'m'}). Thus the conditions imposed by a @code{define_memory_constraint}
4628 always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}.
4629
4630 However, it is sometimes useful to define memory constraints that allow
4631 addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}.
4632 @code{define_relaxed_memory_constraint} exists for this case.
4633 The test expression in a @code{define_relaxed_memory_constraint} is
4634 applied with no preconditions, so that the expression can determine
4635 ``from scratch'' exactly which addresses are valid and which are not.
4636
4637 The syntax and semantics are otherwise identical to
4638 @code{define_memory_constraint}.
4639 @end deffn
4640
4641 @deffn {MD Expression} define_address_constraint name docstring exp
4642 Use this expression for constraints that match a subset of all address
4643 operands: that is, @code{reload} can make the constraint match by
4644 converting the operand to the form @samp{@w{(reg @var{X})}}, again
4645 with @var{X} a base register.
4646
4647 Constraints defined with @code{define_address_constraint} can only be
4648 used with the @code{address_operand} predicate, or machine-specific
4649 predicates that work the same way. They are treated analogously to
4650 the generic @samp{p} constraint.
4651
4652 The syntax and semantics are otherwise identical to
4653 @code{define_constraint}.
4654 @end deffn
4655
4656 For historical reasons, names beginning with the letters @samp{G H}
4657 are reserved for constraints that match only @code{const_double}s, and
4658 names beginning with the letters @samp{I J K L M N O P} are reserved
4659 for constraints that match only @code{const_int}s. This may change in
4660 the future. For the time being, constraints with these names must be
4661 written in a stylized form, so that @code{genpreds} can tell you did
4662 it correctly:
4663
4664 @smallexample
4665 @group
4666 (define_constraint "[@var{GHIJKLMNOP}]@dots{}"
4667 "@var{doc}@dots{}"
4668 (and (match_code "const_int") ; @r{@code{const_double} for G/H}
4669 @var{condition}@dots{})) ; @r{usually a @code{match_test}}
4670 @end group
4671 @end smallexample
4672 @c the semicolons line up in the formatted manual
4673
4674 It is fine to use names beginning with other letters for constraints
4675 that match @code{const_double}s or @code{const_int}s.
4676
4677 Each docstring in a constraint definition should be one or more complete
4678 sentences, marked up in Texinfo format. @emph{They are currently unused.}
4679 In the future they will be copied into the GCC manual, in @ref{Machine
4680 Constraints}, replacing the hand-maintained tables currently found in
4681 that section. Also, in the future the compiler may use this to give
4682 more helpful diagnostics when poor choice of @code{asm} constraints
4683 causes a reload failure.
4684
4685 If you put the pseudo-Texinfo directive @samp{@@internal} at the
4686 beginning of a docstring, then (in the future) it will appear only in
4687 the internals manual's version of the machine-specific constraint tables.
4688 Use this for constraints that should not appear in @code{asm} statements.
4689
4690 @node C Constraint Interface
4691 @subsection Testing constraints from C
4692 @cindex testing constraints
4693 @cindex constraints, testing
4694
4695 It is occasionally useful to test a constraint from C code rather than
4696 implicitly via the constraint string in a @code{match_operand}. The
4697 generated file @file{tm_p.h} declares a few interfaces for working
4698 with constraints. At present these are defined for all constraints
4699 except @code{g} (which is equivalent to @code{general_operand}).
4700
4701 Some valid constraint names are not valid C identifiers, so there is a
4702 mangling scheme for referring to them from C@. Constraint names that
4703 do not contain angle brackets or underscores are left unchanged.
4704 Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and
4705 each @samp{>} with @samp{_g}. Here are some examples:
4706
4707 @c the @c's prevent double blank lines in the printed manual.
4708 @example
4709 @multitable {Original} {Mangled}
4710 @item @strong{Original} @tab @strong{Mangled} @c
4711 @item @code{x} @tab @code{x} @c
4712 @item @code{P42x} @tab @code{P42x} @c
4713 @item @code{P4_x} @tab @code{P4__x} @c
4714 @item @code{P4>x} @tab @code{P4_gx} @c
4715 @item @code{P4>>} @tab @code{P4_g_g} @c
4716 @item @code{P4_g>} @tab @code{P4__g_g} @c
4717 @end multitable
4718 @end example
4719
4720 Throughout this section, the variable @var{c} is either a constraint
4721 in the abstract sense, or a constant from @code{enum constraint_num};
4722 the variable @var{m} is a mangled constraint name (usually as part of
4723 a larger identifier).
4724
4725 @deftp Enum constraint_num
4726 For each constraint except @code{g}, there is a corresponding
4727 enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
4728 constraint. Functions that take an @code{enum constraint_num} as an
4729 argument expect one of these constants.
4730 @end deftp
4731
4732 @deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
4733 For each non-register constraint @var{m} except @code{g}, there is
4734 one of these functions; it returns @code{true} if @var{exp} satisfies the
4735 constraint. These functions are only visible if @file{rtl.h} was included
4736 before @file{tm_p.h}.
4737 @end deftypefun
4738
4739 @deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
4740 Like the @code{satisfies_constraint_@var{m}} functions, but the
4741 constraint to test is given as an argument, @var{c}. If @var{c}
4742 specifies a register constraint, this function will always return
4743 @code{false}.
4744 @end deftypefun
4745
4746 @deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c})
4747 Returns the register class associated with @var{c}. If @var{c} is not
4748 a register constraint, or those registers are not available for the
4749 currently selected subtarget, returns @code{NO_REGS}.
4750 @end deftypefun
4751
4752 Here is an example use of @code{satisfies_constraint_@var{m}}. In
4753 peephole optimizations (@pxref{Peephole Definitions}), operand
4754 constraint strings are ignored, so if there are relevant constraints,
4755 they must be tested in the C condition. In the example, the
4756 optimization is applied if operand 2 does @emph{not} satisfy the
4757 @samp{K} constraint. (This is a simplified version of a peephole
4758 definition from the i386 machine description.)
4759
4760 @smallexample
4761 (define_peephole2
4762 [(match_scratch:SI 3 "r")
4763 (set (match_operand:SI 0 "register_operand" "")
4764 (mult:SI (match_operand:SI 1 "memory_operand" "")
4765 (match_operand:SI 2 "immediate_operand" "")))]
4766
4767 "!satisfies_constraint_K (operands[2])"
4768
4769 [(set (match_dup 3) (match_dup 1))
4770 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]
4771
4772 "")
4773 @end smallexample
4774
4775 @node Standard Names
4776 @section Standard Pattern Names For Generation
4777 @cindex standard pattern names
4778 @cindex pattern names
4779 @cindex names, pattern
4780
4781 Here is a table of the instruction names that are meaningful in the RTL
4782 generation pass of the compiler. Giving one of these names to an
4783 instruction pattern tells the RTL generation pass that it can use the
4784 pattern to accomplish a certain task.
4785
4786 @table @asis
4787 @cindex @code{mov@var{m}} instruction pattern
4788 @item @samp{mov@var{m}}
4789 Here @var{m} stands for a two-letter machine mode name, in lowercase.
4790 This instruction pattern moves data with that machine mode from operand
4791 1 to operand 0. For example, @samp{movsi} moves full-word data.
4792
4793 If operand 0 is a @code{subreg} with mode @var{m} of a register whose
4794 own mode is wider than @var{m}, the effect of this instruction is
4795 to store the specified value in the part of the register that corresponds
4796 to mode @var{m}. Bits outside of @var{m}, but which are within the
4797 same target word as the @code{subreg} are undefined. Bits which are
4798 outside the target word are left unchanged.
4799
4800 This class of patterns is special in several ways. First of all, each
4801 of these names up to and including full word size @emph{must} be defined,
4802 because there is no other way to copy a datum from one place to another.
4803 If there are patterns accepting operands in larger modes,
4804 @samp{mov@var{m}} must be defined for integer modes of those sizes.
4805
4806 Second, these patterns are not used solely in the RTL generation pass.
4807 Even the reload pass can generate move insns to copy values from stack
4808 slots into temporary registers. When it does so, one of the operands is
4809 a hard register and the other is an operand that can need to be reloaded
4810 into a register.
4811
4812 @findex force_reg
4813 Therefore, when given such a pair of operands, the pattern must generate
4814 RTL which needs no reloading and needs no temporary registers---no
4815 registers other than the operands. For example, if you support the
4816 pattern with a @code{define_expand}, then in such a case the
4817 @code{define_expand} mustn't call @code{force_reg} or any other such
4818 function which might generate new pseudo registers.
4819
4820 This requirement exists even for subword modes on a RISC machine where
4821 fetching those modes from memory normally requires several insns and
4822 some temporary registers.
4823
4824 @findex change_address
4825 During reload a memory reference with an invalid address may be passed
4826 as an operand. Such an address will be replaced with a valid address
4827 later in the reload pass. In this case, nothing may be done with the
4828 address except to use it as it stands. If it is copied, it will not be
4829 replaced with a valid address. No attempt should be made to make such
4830 an address into a valid address and no routine (such as
4831 @code{change_address}) that will do so may be called. Note that
4832 @code{general_operand} will fail when applied to such an address.
4833
4834 @findex reload_in_progress
4835 The global variable @code{reload_in_progress} (which must be explicitly
4836 declared if required) can be used to determine whether such special
4837 handling is required.
4838
4839 The variety of operands that have reloads depends on the rest of the
4840 machine description, but typically on a RISC machine these can only be
4841 pseudo registers that did not get hard registers, while on other
4842 machines explicit memory references will get optional reloads.
4843
4844 If a scratch register is required to move an object to or from memory,
4845 it can be allocated using @code{gen_reg_rtx} prior to life analysis.
4846
4847 If there are cases which need scratch registers during or after reload,
4848 you must provide an appropriate secondary_reload target hook.
4849
4850 @findex can_create_pseudo_p
4851 The macro @code{can_create_pseudo_p} can be used to determine if it
4852 is unsafe to create new pseudo registers. If this variable is nonzero, then
4853 it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
4854
4855 The constraints on a @samp{mov@var{m}} must permit moving any hard
4856 register to any other hard register provided that
4857 @code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
4858 @code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
4859 of 2.
4860
4861 It is obligatory to support floating point @samp{mov@var{m}}
4862 instructions into and out of any registers that can hold fixed point
4863 values, because unions and structures (which have modes @code{SImode} or
4864 @code{DImode}) can be in those registers and they may have floating
4865 point members.
4866
4867 There may also be a need to support fixed point @samp{mov@var{m}}
4868 instructions in and out of floating point registers. Unfortunately, I
4869 have forgotten why this was so, and I don't know whether it is still
4870 true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in
4871 floating point registers, then the constraints of the fixed point
4872 @samp{mov@var{m}} instructions must be designed to avoid ever trying to
4873 reload into a floating point register.
4874
4875 @cindex @code{reload_in} instruction pattern
4876 @cindex @code{reload_out} instruction pattern
4877 @item @samp{reload_in@var{m}}
4878 @itemx @samp{reload_out@var{m}}
4879 These named patterns have been obsoleted by the target hook
4880 @code{secondary_reload}.
4881
4882 Like @samp{mov@var{m}}, but used when a scratch register is required to
4883 move between operand 0 and operand 1. Operand 2 describes the scratch
4884 register. See the discussion of the @code{SECONDARY_RELOAD_CLASS}
4885 macro in @pxref{Register Classes}.
4886
4887 There are special restrictions on the form of the @code{match_operand}s
4888 used in these patterns. First, only the predicate for the reload
4889 operand is examined, i.e., @code{reload_in} examines operand 1, but not
4890 the predicates for operand 0 or 2. Second, there may be only one
4891 alternative in the constraints. Third, only a single register class
4892 letter may be used for the constraint; subsequent constraint letters
4893 are ignored. As a special exception, an empty constraint string
4894 matches the @code{ALL_REGS} register class. This may relieve ports
4895 of the burden of defining an @code{ALL_REGS} constraint letter just
4896 for these patterns.
4897
4898 @cindex @code{movstrict@var{m}} instruction pattern
4899 @item @samp{movstrict@var{m}}
4900 Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
4901 with mode @var{m} of a register whose natural mode is wider,
4902 the @samp{movstrict@var{m}} instruction is guaranteed not to alter
4903 any of the register except the part which belongs to mode @var{m}.
4904
4905 @cindex @code{movmisalign@var{m}} instruction pattern
4906 @item @samp{movmisalign@var{m}}
4907 This variant of a move pattern is designed to load or store a value
4908 from a memory address that is not naturally aligned for its mode.
4909 For a store, the memory will be in operand 0; for a load, the memory
4910 will be in operand 1. The other operand is guaranteed not to be a
4911 memory, so that it's easy to tell whether this is a load or store.
4912
4913 This pattern is used by the autovectorizer, and when expanding a
4914 @code{MISALIGNED_INDIRECT_REF} expression.
4915
4916 @cindex @code{load_multiple} instruction pattern
4917 @item @samp{load_multiple}
4918 Load several consecutive memory locations into consecutive registers.
4919 Operand 0 is the first of the consecutive registers, operand 1
4920 is the first memory location, and operand 2 is a constant: the
4921 number of consecutive registers.
4922
4923 Define this only if the target machine really has such an instruction;
4924 do not define this if the most efficient way of loading consecutive
4925 registers from memory is to do them one at a time.
4926
4927 On some machines, there are restrictions as to which consecutive
4928 registers can be stored into memory, such as particular starting or
4929 ending register numbers or only a range of valid counts. For those
4930 machines, use a @code{define_expand} (@pxref{Expander Definitions})
4931 and make the pattern fail if the restrictions are not met.
4932
4933 Write the generated insn as a @code{parallel} with elements being a
4934 @code{set} of one register from the appropriate memory location (you may
4935 also need @code{use} or @code{clobber} elements). Use a
4936 @code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See
4937 @file{rs6000.md} for examples of the use of this insn pattern.
4938
4939 @cindex @samp{store_multiple} instruction pattern
4940 @item @samp{store_multiple}
4941 Similar to @samp{load_multiple}, but store several consecutive registers
4942 into consecutive memory locations. Operand 0 is the first of the
4943 consecutive memory locations, operand 1 is the first register, and
4944 operand 2 is a constant: the number of consecutive registers.
4945
4946 @cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
4947 @item @samp{vec_load_lanes@var{m}@var{n}}
4948 Perform an interleaved load of several vectors from memory operand 1
4949 into register operand 0. Both operands have mode @var{m}. The register
4950 operand is viewed as holding consecutive vectors of mode @var{n},
4951 while the memory operand is a flat array that contains the same number
4952 of elements. The operation is equivalent to:
4953
4954 @smallexample
4955 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4956 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4957 for (i = 0; i < c; i++)
4958 operand0[i][j] = operand1[j * c + i];
4959 @end smallexample
4960
4961 For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
4962 from memory into a register of mode @samp{TI}@. The register
4963 contains two consecutive vectors of mode @samp{V4HI}@.
4964
4965 This pattern can only be used if:
4966 @smallexample
4967 TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
4968 @end smallexample
4969 is true. GCC assumes that, if a target supports this kind of
4970 instruction for some mode @var{n}, it also supports unaligned
4971 loads for vectors of mode @var{n}.
4972
4973 This pattern is not allowed to @code{FAIL}.
4974
4975 @cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern
4976 @item @samp{vec_mask_load_lanes@var{m}@var{n}}
4977 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
4978 mask operand (operand 2) that specifies which elements of the destination
4979 vectors should be loaded. Other elements of the destination
4980 vectors are set to zero. The operation is equivalent to:
4981
4982 @smallexample
4983 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4984 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4985 if (operand2[j])
4986 for (i = 0; i < c; i++)
4987 operand0[i][j] = operand1[j * c + i];
4988 else
4989 for (i = 0; i < c; i++)
4990 operand0[i][j] = 0;
4991 @end smallexample
4992
4993 This pattern is not allowed to @code{FAIL}.
4994
4995 @cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
4996 @item @samp{vec_store_lanes@var{m}@var{n}}
4997 Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
4998 and register operands reversed. That is, the instruction is
4999 equivalent to:
5000
5001 @smallexample
5002 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5003 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5004 for (i = 0; i < c; i++)
5005 operand0[j * c + i] = operand1[i][j];
5006 @end smallexample
5007
5008 for a memory operand 0 and register operand 1.
5009
5010 This pattern is not allowed to @code{FAIL}.
5011
5012 @cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern
5013 @item @samp{vec_mask_store_lanes@var{m}@var{n}}
5014 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
5015 mask operand (operand 2) that specifies which elements of the source
5016 vectors should be stored. The operation is equivalent to:
5017
5018 @smallexample
5019 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
5020 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
5021 if (operand2[j])
5022 for (i = 0; i < c; i++)
5023 operand0[j * c + i] = operand1[i][j];
5024 @end smallexample
5025
5026 This pattern is not allowed to @code{FAIL}.
5027
5028 @cindex @code{gather_load@var{m}@var{n}} instruction pattern
5029 @item @samp{gather_load@var{m}@var{n}}
5030 Load several separate memory locations into a vector of mode @var{m}.
5031 Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n}
5032 containing offsets from that base. Operand 0 is a destination vector with
5033 the same number of elements as @var{n}. For each element index @var{i}:
5034
5035 @itemize @bullet
5036 @item
5037 extend the offset element @var{i} to address width, using zero
5038 extension if operand 3 is 1 and sign extension if operand 3 is zero;
5039 @item
5040 multiply the extended offset by operand 4;
5041 @item
5042 add the result to the base; and
5043 @item
5044 load the value at that address into element @var{i} of operand 0.
5045 @end itemize
5046
5047 The value of operand 3 does not matter if the offsets are already
5048 address width.
5049
5050 @cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern
5051 @item @samp{mask_gather_load@var{m}@var{n}}
5052 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as
5053 operand 5. Bit @var{i} of the mask is set if element @var{i}
5054 of the result should be loaded from memory and clear if element @var{i}
5055 of the result should be set to zero.
5056
5057 @cindex @code{scatter_store@var{m}@var{n}} instruction pattern
5058 @item @samp{scatter_store@var{m}@var{n}}
5059 Store a vector of mode @var{m} into several distinct memory locations.
5060 Operand 0 is a scalar base address and operand 1 is a vector of mode
5061 @var{n} containing offsets from that base. Operand 4 is the vector of
5062 values that should be stored, which has the same number of elements as
5063 @var{n}. For each element index @var{i}:
5064
5065 @itemize @bullet
5066 @item
5067 extend the offset element @var{i} to address width, using zero
5068 extension if operand 2 is 1 and sign extension if operand 2 is zero;
5069 @item
5070 multiply the extended offset by operand 3;
5071 @item
5072 add the result to the base; and
5073 @item
5074 store element @var{i} of operand 4 to that address.
5075 @end itemize
5076
5077 The value of operand 2 does not matter if the offsets are already
5078 address width.
5079
5080 @cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern
5081 @item @samp{mask_scatter_store@var{m}@var{n}}
5082 Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as
5083 operand 5. Bit @var{i} of the mask is set if element @var{i}
5084 of the result should be stored to memory.
5085
5086 @cindex @code{vec_set@var{m}} instruction pattern
5087 @item @samp{vec_set@var{m}}
5088 Set given field in the vector value. Operand 0 is the vector to modify,
5089 operand 1 is new value of field and operand 2 specify the field index.
5090
5091 @cindex @code{vec_extract@var{m}@var{n}} instruction pattern
5092 @item @samp{vec_extract@var{m}@var{n}}
5093 Extract given field from the vector value. Operand 1 is the vector, operand 2
5094 specify field index and operand 0 place to store value into. The
5095 @var{n} mode is the mode of the field or vector of fields that should be
5096 extracted, should be either element mode of the vector mode @var{m}, or
5097 a vector mode with the same element mode and smaller number of elements.
5098 If @var{n} is a vector mode, the index is counted in units of that mode.
5099
5100 @cindex @code{vec_init@var{m}@var{n}} instruction pattern
5101 @item @samp{vec_init@var{m}@var{n}}
5102 Initialize the vector to given values. Operand 0 is the vector to initialize
5103 and operand 1 is parallel containing values for individual fields. The
5104 @var{n} mode is the mode of the elements, should be either element mode of
5105 the vector mode @var{m}, or a vector mode with the same element mode and
5106 smaller number of elements.
5107
5108 @cindex @code{vec_duplicate@var{m}} instruction pattern
5109 @item @samp{vec_duplicate@var{m}}
5110 Initialize vector output operand 0 so that each element has the value given
5111 by scalar input operand 1. The vector has mode @var{m} and the scalar has
5112 the mode appropriate for one element of @var{m}.
5113
5114 This pattern only handles duplicates of non-constant inputs. Constant
5115 vectors go through the @code{mov@var{m}} pattern instead.
5116
5117 This pattern is not allowed to @code{FAIL}.
5118
5119 @cindex @code{vec_series@var{m}} instruction pattern
5120 @item @samp{vec_series@var{m}}
5121 Initialize vector output operand 0 so that element @var{i} is equal to
5122 operand 1 plus @var{i} times operand 2. In other words, create a linear
5123 series whose base value is operand 1 and whose step is operand 2.
5124
5125 The vector output has mode @var{m} and the scalar inputs have the mode
5126 appropriate for one element of @var{m}. This pattern is not used for
5127 floating-point vectors, in order to avoid having to specify the
5128 rounding behavior for @var{i} > 1.
5129
5130 This pattern is not allowed to @code{FAIL}.
5131
5132 @cindex @code{while_ult@var{m}@var{n}} instruction pattern
5133 @item @code{while_ult@var{m}@var{n}}
5134 Set operand 0 to a mask that is true while incrementing operand 1
5135 gives a value that is less than operand 2. Operand 0 has mode @var{n}
5136 and operands 1 and 2 are scalar integers of mode @var{m}.
5137 The operation is equivalent to:
5138
5139 @smallexample
5140 operand0[0] = operand1 < operand2;
5141 for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++)
5142 operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
5143 @end smallexample
5144
5145 @cindex @code{check_raw_ptrs@var{m}} instruction pattern
5146 @item @samp{check_raw_ptrs@var{m}}
5147 Check whether, given two pointers @var{a} and @var{b} and a length @var{len},
5148 a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes
5149 at @var{b} can be split into interleaved byte accesses
5150 @samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}}
5151 without affecting the dependencies between the bytes. Set operand 0
5152 to true if the split is possible and false otherwise.
5153
5154 Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len}
5155 respectively. Operand 4 is a constant integer that provides the known
5156 common alignment of @var{a} and @var{b}. All inputs have mode @var{m}.
5157
5158 This split is possible if:
5159
5160 @smallexample
5161 @var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a}
5162 @end smallexample
5163
5164 You should only define this pattern if the target has a way of accelerating
5165 the test without having to do the individual comparisons.
5166
5167 @cindex @code{check_war_ptrs@var{m}} instruction pattern
5168 @item @samp{check_war_ptrs@var{m}}
5169 Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round.
5170 The split is possible in this case if:
5171
5172 @smallexample
5173 @var{b} <= @var{a} || @var{a} + @var{len} <= @var{b}
5174 @end smallexample
5175
5176 @cindex @code{vec_cmp@var{m}@var{n}} instruction pattern
5177 @item @samp{vec_cmp@var{m}@var{n}}
5178 Output a vector comparison. Operand 0 of mode @var{n} is the destination for
5179 predicate in operand 1 which is a signed vector comparison with operands of
5180 mode @var{m} in operands 2 and 3. Predicate is computed by element-wise
5181 evaluation of the vector comparison with a truth value of all-ones and a false
5182 value of all-zeros.
5183
5184 @cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern
5185 @item @samp{vec_cmpu@var{m}@var{n}}
5186 Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison.
5187
5188 @cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern
5189 @item @samp{vec_cmpeq@var{m}@var{n}}
5190 Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality
5191 vector comparison only. If @code{vec_cmp@var{m}@var{n}}
5192 or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported,
5193 it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is
5194 no need to define this instruction pattern if the others are supported.
5195
5196 @cindex @code{vcond@var{m}@var{n}} instruction pattern
5197 @item @samp{vcond@var{m}@var{n}}
5198 Output a conditional vector move. Operand 0 is the destination to
5199 receive a combination of operand 1 and operand 2, which are of mode @var{m},
5200 dependent on the outcome of the predicate in operand 3 which is a signed
5201 vector comparison with operands of mode @var{n} in operands 4 and 5. The
5202 modes @var{m} and @var{n} should have the same size. Operand 0
5203 will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk}
5204 where @var{msk} is computed by element-wise evaluation of the vector
5205 comparison with a truth value of all-ones and a false value of all-zeros.
5206
5207 @cindex @code{vcondu@var{m}@var{n}} instruction pattern
5208 @item @samp{vcondu@var{m}@var{n}}
5209 Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector
5210 comparison.
5211
5212 @cindex @code{vcondeq@var{m}@var{n}} instruction pattern
5213 @item @samp{vcondeq@var{m}@var{n}}
5214 Similar to @code{vcond@var{m}@var{n}} but performs equality or
5215 non-equality vector comparison only. If @code{vcond@var{m}@var{n}}
5216 or @code{vcondu@var{m}@var{n}} instruction pattern is supported,
5217 it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is
5218 no need to define this instruction pattern if the others are supported.
5219
5220 @cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern
5221 @item @samp{vcond_mask_@var{m}@var{n}}
5222 Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed
5223 result of vector comparison.
5224
5225 @cindex @code{maskload@var{m}@var{n}} instruction pattern
5226 @item @samp{maskload@var{m}@var{n}}
5227 Perform a masked load of vector from memory operand 1 of mode @var{m}
5228 into register operand 0. Mask is provided in register operand 2 of
5229 mode @var{n}.
5230
5231 This pattern is not allowed to @code{FAIL}.
5232
5233 @cindex @code{maskstore@var{m}@var{n}} instruction pattern
5234 @item @samp{maskstore@var{m}@var{n}}
5235 Perform a masked store of vector from register operand 1 of mode @var{m}
5236 into memory operand 0. Mask is provided in register operand 2 of
5237 mode @var{n}.
5238
5239 This pattern is not allowed to @code{FAIL}.
5240
5241 @cindex @code{len_load_@var{m}} instruction pattern
5242 @item @samp{len_load_@var{m}}
5243 Load (operand 2 - operand 3) elements from vector memory operand 1
5244 into vector register operand 0, setting the other elements of
5245 operand 0 to undefined values. Operands 0 and 1 have mode @var{m},
5246 which must be a vector mode. Operand 2 has whichever integer mode the
5247 target prefers. Operand 3 conceptually has mode @code{QI}.
5248
5249 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5250 constant bias: it is either a constant 0 or a constant -1. The predicate on
5251 operand 3 must only accept the bias values that the target actually supports.
5252 GCC handles a bias of 0 more efficiently than a bias of -1.
5253
5254 If (operand 2 - operand 3) exceeds the number of elements in mode
5255 @var{m}, the behavior is undefined.
5256
5257 If the target prefers the length to be measured in bytes rather than
5258 elements, it should only implement this pattern for vectors of @code{QI}
5259 elements.
5260
5261 This pattern is not allowed to @code{FAIL}.
5262
5263 @cindex @code{len_store_@var{m}} instruction pattern
5264 @item @samp{len_store_@var{m}}
5265 Store (operand 2 - operand 3) vector elements from vector register operand 1
5266 into memory operand 0, leaving the other elements of
5267 operand 0 unchanged. Operands 0 and 1 have mode @var{m}, which must be
5268 a vector mode. Operand 2 has whichever integer mode the target prefers.
5269 Operand 3 conceptually has mode @code{QI}.
5270
5271 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5272 constant bias: it is either a constant 0 or a constant -1. The predicate on
5273 operand 3 must only accept the bias values that the target actually supports.
5274 GCC handles a bias of 0 more efficiently than a bias of -1.
5275
5276 If (operand 2 - operand 3) exceeds the number of elements in mode
5277 @var{m}, the behavior is undefined.
5278
5279 If the target prefers the length to be measured in bytes
5280 rather than elements, it should only implement this pattern for vectors
5281 of @code{QI} elements.
5282
5283 This pattern is not allowed to @code{FAIL}.
5284
5285 @cindex @code{vec_perm@var{m}} instruction pattern
5286 @item @samp{vec_perm@var{m}}
5287 Output a (variable) vector permutation. Operand 0 is the destination
5288 to receive elements from operand 1 and operand 2, which are of mode
5289 @var{m}. Operand 3 is the @dfn{selector}. It is an integral mode
5290 vector of the same width and number of elements as mode @var{m}.
5291
5292 The input elements are numbered from 0 in operand 1 through
5293 @math{2*@var{N}-1} in operand 2. The elements of the selector must
5294 be computed modulo @math{2*@var{N}}. Note that if
5295 @code{rtx_equal_p(operand1, operand2)}, this can be implemented
5296 with just operand 1 and selector elements modulo @var{N}.
5297
5298 In order to make things easy for a number of targets, if there is no
5299 @samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
5300 where @var{q} is a vector of @code{QImode} of the same width as @var{m},
5301 the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
5302 mode @var{q}.
5303
5304 See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs
5305 the analogous operation for constant selectors.
5306
5307 @cindex @code{push@var{m}1} instruction pattern
5308 @item @samp{push@var{m}1}
5309 Output a push instruction. Operand 0 is value to push. Used only when
5310 @code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be
5311 missing and in such case an @code{mov} expander is used instead, with a
5312 @code{MEM} expression forming the push operation. The @code{mov} expander
5313 method is deprecated.
5314
5315 @cindex @code{add@var{m}3} instruction pattern
5316 @item @samp{add@var{m}3}
5317 Add operand 2 and operand 1, storing the result in operand 0. All operands
5318 must have mode @var{m}. This can be used even on two-address machines, by
5319 means of constraints requiring operands 1 and 0 to be the same location.
5320
5321 @cindex @code{ssadd@var{m}3} instruction pattern
5322 @cindex @code{usadd@var{m}3} instruction pattern
5323 @cindex @code{sub@var{m}3} instruction pattern
5324 @cindex @code{sssub@var{m}3} instruction pattern
5325 @cindex @code{ussub@var{m}3} instruction pattern
5326 @cindex @code{mul@var{m}3} instruction pattern
5327 @cindex @code{ssmul@var{m}3} instruction pattern
5328 @cindex @code{usmul@var{m}3} instruction pattern
5329 @cindex @code{div@var{m}3} instruction pattern
5330 @cindex @code{ssdiv@var{m}3} instruction pattern
5331 @cindex @code{udiv@var{m}3} instruction pattern
5332 @cindex @code{usdiv@var{m}3} instruction pattern
5333 @cindex @code{mod@var{m}3} instruction pattern
5334 @cindex @code{umod@var{m}3} instruction pattern
5335 @cindex @code{umin@var{m}3} instruction pattern
5336 @cindex @code{umax@var{m}3} instruction pattern
5337 @cindex @code{and@var{m}3} instruction pattern
5338 @cindex @code{ior@var{m}3} instruction pattern
5339 @cindex @code{xor@var{m}3} instruction pattern
5340 @item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
5341 @itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
5342 @itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
5343 @itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
5344 @itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
5345 @itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
5346 @itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
5347 @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
5348 Similar, for other arithmetic operations.
5349
5350 @cindex @code{addv@var{m}4} instruction pattern
5351 @item @samp{addv@var{m}4}
5352 Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and
5353 emits code to jump to it if signed overflow occurs during the addition.
5354 This pattern is used to implement the built-in functions performing
5355 signed integer addition with overflow checking.
5356
5357 @cindex @code{subv@var{m}4} instruction pattern
5358 @cindex @code{mulv@var{m}4} instruction pattern
5359 @item @samp{subv@var{m}4}, @samp{mulv@var{m}4}
5360 Similar, for other signed arithmetic operations.
5361
5362 @cindex @code{uaddv@var{m}4} instruction pattern
5363 @item @samp{uaddv@var{m}4}
5364 Like @code{addv@var{m}4} but for unsigned addition. That is to
5365 say, the operation is the same as signed addition but the jump
5366 is taken only on unsigned overflow.
5367
5368 @cindex @code{usubv@var{m}4} instruction pattern
5369 @cindex @code{umulv@var{m}4} instruction pattern
5370 @item @samp{usubv@var{m}4}, @samp{umulv@var{m}4}
5371 Similar, for other unsigned arithmetic operations.
5372
5373 @cindex @code{addptr@var{m}3} instruction pattern
5374 @item @samp{addptr@var{m}3}
5375 Like @code{add@var{m}3} but is guaranteed to only be used for address
5376 calculations. The expanded code is not allowed to clobber the
5377 condition code. It only needs to be defined if @code{add@var{m}3}
5378 sets the condition code. If adds used for address calculations and
5379 normal adds are not compatible it is required to expand a distinct
5380 pattern (e.g.@: using an unspec). The pattern is used by LRA to emit
5381 address calculations. @code{add@var{m}3} is used if
5382 @code{addptr@var{m}3} is not defined.
5383
5384 @cindex @code{fma@var{m}4} instruction pattern
5385 @item @samp{fma@var{m}4}
5386 Multiply operand 2 and operand 1, then add operand 3, storing the
5387 result in operand 0 without doing an intermediate rounding step. All
5388 operands must have mode @var{m}. This pattern is used to implement
5389 the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from
5390 the ISO C99 standard.
5391
5392 @cindex @code{fms@var{m}4} instruction pattern
5393 @item @samp{fms@var{m}4}
5394 Like @code{fma@var{m}4}, except operand 3 subtracted from the
5395 product instead of added to the product. This is represented
5396 in the rtl as
5397
5398 @smallexample
5399 (fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
5400 @end smallexample
5401
5402 @cindex @code{fnma@var{m}4} instruction pattern
5403 @item @samp{fnma@var{m}4}
5404 Like @code{fma@var{m}4} except that the intermediate product
5405 is negated before being added to operand 3. This is represented
5406 in the rtl as
5407
5408 @smallexample
5409 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
5410 @end smallexample
5411
5412 @cindex @code{fnms@var{m}4} instruction pattern
5413 @item @samp{fnms@var{m}4}
5414 Like @code{fms@var{m}4} except that the intermediate product
5415 is negated before subtracting operand 3. This is represented
5416 in the rtl as
5417
5418 @smallexample
5419 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
5420 @end smallexample
5421
5422 @cindex @code{min@var{m}3} instruction pattern
5423 @cindex @code{max@var{m}3} instruction pattern
5424 @item @samp{smin@var{m}3}, @samp{smax@var{m}3}
5425 Signed minimum and maximum operations. When used with floating point,
5426 if both operands are zeros, or if either operand is @code{NaN}, then
5427 it is unspecified which of the two operands is returned as the result.
5428
5429 @cindex @code{fmin@var{m}3} instruction pattern
5430 @cindex @code{fmax@var{m}3} instruction pattern
5431 @item @samp{fmin@var{m}3}, @samp{fmax@var{m}3}
5432 IEEE-conformant minimum and maximum operations. If one operand is a quiet
5433 @code{NaN}, then the other operand is returned. If both operands are quiet
5434 @code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports
5435 signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is
5436 raised and a quiet @code{NaN} is returned.
5437
5438 All operands have mode @var{m}, which is a scalar or vector
5439 floating-point mode. These patterns are not allowed to @code{FAIL}.
5440
5441 @cindex @code{reduc_smin_scal_@var{m}} instruction pattern
5442 @cindex @code{reduc_smax_scal_@var{m}} instruction pattern
5443 @item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}}
5444 Find the signed minimum/maximum of the elements of a vector. The vector is
5445 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5446 the elements of the input vector.
5447
5448 @cindex @code{reduc_umin_scal_@var{m}} instruction pattern
5449 @cindex @code{reduc_umax_scal_@var{m}} instruction pattern
5450 @item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}}
5451 Find the unsigned minimum/maximum of the elements of a vector. The vector is
5452 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5453 the elements of the input vector.
5454
5455 @cindex @code{reduc_fmin_scal_@var{m}} instruction pattern
5456 @cindex @code{reduc_fmax_scal_@var{m}} instruction pattern
5457 @item @samp{reduc_fmin_scal_@var{m}}, @samp{reduc_fmax_scal_@var{m}}
5458 Find the floating-point minimum/maximum of the elements of a vector,
5459 using the same rules as @code{fmin@var{m}3} and @code{fmax@var{m}3}.
5460 Operand 1 is a vector of mode @var{m} and operand 0 is the scalar
5461 result, which has mode @code{GET_MODE_INNER (@var{m})}.
5462
5463 @cindex @code{reduc_plus_scal_@var{m}} instruction pattern
5464 @item @samp{reduc_plus_scal_@var{m}}
5465 Compute the sum of the elements of a vector. The vector is operand 1, and
5466 operand 0 is the scalar result, with mode equal to the mode of the elements of
5467 the input vector.
5468
5469 @cindex @code{reduc_and_scal_@var{m}} instruction pattern
5470 @item @samp{reduc_and_scal_@var{m}}
5471 @cindex @code{reduc_ior_scal_@var{m}} instruction pattern
5472 @itemx @samp{reduc_ior_scal_@var{m}}
5473 @cindex @code{reduc_xor_scal_@var{m}} instruction pattern
5474 @itemx @samp{reduc_xor_scal_@var{m}}
5475 Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements
5476 of a vector of mode @var{m}. Operand 1 is the vector input and operand 0
5477 is the scalar result. The mode of the scalar result is the same as one
5478 element of @var{m}.
5479
5480 @cindex @code{extract_last_@var{m}} instruction pattern
5481 @item @code{extract_last_@var{m}}
5482 Find the last set bit in mask operand 1 and extract the associated element
5483 of vector operand 2. Store the result in scalar operand 0. Operand 2
5484 has vector mode @var{m} while operand 0 has the mode appropriate for one
5485 element of @var{m}. Operand 1 has the usual mask mode for vectors of mode
5486 @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5487
5488 @cindex @code{fold_extract_last_@var{m}} instruction pattern
5489 @item @code{fold_extract_last_@var{m}}
5490 If any bits of mask operand 2 are set, find the last set bit, extract
5491 the associated element from vector operand 3, and store the result
5492 in operand 0. Store operand 1 in operand 0 otherwise. Operand 3
5493 has mode @var{m} and operands 0 and 1 have the mode appropriate for
5494 one element of @var{m}. Operand 2 has the usual mask mode for vectors
5495 of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5496
5497 @cindex @code{fold_left_plus_@var{m}} instruction pattern
5498 @item @code{fold_left_plus_@var{m}}
5499 Take scalar operand 1 and successively add each element from vector
5500 operand 2. Store the result in scalar operand 0. The vector has
5501 mode @var{m} and the scalars have the mode appropriate for one
5502 element of @var{m}. The operation is strictly in-order: there is
5503 no reassociation.
5504
5505 @cindex @code{mask_fold_left_plus_@var{m}} instruction pattern
5506 @item @code{mask_fold_left_plus_@var{m}}
5507 Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
5508 (operand 3) that specifies which elements of the source vector should be added.
5509
5510 @cindex @code{sdot_prod@var{m}} instruction pattern
5511 @item @samp{sdot_prod@var{m}}
5512
5513 Compute the sum of the products of two signed elements.
5514 Operand 1 and operand 2 are of the same mode. Their
5515 product, which is of a wider mode, is computed and added to operand 3.
5516 Operand 3 is of a mode equal or wider than the mode of the product. The
5517 result is placed in operand 0, which is of the same mode as operand 3.
5518
5519 Semantically the expressions perform the multiplication in the following signs
5520
5521 @smallexample
5522 sdot<signed op0, signed op1, signed op2, signed op3> ==
5523 op0 = sign-ext (op1) * sign-ext (op2) + op3
5524 @dots{}
5525 @end smallexample
5526
5527 @cindex @code{udot_prod@var{m}} instruction pattern
5528 @item @samp{udot_prod@var{m}}
5529
5530 Compute the sum of the products of two unsigned elements.
5531 Operand 1 and operand 2 are of the same mode. Their
5532 product, which is of a wider mode, is computed and added to operand 3.
5533 Operand 3 is of a mode equal or wider than the mode of the product. The
5534 result is placed in operand 0, which is of the same mode as operand 3.
5535
5536 Semantically the expressions perform the multiplication in the following signs
5537
5538 @smallexample
5539 udot<unsigned op0, unsigned op1, unsigned op2, unsigned op3> ==
5540 op0 = zero-ext (op1) * zero-ext (op2) + op3
5541 @dots{}
5542 @end smallexample
5543
5544 @cindex @code{usdot_prod@var{m}} instruction pattern
5545 @item @samp{usdot_prod@var{m}}
5546 Compute the sum of the products of elements of different signs.
5547 Operand 1 must be unsigned and operand 2 signed. Their
5548 product, which is of a wider mode, is computed and added to operand 3.
5549 Operand 3 is of a mode equal or wider than the mode of the product. The
5550 result is placed in operand 0, which is of the same mode as operand 3.
5551
5552 Semantically the expressions perform the multiplication in the following signs
5553
5554 @smallexample
5555 usdot<signed op0, unsigned op1, signed op2, signed op3> ==
5556 op0 = ((signed-conv) zero-ext (op1)) * sign-ext (op2) + op3
5557 @dots{}
5558 @end smallexample
5559
5560 @cindex @code{ssad@var{m}} instruction pattern
5561 @item @samp{ssad@var{m}}
5562 @cindex @code{usad@var{m}} instruction pattern
5563 @item @samp{usad@var{m}}
5564 Compute the sum of absolute differences of two signed/unsigned elements.
5565 Operand 1 and operand 2 are of the same mode. Their absolute difference, which
5566 is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode
5567 equal or wider than the mode of the absolute difference. The result is placed
5568 in operand 0, which is of the same mode as operand 3.
5569
5570 @cindex @code{widen_ssum@var{m3}} instruction pattern
5571 @item @samp{widen_ssum@var{m3}}
5572 @cindex @code{widen_usum@var{m3}} instruction pattern
5573 @itemx @samp{widen_usum@var{m3}}
5574 Operands 0 and 2 are of the same mode, which is wider than the mode of
5575 operand 1. Add operand 1 to operand 2 and place the widened result in
5576 operand 0. (This is used express accumulation of elements into an accumulator
5577 of a wider mode.)
5578
5579 @cindex @code{smulhs@var{m3}} instruction pattern
5580 @item @samp{smulhs@var{m3}}
5581 @cindex @code{umulhs@var{m3}} instruction pattern
5582 @itemx @samp{umulhs@var{m3}}
5583 Signed/unsigned multiply high with scale. This is equivalent to the C code:
5584 @smallexample
5585 narrow op0, op1, op2;
5586 @dots{}
5587 op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1));
5588 @end smallexample
5589 where the sign of @samp{narrow} determines whether this is a signed
5590 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5591
5592 @cindex @code{smulhrs@var{m3}} instruction pattern
5593 @item @samp{smulhrs@var{m3}}
5594 @cindex @code{umulhrs@var{m3}} instruction pattern
5595 @itemx @samp{umulhrs@var{m3}}
5596 Signed/unsigned multiply high with round and scale. This is
5597 equivalent to the C code:
5598 @smallexample
5599 narrow op0, op1, op2;
5600 @dots{}
5601 op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1);
5602 @end smallexample
5603 where the sign of @samp{narrow} determines whether this is a signed
5604 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5605
5606 @cindex @code{sdiv_pow2@var{m3}} instruction pattern
5607 @item @samp{sdiv_pow2@var{m3}}
5608 @cindex @code{sdiv_pow2@var{m3}} instruction pattern
5609 @itemx @samp{sdiv_pow2@var{m3}}
5610 Signed division by power-of-2 immediate. Equivalent to:
5611 @smallexample
5612 signed op0, op1;
5613 @dots{}
5614 op0 = op1 / (1 << imm);
5615 @end smallexample
5616
5617 @cindex @code{vec_shl_insert_@var{m}} instruction pattern
5618 @item @samp{vec_shl_insert_@var{m}}
5619 Shift the elements in vector input operand 1 left one element (i.e.@:
5620 away from element 0) and fill the vacated element 0 with the scalar
5621 in operand 2. Store the result in vector output operand 0. Operands
5622 0 and 1 have mode @var{m} and operand 2 has the mode appropriate for
5623 one element of @var{m}.
5624
5625 @cindex @code{vec_shl_@var{m}} instruction pattern
5626 @item @samp{vec_shl_@var{m}}
5627 Whole vector left shift in bits, i.e.@: away from element 0.
5628 Operand 1 is a vector to be shifted.
5629 Operand 2 is an integer shift amount in bits.
5630 Operand 0 is where the resulting shifted vector is stored.
5631 The output and input vectors should have the same modes.
5632
5633 @cindex @code{vec_shr_@var{m}} instruction pattern
5634 @item @samp{vec_shr_@var{m}}
5635 Whole vector right shift in bits, i.e.@: towards element 0.
5636 Operand 1 is a vector to be shifted.
5637 Operand 2 is an integer shift amount in bits.
5638 Operand 0 is where the resulting shifted vector is stored.
5639 The output and input vectors should have the same modes.
5640
5641 @cindex @code{vec_pack_trunc_@var{m}} instruction pattern
5642 @item @samp{vec_pack_trunc_@var{m}}
5643 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5644 are vectors of the same mode having N integral or floating point elements
5645 of size S@. Operand 0 is the resulting vector in which 2*N elements of
5646 size S/2 are concatenated after narrowing them down using truncation.
5647
5648 @cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern
5649 @item @samp{vec_pack_sbool_trunc_@var{m}}
5650 Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors
5651 of the same type having N boolean elements. Operand 0 is the resulting
5652 vector in which 2*N elements are concatenated. The last operand (operand 3)
5653 is the number of elements in the output vector 2*N as a @code{CONST_INT}.
5654 This instruction pattern is used when all the vector input and output
5655 operands have the same scalar mode @var{m} and thus using
5656 @code{vec_pack_trunc_@var{m}} would be ambiguous.
5657
5658 @cindex @code{vec_pack_ssat_@var{m}} instruction pattern
5659 @cindex @code{vec_pack_usat_@var{m}} instruction pattern
5660 @item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
5661 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5662 are vectors of the same mode having N integral elements of size S.
5663 Operand 0 is the resulting vector in which the elements of the two input
5664 vectors are concatenated after narrowing them down using signed/unsigned
5665 saturating arithmetic.
5666
5667 @cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
5668 @cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
5669 @item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
5670 Narrow, convert to signed/unsigned integral type and merge the elements
5671 of two vectors. Operands 1 and 2 are vectors of the same mode having N
5672 floating point elements of size S@. Operand 0 is the resulting vector
5673 in which 2*N elements of size S/2 are concatenated.
5674
5675 @cindex @code{vec_packs_float_@var{m}} instruction pattern
5676 @cindex @code{vec_packu_float_@var{m}} instruction pattern
5677 @item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}}
5678 Narrow, convert to floating point type and merge the elements
5679 of two vectors. Operands 1 and 2 are vectors of the same mode having N
5680 signed/unsigned integral elements of size S@. Operand 0 is the resulting vector
5681 in which 2*N elements of size S/2 are concatenated.
5682
5683 @cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
5684 @cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
5685 @item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
5686 Extract and widen (promote) the high/low part of a vector of signed
5687 integral or floating point elements. The input vector (operand 1) has N
5688 elements of size S@. Widen (promote) the high/low elements of the vector
5689 using signed or floating point extension and place the resulting N/2
5690 values of size 2*S in the output vector (operand 0).
5691
5692 @cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
5693 @cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
5694 @item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
5695 Extract and widen (promote) the high/low part of a vector of unsigned
5696 integral elements. The input vector (operand 1) has N elements of size S.
5697 Widen (promote) the high/low elements of the vector using zero extension and
5698 place the resulting N/2 values of size 2*S in the output vector (operand 0).
5699
5700 @cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern
5701 @cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern
5702 @item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}}
5703 Extract the high/low part of a vector of boolean elements that have scalar
5704 mode @var{m}. The input vector (operand 1) has N elements, the output
5705 vector (operand 0) has N/2 elements. The last operand (operand 2) is the
5706 number of elements of the input vector N as a @code{CONST_INT}. These
5707 patterns are used if both the input and output vectors have the same scalar
5708 mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or
5709 @code{vec_unpacks_lo_@var{m}} would be ambiguous.
5710
5711 @cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
5712 @cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
5713 @cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
5714 @cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
5715 @item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
5716 @itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
5717 Extract, convert to floating point type and widen the high/low part of a
5718 vector of signed/unsigned integral elements. The input vector (operand 1)
5719 has N elements of size S@. Convert the high/low elements of the vector using
5720 floating point conversion and place the resulting N/2 values of size 2*S in
5721 the output vector (operand 0).
5722
5723 @cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern
5724 @cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern
5725 @cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern
5726 @cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern
5727 @item @samp{vec_unpack_sfix_trunc_hi_@var{m}},
5728 @itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}}
5729 @itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}}
5730 @itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}}
5731 Extract, convert to signed/unsigned integer type and widen the high/low part of a
5732 vector of floating point elements. The input vector (operand 1)
5733 has N elements of size S@. Convert the high/low elements of the vector
5734 to integers and place the resulting N/2 values of size 2*S in
5735 the output vector (operand 0).
5736
5737 @cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
5738 @cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern
5739 @cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
5740 @cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
5741 @cindex @code{vec_widen_umult_even_@var{m}} instruction pattern
5742 @cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern
5743 @cindex @code{vec_widen_smult_even_@var{m}} instruction pattern
5744 @cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern
5745 @item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
5746 @itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
5747 @itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}}
5748 @itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}}
5749 Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2)
5750 are vectors with N signed/unsigned elements of size S@. Multiply the high/low
5751 or even/odd elements of the two vectors, and put the N/2 products of size 2*S
5752 in the output vector (operand 0). A target shouldn't implement even/odd pattern
5753 pair if it is less efficient than lo/hi one.
5754
5755 @cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
5756 @cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
5757 @cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
5758 @cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
5759 @item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
5760 @itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
5761 Signed/Unsigned widening shift left. The first input (operand 1) is a vector
5762 with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift
5763 the high/low elements of operand 1, and put the N/2 results of size 2*S in the
5764 output vector (operand 0).
5765
5766 @cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern
5767 @cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern
5768 @cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern
5769 @cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern
5770 @item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}}
5771 @itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}}
5772 Signed/Unsigned widening add long. Operands 1 and 2 are vectors with N
5773 signed/unsigned elements of size S@. Add the high/low elements of 1 and 2
5774 together, widen the resulting elements and put the N/2 results of size 2*S in
5775 the output vector (operand 0).
5776
5777 @cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern
5778 @cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern
5779 @cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern
5780 @cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern
5781 @item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}}
5782 @itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}}
5783 Signed/Unsigned widening subtract long. Operands 1 and 2 are vectors with N
5784 signed/unsigned elements of size S@. Subtract the high/low elements of 2 from
5785 1 and widen the resulting elements. Put the N/2 results of size 2*S in the
5786 output vector (operand 0).
5787
5788 @cindex @code{vec_addsub@var{m}3} instruction pattern
5789 @item @samp{vec_addsub@var{m}3}
5790 Alternating subtract, add with even lanes doing subtract and odd
5791 lanes doing addition. Operands 1 and 2 and the outout operand are vectors
5792 with mode @var{m}.
5793
5794 @cindex @code{vec_fmaddsub@var{m}4} instruction pattern
5795 @item @samp{vec_fmaddsub@var{m}4}
5796 Alternating multiply subtract, add with even lanes doing subtract and odd
5797 lanes doing addition of the third operand to the multiplication result
5798 of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
5799 with mode @var{m}.
5800
5801 @cindex @code{vec_fmsubadd@var{m}4} instruction pattern
5802 @item @samp{vec_fmsubadd@var{m}4}
5803 Alternating multiply add, subtract with even lanes doing addition and odd
5804 lanes doing subtraction of the third operand to the multiplication result
5805 of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
5806 with mode @var{m}.
5807
5808 These instructions are not allowed to @code{FAIL}.
5809
5810 @cindex @code{mulhisi3} instruction pattern
5811 @item @samp{mulhisi3}
5812 Multiply operands 1 and 2, which have mode @code{HImode}, and store
5813 a @code{SImode} product in operand 0.
5814
5815 @cindex @code{mulqihi3} instruction pattern
5816 @cindex @code{mulsidi3} instruction pattern
5817 @item @samp{mulqihi3}, @samp{mulsidi3}
5818 Similar widening-multiplication instructions of other widths.
5819
5820 @cindex @code{umulqihi3} instruction pattern
5821 @cindex @code{umulhisi3} instruction pattern
5822 @cindex @code{umulsidi3} instruction pattern
5823 @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
5824 Similar widening-multiplication instructions that do unsigned
5825 multiplication.
5826
5827 @cindex @code{usmulqihi3} instruction pattern
5828 @cindex @code{usmulhisi3} instruction pattern
5829 @cindex @code{usmulsidi3} instruction pattern
5830 @item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
5831 Similar widening-multiplication instructions that interpret the first
5832 operand as unsigned and the second operand as signed, then do a signed
5833 multiplication.
5834
5835 @cindex @code{smul@var{m}3_highpart} instruction pattern
5836 @item @samp{smul@var{m}3_highpart}
5837 Perform a signed multiplication of operands 1 and 2, which have mode
5838 @var{m}, and store the most significant half of the product in operand 0.
5839 The least significant half of the product is discarded. This may be
5840 represented in RTL using a @code{smul_highpart} RTX expression.
5841
5842 @cindex @code{umul@var{m}3_highpart} instruction pattern
5843 @item @samp{umul@var{m}3_highpart}
5844 Similar, but the multiplication is unsigned. This may be represented
5845 in RTL using an @code{umul_highpart} RTX expression.
5846
5847 @cindex @code{madd@var{m}@var{n}4} instruction pattern
5848 @item @samp{madd@var{m}@var{n}4}
5849 Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
5850 operand 3, and store the result in operand 0. Operands 1 and 2
5851 have mode @var{m} and operands 0 and 3 have mode @var{n}.
5852 Both modes must be integer or fixed-point modes and @var{n} must be twice
5853 the size of @var{m}.
5854
5855 In other words, @code{madd@var{m}@var{n}4} is like
5856 @code{mul@var{m}@var{n}3} except that it also adds operand 3.
5857
5858 These instructions are not allowed to @code{FAIL}.
5859
5860 @cindex @code{umadd@var{m}@var{n}4} instruction pattern
5861 @item @samp{umadd@var{m}@var{n}4}
5862 Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
5863 operands instead of sign-extending them.
5864
5865 @cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
5866 @item @samp{ssmadd@var{m}@var{n}4}
5867 Like @code{madd@var{m}@var{n}4}, but all involved operations must be
5868 signed-saturating.
5869
5870 @cindex @code{usmadd@var{m}@var{n}4} instruction pattern
5871 @item @samp{usmadd@var{m}@var{n}4}
5872 Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
5873 unsigned-saturating.
5874
5875 @cindex @code{msub@var{m}@var{n}4} instruction pattern
5876 @item @samp{msub@var{m}@var{n}4}
5877 Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
5878 result from operand 3, and store the result in operand 0. Operands 1 and 2
5879 have mode @var{m} and operands 0 and 3 have mode @var{n}.
5880 Both modes must be integer or fixed-point modes and @var{n} must be twice
5881 the size of @var{m}.
5882
5883 In other words, @code{msub@var{m}@var{n}4} is like
5884 @code{mul@var{m}@var{n}3} except that it also subtracts the result
5885 from operand 3.
5886
5887 These instructions are not allowed to @code{FAIL}.
5888
5889 @cindex @code{umsub@var{m}@var{n}4} instruction pattern
5890 @item @samp{umsub@var{m}@var{n}4}
5891 Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
5892 operands instead of sign-extending them.
5893
5894 @cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
5895 @item @samp{ssmsub@var{m}@var{n}4}
5896 Like @code{msub@var{m}@var{n}4}, but all involved operations must be
5897 signed-saturating.
5898
5899 @cindex @code{usmsub@var{m}@var{n}4} instruction pattern
5900 @item @samp{usmsub@var{m}@var{n}4}
5901 Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
5902 unsigned-saturating.
5903
5904 @cindex @code{divmod@var{m}4} instruction pattern
5905 @item @samp{divmod@var{m}4}
5906 Signed division that produces both a quotient and a remainder.
5907 Operand 1 is divided by operand 2 to produce a quotient stored
5908 in operand 0 and a remainder stored in operand 3.
5909
5910 For machines with an instruction that produces both a quotient and a
5911 remainder, provide a pattern for @samp{divmod@var{m}4} but do not
5912 provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This
5913 allows optimization in the relatively common case when both the quotient
5914 and remainder are computed.
5915
5916 If an instruction that just produces a quotient or just a remainder
5917 exists and is more efficient than the instruction that produces both,
5918 write the output routine of @samp{divmod@var{m}4} to call
5919 @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
5920 quotient or remainder and generate the appropriate instruction.
5921
5922 @cindex @code{udivmod@var{m}4} instruction pattern
5923 @item @samp{udivmod@var{m}4}
5924 Similar, but does unsigned division.
5925
5926 @anchor{shift patterns}
5927 @cindex @code{ashl@var{m}3} instruction pattern
5928 @cindex @code{ssashl@var{m}3} instruction pattern
5929 @cindex @code{usashl@var{m}3} instruction pattern
5930 @item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
5931 Arithmetic-shift operand 1 left by a number of bits specified by operand
5932 2, and store the result in operand 0. Here @var{m} is the mode of
5933 operand 0 and operand 1; operand 2's mode is specified by the
5934 instruction pattern, and the compiler will convert the operand to that
5935 mode before generating the instruction. The shift or rotate expander
5936 or instruction pattern should explicitly specify the mode of the operand 2,
5937 it should never be @code{VOIDmode}. The meaning of out-of-range shift
5938 counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
5939 @xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type.
5940
5941 @cindex @code{ashr@var{m}3} instruction pattern
5942 @cindex @code{lshr@var{m}3} instruction pattern
5943 @cindex @code{rotl@var{m}3} instruction pattern
5944 @cindex @code{rotr@var{m}3} instruction pattern
5945 @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
5946 Other shift and rotate instructions, analogous to the
5947 @code{ashl@var{m}3} instructions. Operand 2 is always a scalar type.
5948
5949 @cindex @code{vashl@var{m}3} instruction pattern
5950 @cindex @code{vashr@var{m}3} instruction pattern
5951 @cindex @code{vlshr@var{m}3} instruction pattern
5952 @cindex @code{vrotl@var{m}3} instruction pattern
5953 @cindex @code{vrotr@var{m}3} instruction pattern
5954 @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}
5955 Vector shift and rotate instructions that take vectors as operand 2
5956 instead of a scalar type.
5957
5958 @cindex @code{avg@var{m}3_floor} instruction pattern
5959 @cindex @code{uavg@var{m}3_floor} instruction pattern
5960 @item @samp{avg@var{m}3_floor}
5961 @itemx @samp{uavg@var{m}3_floor}
5962 Signed and unsigned average instructions. These instructions add
5963 operands 1 and 2 without truncation, divide the result by 2,
5964 round towards -Inf, and store the result in operand 0. This is
5965 equivalent to the C code:
5966 @smallexample
5967 narrow op0, op1, op2;
5968 @dots{}
5969 op0 = (narrow) (((wide) op1 + (wide) op2) >> 1);
5970 @end smallexample
5971 where the sign of @samp{narrow} determines whether this is a signed
5972 or unsigned operation.
5973
5974 @cindex @code{avg@var{m}3_ceil} instruction pattern
5975 @cindex @code{uavg@var{m}3_ceil} instruction pattern
5976 @item @samp{avg@var{m}3_ceil}
5977 @itemx @samp{uavg@var{m}3_ceil}
5978 Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round
5979 towards +Inf. This is equivalent to the C code:
5980 @smallexample
5981 narrow op0, op1, op2;
5982 @dots{}
5983 op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1);
5984 @end smallexample
5985
5986 @cindex @code{bswap@var{m}2} instruction pattern
5987 @item @samp{bswap@var{m}2}
5988 Reverse the order of bytes of operand 1 and store the result in operand 0.
5989
5990 @cindex @code{neg@var{m}2} instruction pattern
5991 @cindex @code{ssneg@var{m}2} instruction pattern
5992 @cindex @code{usneg@var{m}2} instruction pattern
5993 @item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
5994 Negate operand 1 and store the result in operand 0.
5995
5996 @cindex @code{negv@var{m}3} instruction pattern
5997 @item @samp{negv@var{m}3}
5998 Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and
5999 emits code to jump to it if signed overflow occurs during the negation.
6000
6001 @cindex @code{abs@var{m}2} instruction pattern
6002 @item @samp{abs@var{m}2}
6003 Store the absolute value of operand 1 into operand 0.
6004
6005 @cindex @code{sqrt@var{m}2} instruction pattern
6006 @item @samp{sqrt@var{m}2}
6007 Store the square root of operand 1 into operand 0. Both operands have
6008 mode @var{m}, which is a scalar or vector floating-point mode.
6009
6010 This pattern is not allowed to @code{FAIL}.
6011
6012 @cindex @code{rsqrt@var{m}2} instruction pattern
6013 @item @samp{rsqrt@var{m}2}
6014 Store the reciprocal of the square root of operand 1 into operand 0.
6015 Both operands have mode @var{m}, which is a scalar or vector
6016 floating-point mode.
6017
6018 On most architectures this pattern is only approximate, so either
6019 its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should
6020 check for the appropriate math flags. (Using the C condition is
6021 more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful
6022 if a target-specific built-in also uses the @samp{rsqrt@var{m}2}
6023 pattern.)
6024
6025 This pattern is not allowed to @code{FAIL}.
6026
6027 @cindex @code{fmod@var{m}3} instruction pattern
6028 @item @samp{fmod@var{m}3}
6029 Store the remainder of dividing operand 1 by operand 2 into
6030 operand 0, rounded towards zero to an integer. All operands have
6031 mode @var{m}, which is a scalar or vector floating-point mode.
6032
6033 This pattern is not allowed to @code{FAIL}.
6034
6035 @cindex @code{remainder@var{m}3} instruction pattern
6036 @item @samp{remainder@var{m}3}
6037 Store the remainder of dividing operand 1 by operand 2 into
6038 operand 0, rounded to the nearest integer. All operands have
6039 mode @var{m}, which is a scalar or vector floating-point mode.
6040
6041 This pattern is not allowed to @code{FAIL}.
6042
6043 @cindex @code{scalb@var{m}3} instruction pattern
6044 @item @samp{scalb@var{m}3}
6045 Raise @code{FLT_RADIX} to the power of operand 2, multiply it by
6046 operand 1, and store the result in operand 0. All operands have
6047 mode @var{m}, which is a scalar or vector floating-point mode.
6048
6049 This pattern is not allowed to @code{FAIL}.
6050
6051 @cindex @code{ldexp@var{m}3} instruction pattern
6052 @item @samp{ldexp@var{m}3}
6053 Raise 2 to the power of operand 2, multiply it by operand 1, and store
6054 the result in operand 0. Operands 0 and 1 have mode @var{m}, which is
6055 a scalar or vector floating-point mode. Operand 2's mode has
6056 the same number of elements as @var{m} and each element is wide
6057 enough to store an @code{int}. The integers are signed.
6058
6059 This pattern is not allowed to @code{FAIL}.
6060
6061 @cindex @code{cos@var{m}2} instruction pattern
6062 @item @samp{cos@var{m}2}
6063 Store the cosine of operand 1 into operand 0. Both operands have
6064 mode @var{m}, which is a scalar or vector floating-point mode.
6065
6066 This pattern is not allowed to @code{FAIL}.
6067
6068 @cindex @code{sin@var{m}2} instruction pattern
6069 @item @samp{sin@var{m}2}
6070 Store the sine of operand 1 into operand 0. Both operands have
6071 mode @var{m}, which is a scalar or vector floating-point mode.
6072
6073 This pattern is not allowed to @code{FAIL}.
6074
6075 @cindex @code{sincos@var{m}3} instruction pattern
6076 @item @samp{sincos@var{m}3}
6077 Store the cosine of operand 2 into operand 0 and the sine of
6078 operand 2 into operand 1. All operands have mode @var{m},
6079 which is a scalar or vector floating-point mode.
6080
6081 Targets that can calculate the sine and cosine simultaneously can
6082 implement this pattern as opposed to implementing individual
6083 @code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin}
6084 and @code{cos} built-in functions will then be expanded to the
6085 @code{sincos@var{m}3} pattern, with one of the output values
6086 left unused.
6087
6088 @cindex @code{tan@var{m}2} instruction pattern
6089 @item @samp{tan@var{m}2}
6090 Store the tangent of operand 1 into operand 0. Both operands have
6091 mode @var{m}, which is a scalar or vector floating-point mode.
6092
6093 This pattern is not allowed to @code{FAIL}.
6094
6095 @cindex @code{asin@var{m}2} instruction pattern
6096 @item @samp{asin@var{m}2}
6097 Store the arc sine of operand 1 into operand 0. Both operands have
6098 mode @var{m}, which is a scalar or vector floating-point mode.
6099
6100 This pattern is not allowed to @code{FAIL}.
6101
6102 @cindex @code{acos@var{m}2} instruction pattern
6103 @item @samp{acos@var{m}2}
6104 Store the arc cosine of operand 1 into operand 0. Both operands have
6105 mode @var{m}, which is a scalar or vector floating-point mode.
6106
6107 This pattern is not allowed to @code{FAIL}.
6108
6109 @cindex @code{atan@var{m}2} instruction pattern
6110 @item @samp{atan@var{m}2}
6111 Store the arc tangent of operand 1 into operand 0. Both operands have
6112 mode @var{m}, which is a scalar or vector floating-point mode.
6113
6114 This pattern is not allowed to @code{FAIL}.
6115
6116 @cindex @code{fegetround@var{m}} instruction pattern
6117 @item @samp{fegetround@var{m}}
6118 Store the current machine floating-point rounding mode into operand 0.
6119 Operand 0 has mode @var{m}, which is scalar. This pattern is used to
6120 implement the @code{fegetround} function from the ISO C99 standard.
6121
6122 @cindex @code{feclearexcept@var{m}} instruction pattern
6123 @cindex @code{feraiseexcept@var{m}} instruction pattern
6124 @item @samp{feclearexcept@var{m}}
6125 @item @samp{feraiseexcept@var{m}}
6126 Clears or raises the supported machine floating-point exceptions
6127 represented by the bits in operand 1. Error status is stored as
6128 nonzero value in operand 0. Both operands have mode @var{m}, which is
6129 a scalar. These patterns are used to implement the
6130 @code{feclearexcept} and @code{feraiseexcept} functions from the ISO
6131 C99 standard.
6132
6133 @cindex @code{exp@var{m}2} instruction pattern
6134 @item @samp{exp@var{m}2}
6135 Raise e (the base of natural logarithms) to the power of operand 1
6136 and store the result in operand 0. Both operands have mode @var{m},
6137 which is a scalar or vector floating-point mode.
6138
6139 This pattern is not allowed to @code{FAIL}.
6140
6141 @cindex @code{expm1@var{m}2} instruction pattern
6142 @item @samp{expm1@var{m}2}
6143 Raise e (the base of natural logarithms) to the power of operand 1,
6144 subtract 1, and store the result in operand 0. Both operands have
6145 mode @var{m}, which is a scalar or vector floating-point mode.
6146
6147 For inputs close to zero, the pattern is expected to be more
6148 accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3}
6149 would be.
6150
6151 This pattern is not allowed to @code{FAIL}.
6152
6153 @cindex @code{exp10@var{m}2} instruction pattern
6154 @item @samp{exp10@var{m}2}
6155 Raise 10 to the power of operand 1 and store the result in operand 0.
6156 Both operands have mode @var{m}, which is a scalar or vector
6157 floating-point mode.
6158
6159 This pattern is not allowed to @code{FAIL}.
6160
6161 @cindex @code{exp2@var{m}2} instruction pattern
6162 @item @samp{exp2@var{m}2}
6163 Raise 2 to the power of operand 1 and store the result in operand 0.
6164 Both operands have mode @var{m}, which is a scalar or vector
6165 floating-point mode.
6166
6167 This pattern is not allowed to @code{FAIL}.
6168
6169 @cindex @code{log@var{m}2} instruction pattern
6170 @item @samp{log@var{m}2}
6171 Store the natural logarithm of operand 1 into operand 0. Both operands
6172 have mode @var{m}, which is a scalar or vector floating-point mode.
6173
6174 This pattern is not allowed to @code{FAIL}.
6175
6176 @cindex @code{log1p@var{m}2} instruction pattern
6177 @item @samp{log1p@var{m}2}
6178 Add 1 to operand 1, compute the natural logarithm, and store
6179 the result in operand 0. Both operands have mode @var{m}, which is
6180 a scalar or vector floating-point mode.
6181
6182 For inputs close to zero, the pattern is expected to be more
6183 accurate than a separate @code{add@var{m}3} and @code{log@var{m}2}
6184 would be.
6185
6186 This pattern is not allowed to @code{FAIL}.
6187
6188 @cindex @code{log10@var{m}2} instruction pattern
6189 @item @samp{log10@var{m}2}
6190 Store the base-10 logarithm of operand 1 into operand 0. Both operands
6191 have mode @var{m}, which is a scalar or vector floating-point mode.
6192
6193 This pattern is not allowed to @code{FAIL}.
6194
6195 @cindex @code{log2@var{m}2} instruction pattern
6196 @item @samp{log2@var{m}2}
6197 Store the base-2 logarithm of operand 1 into operand 0. Both operands
6198 have mode @var{m}, which is a scalar or vector floating-point mode.
6199
6200 This pattern is not allowed to @code{FAIL}.
6201
6202 @cindex @code{logb@var{m}2} instruction pattern
6203 @item @samp{logb@var{m}2}
6204 Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0.
6205 Both operands have mode @var{m}, which is a scalar or vector
6206 floating-point mode.
6207
6208 This pattern is not allowed to @code{FAIL}.
6209
6210 @cindex @code{significand@var{m}2} instruction pattern
6211 @item @samp{significand@var{m}2}
6212 Store the significand of floating-point operand 1 in operand 0.
6213 Both operands have mode @var{m}, which is a scalar or vector
6214 floating-point mode.
6215
6216 This pattern is not allowed to @code{FAIL}.
6217
6218 @cindex @code{pow@var{m}3} instruction pattern
6219 @item @samp{pow@var{m}3}
6220 Store the value of operand 1 raised to the exponent operand 2
6221 into operand 0. All operands have mode @var{m}, which is a scalar
6222 or vector floating-point mode.
6223
6224 This pattern is not allowed to @code{FAIL}.
6225
6226 @cindex @code{atan2@var{m}3} instruction pattern
6227 @item @samp{atan2@var{m}3}
6228 Store the arc tangent (inverse tangent) of operand 1 divided by
6229 operand 2 into operand 0, using the signs of both arguments to
6230 determine the quadrant of the result. All operands have mode
6231 @var{m}, which is a scalar or vector floating-point mode.
6232
6233 This pattern is not allowed to @code{FAIL}.
6234
6235 @cindex @code{floor@var{m}2} instruction pattern
6236 @item @samp{floor@var{m}2}
6237 Store the largest integral value not greater than operand 1 in operand 0.
6238 Both operands have mode @var{m}, which is a scalar or vector
6239 floating-point mode. If @option{-ffp-int-builtin-inexact} is in
6240 effect, the ``inexact'' exception may be raised for noninteger
6241 operands; otherwise, it may not.
6242
6243 This pattern is not allowed to @code{FAIL}.
6244
6245 @cindex @code{btrunc@var{m}2} instruction pattern
6246 @item @samp{btrunc@var{m}2}
6247 Round operand 1 to an integer, towards zero, and store the result in
6248 operand 0. Both operands have mode @var{m}, which is a scalar or
6249 vector floating-point mode. If @option{-ffp-int-builtin-inexact} is
6250 in effect, the ``inexact'' exception may be raised for noninteger
6251 operands; otherwise, it may not.
6252
6253 This pattern is not allowed to @code{FAIL}.
6254
6255 @cindex @code{round@var{m}2} instruction pattern
6256 @item @samp{round@var{m}2}
6257 Round operand 1 to the nearest integer, rounding away from zero in the
6258 event of a tie, and store the result in operand 0. Both operands have
6259 mode @var{m}, which is a scalar or vector floating-point mode. If
6260 @option{-ffp-int-builtin-inexact} is in effect, the ``inexact''
6261 exception may be raised for noninteger operands; otherwise, it may
6262 not.
6263
6264 This pattern is not allowed to @code{FAIL}.
6265
6266 @cindex @code{ceil@var{m}2} instruction pattern
6267 @item @samp{ceil@var{m}2}
6268 Store the smallest integral value not less than operand 1 in operand 0.
6269 Both operands have mode @var{m}, which is a scalar or vector
6270 floating-point mode. If @option{-ffp-int-builtin-inexact} is in
6271 effect, the ``inexact'' exception may be raised for noninteger
6272 operands; otherwise, it may not.
6273
6274 This pattern is not allowed to @code{FAIL}.
6275
6276 @cindex @code{nearbyint@var{m}2} instruction pattern
6277 @item @samp{nearbyint@var{m}2}
6278 Round operand 1 to an integer, using the current rounding mode, and
6279 store the result in operand 0. Do not raise an inexact condition when
6280 the result is different from the argument. Both operands have mode
6281 @var{m}, which is a scalar or vector floating-point mode.
6282
6283 This pattern is not allowed to @code{FAIL}.
6284
6285 @cindex @code{rint@var{m}2} instruction pattern
6286 @item @samp{rint@var{m}2}
6287 Round operand 1 to an integer, using the current rounding mode, and
6288 store the result in operand 0. Raise an inexact condition when
6289 the result is different from the argument. Both operands have mode
6290 @var{m}, which is a scalar or vector floating-point mode.
6291
6292 This pattern is not allowed to @code{FAIL}.
6293
6294 @cindex @code{lrint@var{m}@var{n}2}
6295 @item @samp{lrint@var{m}@var{n}2}
6296 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6297 point mode @var{n} as a signed number according to the current
6298 rounding mode and store in operand 0 (which has mode @var{n}).
6299
6300 @cindex @code{lround@var{m}@var{n}2}
6301 @item @samp{lround@var{m}@var{n}2}
6302 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6303 point mode @var{n} as a signed number rounding to nearest and away
6304 from zero and store in operand 0 (which has mode @var{n}).
6305
6306 @cindex @code{lfloor@var{m}@var{n}2}
6307 @item @samp{lfloor@var{m}@var{n}2}
6308 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6309 point mode @var{n} as a signed number rounding down and store in
6310 operand 0 (which has mode @var{n}).
6311
6312 @cindex @code{lceil@var{m}@var{n}2}
6313 @item @samp{lceil@var{m}@var{n}2}
6314 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6315 point mode @var{n} as a signed number rounding up and store in
6316 operand 0 (which has mode @var{n}).
6317
6318 @cindex @code{copysign@var{m}3} instruction pattern
6319 @item @samp{copysign@var{m}3}
6320 Store a value with the magnitude of operand 1 and the sign of operand
6321 2 into operand 0. All operands have mode @var{m}, which is a scalar or
6322 vector floating-point mode.
6323
6324 This pattern is not allowed to @code{FAIL}.
6325
6326 @cindex @code{xorsign@var{m}3} instruction pattern
6327 @item @samp{xorsign@var{m}3}
6328 Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with
6329 the magnitude of operand 1 and the sign of operand 2 into operand 0.
6330 All operands have mode @var{m}, which is a scalar or vector
6331 floating-point mode.
6332
6333 This pattern is not allowed to @code{FAIL}.
6334
6335 @cindex @code{cadd90@var{m}3} instruction pattern
6336 @item @samp{cadd90@var{m}3}
6337 Perform vector add and subtract on even/odd number pairs. The operation being
6338 matched is semantically described as
6339
6340 @smallexample
6341 for (int i = 0; i < N; i += 2)
6342 @{
6343 c[i] = a[i] - b[i+1];
6344 c[i+1] = a[i+1] + b[i];
6345 @}
6346 @end smallexample
6347
6348 This operation is semantically equivalent to performing a vector addition of
6349 complex numbers in operand 1 with operand 2 rotated by 90 degrees around
6350 the argand plane and storing the result in operand 0.
6351
6352 In GCC lane ordering the real part of the number must be in the even lanes with
6353 the imaginary part in the odd lanes.
6354
6355 The operation is only supported for vector modes @var{m}.
6356
6357 This pattern is not allowed to @code{FAIL}.
6358
6359 @cindex @code{cadd270@var{m}3} instruction pattern
6360 @item @samp{cadd270@var{m}3}
6361 Perform vector add and subtract on even/odd number pairs. The operation being
6362 matched is semantically described as
6363
6364 @smallexample
6365 for (int i = 0; i < N; i += 2)
6366 @{
6367 c[i] = a[i] + b[i+1];
6368 c[i+1] = a[i+1] - b[i];
6369 @}
6370 @end smallexample
6371
6372 This operation is semantically equivalent to performing a vector addition of
6373 complex numbers in operand 1 with operand 2 rotated by 270 degrees around
6374 the argand plane and storing the result in operand 0.
6375
6376 In GCC lane ordering the real part of the number must be in the even lanes with
6377 the imaginary part in the odd lanes.
6378
6379 The operation is only supported for vector modes @var{m}.
6380
6381 This pattern is not allowed to @code{FAIL}.
6382
6383 @cindex @code{cmla@var{m}4} instruction pattern
6384 @item @samp{cmla@var{m}4}
6385 Perform a vector multiply and accumulate that is semantically the same as
6386 a multiply and accumulate of complex numbers.
6387
6388 @smallexample
6389 complex TYPE op0[N];
6390 complex TYPE op1[N];
6391 complex TYPE op2[N];
6392 complex TYPE op3[N];
6393 for (int i = 0; i < N; i += 1)
6394 @{
6395 op0[i] = op1[i] * op2[i] + op3[i];
6396 @}
6397 @end smallexample
6398
6399 In GCC lane ordering the real part of the number must be in the even lanes with
6400 the imaginary part in the odd lanes.
6401
6402 The operation is only supported for vector modes @var{m}.
6403
6404 This pattern is not allowed to @code{FAIL}.
6405
6406 @cindex @code{cmla_conj@var{m}4} instruction pattern
6407 @item @samp{cmla_conj@var{m}4}
6408 Perform a vector multiply by conjugate and accumulate that is semantically
6409 the same as a multiply and accumulate of complex numbers where the second
6410 multiply arguments is conjugated.
6411
6412 @smallexample
6413 complex TYPE op0[N];
6414 complex TYPE op1[N];
6415 complex TYPE op2[N];
6416 complex TYPE op3[N];
6417 for (int i = 0; i < N; i += 1)
6418 @{
6419 op0[i] = op1[i] * conj (op2[i]) + op3[i];
6420 @}
6421 @end smallexample
6422
6423 In GCC lane ordering the real part of the number must be in the even lanes with
6424 the imaginary part in the odd lanes.
6425
6426 The operation is only supported for vector modes @var{m}.
6427
6428 This pattern is not allowed to @code{FAIL}.
6429
6430 @cindex @code{cmls@var{m}4} instruction pattern
6431 @item @samp{cmls@var{m}4}
6432 Perform a vector multiply and subtract that is semantically the same as
6433 a multiply and subtract of complex numbers.
6434
6435 @smallexample
6436 complex TYPE op0[N];
6437 complex TYPE op1[N];
6438 complex TYPE op2[N];
6439 complex TYPE op3[N];
6440 for (int i = 0; i < N; i += 1)
6441 @{
6442 op0[i] = op1[i] * op2[i] - op3[i];
6443 @}
6444 @end smallexample
6445
6446 In GCC lane ordering the real part of the number must be in the even lanes with
6447 the imaginary part in the odd lanes.
6448
6449 The operation is only supported for vector modes @var{m}.
6450
6451 This pattern is not allowed to @code{FAIL}.
6452
6453 @cindex @code{cmls_conj@var{m}4} instruction pattern
6454 @item @samp{cmls_conj@var{m}4}
6455 Perform a vector multiply by conjugate and subtract that is semantically
6456 the same as a multiply and subtract of complex numbers where the second
6457 multiply arguments is conjugated.
6458
6459 @smallexample
6460 complex TYPE op0[N];
6461 complex TYPE op1[N];
6462 complex TYPE op2[N];
6463 complex TYPE op3[N];
6464 for (int i = 0; i < N; i += 1)
6465 @{
6466 op0[i] = op1[i] * conj (op2[i]) - op3[i];
6467 @}
6468 @end smallexample
6469
6470 In GCC lane ordering the real part of the number must be in the even lanes with
6471 the imaginary part in the odd lanes.
6472
6473 The operation is only supported for vector modes @var{m}.
6474
6475 This pattern is not allowed to @code{FAIL}.
6476
6477 @cindex @code{cmul@var{m}4} instruction pattern
6478 @item @samp{cmul@var{m}4}
6479 Perform a vector multiply that is semantically the same as multiply of
6480 complex numbers.
6481
6482 @smallexample
6483 complex TYPE op0[N];
6484 complex TYPE op1[N];
6485 complex TYPE op2[N];
6486 for (int i = 0; i < N; i += 1)
6487 @{
6488 op0[i] = op1[i] * op2[i];
6489 @}
6490 @end smallexample
6491
6492 In GCC lane ordering the real part of the number must be in the even lanes with
6493 the imaginary part in the odd lanes.
6494
6495 The operation is only supported for vector modes @var{m}.
6496
6497 This pattern is not allowed to @code{FAIL}.
6498
6499 @cindex @code{cmul_conj@var{m}4} instruction pattern
6500 @item @samp{cmul_conj@var{m}4}
6501 Perform a vector multiply by conjugate that is semantically the same as a
6502 multiply of complex numbers where the second multiply arguments is conjugated.
6503
6504 @smallexample
6505 complex TYPE op0[N];
6506 complex TYPE op1[N];
6507 complex TYPE op2[N];
6508 for (int i = 0; i < N; i += 1)
6509 @{
6510 op0[i] = op1[i] * conj (op2[i]);
6511 @}
6512 @end smallexample
6513
6514 In GCC lane ordering the real part of the number must be in the even lanes with
6515 the imaginary part in the odd lanes.
6516
6517 The operation is only supported for vector modes @var{m}.
6518
6519 This pattern is not allowed to @code{FAIL}.
6520
6521 @cindex @code{ffs@var{m}2} instruction pattern
6522 @item @samp{ffs@var{m}2}
6523 Store into operand 0 one plus the index of the least significant 1-bit
6524 of operand 1. If operand 1 is zero, store zero.
6525
6526 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6527 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6528 integer mode is suitable for the target. The compiler will insert
6529 conversion instructions as necessary (typically to convert the result
6530 to the same width as @code{int}). When @var{m} is a vector, both
6531 operands must have mode @var{m}.
6532
6533 This pattern is not allowed to @code{FAIL}.
6534
6535 @cindex @code{clrsb@var{m}2} instruction pattern
6536 @item @samp{clrsb@var{m}2}
6537 Count leading redundant sign bits.
6538 Store into operand 0 the number of redundant sign bits in operand 1, starting
6539 at the most significant bit position.
6540 A redundant sign bit is defined as any sign bit after the first. As such,
6541 this count will be one less than the count of leading sign bits.
6542
6543 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6544 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6545 integer mode is suitable for the target. The compiler will insert
6546 conversion instructions as necessary (typically to convert the result
6547 to the same width as @code{int}). When @var{m} is a vector, both
6548 operands must have mode @var{m}.
6549
6550 This pattern is not allowed to @code{FAIL}.
6551
6552 @cindex @code{clz@var{m}2} instruction pattern
6553 @item @samp{clz@var{m}2}
6554 Store into operand 0 the number of leading 0-bits in operand 1, starting
6555 at the most significant bit position. If operand 1 is 0, the
6556 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6557 the result is undefined or has a useful value.
6558
6559 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6560 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6561 integer mode is suitable for the target. The compiler will insert
6562 conversion instructions as necessary (typically to convert the result
6563 to the same width as @code{int}). When @var{m} is a vector, both
6564 operands must have mode @var{m}.
6565
6566 This pattern is not allowed to @code{FAIL}.
6567
6568 @cindex @code{ctz@var{m}2} instruction pattern
6569 @item @samp{ctz@var{m}2}
6570 Store into operand 0 the number of trailing 0-bits in operand 1, starting
6571 at the least significant bit position. If operand 1 is 0, the
6572 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6573 the result is undefined or has a useful value.
6574
6575 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6576 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6577 integer mode is suitable for the target. The compiler will insert
6578 conversion instructions as necessary (typically to convert the result
6579 to the same width as @code{int}). When @var{m} is a vector, both
6580 operands must have mode @var{m}.
6581
6582 This pattern is not allowed to @code{FAIL}.
6583
6584 @cindex @code{popcount@var{m}2} instruction pattern
6585 @item @samp{popcount@var{m}2}
6586 Store into operand 0 the number of 1-bits in operand 1.
6587
6588 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6589 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6590 integer mode is suitable for the target. The compiler will insert
6591 conversion instructions as necessary (typically to convert the result
6592 to the same width as @code{int}). When @var{m} is a vector, both
6593 operands must have mode @var{m}.
6594
6595 This pattern is not allowed to @code{FAIL}.
6596
6597 @cindex @code{parity@var{m}2} instruction pattern
6598 @item @samp{parity@var{m}2}
6599 Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
6600 in operand 1 modulo 2.
6601
6602 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6603 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6604 integer mode is suitable for the target. The compiler will insert
6605 conversion instructions as necessary (typically to convert the result
6606 to the same width as @code{int}). When @var{m} is a vector, both
6607 operands must have mode @var{m}.
6608
6609 This pattern is not allowed to @code{FAIL}.
6610
6611 @cindex @code{one_cmpl@var{m}2} instruction pattern
6612 @item @samp{one_cmpl@var{m}2}
6613 Store the bitwise-complement of operand 1 into operand 0.
6614
6615 @cindex @code{cpymem@var{m}} instruction pattern
6616 @item @samp{cpymem@var{m}}
6617 Block copy instruction. The destination and source blocks of memory
6618 are the first two operands, and both are @code{mem:BLK}s with an
6619 address in mode @code{Pmode}.
6620
6621 The number of bytes to copy is the third operand, in mode @var{m}.
6622 Usually, you specify @code{Pmode} for @var{m}. However, if you can
6623 generate better code knowing the range of valid lengths is smaller than
6624 those representable in a full Pmode pointer, you should provide
6625 a pattern with a
6626 mode corresponding to the range of values you can handle efficiently
6627 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6628 that appear negative) and also a pattern with @code{Pmode}.
6629
6630 The fourth operand is the known shared alignment of the source and
6631 destination, in the form of a @code{const_int} rtx. Thus, if the
6632 compiler knows that both source and destination are word-aligned,
6633 it may provide the value 4 for this operand.
6634
6635 Optional operands 5 and 6 specify expected alignment and size of block
6636 respectively. The expected alignment differs from alignment in operand 4
6637 in a way that the blocks are not required to be aligned according to it in
6638 all cases. This expected alignment is also in bytes, just like operand 4.
6639 Expected size, when unknown, is set to @code{(const_int -1)}.
6640
6641 Descriptions of multiple @code{cpymem@var{m}} patterns can only be
6642 beneficial if the patterns for smaller modes have fewer restrictions
6643 on their first, second and fourth operands. Note that the mode @var{m}
6644 in @code{cpymem@var{m}} does not impose any restriction on the mode of
6645 individually copied data units in the block.
6646
6647 The @code{cpymem@var{m}} patterns need not give special consideration
6648 to the possibility that the source and destination strings might
6649 overlap. These patterns are used to do inline expansion of
6650 @code{__builtin_memcpy}.
6651
6652 @cindex @code{movmem@var{m}} instruction pattern
6653 @item @samp{movmem@var{m}}
6654 Block move instruction. The destination and source blocks of memory
6655 are the first two operands, and both are @code{mem:BLK}s with an
6656 address in mode @code{Pmode}.
6657
6658 The number of bytes to copy is the third operand, in mode @var{m}.
6659 Usually, you specify @code{Pmode} for @var{m}. However, if you can
6660 generate better code knowing the range of valid lengths is smaller than
6661 those representable in a full Pmode pointer, you should provide
6662 a pattern with a
6663 mode corresponding to the range of values you can handle efficiently
6664 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6665 that appear negative) and also a pattern with @code{Pmode}.
6666
6667 The fourth operand is the known shared alignment of the source and
6668 destination, in the form of a @code{const_int} rtx. Thus, if the
6669 compiler knows that both source and destination are word-aligned,
6670 it may provide the value 4 for this operand.
6671
6672 Optional operands 5 and 6 specify expected alignment and size of block
6673 respectively. The expected alignment differs from alignment in operand 4
6674 in a way that the blocks are not required to be aligned according to it in
6675 all cases. This expected alignment is also in bytes, just like operand 4.
6676 Expected size, when unknown, is set to @code{(const_int -1)}.
6677
6678 Descriptions of multiple @code{movmem@var{m}} patterns can only be
6679 beneficial if the patterns for smaller modes have fewer restrictions
6680 on their first, second and fourth operands. Note that the mode @var{m}
6681 in @code{movmem@var{m}} does not impose any restriction on the mode of
6682 individually copied data units in the block.
6683
6684 The @code{movmem@var{m}} patterns must correctly handle the case where
6685 the source and destination strings overlap. These patterns are used to
6686 do inline expansion of @code{__builtin_memmove}.
6687
6688 @cindex @code{movstr} instruction pattern
6689 @item @samp{movstr}
6690 String copy instruction, with @code{stpcpy} semantics. Operand 0 is
6691 an output operand in mode @code{Pmode}. The addresses of the
6692 destination and source strings are operands 1 and 2, and both are
6693 @code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of
6694 the expansion of this pattern should store in operand 0 the address in
6695 which the @code{NUL} terminator was stored in the destination string.
6696
6697 This pattern has also several optional operands that are same as in
6698 @code{setmem}.
6699
6700 @cindex @code{setmem@var{m}} instruction pattern
6701 @item @samp{setmem@var{m}}
6702 Block set instruction. The destination string is the first operand,
6703 given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The
6704 number of bytes to set is the second operand, in mode @var{m}. The value to
6705 initialize the memory with is the third operand. Targets that only support the
6706 clearing of memory should reject any value that is not the constant 0. See
6707 @samp{cpymem@var{m}} for a discussion of the choice of mode.
6708
6709 The fourth operand is the known alignment of the destination, in the form
6710 of a @code{const_int} rtx. Thus, if the compiler knows that the
6711 destination is word-aligned, it may provide the value 4 for this
6712 operand.
6713
6714 Optional operands 5 and 6 specify expected alignment and size of block
6715 respectively. The expected alignment differs from alignment in operand 4
6716 in a way that the blocks are not required to be aligned according to it in
6717 all cases. This expected alignment is also in bytes, just like operand 4.
6718 Expected size, when unknown, is set to @code{(const_int -1)}.
6719 Operand 7 is the minimal size of the block and operand 8 is the
6720 maximal size of the block (NULL if it cannot be represented as CONST_INT).
6721 Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for
6722 correctness, but it can be used for choosing proper code sequence for a
6723 given size).
6724
6725 The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}.
6726
6727 @cindex @code{cmpstrn@var{m}} instruction pattern
6728 @item @samp{cmpstrn@var{m}}
6729 String compare instruction, with five operands. Operand 0 is the output;
6730 it has mode @var{m}. The remaining four operands are like the operands
6731 of @samp{cpymem@var{m}}. The two memory blocks specified are compared
6732 byte by byte in lexicographic order starting at the beginning of each
6733 string. The instruction is not allowed to prefetch more than one byte
6734 at a time since either string may end in the first byte and reading past
6735 that may access an invalid page or segment and cause a fault. The
6736 comparison terminates early if the fetched bytes are different or if
6737 they are equal to zero. The effect of the instruction is to store a
6738 value in operand 0 whose sign indicates the result of the comparison.
6739
6740 @cindex @code{cmpstr@var{m}} instruction pattern
6741 @item @samp{cmpstr@var{m}}
6742 String compare instruction, without known maximum length. Operand 0 is the
6743 output; it has mode @var{m}. The second and third operand are the blocks of
6744 memory to be compared; both are @code{mem:BLK} with an address in mode
6745 @code{Pmode}.
6746
6747 The fourth operand is the known shared alignment of the source and
6748 destination, in the form of a @code{const_int} rtx. Thus, if the
6749 compiler knows that both source and destination are word-aligned,
6750 it may provide the value 4 for this operand.
6751
6752 The two memory blocks specified are compared byte by byte in lexicographic
6753 order starting at the beginning of each string. The instruction is not allowed
6754 to prefetch more than one byte at a time since either string may end in the
6755 first byte and reading past that may access an invalid page or segment and
6756 cause a fault. The comparison will terminate when the fetched bytes
6757 are different or if they are equal to zero. The effect of the
6758 instruction is to store a value in operand 0 whose sign indicates the
6759 result of the comparison.
6760
6761 @cindex @code{cmpmem@var{m}} instruction pattern
6762 @item @samp{cmpmem@var{m}}
6763 Block compare instruction, with five operands like the operands
6764 of @samp{cmpstr@var{m}}. The two memory blocks specified are compared
6765 byte by byte in lexicographic order starting at the beginning of each
6766 block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch
6767 any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}}
6768 the comparison will not stop if both bytes are zero. The effect of
6769 the instruction is to store a value in operand 0 whose sign indicates
6770 the result of the comparison.
6771
6772 @cindex @code{strlen@var{m}} instruction pattern
6773 @item @samp{strlen@var{m}}
6774 Compute the length of a string, with three operands.
6775 Operand 0 is the result (of mode @var{m}), operand 1 is
6776 a @code{mem} referring to the first character of the string,
6777 operand 2 is the character to search for (normally zero),
6778 and operand 3 is a constant describing the known alignment
6779 of the beginning of the string.
6780
6781 @cindex @code{rawmemchr@var{m}} instruction pattern
6782 @item @samp{rawmemchr@var{m}}
6783 Scan memory referred to by operand 1 for the first occurrence of operand 2.
6784 Operand 1 is a @code{mem} and operand 2 a @code{const_int} of mode @var{m}.
6785 Operand 0 is the result, i.e., a pointer to the first occurrence of operand 2
6786 in the memory block given by operand 1.
6787
6788 @cindex @code{float@var{m}@var{n}2} instruction pattern
6789 @item @samp{float@var{m}@var{n}2}
6790 Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
6791 floating point mode @var{n} and store in operand 0 (which has mode
6792 @var{n}).
6793
6794 @cindex @code{floatuns@var{m}@var{n}2} instruction pattern
6795 @item @samp{floatuns@var{m}@var{n}2}
6796 Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
6797 to floating point mode @var{n} and store in operand 0 (which has mode
6798 @var{n}).
6799
6800 @cindex @code{fix@var{m}@var{n}2} instruction pattern
6801 @item @samp{fix@var{m}@var{n}2}
6802 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6803 point mode @var{n} as a signed number and store in operand 0 (which
6804 has mode @var{n}). This instruction's result is defined only when
6805 the value of operand 1 is an integer.
6806
6807 If the machine description defines this pattern, it also needs to
6808 define the @code{ftrunc} pattern.
6809
6810 @cindex @code{fixuns@var{m}@var{n}2} instruction pattern
6811 @item @samp{fixuns@var{m}@var{n}2}
6812 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6813 point mode @var{n} as an unsigned number and store in operand 0 (which
6814 has mode @var{n}). This instruction's result is defined only when the
6815 value of operand 1 is an integer.
6816
6817 @cindex @code{ftrunc@var{m}2} instruction pattern
6818 @item @samp{ftrunc@var{m}2}
6819 Convert operand 1 (valid for floating point mode @var{m}) to an
6820 integer value, still represented in floating point mode @var{m}, and
6821 store it in operand 0 (valid for floating point mode @var{m}).
6822
6823 @cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
6824 @item @samp{fix_trunc@var{m}@var{n}2}
6825 Like @samp{fix@var{m}@var{n}2} but works for any floating point value
6826 of mode @var{m} by converting the value to an integer.
6827
6828 @cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
6829 @item @samp{fixuns_trunc@var{m}@var{n}2}
6830 Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
6831 value of mode @var{m} by converting the value to an integer.
6832
6833 @cindex @code{trunc@var{m}@var{n}2} instruction pattern
6834 @item @samp{trunc@var{m}@var{n}2}
6835 Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
6836 store in operand 0 (which has mode @var{n}). Both modes must be fixed
6837 point or both floating point.
6838
6839 @cindex @code{extend@var{m}@var{n}2} instruction pattern
6840 @item @samp{extend@var{m}@var{n}2}
6841 Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6842 store in operand 0 (which has mode @var{n}). Both modes must be fixed
6843 point or both floating point.
6844
6845 @cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
6846 @item @samp{zero_extend@var{m}@var{n}2}
6847 Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6848 store in operand 0 (which has mode @var{n}). Both modes must be fixed
6849 point.
6850
6851 @cindex @code{fract@var{m}@var{n}2} instruction pattern
6852 @item @samp{fract@var{m}@var{n}2}
6853 Convert operand 1 of mode @var{m} to mode @var{n} and store in
6854 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
6855 could be fixed-point to fixed-point, signed integer to fixed-point,
6856 fixed-point to signed integer, floating-point to fixed-point,
6857 or fixed-point to floating-point.
6858 When overflows or underflows happen, the results are undefined.
6859
6860 @cindex @code{satfract@var{m}@var{n}2} instruction pattern
6861 @item @samp{satfract@var{m}@var{n}2}
6862 Convert operand 1 of mode @var{m} to mode @var{n} and store in
6863 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
6864 could be fixed-point to fixed-point, signed integer to fixed-point,
6865 or floating-point to fixed-point.
6866 When overflows or underflows happen, the instruction saturates the
6867 results to the maximum or the minimum.
6868
6869 @cindex @code{fractuns@var{m}@var{n}2} instruction pattern
6870 @item @samp{fractuns@var{m}@var{n}2}
6871 Convert operand 1 of mode @var{m} to mode @var{n} and store in
6872 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
6873 could be unsigned integer to fixed-point, or
6874 fixed-point to unsigned integer.
6875 When overflows or underflows happen, the results are undefined.
6876
6877 @cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
6878 @item @samp{satfractuns@var{m}@var{n}2}
6879 Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
6880 @var{n} and store in operand 0 (which has mode @var{n}).
6881 When overflows or underflows happen, the instruction saturates the
6882 results to the maximum or the minimum.
6883
6884 @cindex @code{extv@var{m}} instruction pattern
6885 @item @samp{extv@var{m}}
6886 Extract a bit-field from register operand 1, sign-extend it, and store
6887 it in operand 0. Operand 2 specifies the width of the field in bits
6888 and operand 3 the starting bit, which counts from the most significant
6889 bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit
6890 otherwise.
6891
6892 Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a
6893 target-specific mode.
6894
6895 @cindex @code{extvmisalign@var{m}} instruction pattern
6896 @item @samp{extvmisalign@var{m}}
6897 Extract a bit-field from memory operand 1, sign extend it, and store
6898 it in operand 0. Operand 2 specifies the width in bits and operand 3
6899 the starting bit. The starting bit is always somewhere in the first byte of
6900 operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
6901 is true and from the least significant bit otherwise.
6902
6903 Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode.
6904 Operands 2 and 3 have a target-specific mode.
6905
6906 The instruction must not read beyond the last byte of the bit-field.
6907
6908 @cindex @code{extzv@var{m}} instruction pattern
6909 @item @samp{extzv@var{m}}
6910 Like @samp{extv@var{m}} except that the bit-field value is zero-extended.
6911
6912 @cindex @code{extzvmisalign@var{m}} instruction pattern
6913 @item @samp{extzvmisalign@var{m}}
6914 Like @samp{extvmisalign@var{m}} except that the bit-field value is
6915 zero-extended.
6916
6917 @cindex @code{insv@var{m}} instruction pattern
6918 @item @samp{insv@var{m}}
6919 Insert operand 3 into a bit-field of register operand 0. Operand 1
6920 specifies the width of the field in bits and operand 2 the starting bit,
6921 which counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
6922 is true and from the least significant bit otherwise.
6923
6924 Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a
6925 target-specific mode.
6926
6927 @cindex @code{insvmisalign@var{m}} instruction pattern
6928 @item @samp{insvmisalign@var{m}}
6929 Insert operand 3 into a bit-field of memory operand 0. Operand 1
6930 specifies the width of the field in bits and operand 2 the starting bit.
6931 The starting bit is always somewhere in the first byte of operand 0;
6932 it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
6933 is true and from the least significant bit otherwise.
6934
6935 Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode.
6936 Operands 1 and 2 have a target-specific mode.
6937
6938 The instruction must not read or write beyond the last byte of the bit-field.
6939
6940 @cindex @code{extv} instruction pattern
6941 @item @samp{extv}
6942 Extract a bit-field from operand 1 (a register or memory operand), where
6943 operand 2 specifies the width in bits and operand 3 the starting bit,
6944 and store it in operand 0. Operand 0 must have mode @code{word_mode}.
6945 Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
6946 @code{word_mode} is allowed only for registers. Operands 2 and 3 must
6947 be valid for @code{word_mode}.
6948
6949 The RTL generation pass generates this instruction only with constants
6950 for operands 2 and 3 and the constant is never zero for operand 2.
6951
6952 The bit-field value is sign-extended to a full word integer
6953 before it is stored in operand 0.
6954
6955 This pattern is deprecated; please use @samp{extv@var{m}} and
6956 @code{extvmisalign@var{m}} instead.
6957
6958 @cindex @code{extzv} instruction pattern
6959 @item @samp{extzv}
6960 Like @samp{extv} except that the bit-field value is zero-extended.
6961
6962 This pattern is deprecated; please use @samp{extzv@var{m}} and
6963 @code{extzvmisalign@var{m}} instead.
6964
6965 @cindex @code{insv} instruction pattern
6966 @item @samp{insv}
6967 Store operand 3 (which must be valid for @code{word_mode}) into a
6968 bit-field in operand 0, where operand 1 specifies the width in bits and
6969 operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or
6970 @code{word_mode}; often @code{word_mode} is allowed only for registers.
6971 Operands 1 and 2 must be valid for @code{word_mode}.
6972
6973 The RTL generation pass generates this instruction only with constants
6974 for operands 1 and 2 and the constant is never zero for operand 1.
6975
6976 This pattern is deprecated; please use @samp{insv@var{m}} and
6977 @code{insvmisalign@var{m}} instead.
6978
6979 @cindex @code{mov@var{mode}cc} instruction pattern
6980 @item @samp{mov@var{mode}cc}
6981 Conditionally move operand 2 or operand 3 into operand 0 according to the
6982 comparison in operand 1. If the comparison is true, operand 2 is moved
6983 into operand 0, otherwise operand 3 is moved.
6984
6985 The mode of the operands being compared need not be the same as the operands
6986 being moved. Some machines, sparc64 for example, have instructions that
6987 conditionally move an integer value based on the floating point condition
6988 codes and vice versa.
6989
6990 If the machine does not have conditional move instructions, do not
6991 define these patterns.
6992
6993 @cindex @code{add@var{mode}cc} instruction pattern
6994 @item @samp{add@var{mode}cc}
6995 Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally
6996 move operand 2 or (operands 2 + operand 3) into operand 0 according to the
6997 comparison in operand 1. If the comparison is false, operand 2 is moved into
6998 operand 0, otherwise (operand 2 + operand 3) is moved.
6999
7000 @cindex @code{cond_add@var{mode}} instruction pattern
7001 @cindex @code{cond_sub@var{mode}} instruction pattern
7002 @cindex @code{cond_mul@var{mode}} instruction pattern
7003 @cindex @code{cond_div@var{mode}} instruction pattern
7004 @cindex @code{cond_udiv@var{mode}} instruction pattern
7005 @cindex @code{cond_mod@var{mode}} instruction pattern
7006 @cindex @code{cond_umod@var{mode}} instruction pattern
7007 @cindex @code{cond_and@var{mode}} instruction pattern
7008 @cindex @code{cond_ior@var{mode}} instruction pattern
7009 @cindex @code{cond_xor@var{mode}} instruction pattern
7010 @cindex @code{cond_smin@var{mode}} instruction pattern
7011 @cindex @code{cond_smax@var{mode}} instruction pattern
7012 @cindex @code{cond_umin@var{mode}} instruction pattern
7013 @cindex @code{cond_umax@var{mode}} instruction pattern
7014 @cindex @code{cond_fmin@var{mode}} instruction pattern
7015 @cindex @code{cond_fmax@var{mode}} instruction pattern
7016 @cindex @code{cond_ashl@var{mode}} instruction pattern
7017 @cindex @code{cond_ashr@var{mode}} instruction pattern
7018 @cindex @code{cond_lshr@var{mode}} instruction pattern
7019 @item @samp{cond_add@var{mode}}
7020 @itemx @samp{cond_sub@var{mode}}
7021 @itemx @samp{cond_mul@var{mode}}
7022 @itemx @samp{cond_div@var{mode}}
7023 @itemx @samp{cond_udiv@var{mode}}
7024 @itemx @samp{cond_mod@var{mode}}
7025 @itemx @samp{cond_umod@var{mode}}
7026 @itemx @samp{cond_and@var{mode}}
7027 @itemx @samp{cond_ior@var{mode}}
7028 @itemx @samp{cond_xor@var{mode}}
7029 @itemx @samp{cond_smin@var{mode}}
7030 @itemx @samp{cond_smax@var{mode}}
7031 @itemx @samp{cond_umin@var{mode}}
7032 @itemx @samp{cond_umax@var{mode}}
7033 @itemx @samp{cond_fmin@var{mode}}
7034 @itemx @samp{cond_fmax@var{mode}}
7035 @itemx @samp{cond_ashl@var{mode}}
7036 @itemx @samp{cond_ashr@var{mode}}
7037 @itemx @samp{cond_lshr@var{mode}}
7038 When operand 1 is true, perform an operation on operands 2 and 3 and
7039 store the result in operand 0, otherwise store operand 4 in operand 0.
7040 The operation works elementwise if the operands are vectors.
7041
7042 The scalar case is equivalent to:
7043
7044 @smallexample
7045 op0 = op1 ? op2 @var{op} op3 : op4;
7046 @end smallexample
7047
7048 while the vector case is equivalent to:
7049
7050 @smallexample
7051 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7052 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i];
7053 @end smallexample
7054
7055 where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}.
7056
7057 When defined for floating-point modes, the contents of @samp{op3[i]}
7058 are not interpreted if @samp{op1[i]} is false, just like they would not
7059 be in a normal C @samp{?:} condition.
7060
7061 Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar
7062 integer if @var{m} is scalar, otherwise it has the mode returned by
7063 @code{TARGET_VECTORIZE_GET_MASK_MODE}.
7064
7065 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
7066 form of @samp{@var{op}@var{mode}3}. As an exception, the vector forms
7067 of shifts correspond to patterns like @code{vashl@var{mode}3} rather
7068 than patterns like @code{ashl@var{mode}3}.
7069
7070 @cindex @code{cond_fma@var{mode}} instruction pattern
7071 @cindex @code{cond_fms@var{mode}} instruction pattern
7072 @cindex @code{cond_fnma@var{mode}} instruction pattern
7073 @cindex @code{cond_fnms@var{mode}} instruction pattern
7074 @item @samp{cond_fma@var{mode}}
7075 @itemx @samp{cond_fms@var{mode}}
7076 @itemx @samp{cond_fnma@var{mode}}
7077 @itemx @samp{cond_fnms@var{mode}}
7078 Like @samp{cond_add@var{m}}, except that the conditional operation
7079 takes 3 operands rather than two. For example, the vector form of
7080 @samp{cond_fma@var{mode}} is equivalent to:
7081
7082 @smallexample
7083 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
7084 op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i];
7085 @end smallexample
7086
7087 @cindex @code{neg@var{mode}cc} instruction pattern
7088 @item @samp{neg@var{mode}cc}
7089 Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally
7090 move the negation of operand 2 or the unchanged operand 3 into operand 0
7091 according to the comparison in operand 1. If the comparison is true, the negation
7092 of operand 2 is moved into operand 0, otherwise operand 3 is moved.
7093
7094 @cindex @code{not@var{mode}cc} instruction pattern
7095 @item @samp{not@var{mode}cc}
7096 Similar to @samp{neg@var{mode}cc} but for conditional complement.
7097 Conditionally move the bitwise complement of operand 2 or the unchanged
7098 operand 3 into operand 0 according to the comparison in operand 1.
7099 If the comparison is true, the complement of operand 2 is moved into
7100 operand 0, otherwise operand 3 is moved.
7101
7102 @cindex @code{cstore@var{mode}4} instruction pattern
7103 @item @samp{cstore@var{mode}4}
7104 Store zero or nonzero in operand 0 according to whether a comparison
7105 is true. Operand 1 is a comparison operator. Operand 2 and operand 3
7106 are the first and second operand of the comparison, respectively.
7107 You specify the mode that operand 0 must have when you write the
7108 @code{match_operand} expression. The compiler automatically sees which
7109 mode you have used and supplies an operand of that mode.
7110
7111 The value stored for a true condition must have 1 as its low bit, or
7112 else must be negative. Otherwise the instruction is not suitable and
7113 you should omit it from the machine description. You describe to the
7114 compiler exactly which value is stored by defining the macro
7115 @code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be
7116 found that can be used for all the possible comparison operators, you
7117 should pick one and use a @code{define_expand} to map all results
7118 onto the one you chose.
7119
7120 These operations may @code{FAIL}, but should do so only in relatively
7121 uncommon cases; if they would @code{FAIL} for common cases involving
7122 integer comparisons, it is best to restrict the predicates to not
7123 allow these operands. Likewise if a given comparison operator will
7124 always fail, independent of the operands (for floating-point modes, the
7125 @code{ordered_comparison_operator} predicate is often useful in this case).
7126
7127 If this pattern is omitted, the compiler will generate a conditional
7128 branch---for example, it may copy a constant one to the target and branching
7129 around an assignment of zero to the target---or a libcall. If the predicate
7130 for operand 1 only rejects some operators, it will also try reordering the
7131 operands and/or inverting the result value (e.g.@: by an exclusive OR).
7132 These possibilities could be cheaper or equivalent to the instructions
7133 used for the @samp{cstore@var{mode}4} pattern followed by those required
7134 to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
7135 case, you can and should make operand 1's predicate reject some operators
7136 in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
7137 from the machine description.
7138
7139 @cindex @code{cbranch@var{mode}4} instruction pattern
7140 @item @samp{cbranch@var{mode}4}
7141 Conditional branch instruction combined with a compare instruction.
7142 Operand 0 is a comparison operator. Operand 1 and operand 2 are the
7143 first and second operands of the comparison, respectively. Operand 3
7144 is the @code{code_label} to jump to.
7145
7146 @cindex @code{jump} instruction pattern
7147 @item @samp{jump}
7148 A jump inside a function; an unconditional branch. Operand 0 is the
7149 @code{code_label} to jump to. This pattern name is mandatory on all
7150 machines.
7151
7152 @cindex @code{call} instruction pattern
7153 @item @samp{call}
7154 Subroutine call instruction returning no value. Operand 0 is the
7155 function to call; operand 1 is the number of bytes of arguments pushed
7156 as a @code{const_int}. Operand 2 is the result of calling the target
7157 hook @code{TARGET_FUNCTION_ARG} with the second argument @code{arg}
7158 yielding true for @code{arg.end_marker_p ()}, in a call after all
7159 parameters have been passed to that hook. By default this is the first
7160 register beyond those used for arguments in the call, or @code{NULL} if
7161 all the argument-registers are used in the call.
7162
7163 On most machines, operand 2 is not actually stored into the RTL
7164 pattern. It is supplied for the sake of some RISC machines which need
7165 to put this information into the assembler code; they can put it in
7166 the RTL instead of operand 1.
7167
7168 Operand 0 should be a @code{mem} RTX whose address is the address of the
7169 function. Note, however, that this address can be a @code{symbol_ref}
7170 expression even if it would not be a legitimate memory address on the
7171 target machine. If it is also not a valid argument for a call
7172 instruction, the pattern for this operation should be a
7173 @code{define_expand} (@pxref{Expander Definitions}) that places the
7174 address into a register and uses that register in the call instruction.
7175
7176 @cindex @code{call_value} instruction pattern
7177 @item @samp{call_value}
7178 Subroutine call instruction returning a value. Operand 0 is the hard
7179 register in which the value is returned. There are three more
7180 operands, the same as the three operands of the @samp{call}
7181 instruction (but with numbers increased by one).
7182
7183 Subroutines that return @code{BLKmode} objects use the @samp{call}
7184 insn.
7185
7186 @cindex @code{call_pop} instruction pattern
7187 @cindex @code{call_value_pop} instruction pattern
7188 @item @samp{call_pop}, @samp{call_value_pop}
7189 Similar to @samp{call} and @samp{call_value}, except used if defined and
7190 if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel}
7191 that contains both the function call and a @code{set} to indicate the
7192 adjustment made to the frame pointer.
7193
7194 For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
7195 patterns increases the number of functions for which the frame pointer
7196 can be eliminated, if desired.
7197
7198 @cindex @code{untyped_call} instruction pattern
7199 @item @samp{untyped_call}
7200 Subroutine call instruction returning a value of any type. Operand 0 is
7201 the function to call; operand 1 is a memory location where the result of
7202 calling the function is to be stored; operand 2 is a @code{parallel}
7203 expression where each element is a @code{set} expression that indicates
7204 the saving of a function return value into the result block.
7205
7206 This instruction pattern should be defined to support
7207 @code{__builtin_apply} on machines where special instructions are needed
7208 to call a subroutine with arbitrary arguments or to save the value
7209 returned. This instruction pattern is required on machines that have
7210 multiple registers that can hold a return value
7211 (i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
7212
7213 @cindex @code{return} instruction pattern
7214 @item @samp{return}
7215 Subroutine return instruction. This instruction pattern name should be
7216 defined only if a single instruction can do all the work of returning
7217 from a function.
7218
7219 Like the @samp{mov@var{m}} patterns, this pattern is also used after the
7220 RTL generation phase. In this case it is to support machines where
7221 multiple instructions are usually needed to return from a function, but
7222 some class of functions only requires one instruction to implement a
7223 return. Normally, the applicable functions are those which do not need
7224 to save any registers or allocate stack space.
7225
7226 It is valid for this pattern to expand to an instruction using
7227 @code{simple_return} if no epilogue is required.
7228
7229 @cindex @code{simple_return} instruction pattern
7230 @item @samp{simple_return}
7231 Subroutine return instruction. This instruction pattern name should be
7232 defined only if a single instruction can do all the work of returning
7233 from a function on a path where no epilogue is required. This pattern
7234 is very similar to the @code{return} instruction pattern, but it is emitted
7235 only by the shrink-wrapping optimization on paths where the function
7236 prologue has not been executed, and a function return should occur without
7237 any of the effects of the epilogue. Additional uses may be introduced on
7238 paths where both the prologue and the epilogue have executed.
7239
7240 @findex reload_completed
7241 @findex leaf_function_p
7242 For such machines, the condition specified in this pattern should only
7243 be true when @code{reload_completed} is nonzero and the function's
7244 epilogue would only be a single instruction. For machines with register
7245 windows, the routine @code{leaf_function_p} may be used to determine if
7246 a register window push is required.
7247
7248 Machines that have conditional return instructions should define patterns
7249 such as
7250
7251 @smallexample
7252 (define_insn ""
7253 [(set (pc)
7254 (if_then_else (match_operator
7255 0 "comparison_operator"
7256 [(reg:CC CC_REG) (const_int 0)])
7257 (return)
7258 (pc)))]
7259 "@var{condition}"
7260 "@dots{}")
7261 @end smallexample
7262
7263 where @var{condition} would normally be the same condition specified on the
7264 named @samp{return} pattern.
7265
7266 @cindex @code{untyped_return} instruction pattern
7267 @item @samp{untyped_return}
7268 Untyped subroutine return instruction. This instruction pattern should
7269 be defined to support @code{__builtin_return} on machines where special
7270 instructions are needed to return a value of any type.
7271
7272 Operand 0 is a memory location where the result of calling a function
7273 with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
7274 expression where each element is a @code{set} expression that indicates
7275 the restoring of a function return value from the result block.
7276
7277 @cindex @code{nop} instruction pattern
7278 @item @samp{nop}
7279 No-op instruction. This instruction pattern name should always be defined
7280 to output a no-op in assembler code. @code{(const_int 0)} will do as an
7281 RTL pattern.
7282
7283 @cindex @code{indirect_jump} instruction pattern
7284 @item @samp{indirect_jump}
7285 An instruction to jump to an address which is operand zero.
7286 This pattern name is mandatory on all machines.
7287
7288 @cindex @code{casesi} instruction pattern
7289 @item @samp{casesi}
7290 Instruction to jump through a dispatch table, including bounds checking.
7291 This instruction takes five operands:
7292
7293 @enumerate
7294 @item
7295 The index to dispatch on, which has mode @code{SImode}.
7296
7297 @item
7298 The lower bound for indices in the table, an integer constant.
7299
7300 @item
7301 The total range of indices in the table---the largest index
7302 minus the smallest one (both inclusive).
7303
7304 @item
7305 A label that precedes the table itself.
7306
7307 @item
7308 A label to jump to if the index has a value outside the bounds.
7309 @end enumerate
7310
7311 The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
7312 @code{jump_table_data}. The number of elements in the table is one plus the
7313 difference between the upper bound and the lower bound.
7314
7315 @cindex @code{tablejump} instruction pattern
7316 @item @samp{tablejump}
7317 Instruction to jump to a variable address. This is a low-level
7318 capability which can be used to implement a dispatch table when there
7319 is no @samp{casesi} pattern.
7320
7321 This pattern requires two operands: the address or offset, and a label
7322 which should immediately precede the jump table. If the macro
7323 @code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
7324 operand is an offset which counts from the address of the table; otherwise,
7325 it is an absolute address to jump to. In either case, the first operand has
7326 mode @code{Pmode}.
7327
7328 The @samp{tablejump} insn is always the last insn before the jump
7329 table it uses. Its assembler code normally has no need to use the
7330 second operand, but you should incorporate it in the RTL pattern so
7331 that the jump optimizer will not delete the table as unreachable code.
7332
7333
7334 @cindex @code{doloop_end} instruction pattern
7335 @item @samp{doloop_end}
7336 Conditional branch instruction that decrements a register and
7337 jumps if the register is nonzero. Operand 0 is the register to
7338 decrement and test; operand 1 is the label to jump to if the
7339 register is nonzero.
7340 @xref{Looping Patterns}.
7341
7342 This optional instruction pattern should be defined for machines with
7343 low-overhead looping instructions as the loop optimizer will try to
7344 modify suitable loops to utilize it. The target hook
7345 @code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which
7346 low-overhead loops can be used.
7347
7348 @cindex @code{doloop_begin} instruction pattern
7349 @item @samp{doloop_begin}
7350 Companion instruction to @code{doloop_end} required for machines that
7351 need to perform some initialization, such as loading a special counter
7352 register. Operand 1 is the associated @code{doloop_end} pattern and
7353 operand 0 is the register that it decrements.
7354
7355 If initialization insns do not always need to be emitted, use a
7356 @code{define_expand} (@pxref{Expander Definitions}) and make it fail.
7357
7358 @cindex @code{canonicalize_funcptr_for_compare} instruction pattern
7359 @item @samp{canonicalize_funcptr_for_compare}
7360 Canonicalize the function pointer in operand 1 and store the result
7361 into operand 0.
7362
7363 Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
7364 may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
7365 and also has mode @code{Pmode}.
7366
7367 Canonicalization of a function pointer usually involves computing
7368 the address of the function which would be called if the function
7369 pointer were used in an indirect call.
7370
7371 Only define this pattern if function pointers on the target machine
7372 can have different values but still call the same function when
7373 used in an indirect call.
7374
7375 @cindex @code{save_stack_block} instruction pattern
7376 @cindex @code{save_stack_function} instruction pattern
7377 @cindex @code{save_stack_nonlocal} instruction pattern
7378 @cindex @code{restore_stack_block} instruction pattern
7379 @cindex @code{restore_stack_function} instruction pattern
7380 @cindex @code{restore_stack_nonlocal} instruction pattern
7381 @item @samp{save_stack_block}
7382 @itemx @samp{save_stack_function}
7383 @itemx @samp{save_stack_nonlocal}
7384 @itemx @samp{restore_stack_block}
7385 @itemx @samp{restore_stack_function}
7386 @itemx @samp{restore_stack_nonlocal}
7387 Most machines save and restore the stack pointer by copying it to or
7388 from an object of mode @code{Pmode}. Do not define these patterns on
7389 such machines.
7390
7391 Some machines require special handling for stack pointer saves and
7392 restores. On those machines, define the patterns corresponding to the
7393 non-standard cases by using a @code{define_expand} (@pxref{Expander
7394 Definitions}) that produces the required insns. The three types of
7395 saves and restores are:
7396
7397 @enumerate
7398 @item
7399 @samp{save_stack_block} saves the stack pointer at the start of a block
7400 that allocates a variable-sized object, and @samp{restore_stack_block}
7401 restores the stack pointer when the block is exited.
7402
7403 @item
7404 @samp{save_stack_function} and @samp{restore_stack_function} do a
7405 similar job for the outermost block of a function and are used when the
7406 function allocates variable-sized objects or calls @code{alloca}. Only
7407 the epilogue uses the restored stack pointer, allowing a simpler save or
7408 restore sequence on some machines.
7409
7410 @item
7411 @samp{save_stack_nonlocal} is used in functions that contain labels
7412 branched to by nested functions. It saves the stack pointer in such a
7413 way that the inner function can use @samp{restore_stack_nonlocal} to
7414 restore the stack pointer. The compiler generates code to restore the
7415 frame and argument pointer registers, but some machines require saving
7416 and restoring additional data such as register window information or
7417 stack backchains. Place insns in these patterns to save and restore any
7418 such required data.
7419 @end enumerate
7420
7421 When saving the stack pointer, operand 0 is the save area and operand 1
7422 is the stack pointer. The mode used to allocate the save area defaults
7423 to @code{Pmode} but you can override that choice by defining the
7424 @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must
7425 specify an integral mode, or @code{VOIDmode} if no save area is needed
7426 for a particular type of save (either because no save is needed or
7427 because a machine-specific save area can be used). Operand 0 is the
7428 stack pointer and operand 1 is the save area for restore operations. If
7429 @samp{save_stack_block} is defined, operand 0 must not be
7430 @code{VOIDmode} since these saves can be arbitrarily nested.
7431
7432 A save area is a @code{mem} that is at a constant offset from
7433 @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
7434 nonlocal gotos and a @code{reg} in the other two cases.
7435
7436 @cindex @code{allocate_stack} instruction pattern
7437 @item @samp{allocate_stack}
7438 Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
7439 the stack pointer to create space for dynamically allocated data.
7440
7441 Store the resultant pointer to this space into operand 0. If you
7442 are allocating space from the main stack, do this by emitting a
7443 move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
7444 If you are allocating the space elsewhere, generate code to copy the
7445 location of the space to operand 0. In the latter case, you must
7446 ensure this space gets freed when the corresponding space on the main
7447 stack is free.
7448
7449 Do not define this pattern if all that must be done is the subtraction.
7450 Some machines require other operations such as stack probes or
7451 maintaining the back chain. Define this pattern to emit those
7452 operations in addition to updating the stack pointer.
7453
7454 @cindex @code{check_stack} instruction pattern
7455 @item @samp{check_stack}
7456 If stack checking (@pxref{Stack Checking}) cannot be done on your system by
7457 probing the stack, define this pattern to perform the needed check and signal
7458 an error if the stack has overflowed. The single operand is the address in
7459 the stack farthest from the current stack pointer that you need to validate.
7460 Normally, on platforms where this pattern is needed, you would obtain the
7461 stack limit from a global or thread-specific variable or register.
7462
7463 @cindex @code{probe_stack_address} instruction pattern
7464 @item @samp{probe_stack_address}
7465 If stack checking (@pxref{Stack Checking}) can be done on your system by
7466 probing the stack but without the need to actually access it, define this
7467 pattern and signal an error if the stack has overflowed. The single operand
7468 is the memory address in the stack that needs to be probed.
7469
7470 @cindex @code{probe_stack} instruction pattern
7471 @item @samp{probe_stack}
7472 If stack checking (@pxref{Stack Checking}) can be done on your system by
7473 probing the stack but doing it with a ``store zero'' instruction is not valid
7474 or optimal, define this pattern to do the probing differently and signal an
7475 error if the stack has overflowed. The single operand is the memory reference
7476 in the stack that needs to be probed.
7477
7478 @cindex @code{nonlocal_goto} instruction pattern
7479 @item @samp{nonlocal_goto}
7480 Emit code to generate a non-local goto, e.g., a jump from one function
7481 to a label in an outer function. This pattern has four arguments,
7482 each representing a value to be used in the jump. The first
7483 argument is to be loaded into the frame pointer, the second is
7484 the address to branch to (code to dispatch to the actual label),
7485 the third is the address of a location where the stack is saved,
7486 and the last is the address of the label, to be placed in the
7487 location for the incoming static chain.
7488
7489 On most machines you need not define this pattern, since GCC will
7490 already generate the correct code, which is to load the frame pointer
7491 and static chain, restore the stack (using the
7492 @samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
7493 to the dispatcher. You need only define this pattern if this code will
7494 not work on your machine.
7495
7496 @cindex @code{nonlocal_goto_receiver} instruction pattern
7497 @item @samp{nonlocal_goto_receiver}
7498 This pattern, if defined, contains code needed at the target of a
7499 nonlocal goto after the code already generated by GCC@. You will not
7500 normally need to define this pattern. A typical reason why you might
7501 need this pattern is if some value, such as a pointer to a global table,
7502 must be restored when the frame pointer is restored. Note that a nonlocal
7503 goto only occurs within a unit-of-translation, so a global table pointer
7504 that is shared by all functions of a given module need not be restored.
7505 There are no arguments.
7506
7507 @cindex @code{exception_receiver} instruction pattern
7508 @item @samp{exception_receiver}
7509 This pattern, if defined, contains code needed at the site of an
7510 exception handler that isn't needed at the site of a nonlocal goto. You
7511 will not normally need to define this pattern. A typical reason why you
7512 might need this pattern is if some value, such as a pointer to a global
7513 table, must be restored after control flow is branched to the handler of
7514 an exception. There are no arguments.
7515
7516 @cindex @code{builtin_setjmp_setup} instruction pattern
7517 @item @samp{builtin_setjmp_setup}
7518 This pattern, if defined, contains additional code needed to initialize
7519 the @code{jmp_buf}. You will not normally need to define this pattern.
7520 A typical reason why you might need this pattern is if some value, such
7521 as a pointer to a global table, must be restored. Though it is
7522 preferred that the pointer value be recalculated if possible (given the
7523 address of a label for instance). The single argument is a pointer to
7524 the @code{jmp_buf}. Note that the buffer is five words long and that
7525 the first three are normally used by the generic mechanism.
7526
7527 @cindex @code{builtin_setjmp_receiver} instruction pattern
7528 @item @samp{builtin_setjmp_receiver}
7529 This pattern, if defined, contains code needed at the site of a
7530 built-in setjmp that isn't needed at the site of a nonlocal goto. You
7531 will not normally need to define this pattern. A typical reason why you
7532 might need this pattern is if some value, such as a pointer to a global
7533 table, must be restored. It takes one argument, which is the label
7534 to which builtin_longjmp transferred control; this pattern may be emitted
7535 at a small offset from that label.
7536
7537 @cindex @code{builtin_longjmp} instruction pattern
7538 @item @samp{builtin_longjmp}
7539 This pattern, if defined, performs the entire action of the longjmp.
7540 You will not normally need to define this pattern unless you also define
7541 @code{builtin_setjmp_setup}. The single argument is a pointer to the
7542 @code{jmp_buf}.
7543
7544 @cindex @code{eh_return} instruction pattern
7545 @item @samp{eh_return}
7546 This pattern, if defined, affects the way @code{__builtin_eh_return},
7547 and thence the call frame exception handling library routines, are
7548 built. It is intended to handle non-trivial actions needed along
7549 the abnormal return path.
7550
7551 The address of the exception handler to which the function should return
7552 is passed as operand to this pattern. It will normally need to copied by
7553 the pattern to some special register or memory location.
7554 If the pattern needs to determine the location of the target call
7555 frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
7556 if defined; it will have already been assigned.
7557
7558 If this pattern is not defined, the default action will be to simply
7559 copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either
7560 that macro or this pattern needs to be defined if call frame exception
7561 handling is to be used.
7562
7563 @cindex @code{prologue} instruction pattern
7564 @anchor{prologue instruction pattern}
7565 @item @samp{prologue}
7566 This pattern, if defined, emits RTL for entry to a function. The function
7567 entry is responsible for setting up the stack frame, initializing the frame
7568 pointer register, saving callee saved registers, etc.
7569
7570 Using a prologue pattern is generally preferred over defining
7571 @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
7572
7573 The @code{prologue} pattern is particularly useful for targets which perform
7574 instruction scheduling.
7575
7576 @cindex @code{window_save} instruction pattern
7577 @anchor{window_save instruction pattern}
7578 @item @samp{window_save}
7579 This pattern, if defined, emits RTL for a register window save. It should
7580 be defined if the target machine has register windows but the window events
7581 are decoupled from calls to subroutines. The canonical example is the SPARC
7582 architecture.
7583
7584 @cindex @code{epilogue} instruction pattern
7585 @anchor{epilogue instruction pattern}
7586 @item @samp{epilogue}
7587 This pattern emits RTL for exit from a function. The function
7588 exit is responsible for deallocating the stack frame, restoring callee saved
7589 registers and emitting the return instruction.
7590
7591 Using an epilogue pattern is generally preferred over defining
7592 @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
7593
7594 The @code{epilogue} pattern is particularly useful for targets which perform
7595 instruction scheduling or which have delay slots for their return instruction.
7596
7597 @cindex @code{sibcall_epilogue} instruction pattern
7598 @item @samp{sibcall_epilogue}
7599 This pattern, if defined, emits RTL for exit from a function without the final
7600 branch back to the calling function. This pattern will be emitted before any
7601 sibling call (aka tail call) sites.
7602
7603 The @code{sibcall_epilogue} pattern must not clobber any arguments used for
7604 parameter passing or any stack slots for arguments passed to the current
7605 function.
7606
7607 @cindex @code{trap} instruction pattern
7608 @item @samp{trap}
7609 This pattern, if defined, signals an error, typically by causing some
7610 kind of signal to be raised.
7611
7612 @cindex @code{ctrap@var{MM}4} instruction pattern
7613 @item @samp{ctrap@var{MM}4}
7614 Conditional trap instruction. Operand 0 is a piece of RTL which
7615 performs a comparison, and operands 1 and 2 are the arms of the
7616 comparison. Operand 3 is the trap code, an integer.
7617
7618 A typical @code{ctrap} pattern looks like
7619
7620 @smallexample
7621 (define_insn "ctrapsi4"
7622 [(trap_if (match_operator 0 "trap_operator"
7623 [(match_operand 1 "register_operand")
7624 (match_operand 2 "immediate_operand")])
7625 (match_operand 3 "const_int_operand" "i"))]
7626 ""
7627 "@dots{}")
7628 @end smallexample
7629
7630 @cindex @code{prefetch} instruction pattern
7631 @item @samp{prefetch}
7632 This pattern, if defined, emits code for a non-faulting data prefetch
7633 instruction. Operand 0 is the address of the memory to prefetch. Operand 1
7634 is a constant 1 if the prefetch is preparing for a write to the memory
7635 address, or a constant 0 otherwise. Operand 2 is the expected degree of
7636 temporal locality of the data and is a value between 0 and 3, inclusive; 0
7637 means that the data has no temporal locality, so it need not be left in the
7638 cache after the access; 3 means that the data has a high degree of temporal
7639 locality and should be left in all levels of cache possible; 1 and 2 mean,
7640 respectively, a low or moderate degree of temporal locality.
7641
7642 Targets that do not support write prefetches or locality hints can ignore
7643 the values of operands 1 and 2.
7644
7645 @cindex @code{blockage} instruction pattern
7646 @item @samp{blockage}
7647 This pattern defines a pseudo insn that prevents the instruction
7648 scheduler and other passes from moving instructions and using register
7649 equivalences across the boundary defined by the blockage insn.
7650 This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM.
7651
7652 @cindex @code{memory_blockage} instruction pattern
7653 @item @samp{memory_blockage}
7654 This pattern, if defined, represents a compiler memory barrier, and will be
7655 placed at points across which RTL passes may not propagate memory accesses.
7656 This instruction needs to read and write volatile BLKmode memory. It does
7657 not need to generate any machine instruction. If this pattern is not defined,
7658 the compiler falls back to emitting an instruction corresponding
7659 to @code{asm volatile ("" ::: "memory")}.
7660
7661 @cindex @code{memory_barrier} instruction pattern
7662 @item @samp{memory_barrier}
7663 If the target memory model is not fully synchronous, then this pattern
7664 should be defined to an instruction that orders both loads and stores
7665 before the instruction with respect to loads and stores after the instruction.
7666 This pattern has no operands.
7667
7668 @cindex @code{speculation_barrier} instruction pattern
7669 @item @samp{speculation_barrier}
7670 If the target can support speculative execution, then this pattern should
7671 be defined to an instruction that will block subsequent execution until
7672 any prior speculation conditions has been resolved. The pattern must also
7673 ensure that the compiler cannot move memory operations past the barrier,
7674 so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no
7675 operands.
7676
7677 If this pattern is not defined then the default expansion of
7678 @code{__builtin_speculation_safe_value} will emit a warning. You can
7679 suppress this warning by defining this pattern with a final condition
7680 of @code{0} (zero), which tells the compiler that a speculation
7681 barrier is not needed for this target.
7682
7683 @cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
7684 @item @samp{sync_compare_and_swap@var{mode}}
7685 This pattern, if defined, emits code for an atomic compare-and-swap
7686 operation. Operand 1 is the memory on which the atomic operation is
7687 performed. Operand 2 is the ``old'' value to be compared against the
7688 current contents of the memory location. Operand 3 is the ``new'' value
7689 to store in the memory if the compare succeeds. Operand 0 is the result
7690 of the operation; it should contain the contents of the memory
7691 before the operation. If the compare succeeds, this should obviously be
7692 a copy of operand 2.
7693
7694 This pattern must show that both operand 0 and operand 1 are modified.
7695
7696 This pattern must issue any memory barrier instructions such that all
7697 memory operations before the atomic operation occur before the atomic
7698 operation and all memory operations after the atomic operation occur
7699 after the atomic operation.
7700
7701 For targets where the success or failure of the compare-and-swap
7702 operation is available via the status flags, it is possible to
7703 avoid a separate compare operation and issue the subsequent
7704 branch or store-flag operation immediately after the compare-and-swap.
7705 To this end, GCC will look for a @code{MODE_CC} set in the
7706 output of @code{sync_compare_and_swap@var{mode}}; if the machine
7707 description includes such a set, the target should also define special
7708 @code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then
7709 be able to take the destination of the @code{MODE_CC} set and pass it
7710 to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
7711 operand of the comparison (the second will be @code{(const_int 0)}).
7712
7713 For targets where the operating system may provide support for this
7714 operation via library calls, the @code{sync_compare_and_swap_optab}
7715 may be initialized to a function with the same interface as the
7716 @code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire
7717 set of @var{__sync} builtins are supported via library calls, the
7718 target can initialize all of the optabs at once with
7719 @code{init_sync_libfuncs}.
7720 For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
7721 assumed that these library calls do @emph{not} use any kind of
7722 interruptable locking.
7723
7724 @cindex @code{sync_add@var{mode}} instruction pattern
7725 @cindex @code{sync_sub@var{mode}} instruction pattern
7726 @cindex @code{sync_ior@var{mode}} instruction pattern
7727 @cindex @code{sync_and@var{mode}} instruction pattern
7728 @cindex @code{sync_xor@var{mode}} instruction pattern
7729 @cindex @code{sync_nand@var{mode}} instruction pattern
7730 @item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
7731 @itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
7732 @itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
7733 These patterns emit code for an atomic operation on memory.
7734 Operand 0 is the memory on which the atomic operation is performed.
7735 Operand 1 is the second operand to the binary operator.
7736
7737 This pattern must issue any memory barrier instructions such that all
7738 memory operations before the atomic operation occur before the atomic
7739 operation and all memory operations after the atomic operation occur
7740 after the atomic operation.
7741
7742 If these patterns are not defined, the operation will be constructed
7743 from a compare-and-swap operation, if defined.
7744
7745 @cindex @code{sync_old_add@var{mode}} instruction pattern
7746 @cindex @code{sync_old_sub@var{mode}} instruction pattern
7747 @cindex @code{sync_old_ior@var{mode}} instruction pattern
7748 @cindex @code{sync_old_and@var{mode}} instruction pattern
7749 @cindex @code{sync_old_xor@var{mode}} instruction pattern
7750 @cindex @code{sync_old_nand@var{mode}} instruction pattern
7751 @item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
7752 @itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
7753 @itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
7754 These patterns emit code for an atomic operation on memory,
7755 and return the value that the memory contained before the operation.
7756 Operand 0 is the result value, operand 1 is the memory on which the
7757 atomic operation is performed, and operand 2 is the second operand
7758 to the binary operator.
7759
7760 This pattern must issue any memory barrier instructions such that all
7761 memory operations before the atomic operation occur before the atomic
7762 operation and all memory operations after the atomic operation occur
7763 after the atomic operation.
7764
7765 If these patterns are not defined, the operation will be constructed
7766 from a compare-and-swap operation, if defined.
7767
7768 @cindex @code{sync_new_add@var{mode}} instruction pattern
7769 @cindex @code{sync_new_sub@var{mode}} instruction pattern
7770 @cindex @code{sync_new_ior@var{mode}} instruction pattern
7771 @cindex @code{sync_new_and@var{mode}} instruction pattern
7772 @cindex @code{sync_new_xor@var{mode}} instruction pattern
7773 @cindex @code{sync_new_nand@var{mode}} instruction pattern
7774 @item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
7775 @itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
7776 @itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
7777 These patterns are like their @code{sync_old_@var{op}} counterparts,
7778 except that they return the value that exists in the memory location
7779 after the operation, rather than before the operation.
7780
7781 @cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
7782 @item @samp{sync_lock_test_and_set@var{mode}}
7783 This pattern takes two forms, based on the capabilities of the target.
7784 In either case, operand 0 is the result of the operand, operand 1 is
7785 the memory on which the atomic operation is performed, and operand 2
7786 is the value to set in the lock.
7787
7788 In the ideal case, this operation is an atomic exchange operation, in
7789 which the previous value in memory operand is copied into the result
7790 operand, and the value operand is stored in the memory operand.
7791
7792 For less capable targets, any value operand that is not the constant 1
7793 should be rejected with @code{FAIL}. In this case the target may use
7794 an atomic test-and-set bit operation. The result operand should contain
7795 1 if the bit was previously set and 0 if the bit was previously clear.
7796 The true contents of the memory operand are implementation defined.
7797
7798 This pattern must issue any memory barrier instructions such that the
7799 pattern as a whole acts as an acquire barrier, that is all memory
7800 operations after the pattern do not occur until the lock is acquired.
7801
7802 If this pattern is not defined, the operation will be constructed from
7803 a compare-and-swap operation, if defined.
7804
7805 @cindex @code{sync_lock_release@var{mode}} instruction pattern
7806 @item @samp{sync_lock_release@var{mode}}
7807 This pattern, if defined, releases a lock set by
7808 @code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory
7809 that contains the lock; operand 1 is the value to store in the lock.
7810
7811 If the target doesn't implement full semantics for
7812 @code{sync_lock_test_and_set@var{mode}}, any value operand which is not
7813 the constant 0 should be rejected with @code{FAIL}, and the true contents
7814 of the memory operand are implementation defined.
7815
7816 This pattern must issue any memory barrier instructions such that the
7817 pattern as a whole acts as a release barrier, that is the lock is
7818 released only after all previous memory operations have completed.
7819
7820 If this pattern is not defined, then a @code{memory_barrier} pattern
7821 will be emitted, followed by a store of the value to the memory operand.
7822
7823 @cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
7824 @item @samp{atomic_compare_and_swap@var{mode}}
7825 This pattern, if defined, emits code for an atomic compare-and-swap
7826 operation with memory model semantics. Operand 2 is the memory on which
7827 the atomic operation is performed. Operand 0 is an output operand which
7828 is set to true or false based on whether the operation succeeded. Operand
7829 1 is an output operand which is set to the contents of the memory before
7830 the operation was attempted. Operand 3 is the value that is expected to
7831 be in memory. Operand 4 is the value to put in memory if the expected
7832 value is found there. Operand 5 is set to 1 if this compare and swap is to
7833 be treated as a weak operation. Operand 6 is the memory model to be used
7834 if the operation is a success. Operand 7 is the memory model to be used
7835 if the operation fails.
7836
7837 If memory referred to in operand 2 contains the value in operand 3, then
7838 operand 4 is stored in memory pointed to by operand 2 and fencing based on
7839 the memory model in operand 6 is issued.
7840
7841 If memory referred to in operand 2 does not contain the value in operand 3,
7842 then fencing based on the memory model in operand 7 is issued.
7843
7844 If a target does not support weak compare-and-swap operations, or the port
7845 elects not to implement weak operations, the argument in operand 5 can be
7846 ignored. Note a strong implementation must be provided.
7847
7848 If this pattern is not provided, the @code{__atomic_compare_exchange}
7849 built-in functions will utilize the legacy @code{sync_compare_and_swap}
7850 pattern with an @code{__ATOMIC_SEQ_CST} memory model.
7851
7852 @cindex @code{atomic_load@var{mode}} instruction pattern
7853 @item @samp{atomic_load@var{mode}}
7854 This pattern implements an atomic load operation with memory model
7855 semantics. Operand 1 is the memory address being loaded from. Operand 0
7856 is the result of the load. Operand 2 is the memory model to be used for
7857 the load operation.
7858
7859 If not present, the @code{__atomic_load} built-in function will either
7860 resort to a normal load with memory barriers, or a compare-and-swap
7861 operation if a normal load would not be atomic.
7862
7863 @cindex @code{atomic_store@var{mode}} instruction pattern
7864 @item @samp{atomic_store@var{mode}}
7865 This pattern implements an atomic store operation with memory model
7866 semantics. Operand 0 is the memory address being stored to. Operand 1
7867 is the value to be written. Operand 2 is the memory model to be used for
7868 the operation.
7869
7870 If not present, the @code{__atomic_store} built-in function will attempt to
7871 perform a normal store and surround it with any required memory fences. If
7872 the store would not be atomic, then an @code{__atomic_exchange} is
7873 attempted with the result being ignored.
7874
7875 @cindex @code{atomic_exchange@var{mode}} instruction pattern
7876 @item @samp{atomic_exchange@var{mode}}
7877 This pattern implements an atomic exchange operation with memory model
7878 semantics. Operand 1 is the memory location the operation is performed on.
7879 Operand 0 is an output operand which is set to the original value contained
7880 in the memory pointed to by operand 1. Operand 2 is the value to be
7881 stored. Operand 3 is the memory model to be used.
7882
7883 If this pattern is not present, the built-in function
7884 @code{__atomic_exchange} will attempt to preform the operation with a
7885 compare and swap loop.
7886
7887 @cindex @code{atomic_add@var{mode}} instruction pattern
7888 @cindex @code{atomic_sub@var{mode}} instruction pattern
7889 @cindex @code{atomic_or@var{mode}} instruction pattern
7890 @cindex @code{atomic_and@var{mode}} instruction pattern
7891 @cindex @code{atomic_xor@var{mode}} instruction pattern
7892 @cindex @code{atomic_nand@var{mode}} instruction pattern
7893 @item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
7894 @itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
7895 @itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
7896 These patterns emit code for an atomic operation on memory with memory
7897 model semantics. Operand 0 is the memory on which the atomic operation is
7898 performed. Operand 1 is the second operand to the binary operator.
7899 Operand 2 is the memory model to be used by the operation.
7900
7901 If these patterns are not defined, attempts will be made to use legacy
7902 @code{sync} patterns, or equivalent patterns which return a result. If
7903 none of these are available a compare-and-swap loop will be used.
7904
7905 @cindex @code{atomic_fetch_add@var{mode}} instruction pattern
7906 @cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
7907 @cindex @code{atomic_fetch_or@var{mode}} instruction pattern
7908 @cindex @code{atomic_fetch_and@var{mode}} instruction pattern
7909 @cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
7910 @cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
7911 @item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
7912 @itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
7913 @itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
7914 These patterns emit code for an atomic operation on memory with memory
7915 model semantics, and return the original value. Operand 0 is an output
7916 operand which contains the value of the memory location before the
7917 operation was performed. Operand 1 is the memory on which the atomic
7918 operation is performed. Operand 2 is the second operand to the binary
7919 operator. Operand 3 is the memory model to be used by the operation.
7920
7921 If these patterns are not defined, attempts will be made to use legacy
7922 @code{sync} patterns. If none of these are available a compare-and-swap
7923 loop will be used.
7924
7925 @cindex @code{atomic_add_fetch@var{mode}} instruction pattern
7926 @cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
7927 @cindex @code{atomic_or_fetch@var{mode}} instruction pattern
7928 @cindex @code{atomic_and_fetch@var{mode}} instruction pattern
7929 @cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
7930 @cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
7931 @item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
7932 @itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
7933 @itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
7934 These patterns emit code for an atomic operation on memory with memory
7935 model semantics and return the result after the operation is performed.
7936 Operand 0 is an output operand which contains the value after the
7937 operation. Operand 1 is the memory on which the atomic operation is
7938 performed. Operand 2 is the second operand to the binary operator.
7939 Operand 3 is the memory model to be used by the operation.
7940
7941 If these patterns are not defined, attempts will be made to use legacy
7942 @code{sync} patterns, or equivalent patterns which return the result before
7943 the operation followed by the arithmetic operation required to produce the
7944 result. If none of these are available a compare-and-swap loop will be
7945 used.
7946
7947 @cindex @code{atomic_test_and_set} instruction pattern
7948 @item @samp{atomic_test_and_set}
7949 This pattern emits code for @code{__builtin_atomic_test_and_set}.
7950 Operand 0 is an output operand which is set to true if the previous
7951 previous contents of the byte was "set", and false otherwise. Operand 1
7952 is the @code{QImode} memory to be modified. Operand 2 is the memory
7953 model to be used.
7954
7955 The specific value that defines "set" is implementation defined, and
7956 is normally based on what is performed by the native atomic test and set
7957 instruction.
7958
7959 @cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern
7960 @cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern
7961 @cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern
7962 @item @samp{atomic_bit_test_and_set@var{mode}}
7963 @itemx @samp{atomic_bit_test_and_complement@var{mode}}
7964 @itemx @samp{atomic_bit_test_and_reset@var{mode}}
7965 These patterns emit code for an atomic bitwise operation on memory with memory
7966 model semantics, and return the original value of the specified bit.
7967 Operand 0 is an output operand which contains the value of the specified bit
7968 from the memory location before the operation was performed. Operand 1 is the
7969 memory on which the atomic operation is performed. Operand 2 is the bit within
7970 the operand, starting with least significant bit. Operand 3 is the memory model
7971 to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx}
7972 if operand 0 should contain the original value of the specified bit in the
7973 least significant bit of the operand, and @code{const0_rtx} if the bit should
7974 be in its original position in the operand.
7975 @code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after
7976 remembering its original value, @code{atomic_bit_test_and_complement@var{mode}}
7977 inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears
7978 the specified bit.
7979
7980 If these patterns are not defined, attempts will be made to use
7981 @code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or
7982 @code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync}
7983 counterparts. If none of these are available a compare-and-swap
7984 loop will be used.
7985
7986 @cindex @code{atomic_add_fetch_cmp_0@var{mode}} instruction pattern
7987 @cindex @code{atomic_sub_fetch_cmp_0@var{mode}} instruction pattern
7988 @cindex @code{atomic_and_fetch_cmp_0@var{mode}} instruction pattern
7989 @cindex @code{atomic_or_fetch_cmp_0@var{mode}} instruction pattern
7990 @cindex @code{atomic_xor_fetch_cmp_0@var{mode}} instruction pattern
7991 @item @samp{atomic_add_fetch_cmp_0@var{mode}}
7992 @itemx @samp{atomic_sub_fetch_cmp_0@var{mode}}
7993 @itemx @samp{atomic_and_fetch_cmp_0@var{mode}}
7994 @itemx @samp{atomic_or_fetch_cmp_0@var{mode}}
7995 @itemx @samp{atomic_xor_fetch_cmp_0@var{mode}}
7996 These patterns emit code for an atomic operation on memory with memory
7997 model semantics if the fetch result is used only in a comparison against
7998 zero.
7999 Operand 0 is an output operand which contains a boolean result of comparison
8000 of the value after the operation against zero. Operand 1 is the memory on
8001 which the atomic operation is performed. Operand 2 is the second operand
8002 to the binary operator. Operand 3 is the memory model to be used by the
8003 operation. Operand 4 is an integer holding the comparison code, one of
8004 @code{EQ}, @code{NE}, @code{LT}, @code{GT}, @code{LE} or @code{GE}.
8005
8006 If these patterns are not defined, attempts will be made to use separate
8007 atomic operation and fetch pattern followed by comparison of the result
8008 against zero.
8009
8010 @cindex @code{mem_thread_fence} instruction pattern
8011 @item @samp{mem_thread_fence}
8012 This pattern emits code required to implement a thread fence with
8013 memory model semantics. Operand 0 is the memory model to be used.
8014
8015 For the @code{__ATOMIC_RELAXED} model no instructions need to be issued
8016 and this expansion is not invoked.
8017
8018 The compiler always emits a compiler memory barrier regardless of what
8019 expanding this pattern produced.
8020
8021 If this pattern is not defined, the compiler falls back to expanding the
8022 @code{memory_barrier} pattern, then to emitting @code{__sync_synchronize}
8023 library call, and finally to just placing a compiler memory barrier.
8024
8025 @cindex @code{get_thread_pointer@var{mode}} instruction pattern
8026 @cindex @code{set_thread_pointer@var{mode}} instruction pattern
8027 @item @samp{get_thread_pointer@var{mode}}
8028 @itemx @samp{set_thread_pointer@var{mode}}
8029 These patterns emit code that reads/sets the TLS thread pointer. Currently,
8030 these are only needed if the target needs to support the
8031 @code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer}
8032 builtins.
8033
8034 The get/set patterns have a single output/input operand respectively,
8035 with @var{mode} intended to be @code{Pmode}.
8036
8037 @cindex @code{stack_protect_combined_set} instruction pattern
8038 @item @samp{stack_protect_combined_set}
8039 This pattern, if defined, moves a @code{ptr_mode} value from an address
8040 whose declaration RTX is given in operand 1 to the memory in operand 0
8041 without leaving the value in a register afterward. If several
8042 instructions are needed by the target to perform the operation (eg. to
8043 load the address from a GOT entry then load the @code{ptr_mode} value
8044 and finally store it), it is the backend's responsibility to ensure no
8045 intermediate result gets spilled. This is to avoid leaking the value
8046 some place that an attacker might use to rewrite the stack guard slot
8047 after having clobbered it.
8048
8049 If this pattern is not defined, then the address declaration is
8050 expanded first in the standard way and a @code{stack_protect_set}
8051 pattern is then generated to move the value from that address to the
8052 address in operand 0.
8053
8054 @cindex @code{stack_protect_set} instruction pattern
8055 @item @samp{stack_protect_set}
8056 This pattern, if defined, moves a @code{ptr_mode} value from the valid
8057 memory location in operand 1 to the memory in operand 0 without leaving
8058 the value in a register afterward. This is to avoid leaking the value
8059 some place that an attacker might use to rewrite the stack guard slot
8060 after having clobbered it.
8061
8062 Note: on targets where the addressing modes do not allow to load
8063 directly from stack guard address, the address is expanded in a standard
8064 way first which could cause some spills.
8065
8066 If this pattern is not defined, then a plain move pattern is generated.
8067
8068 @cindex @code{stack_protect_combined_test} instruction pattern
8069 @item @samp{stack_protect_combined_test}
8070 This pattern, if defined, compares a @code{ptr_mode} value from an
8071 address whose declaration RTX is given in operand 1 with the memory in
8072 operand 0 without leaving the value in a register afterward and
8073 branches to operand 2 if the values were equal. If several
8074 instructions are needed by the target to perform the operation (eg. to
8075 load the address from a GOT entry then load the @code{ptr_mode} value
8076 and finally store it), it is the backend's responsibility to ensure no
8077 intermediate result gets spilled. This is to avoid leaking the value
8078 some place that an attacker might use to rewrite the stack guard slot
8079 after having clobbered it.
8080
8081 If this pattern is not defined, then the address declaration is
8082 expanded first in the standard way and a @code{stack_protect_test}
8083 pattern is then generated to compare the value from that address to the
8084 value at the memory in operand 0.
8085
8086 @cindex @code{stack_protect_test} instruction pattern
8087 @item @samp{stack_protect_test}
8088 This pattern, if defined, compares a @code{ptr_mode} value from the
8089 valid memory location in operand 1 with the memory in operand 0 without
8090 leaving the value in a register afterward and branches to operand 2 if
8091 the values were equal.
8092
8093 If this pattern is not defined, then a plain compare pattern and
8094 conditional branch pattern is used.
8095
8096 @cindex @code{clear_cache} instruction pattern
8097 @item @samp{clear_cache}
8098 This pattern, if defined, flushes the instruction cache for a region of
8099 memory. The region is bounded to by the Pmode pointers in operand 0
8100 inclusive and operand 1 exclusive.
8101
8102 If this pattern is not defined, a call to the library function
8103 @code{__clear_cache} is used.
8104
8105 @cindex @code{spaceship@var{m}3} instruction pattern
8106 @item @samp{spaceship@var{m}3}
8107 Initialize output operand 0 with mode of integer type to -1, 0, 1 or 2
8108 if operand 1 with mode @var{m} compares less than operand 2, equal to
8109 operand 2, greater than operand 2 or is unordered with operand 2.
8110 @var{m} should be a scalar floating point mode.
8111
8112 This pattern is not allowed to @code{FAIL}.
8113
8114 @end table
8115
8116 @end ifset
8117 @c Each of the following nodes are wrapped in separate
8118 @c "@ifset INTERNALS" to work around memory limits for the default
8119 @c configuration in older tetex distributions. Known to not work:
8120 @c tetex-1.0.7, known to work: tetex-2.0.2.
8121 @ifset INTERNALS
8122 @node Pattern Ordering
8123 @section When the Order of Patterns Matters
8124 @cindex Pattern Ordering
8125 @cindex Ordering of Patterns
8126
8127 Sometimes an insn can match more than one instruction pattern. Then the
8128 pattern that appears first in the machine description is the one used.
8129 Therefore, more specific patterns (patterns that will match fewer things)
8130 and faster instructions (those that will produce better code when they
8131 do match) should usually go first in the description.
8132
8133 In some cases the effect of ordering the patterns can be used to hide
8134 a pattern when it is not valid. For example, the 68000 has an
8135 instruction for converting a fullword to floating point and another
8136 for converting a byte to floating point. An instruction converting
8137 an integer to floating point could match either one. We put the
8138 pattern to convert the fullword first to make sure that one will
8139 be used rather than the other. (Otherwise a large integer might
8140 be generated as a single-byte immediate quantity, which would not work.)
8141 Instead of using this pattern ordering it would be possible to make the
8142 pattern for convert-a-byte smart enough to deal properly with any
8143 constant value.
8144
8145 @end ifset
8146 @ifset INTERNALS
8147 @node Dependent Patterns
8148 @section Interdependence of Patterns
8149 @cindex Dependent Patterns
8150 @cindex Interdependence of Patterns
8151
8152 In some cases machines support instructions identical except for the
8153 machine mode of one or more operands. For example, there may be
8154 ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
8155 patterns are
8156
8157 @smallexample
8158 (set (match_operand:SI 0 @dots{})
8159 (extend:SI (match_operand:HI 1 @dots{})))
8160
8161 (set (match_operand:SI 0 @dots{})
8162 (extend:SI (match_operand:QI 1 @dots{})))
8163 @end smallexample
8164
8165 @noindent
8166 Constant integers do not specify a machine mode, so an instruction to
8167 extend a constant value could match either pattern. The pattern it
8168 actually will match is the one that appears first in the file. For correct
8169 results, this must be the one for the widest possible mode (@code{HImode},
8170 here). If the pattern matches the @code{QImode} instruction, the results
8171 will be incorrect if the constant value does not actually fit that mode.
8172
8173 Such instructions to extend constants are rarely generated because they are
8174 optimized away, but they do occasionally happen in nonoptimized
8175 compilations.
8176
8177 If a constraint in a pattern allows a constant, the reload pass may
8178 replace a register with a constant permitted by the constraint in some
8179 cases. Similarly for memory references. Because of this substitution,
8180 you should not provide separate patterns for increment and decrement
8181 instructions. Instead, they should be generated from the same pattern
8182 that supports register-register add insns by examining the operands and
8183 generating the appropriate machine instruction.
8184
8185 @end ifset
8186 @ifset INTERNALS
8187 @node Jump Patterns
8188 @section Defining Jump Instruction Patterns
8189 @cindex jump instruction patterns
8190 @cindex defining jump instruction patterns
8191
8192 GCC does not assume anything about how the machine realizes jumps.
8193 The machine description should define a single pattern, usually
8194 a @code{define_expand}, which expands to all the required insns.
8195
8196 Usually, this would be a comparison insn to set the condition code
8197 and a separate branch insn testing the condition code and branching
8198 or not according to its value. For many machines, however,
8199 separating compares and branches is limiting, which is why the
8200 more flexible approach with one @code{define_expand} is used in GCC.
8201 The machine description becomes clearer for architectures that
8202 have compare-and-branch instructions but no condition code. It also
8203 works better when different sets of comparison operators are supported
8204 by different kinds of conditional branches (e.g.@: integer vs.@:
8205 floating-point), or by conditional branches with respect to conditional stores.
8206
8207 Two separate insns are always used on most machines that use a separate
8208 condition code register (@pxref{Condition Code}).
8209
8210 Even in this case having a single entry point for conditional branches
8211 is advantageous, because it handles equally well the case where a single
8212 comparison instruction records the results of both signed and unsigned
8213 comparison of the given operands (with the branch insns coming in distinct
8214 signed and unsigned flavors) as in the x86 or SPARC, and the case where
8215 there are distinct signed and unsigned compare instructions and only
8216 one set of conditional branch instructions as in the PowerPC.
8217
8218 @end ifset
8219 @ifset INTERNALS
8220 @node Looping Patterns
8221 @section Defining Looping Instruction Patterns
8222 @cindex looping instruction patterns
8223 @cindex defining looping instruction patterns
8224
8225 Some machines have special jump instructions that can be utilized to
8226 make loops more efficient. A common example is the 68000 @samp{dbra}
8227 instruction which performs a decrement of a register and a branch if the
8228 result was greater than zero. Other machines, in particular digital
8229 signal processors (DSPs), have special block repeat instructions to
8230 provide low-overhead loop support. For example, the TI TMS320C3x/C4x
8231 DSPs have a block repeat instruction that loads special registers to
8232 mark the top and end of a loop and to count the number of loop
8233 iterations. This avoids the need for fetching and executing a
8234 @samp{dbra}-like instruction and avoids pipeline stalls associated with
8235 the jump.
8236
8237 GCC has two special named patterns to support low overhead looping.
8238 They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted
8239 by the loop optimizer for certain well-behaved loops with a finite
8240 number of loop iterations using information collected during strength
8241 reduction.
8242
8243 The @samp{doloop_end} pattern describes the actual looping instruction
8244 (or the implicit looping operation) and the @samp{doloop_begin} pattern
8245 is an optional companion pattern that can be used for initialization
8246 needed for some low-overhead looping instructions.
8247
8248 Note that some machines require the actual looping instruction to be
8249 emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting
8250 the true RTL for a looping instruction at the top of the loop can cause
8251 problems with flow analysis. So instead, a dummy @code{doloop} insn is
8252 emitted at the end of the loop. The machine dependent reorg pass checks
8253 for the presence of this @code{doloop} insn and then searches back to
8254 the top of the loop, where it inserts the true looping insn (provided
8255 there are no instructions in the loop which would cause problems). Any
8256 additional labels can be emitted at this point. In addition, if the
8257 desired special iteration counter register was not allocated, this
8258 machine dependent reorg pass could emit a traditional compare and jump
8259 instruction pair.
8260
8261 For the @samp{doloop_end} pattern, the loop optimizer allocates an
8262 additional pseudo register as an iteration counter. This pseudo
8263 register cannot be used within the loop (i.e., general induction
8264 variables cannot be derived from it), however, in many cases the loop
8265 induction variable may become redundant and removed by the flow pass.
8266
8267 The @samp{doloop_end} pattern must have a specific structure to be
8268 handled correctly by GCC. The example below is taken (slightly
8269 simplified) from the PDP-11 target:
8270
8271 @smallexample
8272 @group
8273 (define_expand "doloop_end"
8274 [(parallel [(set (pc)
8275 (if_then_else
8276 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8277 (const_int 1))
8278 (label_ref (match_operand 1 "" ""))
8279 (pc)))
8280 (set (match_dup 0)
8281 (plus:HI (match_dup 0)
8282 (const_int -1)))])]
8283 ""
8284 "@{
8285 if (GET_MODE (operands[0]) != HImode)
8286 FAIL;
8287 @}")
8288
8289 (define_insn "doloop_end_insn"
8290 [(set (pc)
8291 (if_then_else
8292 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8293 (const_int 1))
8294 (label_ref (match_operand 1 "" ""))
8295 (pc)))
8296 (set (match_dup 0)
8297 (plus:HI (match_dup 0)
8298 (const_int -1)))]
8299 ""
8300
8301 @{
8302 if (which_alternative == 0)
8303 return "sob %0,%l1";
8304
8305 /* emulate sob */
8306 output_asm_insn ("dec %0", operands);
8307 return "bne %l1";
8308 @})
8309 @end group
8310 @end smallexample
8311
8312 The first part of the pattern describes the branch condition. GCC
8313 supports three cases for the way the target machine handles the loop
8314 counter:
8315 @itemize @bullet
8316 @item Loop terminates when the loop register decrements to zero. This
8317 is represented by a @code{ne} comparison of the register (its old value)
8318 with constant 1 (as in the example above).
8319 @item Loop terminates when the loop register decrements to @minus{}1.
8320 This is represented by a @code{ne} comparison of the register with
8321 constant zero.
8322 @item Loop terminates when the loop register decrements to a negative
8323 value. This is represented by a @code{ge} comparison of the register
8324 with constant zero. For this case, GCC will attach a @code{REG_NONNEG}
8325 note to the @code{doloop_end} insn if it can determine that the register
8326 will be non-negative.
8327 @end itemize
8328
8329 Since the @code{doloop_end} insn is a jump insn that also has an output,
8330 the reload pass does not handle the output operand. Therefore, the
8331 constraint must allow for that operand to be in memory rather than a
8332 register. In the example shown above, that is handled (in the
8333 @code{doloop_end_insn} pattern) by using a loop instruction sequence
8334 that can handle memory operands when the memory alternative appears.
8335
8336 GCC does not check the mode of the loop register operand when generating
8337 the @code{doloop_end} pattern. If the pattern is only valid for some
8338 modes but not others, the pattern should be a @code{define_expand}
8339 pattern that checks the operand mode in the preparation code, and issues
8340 @code{FAIL} if an unsupported mode is found. The example above does
8341 this, since the machine instruction to be used only exists for
8342 @code{HImode}.
8343
8344 If the @code{doloop_end} pattern is a @code{define_expand}, there must
8345 also be a @code{define_insn} or @code{define_insn_and_split} matching
8346 the generated pattern. Otherwise, the compiler will fail during loop
8347 optimization.
8348
8349 @end ifset
8350 @ifset INTERNALS
8351 @node Insn Canonicalizations
8352 @section Canonicalization of Instructions
8353 @cindex canonicalization of instructions
8354 @cindex insn canonicalization
8355
8356 There are often cases where multiple RTL expressions could represent an
8357 operation performed by a single machine instruction. This situation is
8358 most commonly encountered with logical, branch, and multiply-accumulate
8359 instructions. In such cases, the compiler attempts to convert these
8360 multiple RTL expressions into a single canonical form to reduce the
8361 number of insn patterns required.
8362
8363 In addition to algebraic simplifications, following canonicalizations
8364 are performed:
8365
8366 @itemize @bullet
8367 @item
8368 For commutative and comparison operators, a constant is always made the
8369 second operand. If a machine only supports a constant as the second
8370 operand, only patterns that match a constant in the second operand need
8371 be supplied.
8372
8373 @item
8374 For associative operators, a sequence of operators will always chain
8375 to the left; for instance, only the left operand of an integer @code{plus}
8376 can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor},
8377 @code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
8378 @code{umax} are associative when applied to integers, and sometimes to
8379 floating-point.
8380
8381 @item
8382 @cindex @code{neg}, canonicalization of
8383 @cindex @code{not}, canonicalization of
8384 @cindex @code{mult}, canonicalization of
8385 @cindex @code{plus}, canonicalization of
8386 @cindex @code{minus}, canonicalization of
8387 For these operators, if only one operand is a @code{neg}, @code{not},
8388 @code{mult}, @code{plus}, or @code{minus} expression, it will be the
8389 first operand.
8390
8391 @item
8392 In combinations of @code{neg}, @code{mult}, @code{plus}, and
8393 @code{minus}, the @code{neg} operations (if any) will be moved inside
8394 the operations as far as possible. For instance,
8395 @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
8396 @code{(plus (mult (neg B) C) A)} is canonicalized as
8397 @code{(minus A (mult B C))}.
8398
8399 @cindex @code{compare}, canonicalization of
8400 @item
8401 For the @code{compare} operator, a constant is always the second operand
8402 if the first argument is a condition code register.
8403
8404 @item
8405 For instructions that inherently set a condition code register, the
8406 @code{compare} operator is always written as the first RTL expression of
8407 the @code{parallel} instruction pattern. For example,
8408
8409 @smallexample
8410 (define_insn ""
8411 [(set (reg:CCZ FLAGS_REG)
8412 (compare:CCZ
8413 (plus:SI
8414 (match_operand:SI 1 "register_operand" "%r")
8415 (match_operand:SI 2 "register_operand" "r"))
8416 (const_int 0)))
8417 (set (match_operand:SI 0 "register_operand" "=r")
8418 (plus:SI (match_dup 1) (match_dup 2)))]
8419 ""
8420 "addl %0, %1, %2")
8421 @end smallexample
8422
8423 @item
8424 An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
8425 @code{minus} is made the first operand under the same conditions as
8426 above.
8427
8428 @item
8429 @code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
8430 @code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
8431 of @code{ltu}.
8432
8433 @item
8434 @code{(minus @var{x} (const_int @var{n}))} is converted to
8435 @code{(plus @var{x} (const_int @var{-n}))}.
8436
8437 @item
8438 Within address computations (i.e., inside @code{mem}), a left shift is
8439 converted into the appropriate multiplication by a power of two.
8440
8441 @cindex @code{ior}, canonicalization of
8442 @cindex @code{and}, canonicalization of
8443 @cindex De Morgan's law
8444 @item
8445 De Morgan's Law is used to move bitwise negation inside a bitwise
8446 logical-and or logical-or operation. If this results in only one
8447 operand being a @code{not} expression, it will be the first one.
8448
8449 A machine that has an instruction that performs a bitwise logical-and of one
8450 operand with the bitwise negation of the other should specify the pattern
8451 for that instruction as
8452
8453 @smallexample
8454 (define_insn ""
8455 [(set (match_operand:@var{m} 0 @dots{})
8456 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8457 (match_operand:@var{m} 2 @dots{})))]
8458 "@dots{}"
8459 "@dots{}")
8460 @end smallexample
8461
8462 @noindent
8463 Similarly, a pattern for a ``NAND'' instruction should be written
8464
8465 @smallexample
8466 (define_insn ""
8467 [(set (match_operand:@var{m} 0 @dots{})
8468 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8469 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
8470 "@dots{}"
8471 "@dots{}")
8472 @end smallexample
8473
8474 In both cases, it is not necessary to include patterns for the many
8475 logically equivalent RTL expressions.
8476
8477 @cindex @code{xor}, canonicalization of
8478 @item
8479 The only possible RTL expressions involving both bitwise exclusive-or
8480 and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
8481 and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
8482
8483 @item
8484 The sum of three items, one of which is a constant, will only appear in
8485 the form
8486
8487 @smallexample
8488 (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
8489 @end smallexample
8490
8491 @cindex @code{zero_extract}, canonicalization of
8492 @cindex @code{sign_extract}, canonicalization of
8493 @item
8494 Equality comparisons of a group of bits (usually a single bit) with zero
8495 will be written using @code{zero_extract} rather than the equivalent
8496 @code{and} or @code{sign_extract} operations.
8497
8498 @cindex @code{mult}, canonicalization of
8499 @item
8500 @code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
8501 (sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
8502 (sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
8503 for @code{zero_extend}.
8504
8505 @item
8506 @code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
8507 @var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
8508 to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
8509 @var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
8510 patterns using @code{zero_extend} and @code{lshiftrt}. If the second
8511 operand of @code{mult} is also a shift, then that is extended also.
8512 This transformation is only applied when it can be proven that the
8513 original operation had sufficient precision to prevent overflow.
8514
8515 @end itemize
8516
8517 Further canonicalization rules are defined in the function
8518 @code{commutative_operand_precedence} in @file{gcc/rtlanal.cc}.
8519
8520 @end ifset
8521 @ifset INTERNALS
8522 @node Expander Definitions
8523 @section Defining RTL Sequences for Code Generation
8524 @cindex expander definitions
8525 @cindex code generation RTL sequences
8526 @cindex defining RTL sequences for code generation
8527
8528 On some target machines, some standard pattern names for RTL generation
8529 cannot be handled with single insn, but a sequence of RTL insns can
8530 represent them. For these target machines, you can write a
8531 @code{define_expand} to specify how to generate the sequence of RTL@.
8532
8533 @findex define_expand
8534 A @code{define_expand} is an RTL expression that looks almost like a
8535 @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
8536 only for RTL generation and it can produce more than one RTL insn.
8537
8538 A @code{define_expand} RTX has four operands:
8539
8540 @itemize @bullet
8541 @item
8542 The name. Each @code{define_expand} must have a name, since the only
8543 use for it is to refer to it by name.
8544
8545 @item
8546 The RTL template. This is a vector of RTL expressions representing
8547 a sequence of separate instructions. Unlike @code{define_insn}, there
8548 is no implicit surrounding @code{PARALLEL}.
8549
8550 @item
8551 The condition, a string containing a C expression. This expression is
8552 used to express how the availability of this pattern depends on
8553 subclasses of target machine, selected by command-line options when GCC
8554 is run. This is just like the condition of a @code{define_insn} that
8555 has a standard name. Therefore, the condition (if present) may not
8556 depend on the data in the insn being matched, but only the
8557 target-machine-type flags. The compiler needs to test these conditions
8558 during initialization in order to learn exactly which named instructions
8559 are available in a particular run.
8560
8561 @item
8562 The preparation statements, a string containing zero or more C
8563 statements which are to be executed before RTL code is generated from
8564 the RTL template.
8565
8566 Usually these statements prepare temporary registers for use as
8567 internal operands in the RTL template, but they can also generate RTL
8568 insns directly by calling routines such as @code{emit_insn}, etc.
8569 Any such insns precede the ones that come from the RTL template.
8570
8571 @item
8572 Optionally, a vector containing the values of attributes. @xref{Insn
8573 Attributes}.
8574 @end itemize
8575
8576 Every RTL insn emitted by a @code{define_expand} must match some
8577 @code{define_insn} in the machine description. Otherwise, the compiler
8578 will crash when trying to generate code for the insn or trying to optimize
8579 it.
8580
8581 The RTL template, in addition to controlling generation of RTL insns,
8582 also describes the operands that need to be specified when this pattern
8583 is used. In particular, it gives a predicate for each operand.
8584
8585 A true operand, which needs to be specified in order to generate RTL from
8586 the pattern, should be described with a @code{match_operand} in its first
8587 occurrence in the RTL template. This enters information on the operand's
8588 predicate into the tables that record such things. GCC uses the
8589 information to preload the operand into a register if that is required for
8590 valid RTL code. If the operand is referred to more than once, subsequent
8591 references should use @code{match_dup}.
8592
8593 The RTL template may also refer to internal ``operands'' which are
8594 temporary registers or labels used only within the sequence made by the
8595 @code{define_expand}. Internal operands are substituted into the RTL
8596 template with @code{match_dup}, never with @code{match_operand}. The
8597 values of the internal operands are not passed in as arguments by the
8598 compiler when it requests use of this pattern. Instead, they are computed
8599 within the pattern, in the preparation statements. These statements
8600 compute the values and store them into the appropriate elements of
8601 @code{operands} so that @code{match_dup} can find them.
8602
8603 There are two special macros defined for use in the preparation statements:
8604 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
8605 as a statement.
8606
8607 @table @code
8608
8609 @findex DONE
8610 @item DONE
8611 Use the @code{DONE} macro to end RTL generation for the pattern. The
8612 only RTL insns resulting from the pattern on this occasion will be
8613 those already emitted by explicit calls to @code{emit_insn} within the
8614 preparation statements; the RTL template will not be generated.
8615
8616 @findex FAIL
8617 @item FAIL
8618 Make the pattern fail on this occasion. When a pattern fails, it means
8619 that the pattern was not truly available. The calling routines in the
8620 compiler will try other strategies for code generation using other patterns.
8621
8622 Failure is currently supported only for binary (addition, multiplication,
8623 shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
8624 operations.
8625 @end table
8626
8627 If the preparation falls through (invokes neither @code{DONE} nor
8628 @code{FAIL}), then the @code{define_expand} acts like a
8629 @code{define_insn} in that the RTL template is used to generate the
8630 insn.
8631
8632 The RTL template is not used for matching, only for generating the
8633 initial insn list. If the preparation statement always invokes
8634 @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
8635 list of operands, such as this example:
8636
8637 @smallexample
8638 @group
8639 (define_expand "addsi3"
8640 [(match_operand:SI 0 "register_operand" "")
8641 (match_operand:SI 1 "register_operand" "")
8642 (match_operand:SI 2 "register_operand" "")]
8643 ""
8644 "
8645 @{
8646 handle_add (operands[0], operands[1], operands[2]);
8647 DONE;
8648 @}")
8649 @end group
8650 @end smallexample
8651
8652 Here is an example, the definition of left-shift for the SPUR chip:
8653
8654 @smallexample
8655 @group
8656 (define_expand "ashlsi3"
8657 [(set (match_operand:SI 0 "register_operand" "")
8658 (ashift:SI
8659 (match_operand:SI 1 "register_operand" "")
8660 (match_operand:SI 2 "nonmemory_operand" "")))]
8661 ""
8662 "
8663 @{
8664 if (GET_CODE (operands[2]) != CONST_INT
8665 || (unsigned) INTVAL (operands[2]) > 3)
8666 FAIL;
8667 @}")
8668 @end group
8669 @end smallexample
8670
8671 @noindent
8672 This example uses @code{define_expand} so that it can generate an RTL insn
8673 for shifting when the shift-count is in the supported range of 0 to 3 but
8674 fail in other cases where machine insns aren't available. When it fails,
8675 the compiler tries another strategy using different patterns (such as, a
8676 library call).
8677
8678 If the compiler were able to handle nontrivial condition-strings in
8679 patterns with names, then it would be possible to use a
8680 @code{define_insn} in that case. Here is another case (zero-extension
8681 on the 68000) which makes more use of the power of @code{define_expand}:
8682
8683 @smallexample
8684 (define_expand "zero_extendhisi2"
8685 [(set (match_operand:SI 0 "general_operand" "")
8686 (const_int 0))
8687 (set (strict_low_part
8688 (subreg:HI
8689 (match_dup 0)
8690 0))
8691 (match_operand:HI 1 "general_operand" ""))]
8692 ""
8693 "operands[1] = make_safe_from (operands[1], operands[0]);")
8694 @end smallexample
8695
8696 @noindent
8697 @findex make_safe_from
8698 Here two RTL insns are generated, one to clear the entire output operand
8699 and the other to copy the input operand into its low half. This sequence
8700 is incorrect if the input operand refers to [the old value of] the output
8701 operand, so the preparation statement makes sure this isn't so. The
8702 function @code{make_safe_from} copies the @code{operands[1]} into a
8703 temporary register if it refers to @code{operands[0]}. It does this
8704 by emitting another RTL insn.
8705
8706 Finally, a third example shows the use of an internal operand.
8707 Zero-extension on the SPUR chip is done by @code{and}-ing the result
8708 against a halfword mask. But this mask cannot be represented by a
8709 @code{const_int} because the constant value is too large to be legitimate
8710 on this machine. So it must be copied into a register with
8711 @code{force_reg} and then the register used in the @code{and}.
8712
8713 @smallexample
8714 (define_expand "zero_extendhisi2"
8715 [(set (match_operand:SI 0 "register_operand" "")
8716 (and:SI (subreg:SI
8717 (match_operand:HI 1 "register_operand" "")
8718 0)
8719 (match_dup 2)))]
8720 ""
8721 "operands[2]
8722 = force_reg (SImode, GEN_INT (65535)); ")
8723 @end smallexample
8724
8725 @emph{Note:} If the @code{define_expand} is used to serve a
8726 standard binary or unary arithmetic operation or a bit-field operation,
8727 then the last insn it generates must not be a @code{code_label},
8728 @code{barrier} or @code{note}. It must be an @code{insn},
8729 @code{jump_insn} or @code{call_insn}. If you don't need a real insn
8730 at the end, emit an insn to copy the result of the operation into
8731 itself. Such an insn will generate no code, but it can avoid problems
8732 in the compiler.
8733
8734 @end ifset
8735 @ifset INTERNALS
8736 @node Insn Splitting
8737 @section Defining How to Split Instructions
8738 @cindex insn splitting
8739 @cindex instruction splitting
8740 @cindex splitting instructions
8741
8742 There are two cases where you should specify how to split a pattern
8743 into multiple insns. On machines that have instructions requiring
8744 delay slots (@pxref{Delay Slots}) or that have instructions whose
8745 output is not available for multiple cycles (@pxref{Processor pipeline
8746 description}), the compiler phases that optimize these cases need to
8747 be able to move insns into one-instruction delay slots. However, some
8748 insns may generate more than one machine instruction. These insns
8749 cannot be placed into a delay slot.
8750
8751 Often you can rewrite the single insn as a list of individual insns,
8752 each corresponding to one machine instruction. The disadvantage of
8753 doing so is that it will cause the compilation to be slower and require
8754 more space. If the resulting insns are too complex, it may also
8755 suppress some optimizations. The compiler splits the insn if there is a
8756 reason to believe that it might improve instruction or delay slot
8757 scheduling.
8758
8759 The insn combiner phase also splits putative insns. If three insns are
8760 merged into one insn with a complex expression that cannot be matched by
8761 some @code{define_insn} pattern, the combiner phase attempts to split
8762 the complex pattern into two insns that are recognized. Usually it can
8763 break the complex pattern into two patterns by splitting out some
8764 subexpression. However, in some other cases, such as performing an
8765 addition of a large constant in two insns on a RISC machine, the way to
8766 split the addition into two insns is machine-dependent.
8767
8768 @findex define_split
8769 The @code{define_split} definition tells the compiler how to split a
8770 complex insn into several simpler insns. It looks like this:
8771
8772 @smallexample
8773 (define_split
8774 [@var{insn-pattern}]
8775 "@var{condition}"
8776 [@var{new-insn-pattern-1}
8777 @var{new-insn-pattern-2}
8778 @dots{}]
8779 "@var{preparation-statements}")
8780 @end smallexample
8781
8782 @var{insn-pattern} is a pattern that needs to be split and
8783 @var{condition} is the final condition to be tested, as in a
8784 @code{define_insn}. When an insn matching @var{insn-pattern} and
8785 satisfying @var{condition} is found, it is replaced in the insn list
8786 with the insns given by @var{new-insn-pattern-1},
8787 @var{new-insn-pattern-2}, etc.
8788
8789 The @var{preparation-statements} are similar to those statements that
8790 are specified for @code{define_expand} (@pxref{Expander Definitions})
8791 and are executed before the new RTL is generated to prepare for the
8792 generated code or emit some insns whose pattern is not fixed. Unlike
8793 those in @code{define_expand}, however, these statements must not
8794 generate any new pseudo-registers. Once reload has completed, they also
8795 must not allocate any space in the stack frame.
8796
8797 There are two special macros defined for use in the preparation statements:
8798 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
8799 as a statement.
8800
8801 @table @code
8802
8803 @findex DONE
8804 @item DONE
8805 Use the @code{DONE} macro to end RTL generation for the splitter. The
8806 only RTL insns generated as replacement for the matched input insn will
8807 be those already emitted by explicit calls to @code{emit_insn} within
8808 the preparation statements; the replacement pattern is not used.
8809
8810 @findex FAIL
8811 @item FAIL
8812 Make the @code{define_split} fail on this occasion. When a @code{define_split}
8813 fails, it means that the splitter was not truly available for the inputs
8814 it was given, and the input insn will not be split.
8815 @end table
8816
8817 If the preparation falls through (invokes neither @code{DONE} nor
8818 @code{FAIL}), then the @code{define_split} uses the replacement
8819 template.
8820
8821 Patterns are matched against @var{insn-pattern} in two different
8822 circumstances. If an insn needs to be split for delay slot scheduling
8823 or insn scheduling, the insn is already known to be valid, which means
8824 that it must have been matched by some @code{define_insn} and, if
8825 @code{reload_completed} is nonzero, is known to satisfy the constraints
8826 of that @code{define_insn}. In that case, the new insn patterns must
8827 also be insns that are matched by some @code{define_insn} and, if
8828 @code{reload_completed} is nonzero, must also satisfy the constraints
8829 of those definitions.
8830
8831 As an example of this usage of @code{define_split}, consider the following
8832 example from @file{a29k.md}, which splits a @code{sign_extend} from
8833 @code{HImode} to @code{SImode} into a pair of shift insns:
8834
8835 @smallexample
8836 (define_split
8837 [(set (match_operand:SI 0 "gen_reg_operand" "")
8838 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
8839 ""
8840 [(set (match_dup 0)
8841 (ashift:SI (match_dup 1)
8842 (const_int 16)))
8843 (set (match_dup 0)
8844 (ashiftrt:SI (match_dup 0)
8845 (const_int 16)))]
8846 "
8847 @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
8848 @end smallexample
8849
8850 When the combiner phase tries to split an insn pattern, it is always the
8851 case that the pattern is @emph{not} matched by any @code{define_insn}.
8852 The combiner pass first tries to split a single @code{set} expression
8853 and then the same @code{set} expression inside a @code{parallel}, but
8854 followed by a @code{clobber} of a pseudo-reg to use as a scratch
8855 register. In these cases, the combiner expects exactly one or two new insn
8856 patterns to be generated. It will verify that these patterns match some
8857 @code{define_insn} definitions, so you need not do this test in the
8858 @code{define_split} (of course, there is no point in writing a
8859 @code{define_split} that will never produce insns that match).
8860
8861 Here is an example of this use of @code{define_split}, taken from
8862 @file{rs6000.md}:
8863
8864 @smallexample
8865 (define_split
8866 [(set (match_operand:SI 0 "gen_reg_operand" "")
8867 (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
8868 (match_operand:SI 2 "non_add_cint_operand" "")))]
8869 ""
8870 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
8871 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
8872 "
8873 @{
8874 int low = INTVAL (operands[2]) & 0xffff;
8875 int high = (unsigned) INTVAL (operands[2]) >> 16;
8876
8877 if (low & 0x8000)
8878 high++, low |= 0xffff0000;
8879
8880 operands[3] = GEN_INT (high << 16);
8881 operands[4] = GEN_INT (low);
8882 @}")
8883 @end smallexample
8884
8885 Here the predicate @code{non_add_cint_operand} matches any
8886 @code{const_int} that is @emph{not} a valid operand of a single add
8887 insn. The add with the smaller displacement is written so that it
8888 can be substituted into the address of a subsequent operation.
8889
8890 An example that uses a scratch register, from the same file, generates
8891 an equality comparison of a register and a large constant:
8892
8893 @smallexample
8894 (define_split
8895 [(set (match_operand:CC 0 "cc_reg_operand" "")
8896 (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
8897 (match_operand:SI 2 "non_short_cint_operand" "")))
8898 (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
8899 "find_single_use (operands[0], insn, 0)
8900 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
8901 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
8902 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
8903 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
8904 "
8905 @{
8906 /* @r{Get the constant we are comparing against, C, and see what it
8907 looks like sign-extended to 16 bits. Then see what constant
8908 could be XOR'ed with C to get the sign-extended value.} */
8909
8910 int c = INTVAL (operands[2]);
8911 int sextc = (c << 16) >> 16;
8912 int xorv = c ^ sextc;
8913
8914 operands[4] = GEN_INT (xorv);
8915 operands[5] = GEN_INT (sextc);
8916 @}")
8917 @end smallexample
8918
8919 To avoid confusion, don't write a single @code{define_split} that
8920 accepts some insns that match some @code{define_insn} as well as some
8921 insns that don't. Instead, write two separate @code{define_split}
8922 definitions, one for the insns that are valid and one for the insns that
8923 are not valid.
8924
8925 The splitter is allowed to split jump instructions into sequence of
8926 jumps or create new jumps in while splitting non-jump instructions. As
8927 the control flow graph and branch prediction information needs to be updated,
8928 several restriction apply.
8929
8930 Splitting of jump instruction into sequence that over by another jump
8931 instruction is always valid, as compiler expect identical behavior of new
8932 jump. When new sequence contains multiple jump instructions or new labels,
8933 more assistance is needed. Splitter is required to create only unconditional
8934 jumps, or simple conditional jump instructions. Additionally it must attach a
8935 @code{REG_BR_PROB} note to each conditional jump. A global variable
8936 @code{split_branch_probability} holds the probability of the original branch in case
8937 it was a simple conditional jump, @minus{}1 otherwise. To simplify
8938 recomputing of edge frequencies, the new sequence is required to have only
8939 forward jumps to the newly created labels.
8940
8941 @findex define_insn_and_split
8942 For the common case where the pattern of a define_split exactly matches the
8943 pattern of a define_insn, use @code{define_insn_and_split}. It looks like
8944 this:
8945
8946 @smallexample
8947 (define_insn_and_split
8948 [@var{insn-pattern}]
8949 "@var{condition}"
8950 "@var{output-template}"
8951 "@var{split-condition}"
8952 [@var{new-insn-pattern-1}
8953 @var{new-insn-pattern-2}
8954 @dots{}]
8955 "@var{preparation-statements}"
8956 [@var{insn-attributes}])
8957
8958 @end smallexample
8959
8960 @var{insn-pattern}, @var{condition}, @var{output-template}, and
8961 @var{insn-attributes} are used as in @code{define_insn}. The
8962 @var{new-insn-pattern} vector and the @var{preparation-statements} are used as
8963 in a @code{define_split}. The @var{split-condition} is also used as in
8964 @code{define_split}, with the additional behavior that if the condition starts
8965 with @samp{&&}, the condition used for the split will be the constructed as a
8966 logical ``and'' of the split condition with the insn condition. For example,
8967 from i386.md:
8968
8969 @smallexample
8970 (define_insn_and_split "zero_extendhisi2_and"
8971 [(set (match_operand:SI 0 "register_operand" "=r")
8972 (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
8973 (clobber (reg:CC 17))]
8974 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
8975 "#"
8976 "&& reload_completed"
8977 [(parallel [(set (match_dup 0)
8978 (and:SI (match_dup 0) (const_int 65535)))
8979 (clobber (reg:CC 17))])]
8980 ""
8981 [(set_attr "type" "alu1")])
8982
8983 @end smallexample
8984
8985 In this case, the actual split condition will be
8986 @samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
8987
8988 The @code{define_insn_and_split} construction provides exactly the same
8989 functionality as two separate @code{define_insn} and @code{define_split}
8990 patterns. It exists for compactness, and as a maintenance tool to prevent
8991 having to ensure the two patterns' templates match.
8992
8993 @findex define_insn_and_rewrite
8994 It is sometimes useful to have a @code{define_insn_and_split}
8995 that replaces specific operands of an instruction but leaves the
8996 rest of the instruction pattern unchanged. You can do this directly
8997 with a @code{define_insn_and_split}, but it requires a
8998 @var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}.
8999 There is also the complication that an implicit @code{parallel} in
9000 @var{insn-pattern} must become an explicit @code{parallel} in
9001 @var{new-insn-pattern-1}, which is easy to overlook.
9002 A simpler alternative is to use @code{define_insn_and_rewrite}, which
9003 is a form of @code{define_insn_and_split} that automatically generates
9004 @var{new-insn-pattern-1} by replacing each @code{match_operand}
9005 in @var{insn-pattern} with a corresponding @code{match_dup}, and each
9006 @code{match_operator} in the pattern with a corresponding @code{match_op_dup}.
9007 The arguments are otherwise identical to @code{define_insn_and_split}:
9008
9009 @smallexample
9010 (define_insn_and_rewrite
9011 [@var{insn-pattern}]
9012 "@var{condition}"
9013 "@var{output-template}"
9014 "@var{split-condition}"
9015 "@var{preparation-statements}"
9016 [@var{insn-attributes}])
9017 @end smallexample
9018
9019 The @code{match_dup}s and @code{match_op_dup}s in the new
9020 instruction pattern use any new operand values that the
9021 @var{preparation-statements} store in the @code{operands} array,
9022 as for a normal @code{define_insn_and_split}. @var{preparation-statements}
9023 can also emit additional instructions before the new instruction.
9024 They can even emit an entirely different sequence of instructions and
9025 use @code{DONE} to avoid emitting a new form of the original
9026 instruction.
9027
9028 The split in a @code{define_insn_and_rewrite} is only intended
9029 to apply to existing instructions that match @var{insn-pattern}.
9030 @var{split-condition} must therefore start with @code{&&},
9031 so that the split condition applies on top of @var{condition}.
9032
9033 Here is an example from the AArch64 SVE port, in which operand 1 is
9034 known to be equivalent to an all-true constant and isn't used by the
9035 output template:
9036
9037 @smallexample
9038 (define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
9039 [(set (reg:CC CC_REGNUM)
9040 (compare:CC
9041 (unspec:SI [(match_operand:PRED_ALL 1)
9042 (unspec:PRED_ALL
9043 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
9044 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
9045 UNSPEC_WHILE_LO)]
9046 UNSPEC_PTEST_PTRUE)
9047 (const_int 0)))
9048 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
9049 (unspec:PRED_ALL [(match_dup 2)
9050 (match_dup 3)]
9051 UNSPEC_WHILE_LO))]
9052 "TARGET_SVE"
9053 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
9054 ;; Force the compiler to drop the unused predicate operand, so that we
9055 ;; don't have an unnecessary PTRUE.
9056 "&& !CONSTANT_P (operands[1])"
9057 @{
9058 operands[1] = CONSTM1_RTX (<MODE>mode);
9059 @}
9060 )
9061 @end smallexample
9062
9063 The splitter in this case simply replaces operand 1 with the constant
9064 value that it is known to have. The equivalent @code{define_insn_and_split}
9065 would be:
9066
9067 @smallexample
9068 (define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
9069 [(set (reg:CC CC_REGNUM)
9070 (compare:CC
9071 (unspec:SI [(match_operand:PRED_ALL 1)
9072 (unspec:PRED_ALL
9073 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
9074 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
9075 UNSPEC_WHILE_LO)]
9076 UNSPEC_PTEST_PTRUE)
9077 (const_int 0)))
9078 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
9079 (unspec:PRED_ALL [(match_dup 2)
9080 (match_dup 3)]
9081 UNSPEC_WHILE_LO))]
9082 "TARGET_SVE"
9083 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
9084 ;; Force the compiler to drop the unused predicate operand, so that we
9085 ;; don't have an unnecessary PTRUE.
9086 "&& !CONSTANT_P (operands[1])"
9087 [(parallel
9088 [(set (reg:CC CC_REGNUM)
9089 (compare:CC
9090 (unspec:SI [(match_dup 1)
9091 (unspec:PRED_ALL [(match_dup 2)
9092 (match_dup 3)]
9093 UNSPEC_WHILE_LO)]
9094 UNSPEC_PTEST_PTRUE)
9095 (const_int 0)))
9096 (set (match_dup 0)
9097 (unspec:PRED_ALL [(match_dup 2)
9098 (match_dup 3)]
9099 UNSPEC_WHILE_LO))])]
9100 @{
9101 operands[1] = CONSTM1_RTX (<MODE>mode);
9102 @}
9103 )
9104 @end smallexample
9105
9106 @end ifset
9107 @ifset INTERNALS
9108 @node Including Patterns
9109 @section Including Patterns in Machine Descriptions.
9110 @cindex insn includes
9111
9112 @findex include
9113 The @code{include} pattern tells the compiler tools where to
9114 look for patterns that are in files other than in the file
9115 @file{.md}. This is used only at build time and there is no preprocessing allowed.
9116
9117 It looks like:
9118
9119 @smallexample
9120
9121 (include
9122 @var{pathname})
9123 @end smallexample
9124
9125 For example:
9126
9127 @smallexample
9128
9129 (include "filestuff")
9130
9131 @end smallexample
9132
9133 Where @var{pathname} is a string that specifies the location of the file,
9134 specifies the include file to be in @file{gcc/config/target/filestuff}. The
9135 directory @file{gcc/config/target} is regarded as the default directory.
9136
9137
9138 Machine descriptions may be split up into smaller more manageable subsections
9139 and placed into subdirectories.
9140
9141 By specifying:
9142
9143 @smallexample
9144
9145 (include "BOGUS/filestuff")
9146
9147 @end smallexample
9148
9149 the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.
9150
9151 Specifying an absolute path for the include file such as;
9152 @smallexample
9153
9154 (include "/u2/BOGUS/filestuff")
9155
9156 @end smallexample
9157 is permitted but is not encouraged.
9158
9159 @subsection RTL Generation Tool Options for Directory Search
9160 @cindex directory options .md
9161 @cindex options, directory search
9162 @cindex search options
9163
9164 The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
9165 For example:
9166
9167 @smallexample
9168
9169 genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
9170
9171 @end smallexample
9172
9173
9174 Add the directory @var{dir} to the head of the list of directories to be
9175 searched for header files. This can be used to override a system machine definition
9176 file, substituting your own version, since these directories are
9177 searched before the default machine description file directories. If you use more than
9178 one @option{-I} option, the directories are scanned in left-to-right
9179 order; the standard default directory come after.
9180
9181
9182 @end ifset
9183 @ifset INTERNALS
9184 @node Peephole Definitions
9185 @section Machine-Specific Peephole Optimizers
9186 @cindex peephole optimizer definitions
9187 @cindex defining peephole optimizers
9188
9189 In addition to instruction patterns the @file{md} file may contain
9190 definitions of machine-specific peephole optimizations.
9191
9192 The combiner does not notice certain peephole optimizations when the data
9193 flow in the program does not suggest that it should try them. For example,
9194 sometimes two consecutive insns related in purpose can be combined even
9195 though the second one does not appear to use a register computed in the
9196 first one. A machine-specific peephole optimizer can detect such
9197 opportunities.
9198
9199 There are two forms of peephole definitions that may be used. The
9200 original @code{define_peephole} is run at assembly output time to
9201 match insns and substitute assembly text. Use of @code{define_peephole}
9202 is deprecated.
9203
9204 A newer @code{define_peephole2} matches insns and substitutes new
9205 insns. The @code{peephole2} pass is run after register allocation
9206 but before scheduling, which may result in much better code for
9207 targets that do scheduling.
9208
9209 @menu
9210 * define_peephole:: RTL to Text Peephole Optimizers
9211 * define_peephole2:: RTL to RTL Peephole Optimizers
9212 @end menu
9213
9214 @end ifset
9215 @ifset INTERNALS
9216 @node define_peephole
9217 @subsection RTL to Text Peephole Optimizers
9218 @findex define_peephole
9219
9220 @need 1000
9221 A definition looks like this:
9222
9223 @smallexample
9224 (define_peephole
9225 [@var{insn-pattern-1}
9226 @var{insn-pattern-2}
9227 @dots{}]
9228 "@var{condition}"
9229 "@var{template}"
9230 "@var{optional-insn-attributes}")
9231 @end smallexample
9232
9233 @noindent
9234 The last string operand may be omitted if you are not using any
9235 machine-specific information in this machine description. If present,
9236 it must obey the same rules as in a @code{define_insn}.
9237
9238 In this skeleton, @var{insn-pattern-1} and so on are patterns to match
9239 consecutive insns. The optimization applies to a sequence of insns when
9240 @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
9241 the next, and so on.
9242
9243 Each of the insns matched by a peephole must also match a
9244 @code{define_insn}. Peepholes are checked only at the last stage just
9245 before code generation, and only optionally. Therefore, any insn which
9246 would match a peephole but no @code{define_insn} will cause a crash in code
9247 generation in an unoptimized compilation, or at various optimization
9248 stages.
9249
9250 The operands of the insns are matched with @code{match_operands},
9251 @code{match_operator}, and @code{match_dup}, as usual. What is not
9252 usual is that the operand numbers apply to all the insn patterns in the
9253 definition. So, you can check for identical operands in two insns by
9254 using @code{match_operand} in one insn and @code{match_dup} in the
9255 other.
9256
9257 The operand constraints used in @code{match_operand} patterns do not have
9258 any direct effect on the applicability of the peephole, but they will
9259 be validated afterward, so make sure your constraints are general enough
9260 to apply whenever the peephole matches. If the peephole matches
9261 but the constraints are not satisfied, the compiler will crash.
9262
9263 It is safe to omit constraints in all the operands of the peephole; or
9264 you can write constraints which serve as a double-check on the criteria
9265 previously tested.
9266
9267 Once a sequence of insns matches the patterns, the @var{condition} is
9268 checked. This is a C expression which makes the final decision whether to
9269 perform the optimization (we do so if the expression is nonzero). If
9270 @var{condition} is omitted (in other words, the string is empty) then the
9271 optimization is applied to every sequence of insns that matches the
9272 patterns.
9273
9274 The defined peephole optimizations are applied after register allocation
9275 is complete. Therefore, the peephole definition can check which
9276 operands have ended up in which kinds of registers, just by looking at
9277 the operands.
9278
9279 @findex prev_active_insn
9280 The way to refer to the operands in @var{condition} is to write
9281 @code{operands[@var{i}]} for operand number @var{i} (as matched by
9282 @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn}
9283 to refer to the last of the insns being matched; use
9284 @code{prev_active_insn} to find the preceding insns.
9285
9286 @findex dead_or_set_p
9287 When optimizing computations with intermediate results, you can use
9288 @var{condition} to match only when the intermediate results are not used
9289 elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
9290 @var{op})}, where @var{insn} is the insn in which you expect the value
9291 to be used for the last time (from the value of @code{insn}, together
9292 with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
9293 value (from @code{operands[@var{i}]}).
9294
9295 Applying the optimization means replacing the sequence of insns with one
9296 new insn. The @var{template} controls ultimate output of assembler code
9297 for this combined insn. It works exactly like the template of a
9298 @code{define_insn}. Operand numbers in this template are the same ones
9299 used in matching the original sequence of insns.
9300
9301 The result of a defined peephole optimizer does not need to match any of
9302 the insn patterns in the machine description; it does not even have an
9303 opportunity to match them. The peephole optimizer definition itself serves
9304 as the insn pattern to control how the insn is output.
9305
9306 Defined peephole optimizers are run as assembler code is being output,
9307 so the insns they produce are never combined or rearranged in any way.
9308
9309 Here is an example, taken from the 68000 machine description:
9310
9311 @smallexample
9312 (define_peephole
9313 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
9314 (set (match_operand:DF 0 "register_operand" "=f")
9315 (match_operand:DF 1 "register_operand" "ad"))]
9316 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
9317 @{
9318 rtx xoperands[2];
9319 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
9320 #ifdef MOTOROLA
9321 output_asm_insn ("move.l %1,(sp)", xoperands);
9322 output_asm_insn ("move.l %1,-(sp)", operands);
9323 return "fmove.d (sp)+,%0";
9324 #else
9325 output_asm_insn ("movel %1,sp@@", xoperands);
9326 output_asm_insn ("movel %1,sp@@-", operands);
9327 return "fmoved sp@@+,%0";
9328 #endif
9329 @})
9330 @end smallexample
9331
9332 @need 1000
9333 The effect of this optimization is to change
9334
9335 @smallexample
9336 @group
9337 jbsr _foobar
9338 addql #4,sp
9339 movel d1,sp@@-
9340 movel d0,sp@@-
9341 fmoved sp@@+,fp0
9342 @end group
9343 @end smallexample
9344
9345 @noindent
9346 into
9347
9348 @smallexample
9349 @group
9350 jbsr _foobar
9351 movel d1,sp@@
9352 movel d0,sp@@-
9353 fmoved sp@@+,fp0
9354 @end group
9355 @end smallexample
9356
9357 @ignore
9358 @findex CC_REVERSED
9359 If a peephole matches a sequence including one or more jump insns, you must
9360 take account of the flags such as @code{CC_REVERSED} which specify that the
9361 condition codes are represented in an unusual manner. The compiler
9362 automatically alters any ordinary conditional jumps which occur in such
9363 situations, but the compiler cannot alter jumps which have been replaced by
9364 peephole optimizations. So it is up to you to alter the assembler code
9365 that the peephole produces. Supply C code to write the assembler output,
9366 and in this C code check the condition code status flags and change the
9367 assembler code as appropriate.
9368 @end ignore
9369
9370 @var{insn-pattern-1} and so on look @emph{almost} like the second
9371 operand of @code{define_insn}. There is one important difference: the
9372 second operand of @code{define_insn} consists of one or more RTX's
9373 enclosed in square brackets. Usually, there is only one: then the same
9374 action can be written as an element of a @code{define_peephole}. But
9375 when there are multiple actions in a @code{define_insn}, they are
9376 implicitly enclosed in a @code{parallel}. Then you must explicitly
9377 write the @code{parallel}, and the square brackets within it, in the
9378 @code{define_peephole}. Thus, if an insn pattern looks like this,
9379
9380 @smallexample
9381 (define_insn "divmodsi4"
9382 [(set (match_operand:SI 0 "general_operand" "=d")
9383 (div:SI (match_operand:SI 1 "general_operand" "0")
9384 (match_operand:SI 2 "general_operand" "dmsK")))
9385 (set (match_operand:SI 3 "general_operand" "=d")
9386 (mod:SI (match_dup 1) (match_dup 2)))]
9387 "TARGET_68020"
9388 "divsl%.l %2,%3:%0")
9389 @end smallexample
9390
9391 @noindent
9392 then the way to mention this insn in a peephole is as follows:
9393
9394 @smallexample
9395 (define_peephole
9396 [@dots{}
9397 (parallel
9398 [(set (match_operand:SI 0 "general_operand" "=d")
9399 (div:SI (match_operand:SI 1 "general_operand" "0")
9400 (match_operand:SI 2 "general_operand" "dmsK")))
9401 (set (match_operand:SI 3 "general_operand" "=d")
9402 (mod:SI (match_dup 1) (match_dup 2)))])
9403 @dots{}]
9404 @dots{})
9405 @end smallexample
9406
9407 @end ifset
9408 @ifset INTERNALS
9409 @node define_peephole2
9410 @subsection RTL to RTL Peephole Optimizers
9411 @findex define_peephole2
9412
9413 The @code{define_peephole2} definition tells the compiler how to
9414 substitute one sequence of instructions for another sequence,
9415 what additional scratch registers may be needed and what their
9416 lifetimes must be.
9417
9418 @smallexample
9419 (define_peephole2
9420 [@var{insn-pattern-1}
9421 @var{insn-pattern-2}
9422 @dots{}]
9423 "@var{condition}"
9424 [@var{new-insn-pattern-1}
9425 @var{new-insn-pattern-2}
9426 @dots{}]
9427 "@var{preparation-statements}")
9428 @end smallexample
9429
9430 The definition is almost identical to @code{define_split}
9431 (@pxref{Insn Splitting}) except that the pattern to match is not a
9432 single instruction, but a sequence of instructions.
9433
9434 It is possible to request additional scratch registers for use in the
9435 output template. If appropriate registers are not free, the pattern
9436 will simply not match.
9437
9438 @findex match_scratch
9439 @findex match_dup
9440 Scratch registers are requested with a @code{match_scratch} pattern at
9441 the top level of the input pattern. The allocated register (initially) will
9442 be dead at the point requested within the original sequence. If the scratch
9443 is used at more than a single point, a @code{match_dup} pattern at the
9444 top level of the input pattern marks the last position in the input sequence
9445 at which the register must be available.
9446
9447 Here is an example from the IA-32 machine description:
9448
9449 @smallexample
9450 (define_peephole2
9451 [(match_scratch:SI 2 "r")
9452 (parallel [(set (match_operand:SI 0 "register_operand" "")
9453 (match_operator:SI 3 "arith_or_logical_operator"
9454 [(match_dup 0)
9455 (match_operand:SI 1 "memory_operand" "")]))
9456 (clobber (reg:CC 17))])]
9457 "! optimize_size && ! TARGET_READ_MODIFY"
9458 [(set (match_dup 2) (match_dup 1))
9459 (parallel [(set (match_dup 0)
9460 (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
9461 (clobber (reg:CC 17))])]
9462 "")
9463 @end smallexample
9464
9465 @noindent
9466 This pattern tries to split a load from its use in the hopes that we'll be
9467 able to schedule around the memory load latency. It allocates a single
9468 @code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
9469 to be live only at the point just before the arithmetic.
9470
9471 A real example requiring extended scratch lifetimes is harder to come by,
9472 so here's a silly made-up example:
9473
9474 @smallexample
9475 (define_peephole2
9476 [(match_scratch:SI 4 "r")
9477 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
9478 (set (match_operand:SI 2 "" "") (match_dup 1))
9479 (match_dup 4)
9480 (set (match_operand:SI 3 "" "") (match_dup 1))]
9481 "/* @r{determine 1 does not overlap 0 and 2} */"
9482 [(set (match_dup 4) (match_dup 1))
9483 (set (match_dup 0) (match_dup 4))
9484 (set (match_dup 2) (match_dup 4))
9485 (set (match_dup 3) (match_dup 4))]
9486 "")
9487 @end smallexample
9488
9489 There are two special macros defined for use in the preparation statements:
9490 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
9491 as a statement.
9492
9493 @table @code
9494
9495 @findex DONE
9496 @item DONE
9497 Use the @code{DONE} macro to end RTL generation for the peephole. The
9498 only RTL insns generated as replacement for the matched input insn will
9499 be those already emitted by explicit calls to @code{emit_insn} within
9500 the preparation statements; the replacement pattern is not used.
9501
9502 @findex FAIL
9503 @item FAIL
9504 Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2}
9505 fails, it means that the replacement was not truly available for the
9506 particular inputs it was given. In that case, GCC may still apply a
9507 later @code{define_peephole2} that also matches the given insn pattern.
9508 (Note that this is different from @code{define_split}, where @code{FAIL}
9509 prevents the input insn from being split at all.)
9510 @end table
9511
9512 If the preparation falls through (invokes neither @code{DONE} nor
9513 @code{FAIL}), then the @code{define_peephole2} uses the replacement
9514 template.
9515
9516 @noindent
9517 If we had not added the @code{(match_dup 4)} in the middle of the input
9518 sequence, it might have been the case that the register we chose at the
9519 beginning of the sequence is killed by the first or second @code{set}.
9520
9521 @end ifset
9522 @ifset INTERNALS
9523 @node Insn Attributes
9524 @section Instruction Attributes
9525 @cindex insn attributes
9526 @cindex instruction attributes
9527
9528 In addition to describing the instruction supported by the target machine,
9529 the @file{md} file also defines a group of @dfn{attributes} and a set of
9530 values for each. Every generated insn is assigned a value for each attribute.
9531 One possible attribute would be the effect that the insn has on the machine's
9532 condition code.
9533
9534 @menu
9535 * Defining Attributes:: Specifying attributes and their values.
9536 * Expressions:: Valid expressions for attribute values.
9537 * Tagging Insns:: Assigning attribute values to insns.
9538 * Attr Example:: An example of assigning attributes.
9539 * Insn Lengths:: Computing the length of insns.
9540 * Constant Attributes:: Defining attributes that are constant.
9541 * Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value.
9542 * Delay Slots:: Defining delay slots required for a machine.
9543 * Processor pipeline description:: Specifying information for insn scheduling.
9544 @end menu
9545
9546 @end ifset
9547 @ifset INTERNALS
9548 @node Defining Attributes
9549 @subsection Defining Attributes and their Values
9550 @cindex defining attributes and their values
9551 @cindex attributes, defining
9552
9553 @findex define_attr
9554 The @code{define_attr} expression is used to define each attribute required
9555 by the target machine. It looks like:
9556
9557 @smallexample
9558 (define_attr @var{name} @var{list-of-values} @var{default})
9559 @end smallexample
9560
9561 @var{name} is a string specifying the name of the attribute being
9562 defined. Some attributes are used in a special way by the rest of the
9563 compiler. The @code{enabled} attribute can be used to conditionally
9564 enable or disable insn alternatives (@pxref{Disable Insn
9565 Alternatives}). The @code{predicable} attribute, together with a
9566 suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can
9567 be used to automatically generate conditional variants of instruction
9568 patterns. The @code{mnemonic} attribute can be used to check for the
9569 instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler
9570 internally uses the names @code{ce_enabled} and @code{nonce_enabled},
9571 so they should not be used elsewhere as alternative names.
9572
9573 @var{list-of-values} is either a string that specifies a comma-separated
9574 list of values that can be assigned to the attribute, or a null string to
9575 indicate that the attribute takes numeric values.
9576
9577 @var{default} is an attribute expression that gives the value of this
9578 attribute for insns that match patterns whose definition does not include
9579 an explicit value for this attribute. @xref{Attr Example}, for more
9580 information on the handling of defaults. @xref{Constant Attributes},
9581 for information on attributes that do not depend on any particular insn.
9582
9583 @findex insn-attr.h
9584 For each defined attribute, a number of definitions are written to the
9585 @file{insn-attr.h} file. For cases where an explicit set of values is
9586 specified for an attribute, the following are defined:
9587
9588 @itemize @bullet
9589 @item
9590 A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
9591
9592 @item
9593 An enumerated class is defined for @samp{attr_@var{name}} with
9594 elements of the form @samp{@var{upper-name}_@var{upper-value}} where
9595 the attribute name and value are first converted to uppercase.
9596
9597 @item
9598 A function @samp{get_attr_@var{name}} is defined that is passed an insn and
9599 returns the attribute value for that insn.
9600 @end itemize
9601
9602 For example, if the following is present in the @file{md} file:
9603
9604 @smallexample
9605 (define_attr "type" "branch,fp,load,store,arith" @dots{})
9606 @end smallexample
9607
9608 @noindent
9609 the following lines will be written to the file @file{insn-attr.h}.
9610
9611 @smallexample
9612 #define HAVE_ATTR_type 1
9613 enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
9614 TYPE_STORE, TYPE_ARITH@};
9615 extern enum attr_type get_attr_type ();
9616 @end smallexample
9617
9618 If the attribute takes numeric values, no @code{enum} type will be
9619 defined and the function to obtain the attribute's value will return
9620 @code{int}.
9621
9622 There are attributes which are tied to a specific meaning. These
9623 attributes are not free to use for other purposes:
9624
9625 @table @code
9626 @item length
9627 The @code{length} attribute is used to calculate the length of emitted
9628 code chunks. This is especially important when verifying branch
9629 distances. @xref{Insn Lengths}.
9630
9631 @item enabled
9632 The @code{enabled} attribute can be defined to prevent certain
9633 alternatives of an insn definition from being used during code
9634 generation. @xref{Disable Insn Alternatives}.
9635
9636 @item mnemonic
9637 The @code{mnemonic} attribute can be defined to implement instruction
9638 specific checks in e.g.@: the pipeline description.
9639 @xref{Mnemonic Attribute}.
9640 @end table
9641
9642 For each of these special attributes, the corresponding
9643 @samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the
9644 attribute is not defined; in that case, it is defined as @samp{0}.
9645
9646 @findex define_enum_attr
9647 @anchor{define_enum_attr}
9648 Another way of defining an attribute is to use:
9649
9650 @smallexample
9651 (define_enum_attr "@var{attr}" "@var{enum}" @var{default})
9652 @end smallexample
9653
9654 This works in just the same way as @code{define_attr}, except that
9655 the list of values is taken from a separate enumeration called
9656 @var{enum} (@pxref{define_enum}). This form allows you to use
9657 the same list of values for several attributes without having to
9658 repeat the list each time. For example:
9659
9660 @smallexample
9661 (define_enum "processor" [
9662 model_a
9663 model_b
9664 @dots{}
9665 ])
9666 (define_enum_attr "arch" "processor"
9667 (const (symbol_ref "target_arch")))
9668 (define_enum_attr "tune" "processor"
9669 (const (symbol_ref "target_tune")))
9670 @end smallexample
9671
9672 defines the same attributes as:
9673
9674 @smallexample
9675 (define_attr "arch" "model_a,model_b,@dots{}"
9676 (const (symbol_ref "target_arch")))
9677 (define_attr "tune" "model_a,model_b,@dots{}"
9678 (const (symbol_ref "target_tune")))
9679 @end smallexample
9680
9681 but without duplicating the processor list. The second example defines two
9682 separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
9683 defines a single C enum (@code{processor}).
9684 @end ifset
9685 @ifset INTERNALS
9686 @node Expressions
9687 @subsection Attribute Expressions
9688 @cindex attribute expressions
9689
9690 RTL expressions used to define attributes use the codes described above
9691 plus a few specific to attribute definitions, to be discussed below.
9692 Attribute value expressions must have one of the following forms:
9693
9694 @table @code
9695 @cindex @code{const_int} and attributes
9696 @item (const_int @var{i})
9697 The integer @var{i} specifies the value of a numeric attribute. @var{i}
9698 must be non-negative.
9699
9700 The value of a numeric attribute can be specified either with a
9701 @code{const_int}, or as an integer represented as a string in
9702 @code{const_string}, @code{eq_attr} (see below), @code{attr},
9703 @code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
9704 overrides on specific instructions (@pxref{Tagging Insns}).
9705
9706 @cindex @code{const_string} and attributes
9707 @item (const_string @var{value})
9708 The string @var{value} specifies a constant attribute value.
9709 If @var{value} is specified as @samp{"*"}, it means that the default value of
9710 the attribute is to be used for the insn containing this expression.
9711 @samp{"*"} obviously cannot be used in the @var{default} expression
9712 of a @code{define_attr}.
9713
9714 If the attribute whose value is being specified is numeric, @var{value}
9715 must be a string containing a non-negative integer (normally
9716 @code{const_int} would be used in this case). Otherwise, it must
9717 contain one of the valid values for the attribute.
9718
9719 @cindex @code{if_then_else} and attributes
9720 @item (if_then_else @var{test} @var{true-value} @var{false-value})
9721 @var{test} specifies an attribute test, whose format is defined below.
9722 The value of this expression is @var{true-value} if @var{test} is true,
9723 otherwise it is @var{false-value}.
9724
9725 @cindex @code{cond} and attributes
9726 @item (cond [@var{test1} @var{value1} @dots{}] @var{default})
9727 The first operand of this expression is a vector containing an even
9728 number of expressions and consisting of pairs of @var{test} and @var{value}
9729 expressions. The value of the @code{cond} expression is that of the
9730 @var{value} corresponding to the first true @var{test} expression. If
9731 none of the @var{test} expressions are true, the value of the @code{cond}
9732 expression is that of the @var{default} expression.
9733 @end table
9734
9735 @var{test} expressions can have one of the following forms:
9736
9737 @table @code
9738 @cindex @code{const_int} and attribute tests
9739 @item (const_int @var{i})
9740 This test is true if @var{i} is nonzero and false otherwise.
9741
9742 @cindex @code{not} and attributes
9743 @cindex @code{ior} and attributes
9744 @cindex @code{and} and attributes
9745 @item (not @var{test})
9746 @itemx (ior @var{test1} @var{test2})
9747 @itemx (and @var{test1} @var{test2})
9748 These tests are true if the indicated logical function is true.
9749
9750 @cindex @code{match_operand} and attributes
9751 @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
9752 This test is true if operand @var{n} of the insn whose attribute value
9753 is being determined has mode @var{m} (this part of the test is ignored
9754 if @var{m} is @code{VOIDmode}) and the function specified by the string
9755 @var{pred} returns a nonzero value when passed operand @var{n} and mode
9756 @var{m} (this part of the test is ignored if @var{pred} is the null
9757 string).
9758
9759 The @var{constraints} operand is ignored and should be the null string.
9760
9761 @cindex @code{match_test} and attributes
9762 @item (match_test @var{c-expr})
9763 The test is true if C expression @var{c-expr} is true. In non-constant
9764 attributes, @var{c-expr} has access to the following variables:
9765
9766 @table @var
9767 @item insn
9768 The rtl instruction under test.
9769 @item which_alternative
9770 The @code{define_insn} alternative that @var{insn} matches.
9771 @xref{Output Statement}.
9772 @item operands
9773 An array of @var{insn}'s rtl operands.
9774 @end table
9775
9776 @var{c-expr} behaves like the condition in a C @code{if} statement,
9777 so there is no need to explicitly convert the expression into a boolean
9778 0 or 1 value. For example, the following two tests are equivalent:
9779
9780 @smallexample
9781 (match_test "x & 2")
9782 (match_test "(x & 2) != 0")
9783 @end smallexample
9784
9785 @cindex @code{le} and attributes
9786 @cindex @code{leu} and attributes
9787 @cindex @code{lt} and attributes
9788 @cindex @code{gt} and attributes
9789 @cindex @code{gtu} and attributes
9790 @cindex @code{ge} and attributes
9791 @cindex @code{geu} and attributes
9792 @cindex @code{ne} and attributes
9793 @cindex @code{eq} and attributes
9794 @cindex @code{plus} and attributes
9795 @cindex @code{minus} and attributes
9796 @cindex @code{mult} and attributes
9797 @cindex @code{div} and attributes
9798 @cindex @code{mod} and attributes
9799 @cindex @code{abs} and attributes
9800 @cindex @code{neg} and attributes
9801 @cindex @code{ashift} and attributes
9802 @cindex @code{lshiftrt} and attributes
9803 @cindex @code{ashiftrt} and attributes
9804 @item (le @var{arith1} @var{arith2})
9805 @itemx (leu @var{arith1} @var{arith2})
9806 @itemx (lt @var{arith1} @var{arith2})
9807 @itemx (ltu @var{arith1} @var{arith2})
9808 @itemx (gt @var{arith1} @var{arith2})
9809 @itemx (gtu @var{arith1} @var{arith2})
9810 @itemx (ge @var{arith1} @var{arith2})
9811 @itemx (geu @var{arith1} @var{arith2})
9812 @itemx (ne @var{arith1} @var{arith2})
9813 @itemx (eq @var{arith1} @var{arith2})
9814 These tests are true if the indicated comparison of the two arithmetic
9815 expressions is true. Arithmetic expressions are formed with
9816 @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
9817 @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
9818 @code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.
9819
9820 @findex get_attr
9821 @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
9822 Lengths},for additional forms). @code{symbol_ref} is a string
9823 denoting a C expression that yields an @code{int} when evaluated by the
9824 @samp{get_attr_@dots{}} routine. It should normally be a global
9825 variable.
9826
9827 @findex eq_attr
9828 @item (eq_attr @var{name} @var{value})
9829 @var{name} is a string specifying the name of an attribute.
9830
9831 @var{value} is a string that is either a valid value for attribute
9832 @var{name}, a comma-separated list of values, or @samp{!} followed by a
9833 value or list. If @var{value} does not begin with a @samp{!}, this
9834 test is true if the value of the @var{name} attribute of the current
9835 insn is in the list specified by @var{value}. If @var{value} begins
9836 with a @samp{!}, this test is true if the attribute's value is
9837 @emph{not} in the specified list.
9838
9839 For example,
9840
9841 @smallexample
9842 (eq_attr "type" "load,store")
9843 @end smallexample
9844
9845 @noindent
9846 is equivalent to
9847
9848 @smallexample
9849 (ior (eq_attr "type" "load") (eq_attr "type" "store"))
9850 @end smallexample
9851
9852 If @var{name} specifies an attribute of @samp{alternative}, it refers to the
9853 value of the compiler variable @code{which_alternative}
9854 (@pxref{Output Statement}) and the values must be small integers. For
9855 example,
9856
9857 @smallexample
9858 (eq_attr "alternative" "2,3")
9859 @end smallexample
9860
9861 @noindent
9862 is equivalent to
9863
9864 @smallexample
9865 (ior (eq (symbol_ref "which_alternative") (const_int 2))
9866 (eq (symbol_ref "which_alternative") (const_int 3)))
9867 @end smallexample
9868
9869 Note that, for most attributes, an @code{eq_attr} test is simplified in cases
9870 where the value of the attribute being tested is known for all insns matching
9871 a particular pattern. This is by far the most common case.
9872
9873 @findex attr_flag
9874 @item (attr_flag @var{name})
9875 The value of an @code{attr_flag} expression is true if the flag
9876 specified by @var{name} is true for the @code{insn} currently being
9877 scheduled.
9878
9879 @var{name} is a string specifying one of a fixed set of flags to test.
9880 Test the flags @code{forward} and @code{backward} to determine the
9881 direction of a conditional branch.
9882
9883 This example describes a conditional branch delay slot which
9884 can be nullified for forward branches that are taken (annul-true) or
9885 for backward branches which are not taken (annul-false).
9886
9887 @smallexample
9888 (define_delay (eq_attr "type" "cbranch")
9889 [(eq_attr "in_branch_delay" "true")
9890 (and (eq_attr "in_branch_delay" "true")
9891 (attr_flag "forward"))
9892 (and (eq_attr "in_branch_delay" "true")
9893 (attr_flag "backward"))])
9894 @end smallexample
9895
9896 The @code{forward} and @code{backward} flags are false if the current
9897 @code{insn} being scheduled is not a conditional branch.
9898
9899 @code{attr_flag} is only used during delay slot scheduling and has no
9900 meaning to other passes of the compiler.
9901
9902 @findex attr
9903 @item (attr @var{name})
9904 The value of another attribute is returned. This is most useful
9905 for numeric attributes, as @code{eq_attr} and @code{attr_flag}
9906 produce more efficient code for non-numeric attributes.
9907 @end table
9908
9909 @end ifset
9910 @ifset INTERNALS
9911 @node Tagging Insns
9912 @subsection Assigning Attribute Values to Insns
9913 @cindex tagging insns
9914 @cindex assigning attribute values to insns
9915
9916 The value assigned to an attribute of an insn is primarily determined by
9917 which pattern is matched by that insn (or which @code{define_peephole}
9918 generated it). Every @code{define_insn} and @code{define_peephole} can
9919 have an optional last argument to specify the values of attributes for
9920 matching insns. The value of any attribute not specified in a particular
9921 insn is set to the default value for that attribute, as specified in its
9922 @code{define_attr}. Extensive use of default values for attributes
9923 permits the specification of the values for only one or two attributes
9924 in the definition of most insn patterns, as seen in the example in the
9925 next section.
9926
9927 The optional last argument of @code{define_insn} and
9928 @code{define_peephole} is a vector of expressions, each of which defines
9929 the value for a single attribute. The most general way of assigning an
9930 attribute's value is to use a @code{set} expression whose first operand is an
9931 @code{attr} expression giving the name of the attribute being set. The
9932 second operand of the @code{set} is an attribute expression
9933 (@pxref{Expressions}) giving the value of the attribute.
9934
9935 When the attribute value depends on the @samp{alternative} attribute
9936 (i.e., which is the applicable alternative in the constraint of the
9937 insn), the @code{set_attr_alternative} expression can be used. It
9938 allows the specification of a vector of attribute expressions, one for
9939 each alternative.
9940
9941 @findex set_attr
9942 When the generality of arbitrary attribute expressions is not required,
9943 the simpler @code{set_attr} expression can be used, which allows
9944 specifying a string giving either a single attribute value or a list
9945 of attribute values, one for each alternative.
9946
9947 The form of each of the above specifications is shown below. In each case,
9948 @var{name} is a string specifying the attribute to be set.
9949
9950 @table @code
9951 @item (set_attr @var{name} @var{value-string})
9952 @var{value-string} is either a string giving the desired attribute value,
9953 or a string containing a comma-separated list giving the values for
9954 succeeding alternatives. The number of elements must match the number
9955 of alternatives in the constraint of the insn pattern.
9956
9957 Note that it may be useful to specify @samp{*} for some alternative, in
9958 which case the attribute will assume its default value for insns matching
9959 that alternative.
9960
9961 @findex set_attr_alternative
9962 @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
9963 Depending on the alternative of the insn, the value will be one of the
9964 specified values. This is a shorthand for using a @code{cond} with
9965 tests on the @samp{alternative} attribute.
9966
9967 @findex attr
9968 @item (set (attr @var{name}) @var{value})
9969 The first operand of this @code{set} must be the special RTL expression
9970 @code{attr}, whose sole operand is a string giving the name of the
9971 attribute being set. @var{value} is the value of the attribute.
9972 @end table
9973
9974 The following shows three different ways of representing the same
9975 attribute value specification:
9976
9977 @smallexample
9978 (set_attr "type" "load,store,arith")
9979
9980 (set_attr_alternative "type"
9981 [(const_string "load") (const_string "store")
9982 (const_string "arith")])
9983
9984 (set (attr "type")
9985 (cond [(eq_attr "alternative" "1") (const_string "load")
9986 (eq_attr "alternative" "2") (const_string "store")]
9987 (const_string "arith")))
9988 @end smallexample
9989
9990 @need 1000
9991 @findex define_asm_attributes
9992 The @code{define_asm_attributes} expression provides a mechanism to
9993 specify the attributes assigned to insns produced from an @code{asm}
9994 statement. It has the form:
9995
9996 @smallexample
9997 (define_asm_attributes [@var{attr-sets}])
9998 @end smallexample
9999
10000 @noindent
10001 where @var{attr-sets} is specified the same as for both the
10002 @code{define_insn} and the @code{define_peephole} expressions.
10003
10004 These values will typically be the ``worst case'' attribute values. For
10005 example, they might indicate that the condition code will be clobbered.
10006
10007 A specification for a @code{length} attribute is handled specially. The
10008 way to compute the length of an @code{asm} insn is to multiply the
10009 length specified in the expression @code{define_asm_attributes} by the
10010 number of machine instructions specified in the @code{asm} statement,
10011 determined by counting the number of semicolons and newlines in the
10012 string. Therefore, the value of the @code{length} attribute specified
10013 in a @code{define_asm_attributes} should be the maximum possible length
10014 of a single machine instruction.
10015
10016 @end ifset
10017 @ifset INTERNALS
10018 @node Attr Example
10019 @subsection Example of Attribute Specifications
10020 @cindex attribute specifications example
10021 @cindex attribute specifications
10022
10023 The judicious use of defaulting is important in the efficient use of
10024 insn attributes. Typically, insns are divided into @dfn{types} and an
10025 attribute, customarily called @code{type}, is used to represent this
10026 value. This attribute is normally used only to define the default value
10027 for other attributes. An example will clarify this usage.
10028
10029 Assume we have a RISC machine with a condition code and in which only
10030 full-word operations are performed in registers. Let us assume that we
10031 can divide all insns into loads, stores, (integer) arithmetic
10032 operations, floating point operations, and branches.
10033
10034 Here we will concern ourselves with determining the effect of an insn on
10035 the condition code and will limit ourselves to the following possible
10036 effects: The condition code can be set unpredictably (clobbered), not
10037 be changed, be set to agree with the results of the operation, or only
10038 changed if the item previously set into the condition code has been
10039 modified.
10040
10041 Here is part of a sample @file{md} file for such a machine:
10042
10043 @smallexample
10044 (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
10045
10046 (define_attr "cc" "clobber,unchanged,set,change0"
10047 (cond [(eq_attr "type" "load")
10048 (const_string "change0")
10049 (eq_attr "type" "store,branch")
10050 (const_string "unchanged")
10051 (eq_attr "type" "arith")
10052 (if_then_else (match_operand:SI 0 "" "")
10053 (const_string "set")
10054 (const_string "clobber"))]
10055 (const_string "clobber")))
10056
10057 (define_insn ""
10058 [(set (match_operand:SI 0 "general_operand" "=r,r,m")
10059 (match_operand:SI 1 "general_operand" "r,m,r"))]
10060 ""
10061 "@@
10062 move %0,%1
10063 load %0,%1
10064 store %0,%1"
10065 [(set_attr "type" "arith,load,store")])
10066 @end smallexample
10067
10068 Note that we assume in the above example that arithmetic operations
10069 performed on quantities smaller than a machine word clobber the condition
10070 code since they will set the condition code to a value corresponding to the
10071 full-word result.
10072
10073 @end ifset
10074 @ifset INTERNALS
10075 @node Insn Lengths
10076 @subsection Computing the Length of an Insn
10077 @cindex insn lengths, computing
10078 @cindex computing the length of an insn
10079
10080 For many machines, multiple types of branch instructions are provided, each
10081 for different length branch displacements. In most cases, the assembler
10082 will choose the correct instruction to use. However, when the assembler
10083 cannot do so, GCC can when a special attribute, the @code{length}
10084 attribute, is defined. This attribute must be defined to have numeric
10085 values by specifying a null string in its @code{define_attr}.
10086
10087 In the case of the @code{length} attribute, two additional forms of
10088 arithmetic terms are allowed in test expressions:
10089
10090 @table @code
10091 @cindex @code{match_dup} and attributes
10092 @item (match_dup @var{n})
10093 This refers to the address of operand @var{n} of the current insn, which
10094 must be a @code{label_ref}.
10095
10096 @cindex @code{pc} and attributes
10097 @item (pc)
10098 For non-branch instructions and backward branch instructions, this refers
10099 to the address of the current insn. But for forward branch instructions,
10100 this refers to the address of the next insn, because the length of the
10101 current insn is to be computed.
10102 @end table
10103
10104 @cindex @code{addr_vec}, length of
10105 @cindex @code{addr_diff_vec}, length of
10106 For normal insns, the length will be determined by value of the
10107 @code{length} attribute. In the case of @code{addr_vec} and
10108 @code{addr_diff_vec} insn patterns, the length is computed as
10109 the number of vectors multiplied by the size of each vector.
10110
10111 Lengths are measured in addressable storage units (bytes).
10112
10113 Note that it is possible to call functions via the @code{symbol_ref}
10114 mechanism to compute the length of an insn. However, if you use this
10115 mechanism you must provide dummy clauses to express the maximum length
10116 without using the function call. You can see an example of this in the
10117 @code{pa} machine description for the @code{call_symref} pattern.
10118
10119 The following macros can be used to refine the length computation:
10120
10121 @table @code
10122 @findex ADJUST_INSN_LENGTH
10123 @item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
10124 If defined, modifies the length assigned to instruction @var{insn} as a
10125 function of the context in which it is used. @var{length} is an lvalue
10126 that contains the initially computed length of the insn and should be
10127 updated with the correct length of the insn.
10128
10129 This macro will normally not be required. A case in which it is
10130 required is the ROMP@. On this machine, the size of an @code{addr_vec}
10131 insn must be increased by two to compensate for the fact that alignment
10132 may be required.
10133 @end table
10134
10135 @findex get_attr_length
10136 The routine that returns @code{get_attr_length} (the value of the
10137 @code{length} attribute) can be used by the output routine to
10138 determine the form of the branch instruction to be written, as the
10139 example below illustrates.
10140
10141 As an example of the specification of variable-length branches, consider
10142 the IBM 360. If we adopt the convention that a register will be set to
10143 the starting address of a function, we can jump to labels within 4k of
10144 the start using a four-byte instruction. Otherwise, we need a six-byte
10145 sequence to load the address from memory and then branch to it.
10146
10147 On such a machine, a pattern for a branch instruction might be specified
10148 as follows:
10149
10150 @smallexample
10151 (define_insn "jump"
10152 [(set (pc)
10153 (label_ref (match_operand 0 "" "")))]
10154 ""
10155 @{
10156 return (get_attr_length (insn) == 4
10157 ? "b %l0" : "l r15,=a(%l0); br r15");
10158 @}
10159 [(set (attr "length")
10160 (if_then_else (lt (match_dup 0) (const_int 4096))
10161 (const_int 4)
10162 (const_int 6)))])
10163 @end smallexample
10164
10165 @end ifset
10166 @ifset INTERNALS
10167 @node Constant Attributes
10168 @subsection Constant Attributes
10169 @cindex constant attributes
10170
10171 A special form of @code{define_attr}, where the expression for the
10172 default value is a @code{const} expression, indicates an attribute that
10173 is constant for a given run of the compiler. Constant attributes may be
10174 used to specify which variety of processor is used. For example,
10175
10176 @smallexample
10177 (define_attr "cpu" "m88100,m88110,m88000"
10178 (const
10179 (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
10180 (symbol_ref "TARGET_88110") (const_string "m88110")]
10181 (const_string "m88000"))))
10182
10183 (define_attr "memory" "fast,slow"
10184 (const
10185 (if_then_else (symbol_ref "TARGET_FAST_MEM")
10186 (const_string "fast")
10187 (const_string "slow"))))
10188 @end smallexample
10189
10190 The routine generated for constant attributes has no parameters as it
10191 does not depend on any particular insn. RTL expressions used to define
10192 the value of a constant attribute may use the @code{symbol_ref} form,
10193 but may not use either the @code{match_operand} form or @code{eq_attr}
10194 forms involving insn attributes.
10195
10196 @end ifset
10197 @ifset INTERNALS
10198 @node Mnemonic Attribute
10199 @subsection Mnemonic Attribute
10200 @cindex mnemonic attribute
10201
10202 The @code{mnemonic} attribute is a string type attribute holding the
10203 instruction mnemonic for an insn alternative. The attribute values
10204 will automatically be generated by the machine description parser if
10205 there is an attribute definition in the md file:
10206
10207 @smallexample
10208 (define_attr "mnemonic" "unknown" (const_string "unknown"))
10209 @end smallexample
10210
10211 The default value can be freely chosen as long as it does not collide
10212 with any of the instruction mnemonics. This value will be used
10213 whenever the machine description parser is not able to determine the
10214 mnemonic string. This might be the case for output templates
10215 containing more than a single instruction as in
10216 @code{"mvcle\t%0,%1,0\;jo\t.-4"}.
10217
10218 The @code{mnemonic} attribute set is not generated automatically if the
10219 instruction string is generated via C code.
10220
10221 An existing @code{mnemonic} attribute set in an insn definition will not
10222 be overriden by the md file parser. That way it is possible to
10223 manually set the instruction mnemonics for the cases where the md file
10224 parser fails to determine it automatically.
10225
10226 The @code{mnemonic} attribute is useful for dealing with instruction
10227 specific properties in the pipeline description without defining
10228 additional insn attributes.
10229
10230 @smallexample
10231 (define_attr "ooo_expanded" ""
10232 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
10233 (const_int 1)]
10234 (const_int 0)))
10235 @end smallexample
10236
10237 @end ifset
10238 @ifset INTERNALS
10239 @node Delay Slots
10240 @subsection Delay Slot Scheduling
10241 @cindex delay slots, defining
10242
10243 The insn attribute mechanism can be used to specify the requirements for
10244 delay slots, if any, on a target machine. An instruction is said to
10245 require a @dfn{delay slot} if some instructions that are physically
10246 after the instruction are executed as if they were located before it.
10247 Classic examples are branch and call instructions, which often execute
10248 the following instruction before the branch or call is performed.
10249
10250 On some machines, conditional branch instructions can optionally
10251 @dfn{annul} instructions in the delay slot. This means that the
10252 instruction will not be executed for certain branch outcomes. Both
10253 instructions that annul if the branch is true and instructions that
10254 annul if the branch is false are supported.
10255
10256 Delay slot scheduling differs from instruction scheduling in that
10257 determining whether an instruction needs a delay slot is dependent only
10258 on the type of instruction being generated, not on data flow between the
10259 instructions. See the next section for a discussion of data-dependent
10260 instruction scheduling.
10261
10262 @findex define_delay
10263 The requirement of an insn needing one or more delay slots is indicated
10264 via the @code{define_delay} expression. It has the following form:
10265
10266 @smallexample
10267 (define_delay @var{test}
10268 [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
10269 @var{delay-2} @var{annul-true-2} @var{annul-false-2}
10270 @dots{}])
10271 @end smallexample
10272
10273 @var{test} is an attribute test that indicates whether this
10274 @code{define_delay} applies to a particular insn. If so, the number of
10275 required delay slots is determined by the length of the vector specified
10276 as the second argument. An insn placed in delay slot @var{n} must
10277 satisfy attribute test @var{delay-n}. @var{annul-true-n} is an
10278 attribute test that specifies which insns may be annulled if the branch
10279 is true. Similarly, @var{annul-false-n} specifies which insns in the
10280 delay slot may be annulled if the branch is false. If annulling is not
10281 supported for that delay slot, @code{(nil)} should be coded.
10282
10283 For example, in the common case where branch and call insns require
10284 a single delay slot, which may contain any insn other than a branch or
10285 call, the following would be placed in the @file{md} file:
10286
10287 @smallexample
10288 (define_delay (eq_attr "type" "branch,call")
10289 [(eq_attr "type" "!branch,call") (nil) (nil)])
10290 @end smallexample
10291
10292 Multiple @code{define_delay} expressions may be specified. In this
10293 case, each such expression specifies different delay slot requirements
10294 and there must be no insn for which tests in two @code{define_delay}
10295 expressions are both true.
10296
10297 For example, if we have a machine that requires one delay slot for branches
10298 but two for calls, no delay slot can contain a branch or call insn,
10299 and any valid insn in the delay slot for the branch can be annulled if the
10300 branch is true, we might represent this as follows:
10301
10302 @smallexample
10303 (define_delay (eq_attr "type" "branch")
10304 [(eq_attr "type" "!branch,call")
10305 (eq_attr "type" "!branch,call")
10306 (nil)])
10307
10308 (define_delay (eq_attr "type" "call")
10309 [(eq_attr "type" "!branch,call") (nil) (nil)
10310 (eq_attr "type" "!branch,call") (nil) (nil)])
10311 @end smallexample
10312 @c the above is *still* too long. --mew 4feb93
10313
10314 @end ifset
10315 @ifset INTERNALS
10316 @node Processor pipeline description
10317 @subsection Specifying processor pipeline description
10318 @cindex processor pipeline description
10319 @cindex processor functional units
10320 @cindex instruction latency time
10321 @cindex interlock delays
10322 @cindex data dependence delays
10323 @cindex reservation delays
10324 @cindex pipeline hazard recognizer
10325 @cindex automaton based pipeline description
10326 @cindex regular expressions
10327 @cindex deterministic finite state automaton
10328 @cindex automaton based scheduler
10329 @cindex RISC
10330 @cindex VLIW
10331
10332 To achieve better performance, most modern processors
10333 (super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
10334 processors) have many @dfn{functional units} on which several
10335 instructions can be executed simultaneously. An instruction starts
10336 execution if its issue conditions are satisfied. If not, the
10337 instruction is stalled until its conditions are satisfied. Such
10338 @dfn{interlock (pipeline) delay} causes interruption of the fetching
10339 of successor instructions (or demands nop instructions, e.g.@: for some
10340 MIPS processors).
10341
10342 There are two major kinds of interlock delays in modern processors.
10343 The first one is a data dependence delay determining @dfn{instruction
10344 latency time}. The instruction execution is not started until all
10345 source data have been evaluated by prior instructions (there are more
10346 complex cases when the instruction execution starts even when the data
10347 are not available but will be ready in given time after the
10348 instruction execution start). Taking the data dependence delays into
10349 account is simple. The data dependence (true, output, and
10350 anti-dependence) delay between two instructions is given by a
10351 constant. In most cases this approach is adequate. The second kind
10352 of interlock delays is a reservation delay. The reservation delay
10353 means that two instructions under execution will be in need of shared
10354 processors resources, i.e.@: buses, internal registers, and/or
10355 functional units, which are reserved for some time. Taking this kind
10356 of delay into account is complex especially for modern @acronym{RISC}
10357 processors.
10358
10359 The task of exploiting more processor parallelism is solved by an
10360 instruction scheduler. For a better solution to this problem, the
10361 instruction scheduler has to have an adequate description of the
10362 processor parallelism (or @dfn{pipeline description}). GCC
10363 machine descriptions describe processor parallelism and functional
10364 unit reservations for groups of instructions with the aid of
10365 @dfn{regular expressions}.
10366
10367 The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
10368 figure out the possibility of the instruction issue by the processor
10369 on a given simulated processor cycle. The pipeline hazard recognizer is
10370 automatically generated from the processor pipeline description. The
10371 pipeline hazard recognizer generated from the machine description
10372 is based on a deterministic finite state automaton (@acronym{DFA}):
10373 the instruction issue is possible if there is a transition from one
10374 automaton state to another one. This algorithm is very fast, and
10375 furthermore, its speed is not dependent on processor
10376 complexity@footnote{However, the size of the automaton depends on
10377 processor complexity. To limit this effect, machine descriptions
10378 can split orthogonal parts of the machine description among several
10379 automata: but then, since each of these must be stepped independently,
10380 this does cause a small decrease in the algorithm's performance.}.
10381
10382 @cindex automaton based pipeline description
10383 The rest of this section describes the directives that constitute
10384 an automaton-based processor pipeline description. The order of
10385 these constructions within the machine description file is not
10386 important.
10387
10388 @findex define_automaton
10389 @cindex pipeline hazard recognizer
10390 The following optional construction describes names of automata
10391 generated and used for the pipeline hazards recognition. Sometimes
10392 the generated finite state automaton used by the pipeline hazard
10393 recognizer is large. If we use more than one automaton and bind functional
10394 units to the automata, the total size of the automata is usually
10395 less than the size of the single automaton. If there is no one such
10396 construction, only one finite state automaton is generated.
10397
10398 @smallexample
10399 (define_automaton @var{automata-names})
10400 @end smallexample
10401
10402 @var{automata-names} is a string giving names of the automata. The
10403 names are separated by commas. All the automata should have unique names.
10404 The automaton name is used in the constructions @code{define_cpu_unit} and
10405 @code{define_query_cpu_unit}.
10406
10407 @findex define_cpu_unit
10408 @cindex processor functional units
10409 Each processor functional unit used in the description of instruction
10410 reservations should be described by the following construction.
10411
10412 @smallexample
10413 (define_cpu_unit @var{unit-names} [@var{automaton-name}])
10414 @end smallexample
10415
10416 @var{unit-names} is a string giving the names of the functional units
10417 separated by commas. Don't use name @samp{nothing}, it is reserved
10418 for other goals.
10419
10420 @var{automaton-name} is a string giving the name of the automaton with
10421 which the unit is bound. The automaton should be described in
10422 construction @code{define_automaton}. You should give
10423 @dfn{automaton-name}, if there is a defined automaton.
10424
10425 The assignment of units to automata are constrained by the uses of the
10426 units in insn reservations. The most important constraint is: if a
10427 unit reservation is present on a particular cycle of an alternative
10428 for an insn reservation, then some unit from the same automaton must
10429 be present on the same cycle for the other alternatives of the insn
10430 reservation. The rest of the constraints are mentioned in the
10431 description of the subsequent constructions.
10432
10433 @findex define_query_cpu_unit
10434 @cindex querying function unit reservations
10435 The following construction describes CPU functional units analogously
10436 to @code{define_cpu_unit}. The reservation of such units can be
10437 queried for an automaton state. The instruction scheduler never
10438 queries reservation of functional units for given automaton state. So
10439 as a rule, you don't need this construction. This construction could
10440 be used for future code generation goals (e.g.@: to generate
10441 @acronym{VLIW} insn templates).
10442
10443 @smallexample
10444 (define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
10445 @end smallexample
10446
10447 @var{unit-names} is a string giving names of the functional units
10448 separated by commas.
10449
10450 @var{automaton-name} is a string giving the name of the automaton with
10451 which the unit is bound.
10452
10453 @findex define_insn_reservation
10454 @cindex instruction latency time
10455 @cindex regular expressions
10456 @cindex data bypass
10457 The following construction is the major one to describe pipeline
10458 characteristics of an instruction.
10459
10460 @smallexample
10461 (define_insn_reservation @var{insn-name} @var{default_latency}
10462 @var{condition} @var{regexp})
10463 @end smallexample
10464
10465 @var{default_latency} is a number giving latency time of the
10466 instruction. There is an important difference between the old
10467 description and the automaton based pipeline description. The latency
10468 time is used for all dependencies when we use the old description. In
10469 the automaton based pipeline description, the given latency time is only
10470 used for true dependencies. The cost of anti-dependencies is always
10471 zero and the cost of output dependencies is the difference between
10472 latency times of the producing and consuming insns (if the difference
10473 is negative, the cost is considered to be zero). You can always
10474 change the default costs for any description by using the target hook
10475 @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
10476
10477 @var{insn-name} is a string giving the internal name of the insn. The
10478 internal names are used in constructions @code{define_bypass} and in
10479 the automaton description file generated for debugging. The internal
10480 name has nothing in common with the names in @code{define_insn}. It is a
10481 good practice to use insn classes described in the processor manual.
10482
10483 @var{condition} defines what RTL insns are described by this
10484 construction. You should remember that you will be in trouble if
10485 @var{condition} for two or more different
10486 @code{define_insn_reservation} constructions is TRUE for an insn. In
10487 this case what reservation will be used for the insn is not defined.
10488 Such cases are not checked during generation of the pipeline hazards
10489 recognizer because in general recognizing that two conditions may have
10490 the same value is quite difficult (especially if the conditions
10491 contain @code{symbol_ref}). It is also not checked during the
10492 pipeline hazard recognizer work because it would slow down the
10493 recognizer considerably.
10494
10495 @var{regexp} is a string describing the reservation of the cpu's functional
10496 units by the instruction. The reservations are described by a regular
10497 expression according to the following syntax:
10498
10499 @smallexample
10500 regexp = regexp "," oneof
10501 | oneof
10502
10503 oneof = oneof "|" allof
10504 | allof
10505
10506 allof = allof "+" repeat
10507 | repeat
10508
10509 repeat = element "*" number
10510 | element
10511
10512 element = cpu_function_unit_name
10513 | reservation_name
10514 | result_name
10515 | "nothing"
10516 | "(" regexp ")"
10517 @end smallexample
10518
10519 @itemize @bullet
10520 @item
10521 @samp{,} is used for describing the start of the next cycle in
10522 the reservation.
10523
10524 @item
10525 @samp{|} is used for describing a reservation described by the first
10526 regular expression @strong{or} a reservation described by the second
10527 regular expression @strong{or} etc.
10528
10529 @item
10530 @samp{+} is used for describing a reservation described by the first
10531 regular expression @strong{and} a reservation described by the
10532 second regular expression @strong{and} etc.
10533
10534 @item
10535 @samp{*} is used for convenience and simply means a sequence in which
10536 the regular expression are repeated @var{number} times with cycle
10537 advancing (see @samp{,}).
10538
10539 @item
10540 @samp{cpu_function_unit_name} denotes reservation of the named
10541 functional unit.
10542
10543 @item
10544 @samp{reservation_name} --- see description of construction
10545 @samp{define_reservation}.
10546
10547 @item
10548 @samp{nothing} denotes no unit reservations.
10549 @end itemize
10550
10551 @findex define_reservation
10552 Sometimes unit reservations for different insns contain common parts.
10553 In such case, you can simplify the pipeline description by describing
10554 the common part by the following construction
10555
10556 @smallexample
10557 (define_reservation @var{reservation-name} @var{regexp})
10558 @end smallexample
10559
10560 @var{reservation-name} is a string giving name of @var{regexp}.
10561 Functional unit names and reservation names are in the same name
10562 space. So the reservation names should be different from the
10563 functional unit names and cannot be the reserved name @samp{nothing}.
10564
10565 @findex define_bypass
10566 @cindex instruction latency time
10567 @cindex data bypass
10568 The following construction is used to describe exceptions in the
10569 latency time for given instruction pair. This is so called bypasses.
10570
10571 @smallexample
10572 (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
10573 [@var{guard}])
10574 @end smallexample
10575
10576 @var{number} defines when the result generated by the instructions
10577 given in string @var{out_insn_names} will be ready for the
10578 instructions given in string @var{in_insn_names}. Each of these
10579 strings is a comma-separated list of filename-style globs and
10580 they refer to the names of @code{define_insn_reservation}s.
10581 For example:
10582 @smallexample
10583 (define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
10584 @end smallexample
10585 defines a bypass between instructions that start with
10586 @samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
10587 @samp{cpu1_load_}.
10588
10589 @var{guard} is an optional string giving the name of a C function which
10590 defines an additional guard for the bypass. The function will get the
10591 two insns as parameters. If the function returns zero the bypass will
10592 be ignored for this case. The additional guard is necessary to
10593 recognize complicated bypasses, e.g.@: when the consumer is only an address
10594 of insn @samp{store} (not a stored value).
10595
10596 If there are more one bypass with the same output and input insns, the
10597 chosen bypass is the first bypass with a guard in description whose
10598 guard function returns nonzero. If there is no such bypass, then
10599 bypass without the guard function is chosen.
10600
10601 @findex exclusion_set
10602 @findex presence_set
10603 @findex final_presence_set
10604 @findex absence_set
10605 @findex final_absence_set
10606 @cindex VLIW
10607 @cindex RISC
10608 The following five constructions are usually used to describe
10609 @acronym{VLIW} processors, or more precisely, to describe a placement
10610 of small instructions into @acronym{VLIW} instruction slots. They
10611 can be used for @acronym{RISC} processors, too.
10612
10613 @smallexample
10614 (exclusion_set @var{unit-names} @var{unit-names})
10615 (presence_set @var{unit-names} @var{patterns})
10616 (final_presence_set @var{unit-names} @var{patterns})
10617 (absence_set @var{unit-names} @var{patterns})
10618 (final_absence_set @var{unit-names} @var{patterns})
10619 @end smallexample
10620
10621 @var{unit-names} is a string giving names of functional units
10622 separated by commas.
10623
10624 @var{patterns} is a string giving patterns of functional units
10625 separated by comma. Currently pattern is one unit or units
10626 separated by white-spaces.
10627
10628 The first construction (@samp{exclusion_set}) means that each
10629 functional unit in the first string cannot be reserved simultaneously
10630 with a unit whose name is in the second string and vice versa. For
10631 example, the construction is useful for describing processors
10632 (e.g.@: some SPARC processors) with a fully pipelined floating point
10633 functional unit which can execute simultaneously only single floating
10634 point insns or only double floating point insns.
10635
10636 The second construction (@samp{presence_set}) means that each
10637 functional unit in the first string cannot be reserved unless at
10638 least one of pattern of units whose names are in the second string is
10639 reserved. This is an asymmetric relation. For example, it is useful
10640 for description that @acronym{VLIW} @samp{slot1} is reserved after
10641 @samp{slot0} reservation. We could describe it by the following
10642 construction
10643
10644 @smallexample
10645 (presence_set "slot1" "slot0")
10646 @end smallexample
10647
10648 Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
10649 reservation. In this case we could write
10650
10651 @smallexample
10652 (presence_set "slot1" "slot0 b0")
10653 @end smallexample
10654
10655 The third construction (@samp{final_presence_set}) is analogous to
10656 @samp{presence_set}. The difference between them is when checking is
10657 done. When an instruction is issued in given automaton state
10658 reflecting all current and planned unit reservations, the automaton
10659 state is changed. The first state is a source state, the second one
10660 is a result state. Checking for @samp{presence_set} is done on the
10661 source state reservation, checking for @samp{final_presence_set} is
10662 done on the result reservation. This construction is useful to
10663 describe a reservation which is actually two subsequent reservations.
10664 For example, if we use
10665
10666 @smallexample
10667 (presence_set "slot1" "slot0")
10668 @end smallexample
10669
10670 the following insn will be never issued (because @samp{slot1} requires
10671 @samp{slot0} which is absent in the source state).
10672
10673 @smallexample
10674 (define_reservation "insn_and_nop" "slot0 + slot1")
10675 @end smallexample
10676
10677 but it can be issued if we use analogous @samp{final_presence_set}.
10678
10679 The forth construction (@samp{absence_set}) means that each functional
10680 unit in the first string can be reserved only if each pattern of units
10681 whose names are in the second string is not reserved. This is an
10682 asymmetric relation (actually @samp{exclusion_set} is analogous to
10683 this one but it is symmetric). For example it might be useful in a
10684 @acronym{VLIW} description to say that @samp{slot0} cannot be reserved
10685 after either @samp{slot1} or @samp{slot2} have been reserved. This
10686 can be described as:
10687
10688 @smallexample
10689 (absence_set "slot0" "slot1, slot2")
10690 @end smallexample
10691
10692 Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0}
10693 are reserved or @samp{slot1} and unit @samp{b1} are reserved. In
10694 this case we could write
10695
10696 @smallexample
10697 (absence_set "slot2" "slot0 b0, slot1 b1")
10698 @end smallexample
10699
10700 All functional units mentioned in a set should belong to the same
10701 automaton.
10702
10703 The last construction (@samp{final_absence_set}) is analogous to
10704 @samp{absence_set} but checking is done on the result (state)
10705 reservation. See comments for @samp{final_presence_set}.
10706
10707 @findex automata_option
10708 @cindex deterministic finite state automaton
10709 @cindex nondeterministic finite state automaton
10710 @cindex finite state automaton minimization
10711 You can control the generator of the pipeline hazard recognizer with
10712 the following construction.
10713
10714 @smallexample
10715 (automata_option @var{options})
10716 @end smallexample
10717
10718 @var{options} is a string giving options which affect the generated
10719 code. Currently there are the following options:
10720
10721 @itemize @bullet
10722 @item
10723 @dfn{no-minimization} makes no minimization of the automaton. This is
10724 only worth to do when we are debugging the description and need to
10725 look more accurately at reservations of states.
10726
10727 @item
10728 @dfn{time} means printing time statistics about the generation of
10729 automata.
10730
10731 @item
10732 @dfn{stats} means printing statistics about the generated automata
10733 such as the number of DFA states, NDFA states and arcs.
10734
10735 @item
10736 @dfn{v} means a generation of the file describing the result automata.
10737 The file has suffix @samp{.dfa} and can be used for the description
10738 verification and debugging.
10739
10740 @item
10741 @dfn{w} means a generation of warning instead of error for
10742 non-critical errors.
10743
10744 @item
10745 @dfn{no-comb-vect} prevents the automaton generator from generating
10746 two data structures and comparing them for space efficiency. Using
10747 a comb vector to represent transitions may be better, but it can be
10748 very expensive to construct. This option is useful if the build
10749 process spends an unacceptably long time in genautomata.
10750
10751 @item
10752 @dfn{ndfa} makes nondeterministic finite state automata. This affects
10753 the treatment of operator @samp{|} in the regular expressions. The
10754 usual treatment of the operator is to try the first alternative and,
10755 if the reservation is not possible, the second alternative. The
10756 nondeterministic treatment means trying all alternatives, some of them
10757 may be rejected by reservations in the subsequent insns.
10758
10759 @item
10760 @dfn{collapse-ndfa} modifies the behavior of the generator when
10761 producing an automaton. An additional state transition to collapse a
10762 nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
10763 state is generated. It can be triggered by passing @code{const0_rtx} to
10764 state_transition. In such an automaton, cycle advance transitions are
10765 available only for these collapsed states. This option is useful for
10766 ports that want to use the @code{ndfa} option, but also want to use
10767 @code{define_query_cpu_unit} to assign units to insns issued in a cycle.
10768
10769 @item
10770 @dfn{progress} means output of a progress bar showing how many states
10771 were generated so far for automaton being processed. This is useful
10772 during debugging a @acronym{DFA} description. If you see too many
10773 generated states, you could interrupt the generator of the pipeline
10774 hazard recognizer and try to figure out a reason for generation of the
10775 huge automaton.
10776 @end itemize
10777
10778 As an example, consider a superscalar @acronym{RISC} machine which can
10779 issue three insns (two integer insns and one floating point insn) on
10780 the cycle but can finish only two insns. To describe this, we define
10781 the following functional units.
10782
10783 @smallexample
10784 (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
10785 (define_cpu_unit "port0, port1")
10786 @end smallexample
10787
10788 All simple integer insns can be executed in any integer pipeline and
10789 their result is ready in two cycles. The simple integer insns are
10790 issued into the first pipeline unless it is reserved, otherwise they
10791 are issued into the second pipeline. Integer division and
10792 multiplication insns can be executed only in the second integer
10793 pipeline and their results are ready correspondingly in 9 and 4
10794 cycles. The integer division is not pipelined, i.e.@: the subsequent
10795 integer division insn cannot be issued until the current division
10796 insn finished. Floating point insns are fully pipelined and their
10797 results are ready in 3 cycles. Where the result of a floating point
10798 insn is used by an integer insn, an additional delay of one cycle is
10799 incurred. To describe all of this we could specify
10800
10801 @smallexample
10802 (define_cpu_unit "div")
10803
10804 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
10805 "(i0_pipeline | i1_pipeline), (port0 | port1)")
10806
10807 (define_insn_reservation "mult" 4 (eq_attr "type" "mult")
10808 "i1_pipeline, nothing*2, (port0 | port1)")
10809
10810 (define_insn_reservation "div" 9 (eq_attr "type" "div")
10811 "i1_pipeline, div*7, div + (port0 | port1)")
10812
10813 (define_insn_reservation "float" 3 (eq_attr "type" "float")
10814 "f_pipeline, nothing, (port0 | port1))
10815
10816 (define_bypass 4 "float" "simple,mult,div")
10817 @end smallexample
10818
10819 To simplify the description we could describe the following reservation
10820
10821 @smallexample
10822 (define_reservation "finish" "port0|port1")
10823 @end smallexample
10824
10825 and use it in all @code{define_insn_reservation} as in the following
10826 construction
10827
10828 @smallexample
10829 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
10830 "(i0_pipeline | i1_pipeline), finish")
10831 @end smallexample
10832
10833
10834 @end ifset
10835 @ifset INTERNALS
10836 @node Conditional Execution
10837 @section Conditional Execution
10838 @cindex conditional execution
10839 @cindex predication
10840
10841 A number of architectures provide for some form of conditional
10842 execution, or predication. The hallmark of this feature is the
10843 ability to nullify most of the instructions in the instruction set.
10844 When the instruction set is large and not entirely symmetric, it
10845 can be quite tedious to describe these forms directly in the
10846 @file{.md} file. An alternative is the @code{define_cond_exec} template.
10847
10848 @findex define_cond_exec
10849 @smallexample
10850 (define_cond_exec
10851 [@var{predicate-pattern}]
10852 "@var{condition}"
10853 "@var{output-template}"
10854 "@var{optional-insn-attribues}")
10855 @end smallexample
10856
10857 @var{predicate-pattern} is the condition that must be true for the
10858 insn to be executed at runtime and should match a relational operator.
10859 One can use @code{match_operator} to match several relational operators
10860 at once. Any @code{match_operand} operands must have no more than one
10861 alternative.
10862
10863 @var{condition} is a C expression that must be true for the generated
10864 pattern to match.
10865
10866 @findex current_insn_predicate
10867 @var{output-template} is a string similar to the @code{define_insn}
10868 output template (@pxref{Output Template}), except that the @samp{*}
10869 and @samp{@@} special cases do not apply. This is only useful if the
10870 assembly text for the predicate is a simple prefix to the main insn.
10871 In order to handle the general case, there is a global variable
10872 @code{current_insn_predicate} that will contain the entire predicate
10873 if the current insn is predicated, and will otherwise be @code{NULL}.
10874
10875 @var{optional-insn-attributes} is an optional vector of attributes that gets
10876 appended to the insn attributes of the produced cond_exec rtx. It can
10877 be used to add some distinguishing attribute to cond_exec rtxs produced
10878 that way. An example usage would be to use this attribute in conjunction
10879 with attributes on the main pattern to disable particular alternatives under
10880 certain conditions.
10881
10882 When @code{define_cond_exec} is used, an implicit reference to
10883 the @code{predicable} instruction attribute is made.
10884 @xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have
10885 exactly two elements in its @var{list-of-values}), with the possible
10886 values being @code{no} and @code{yes}. The default and all uses in
10887 the insns must be a simple constant, not a complex expressions. It
10888 may, however, depend on the alternative, by using a comma-separated
10889 list of values. If that is the case, the port should also define an
10890 @code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
10891 should also allow only @code{no} and @code{yes} as its values.
10892
10893 For each @code{define_insn} for which the @code{predicable}
10894 attribute is true, a new @code{define_insn} pattern will be
10895 generated that matches a predicated version of the instruction.
10896 For example,
10897
10898 @smallexample
10899 (define_insn "addsi"
10900 [(set (match_operand:SI 0 "register_operand" "r")
10901 (plus:SI (match_operand:SI 1 "register_operand" "r")
10902 (match_operand:SI 2 "register_operand" "r")))]
10903 "@var{test1}"
10904 "add %2,%1,%0")
10905
10906 (define_cond_exec
10907 [(ne (match_operand:CC 0 "register_operand" "c")
10908 (const_int 0))]
10909 "@var{test2}"
10910 "(%0)")
10911 @end smallexample
10912
10913 @noindent
10914 generates a new pattern
10915
10916 @smallexample
10917 (define_insn ""
10918 [(cond_exec
10919 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
10920 (set (match_operand:SI 0 "register_operand" "r")
10921 (plus:SI (match_operand:SI 1 "register_operand" "r")
10922 (match_operand:SI 2 "register_operand" "r"))))]
10923 "(@var{test2}) && (@var{test1})"
10924 "(%3) add %2,%1,%0")
10925 @end smallexample
10926
10927 @end ifset
10928 @ifset INTERNALS
10929 @node Define Subst
10930 @section RTL Templates Transformations
10931 @cindex define_subst
10932
10933 For some hardware architectures there are common cases when the RTL
10934 templates for the instructions can be derived from the other RTL
10935 templates using simple transformations. E.g., @file{i386.md} contains
10936 an RTL template for the ordinary @code{sub} instruction---
10937 @code{*subsi_1}, and for the @code{sub} instruction with subsequent
10938 zero-extension---@code{*subsi_1_zext}. Such cases can be easily
10939 implemented by a single meta-template capable of generating a modified
10940 case based on the initial one:
10941
10942 @findex define_subst
10943 @smallexample
10944 (define_subst "@var{name}"
10945 [@var{input-template}]
10946 "@var{condition}"
10947 [@var{output-template}])
10948 @end smallexample
10949 @var{input-template} is a pattern describing the source RTL template,
10950 which will be transformed.
10951
10952 @var{condition} is a C expression that is conjunct with the condition
10953 from the input-template to generate a condition to be used in the
10954 output-template.
10955
10956 @var{output-template} is a pattern that will be used in the resulting
10957 template.
10958
10959 @code{define_subst} mechanism is tightly coupled with the notion of the
10960 subst attribute (@pxref{Subst Iterators}). The use of
10961 @code{define_subst} is triggered by a reference to a subst attribute in
10962 the transforming RTL template. This reference initiates duplication of
10963 the source RTL template and substitution of the attributes with their
10964 values. The source RTL template is left unchanged, while the copy is
10965 transformed by @code{define_subst}. This transformation can fail in the
10966 case when the source RTL template is not matched against the
10967 input-template of the @code{define_subst}. In such case the copy is
10968 deleted.
10969
10970 @code{define_subst} can be used only in @code{define_insn} and
10971 @code{define_expand}, it cannot be used in other expressions (e.g.@: in
10972 @code{define_insn_and_split}).
10973
10974 @menu
10975 * Define Subst Example:: Example of @code{define_subst} work.
10976 * Define Subst Pattern Matching:: Process of template comparison.
10977 * Define Subst Output Template:: Generation of output template.
10978 @end menu
10979
10980 @node Define Subst Example
10981 @subsection @code{define_subst} Example
10982 @cindex define_subst
10983
10984 To illustrate how @code{define_subst} works, let us examine a simple
10985 template transformation.
10986
10987 Suppose there are two kinds of instructions: one that touches flags and
10988 the other that does not. The instructions of the second type could be
10989 generated with the following @code{define_subst}:
10990
10991 @smallexample
10992 (define_subst "add_clobber_subst"
10993 [(set (match_operand:SI 0 "" "")
10994 (match_operand:SI 1 "" ""))]
10995 ""
10996 [(set (match_dup 0)
10997 (match_dup 1))
10998 (clobber (reg:CC FLAGS_REG))])
10999 @end smallexample
11000
11001 This @code{define_subst} can be applied to any RTL pattern containing
11002 @code{set} of mode SI and generates a copy with clobber when it is
11003 applied.
11004
11005 Assume there is an RTL template for a @code{max} instruction to be used
11006 in @code{define_subst} mentioned above:
11007
11008 @smallexample
11009 (define_insn "maxsi"
11010 [(set (match_operand:SI 0 "register_operand" "=r")
11011 (max:SI
11012 (match_operand:SI 1 "register_operand" "r")
11013 (match_operand:SI 2 "register_operand" "r")))]
11014 ""
11015 "max\t@{%2, %1, %0|%0, %1, %2@}"
11016 [@dots{}])
11017 @end smallexample
11018
11019 To mark the RTL template for @code{define_subst} application,
11020 subst-attributes are used. They should be declared in advance:
11021
11022 @smallexample
11023 (define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber")
11024 @end smallexample
11025
11026 Here @samp{add_clobber_name} is the attribute name,
11027 @samp{add_clobber_subst} is the name of the corresponding
11028 @code{define_subst}, the third argument (@samp{_noclobber}) is the
11029 attribute value that would be substituted into the unchanged version of
11030 the source RTL template, and the last argument (@samp{_clobber}) is the
11031 value that would be substituted into the second, transformed,
11032 version of the RTL template.
11033
11034 Once the subst-attribute has been defined, it should be used in RTL
11035 templates which need to be processed by the @code{define_subst}. So,
11036 the original RTL template should be changed:
11037
11038 @smallexample
11039 (define_insn "maxsi<add_clobber_name>"
11040 [(set (match_operand:SI 0 "register_operand" "=r")
11041 (max:SI
11042 (match_operand:SI 1 "register_operand" "r")
11043 (match_operand:SI 2 "register_operand" "r")))]
11044 ""
11045 "max\t@{%2, %1, %0|%0, %1, %2@}"
11046 [@dots{}])
11047 @end smallexample
11048
11049 The result of the @code{define_subst} usage would look like the following:
11050
11051 @smallexample
11052 (define_insn "maxsi_noclobber"
11053 [(set (match_operand:SI 0 "register_operand" "=r")
11054 (max:SI
11055 (match_operand:SI 1 "register_operand" "r")
11056 (match_operand:SI 2 "register_operand" "r")))]
11057 ""
11058 "max\t@{%2, %1, %0|%0, %1, %2@}"
11059 [@dots{}])
11060 (define_insn "maxsi_clobber"
11061 [(set (match_operand:SI 0 "register_operand" "=r")
11062 (max:SI
11063 (match_operand:SI 1 "register_operand" "r")
11064 (match_operand:SI 2 "register_operand" "r")))
11065 (clobber (reg:CC FLAGS_REG))]
11066 ""
11067 "max\t@{%2, %1, %0|%0, %1, %2@}"
11068 [@dots{}])
11069 @end smallexample
11070
11071 @node Define Subst Pattern Matching
11072 @subsection Pattern Matching in @code{define_subst}
11073 @cindex define_subst
11074
11075 All expressions, allowed in @code{define_insn} or @code{define_expand},
11076 are allowed in the input-template of @code{define_subst}, except
11077 @code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The
11078 meanings of expressions in the input-template were changed:
11079
11080 @code{match_operand} matches any expression (possibly, a subtree in
11081 RTL-template), if modes of the @code{match_operand} and this expression
11082 are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or
11083 this expression is @code{match_dup}, @code{match_op_dup}. If the
11084 expression is @code{match_operand} too, and predicate of
11085 @code{match_operand} from the input pattern is not empty, then the
11086 predicates are compared. That can be used for more accurate filtering
11087 of accepted RTL-templates.
11088
11089 @code{match_operator} matches common operators (like @code{plus},
11090 @code{minus}), @code{unspec}, @code{unspec_volatile} operators and
11091 @code{match_operator}s from the original pattern if the modes match and
11092 @code{match_operator} from the input pattern has the same number of
11093 operands as the operator from the original pattern.
11094
11095 @node Define Subst Output Template
11096 @subsection Generation of output template in @code{define_subst}
11097 @cindex define_subst
11098
11099 If all necessary checks for @code{define_subst} application pass, a new
11100 RTL-pattern, based on the output-template, is created to replace the old
11101 template. Like in input-patterns, meanings of some RTL expressions are
11102 changed when they are used in output-patterns of a @code{define_subst}.
11103 Thus, @code{match_dup} is used for copying the whole expression from the
11104 original pattern, which matched corresponding @code{match_operand} from
11105 the input pattern.
11106
11107 @code{match_dup N} is used in the output template to be replaced with
11108 the expression from the original pattern, which matched
11109 @code{match_operand N} from the input pattern. As a consequence,
11110 @code{match_dup} cannot be used to point to @code{match_operand}s from
11111 the output pattern, it should always refer to a @code{match_operand}
11112 from the input pattern. If a @code{match_dup N} occurs more than once
11113 in the output template, its first occurrence is replaced with the
11114 expression from the original pattern, and the subsequent expressions
11115 are replaced with @code{match_dup N}, i.e., a reference to the first
11116 expression.
11117
11118 In the output template one can refer to the expressions from the
11119 original pattern and create new ones. For instance, some operands could
11120 be added by means of standard @code{match_operand}.
11121
11122 After replacing @code{match_dup} with some RTL-subtree from the original
11123 pattern, it could happen that several @code{match_operand}s in the
11124 output pattern have the same indexes. It is unknown, how many and what
11125 indexes would be used in the expression which would replace
11126 @code{match_dup}, so such conflicts in indexes are inevitable. To
11127 overcome this issue, @code{match_operands} and @code{match_operators},
11128 which were introduced into the output pattern, are renumerated when all
11129 @code{match_dup}s are replaced.
11130
11131 Number of alternatives in @code{match_operand}s introduced into the
11132 output template @code{M} could differ from the number of alternatives in
11133 the original pattern @code{N}, so in the resultant pattern there would
11134 be @code{N*M} alternatives. Thus, constraints from the original pattern
11135 would be duplicated @code{N} times, constraints from the output pattern
11136 would be duplicated @code{M} times, producing all possible combinations.
11137 @end ifset
11138
11139 @ifset INTERNALS
11140 @node Constant Definitions
11141 @section Constant Definitions
11142 @cindex constant definitions
11143 @findex define_constants
11144
11145 Using literal constants inside instruction patterns reduces legibility and
11146 can be a maintenance problem.
11147
11148 To overcome this problem, you may use the @code{define_constants}
11149 expression. It contains a vector of name-value pairs. From that
11150 point on, wherever any of the names appears in the MD file, it is as
11151 if the corresponding value had been written instead. You may use
11152 @code{define_constants} multiple times; each appearance adds more
11153 constants to the table. It is an error to redefine a constant with
11154 a different value.
11155
11156 To come back to the a29k load multiple example, instead of
11157
11158 @smallexample
11159 (define_insn ""
11160 [(match_parallel 0 "load_multiple_operation"
11161 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11162 (match_operand:SI 2 "memory_operand" "m"))
11163 (use (reg:SI 179))
11164 (clobber (reg:SI 179))])]
11165 ""
11166 "loadm 0,0,%1,%2")
11167 @end smallexample
11168
11169 You could write:
11170
11171 @smallexample
11172 (define_constants [
11173 (R_BP 177)
11174 (R_FC 178)
11175 (R_CR 179)
11176 (R_Q 180)
11177 ])
11178
11179 (define_insn ""
11180 [(match_parallel 0 "load_multiple_operation"
11181 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11182 (match_operand:SI 2 "memory_operand" "m"))
11183 (use (reg:SI R_CR))
11184 (clobber (reg:SI R_CR))])]
11185 ""
11186 "loadm 0,0,%1,%2")
11187 @end smallexample
11188
11189 The constants that are defined with a define_constant are also output
11190 in the insn-codes.h header file as #defines.
11191
11192 @cindex enumerations
11193 @findex define_c_enum
11194 You can also use the machine description file to define enumerations.
11195 Like the constants defined by @code{define_constant}, these enumerations
11196 are visible to both the machine description file and the main C code.
11197
11198 The syntax is as follows:
11199
11200 @smallexample
11201 (define_c_enum "@var{name}" [
11202 @var{value0}
11203 @var{value1}
11204 (@var{value32} 32)
11205 @var{value33}
11206 @dots{}
11207 @var{valuen}
11208 ])
11209 @end smallexample
11210
11211 This definition causes the equivalent of the following C code to appear
11212 in @file{insn-constants.h}:
11213
11214 @smallexample
11215 enum @var{name} @{
11216 @var{value0} = 0,
11217 @var{value1} = 1,
11218 @var{value32} = 32,
11219 @var{value33} = 33,
11220 @dots{}
11221 @var{valuen} = @var{n}
11222 @};
11223 #define NUM_@var{cname}_VALUES (@var{n} + 1)
11224 @end smallexample
11225
11226 where @var{cname} is the capitalized form of @var{name}.
11227 It also makes each @var{valuei} available in the machine description
11228 file, just as if it had been declared with:
11229
11230 @smallexample
11231 (define_constants [(@var{valuei} @var{i})])
11232 @end smallexample
11233
11234 Each @var{valuei} is usually an upper-case identifier and usually
11235 begins with @var{cname}.
11236
11237 You can split the enumeration definition into as many statements as
11238 you like. The above example is directly equivalent to:
11239
11240 @smallexample
11241 (define_c_enum "@var{name}" [@var{value0}])
11242 (define_c_enum "@var{name}" [@var{value1}])
11243 @dots{}
11244 (define_c_enum "@var{name}" [@var{valuen}])
11245 @end smallexample
11246
11247 Splitting the enumeration helps to improve the modularity of each
11248 individual @code{.md} file. For example, if a port defines its
11249 synchronization instructions in a separate @file{sync.md} file,
11250 it is convenient to define all synchronization-specific enumeration
11251 values in @file{sync.md} rather than in the main @file{.md} file.
11252
11253 Some enumeration names have special significance to GCC:
11254
11255 @table @code
11256 @item unspecv
11257 @findex unspec_volatile
11258 If an enumeration called @code{unspecv} is defined, GCC will use it
11259 when printing out @code{unspec_volatile} expressions. For example:
11260
11261 @smallexample
11262 (define_c_enum "unspecv" [
11263 UNSPECV_BLOCKAGE
11264 ])
11265 @end smallexample
11266
11267 causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:
11268
11269 @smallexample
11270 (unspec_volatile ... UNSPECV_BLOCKAGE)
11271 @end smallexample
11272
11273 @item unspec
11274 @findex unspec
11275 If an enumeration called @code{unspec} is defined, GCC will use
11276 it when printing out @code{unspec} expressions. GCC will also use
11277 it when printing out @code{unspec_volatile} expressions unless an
11278 @code{unspecv} enumeration is also defined. You can therefore
11279 decide whether to keep separate enumerations for volatile and
11280 non-volatile expressions or whether to use the same enumeration
11281 for both.
11282 @end table
11283
11284 @findex define_enum
11285 @anchor{define_enum}
11286 Another way of defining an enumeration is to use @code{define_enum}:
11287
11288 @smallexample
11289 (define_enum "@var{name}" [
11290 @var{value0}
11291 @var{value1}
11292 @dots{}
11293 @var{valuen}
11294 ])
11295 @end smallexample
11296
11297 This directive implies:
11298
11299 @smallexample
11300 (define_c_enum "@var{name}" [
11301 @var{cname}_@var{cvalue0}
11302 @var{cname}_@var{cvalue1}
11303 @dots{}
11304 @var{cname}_@var{cvaluen}
11305 ])
11306 @end smallexample
11307
11308 @findex define_enum_attr
11309 where @var{cvaluei} is the capitalized form of @var{valuei}.
11310 However, unlike @code{define_c_enum}, the enumerations defined
11311 by @code{define_enum} can be used in attribute specifications
11312 (@pxref{define_enum_attr}).
11313 @end ifset
11314 @ifset INTERNALS
11315 @node Iterators
11316 @section Iterators
11317 @cindex iterators in @file{.md} files
11318
11319 Ports often need to define similar patterns for more than one machine
11320 mode or for more than one rtx code. GCC provides some simple iterator
11321 facilities to make this process easier.
11322
11323 @menu
11324 * Mode Iterators:: Generating variations of patterns for different modes.
11325 * Code Iterators:: Doing the same for codes.
11326 * Int Iterators:: Doing the same for integers.
11327 * Subst Iterators:: Generating variations of patterns for define_subst.
11328 * Parameterized Names:: Specifying iterator values in C++ code.
11329 @end menu
11330
11331 @node Mode Iterators
11332 @subsection Mode Iterators
11333 @cindex mode iterators in @file{.md} files
11334
11335 Ports often need to define similar patterns for two or more different modes.
11336 For example:
11337
11338 @itemize @bullet
11339 @item
11340 If a processor has hardware support for both single and double
11341 floating-point arithmetic, the @code{SFmode} patterns tend to be
11342 very similar to the @code{DFmode} ones.
11343
11344 @item
11345 If a port uses @code{SImode} pointers in one configuration and
11346 @code{DImode} pointers in another, it will usually have very similar
11347 @code{SImode} and @code{DImode} patterns for manipulating pointers.
11348 @end itemize
11349
11350 Mode iterators allow several patterns to be instantiated from one
11351 @file{.md} file template. They can be used with any type of
11352 rtx-based construct, such as a @code{define_insn},
11353 @code{define_split}, or @code{define_peephole2}.
11354
11355 @menu
11356 * Defining Mode Iterators:: Defining a new mode iterator.
11357 * Substitutions:: Combining mode iterators with substitutions
11358 * Examples:: Examples
11359 @end menu
11360
11361 @node Defining Mode Iterators
11362 @subsubsection Defining Mode Iterators
11363 @findex define_mode_iterator
11364
11365 The syntax for defining a mode iterator is:
11366
11367 @smallexample
11368 (define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
11369 @end smallexample
11370
11371 This allows subsequent @file{.md} file constructs to use the mode suffix
11372 @code{:@var{name}}. Every construct that does so will be expanded
11373 @var{n} times, once with every use of @code{:@var{name}} replaced by
11374 @code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
11375 and so on. In the expansion for a particular @var{modei}, every
11376 C condition will also require that @var{condi} be true.
11377
11378 For example:
11379
11380 @smallexample
11381 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11382 @end smallexample
11383
11384 defines a new mode suffix @code{:P}. Every construct that uses
11385 @code{:P} will be expanded twice, once with every @code{:P} replaced
11386 by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
11387 The @code{:SI} version will only apply if @code{Pmode == SImode} and
11388 the @code{:DI} version will only apply if @code{Pmode == DImode}.
11389
11390 As with other @file{.md} conditions, an empty string is treated
11391 as ``always true''. @code{(@var{mode} "")} can also be abbreviated
11392 to @code{@var{mode}}. For example:
11393
11394 @smallexample
11395 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11396 @end smallexample
11397
11398 means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
11399 but that the @code{:SI} expansion has no such constraint.
11400
11401 Iterators are applied in the order they are defined. This can be
11402 significant if two iterators are used in a construct that requires
11403 substitutions. @xref{Substitutions}.
11404
11405 @node Substitutions
11406 @subsubsection Substitution in Mode Iterators
11407 @findex define_mode_attr
11408
11409 If an @file{.md} file construct uses mode iterators, each version of the
11410 construct will often need slightly different strings or modes. For
11411 example:
11412
11413 @itemize @bullet
11414 @item
11415 When a @code{define_expand} defines several @code{add@var{m}3} patterns
11416 (@pxref{Standard Names}), each expander will need to use the
11417 appropriate mode name for @var{m}.
11418
11419 @item
11420 When a @code{define_insn} defines several instruction patterns,
11421 each instruction will often use a different assembler mnemonic.
11422
11423 @item
11424 When a @code{define_insn} requires operands with different modes,
11425 using an iterator for one of the operand modes usually requires a specific
11426 mode for the other operand(s).
11427 @end itemize
11428
11429 GCC supports such variations through a system of ``mode attributes''.
11430 There are two standard attributes: @code{mode}, which is the name of
11431 the mode in lower case, and @code{MODE}, which is the same thing in
11432 upper case. You can define other attributes using:
11433
11434 @smallexample
11435 (define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
11436 @end smallexample
11437
11438 where @var{name} is the name of the attribute and @var{valuei}
11439 is the value associated with @var{modei}.
11440
11441 When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
11442 each string and mode in the pattern for sequences of the form
11443 @code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
11444 mode attribute. If the attribute is defined for @var{mode}, the whole
11445 @code{<@dots{}>} sequence will be replaced by the appropriate attribute
11446 value.
11447
11448 For example, suppose an @file{.md} file has:
11449
11450 @smallexample
11451 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11452 (define_mode_attr load [(SI "lw") (DI "ld")])
11453 @end smallexample
11454
11455 If one of the patterns that uses @code{:P} contains the string
11456 @code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
11457 will use @code{"lw\t%0,%1"} and the @code{DI} version will use
11458 @code{"ld\t%0,%1"}.
11459
11460 Here is an example of using an attribute for a mode:
11461
11462 @smallexample
11463 (define_mode_iterator LONG [SI DI])
11464 (define_mode_attr SHORT [(SI "HI") (DI "SI")])
11465 (define_insn @dots{}
11466 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
11467 @end smallexample
11468
11469 The @code{@var{iterator}:} prefix may be omitted, in which case the
11470 substitution will be attempted for every iterator expansion.
11471
11472 @node Examples
11473 @subsubsection Mode Iterator Examples
11474
11475 Here is an example from the MIPS port. It defines the following
11476 modes and attributes (among others):
11477
11478 @smallexample
11479 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11480 (define_mode_attr d [(SI "") (DI "d")])
11481 @end smallexample
11482
11483 and uses the following template to define both @code{subsi3}
11484 and @code{subdi3}:
11485
11486 @smallexample
11487 (define_insn "sub<mode>3"
11488 [(set (match_operand:GPR 0 "register_operand" "=d")
11489 (minus:GPR (match_operand:GPR 1 "register_operand" "d")
11490 (match_operand:GPR 2 "register_operand" "d")))]
11491 ""
11492 "<d>subu\t%0,%1,%2"
11493 [(set_attr "type" "arith")
11494 (set_attr "mode" "<MODE>")])
11495 @end smallexample
11496
11497 This is exactly equivalent to:
11498
11499 @smallexample
11500 (define_insn "subsi3"
11501 [(set (match_operand:SI 0 "register_operand" "=d")
11502 (minus:SI (match_operand:SI 1 "register_operand" "d")
11503 (match_operand:SI 2 "register_operand" "d")))]
11504 ""
11505 "subu\t%0,%1,%2"
11506 [(set_attr "type" "arith")
11507 (set_attr "mode" "SI")])
11508
11509 (define_insn "subdi3"
11510 [(set (match_operand:DI 0 "register_operand" "=d")
11511 (minus:DI (match_operand:DI 1 "register_operand" "d")
11512 (match_operand:DI 2 "register_operand" "d")))]
11513 ""
11514 "dsubu\t%0,%1,%2"
11515 [(set_attr "type" "arith")
11516 (set_attr "mode" "DI")])
11517 @end smallexample
11518
11519 @node Code Iterators
11520 @subsection Code Iterators
11521 @cindex code iterators in @file{.md} files
11522 @findex define_code_iterator
11523 @findex define_code_attr
11524
11525 Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}.
11526
11527 The construct:
11528
11529 @smallexample
11530 (define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
11531 @end smallexample
11532
11533 defines a pseudo rtx code @var{name} that can be instantiated as
11534 @var{codei} if condition @var{condi} is true. Each @var{codei}
11535 must have the same rtx format. @xref{RTL Classes}.
11536
11537 As with mode iterators, each pattern that uses @var{name} will be
11538 expanded @var{n} times, once with all uses of @var{name} replaced by
11539 @var{code1}, once with all uses replaced by @var{code2}, and so on.
11540 @xref{Defining Mode Iterators}.
11541
11542 It is possible to define attributes for codes as well as for modes.
11543 There are two standard code attributes: @code{code}, the name of the
11544 code in lower case, and @code{CODE}, the name of the code in upper case.
11545 Other attributes are defined using:
11546
11547 @smallexample
11548 (define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
11549 @end smallexample
11550
11551 Instruction patterns can use code attributes as rtx codes, which can be
11552 useful if two sets of codes act in tandem. For example, the following
11553 @code{define_insn} defines two patterns, one calculating a signed absolute
11554 difference and another calculating an unsigned absolute difference:
11555
11556 @smallexample
11557 (define_code_iterator any_max [smax umax])
11558 (define_code_attr paired_min [(smax "smin") (umax "umin")])
11559 (define_insn @dots{}
11560 [(set (match_operand:SI 0 @dots{})
11561 (minus:SI (any_max:SI (match_operand:SI 1 @dots{})
11562 (match_operand:SI 2 @dots{}))
11563 (<paired_min>:SI (match_dup 1) (match_dup 2))))]
11564 @dots{})
11565 @end smallexample
11566
11567 The signed version of the instruction uses @code{smax} and @code{smin}
11568 while the unsigned version uses @code{umax} and @code{umin}. There
11569 are no versions that pair @code{smax} with @code{umin} or @code{umax}
11570 with @code{smin}.
11571
11572 Here's an example of code iterators in action, taken from the MIPS port:
11573
11574 @smallexample
11575 (define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
11576 eq ne gt ge lt le gtu geu ltu leu])
11577
11578 (define_expand "b<code>"
11579 [(set (pc)
11580 (if_then_else (any_cond:CC (cc0)
11581 (const_int 0))
11582 (label_ref (match_operand 0 ""))
11583 (pc)))]
11584 ""
11585 @{
11586 gen_conditional_branch (operands, <CODE>);
11587 DONE;
11588 @})
11589 @end smallexample
11590
11591 This is equivalent to:
11592
11593 @smallexample
11594 (define_expand "bunordered"
11595 [(set (pc)
11596 (if_then_else (unordered:CC (cc0)
11597 (const_int 0))
11598 (label_ref (match_operand 0 ""))
11599 (pc)))]
11600 ""
11601 @{
11602 gen_conditional_branch (operands, UNORDERED);
11603 DONE;
11604 @})
11605
11606 (define_expand "bordered"
11607 [(set (pc)
11608 (if_then_else (ordered:CC (cc0)
11609 (const_int 0))
11610 (label_ref (match_operand 0 ""))
11611 (pc)))]
11612 ""
11613 @{
11614 gen_conditional_branch (operands, ORDERED);
11615 DONE;
11616 @})
11617
11618 @dots{}
11619 @end smallexample
11620
11621 @node Int Iterators
11622 @subsection Int Iterators
11623 @cindex int iterators in @file{.md} files
11624 @findex define_int_iterator
11625 @findex define_int_attr
11626
11627 Int iterators operate in a similar way to code iterators. @xref{Code Iterators}.
11628
11629 The construct:
11630
11631 @smallexample
11632 (define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")])
11633 @end smallexample
11634
11635 defines a pseudo integer constant @var{name} that can be instantiated as
11636 @var{inti} if condition @var{condi} is true. Each @var{int} must have the
11637 same rtx format. @xref{RTL Classes}. Int iterators can appear in only
11638 those rtx fields that have 'i', 'n', 'w', or 'p' as the specifier. This
11639 means that each @var{int} has to be a constant defined using define_constant
11640 or define_c_enum.
11641
11642 As with mode and code iterators, each pattern that uses @var{name} will be
11643 expanded @var{n} times, once with all uses of @var{name} replaced by
11644 @var{int1}, once with all uses replaced by @var{int2}, and so on.
11645 @xref{Defining Mode Iterators}.
11646
11647 It is possible to define attributes for ints as well as for codes and modes.
11648 Attributes are defined using:
11649
11650 @smallexample
11651 (define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")])
11652 @end smallexample
11653
11654 Here's an example of int iterators in action, taken from the ARM port:
11655
11656 @smallexample
11657 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
11658
11659 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
11660
11661 (define_insn "neon_vq<absneg><mode>"
11662 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11663 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11664 (match_operand:SI 2 "immediate_operand" "i")]
11665 QABSNEG))]
11666 "TARGET_NEON"
11667 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
11668 [(set_attr "type" "neon_vqneg_vqabs")]
11669 )
11670
11671 @end smallexample
11672
11673 This is equivalent to:
11674
11675 @smallexample
11676 (define_insn "neon_vqabs<mode>"
11677 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11678 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11679 (match_operand:SI 2 "immediate_operand" "i")]
11680 UNSPEC_VQABS))]
11681 "TARGET_NEON"
11682 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
11683 [(set_attr "type" "neon_vqneg_vqabs")]
11684 )
11685
11686 (define_insn "neon_vqneg<mode>"
11687 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11688 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11689 (match_operand:SI 2 "immediate_operand" "i")]
11690 UNSPEC_VQNEG))]
11691 "TARGET_NEON"
11692 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
11693 [(set_attr "type" "neon_vqneg_vqabs")]
11694 )
11695
11696 @end smallexample
11697
11698 @node Subst Iterators
11699 @subsection Subst Iterators
11700 @cindex subst iterators in @file{.md} files
11701 @findex define_subst
11702 @findex define_subst_attr
11703
11704 Subst iterators are special type of iterators with the following
11705 restrictions: they could not be declared explicitly, they always have
11706 only two values, and they do not have explicit dedicated name.
11707 Subst-iterators are triggered only when corresponding subst-attribute is
11708 used in RTL-pattern.
11709
11710 Subst iterators transform templates in the following way: the templates
11711 are duplicated, the subst-attributes in these templates are replaced
11712 with the corresponding values, and a new attribute is implicitly added
11713 to the given @code{define_insn}/@code{define_expand}. The name of the
11714 added attribute matches the name of @code{define_subst}. Such
11715 attributes are declared implicitly, and it is not allowed to have a
11716 @code{define_attr} named as a @code{define_subst}.
11717
11718 Each subst iterator is linked to a @code{define_subst}. It is declared
11719 implicitly by the first appearance of the corresponding
11720 @code{define_subst_attr}, and it is not allowed to define it explicitly.
11721
11722 Declarations of subst-attributes have the following syntax:
11723
11724 @findex define_subst_attr
11725 @smallexample
11726 (define_subst_attr "@var{name}"
11727 "@var{subst-name}"
11728 "@var{no-subst-value}"
11729 "@var{subst-applied-value}")
11730 @end smallexample
11731
11732 @var{name} is a string with which the given subst-attribute could be
11733 referred to.
11734
11735 @var{subst-name} shows which @code{define_subst} should be applied to an
11736 RTL-template if the given subst-attribute is present in the
11737 RTL-template.
11738
11739 @var{no-subst-value} is a value with which subst-attribute would be
11740 replaced in the first copy of the original RTL-template.
11741
11742 @var{subst-applied-value} is a value with which subst-attribute would be
11743 replaced in the second copy of the original RTL-template.
11744
11745 @node Parameterized Names
11746 @subsection Parameterized Names
11747 @cindex @samp{@@} in instruction pattern names
11748 Ports sometimes need to apply iterators using C++ code, in order to
11749 get the code or RTL pattern for a specific instruction. For example,
11750 suppose we have the @samp{neon_vq<absneg><mode>} pattern given above:
11751
11752 @smallexample
11753 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
11754
11755 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
11756
11757 (define_insn "neon_vq<absneg><mode>"
11758 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11759 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11760 (match_operand:SI 2 "immediate_operand" "i")]
11761 QABSNEG))]
11762 @dots{}
11763 )
11764 @end smallexample
11765
11766 A port might need to generate this pattern for a variable
11767 @samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two
11768 ways of doing this. The first is to build the rtx for the pattern
11769 directly from C++ code; this is a valid technique and avoids any risk
11770 of combinatorial explosion. The second is to prefix the instruction
11771 name with the special character @samp{@@}, which tells GCC to generate
11772 the four additional functions below. In each case, @var{name} is the
11773 name of the instruction without the leading @samp{@@} character,
11774 without the @samp{<@dots{}>} placeholders, and with any underscore
11775 before a @samp{<@dots{}>} placeholder removed if keeping it would
11776 lead to a double or trailing underscore.
11777
11778 @table @samp
11779 @item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
11780 See whether replacing the first @samp{<@dots{}>} placeholder with
11781 iterator value @var{i1}, the second with iterator value @var{i2}, and
11782 so on, gives a valid instruction. Return its code if so, otherwise
11783 return @code{CODE_FOR_nothing}.
11784
11785 @item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
11786 Same, but abort the compiler if the requested instruction does not exist.
11787
11788 @item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
11789 Check for a valid instruction in the same way as
11790 @code{maybe_code_for_@var{name}}. If the instruction exists,
11791 generate an instance of it using the operand values given by @var{op0},
11792 @var{op1}, and so on, otherwise return null.
11793
11794 @item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
11795 Same, but abort the compiler if the requested instruction does not exist,
11796 or if the instruction generator invoked the @code{FAIL} macro.
11797 @end table
11798
11799 For example, changing the pattern above to:
11800
11801 @smallexample
11802 (define_insn "@@neon_vq<absneg><mode>"
11803 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11804 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11805 (match_operand:SI 2 "immediate_operand" "i")]
11806 QABSNEG))]
11807 @dots{}
11808 )
11809 @end smallexample
11810
11811 would define the same patterns as before, but in addition would generate
11812 the four functions below:
11813
11814 @smallexample
11815 insn_code maybe_code_for_neon_vq (int, machine_mode);
11816 insn_code code_for_neon_vq (int, machine_mode);
11817 rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
11818 rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
11819 @end smallexample
11820
11821 Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)}
11822 would then give @code{CODE_FOR_neon_vqabsv8qi}.
11823
11824 It is possible to have multiple @samp{@@} patterns with the same
11825 name and same types of iterator. For example:
11826
11827 @smallexample
11828 (define_insn "@@some_arithmetic_op<mode>"
11829 [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})]
11830 @dots{}
11831 )
11832
11833 (define_insn "@@some_arithmetic_op<mode>"
11834 [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})]
11835 @dots{}
11836 )
11837 @end smallexample
11838
11839 would produce a single set of functions that handles both
11840 @code{INTEGER_MODES} and @code{FLOAT_MODES}.
11841
11842 It is also possible for these @samp{@@} patterns to have different
11843 numbers of operands from each other. For example, patterns with
11844 a binary rtl code might take three operands (one output and two inputs)
11845 while patterns with a ternary rtl code might take four operands (one
11846 output and three inputs). This combination would produce separate
11847 @samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for
11848 each operand count, but it would still produce a single
11849 @samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}.
11850
11851 @end ifset