Debian Codegraph @

gcc/doc/md.texi

raw
1 @c Copyright (C) 1988-2023 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
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 @cindex pattern conditions
160 @cindex conditions, in patterns
161 @item
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_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 a later section (@pxref{Modifiers}).
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 @itemx Q
2197 Any SYMBOL_REF.
2198 @end table
2199
2200 @item C-SKY---@file{config/csky/constraints.md}
2201 @table @code
2202
2203 @item a
2204 The mini registers r0 - r7.
2205
2206 @item b
2207 The low registers r0 - r15.
2208
2209 @item c
2210 C register.
2211
2212 @item y
2213 HI and LO registers.
2214
2215 @item l
2216 LO register.
2217
2218 @item h
2219 HI register.
2220
2221 @item v
2222 Vector registers.
2223
2224 @item z
2225 Stack pointer register (SP).
2226
2227 @item Q
2228 A memory address which uses a base register with a short offset
2229 or with a index register with its scale.
2230
2231 @item W
2232 A memory address which uses a base register with a index register
2233 with its scale.
2234 @end table
2235
2236 @ifset INTERNALS
2237 The C-SKY back end supports a large set of additional constraints
2238 that are only useful for instruction selection or splitting rather
2239 than inline asm, such as constraints representing constant integer
2240 ranges accepted by particular instruction encodings.
2241 Refer to the source code for details.
2242 @end ifset
2243
2244 @item Epiphany---@file{config/epiphany/constraints.md}
2245 @table @code
2246 @item U16
2247 An unsigned 16-bit constant.
2248
2249 @item K
2250 An unsigned 5-bit constant.
2251
2252 @item L
2253 A signed 11-bit constant.
2254
2255 @item Cm1
2256 A signed 11-bit constant added to @minus{}1.
2257 Can only match when the @option{-m1reg-@var{reg}} option is active.
2258
2259 @item Cl1
2260 Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
2261 being a block of trailing zeroes.
2262 Can only match when the @option{-m1reg-@var{reg}} option is active.
2263
2264 @item Cr1
2265 Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
2266 rest being zeroes. Or to put it another way, one less than a power of two.
2267 Can only match when the @option{-m1reg-@var{reg}} option is active.
2268
2269 @item Cal
2270 Constant for arithmetic/logical operations.
2271 This is like @code{i}, except that for position independent code,
2272 no symbols / expressions needing relocations are allowed.
2273
2274 @item Csy
2275 Symbolic constant for call/jump instruction.
2276
2277 @item Rcs
2278 The register class usable in short insns. This is a register class
2279 constraint, and can thus drive register allocation.
2280 This constraint won't match unless @option{-mprefer-short-insn-regs} is
2281 in effect.
2282
2283 @item Rsc
2284 The register class of registers that can be used to hold a
2285 sibcall call address. I.e., a caller-saved register.
2286
2287 @item Rct
2288 Core control register class.
2289
2290 @item Rgs
2291 The register group usable in short insns.
2292 This constraint does not use a register class, so that it only
2293 passively matches suitable registers, and doesn't drive register allocation.
2294
2295 @ifset INTERNALS
2296 @item Car
2297 Constant suitable for the addsi3_r pattern. This is a valid offset
2298 For byte, halfword, or word addressing.
2299 @end ifset
2300
2301 @item Rra
2302 Matches the return address if it can be replaced with the link register.
2303
2304 @item Rcc
2305 Matches the integer condition code register.
2306
2307 @item Sra
2308 Matches the return address if it is in a stack slot.
2309
2310 @item Cfm
2311 Matches control register values to switch fp mode, which are encapsulated in
2312 @code{UNSPEC_FP_MODE}.
2313 @end table
2314
2315 @item FRV---@file{config/frv/frv.h}
2316 @table @code
2317 @item a
2318 Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).
2319
2320 @item b
2321 Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).
2322
2323 @item c
2324 Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
2325 @code{icc0} to @code{icc3}).
2326
2327 @item d
2328 Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).
2329
2330 @item e
2331 Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
2332 Odd registers are excluded not in the class but through the use of a machine
2333 mode larger than 4 bytes.
2334
2335 @item f
2336 Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).
2337
2338 @item h
2339 Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
2340 Odd registers are excluded not in the class but through the use of a machine
2341 mode larger than 4 bytes.
2342
2343 @item l
2344 Register in the class @code{LR_REG} (the @code{lr} register).
2345
2346 @item q
2347 Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
2348 Register numbers not divisible by 4 are excluded not in the class but through
2349 the use of a machine mode larger than 8 bytes.
2350
2351 @item t
2352 Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).
2353
2354 @item u
2355 Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).
2356
2357 @item v
2358 Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).
2359
2360 @item w
2361 Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).
2362
2363 @item x
2364 Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
2365 Register numbers not divisible by 4 are excluded not in the class but through
2366 the use of a machine mode larger than 8 bytes.
2367
2368 @item z
2369 Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).
2370
2371 @item A
2372 Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).
2373
2374 @item B
2375 Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).
2376
2377 @item C
2378 Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).
2379
2380 @item G
2381 Floating point constant zero
2382
2383 @item I
2384 6-bit signed integer constant
2385
2386 @item J
2387 10-bit signed integer constant
2388
2389 @item L
2390 16-bit signed integer constant
2391
2392 @item M
2393 16-bit unsigned integer constant
2394
2395 @item N
2396 12-bit signed integer constant that is negative---i.e.@: in the
2397 range of @minus{}2048 to @minus{}1
2398
2399 @item O
2400 Constant zero
2401
2402 @item P
2403 12-bit signed integer constant that is greater than zero---i.e.@: in the
2404 range of 1 to 2047.
2405
2406 @end table
2407
2408 @item FT32---@file{config/ft32/constraints.md}
2409 @table @code
2410 @item A
2411 An absolute address
2412
2413 @item B
2414 An offset address
2415
2416 @item W
2417 A register indirect memory operand
2418
2419 @item e
2420 An offset address.
2421
2422 @item f
2423 An offset address.
2424
2425 @item O
2426 The constant zero or one
2427
2428 @item I
2429 A 16-bit signed constant (@minus{}32768 @dots{} 32767)
2430
2431 @item w
2432 A bitfield mask suitable for bext or bins
2433
2434 @item x
2435 An inverted bitfield mask suitable for bext or bins
2436
2437 @item L
2438 A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532)
2439
2440 @item S
2441 A 20-bit signed constant (@minus{}524288 @dots{} 524287)
2442
2443 @item b
2444 A constant for a bitfield width (1 @dots{} 16)
2445
2446 @item KA
2447 A 10-bit signed constant (@minus{}512 @dots{} 511)
2448
2449 @end table
2450
2451 @item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
2452 @table @code
2453 @item a
2454 General register 1
2455
2456 @item f
2457 Floating point register
2458
2459 @item q
2460 Shift amount register
2461
2462 @item x
2463 Floating point register (deprecated)
2464
2465 @item y
2466 Upper floating point register (32-bit), floating point register (64-bit)
2467
2468 @item Z
2469 Any register
2470
2471 @item I
2472 Signed 11-bit integer constant
2473
2474 @item J
2475 Signed 14-bit integer constant
2476
2477 @item K
2478 Integer constant that can be deposited with a @code{zdepi} instruction
2479
2480 @item L
2481 Signed 5-bit integer constant
2482
2483 @item M
2484 Integer constant 0
2485
2486 @item N
2487 Integer constant that can be loaded with a @code{ldil} instruction
2488
2489 @item O
2490 Integer constant whose value plus one is a power of 2
2491
2492 @item P
2493 Integer constant that can be used for @code{and} operations in @code{depi}
2494 and @code{extru} instructions
2495
2496 @item S
2497 Integer constant 31
2498
2499 @item U
2500 Integer constant 63
2501
2502 @item G
2503 Floating-point constant 0.0
2504
2505 @item A
2506 A @code{lo_sum} data-linkage-table memory operand
2507
2508 @item Q
2509 A memory operand that can be used as the destination operand of an
2510 integer store instruction
2511
2512 @item R
2513 A scaled or unscaled indexed memory operand
2514
2515 @item T
2516 A memory operand for floating-point loads and stores
2517
2518 @item W
2519 A register indirect memory operand
2520 @end table
2521
2522 @item Intel IA-64---@file{config/ia64/ia64.h}
2523 @table @code
2524 @item a
2525 General register @code{r0} to @code{r3} for @code{addl} instruction
2526
2527 @item b
2528 Branch register
2529
2530 @item c
2531 Predicate register (@samp{c} as in ``conditional'')
2532
2533 @item d
2534 Application register residing in M-unit
2535
2536 @item e
2537 Application register residing in I-unit
2538
2539 @item f
2540 Floating-point register
2541
2542 @item m
2543 Memory operand. If used together with @samp{<} or @samp{>},
2544 the operand can have postincrement and postdecrement which
2545 require printing with @samp{%Pn} on IA-64.
2546
2547 @item G
2548 Floating-point constant 0.0 or 1.0
2549
2550 @item I
2551 14-bit signed integer constant
2552
2553 @item J
2554 22-bit signed integer constant
2555
2556 @item K
2557 8-bit signed integer constant for logical instructions
2558
2559 @item L
2560 8-bit adjusted signed integer constant for compare pseudo-ops
2561
2562 @item M
2563 6-bit unsigned integer constant for shift counts
2564
2565 @item N
2566 9-bit signed integer constant for load and store postincrements
2567
2568 @item O
2569 The constant zero
2570
2571 @item P
2572 0 or @minus{}1 for @code{dep} instruction
2573
2574 @item Q
2575 Non-volatile memory for floating-point loads and stores
2576
2577 @item R
2578 Integer constant in the range 1 to 4 for @code{shladd} instruction
2579
2580 @item S
2581 Memory operand except postincrement and postdecrement. This is
2582 now roughly the same as @samp{m} when not used together with @samp{<}
2583 or @samp{>}.
2584 @end table
2585
2586 @item M32C---@file{config/m32c/m32c.cc}
2587 @table @code
2588 @item Rsp
2589 @itemx Rfb
2590 @itemx Rsb
2591 @samp{$sp}, @samp{$fb}, @samp{$sb}.
2592
2593 @item Rcr
2594 Any control register, when they're 16 bits wide (nothing if control
2595 registers are 24 bits wide)
2596
2597 @item Rcl
2598 Any control register, when they're 24 bits wide.
2599
2600 @item R0w
2601 @itemx R1w
2602 @itemx R2w
2603 @itemx R3w
2604 $r0, $r1, $r2, $r3.
2605
2606 @item R02
2607 $r0 or $r2, or $r2r0 for 32 bit values.
2608
2609 @item R13
2610 $r1 or $r3, or $r3r1 for 32 bit values.
2611
2612 @item Rdi
2613 A register that can hold a 64 bit value.
2614
2615 @item Rhl
2616 $r0 or $r1 (registers with addressable high/low bytes)
2617
2618 @item R23
2619 $r2 or $r3
2620
2621 @item Raa
2622 Address registers
2623
2624 @item Raw
2625 Address registers when they're 16 bits wide.
2626
2627 @item Ral
2628 Address registers when they're 24 bits wide.
2629
2630 @item Rqi
2631 Registers that can hold QI values.
2632
2633 @item Rad
2634 Registers that can be used with displacements ($a0, $a1, $sb).
2635
2636 @item Rsi
2637 Registers that can hold 32 bit values.
2638
2639 @item Rhi
2640 Registers that can hold 16 bit values.
2641
2642 @item Rhc
2643 Registers chat can hold 16 bit values, including all control
2644 registers.
2645
2646 @item Rra
2647 $r0 through R1, plus $a0 and $a1.
2648
2649 @item Rfl
2650 The flags register.
2651
2652 @item Rmm
2653 The memory-based pseudo-registers $mem0 through $mem15.
2654
2655 @item Rpi
2656 Registers that can hold pointers (16 bit registers for r8c, m16c; 24
2657 bit registers for m32cm, m32c).
2658
2659 @item Rpa
2660 Matches multiple registers in a PARALLEL to form a larger register.
2661 Used to match function return values.
2662
2663 @item Is3
2664 @minus{}8 @dots{} 7
2665
2666 @item IS1
2667 @minus{}128 @dots{} 127
2668
2669 @item IS2
2670 @minus{}32768 @dots{} 32767
2671
2672 @item IU2
2673 0 @dots{} 65535
2674
2675 @item In4
2676 @minus{}8 @dots{} @minus{}1 or 1 @dots{} 8
2677
2678 @item In5
2679 @minus{}16 @dots{} @minus{}1 or 1 @dots{} 16
2680
2681 @item In6
2682 @minus{}32 @dots{} @minus{}1 or 1 @dots{} 32
2683
2684 @item IM2
2685 @minus{}65536 @dots{} @minus{}1
2686
2687 @item Ilb
2688 An 8 bit value with exactly one bit set.
2689
2690 @item Ilw
2691 A 16 bit value with exactly one bit set.
2692
2693 @item Sd
2694 The common src/dest memory addressing modes.
2695
2696 @item Sa
2697 Memory addressed using $a0 or $a1.
2698
2699 @item Si
2700 Memory addressed with immediate addresses.
2701
2702 @item Ss
2703 Memory addressed using the stack pointer ($sp).
2704
2705 @item Sf
2706 Memory addressed using the frame base register ($fb).
2707
2708 @item Ss
2709 Memory addressed using the small base register ($sb).
2710
2711 @item S1
2712 $r1h
2713 @end table
2714
2715 @item LoongArch---@file{config/loongarch/constraints.md}
2716 @table @code
2717 @item f
2718 A floating-point register (if available).
2719 @item k
2720 A memory operand whose address is formed by a base register and
2721 (optionally scaled) index register.
2722 @item l
2723 A signed 16-bit constant.
2724 @item m
2725 A memory operand whose address is formed by a base register and offset
2726 that is suitable for use in instructions with the same addressing mode
2727 as @code{st.w} and @code{ld.w}.
2728 @item I
2729 A signed 12-bit constant (for arithmetic instructions).
2730 @item K
2731 An unsigned 12-bit constant (for logic instructions).
2732 @item ZB
2733 An address that is held in a general-purpose register.
2734 The offset is zero.
2735 @item ZC
2736 A memory operand whose address is formed by a base register and offset
2737 that is suitable for use in instructions with the same addressing mode
2738 as @code{ll.w} and @code{sc.w}.
2739 @end table
2740
2741 @item MicroBlaze---@file{config/microblaze/constraints.md}
2742 @table @code
2743 @item d
2744 A general register (@code{r0} to @code{r31}).
2745
2746 @item z
2747 A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).
2748
2749 @end table
2750
2751 @item MIPS---@file{config/mips/constraints.md}
2752 @table @code
2753 @item d
2754 A general-purpose register. This is equivalent to @code{r} unless
2755 generating MIPS16 code, in which case the MIPS16 register set is used.
2756
2757 @item f
2758 A floating-point register (if available).
2759
2760 @item h
2761 Formerly the @code{hi} register. This constraint is no longer supported.
2762
2763 @item l
2764 The @code{lo} register. Use this register to store values that are
2765 no bigger than a word.
2766
2767 @item x
2768 The concatenated @code{hi} and @code{lo} registers. Use this register
2769 to store doubleword values.
2770
2771 @item c
2772 A register suitable for use in an indirect jump. This will always be
2773 @code{$25} for @option{-mabicalls}.
2774
2775 @item v
2776 Register @code{$3}. Do not use this constraint in new code;
2777 it is retained only for compatibility with glibc.
2778
2779 @item y
2780 Equivalent to @code{r}; retained for backwards compatibility.
2781
2782 @item z
2783 A floating-point condition code register.
2784
2785 @item I
2786 A signed 16-bit constant (for arithmetic instructions).
2787
2788 @item J
2789 Integer zero.
2790
2791 @item K
2792 An unsigned 16-bit constant (for logic instructions).
2793
2794 @item L
2795 A signed 32-bit constant in which the lower 16 bits are zero.
2796 Such constants can be loaded using @code{lui}.
2797
2798 @item M
2799 A constant that cannot be loaded using @code{lui}, @code{addiu}
2800 or @code{ori}.
2801
2802 @item N
2803 A constant in the range @minus{}65535 to @minus{}1 (inclusive).
2804
2805 @item O
2806 A signed 15-bit constant.
2807
2808 @item P
2809 A constant in the range 1 to 65535 (inclusive).
2810
2811 @item G
2812 Floating-point zero.
2813
2814 @item R
2815 An address that can be used in a non-macro load or store.
2816
2817 @item ZC
2818 A memory operand whose address is formed by a base register and offset
2819 that is suitable for use in instructions with the same addressing mode
2820 as @code{ll} and @code{sc}.
2821
2822 @item ZD
2823 An address suitable for a @code{prefetch} instruction, or for any other
2824 instruction with the same addressing mode as @code{prefetch}.
2825 @end table
2826
2827 @item Motorola 680x0---@file{config/m68k/constraints.md}
2828 @table @code
2829 @item a
2830 Address register
2831
2832 @item d
2833 Data register
2834
2835 @item f
2836 68881 floating-point register, if available
2837
2838 @item I
2839 Integer in the range 1 to 8
2840
2841 @item J
2842 16-bit signed number
2843
2844 @item K
2845 Signed number whose magnitude is greater than 0x80
2846
2847 @item L
2848 Integer in the range @minus{}8 to @minus{}1
2849
2850 @item M
2851 Signed number whose magnitude is greater than 0x100
2852
2853 @item N
2854 Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate
2855
2856 @item O
2857 16 (for rotate using swap)
2858
2859 @item P
2860 Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate
2861
2862 @item R
2863 Numbers that mov3q can handle
2864
2865 @item G
2866 Floating point constant that is not a 68881 constant
2867
2868 @item S
2869 Operands that satisfy 'm' when -mpcrel is in effect
2870
2871 @item T
2872 Operands that satisfy 's' when -mpcrel is not in effect
2873
2874 @item Q
2875 Address register indirect addressing mode
2876
2877 @item U
2878 Register offset addressing
2879
2880 @item W
2881 const_call_operand
2882
2883 @item Cs
2884 symbol_ref or const
2885
2886 @item Ci
2887 const_int
2888
2889 @item C0
2890 const_int 0
2891
2892 @item Cj
2893 Range of signed numbers that don't fit in 16 bits
2894
2895 @item Cmvq
2896 Integers valid for mvq
2897
2898 @item Capsw
2899 Integers valid for a moveq followed by a swap
2900
2901 @item Cmvz
2902 Integers valid for mvz
2903
2904 @item Cmvs
2905 Integers valid for mvs
2906
2907 @item Ap
2908 push_operand
2909
2910 @item Ac
2911 Non-register operands allowed in clr
2912
2913 @end table
2914
2915 @item Moxie---@file{config/moxie/constraints.md}
2916 @table @code
2917 @item A
2918 An absolute address
2919
2920 @item B
2921 An offset address
2922
2923 @item W
2924 A register indirect memory operand
2925
2926 @item I
2927 A constant in the range of 0 to 255.
2928
2929 @item N
2930 A constant in the range of 0 to @minus{}255.
2931
2932 @end table
2933
2934 @item MSP430--@file{config/msp430/constraints.md}
2935 @table @code
2936
2937 @item R12
2938 Register R12.
2939
2940 @item R13
2941 Register R13.
2942
2943 @item K
2944 Integer constant 1.
2945
2946 @item L
2947 Integer constant -1^20..1^19.
2948
2949 @item M
2950 Integer constant 1-4.
2951
2952 @item Ya
2953 Memory references which do not require an extended MOVX instruction.
2954
2955 @item Yl
2956 Memory reference, labels only.
2957
2958 @item Ys
2959 Memory reference, stack only.
2960
2961 @end table
2962
2963 @item NDS32---@file{config/nds32/constraints.md}
2964 @table @code
2965 @item w
2966 LOW register class $r0 to $r7 constraint for V3/V3M ISA.
2967 @item l
2968 LOW register class $r0 to $r7.
2969 @item d
2970 MIDDLE register class $r0 to $r11, $r16 to $r19.
2971 @item h
2972 HIGH register class $r12 to $r14, $r20 to $r31.
2973 @item t
2974 Temporary assist register $ta (i.e.@: $r15).
2975 @item k
2976 Stack register $sp.
2977 @item Iu03
2978 Unsigned immediate 3-bit value.
2979 @item In03
2980 Negative immediate 3-bit value in the range of @minus{}7--0.
2981 @item Iu04
2982 Unsigned immediate 4-bit value.
2983 @item Is05
2984 Signed immediate 5-bit value.
2985 @item Iu05
2986 Unsigned immediate 5-bit value.
2987 @item In05
2988 Negative immediate 5-bit value in the range of @minus{}31--0.
2989 @item Ip05
2990 Unsigned immediate 5-bit value for movpi45 instruction with range 16--47.
2991 @item Iu06
2992 Unsigned immediate 6-bit value constraint for addri36.sp instruction.
2993 @item Iu08
2994 Unsigned immediate 8-bit value.
2995 @item Iu09
2996 Unsigned immediate 9-bit value.
2997 @item Is10
2998 Signed immediate 10-bit value.
2999 @item Is11
3000 Signed immediate 11-bit value.
3001 @item Is15
3002 Signed immediate 15-bit value.
3003 @item Iu15
3004 Unsigned immediate 15-bit value.
3005 @item Ic15
3006 A constant which is not in the range of imm15u but ok for bclr instruction.
3007 @item Ie15
3008 A constant which is not in the range of imm15u but ok for bset instruction.
3009 @item It15
3010 A constant which is not in the range of imm15u but ok for btgl instruction.
3011 @item Ii15
3012 A constant whose compliment value is in the range of imm15u
3013 and ok for bitci instruction.
3014 @item Is16
3015 Signed immediate 16-bit value.
3016 @item Is17
3017 Signed immediate 17-bit value.
3018 @item Is19
3019 Signed immediate 19-bit value.
3020 @item Is20
3021 Signed immediate 20-bit value.
3022 @item Ihig
3023 The immediate value that can be simply set high 20-bit.
3024 @item Izeb
3025 The immediate value 0xff.
3026 @item Izeh
3027 The immediate value 0xffff.
3028 @item Ixls
3029 The immediate value 0x01.
3030 @item Ix11
3031 The immediate value 0x7ff.
3032 @item Ibms
3033 The immediate value with power of 2.
3034 @item Ifex
3035 The immediate value with power of 2 minus 1.
3036 @item U33
3037 Memory constraint for 333 format.
3038 @item U45
3039 Memory constraint for 45 format.
3040 @item U37
3041 Memory constraint for 37 format.
3042 @end table
3043
3044 @item Nios II family---@file{config/nios2/constraints.md}
3045 @table @code
3046
3047 @item I
3048 Integer that is valid as an immediate operand in an
3049 instruction taking a signed 16-bit number. Range
3050 @minus{}32768 to 32767.
3051
3052 @item J
3053 Integer that is valid as an immediate operand in an
3054 instruction taking an unsigned 16-bit number. Range
3055 0 to 65535.
3056
3057 @item K
3058 Integer that is valid as an immediate operand in an
3059 instruction taking only the upper 16-bits of a
3060 32-bit number. Range 32-bit numbers with the lower
3061 16-bits being 0.
3062
3063 @item L
3064 Integer that is valid as an immediate operand for a
3065 shift instruction. Range 0 to 31.
3066
3067 @item M
3068 Integer that is valid as an immediate operand for
3069 only the value 0. Can be used in conjunction with
3070 the format modifier @code{z} to use @code{r0}
3071 instead of @code{0} in the assembly output.
3072
3073 @item N
3074 Integer that is valid as an immediate operand for
3075 a custom instruction opcode. Range 0 to 255.
3076
3077 @item P
3078 An immediate operand for R2 andchi/andci instructions.
3079
3080 @item S
3081 Matches immediates which are addresses in the small
3082 data section and therefore can be added to @code{gp}
3083 as a 16-bit immediate to re-create their 32-bit value.
3084
3085 @item U
3086 Matches constants suitable as an operand for the rdprs and
3087 cache instructions.
3088
3089 @item v
3090 A memory operand suitable for Nios II R2 load/store
3091 exclusive instructions.
3092
3093 @item w
3094 A memory operand suitable for load/store IO and cache
3095 instructions.
3096
3097 @ifset INTERNALS
3098 @item T
3099 A @code{const} wrapped @code{UNSPEC} expression,
3100 representing a supported PIC or TLS relocation.
3101 @end ifset
3102
3103 @end table
3104
3105 @item OpenRISC---@file{config/or1k/constraints.md}
3106 @table @code
3107 @item I
3108 Integer that is valid as an immediate operand in an
3109 instruction taking a signed 16-bit number. Range
3110 @minus{}32768 to 32767.
3111
3112 @item K
3113 Integer that is valid as an immediate operand in an
3114 instruction taking an unsigned 16-bit number. Range
3115 0 to 65535.
3116
3117 @item M
3118 Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi})
3119
3120 @item O
3121 Zero
3122
3123 @ifset INTERNALS
3124 @item c
3125 Register usable for sibcalls.
3126 @end ifset
3127
3128 @end table
3129
3130 @item PDP-11---@file{config/pdp11/constraints.md}
3131 @table @code
3132 @item a
3133 Floating point registers AC0 through AC3. These can be loaded from/to
3134 memory with a single instruction.
3135
3136 @item d
3137 Odd numbered general registers (R1, R3, R5). These are used for
3138 16-bit multiply operations.
3139
3140 @item D
3141 A memory reference that is encoded within the opcode, but not
3142 auto-increment or auto-decrement.
3143
3144 @item f
3145 Any of the floating point registers (AC0 through AC5).
3146
3147 @item G
3148 Floating point constant 0.
3149
3150 @item h
3151 Floating point registers AC4 and AC5. These cannot be loaded from/to
3152 memory with a single instruction.
3153
3154 @item I
3155 An integer constant that fits in 16 bits.
3156
3157 @item J
3158 An integer constant whose low order 16 bits are zero.
3159
3160 @item K
3161 An integer constant that does not meet the constraints for codes
3162 @samp{I} or @samp{J}.
3163
3164 @item L
3165 The integer constant 1.
3166
3167 @item M
3168 The integer constant @minus{}1.
3169
3170 @item N
3171 The integer constant 0.
3172
3173 @item O
3174 Integer constants 0 through 3; shifts by these
3175 amounts are handled as multiple single-bit shifts rather than a single
3176 variable-length shift.
3177
3178 @item Q
3179 A memory reference which requires an additional word (address or
3180 offset) after the opcode.
3181
3182 @item R
3183 A memory reference that is encoded within the opcode.
3184
3185 @end table
3186
3187 @item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md}
3188 @table @code
3189 @item r
3190 A general purpose register (GPR), @code{r0}@dots{}@code{r31}.
3191
3192 @item b
3193 A base register. Like @code{r}, but @code{r0} is not allowed, so
3194 @code{r1}@dots{}@code{r31}.
3195
3196 @item f
3197 A floating point register (FPR), @code{f0}@dots{}@code{f31}.
3198
3199 @item d
3200 A floating point register. This is the same as @code{f} nowadays;
3201 historically @code{f} was for single-precision and @code{d} was for
3202 double-precision floating point.
3203
3204 @item v
3205 An Altivec vector register (VR), @code{v0}@dots{}@code{v31}.
3206
3207 @item wa
3208 A VSX register (VSR), @code{vs0}@dots{}@code{vs63}. This is either an
3209 FPR (@code{vs0}@dots{}@code{vs31} are @code{f0}@dots{}@code{f31}) or a VR
3210 (@code{vs32}@dots{}@code{vs63} are @code{v0}@dots{}@code{v31}).
3211
3212 When using @code{wa}, you should use the @code{%x} output modifier, so that
3213 the correct register number is printed. For example:
3214
3215 @smallexample
3216 asm ("xvadddp %x0,%x1,%x2"
3217 : "=wa" (v1)
3218 : "wa" (v2), "wa" (v3));
3219 @end smallexample
3220
3221 You should not use @code{%x} for @code{v} operands:
3222
3223 @smallexample
3224 asm ("xsaddqp %0,%1,%2"
3225 : "=v" (v1)
3226 : "v" (v2), "v" (v3));
3227 @end smallexample
3228
3229 @ifset INTERNALS
3230 @item h
3231 A special register (@code{vrsave}, @code{ctr}, or @code{lr}).
3232 @end ifset
3233
3234 @item c
3235 The count register, @code{ctr}.
3236
3237 @item l
3238 The link register, @code{lr}.
3239
3240 @item x
3241 Condition register field 0, @code{cr0}.
3242
3243 @item y
3244 Any condition register field, @code{cr0}@dots{}@code{cr7}.
3245
3246 @ifset INTERNALS
3247 @item z
3248 The carry bit, @code{XER[CA]}.
3249
3250 @item we
3251 Like @code{wa}, if @option{-mpower9-vector} and @option{-m64} are used;
3252 otherwise, @code{NO_REGS}.
3253
3254 @item wn
3255 No register (@code{NO_REGS}).
3256
3257 @item wr
3258 Like @code{r}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3259
3260 @item wx
3261 Like @code{d}, if @option{-mpowerpc-gfxopt} is used; otherwise, @code{NO_REGS}.
3262
3263 @item wA
3264 Like @code{b}, if @option{-mpowerpc64} is used; otherwise, @code{NO_REGS}.
3265
3266 @item wB
3267 Signed 5-bit constant integer that can be loaded into an Altivec register.
3268
3269 @item wE
3270 Vector constant that can be loaded with the XXSPLTIB instruction.
3271
3272 @item wF
3273 Memory operand suitable for power8 GPR load fusion.
3274
3275 @item wL
3276 Int constant that is the element number mfvsrld accesses in a vector.
3277
3278 @item wM
3279 Match vector constant with all 1's if the XXLORC instruction is available.
3280
3281 @item wO
3282 Memory operand suitable for the ISA 3.0 vector d-form instructions.
3283
3284 @item wQ
3285 Memory operand suitable for the load/store quad instructions.
3286
3287 @item wS
3288 Vector constant that can be loaded with XXSPLTIB & sign extension.
3289
3290 @item wY
3291 A memory operand for a DS-form instruction.
3292
3293 @item wZ
3294 An indexed or indirect memory operand, ignoring the bottom 4 bits.
3295 @end ifset
3296
3297 @item I
3298 A signed 16-bit constant.
3299
3300 @item J
3301 An unsigned 16-bit constant shifted left 16 bits (use @code{L} instead
3302 for @code{SImode} constants).
3303
3304 @item K
3305 An unsigned 16-bit constant.
3306
3307 @item L
3308 A signed 16-bit constant shifted left 16 bits.
3309
3310 @ifset INTERNALS
3311 @item M
3312 An integer constant greater than 31.
3313
3314 @item N
3315 An exact power of 2.
3316
3317 @item O
3318 The integer constant zero.
3319
3320 @item P
3321 A constant whose negation is a signed 16-bit constant.
3322 @end ifset
3323
3324 @item eI
3325 A signed 34-bit integer constant if prefixed instructions are supported.
3326
3327 @item eP
3328 A scalar floating point constant or a vector constant that can be
3329 loaded to a VSX register with one prefixed instruction.
3330
3331 @item eQ
3332 An IEEE 128-bit constant that can be loaded into a VSX register with
3333 the @code{lxvkq} instruction.
3334
3335 @ifset INTERNALS
3336 @item G
3337 A floating point constant that can be loaded into a register with one
3338 instruction per word.
3339
3340 @item H
3341 A floating point constant that can be loaded into a register using
3342 three instructions.
3343 @end ifset
3344
3345 @item m
3346 A memory operand.
3347 Normally, @code{m} does not allow addresses that update the base register.
3348 If the @code{<} or @code{>} constraint is also used, they are allowed and
3349 therefore on PowerPC targets in that case it is only safe
3350 to use @code{m<>} in an @code{asm} statement if that @code{asm} statement
3351 accesses the operand exactly once. The @code{asm} statement must also
3352 use @code{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
3353 corresponding load or store instruction. For example:
3354
3355 @smallexample
3356 asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
3357 @end smallexample
3358
3359 is correct but:
3360
3361 @smallexample
3362 asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
3363 @end smallexample
3364
3365 is not.
3366
3367 @ifset INTERNALS
3368 @item es
3369 A ``stable'' memory operand; that is, one which does not include any
3370 automodification of the base register. This used to be useful when
3371 @code{m} allowed automodification of the base register, but as those
3372 are now only allowed when @code{<} or @code{>} is used, @code{es} is
3373 basically the same as @code{m} without @code{<} and @code{>}.
3374 @end ifset
3375
3376 @item Q
3377 A memory operand addressed by just a base register.
3378
3379 @ifset INTERNALS
3380 @item Y
3381 A memory operand for a DQ-form instruction.
3382 @end ifset
3383
3384 @item Z
3385 A memory operand accessed with indexed or indirect addressing.
3386
3387 @ifset INTERNALS
3388 @item R
3389 An AIX TOC entry.
3390 @end ifset
3391
3392 @item a
3393 An indexed or indirect address.
3394
3395 @ifset INTERNALS
3396 @item U
3397 A V.4 small data reference.
3398
3399 @item W
3400 A vector constant that does not require memory.
3401
3402 @item j
3403 The zero vector constant.
3404 @end ifset
3405
3406 @end table
3407
3408 @item PRU---@file{config/pru/constraints.md}
3409 @table @code
3410 @item I
3411 An unsigned 8-bit integer constant.
3412
3413 @item J
3414 An unsigned 16-bit integer constant.
3415
3416 @item L
3417 An unsigned 5-bit integer constant (for shift counts).
3418
3419 @item T
3420 A text segment (program memory) constant label.
3421
3422 @item Z
3423 Integer constant zero.
3424
3425 @end table
3426
3427 @item RL78---@file{config/rl78/constraints.md}
3428 @table @code
3429
3430 @item Int3
3431 An integer constant in the range 1 @dots{} 7.
3432 @item Int8
3433 An integer constant in the range 0 @dots{} 255.
3434 @item J
3435 An integer constant in the range @minus{}255 @dots{} 0
3436 @item K
3437 The integer constant 1.
3438 @item L
3439 The integer constant -1.
3440 @item M
3441 The integer constant 0.
3442 @item N
3443 The integer constant 2.
3444 @item O
3445 The integer constant -2.
3446 @item P
3447 An integer constant in the range 1 @dots{} 15.
3448 @item Qbi
3449 The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
3450 @item Qsc
3451 The synthetic compare types--gt, lt, ge, and le.
3452 @item Wab
3453 A memory reference with an absolute address.
3454 @item Wbc
3455 A memory reference using @code{BC} as a base register, with an optional offset.
3456 @item Wca
3457 A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
3458 @item Wcv
3459 A memory reference using any 16-bit register pair for the address, for calls.
3460 @item Wd2
3461 A memory reference using @code{DE} as a base register, with an optional offset.
3462 @item Wde
3463 A memory reference using @code{DE} as a base register, without any offset.
3464 @item Wfr
3465 Any memory reference to an address in the far address space.
3466 @item Wh1
3467 A memory reference using @code{HL} as a base register, with an optional one-byte offset.
3468 @item Whb
3469 A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
3470 @item Whl
3471 A memory reference using @code{HL} as a base register, without any offset.
3472 @item Ws1
3473 A memory reference using @code{SP} as a base register, with an optional one-byte offset.
3474 @item Y
3475 Any memory reference to an address in the near address space.
3476 @item A
3477 The @code{AX} register.
3478 @item B
3479 The @code{BC} register.
3480 @item D
3481 The @code{DE} register.
3482 @item R
3483 @code{A} through @code{L} registers.
3484 @item S
3485 The @code{SP} register.
3486 @item T
3487 The @code{HL} register.
3488 @item Z08W
3489 The 16-bit @code{R8} register.
3490 @item Z10W
3491 The 16-bit @code{R10} register.
3492 @item Zint
3493 The registers reserved for interrupts (@code{R24} to @code{R31}).
3494 @item a
3495 The @code{A} register.
3496 @item b
3497 The @code{B} register.
3498 @item c
3499 The @code{C} register.
3500 @item d
3501 The @code{D} register.
3502 @item e
3503 The @code{E} register.
3504 @item h
3505 The @code{H} register.
3506 @item l
3507 The @code{L} register.
3508 @item v
3509 The virtual registers.
3510 @item w
3511 The @code{PSW} register.
3512 @item x
3513 The @code{X} register.
3514
3515 @end table
3516
3517 @item RISC-V---@file{config/riscv/constraints.md}
3518 @table @code
3519
3520 @item f
3521 A floating-point register (if available).
3522
3523 @item I
3524 An I-type 12-bit signed immediate.
3525
3526 @item J
3527 Integer zero.
3528
3529 @item K
3530 A 5-bit unsigned immediate for CSR access instructions.
3531
3532 @item A
3533 An address that is held in a general-purpose register.
3534
3535 @item S
3536 A constraint that matches an absolute symbolic address.
3537
3538 @item vr
3539 A vector register (if available)..
3540
3541 @item vd
3542 A vector register, excluding v0 (if available).
3543
3544 @item vm
3545 A vector register, only v0 (if available).
3546
3547 @end table
3548
3549 @item RX---@file{config/rx/constraints.md}
3550 @table @code
3551 @item Q
3552 An address which does not involve register indirect addressing or
3553 pre/post increment/decrement addressing.
3554
3555 @item Symbol
3556 A symbol reference.
3557
3558 @item Int08
3559 A constant in the range @minus{}256 to 255, inclusive.
3560
3561 @item Sint08
3562 A constant in the range @minus{}128 to 127, inclusive.
3563
3564 @item Sint16
3565 A constant in the range @minus{}32768 to 32767, inclusive.
3566
3567 @item Sint24
3568 A constant in the range @minus{}8388608 to 8388607, inclusive.
3569
3570 @item Uint04
3571 A constant in the range 0 to 15, inclusive.
3572
3573 @end table
3574
3575 @item S/390 and zSeries---@file{config/s390/s390.h}
3576 @table @code
3577 @item a
3578 Address register (general purpose register except r0)
3579
3580 @item c
3581 Condition code register
3582
3583 @item d
3584 Data register (arbitrary general purpose register)
3585
3586 @item f
3587 Floating-point register
3588
3589 @item I
3590 Unsigned 8-bit constant (0--255)
3591
3592 @item J
3593 Unsigned 12-bit constant (0--4095)
3594
3595 @item K
3596 Signed 16-bit constant (@minus{}32768--32767)
3597
3598 @item L
3599 Value appropriate as displacement.
3600 @table @code
3601 @item (0..4095)
3602 for short displacement
3603 @item (@minus{}524288..524287)
3604 for long displacement
3605 @end table
3606
3607 @item M
3608 Constant integer with a value of 0x7fffffff.
3609
3610 @item N
3611 Multiple letter constraint followed by 4 parameter letters.
3612 @table @code
3613 @item 0..9:
3614 number of the part counting from most to least significant
3615 @item H,Q:
3616 mode of the part
3617 @item D,S,H:
3618 mode of the containing operand
3619 @item 0,F:
3620 value of the other parts (F---all bits set)
3621 @end table
3622 The constraint matches if the specified part of a constant
3623 has a value different from its other parts.
3624
3625 @item Q
3626 Memory reference without index register and with short displacement.
3627
3628 @item R
3629 Memory reference with index register and short displacement.
3630
3631 @item S
3632 Memory reference without index register but with long displacement.
3633
3634 @item T
3635 Memory reference with index register and long displacement.
3636
3637 @item U
3638 Pointer with short displacement.
3639
3640 @item W
3641 Pointer with long displacement.
3642
3643 @item Y
3644 Shift count operand.
3645
3646 @end table
3647
3648 @need 1000
3649 @item SPARC---@file{config/sparc/sparc.h}
3650 @table @code
3651 @item f
3652 Floating-point register on the SPARC-V8 architecture and
3653 lower floating-point register on the SPARC-V9 architecture.
3654
3655 @item e
3656 Floating-point register. It is equivalent to @samp{f} on the
3657 SPARC-V8 architecture and contains both lower and upper
3658 floating-point registers on the SPARC-V9 architecture.
3659
3660 @item c
3661 Floating-point condition code register.
3662
3663 @item d
3664 Lower floating-point register. It is only valid on the SPARC-V9
3665 architecture when the Visual Instruction Set is available.
3666
3667 @item b
3668 Floating-point register. It is only valid on the SPARC-V9 architecture
3669 when the Visual Instruction Set is available.
3670
3671 @item h
3672 64-bit global or out register for the SPARC-V8+ architecture.
3673
3674 @item C
3675 The constant all-ones, for floating-point.
3676
3677 @item A
3678 Signed 5-bit constant
3679
3680 @item D
3681 A vector constant
3682
3683 @item I
3684 Signed 13-bit constant
3685
3686 @item J
3687 Zero
3688
3689 @item K
3690 32-bit constant with the low 12 bits clear (a constant that can be
3691 loaded with the @code{sethi} instruction)
3692
3693 @item L
3694 A constant in the range supported by @code{movcc} instructions (11-bit
3695 signed immediate)
3696
3697 @item M
3698 A constant in the range supported by @code{movrcc} instructions (10-bit
3699 signed immediate)
3700
3701 @item N
3702 Same as @samp{K}, except that it verifies that bits that are not in the
3703 lower 32-bit range are all zero. Must be used instead of @samp{K} for
3704 modes wider than @code{SImode}
3705
3706 @item O
3707 The constant 4096
3708
3709 @item G
3710 Floating-point zero
3711
3712 @item H
3713 Signed 13-bit constant, sign-extended to 32 or 64 bits
3714
3715 @item P
3716 The constant -1
3717
3718 @item Q
3719 Floating-point constant whose integral representation can
3720 be moved into an integer register using a single sethi
3721 instruction
3722
3723 @item R
3724 Floating-point constant whose integral representation can
3725 be moved into an integer register using a single mov
3726 instruction
3727
3728 @item S
3729 Floating-point constant whose integral representation can
3730 be moved into an integer register using a high/lo_sum
3731 instruction sequence
3732
3733 @item T
3734 Memory address aligned to an 8-byte boundary
3735
3736 @item U
3737 Even register
3738
3739 @item W
3740 Memory address for @samp{e} constraint registers
3741
3742 @item w
3743 Memory address with only a base register
3744
3745 @item Y
3746 Vector zero
3747
3748 @end table
3749
3750 @item TI C6X family---@file{config/c6x/constraints.md}
3751 @table @code
3752 @item a
3753 Register file A (A0--A31).
3754
3755 @item b
3756 Register file B (B0--B31).
3757
3758 @item A
3759 Predicate registers in register file A (A0--A2 on C64X and
3760 higher, A1 and A2 otherwise).
3761
3762 @item B
3763 Predicate registers in register file B (B0--B2).
3764
3765 @item C
3766 A call-used register in register file B (B0--B9, B16--B31).
3767
3768 @item Da
3769 Register file A, excluding predicate registers (A3--A31,
3770 plus A0 if not C64X or higher).
3771
3772 @item Db
3773 Register file B, excluding predicate registers (B3--B31).
3774
3775 @item Iu4
3776 Integer constant in the range 0 @dots{} 15.
3777
3778 @item Iu5
3779 Integer constant in the range 0 @dots{} 31.
3780
3781 @item In5
3782 Integer constant in the range @minus{}31 @dots{} 0.
3783
3784 @item Is5
3785 Integer constant in the range @minus{}16 @dots{} 15.
3786
3787 @item I5x
3788 Integer constant that can be the operand of an ADDA or a SUBA insn.
3789
3790 @item IuB
3791 Integer constant in the range 0 @dots{} 65535.
3792
3793 @item IsB
3794 Integer constant in the range @minus{}32768 @dots{} 32767.
3795
3796 @item IsC
3797 Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.
3798
3799 @item Jc
3800 Integer constant that is a valid mask for the clr instruction.
3801
3802 @item Js
3803 Integer constant that is a valid mask for the set instruction.
3804
3805 @item Q
3806 Memory location with A base register.
3807
3808 @item R
3809 Memory location with B base register.
3810
3811 @ifset INTERNALS
3812 @item S0
3813 On C64x+ targets, a GP-relative small data reference.
3814
3815 @item S1
3816 Any kind of @code{SYMBOL_REF}, for use in a call address.
3817
3818 @item Si
3819 Any kind of immediate operand, unless it matches the S0 constraint.
3820
3821 @item T
3822 Memory location with B base register, but not using a long offset.
3823
3824 @item W
3825 A memory operand with an address that cannot be used in an unaligned access.
3826
3827 @end ifset
3828 @item Z
3829 Register B14 (aka DP).
3830
3831 @end table
3832
3833 @item Visium---@file{config/visium/constraints.md}
3834 @table @code
3835 @item b
3836 EAM register @code{mdb}
3837
3838 @item c
3839 EAM register @code{mdc}
3840
3841 @item f
3842 Floating point register
3843
3844 @ifset INTERNALS
3845 @item k
3846 Register for sibcall optimization
3847 @end ifset
3848
3849 @item l
3850 General register, but not @code{r29}, @code{r30} and @code{r31}
3851
3852 @item t
3853 Register @code{r1}
3854
3855 @item u
3856 Register @code{r2}
3857
3858 @item v
3859 Register @code{r3}
3860
3861 @item G
3862 Floating-point constant 0.0
3863
3864 @item J
3865 Integer constant in the range 0 .. 65535 (16-bit immediate)
3866
3867 @item K
3868 Integer constant in the range 1 .. 31 (5-bit immediate)
3869
3870 @item L
3871 Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate)
3872
3873 @item M
3874 Integer constant @minus{}1
3875
3876 @item O
3877 Integer constant 0
3878
3879 @item P
3880 Integer constant 32
3881 @end table
3882
3883 @item x86 family---@file{config/i386/constraints.md}
3884 @table @code
3885 @item R
3886 Legacy register---the eight integer registers available on all
3887 i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
3888 @code{si}, @code{di}, @code{bp}, @code{sp}).
3889
3890 @item q
3891 Any register accessible as @code{@var{r}l}. In 32-bit mode, @code{a},
3892 @code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.
3893
3894 @item Q
3895 Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
3896 @code{c}, and @code{d}.
3897
3898 @ifset INTERNALS
3899 @item l
3900 Any register that can be used as the index in a base+index memory
3901 access: that is, any general register except the stack pointer.
3902 @end ifset
3903
3904 @item a
3905 The @code{a} register.
3906
3907 @item b
3908 The @code{b} register.
3909
3910 @item c
3911 The @code{c} register.
3912
3913 @item d
3914 The @code{d} register.
3915
3916 @item S
3917 The @code{si} register.
3918
3919 @item D
3920 The @code{di} register.
3921
3922 @item A
3923 The @code{a} and @code{d} registers. This class is used for instructions
3924 that return double word results in the @code{ax:dx} register pair. Single
3925 word values will be allocated either in @code{ax} or @code{dx}.
3926 For example on i386 the following implements @code{rdtsc}:
3927
3928 @smallexample
3929 unsigned long long rdtsc (void)
3930 @{
3931 unsigned long long tick;
3932 __asm__ __volatile__("rdtsc":"=A"(tick));
3933 return tick;
3934 @}
3935 @end smallexample
3936
3937 This is not correct on x86-64 as it would allocate tick in either @code{ax}
3938 or @code{dx}. You have to use the following variant instead:
3939
3940 @smallexample
3941 unsigned long long rdtsc (void)
3942 @{
3943 unsigned int tickl, tickh;
3944 __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
3945 return ((unsigned long long)tickh << 32)|tickl;
3946 @}
3947 @end smallexample
3948
3949 @item U
3950 The call-clobbered integer registers.
3951
3952 @item f
3953 Any 80387 floating-point (stack) register.
3954
3955 @item t
3956 Top of 80387 floating-point stack (@code{%st(0)}).
3957
3958 @item u
3959 Second from top of 80387 floating-point stack (@code{%st(1)}).
3960
3961 @ifset INTERNALS
3962 @item Yk
3963 Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}.
3964
3965 @item k
3966 Any mask register.
3967 @end ifset
3968
3969 @item y
3970 Any MMX register.
3971
3972 @item x
3973 Any SSE register.
3974
3975 @item v
3976 Any EVEX encodable SSE register (@code{%xmm0-%xmm31}).
3977
3978 @ifset INTERNALS
3979 @item w
3980 Any bound register.
3981 @end ifset
3982
3983 @item Yz
3984 First SSE register (@code{%xmm0}).
3985
3986 @ifset INTERNALS
3987 @item Yi
3988 Any SSE register, when SSE2 and inter-unit moves are enabled.
3989
3990 @item Yj
3991 Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled.
3992
3993 @item Ym
3994 Any MMX register, when inter-unit moves are enabled.
3995
3996 @item Yn
3997 Any MMX register, when inter-unit moves from vector registers are enabled.
3998
3999 @item Yp
4000 Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled.
4001
4002 @item Ya
4003 Any integer register when zero extensions with @code{AND} are disabled.
4004
4005 @item Yb
4006 Any register that can be used as the GOT base when calling@*
4007 @code{___tls_get_addr}: that is, any general register except @code{a}
4008 and @code{sp} registers, for @option{-fno-plt} if linker supports it.
4009 Otherwise, @code{b} register.
4010
4011 @item Yf
4012 Any x87 register when 80387 floating-point arithmetic is enabled.
4013
4014 @item Yr
4015 Lower SSE register when avoiding REX prefix and all SSE registers otherwise.
4016
4017 @item Yv
4018 For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}),
4019 otherwise any SSE register.
4020
4021 @item Yh
4022 Any EVEX-encodable SSE register, that has number factor of four.
4023
4024 @item Bf
4025 Flags register operand.
4026
4027 @item Bg
4028 GOT memory operand.
4029
4030 @item Bm
4031 Vector memory operand.
4032
4033 @item Bc
4034 Constant memory operand.
4035
4036 @item Bn
4037 Memory operand without REX prefix.
4038
4039 @item Bs
4040 Sibcall memory operand.
4041
4042 @item Bw
4043 Call memory operand.
4044
4045 @item Bz
4046 Constant call address operand.
4047
4048 @item BC
4049 SSE constant -1 operand.
4050 @end ifset
4051
4052 @item I
4053 Integer constant in the range 0 @dots{} 31, for 32-bit shifts.
4054
4055 @item J
4056 Integer constant in the range 0 @dots{} 63, for 64-bit shifts.
4057
4058 @item K
4059 Signed 8-bit integer constant.
4060
4061 @item L
4062 @code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.
4063
4064 @item M
4065 0, 1, 2, or 3 (shifts for the @code{lea} instruction).
4066
4067 @item N
4068 Unsigned 8-bit integer constant (for @code{in} and @code{out}
4069 instructions).
4070
4071 @ifset INTERNALS
4072 @item O
4073 Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
4074 @end ifset
4075
4076 @item G
4077 Standard 80387 floating point constant.
4078
4079 @item C
4080 SSE constant zero operand.
4081
4082 @item e
4083 32-bit signed integer constant, or a symbolic reference known
4084 to fit that range (for immediate operands in sign-extending x86-64
4085 instructions).
4086
4087 @item We
4088 32-bit signed integer constant, or a symbolic reference known
4089 to fit that range (for sign-extending conversion operations that
4090 require non-@code{VOIDmode} immediate operands).
4091
4092 @item Wz
4093 32-bit unsigned integer constant, or a symbolic reference known
4094 to fit that range (for zero-extending conversion operations that
4095 require non-@code{VOIDmode} immediate operands).
4096
4097 @item Wd
4098 128-bit integer constant where both the high and low 64-bit word
4099 satisfy the @code{e} constraint.
4100
4101 @item Z
4102 32-bit unsigned integer constant, or a symbolic reference known
4103 to fit that range (for immediate operands in zero-extending x86-64
4104 instructions).
4105
4106 @item Tv
4107 VSIB address operand.
4108
4109 @item Ts
4110 Address operand without segment register.
4111
4112 @end table
4113
4114 @item Xstormy16---@file{config/stormy16/stormy16.h}
4115 @table @code
4116 @item a
4117 Register r0.
4118
4119 @item b
4120 Register r1.
4121
4122 @item c
4123 Register r2.
4124
4125 @item d
4126 Register r8.
4127
4128 @item e
4129 Registers r0 through r7.
4130
4131 @item t
4132 Registers r0 and r1.
4133
4134 @item y
4135 The carry register.
4136
4137 @item z
4138 Registers r8 and r9.
4139
4140 @item I
4141 A constant between 0 and 3 inclusive.
4142
4143 @item J
4144 A constant that has exactly one bit set.
4145
4146 @item K
4147 A constant that has exactly one bit clear.
4148
4149 @item L
4150 A constant between 0 and 255 inclusive.
4151
4152 @item M
4153 A constant between @minus{}255 and 0 inclusive.
4154
4155 @item N
4156 A constant between @minus{}3 and 0 inclusive.
4157
4158 @item O
4159 A constant between 1 and 4 inclusive.
4160
4161 @item P
4162 A constant between @minus{}4 and @minus{}1 inclusive.
4163
4164 @item Q
4165 A memory reference that is a stack push.
4166
4167 @item R
4168 A memory reference that is a stack pop.
4169
4170 @item S
4171 A memory reference that refers to a constant address of known value.
4172
4173 @item T
4174 The register indicated by Rx (not implemented yet).
4175
4176 @item U
4177 A constant that is not between 2 and 15 inclusive.
4178
4179 @item Z
4180 The constant 0.
4181
4182 @end table
4183
4184 @item Xtensa---@file{config/xtensa/constraints.md}
4185 @table @code
4186 @item a
4187 General-purpose 32-bit register
4188
4189 @item b
4190 One-bit boolean register
4191
4192 @item A
4193 MAC16 40-bit accumulator register
4194
4195 @item I
4196 Signed 12-bit integer constant, for use in MOVI instructions
4197
4198 @item J
4199 Signed 8-bit integer constant, for use in ADDI instructions
4200
4201 @item K
4202 Integer constant valid for BccI instructions
4203
4204 @item L
4205 Unsigned constant valid for BccUI instructions
4206
4207 @end table
4208
4209 @end table
4210
4211 @ifset INTERNALS
4212 @node Disable Insn Alternatives
4213 @subsection Disable insn alternatives using the @code{enabled} attribute
4214 @cindex enabled
4215
4216 There are three insn attributes that may be used to selectively disable
4217 instruction alternatives:
4218
4219 @table @code
4220 @item enabled
4221 Says whether an alternative is available on the current subtarget.
4222
4223 @item preferred_for_size
4224 Says whether an enabled alternative should be used in code that is
4225 optimized for size.
4226
4227 @item preferred_for_speed
4228 Says whether an enabled alternative should be used in code that is
4229 optimized for speed.
4230 @end table
4231
4232 All these attributes should use @code{(const_int 1)} to allow an alternative
4233 or @code{(const_int 0)} to disallow it. The attributes must be a static
4234 property of the subtarget; they cannot for example depend on the
4235 current operands, on the current optimization level, on the location
4236 of the insn within the body of a loop, on whether register allocation
4237 has finished, or on the current compiler pass.
4238
4239 The @code{enabled} attribute is a correctness property. It tells GCC to act
4240 as though the disabled alternatives were never defined in the first place.
4241 This is useful when adding new instructions to an existing pattern in
4242 cases where the new instructions are only available for certain cpu
4243 architecture levels (typically mapped to the @code{-march=} command-line
4244 option).
4245
4246 In contrast, the @code{preferred_for_size} and @code{preferred_for_speed}
4247 attributes are strong optimization hints rather than correctness properties.
4248 @code{preferred_for_size} tells GCC which alternatives to consider when
4249 adding or modifying an instruction that GCC wants to optimize for size.
4250 @code{preferred_for_speed} does the same thing for speed. Note that things
4251 like code motion can lead to cases where code optimized for size uses
4252 alternatives that are not preferred for size, and similarly for speed.
4253
4254 Although @code{define_insn}s can in principle specify the @code{enabled}
4255 attribute directly, it is often clearer to have subsiduary attributes
4256 for each architectural feature of interest. The @code{define_insn}s
4257 can then use these subsiduary attributes to say which alternatives
4258 require which features. The example below does this for @code{cpu_facility}.
4259
4260 E.g. the following two patterns could easily be merged using the @code{enabled}
4261 attribute:
4262
4263 @smallexample
4264
4265 (define_insn "*movdi_old"
4266 [(set (match_operand:DI 0 "register_operand" "=d")
4267 (match_operand:DI 1 "register_operand" " d"))]
4268 "!TARGET_NEW"
4269 "lgr %0,%1")
4270
4271 (define_insn "*movdi_new"
4272 [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4273 (match_operand:DI 1 "register_operand" " d,d,f"))]
4274 "TARGET_NEW"
4275 "@@
4276 lgr %0,%1
4277 ldgr %0,%1
4278 lgdr %0,%1")
4279
4280 @end smallexample
4281
4282 to:
4283
4284 @smallexample
4285
4286 (define_insn "*movdi_combined"
4287 [(set (match_operand:DI 0 "register_operand" "=d,f,d")
4288 (match_operand:DI 1 "register_operand" " d,d,f"))]
4289 ""
4290 "@@
4291 lgr %0,%1
4292 ldgr %0,%1
4293 lgdr %0,%1"
4294 [(set_attr "cpu_facility" "*,new,new")])
4295
4296 @end smallexample
4297
4298 with the @code{enabled} attribute defined like this:
4299
4300 @smallexample
4301
4302 (define_attr "cpu_facility" "standard,new" (const_string "standard"))
4303
4304 (define_attr "enabled" ""
4305 (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
4306 (and (eq_attr "cpu_facility" "new")
4307 (ne (symbol_ref "TARGET_NEW") (const_int 0)))
4308 (const_int 1)]
4309 (const_int 0)))
4310
4311 @end smallexample
4312
4313 @end ifset
4314
4315 @ifset INTERNALS
4316 @node Define Constraints
4317 @subsection Defining Machine-Specific Constraints
4318 @cindex defining constraints
4319 @cindex constraints, defining
4320
4321 Machine-specific constraints fall into two categories: register and
4322 non-register constraints. Within the latter category, constraints
4323 which allow subsets of all possible memory or address operands should
4324 be specially marked, to give @code{reload} more information.
4325
4326 Machine-specific constraints can be given names of arbitrary length,
4327 but they must be entirely composed of letters, digits, underscores
4328 (@samp{_}), and angle brackets (@samp{< >}). Like C identifiers, they
4329 must begin with a letter or underscore.
4330
4331 In order to avoid ambiguity in operand constraint strings, no
4332 constraint can have a name that begins with any other constraint's
4333 name. For example, if @code{x} is defined as a constraint name,
4334 @code{xy} may not be, and vice versa. As a consequence of this rule,
4335 no constraint may begin with one of the generic constraint letters:
4336 @samp{E F V X g i m n o p r s}.
4337
4338 Register constraints correspond directly to register classes.
4339 @xref{Register Classes}. There is thus not much flexibility in their
4340 definitions.
4341
4342 @deffn {MD Expression} define_register_constraint name regclass docstring
4343 All three arguments are string constants.
4344 @var{name} is the name of the constraint, as it will appear in
4345 @code{match_operand} expressions. If @var{name} is a multi-letter
4346 constraint its length shall be the same for all constraints starting
4347 with the same letter. @var{regclass} can be either the
4348 name of the corresponding register class (@pxref{Register Classes}),
4349 or a C expression which evaluates to the appropriate register class.
4350 If it is an expression, it must have no side effects, and it cannot
4351 look at the operand. The usual use of expressions is to map some
4352 register constraints to @code{NO_REGS} when the register class
4353 is not available on a given subarchitecture.
4354
4355 @var{docstring} is a sentence documenting the meaning of the
4356 constraint. Docstrings are explained further below.
4357 @end deffn
4358
4359 Non-register constraints are more like predicates: the constraint
4360 definition gives a boolean expression which indicates whether the
4361 constraint matches.
4362
4363 @deffn {MD Expression} define_constraint name docstring exp
4364 The @var{name} and @var{docstring} arguments are the same as for
4365 @code{define_register_constraint}, but note that the docstring comes
4366 immediately after the name for these expressions. @var{exp} is an RTL
4367 expression, obeying the same rules as the RTL expressions in predicate
4368 definitions. @xref{Defining Predicates}, for details. If it
4369 evaluates true, the constraint matches; if it evaluates false, it
4370 doesn't. Constraint expressions should indicate which RTL codes they
4371 might match, just like predicate expressions.
4372
4373 @code{match_test} C expressions have access to the
4374 following variables:
4375
4376 @table @var
4377 @item op
4378 The RTL object defining the operand.
4379 @item mode
4380 The machine mode of @var{op}.
4381 @item ival
4382 @samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
4383 @item hval
4384 @samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
4385 @code{const_double}.
4386 @item lval
4387 @samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
4388 @code{const_double}.
4389 @item rval
4390 @samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
4391 @code{const_double}.
4392 @end table
4393
4394 The @var{*val} variables should only be used once another piece of the
4395 expression has verified that @var{op} is the appropriate kind of RTL
4396 object.
4397 @end deffn
4398
4399 Most non-register constraints should be defined with
4400 @code{define_constraint}. The remaining two definition expressions
4401 are only appropriate for constraints that should be handled specially
4402 by @code{reload} if they fail to match.
4403
4404 @deffn {MD Expression} define_memory_constraint name docstring exp
4405 Use this expression for constraints that match a subset of all memory
4406 operands: that is, @code{reload} can make them match by converting the
4407 operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
4408 base register (from the register class specified by
4409 @code{BASE_REG_CLASS}, @pxref{Register Classes}).
4410
4411 For example, on the S/390, some instructions do not accept arbitrary
4412 memory references, but only those that do not make use of an index
4413 register. The constraint letter @samp{Q} is defined to represent a
4414 memory address of this type. If @samp{Q} is defined with
4415 @code{define_memory_constraint}, a @samp{Q} constraint can handle any
4416 memory operand, because @code{reload} knows it can simply copy the
4417 memory address into a base register if required. This is analogous to
4418 the way an @samp{o} constraint can handle any memory operand.
4419
4420 The syntax and semantics are otherwise identical to
4421 @code{define_constraint}.
4422 @end deffn
4423
4424 @deffn {MD Expression} define_special_memory_constraint name docstring exp
4425 Use this expression for constraints that match a subset of all memory
4426 operands: that is, @code{reload} cannot make them match by reloading
4427 the address as it is described for @code{define_memory_constraint} or
4428 such address reload is undesirable with the performance point of view.
4429
4430 For example, @code{define_special_memory_constraint} can be useful if
4431 specifically aligned memory is necessary or desirable for some insn
4432 operand.
4433
4434 The syntax and semantics are otherwise identical to
4435 @code{define_memory_constraint}.
4436 @end deffn
4437
4438 @deffn {MD Expression} define_relaxed_memory_constraint name docstring exp
4439 The test expression in a @code{define_memory_constraint} can assume
4440 that @code{TARGET_LEGITIMATE_ADDRESS_P} holds for the address inside
4441 a @code{mem} rtx and so it does not need to test this condition itself.
4442 In other words, a @code{define_memory_constraint} test of the form:
4443
4444 @smallexample
4445 (match_test "mem")
4446 @end smallexample
4447
4448 is enough to test whether an rtx is a @code{mem} @emph{and} whether
4449 its address satisfies @code{TARGET_MEM_CONSTRAINT} (which is usually
4450 @samp{'m'}). Thus the conditions imposed by a @code{define_memory_constraint}
4451 always apply on top of the conditions imposed by @code{TARGET_MEM_CONSTRAINT}.
4452
4453 However, it is sometimes useful to define memory constraints that allow
4454 addresses beyond those accepted by @code{TARGET_LEGITIMATE_ADDRESS_P}.
4455 @code{define_relaxed_memory_constraint} exists for this case.
4456 The test expression in a @code{define_relaxed_memory_constraint} is
4457 applied with no preconditions, so that the expression can determine
4458 ``from scratch'' exactly which addresses are valid and which are not.
4459
4460 The syntax and semantics are otherwise identical to
4461 @code{define_memory_constraint}.
4462 @end deffn
4463
4464 @deffn {MD Expression} define_address_constraint name docstring exp
4465 Use this expression for constraints that match a subset of all address
4466 operands: that is, @code{reload} can make the constraint match by
4467 converting the operand to the form @samp{@w{(reg @var{X})}}, again
4468 with @var{X} a base register.
4469
4470 Constraints defined with @code{define_address_constraint} can only be
4471 used with the @code{address_operand} predicate, or machine-specific
4472 predicates that work the same way. They are treated analogously to
4473 the generic @samp{p} constraint.
4474
4475 The syntax and semantics are otherwise identical to
4476 @code{define_constraint}.
4477 @end deffn
4478
4479 For historical reasons, names beginning with the letters @samp{G H}
4480 are reserved for constraints that match only @code{const_double}s, and
4481 names beginning with the letters @samp{I J K L M N O P} are reserved
4482 for constraints that match only @code{const_int}s. This may change in
4483 the future. For the time being, constraints with these names must be
4484 written in a stylized form, so that @code{genpreds} can tell you did
4485 it correctly:
4486
4487 @smallexample
4488 @group
4489 (define_constraint "[@var{GHIJKLMNOP}]@dots{}"
4490 "@var{doc}@dots{}"
4491 (and (match_code "const_int") ; @r{@code{const_double} for G/H}
4492 @var{condition}@dots{})) ; @r{usually a @code{match_test}}
4493 @end group
4494 @end smallexample
4495 @c the semicolons line up in the formatted manual
4496
4497 It is fine to use names beginning with other letters for constraints
4498 that match @code{const_double}s or @code{const_int}s.
4499
4500 Each docstring in a constraint definition should be one or more complete
4501 sentences, marked up in Texinfo format. @emph{They are currently unused.}
4502 In the future they will be copied into the GCC manual, in @ref{Machine
4503 Constraints}, replacing the hand-maintained tables currently found in
4504 that section. Also, in the future the compiler may use this to give
4505 more helpful diagnostics when poor choice of @code{asm} constraints
4506 causes a reload failure.
4507
4508 If you put the pseudo-Texinfo directive @samp{@@internal} at the
4509 beginning of a docstring, then (in the future) it will appear only in
4510 the internals manual's version of the machine-specific constraint tables.
4511 Use this for constraints that should not appear in @code{asm} statements.
4512
4513 @node C Constraint Interface
4514 @subsection Testing constraints from C
4515 @cindex testing constraints
4516 @cindex constraints, testing
4517
4518 It is occasionally useful to test a constraint from C code rather than
4519 implicitly via the constraint string in a @code{match_operand}. The
4520 generated file @file{tm_p.h} declares a few interfaces for working
4521 with constraints. At present these are defined for all constraints
4522 except @code{g} (which is equivalent to @code{general_operand}).
4523
4524 Some valid constraint names are not valid C identifiers, so there is a
4525 mangling scheme for referring to them from C@. Constraint names that
4526 do not contain angle brackets or underscores are left unchanged.
4527 Underscores are doubled, each @samp{<} is replaced with @samp{_l}, and
4528 each @samp{>} with @samp{_g}. Here are some examples:
4529
4530 @c the @c's prevent double blank lines in the printed manual.
4531 @example
4532 @multitable {Original} {Mangled}
4533 @item @strong{Original} @tab @strong{Mangled} @c
4534 @item @code{x} @tab @code{x} @c
4535 @item @code{P42x} @tab @code{P42x} @c
4536 @item @code{P4_x} @tab @code{P4__x} @c
4537 @item @code{P4>x} @tab @code{P4_gx} @c
4538 @item @code{P4>>} @tab @code{P4_g_g} @c
4539 @item @code{P4_g>} @tab @code{P4__g_g} @c
4540 @end multitable
4541 @end example
4542
4543 Throughout this section, the variable @var{c} is either a constraint
4544 in the abstract sense, or a constant from @code{enum constraint_num};
4545 the variable @var{m} is a mangled constraint name (usually as part of
4546 a larger identifier).
4547
4548 @deftp Enum constraint_num
4549 For each constraint except @code{g}, there is a corresponding
4550 enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
4551 constraint. Functions that take an @code{enum constraint_num} as an
4552 argument expect one of these constants.
4553 @end deftp
4554
4555 @deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
4556 For each non-register constraint @var{m} except @code{g}, there is
4557 one of these functions; it returns @code{true} if @var{exp} satisfies the
4558 constraint. These functions are only visible if @file{rtl.h} was included
4559 before @file{tm_p.h}.
4560 @end deftypefun
4561
4562 @deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
4563 Like the @code{satisfies_constraint_@var{m}} functions, but the
4564 constraint to test is given as an argument, @var{c}. If @var{c}
4565 specifies a register constraint, this function will always return
4566 @code{false}.
4567 @end deftypefun
4568
4569 @deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c})
4570 Returns the register class associated with @var{c}. If @var{c} is not
4571 a register constraint, or those registers are not available for the
4572 currently selected subtarget, returns @code{NO_REGS}.
4573 @end deftypefun
4574
4575 Here is an example use of @code{satisfies_constraint_@var{m}}. In
4576 peephole optimizations (@pxref{Peephole Definitions}), operand
4577 constraint strings are ignored, so if there are relevant constraints,
4578 they must be tested in the C condition. In the example, the
4579 optimization is applied if operand 2 does @emph{not} satisfy the
4580 @samp{K} constraint. (This is a simplified version of a peephole
4581 definition from the i386 machine description.)
4582
4583 @smallexample
4584 (define_peephole2
4585 [(match_scratch:SI 3 "r")
4586 (set (match_operand:SI 0 "register_operand" "")
4587 (mult:SI (match_operand:SI 1 "memory_operand" "")
4588 (match_operand:SI 2 "immediate_operand" "")))]
4589
4590 "!satisfies_constraint_K (operands[2])"
4591
4592 [(set (match_dup 3) (match_dup 1))
4593 (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]
4594
4595 "")
4596 @end smallexample
4597
4598 @node Standard Names
4599 @section Standard Pattern Names For Generation
4600 @cindex standard pattern names
4601 @cindex pattern names
4602 @cindex names, pattern
4603
4604 Here is a table of the instruction names that are meaningful in the RTL
4605 generation pass of the compiler. Giving one of these names to an
4606 instruction pattern tells the RTL generation pass that it can use the
4607 pattern to accomplish a certain task.
4608
4609 @table @asis
4610 @cindex @code{mov@var{m}} instruction pattern
4611 @item @samp{mov@var{m}}
4612 Here @var{m} stands for a two-letter machine mode name, in lowercase.
4613 This instruction pattern moves data with that machine mode from operand
4614 1 to operand 0. For example, @samp{movsi} moves full-word data.
4615
4616 If operand 0 is a @code{subreg} with mode @var{m} of a register whose
4617 own mode is wider than @var{m}, the effect of this instruction is
4618 to store the specified value in the part of the register that corresponds
4619 to mode @var{m}. Bits outside of @var{m}, but which are within the
4620 same target word as the @code{subreg} are undefined. Bits which are
4621 outside the target word are left unchanged.
4622
4623 This class of patterns is special in several ways. First of all, each
4624 of these names up to and including full word size @emph{must} be defined,
4625 because there is no other way to copy a datum from one place to another.
4626 If there are patterns accepting operands in larger modes,
4627 @samp{mov@var{m}} must be defined for integer modes of those sizes.
4628
4629 Second, these patterns are not used solely in the RTL generation pass.
4630 Even the reload pass can generate move insns to copy values from stack
4631 slots into temporary registers. When it does so, one of the operands is
4632 a hard register and the other is an operand that can need to be reloaded
4633 into a register.
4634
4635 @findex force_reg
4636 Therefore, when given such a pair of operands, the pattern must generate
4637 RTL which needs no reloading and needs no temporary registers---no
4638 registers other than the operands. For example, if you support the
4639 pattern with a @code{define_expand}, then in such a case the
4640 @code{define_expand} mustn't call @code{force_reg} or any other such
4641 function which might generate new pseudo registers.
4642
4643 This requirement exists even for subword modes on a RISC machine where
4644 fetching those modes from memory normally requires several insns and
4645 some temporary registers.
4646
4647 @findex change_address
4648 During reload a memory reference with an invalid address may be passed
4649 as an operand. Such an address will be replaced with a valid address
4650 later in the reload pass. In this case, nothing may be done with the
4651 address except to use it as it stands. If it is copied, it will not be
4652 replaced with a valid address. No attempt should be made to make such
4653 an address into a valid address and no routine (such as
4654 @code{change_address}) that will do so may be called. Note that
4655 @code{general_operand} will fail when applied to such an address.
4656
4657 @findex reload_in_progress
4658 The global variable @code{reload_in_progress} (which must be explicitly
4659 declared if required) can be used to determine whether such special
4660 handling is required.
4661
4662 The variety of operands that have reloads depends on the rest of the
4663 machine description, but typically on a RISC machine these can only be
4664 pseudo registers that did not get hard registers, while on other
4665 machines explicit memory references will get optional reloads.
4666
4667 If a scratch register is required to move an object to or from memory,
4668 it can be allocated using @code{gen_reg_rtx} prior to life analysis.
4669
4670 If there are cases which need scratch registers during or after reload,
4671 you must provide an appropriate secondary_reload target hook.
4672
4673 @findex can_create_pseudo_p
4674 The macro @code{can_create_pseudo_p} can be used to determine if it
4675 is unsafe to create new pseudo registers. If this variable is nonzero, then
4676 it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.
4677
4678 The constraints on a @samp{mov@var{m}} must permit moving any hard
4679 register to any other hard register provided that
4680 @code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
4681 @code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
4682 of 2.
4683
4684 It is obligatory to support floating point @samp{mov@var{m}}
4685 instructions into and out of any registers that can hold fixed point
4686 values, because unions and structures (which have modes @code{SImode} or
4687 @code{DImode}) can be in those registers and they may have floating
4688 point members.
4689
4690 There may also be a need to support fixed point @samp{mov@var{m}}
4691 instructions in and out of floating point registers. Unfortunately, I
4692 have forgotten why this was so, and I don't know whether it is still
4693 true. If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in
4694 floating point registers, then the constraints of the fixed point
4695 @samp{mov@var{m}} instructions must be designed to avoid ever trying to
4696 reload into a floating point register.
4697
4698 @cindex @code{reload_in} instruction pattern
4699 @cindex @code{reload_out} instruction pattern
4700 @item @samp{reload_in@var{m}}
4701 @itemx @samp{reload_out@var{m}}
4702 These named patterns have been obsoleted by the target hook
4703 @code{secondary_reload}.
4704
4705 Like @samp{mov@var{m}}, but used when a scratch register is required to
4706 move between operand 0 and operand 1. Operand 2 describes the scratch
4707 register. See the discussion of the @code{SECONDARY_RELOAD_CLASS}
4708 macro in @pxref{Register Classes}.
4709
4710 There are special restrictions on the form of the @code{match_operand}s
4711 used in these patterns. First, only the predicate for the reload
4712 operand is examined, i.e., @code{reload_in} examines operand 1, but not
4713 the predicates for operand 0 or 2. Second, there may be only one
4714 alternative in the constraints. Third, only a single register class
4715 letter may be used for the constraint; subsequent constraint letters
4716 are ignored. As a special exception, an empty constraint string
4717 matches the @code{ALL_REGS} register class. This may relieve ports
4718 of the burden of defining an @code{ALL_REGS} constraint letter just
4719 for these patterns.
4720
4721 @cindex @code{movstrict@var{m}} instruction pattern
4722 @item @samp{movstrict@var{m}}
4723 Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
4724 with mode @var{m} of a register whose natural mode is wider,
4725 the @samp{movstrict@var{m}} instruction is guaranteed not to alter
4726 any of the register except the part which belongs to mode @var{m}.
4727
4728 @cindex @code{movmisalign@var{m}} instruction pattern
4729 @item @samp{movmisalign@var{m}}
4730 This variant of a move pattern is designed to load or store a value
4731 from a memory address that is not naturally aligned for its mode.
4732 For a store, the memory will be in operand 0; for a load, the memory
4733 will be in operand 1. The other operand is guaranteed not to be a
4734 memory, so that it's easy to tell whether this is a load or store.
4735
4736 This pattern is used by the autovectorizer, and when expanding a
4737 @code{MISALIGNED_INDIRECT_REF} expression.
4738
4739 @cindex @code{load_multiple} instruction pattern
4740 @item @samp{load_multiple}
4741 Load several consecutive memory locations into consecutive registers.
4742 Operand 0 is the first of the consecutive registers, operand 1
4743 is the first memory location, and operand 2 is a constant: the
4744 number of consecutive registers.
4745
4746 Define this only if the target machine really has such an instruction;
4747 do not define this if the most efficient way of loading consecutive
4748 registers from memory is to do them one at a time.
4749
4750 On some machines, there are restrictions as to which consecutive
4751 registers can be stored into memory, such as particular starting or
4752 ending register numbers or only a range of valid counts. For those
4753 machines, use a @code{define_expand} (@pxref{Expander Definitions})
4754 and make the pattern fail if the restrictions are not met.
4755
4756 Write the generated insn as a @code{parallel} with elements being a
4757 @code{set} of one register from the appropriate memory location (you may
4758 also need @code{use} or @code{clobber} elements). Use a
4759 @code{match_parallel} (@pxref{RTL Template}) to recognize the insn. See
4760 @file{rs6000.md} for examples of the use of this insn pattern.
4761
4762 @cindex @samp{store_multiple} instruction pattern
4763 @item @samp{store_multiple}
4764 Similar to @samp{load_multiple}, but store several consecutive registers
4765 into consecutive memory locations. Operand 0 is the first of the
4766 consecutive memory locations, operand 1 is the first register, and
4767 operand 2 is a constant: the number of consecutive registers.
4768
4769 @cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
4770 @item @samp{vec_load_lanes@var{m}@var{n}}
4771 Perform an interleaved load of several vectors from memory operand 1
4772 into register operand 0. Both operands have mode @var{m}. The register
4773 operand is viewed as holding consecutive vectors of mode @var{n},
4774 while the memory operand is a flat array that contains the same number
4775 of elements. The operation is equivalent to:
4776
4777 @smallexample
4778 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4779 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4780 for (i = 0; i < c; i++)
4781 operand0[i][j] = operand1[j * c + i];
4782 @end smallexample
4783
4784 For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
4785 from memory into a register of mode @samp{TI}@. The register
4786 contains two consecutive vectors of mode @samp{V4HI}@.
4787
4788 This pattern can only be used if:
4789 @smallexample
4790 TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
4791 @end smallexample
4792 is true. GCC assumes that, if a target supports this kind of
4793 instruction for some mode @var{n}, it also supports unaligned
4794 loads for vectors of mode @var{n}.
4795
4796 This pattern is not allowed to @code{FAIL}.
4797
4798 @cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern
4799 @item @samp{vec_mask_load_lanes@var{m}@var{n}}
4800 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
4801 mask operand (operand 2) that specifies which elements of the destination
4802 vectors should be loaded. Other elements of the destination
4803 vectors are set to zero. The operation is equivalent to:
4804
4805 @smallexample
4806 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4807 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4808 if (operand2[j])
4809 for (i = 0; i < c; i++)
4810 operand0[i][j] = operand1[j * c + i];
4811 else
4812 for (i = 0; i < c; i++)
4813 operand0[i][j] = 0;
4814 @end smallexample
4815
4816 This pattern is not allowed to @code{FAIL}.
4817
4818 @cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
4819 @item @samp{vec_store_lanes@var{m}@var{n}}
4820 Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
4821 and register operands reversed. That is, the instruction is
4822 equivalent to:
4823
4824 @smallexample
4825 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4826 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4827 for (i = 0; i < c; i++)
4828 operand0[j * c + i] = operand1[i][j];
4829 @end smallexample
4830
4831 for a memory operand 0 and register operand 1.
4832
4833 This pattern is not allowed to @code{FAIL}.
4834
4835 @cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern
4836 @item @samp{vec_mask_store_lanes@var{m}@var{n}}
4837 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
4838 mask operand (operand 2) that specifies which elements of the source
4839 vectors should be stored. The operation is equivalent to:
4840
4841 @smallexample
4842 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
4843 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
4844 if (operand2[j])
4845 for (i = 0; i < c; i++)
4846 operand0[j * c + i] = operand1[i][j];
4847 @end smallexample
4848
4849 This pattern is not allowed to @code{FAIL}.
4850
4851 @cindex @code{gather_load@var{m}@var{n}} instruction pattern
4852 @item @samp{gather_load@var{m}@var{n}}
4853 Load several separate memory locations into a vector of mode @var{m}.
4854 Operand 1 is a scalar base address and operand 2 is a vector of mode @var{n}
4855 containing offsets from that base. Operand 0 is a destination vector with
4856 the same number of elements as @var{n}. For each element index @var{i}:
4857
4858 @itemize @bullet
4859 @item
4860 extend the offset element @var{i} to address width, using zero
4861 extension if operand 3 is 1 and sign extension if operand 3 is zero;
4862 @item
4863 multiply the extended offset by operand 4;
4864 @item
4865 add the result to the base; and
4866 @item
4867 load the value at that address into element @var{i} of operand 0.
4868 @end itemize
4869
4870 The value of operand 3 does not matter if the offsets are already
4871 address width.
4872
4873 @cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern
4874 @item @samp{mask_gather_load@var{m}@var{n}}
4875 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as
4876 operand 5. Bit @var{i} of the mask is set if element @var{i}
4877 of the result should be loaded from memory and clear if element @var{i}
4878 of the result should be set to zero.
4879
4880 @cindex @code{scatter_store@var{m}@var{n}} instruction pattern
4881 @item @samp{scatter_store@var{m}@var{n}}
4882 Store a vector of mode @var{m} into several distinct memory locations.
4883 Operand 0 is a scalar base address and operand 1 is a vector of mode
4884 @var{n} containing offsets from that base. Operand 4 is the vector of
4885 values that should be stored, which has the same number of elements as
4886 @var{n}. For each element index @var{i}:
4887
4888 @itemize @bullet
4889 @item
4890 extend the offset element @var{i} to address width, using zero
4891 extension if operand 2 is 1 and sign extension if operand 2 is zero;
4892 @item
4893 multiply the extended offset by operand 3;
4894 @item
4895 add the result to the base; and
4896 @item
4897 store element @var{i} of operand 4 to that address.
4898 @end itemize
4899
4900 The value of operand 2 does not matter if the offsets are already
4901 address width.
4902
4903 @cindex @code{mask_scatter_store@var{m}@var{n}} instruction pattern
4904 @item @samp{mask_scatter_store@var{m}@var{n}}
4905 Like @samp{scatter_store@var{m}@var{n}}, but takes an extra mask operand as
4906 operand 5. Bit @var{i} of the mask is set if element @var{i}
4907 of the result should be stored to memory.
4908
4909 @cindex @code{vec_set@var{m}} instruction pattern
4910 @item @samp{vec_set@var{m}}
4911 Set given field in the vector value. Operand 0 is the vector to modify,
4912 operand 1 is new value of field and operand 2 specify the field index.
4913
4914 @cindex @code{vec_extract@var{m}@var{n}} instruction pattern
4915 @item @samp{vec_extract@var{m}@var{n}}
4916 Extract given field from the vector value. Operand 1 is the vector, operand 2
4917 specify field index and operand 0 place to store value into. The
4918 @var{n} mode is the mode of the field or vector of fields that should be
4919 extracted, should be either element mode of the vector mode @var{m}, or
4920 a vector mode with the same element mode and smaller number of elements.
4921 If @var{n} is a vector mode, the index is counted in units of that mode.
4922
4923 @cindex @code{vec_init@var{m}@var{n}} instruction pattern
4924 @item @samp{vec_init@var{m}@var{n}}
4925 Initialize the vector to given values. Operand 0 is the vector to initialize
4926 and operand 1 is parallel containing values for individual fields. The
4927 @var{n} mode is the mode of the elements, should be either element mode of
4928 the vector mode @var{m}, or a vector mode with the same element mode and
4929 smaller number of elements.
4930
4931 @cindex @code{vec_duplicate@var{m}} instruction pattern
4932 @item @samp{vec_duplicate@var{m}}
4933 Initialize vector output operand 0 so that each element has the value given
4934 by scalar input operand 1. The vector has mode @var{m} and the scalar has
4935 the mode appropriate for one element of @var{m}.
4936
4937 This pattern only handles duplicates of non-constant inputs. Constant
4938 vectors go through the @code{mov@var{m}} pattern instead.
4939
4940 This pattern is not allowed to @code{FAIL}.
4941
4942 @cindex @code{vec_series@var{m}} instruction pattern
4943 @item @samp{vec_series@var{m}}
4944 Initialize vector output operand 0 so that element @var{i} is equal to
4945 operand 1 plus @var{i} times operand 2. In other words, create a linear
4946 series whose base value is operand 1 and whose step is operand 2.
4947
4948 The vector output has mode @var{m} and the scalar inputs have the mode
4949 appropriate for one element of @var{m}. This pattern is not used for
4950 floating-point vectors, in order to avoid having to specify the
4951 rounding behavior for @var{i} > 1.
4952
4953 This pattern is not allowed to @code{FAIL}.
4954
4955 @cindex @code{while_ult@var{m}@var{n}} instruction pattern
4956 @item @code{while_ult@var{m}@var{n}}
4957 Set operand 0 to a mask that is true while incrementing operand 1
4958 gives a value that is less than operand 2, for a vector length up to operand 3.
4959 Operand 0 has mode @var{n} and operands 1 and 2 are scalar integers of mode
4960 @var{m}. Operand 3 should be omitted when @var{n} is a vector mode, and
4961 a @code{CONST_INT} otherwise. The operation for vector modes is equivalent to:
4962
4963 @smallexample
4964 operand0[0] = operand1 < operand2;
4965 for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++)
4966 operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
4967 @end smallexample
4968
4969 And for non-vector modes the operation is equivalent to:
4970
4971 @smallexample
4972 operand0[0] = operand1 < operand2;
4973 for (i = 1; i < operand3; i++)
4974 operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
4975 @end smallexample
4976
4977 @cindex @code{check_raw_ptrs@var{m}} instruction pattern
4978 @item @samp{check_raw_ptrs@var{m}}
4979 Check whether, given two pointers @var{a} and @var{b} and a length @var{len},
4980 a write of @var{len} bytes at @var{a} followed by a read of @var{len} bytes
4981 at @var{b} can be split into interleaved byte accesses
4982 @samp{@var{a}[0], @var{b}[0], @var{a}[1], @var{b}[1], @dots{}}
4983 without affecting the dependencies between the bytes. Set operand 0
4984 to true if the split is possible and false otherwise.
4985
4986 Operands 1, 2 and 3 provide the values of @var{a}, @var{b} and @var{len}
4987 respectively. Operand 4 is a constant integer that provides the known
4988 common alignment of @var{a} and @var{b}. All inputs have mode @var{m}.
4989
4990 This split is possible if:
4991
4992 @smallexample
4993 @var{a} == @var{b} || @var{a} + @var{len} <= @var{b} || @var{b} + @var{len} <= @var{a}
4994 @end smallexample
4995
4996 You should only define this pattern if the target has a way of accelerating
4997 the test without having to do the individual comparisons.
4998
4999 @cindex @code{check_war_ptrs@var{m}} instruction pattern
5000 @item @samp{check_war_ptrs@var{m}}
5001 Like @samp{check_raw_ptrs@var{m}}, but with the read and write swapped round.
5002 The split is possible in this case if:
5003
5004 @smallexample
5005 @var{b} <= @var{a} || @var{a} + @var{len} <= @var{b}
5006 @end smallexample
5007
5008 @cindex @code{vec_cmp@var{m}@var{n}} instruction pattern
5009 @item @samp{vec_cmp@var{m}@var{n}}
5010 Output a vector comparison. Operand 0 of mode @var{n} is the destination for
5011 predicate in operand 1 which is a signed vector comparison with operands of
5012 mode @var{m} in operands 2 and 3. Predicate is computed by element-wise
5013 evaluation of the vector comparison with a truth value of all-ones and a false
5014 value of all-zeros.
5015
5016 @cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern
5017 @item @samp{vec_cmpu@var{m}@var{n}}
5018 Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison.
5019
5020 @cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern
5021 @item @samp{vec_cmpeq@var{m}@var{n}}
5022 Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality
5023 vector comparison only. If @code{vec_cmp@var{m}@var{n}}
5024 or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported,
5025 it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is
5026 no need to define this instruction pattern if the others are supported.
5027
5028 @cindex @code{vcond@var{m}@var{n}} instruction pattern
5029 @item @samp{vcond@var{m}@var{n}}
5030 Output a conditional vector move. Operand 0 is the destination to
5031 receive a combination of operand 1 and operand 2, which are of mode @var{m},
5032 dependent on the outcome of the predicate in operand 3 which is a signed
5033 vector comparison with operands of mode @var{n} in operands 4 and 5. The
5034 modes @var{m} and @var{n} should have the same size. Operand 0
5035 will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk}
5036 where @var{msk} is computed by element-wise evaluation of the vector
5037 comparison with a truth value of all-ones and a false value of all-zeros.
5038
5039 @cindex @code{vcondu@var{m}@var{n}} instruction pattern
5040 @item @samp{vcondu@var{m}@var{n}}
5041 Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector
5042 comparison.
5043
5044 @cindex @code{vcondeq@var{m}@var{n}} instruction pattern
5045 @item @samp{vcondeq@var{m}@var{n}}
5046 Similar to @code{vcond@var{m}@var{n}} but performs equality or
5047 non-equality vector comparison only. If @code{vcond@var{m}@var{n}}
5048 or @code{vcondu@var{m}@var{n}} instruction pattern is supported,
5049 it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is
5050 no need to define this instruction pattern if the others are supported.
5051
5052 @cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern
5053 @item @samp{vcond_mask_@var{m}@var{n}}
5054 Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed
5055 result of vector comparison.
5056
5057 @cindex @code{maskload@var{m}@var{n}} instruction pattern
5058 @item @samp{maskload@var{m}@var{n}}
5059 Perform a masked load of vector from memory operand 1 of mode @var{m}
5060 into register operand 0. Mask is provided in register operand 2 of
5061 mode @var{n}.
5062
5063 This pattern is not allowed to @code{FAIL}.
5064
5065 @cindex @code{maskstore@var{m}@var{n}} instruction pattern
5066 @item @samp{maskstore@var{m}@var{n}}
5067 Perform a masked store of vector from register operand 1 of mode @var{m}
5068 into memory operand 0. Mask is provided in register operand 2 of
5069 mode @var{n}.
5070
5071 This pattern is not allowed to @code{FAIL}.
5072
5073 @cindex @code{len_load_@var{m}} instruction pattern
5074 @item @samp{len_load_@var{m}}
5075 Load (operand 2 - operand 3) elements from vector memory operand 1
5076 into vector register operand 0, setting the other elements of
5077 operand 0 to undefined values. Operands 0 and 1 have mode @var{m},
5078 which must be a vector mode. Operand 2 has whichever integer mode the
5079 target prefers. Operand 3 conceptually has mode @code{QI}.
5080
5081 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5082 constant bias: it is either a constant 0 or a constant -1. The predicate on
5083 operand 3 must only accept the bias values that the target actually supports.
5084 GCC handles a bias of 0 more efficiently than a bias of -1.
5085
5086 If (operand 2 - operand 3) exceeds the number of elements in mode
5087 @var{m}, the behavior is undefined.
5088
5089 If the target prefers the length to be measured in bytes rather than
5090 elements, it should only implement this pattern for vectors of @code{QI}
5091 elements.
5092
5093 This pattern is not allowed to @code{FAIL}.
5094
5095 @cindex @code{len_store_@var{m}} instruction pattern
5096 @item @samp{len_store_@var{m}}
5097 Store (operand 2 - operand 3) vector elements from vector register operand 1
5098 into memory operand 0, leaving the other elements of
5099 operand 0 unchanged. Operands 0 and 1 have mode @var{m}, which must be
5100 a vector mode. Operand 2 has whichever integer mode the target prefers.
5101 Operand 3 conceptually has mode @code{QI}.
5102
5103 Operand 2 can be a variable or a constant amount. Operand 3 specifies a
5104 constant bias: it is either a constant 0 or a constant -1. The predicate on
5105 operand 3 must only accept the bias values that the target actually supports.
5106 GCC handles a bias of 0 more efficiently than a bias of -1.
5107
5108 If (operand 2 - operand 3) exceeds the number of elements in mode
5109 @var{m}, the behavior is undefined.
5110
5111 If the target prefers the length to be measured in bytes
5112 rather than elements, it should only implement this pattern for vectors
5113 of @code{QI} elements.
5114
5115 This pattern is not allowed to @code{FAIL}.
5116
5117 @cindex @code{vec_perm@var{m}} instruction pattern
5118 @item @samp{vec_perm@var{m}}
5119 Output a (variable) vector permutation. Operand 0 is the destination
5120 to receive elements from operand 1 and operand 2, which are of mode
5121 @var{m}. Operand 3 is the @dfn{selector}. It is an integral mode
5122 vector of the same width and number of elements as mode @var{m}.
5123
5124 The input elements are numbered from 0 in operand 1 through
5125 @math{2*@var{N}-1} in operand 2. The elements of the selector must
5126 be computed modulo @math{2*@var{N}}. Note that if
5127 @code{rtx_equal_p(operand1, operand2)}, this can be implemented
5128 with just operand 1 and selector elements modulo @var{N}.
5129
5130 In order to make things easy for a number of targets, if there is no
5131 @samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
5132 where @var{q} is a vector of @code{QImode} of the same width as @var{m},
5133 the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
5134 mode @var{q}.
5135
5136 See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs
5137 the analogous operation for constant selectors.
5138
5139 @cindex @code{push@var{m}1} instruction pattern
5140 @item @samp{push@var{m}1}
5141 Output a push instruction. Operand 0 is value to push. Used only when
5142 @code{PUSH_ROUNDING} is defined. For historical reason, this pattern may be
5143 missing and in such case an @code{mov} expander is used instead, with a
5144 @code{MEM} expression forming the push operation. The @code{mov} expander
5145 method is deprecated.
5146
5147 @cindex @code{add@var{m}3} instruction pattern
5148 @item @samp{add@var{m}3}
5149 Add operand 2 and operand 1, storing the result in operand 0. All operands
5150 must have mode @var{m}. This can be used even on two-address machines, by
5151 means of constraints requiring operands 1 and 0 to be the same location.
5152
5153 @cindex @code{ssadd@var{m}3} instruction pattern
5154 @cindex @code{usadd@var{m}3} instruction pattern
5155 @cindex @code{sub@var{m}3} instruction pattern
5156 @cindex @code{sssub@var{m}3} instruction pattern
5157 @cindex @code{ussub@var{m}3} instruction pattern
5158 @cindex @code{mul@var{m}3} instruction pattern
5159 @cindex @code{ssmul@var{m}3} instruction pattern
5160 @cindex @code{usmul@var{m}3} instruction pattern
5161 @cindex @code{div@var{m}3} instruction pattern
5162 @cindex @code{ssdiv@var{m}3} instruction pattern
5163 @cindex @code{udiv@var{m}3} instruction pattern
5164 @cindex @code{usdiv@var{m}3} instruction pattern
5165 @cindex @code{mod@var{m}3} instruction pattern
5166 @cindex @code{umod@var{m}3} instruction pattern
5167 @cindex @code{umin@var{m}3} instruction pattern
5168 @cindex @code{umax@var{m}3} instruction pattern
5169 @cindex @code{and@var{m}3} instruction pattern
5170 @cindex @code{ior@var{m}3} instruction pattern
5171 @cindex @code{xor@var{m}3} instruction pattern
5172 @item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
5173 @itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
5174 @itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
5175 @itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
5176 @itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
5177 @itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
5178 @itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
5179 @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
5180 Similar, for other arithmetic operations.
5181
5182 @cindex @code{addv@var{m}4} instruction pattern
5183 @item @samp{addv@var{m}4}
5184 Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and
5185 emits code to jump to it if signed overflow occurs during the addition.
5186 This pattern is used to implement the built-in functions performing
5187 signed integer addition with overflow checking.
5188
5189 @cindex @code{subv@var{m}4} instruction pattern
5190 @cindex @code{mulv@var{m}4} instruction pattern
5191 @item @samp{subv@var{m}4}, @samp{mulv@var{m}4}
5192 Similar, for other signed arithmetic operations.
5193
5194 @cindex @code{uaddv@var{m}4} instruction pattern
5195 @item @samp{uaddv@var{m}4}
5196 Like @code{addv@var{m}4} but for unsigned addition. That is to
5197 say, the operation is the same as signed addition but the jump
5198 is taken only on unsigned overflow.
5199
5200 @cindex @code{usubv@var{m}4} instruction pattern
5201 @cindex @code{umulv@var{m}4} instruction pattern
5202 @item @samp{usubv@var{m}4}, @samp{umulv@var{m}4}
5203 Similar, for other unsigned arithmetic operations.
5204
5205 @cindex @code{addptr@var{m}3} instruction pattern
5206 @item @samp{addptr@var{m}3}
5207 Like @code{add@var{m}3} but is guaranteed to only be used for address
5208 calculations. The expanded code is not allowed to clobber the
5209 condition code. It only needs to be defined if @code{add@var{m}3}
5210 sets the condition code. If adds used for address calculations and
5211 normal adds are not compatible it is required to expand a distinct
5212 pattern (e.g.@: using an unspec). The pattern is used by LRA to emit
5213 address calculations. @code{add@var{m}3} is used if
5214 @code{addptr@var{m}3} is not defined.
5215
5216 @cindex @code{fma@var{m}4} instruction pattern
5217 @item @samp{fma@var{m}4}
5218 Multiply operand 2 and operand 1, then add operand 3, storing the
5219 result in operand 0 without doing an intermediate rounding step. All
5220 operands must have mode @var{m}. This pattern is used to implement
5221 the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from
5222 the ISO C99 standard.
5223
5224 @cindex @code{fms@var{m}4} instruction pattern
5225 @item @samp{fms@var{m}4}
5226 Like @code{fma@var{m}4}, except operand 3 subtracted from the
5227 product instead of added to the product. This is represented
5228 in the rtl as
5229
5230 @smallexample
5231 (fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
5232 @end smallexample
5233
5234 @cindex @code{fnma@var{m}4} instruction pattern
5235 @item @samp{fnma@var{m}4}
5236 Like @code{fma@var{m}4} except that the intermediate product
5237 is negated before being added to operand 3. This is represented
5238 in the rtl as
5239
5240 @smallexample
5241 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
5242 @end smallexample
5243
5244 @cindex @code{fnms@var{m}4} instruction pattern
5245 @item @samp{fnms@var{m}4}
5246 Like @code{fms@var{m}4} except that the intermediate product
5247 is negated before subtracting operand 3. This is represented
5248 in the rtl as
5249
5250 @smallexample
5251 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
5252 @end smallexample
5253
5254 @cindex @code{min@var{m}3} instruction pattern
5255 @cindex @code{max@var{m}3} instruction pattern
5256 @item @samp{smin@var{m}3}, @samp{smax@var{m}3}
5257 Signed minimum and maximum operations. When used with floating point,
5258 if both operands are zeros, or if either operand is @code{NaN}, then
5259 it is unspecified which of the two operands is returned as the result.
5260
5261 @cindex @code{fmin@var{m}3} instruction pattern
5262 @cindex @code{fmax@var{m}3} instruction pattern
5263 @item @samp{fmin@var{m}3}, @samp{fmax@var{m}3}
5264 IEEE-conformant minimum and maximum operations. If one operand is a quiet
5265 @code{NaN}, then the other operand is returned. If both operands are quiet
5266 @code{NaN}, then a quiet @code{NaN} is returned. In the case when gcc supports
5267 signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is
5268 raised and a quiet @code{NaN} is returned.
5269
5270 All operands have mode @var{m}, which is a scalar or vector
5271 floating-point mode. These patterns are not allowed to @code{FAIL}.
5272
5273 @cindex @code{reduc_smin_scal_@var{m}} instruction pattern
5274 @cindex @code{reduc_smax_scal_@var{m}} instruction pattern
5275 @item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}}
5276 Find the signed minimum/maximum of the elements of a vector. The vector is
5277 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5278 the elements of the input vector.
5279
5280 @cindex @code{reduc_umin_scal_@var{m}} instruction pattern
5281 @cindex @code{reduc_umax_scal_@var{m}} instruction pattern
5282 @item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}}
5283 Find the unsigned minimum/maximum of the elements of a vector. The vector is
5284 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
5285 the elements of the input vector.
5286
5287 @cindex @code{reduc_fmin_scal_@var{m}} instruction pattern
5288 @cindex @code{reduc_fmax_scal_@var{m}} instruction pattern
5289 @item @samp{reduc_fmin_scal_@var{m}}, @samp{reduc_fmax_scal_@var{m}}
5290 Find the floating-point minimum/maximum of the elements of a vector,
5291 using the same rules as @code{fmin@var{m}3} and @code{fmax@var{m}3}.
5292 Operand 1 is a vector of mode @var{m} and operand 0 is the scalar
5293 result, which has mode @code{GET_MODE_INNER (@var{m})}.
5294
5295 @cindex @code{reduc_plus_scal_@var{m}} instruction pattern
5296 @item @samp{reduc_plus_scal_@var{m}}
5297 Compute the sum of the elements of a vector. The vector is operand 1, and
5298 operand 0 is the scalar result, with mode equal to the mode of the elements of
5299 the input vector.
5300
5301 @cindex @code{reduc_and_scal_@var{m}} instruction pattern
5302 @cindex @code{reduc_ior_scal_@var{m}} instruction pattern
5303 @cindex @code{reduc_xor_scal_@var{m}} instruction pattern
5304 @item @samp{reduc_and_scal_@var{m}}
5305 @itemx @samp{reduc_ior_scal_@var{m}}
5306 @itemx @samp{reduc_xor_scal_@var{m}}
5307 Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements
5308 of a vector of mode @var{m}. Operand 1 is the vector input and operand 0
5309 is the scalar result. The mode of the scalar result is the same as one
5310 element of @var{m}.
5311
5312 @cindex @code{extract_last_@var{m}} instruction pattern
5313 @item @code{extract_last_@var{m}}
5314 Find the last set bit in mask operand 1 and extract the associated element
5315 of vector operand 2. Store the result in scalar operand 0. Operand 2
5316 has vector mode @var{m} while operand 0 has the mode appropriate for one
5317 element of @var{m}. Operand 1 has the usual mask mode for vectors of mode
5318 @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5319
5320 @cindex @code{fold_extract_last_@var{m}} instruction pattern
5321 @item @code{fold_extract_last_@var{m}}
5322 If any bits of mask operand 2 are set, find the last set bit, extract
5323 the associated element from vector operand 3, and store the result
5324 in operand 0. Store operand 1 in operand 0 otherwise. Operand 3
5325 has mode @var{m} and operands 0 and 1 have the mode appropriate for
5326 one element of @var{m}. Operand 2 has the usual mask mode for vectors
5327 of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.
5328
5329 @cindex @code{fold_left_plus_@var{m}} instruction pattern
5330 @item @code{fold_left_plus_@var{m}}
5331 Take scalar operand 1 and successively add each element from vector
5332 operand 2. Store the result in scalar operand 0. The vector has
5333 mode @var{m} and the scalars have the mode appropriate for one
5334 element of @var{m}. The operation is strictly in-order: there is
5335 no reassociation.
5336
5337 @cindex @code{mask_fold_left_plus_@var{m}} instruction pattern
5338 @item @code{mask_fold_left_plus_@var{m}}
5339 Like @samp{fold_left_plus_@var{m}}, but takes an additional mask operand
5340 (operand 3) that specifies which elements of the source vector should be added.
5341
5342 @cindex @code{sdot_prod@var{m}} instruction pattern
5343 @item @samp{sdot_prod@var{m}}
5344
5345 Compute the sum of the products of two signed elements.
5346 Operand 1 and operand 2 are of the same mode. Their
5347 product, which is of a wider mode, is computed and added to operand 3.
5348 Operand 3 is of a mode equal or wider than the mode of the product. The
5349 result is placed in operand 0, which is of the same mode as operand 3.
5350
5351 Semantically the expressions perform the multiplication in the following signs
5352
5353 @smallexample
5354 sdot<signed op0, signed op1, signed op2, signed op3> ==
5355 op0 = sign-ext (op1) * sign-ext (op2) + op3
5356 @dots{}
5357 @end smallexample
5358
5359 @cindex @code{udot_prod@var{m}} instruction pattern
5360 @item @samp{udot_prod@var{m}}
5361
5362 Compute the sum of the products of two unsigned elements.
5363 Operand 1 and operand 2 are of the same mode. Their
5364 product, which is of a wider mode, is computed and added to operand 3.
5365 Operand 3 is of a mode equal or wider than the mode of the product. The
5366 result is placed in operand 0, which is of the same mode as operand 3.
5367
5368 Semantically the expressions perform the multiplication in the following signs
5369
5370 @smallexample
5371 udot<unsigned op0, unsigned op1, unsigned op2, unsigned op3> ==
5372 op0 = zero-ext (op1) * zero-ext (op2) + op3
5373 @dots{}
5374 @end smallexample
5375
5376 @cindex @code{usdot_prod@var{m}} instruction pattern
5377 @item @samp{usdot_prod@var{m}}
5378 Compute the sum of the products of elements of different signs.
5379 Operand 1 must be unsigned and operand 2 signed. Their
5380 product, which is of a wider mode, is computed and added to operand 3.
5381 Operand 3 is of a mode equal or wider than the mode of the product. The
5382 result is placed in operand 0, which is of the same mode as operand 3.
5383
5384 Semantically the expressions perform the multiplication in the following signs
5385
5386 @smallexample
5387 usdot<signed op0, unsigned op1, signed op2, signed op3> ==
5388 op0 = ((signed-conv) zero-ext (op1)) * sign-ext (op2) + op3
5389 @dots{}
5390 @end smallexample
5391
5392 @cindex @code{ssad@var{m}} instruction pattern
5393 @cindex @code{usad@var{m}} instruction pattern
5394 @item @samp{ssad@var{m}}
5395 @item @samp{usad@var{m}}
5396 Compute the sum of absolute differences of two signed/unsigned elements.
5397 Operand 1 and operand 2 are of the same mode. Their absolute difference, which
5398 is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode
5399 equal or wider than the mode of the absolute difference. The result is placed
5400 in operand 0, which is of the same mode as operand 3.
5401
5402 @cindex @code{widen_ssum@var{m3}} instruction pattern
5403 @cindex @code{widen_usum@var{m3}} instruction pattern
5404 @item @samp{widen_ssum@var{m3}}
5405 @itemx @samp{widen_usum@var{m3}}
5406 Operands 0 and 2 are of the same mode, which is wider than the mode of
5407 operand 1. Add operand 1 to operand 2 and place the widened result in
5408 operand 0. (This is used express accumulation of elements into an accumulator
5409 of a wider mode.)
5410
5411 @cindex @code{smulhs@var{m3}} instruction pattern
5412 @cindex @code{umulhs@var{m3}} instruction pattern
5413 @item @samp{smulhs@var{m3}}
5414 @itemx @samp{umulhs@var{m3}}
5415 Signed/unsigned multiply high with scale. This is equivalent to the C code:
5416 @smallexample
5417 narrow op0, op1, op2;
5418 @dots{}
5419 op0 = (narrow) (((wide) op1 * (wide) op2) >> (N / 2 - 1));
5420 @end smallexample
5421 where the sign of @samp{narrow} determines whether this is a signed
5422 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5423
5424 @cindex @code{smulhrs@var{m3}} instruction pattern
5425 @cindex @code{umulhrs@var{m3}} instruction pattern
5426 @item @samp{smulhrs@var{m3}}
5427 @itemx @samp{umulhrs@var{m3}}
5428 Signed/unsigned multiply high with round and scale. This is
5429 equivalent to the C code:
5430 @smallexample
5431 narrow op0, op1, op2;
5432 @dots{}
5433 op0 = (narrow) (((((wide) op1 * (wide) op2) >> (N / 2 - 2)) + 1) >> 1);
5434 @end smallexample
5435 where the sign of @samp{narrow} determines whether this is a signed
5436 or unsigned operation, and @var{N} is the size of @samp{wide} in bits.
5437
5438 @cindex @code{sdiv_pow2@var{m3}} instruction pattern
5439 @cindex @code{sdiv_pow2@var{m3}} instruction pattern
5440 @item @samp{sdiv_pow2@var{m3}}
5441 @itemx @samp{sdiv_pow2@var{m3}}
5442 Signed division by power-of-2 immediate. Equivalent to:
5443 @smallexample
5444 signed op0, op1;
5445 @dots{}
5446 op0 = op1 / (1 << imm);
5447 @end smallexample
5448
5449 @cindex @code{vec_shl_insert_@var{m}} instruction pattern
5450 @item @samp{vec_shl_insert_@var{m}}
5451 Shift the elements in vector input operand 1 left one element (i.e.@:
5452 away from element 0) and fill the vacated element 0 with the scalar
5453 in operand 2. Store the result in vector output operand 0. Operands
5454 0 and 1 have mode @var{m} and operand 2 has the mode appropriate for
5455 one element of @var{m}.
5456
5457 @cindex @code{vec_shl_@var{m}} instruction pattern
5458 @item @samp{vec_shl_@var{m}}
5459 Whole vector left shift in bits, i.e.@: away from element 0.
5460 Operand 1 is a vector to be shifted.
5461 Operand 2 is an integer shift amount in bits.
5462 Operand 0 is where the resulting shifted vector is stored.
5463 The output and input vectors should have the same modes.
5464
5465 @cindex @code{vec_shr_@var{m}} instruction pattern
5466 @item @samp{vec_shr_@var{m}}
5467 Whole vector right shift in bits, i.e.@: towards element 0.
5468 Operand 1 is a vector to be shifted.
5469 Operand 2 is an integer shift amount in bits.
5470 Operand 0 is where the resulting shifted vector is stored.
5471 The output and input vectors should have the same modes.
5472
5473 @cindex @code{vec_pack_trunc_@var{m}} instruction pattern
5474 @item @samp{vec_pack_trunc_@var{m}}
5475 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5476 are vectors of the same mode having N integral or floating point elements
5477 of size S@. Operand 0 is the resulting vector in which 2*N elements of
5478 size S/2 are concatenated after narrowing them down using truncation.
5479
5480 @cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern
5481 @item @samp{vec_pack_sbool_trunc_@var{m}}
5482 Narrow and merge the elements of two vectors. Operands 1 and 2 are vectors
5483 of the same type having N boolean elements. Operand 0 is the resulting
5484 vector in which 2*N elements are concatenated. The last operand (operand 3)
5485 is the number of elements in the output vector 2*N as a @code{CONST_INT}.
5486 This instruction pattern is used when all the vector input and output
5487 operands have the same scalar mode @var{m} and thus using
5488 @code{vec_pack_trunc_@var{m}} would be ambiguous.
5489
5490 @cindex @code{vec_pack_ssat_@var{m}} instruction pattern
5491 @cindex @code{vec_pack_usat_@var{m}} instruction pattern
5492 @item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
5493 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
5494 are vectors of the same mode having N integral elements of size S.
5495 Operand 0 is the resulting vector in which the elements of the two input
5496 vectors are concatenated after narrowing them down using signed/unsigned
5497 saturating arithmetic.
5498
5499 @cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
5500 @cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
5501 @item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
5502 Narrow, convert to signed/unsigned integral type and merge the elements
5503 of two vectors. Operands 1 and 2 are vectors of the same mode having N
5504 floating point elements of size S@. Operand 0 is the resulting vector
5505 in which 2*N elements of size S/2 are concatenated.
5506
5507 @cindex @code{vec_packs_float_@var{m}} instruction pattern
5508 @cindex @code{vec_packu_float_@var{m}} instruction pattern
5509 @item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}}
5510 Narrow, convert to floating point type and merge the elements
5511 of two vectors. Operands 1 and 2 are vectors of the same mode having N
5512 signed/unsigned integral elements of size S@. Operand 0 is the resulting vector
5513 in which 2*N elements of size S/2 are concatenated.
5514
5515 @cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
5516 @cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
5517 @item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
5518 Extract and widen (promote) the high/low part of a vector of signed
5519 integral or floating point elements. The input vector (operand 1) has N
5520 elements of size S@. Widen (promote) the high/low elements of the vector
5521 using signed or floating point extension and place the resulting N/2
5522 values of size 2*S in the output vector (operand 0).
5523
5524 @cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
5525 @cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
5526 @item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
5527 Extract and widen (promote) the high/low part of a vector of unsigned
5528 integral elements. The input vector (operand 1) has N elements of size S.
5529 Widen (promote) the high/low elements of the vector using zero extension and
5530 place the resulting N/2 values of size 2*S in the output vector (operand 0).
5531
5532 @cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern
5533 @cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern
5534 @item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}}
5535 Extract the high/low part of a vector of boolean elements that have scalar
5536 mode @var{m}. The input vector (operand 1) has N elements, the output
5537 vector (operand 0) has N/2 elements. The last operand (operand 2) is the
5538 number of elements of the input vector N as a @code{CONST_INT}. These
5539 patterns are used if both the input and output vectors have the same scalar
5540 mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or
5541 @code{vec_unpacks_lo_@var{m}} would be ambiguous.
5542
5543 @cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
5544 @cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
5545 @cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
5546 @cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
5547 @item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
5548 @itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
5549 Extract, convert to floating point type and widen the high/low part of a
5550 vector of signed/unsigned integral elements. The input vector (operand 1)
5551 has N elements of size S@. Convert the high/low elements of the vector using
5552 floating point conversion and place the resulting N/2 values of size 2*S in
5553 the output vector (operand 0).
5554
5555 @cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern
5556 @cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern
5557 @cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern
5558 @cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern
5559 @item @samp{vec_unpack_sfix_trunc_hi_@var{m}},
5560 @itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}}
5561 @itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}}
5562 @itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}}
5563 Extract, convert to signed/unsigned integer type and widen the high/low part of a
5564 vector of floating point elements. The input vector (operand 1)
5565 has N elements of size S@. Convert the high/low elements of the vector
5566 to integers and place the resulting N/2 values of size 2*S in
5567 the output vector (operand 0).
5568
5569 @cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
5570 @cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern
5571 @cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
5572 @cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
5573 @cindex @code{vec_widen_umult_even_@var{m}} instruction pattern
5574 @cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern
5575 @cindex @code{vec_widen_smult_even_@var{m}} instruction pattern
5576 @cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern
5577 @item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
5578 @itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
5579 @itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}}
5580 @itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}}
5581 Signed/Unsigned widening multiplication. The two inputs (operands 1 and 2)
5582 are vectors with N signed/unsigned elements of size S@. Multiply the high/low
5583 or even/odd elements of the two vectors, and put the N/2 products of size 2*S
5584 in the output vector (operand 0). A target shouldn't implement even/odd pattern
5585 pair if it is less efficient than lo/hi one.
5586
5587 @cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
5588 @cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
5589 @cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
5590 @cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
5591 @item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
5592 @itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
5593 Signed/Unsigned widening shift left. The first input (operand 1) is a vector
5594 with N signed/unsigned elements of size S@. Operand 2 is a constant. Shift
5595 the high/low elements of operand 1, and put the N/2 results of size 2*S in the
5596 output vector (operand 0).
5597
5598 @cindex @code{vec_widen_saddl_hi_@var{m}} instruction pattern
5599 @cindex @code{vec_widen_saddl_lo_@var{m}} instruction pattern
5600 @cindex @code{vec_widen_uaddl_hi_@var{m}} instruction pattern
5601 @cindex @code{vec_widen_uaddl_lo_@var{m}} instruction pattern
5602 @item @samp{vec_widen_uaddl_hi_@var{m}}, @samp{vec_widen_uaddl_lo_@var{m}}
5603 @itemx @samp{vec_widen_saddl_hi_@var{m}}, @samp{vec_widen_saddl_lo_@var{m}}
5604 Signed/Unsigned widening add long. Operands 1 and 2 are vectors with N
5605 signed/unsigned elements of size S@. Add the high/low elements of 1 and 2
5606 together, widen the resulting elements and put the N/2 results of size 2*S in
5607 the output vector (operand 0).
5608
5609 @cindex @code{vec_widen_ssubl_hi_@var{m}} instruction pattern
5610 @cindex @code{vec_widen_ssubl_lo_@var{m}} instruction pattern
5611 @cindex @code{vec_widen_usubl_hi_@var{m}} instruction pattern
5612 @cindex @code{vec_widen_usubl_lo_@var{m}} instruction pattern
5613 @item @samp{vec_widen_usubl_hi_@var{m}}, @samp{vec_widen_usubl_lo_@var{m}}
5614 @itemx @samp{vec_widen_ssubl_hi_@var{m}}, @samp{vec_widen_ssubl_lo_@var{m}}
5615 Signed/Unsigned widening subtract long. Operands 1 and 2 are vectors with N
5616 signed/unsigned elements of size S@. Subtract the high/low elements of 2 from
5617 1 and widen the resulting elements. Put the N/2 results of size 2*S in the
5618 output vector (operand 0).
5619
5620 @cindex @code{vec_addsub@var{m}3} instruction pattern
5621 @item @samp{vec_addsub@var{m}3}
5622 Alternating subtract, add with even lanes doing subtract and odd
5623 lanes doing addition. Operands 1 and 2 and the outout operand are vectors
5624 with mode @var{m}.
5625
5626 @cindex @code{vec_fmaddsub@var{m}4} instruction pattern
5627 @item @samp{vec_fmaddsub@var{m}4}
5628 Alternating multiply subtract, add with even lanes doing subtract and odd
5629 lanes doing addition of the third operand to the multiplication result
5630 of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
5631 with mode @var{m}.
5632
5633 @cindex @code{vec_fmsubadd@var{m}4} instruction pattern
5634 @item @samp{vec_fmsubadd@var{m}4}
5635 Alternating multiply add, subtract with even lanes doing addition and odd
5636 lanes doing subtraction of the third operand to the multiplication result
5637 of the first two operands. Operands 1, 2 and 3 and the outout operand are vectors
5638 with mode @var{m}.
5639
5640 These instructions are not allowed to @code{FAIL}.
5641
5642 @cindex @code{mulhisi3} instruction pattern
5643 @item @samp{mulhisi3}
5644 Multiply operands 1 and 2, which have mode @code{HImode}, and store
5645 a @code{SImode} product in operand 0.
5646
5647 @cindex @code{mulqihi3} instruction pattern
5648 @cindex @code{mulsidi3} instruction pattern
5649 @item @samp{mulqihi3}, @samp{mulsidi3}
5650 Similar widening-multiplication instructions of other widths.
5651
5652 @cindex @code{umulqihi3} instruction pattern
5653 @cindex @code{umulhisi3} instruction pattern
5654 @cindex @code{umulsidi3} instruction pattern
5655 @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
5656 Similar widening-multiplication instructions that do unsigned
5657 multiplication.
5658
5659 @cindex @code{usmulqihi3} instruction pattern
5660 @cindex @code{usmulhisi3} instruction pattern
5661 @cindex @code{usmulsidi3} instruction pattern
5662 @item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
5663 Similar widening-multiplication instructions that interpret the first
5664 operand as unsigned and the second operand as signed, then do a signed
5665 multiplication.
5666
5667 @cindex @code{smul@var{m}3_highpart} instruction pattern
5668 @item @samp{smul@var{m}3_highpart}
5669 Perform a signed multiplication of operands 1 and 2, which have mode
5670 @var{m}, and store the most significant half of the product in operand 0.
5671 The least significant half of the product is discarded. This may be
5672 represented in RTL using a @code{smul_highpart} RTX expression.
5673
5674 @cindex @code{umul@var{m}3_highpart} instruction pattern
5675 @item @samp{umul@var{m}3_highpart}
5676 Similar, but the multiplication is unsigned. This may be represented
5677 in RTL using an @code{umul_highpart} RTX expression.
5678
5679 @cindex @code{madd@var{m}@var{n}4} instruction pattern
5680 @item @samp{madd@var{m}@var{n}4}
5681 Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
5682 operand 3, and store the result in operand 0. Operands 1 and 2
5683 have mode @var{m} and operands 0 and 3 have mode @var{n}.
5684 Both modes must be integer or fixed-point modes and @var{n} must be twice
5685 the size of @var{m}.
5686
5687 In other words, @code{madd@var{m}@var{n}4} is like
5688 @code{mul@var{m}@var{n}3} except that it also adds operand 3.
5689
5690 These instructions are not allowed to @code{FAIL}.
5691
5692 @cindex @code{umadd@var{m}@var{n}4} instruction pattern
5693 @item @samp{umadd@var{m}@var{n}4}
5694 Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
5695 operands instead of sign-extending them.
5696
5697 @cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
5698 @item @samp{ssmadd@var{m}@var{n}4}
5699 Like @code{madd@var{m}@var{n}4}, but all involved operations must be
5700 signed-saturating.
5701
5702 @cindex @code{usmadd@var{m}@var{n}4} instruction pattern
5703 @item @samp{usmadd@var{m}@var{n}4}
5704 Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
5705 unsigned-saturating.
5706
5707 @cindex @code{msub@var{m}@var{n}4} instruction pattern
5708 @item @samp{msub@var{m}@var{n}4}
5709 Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
5710 result from operand 3, and store the result in operand 0. Operands 1 and 2
5711 have mode @var{m} and operands 0 and 3 have mode @var{n}.
5712 Both modes must be integer or fixed-point modes and @var{n} must be twice
5713 the size of @var{m}.
5714
5715 In other words, @code{msub@var{m}@var{n}4} is like
5716 @code{mul@var{m}@var{n}3} except that it also subtracts the result
5717 from operand 3.
5718
5719 These instructions are not allowed to @code{FAIL}.
5720
5721 @cindex @code{umsub@var{m}@var{n}4} instruction pattern
5722 @item @samp{umsub@var{m}@var{n}4}
5723 Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
5724 operands instead of sign-extending them.
5725
5726 @cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
5727 @item @samp{ssmsub@var{m}@var{n}4}
5728 Like @code{msub@var{m}@var{n}4}, but all involved operations must be
5729 signed-saturating.
5730
5731 @cindex @code{usmsub@var{m}@var{n}4} instruction pattern
5732 @item @samp{usmsub@var{m}@var{n}4}
5733 Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
5734 unsigned-saturating.
5735
5736 @cindex @code{divmod@var{m}4} instruction pattern
5737 @item @samp{divmod@var{m}4}
5738 Signed division that produces both a quotient and a remainder.
5739 Operand 1 is divided by operand 2 to produce a quotient stored
5740 in operand 0 and a remainder stored in operand 3.
5741
5742 For machines with an instruction that produces both a quotient and a
5743 remainder, provide a pattern for @samp{divmod@var{m}4} but do not
5744 provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}. This
5745 allows optimization in the relatively common case when both the quotient
5746 and remainder are computed.
5747
5748 If an instruction that just produces a quotient or just a remainder
5749 exists and is more efficient than the instruction that produces both,
5750 write the output routine of @samp{divmod@var{m}4} to call
5751 @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
5752 quotient or remainder and generate the appropriate instruction.
5753
5754 @cindex @code{udivmod@var{m}4} instruction pattern
5755 @item @samp{udivmod@var{m}4}
5756 Similar, but does unsigned division.
5757
5758 @anchor{shift patterns}
5759 @cindex @code{ashl@var{m}3} instruction pattern
5760 @cindex @code{ssashl@var{m}3} instruction pattern
5761 @cindex @code{usashl@var{m}3} instruction pattern
5762 @item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
5763 Arithmetic-shift operand 1 left by a number of bits specified by operand
5764 2, and store the result in operand 0. Here @var{m} is the mode of
5765 operand 0 and operand 1; operand 2's mode is specified by the
5766 instruction pattern, and the compiler will convert the operand to that
5767 mode before generating the instruction. The shift or rotate expander
5768 or instruction pattern should explicitly specify the mode of the operand 2,
5769 it should never be @code{VOIDmode}. The meaning of out-of-range shift
5770 counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
5771 @xref{TARGET_SHIFT_TRUNCATION_MASK}. Operand 2 is always a scalar type.
5772
5773 @cindex @code{ashr@var{m}3} instruction pattern
5774 @cindex @code{lshr@var{m}3} instruction pattern
5775 @cindex @code{rotl@var{m}3} instruction pattern
5776 @cindex @code{rotr@var{m}3} instruction pattern
5777 @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
5778 Other shift and rotate instructions, analogous to the
5779 @code{ashl@var{m}3} instructions. Operand 2 is always a scalar type.
5780
5781 @cindex @code{vashl@var{m}3} instruction pattern
5782 @cindex @code{vashr@var{m}3} instruction pattern
5783 @cindex @code{vlshr@var{m}3} instruction pattern
5784 @cindex @code{vrotl@var{m}3} instruction pattern
5785 @cindex @code{vrotr@var{m}3} instruction pattern
5786 @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}
5787 Vector shift and rotate instructions that take vectors as operand 2
5788 instead of a scalar type.
5789
5790 @cindex @code{avg@var{m}3_floor} instruction pattern
5791 @cindex @code{uavg@var{m}3_floor} instruction pattern
5792 @item @samp{avg@var{m}3_floor}
5793 @itemx @samp{uavg@var{m}3_floor}
5794 Signed and unsigned average instructions. These instructions add
5795 operands 1 and 2 without truncation, divide the result by 2,
5796 round towards -Inf, and store the result in operand 0. This is
5797 equivalent to the C code:
5798 @smallexample
5799 narrow op0, op1, op2;
5800 @dots{}
5801 op0 = (narrow) (((wide) op1 + (wide) op2) >> 1);
5802 @end smallexample
5803 where the sign of @samp{narrow} determines whether this is a signed
5804 or unsigned operation.
5805
5806 @cindex @code{avg@var{m}3_ceil} instruction pattern
5807 @cindex @code{uavg@var{m}3_ceil} instruction pattern
5808 @item @samp{avg@var{m}3_ceil}
5809 @itemx @samp{uavg@var{m}3_ceil}
5810 Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round
5811 towards +Inf. This is equivalent to the C code:
5812 @smallexample
5813 narrow op0, op1, op2;
5814 @dots{}
5815 op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1);
5816 @end smallexample
5817
5818 @cindex @code{bswap@var{m}2} instruction pattern
5819 @item @samp{bswap@var{m}2}
5820 Reverse the order of bytes of operand 1 and store the result in operand 0.
5821
5822 @cindex @code{neg@var{m}2} instruction pattern
5823 @cindex @code{ssneg@var{m}2} instruction pattern
5824 @cindex @code{usneg@var{m}2} instruction pattern
5825 @item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
5826 Negate operand 1 and store the result in operand 0.
5827
5828 @cindex @code{negv@var{m}3} instruction pattern
5829 @item @samp{negv@var{m}3}
5830 Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and
5831 emits code to jump to it if signed overflow occurs during the negation.
5832
5833 @cindex @code{abs@var{m}2} instruction pattern
5834 @item @samp{abs@var{m}2}
5835 Store the absolute value of operand 1 into operand 0.
5836
5837 @cindex @code{sqrt@var{m}2} instruction pattern
5838 @item @samp{sqrt@var{m}2}
5839 Store the square root of operand 1 into operand 0. Both operands have
5840 mode @var{m}, which is a scalar or vector floating-point mode.
5841
5842 This pattern is not allowed to @code{FAIL}.
5843
5844 @cindex @code{rsqrt@var{m}2} instruction pattern
5845 @item @samp{rsqrt@var{m}2}
5846 Store the reciprocal of the square root of operand 1 into operand 0.
5847 Both operands have mode @var{m}, which is a scalar or vector
5848 floating-point mode.
5849
5850 On most architectures this pattern is only approximate, so either
5851 its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should
5852 check for the appropriate math flags. (Using the C condition is
5853 more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful
5854 if a target-specific built-in also uses the @samp{rsqrt@var{m}2}
5855 pattern.)
5856
5857 This pattern is not allowed to @code{FAIL}.
5858
5859 @cindex @code{fmod@var{m}3} instruction pattern
5860 @item @samp{fmod@var{m}3}
5861 Store the remainder of dividing operand 1 by operand 2 into
5862 operand 0, rounded towards zero to an integer. All operands have
5863 mode @var{m}, which is a scalar or vector floating-point mode.
5864
5865 This pattern is not allowed to @code{FAIL}.
5866
5867 @cindex @code{remainder@var{m}3} instruction pattern
5868 @item @samp{remainder@var{m}3}
5869 Store the remainder of dividing operand 1 by operand 2 into
5870 operand 0, rounded to the nearest integer. All operands have
5871 mode @var{m}, which is a scalar or vector floating-point mode.
5872
5873 This pattern is not allowed to @code{FAIL}.
5874
5875 @cindex @code{scalb@var{m}3} instruction pattern
5876 @item @samp{scalb@var{m}3}
5877 Raise @code{FLT_RADIX} to the power of operand 2, multiply it by
5878 operand 1, and store the result in operand 0. All operands have
5879 mode @var{m}, which is a scalar or vector floating-point mode.
5880
5881 This pattern is not allowed to @code{FAIL}.
5882
5883 @cindex @code{ldexp@var{m}3} instruction pattern
5884 @item @samp{ldexp@var{m}3}
5885 Raise 2 to the power of operand 2, multiply it by operand 1, and store
5886 the result in operand 0. Operands 0 and 1 have mode @var{m}, which is
5887 a scalar or vector floating-point mode. Operand 2's mode has
5888 the same number of elements as @var{m} and each element is wide
5889 enough to store an @code{int}. The integers are signed.
5890
5891 This pattern is not allowed to @code{FAIL}.
5892
5893 @cindex @code{cos@var{m}2} instruction pattern
5894 @item @samp{cos@var{m}2}
5895 Store the cosine of operand 1 into operand 0. Both operands have
5896 mode @var{m}, which is a scalar or vector floating-point mode.
5897
5898 This pattern is not allowed to @code{FAIL}.
5899
5900 @cindex @code{sin@var{m}2} instruction pattern
5901 @item @samp{sin@var{m}2}
5902 Store the sine of operand 1 into operand 0. Both operands have
5903 mode @var{m}, which is a scalar or vector floating-point mode.
5904
5905 This pattern is not allowed to @code{FAIL}.
5906
5907 @cindex @code{sincos@var{m}3} instruction pattern
5908 @item @samp{sincos@var{m}3}
5909 Store the cosine of operand 2 into operand 0 and the sine of
5910 operand 2 into operand 1. All operands have mode @var{m},
5911 which is a scalar or vector floating-point mode.
5912
5913 Targets that can calculate the sine and cosine simultaneously can
5914 implement this pattern as opposed to implementing individual
5915 @code{sin@var{m}2} and @code{cos@var{m}2} patterns. The @code{sin}
5916 and @code{cos} built-in functions will then be expanded to the
5917 @code{sincos@var{m}3} pattern, with one of the output values
5918 left unused.
5919
5920 @cindex @code{tan@var{m}2} instruction pattern
5921 @item @samp{tan@var{m}2}
5922 Store the tangent of operand 1 into operand 0. Both operands have
5923 mode @var{m}, which is a scalar or vector floating-point mode.
5924
5925 This pattern is not allowed to @code{FAIL}.
5926
5927 @cindex @code{asin@var{m}2} instruction pattern
5928 @item @samp{asin@var{m}2}
5929 Store the arc sine of operand 1 into operand 0. Both operands have
5930 mode @var{m}, which is a scalar or vector floating-point mode.
5931
5932 This pattern is not allowed to @code{FAIL}.
5933
5934 @cindex @code{acos@var{m}2} instruction pattern
5935 @item @samp{acos@var{m}2}
5936 Store the arc cosine of operand 1 into operand 0. Both operands have
5937 mode @var{m}, which is a scalar or vector floating-point mode.
5938
5939 This pattern is not allowed to @code{FAIL}.
5940
5941 @cindex @code{atan@var{m}2} instruction pattern
5942 @item @samp{atan@var{m}2}
5943 Store the arc tangent of operand 1 into operand 0. Both operands have
5944 mode @var{m}, which is a scalar or vector floating-point mode.
5945
5946 This pattern is not allowed to @code{FAIL}.
5947
5948 @cindex @code{fegetround@var{m}} instruction pattern
5949 @item @samp{fegetround@var{m}}
5950 Store the current machine floating-point rounding mode into operand 0.
5951 Operand 0 has mode @var{m}, which is scalar. This pattern is used to
5952 implement the @code{fegetround} function from the ISO C99 standard.
5953
5954 @cindex @code{feclearexcept@var{m}} instruction pattern
5955 @cindex @code{feraiseexcept@var{m}} instruction pattern
5956 @item @samp{feclearexcept@var{m}}
5957 @item @samp{feraiseexcept@var{m}}
5958 Clears or raises the supported machine floating-point exceptions
5959 represented by the bits in operand 1. Error status is stored as
5960 nonzero value in operand 0. Both operands have mode @var{m}, which is
5961 a scalar. These patterns are used to implement the
5962 @code{feclearexcept} and @code{feraiseexcept} functions from the ISO
5963 C99 standard.
5964
5965 @cindex @code{exp@var{m}2} instruction pattern
5966 @item @samp{exp@var{m}2}
5967 Raise e (the base of natural logarithms) to the power of operand 1
5968 and store the result in operand 0. Both operands have mode @var{m},
5969 which is a scalar or vector floating-point mode.
5970
5971 This pattern is not allowed to @code{FAIL}.
5972
5973 @cindex @code{expm1@var{m}2} instruction pattern
5974 @item @samp{expm1@var{m}2}
5975 Raise e (the base of natural logarithms) to the power of operand 1,
5976 subtract 1, and store the result in operand 0. Both operands have
5977 mode @var{m}, which is a scalar or vector floating-point mode.
5978
5979 For inputs close to zero, the pattern is expected to be more
5980 accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3}
5981 would be.
5982
5983 This pattern is not allowed to @code{FAIL}.
5984
5985 @cindex @code{exp10@var{m}2} instruction pattern
5986 @item @samp{exp10@var{m}2}
5987 Raise 10 to the power of operand 1 and store the result in operand 0.
5988 Both operands have mode @var{m}, which is a scalar or vector
5989 floating-point mode.
5990
5991 This pattern is not allowed to @code{FAIL}.
5992
5993 @cindex @code{exp2@var{m}2} instruction pattern
5994 @item @samp{exp2@var{m}2}
5995 Raise 2 to the power of operand 1 and store the result in operand 0.
5996 Both operands have mode @var{m}, which is a scalar or vector
5997 floating-point mode.
5998
5999 This pattern is not allowed to @code{FAIL}.
6000
6001 @cindex @code{log@var{m}2} instruction pattern
6002 @item @samp{log@var{m}2}
6003 Store the natural logarithm of operand 1 into operand 0. Both operands
6004 have mode @var{m}, which is a scalar or vector floating-point mode.
6005
6006 This pattern is not allowed to @code{FAIL}.
6007
6008 @cindex @code{log1p@var{m}2} instruction pattern
6009 @item @samp{log1p@var{m}2}
6010 Add 1 to operand 1, compute the natural logarithm, and store
6011 the result in operand 0. Both operands have mode @var{m}, which is
6012 a scalar or vector floating-point mode.
6013
6014 For inputs close to zero, the pattern is expected to be more
6015 accurate than a separate @code{add@var{m}3} and @code{log@var{m}2}
6016 would be.
6017
6018 This pattern is not allowed to @code{FAIL}.
6019
6020 @cindex @code{log10@var{m}2} instruction pattern
6021 @item @samp{log10@var{m}2}
6022 Store the base-10 logarithm of operand 1 into operand 0. Both operands
6023 have mode @var{m}, which is a scalar or vector floating-point mode.
6024
6025 This pattern is not allowed to @code{FAIL}.
6026
6027 @cindex @code{log2@var{m}2} instruction pattern
6028 @item @samp{log2@var{m}2}
6029 Store the base-2 logarithm of operand 1 into operand 0. Both operands
6030 have mode @var{m}, which is a scalar or vector floating-point mode.
6031
6032 This pattern is not allowed to @code{FAIL}.
6033
6034 @cindex @code{logb@var{m}2} instruction pattern
6035 @item @samp{logb@var{m}2}
6036 Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0.
6037 Both operands have mode @var{m}, which is a scalar or vector
6038 floating-point mode.
6039
6040 This pattern is not allowed to @code{FAIL}.
6041
6042 @cindex @code{signbit@var{m}2} instruction pattern
6043 @item @samp{signbit@var{m}2}
6044 Store the sign bit of floating-point operand 1 in operand 0.
6045 @var{m} is either a scalar or vector mode. When it is a scalar,
6046 operand 1 has mode @var{m} but operand 0 must have mode @code{SImode}.
6047 When @var{m} is a vector, operand 1 has the mode @var{m}.
6048 operand 0's mode should be an vector integer mode which has
6049 the same number of elements and the same size as mode @var{m}.
6050
6051 This pattern is not allowed to @code{FAIL}.
6052
6053 @cindex @code{significand@var{m}2} instruction pattern
6054 @item @samp{significand@var{m}2}
6055 Store the significand of floating-point operand 1 in operand 0.
6056 Both operands have mode @var{m}, which is a scalar or vector
6057 floating-point mode.
6058
6059 This pattern is not allowed to @code{FAIL}.
6060
6061 @cindex @code{pow@var{m}3} instruction pattern
6062 @item @samp{pow@var{m}3}
6063 Store the value of operand 1 raised to the exponent operand 2
6064 into operand 0. All operands have mode @var{m}, which is a scalar
6065 or vector floating-point mode.
6066
6067 This pattern is not allowed to @code{FAIL}.
6068
6069 @cindex @code{atan2@var{m}3} instruction pattern
6070 @item @samp{atan2@var{m}3}
6071 Store the arc tangent (inverse tangent) of operand 1 divided by
6072 operand 2 into operand 0, using the signs of both arguments to
6073 determine the quadrant of the result. All operands have mode
6074 @var{m}, which is a scalar or vector floating-point mode.
6075
6076 This pattern is not allowed to @code{FAIL}.
6077
6078 @cindex @code{floor@var{m}2} instruction pattern
6079 @item @samp{floor@var{m}2}
6080 Store the largest integral value not greater than operand 1 in operand 0.
6081 Both operands have mode @var{m}, which is a scalar or vector
6082 floating-point mode. If @option{-ffp-int-builtin-inexact} is in
6083 effect, the ``inexact'' exception may be raised for noninteger
6084 operands; otherwise, it may not.
6085
6086 This pattern is not allowed to @code{FAIL}.
6087
6088 @cindex @code{btrunc@var{m}2} instruction pattern
6089 @item @samp{btrunc@var{m}2}
6090 Round operand 1 to an integer, towards zero, and store the result in
6091 operand 0. Both operands have mode @var{m}, which is a scalar or
6092 vector floating-point mode. If @option{-ffp-int-builtin-inexact} is
6093 in effect, the ``inexact'' exception may be raised for noninteger
6094 operands; otherwise, it may not.
6095
6096 This pattern is not allowed to @code{FAIL}.
6097
6098 @cindex @code{round@var{m}2} instruction pattern
6099 @item @samp{round@var{m}2}
6100 Round operand 1 to the nearest integer, rounding away from zero in the
6101 event of a tie, and store the result in operand 0. Both operands have
6102 mode @var{m}, which is a scalar or vector floating-point mode. If
6103 @option{-ffp-int-builtin-inexact} is in effect, the ``inexact''
6104 exception may be raised for noninteger operands; otherwise, it may
6105 not.
6106
6107 This pattern is not allowed to @code{FAIL}.
6108
6109 @cindex @code{ceil@var{m}2} instruction pattern
6110 @item @samp{ceil@var{m}2}
6111 Store the smallest integral value not less than operand 1 in operand 0.
6112 Both operands have mode @var{m}, which is a scalar or vector
6113 floating-point mode. If @option{-ffp-int-builtin-inexact} is in
6114 effect, the ``inexact'' exception may be raised for noninteger
6115 operands; otherwise, it may not.
6116
6117 This pattern is not allowed to @code{FAIL}.
6118
6119 @cindex @code{nearbyint@var{m}2} instruction pattern
6120 @item @samp{nearbyint@var{m}2}
6121 Round operand 1 to an integer, using the current rounding mode, and
6122 store the result in operand 0. Do not raise an inexact condition when
6123 the result is different from the argument. Both operands have mode
6124 @var{m}, which is a scalar or vector floating-point mode.
6125
6126 This pattern is not allowed to @code{FAIL}.
6127
6128 @cindex @code{rint@var{m}2} instruction pattern
6129 @item @samp{rint@var{m}2}
6130 Round operand 1 to an integer, using the current rounding mode, and
6131 store the result in operand 0. Raise an inexact condition when
6132 the result is different from the argument. Both operands have mode
6133 @var{m}, which is a scalar or vector floating-point mode.
6134
6135 This pattern is not allowed to @code{FAIL}.
6136
6137 @cindex @code{lrint@var{m}@var{n}2}
6138 @item @samp{lrint@var{m}@var{n}2}
6139 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6140 point mode @var{n} as a signed number according to the current
6141 rounding mode and store in operand 0 (which has mode @var{n}).
6142
6143 @cindex @code{lround@var{m}@var{n}2}
6144 @item @samp{lround@var{m}@var{n}2}
6145 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6146 point mode @var{n} as a signed number rounding to nearest and away
6147 from zero and store in operand 0 (which has mode @var{n}).
6148
6149 @cindex @code{lfloor@var{m}@var{n}2}
6150 @item @samp{lfloor@var{m}@var{n}2}
6151 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6152 point mode @var{n} as a signed number rounding down and store in
6153 operand 0 (which has mode @var{n}).
6154
6155 @cindex @code{lceil@var{m}@var{n}2}
6156 @item @samp{lceil@var{m}@var{n}2}
6157 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6158 point mode @var{n} as a signed number rounding up and store in
6159 operand 0 (which has mode @var{n}).
6160
6161 @cindex @code{copysign@var{m}3} instruction pattern
6162 @item @samp{copysign@var{m}3}
6163 Store a value with the magnitude of operand 1 and the sign of operand
6164 2 into operand 0. All operands have mode @var{m}, which is a scalar or
6165 vector floating-point mode.
6166
6167 This pattern is not allowed to @code{FAIL}.
6168
6169 @cindex @code{xorsign@var{m}3} instruction pattern
6170 @item @samp{xorsign@var{m}3}
6171 Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with
6172 the magnitude of operand 1 and the sign of operand 2 into operand 0.
6173 All operands have mode @var{m}, which is a scalar or vector
6174 floating-point mode.
6175
6176 This pattern is not allowed to @code{FAIL}.
6177
6178 @cindex @code{issignaling@var{m}2} instruction pattern
6179 @item @samp{issignaling@var{m}2}
6180 Set operand 0 to 1 if operand 1 is a signaling NaN and to 0 otherwise.
6181
6182 @cindex @code{cadd90@var{m}3} instruction pattern
6183 @item @samp{cadd90@var{m}3}
6184 Perform vector add and subtract on even/odd number pairs. The operation being
6185 matched is semantically described as
6186
6187 @smallexample
6188 for (int i = 0; i < N; i += 2)
6189 @{
6190 c[i] = a[i] - b[i+1];
6191 c[i+1] = a[i+1] + b[i];
6192 @}
6193 @end smallexample
6194
6195 This operation is semantically equivalent to performing a vector addition of
6196 complex numbers in operand 1 with operand 2 rotated by 90 degrees around
6197 the argand plane and storing the result in operand 0.
6198
6199 In GCC lane ordering the real part of the number must be in the even lanes with
6200 the imaginary part in the odd lanes.
6201
6202 The operation is only supported for vector modes @var{m}.
6203
6204 This pattern is not allowed to @code{FAIL}.
6205
6206 @cindex @code{cadd270@var{m}3} instruction pattern
6207 @item @samp{cadd270@var{m}3}
6208 Perform vector add and subtract on even/odd number pairs. The operation being
6209 matched is semantically described as
6210
6211 @smallexample
6212 for (int i = 0; i < N; i += 2)
6213 @{
6214 c[i] = a[i] + b[i+1];
6215 c[i+1] = a[i+1] - b[i];
6216 @}
6217 @end smallexample
6218
6219 This operation is semantically equivalent to performing a vector addition of
6220 complex numbers in operand 1 with operand 2 rotated by 270 degrees around
6221 the argand plane and storing the result in operand 0.
6222
6223 In GCC lane ordering the real part of the number must be in the even lanes with
6224 the imaginary part in the odd lanes.
6225
6226 The operation is only supported for vector modes @var{m}.
6227
6228 This pattern is not allowed to @code{FAIL}.
6229
6230 @cindex @code{cmla@var{m}4} instruction pattern
6231 @item @samp{cmla@var{m}4}
6232 Perform a vector multiply and accumulate that is semantically the same as
6233 a multiply and accumulate of complex numbers.
6234
6235 @smallexample
6236 complex TYPE op0[N];
6237 complex TYPE op1[N];
6238 complex TYPE op2[N];
6239 complex TYPE op3[N];
6240 for (int i = 0; i < N; i += 1)
6241 @{
6242 op0[i] = op1[i] * op2[i] + op3[i];
6243 @}
6244 @end smallexample
6245
6246 In GCC lane ordering the real part of the number must be in the even lanes with
6247 the imaginary part in the odd lanes.
6248
6249 The operation is only supported for vector modes @var{m}.
6250
6251 This pattern is not allowed to @code{FAIL}.
6252
6253 @cindex @code{cmla_conj@var{m}4} instruction pattern
6254 @item @samp{cmla_conj@var{m}4}
6255 Perform a vector multiply by conjugate and accumulate that is semantically
6256 the same as a multiply and accumulate of complex numbers where the second
6257 multiply arguments is conjugated.
6258
6259 @smallexample
6260 complex TYPE op0[N];
6261 complex TYPE op1[N];
6262 complex TYPE op2[N];
6263 complex TYPE op3[N];
6264 for (int i = 0; i < N; i += 1)
6265 @{
6266 op0[i] = op1[i] * conj (op2[i]) + op3[i];
6267 @}
6268 @end smallexample
6269
6270 In GCC lane ordering the real part of the number must be in the even lanes with
6271 the imaginary part in the odd lanes.
6272
6273 The operation is only supported for vector modes @var{m}.
6274
6275 This pattern is not allowed to @code{FAIL}.
6276
6277 @cindex @code{cmls@var{m}4} instruction pattern
6278 @item @samp{cmls@var{m}4}
6279 Perform a vector multiply and subtract that is semantically the same as
6280 a multiply and subtract of complex numbers.
6281
6282 @smallexample
6283 complex TYPE op0[N];
6284 complex TYPE op1[N];
6285 complex TYPE op2[N];
6286 complex TYPE op3[N];
6287 for (int i = 0; i < N; i += 1)
6288 @{
6289 op0[i] = op1[i] * op2[i] - op3[i];
6290 @}
6291 @end smallexample
6292
6293 In GCC lane ordering the real part of the number must be in the even lanes with
6294 the imaginary part in the odd lanes.
6295
6296 The operation is only supported for vector modes @var{m}.
6297
6298 This pattern is not allowed to @code{FAIL}.
6299
6300 @cindex @code{cmls_conj@var{m}4} instruction pattern
6301 @item @samp{cmls_conj@var{m}4}
6302 Perform a vector multiply by conjugate and subtract that is semantically
6303 the same as a multiply and subtract of complex numbers where the second
6304 multiply arguments is conjugated.
6305
6306 @smallexample
6307 complex TYPE op0[N];
6308 complex TYPE op1[N];
6309 complex TYPE op2[N];
6310 complex TYPE op3[N];
6311 for (int i = 0; i < N; i += 1)
6312 @{
6313 op0[i] = op1[i] * conj (op2[i]) - op3[i];
6314 @}
6315 @end smallexample
6316
6317 In GCC lane ordering the real part of the number must be in the even lanes with
6318 the imaginary part in the odd lanes.
6319
6320 The operation is only supported for vector modes @var{m}.
6321
6322 This pattern is not allowed to @code{FAIL}.
6323
6324 @cindex @code{cmul@var{m}4} instruction pattern
6325 @item @samp{cmul@var{m}4}
6326 Perform a vector multiply that is semantically the same as multiply of
6327 complex numbers.
6328
6329 @smallexample
6330 complex TYPE op0[N];
6331 complex TYPE op1[N];
6332 complex TYPE op2[N];
6333 for (int i = 0; i < N; i += 1)
6334 @{
6335 op0[i] = op1[i] * op2[i];
6336 @}
6337 @end smallexample
6338
6339 In GCC lane ordering the real part of the number must be in the even lanes with
6340 the imaginary part in the odd lanes.
6341
6342 The operation is only supported for vector modes @var{m}.
6343
6344 This pattern is not allowed to @code{FAIL}.
6345
6346 @cindex @code{cmul_conj@var{m}4} instruction pattern
6347 @item @samp{cmul_conj@var{m}4}
6348 Perform a vector multiply by conjugate that is semantically the same as a
6349 multiply of complex numbers where the second multiply arguments is conjugated.
6350
6351 @smallexample
6352 complex TYPE op0[N];
6353 complex TYPE op1[N];
6354 complex TYPE op2[N];
6355 for (int i = 0; i < N; i += 1)
6356 @{
6357 op0[i] = op1[i] * conj (op2[i]);
6358 @}
6359 @end smallexample
6360
6361 In GCC lane ordering the real part of the number must be in the even lanes with
6362 the imaginary part in the odd lanes.
6363
6364 The operation is only supported for vector modes @var{m}.
6365
6366 This pattern is not allowed to @code{FAIL}.
6367
6368 @cindex @code{ffs@var{m}2} instruction pattern
6369 @item @samp{ffs@var{m}2}
6370 Store into operand 0 one plus the index of the least significant 1-bit
6371 of operand 1. If operand 1 is zero, store zero.
6372
6373 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6374 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6375 integer mode is suitable for the target. The compiler will insert
6376 conversion instructions as necessary (typically to convert the result
6377 to the same width as @code{int}). When @var{m} is a vector, both
6378 operands must have mode @var{m}.
6379
6380 This pattern is not allowed to @code{FAIL}.
6381
6382 @cindex @code{clrsb@var{m}2} instruction pattern
6383 @item @samp{clrsb@var{m}2}
6384 Count leading redundant sign bits.
6385 Store into operand 0 the number of redundant sign bits in operand 1, starting
6386 at the most significant bit position.
6387 A redundant sign bit is defined as any sign bit after the first. As such,
6388 this count will be one less than the count of leading sign bits.
6389
6390 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6391 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6392 integer mode is suitable for the target. The compiler will insert
6393 conversion instructions as necessary (typically to convert the result
6394 to the same width as @code{int}). When @var{m} is a vector, both
6395 operands must have mode @var{m}.
6396
6397 This pattern is not allowed to @code{FAIL}.
6398
6399 @cindex @code{clz@var{m}2} instruction pattern
6400 @item @samp{clz@var{m}2}
6401 Store into operand 0 the number of leading 0-bits in operand 1, starting
6402 at the most significant bit position. If operand 1 is 0, the
6403 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6404 the result is undefined or has a useful value.
6405
6406 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6407 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6408 integer mode is suitable for the target. The compiler will insert
6409 conversion instructions as necessary (typically to convert the result
6410 to the same width as @code{int}). When @var{m} is a vector, both
6411 operands must have mode @var{m}.
6412
6413 This pattern is not allowed to @code{FAIL}.
6414
6415 @cindex @code{ctz@var{m}2} instruction pattern
6416 @item @samp{ctz@var{m}2}
6417 Store into operand 0 the number of trailing 0-bits in operand 1, starting
6418 at the least significant bit position. If operand 1 is 0, the
6419 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
6420 the result is undefined or has a useful value.
6421
6422 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6423 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6424 integer mode is suitable for the target. The compiler will insert
6425 conversion instructions as necessary (typically to convert the result
6426 to the same width as @code{int}). When @var{m} is a vector, both
6427 operands must have mode @var{m}.
6428
6429 This pattern is not allowed to @code{FAIL}.
6430
6431 @cindex @code{popcount@var{m}2} instruction pattern
6432 @item @samp{popcount@var{m}2}
6433 Store into operand 0 the number of 1-bits in operand 1.
6434
6435 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6436 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6437 integer mode is suitable for the target. The compiler will insert
6438 conversion instructions as necessary (typically to convert the result
6439 to the same width as @code{int}). When @var{m} is a vector, both
6440 operands must have mode @var{m}.
6441
6442 This pattern is not allowed to @code{FAIL}.
6443
6444 @cindex @code{parity@var{m}2} instruction pattern
6445 @item @samp{parity@var{m}2}
6446 Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
6447 in operand 1 modulo 2.
6448
6449 @var{m} is either a scalar or vector integer mode. When it is a scalar,
6450 operand 1 has mode @var{m} but operand 0 can have whatever scalar
6451 integer mode is suitable for the target. The compiler will insert
6452 conversion instructions as necessary (typically to convert the result
6453 to the same width as @code{int}). When @var{m} is a vector, both
6454 operands must have mode @var{m}.
6455
6456 This pattern is not allowed to @code{FAIL}.
6457
6458 @cindex @code{one_cmpl@var{m}2} instruction pattern
6459 @item @samp{one_cmpl@var{m}2}
6460 Store the bitwise-complement of operand 1 into operand 0.
6461
6462 @cindex @code{cpymem@var{m}} instruction pattern
6463 @item @samp{cpymem@var{m}}
6464 Block copy instruction. The destination and source blocks of memory
6465 are the first two operands, and both are @code{mem:BLK}s with an
6466 address in mode @code{Pmode}.
6467
6468 The number of bytes to copy is the third operand, in mode @var{m}.
6469 Usually, you specify @code{Pmode} for @var{m}. However, if you can
6470 generate better code knowing the range of valid lengths is smaller than
6471 those representable in a full Pmode pointer, you should provide
6472 a pattern with a
6473 mode corresponding to the range of values you can handle efficiently
6474 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6475 that appear negative) and also a pattern with @code{Pmode}.
6476
6477 The fourth operand is the known shared alignment of the source and
6478 destination, in the form of a @code{const_int} rtx. Thus, if the
6479 compiler knows that both source and destination are word-aligned,
6480 it may provide the value 4 for this operand.
6481
6482 Optional operands 5 and 6 specify expected alignment and size of block
6483 respectively. The expected alignment differs from alignment in operand 4
6484 in a way that the blocks are not required to be aligned according to it in
6485 all cases. This expected alignment is also in bytes, just like operand 4.
6486 Expected size, when unknown, is set to @code{(const_int -1)}.
6487
6488 Descriptions of multiple @code{cpymem@var{m}} patterns can only be
6489 beneficial if the patterns for smaller modes have fewer restrictions
6490 on their first, second and fourth operands. Note that the mode @var{m}
6491 in @code{cpymem@var{m}} does not impose any restriction on the mode of
6492 individually copied data units in the block.
6493
6494 The @code{cpymem@var{m}} patterns need not give special consideration
6495 to the possibility that the source and destination strings might
6496 overlap. These patterns are used to do inline expansion of
6497 @code{__builtin_memcpy}.
6498
6499 @cindex @code{movmem@var{m}} instruction pattern
6500 @item @samp{movmem@var{m}}
6501 Block move instruction. The destination and source blocks of memory
6502 are the first two operands, and both are @code{mem:BLK}s with an
6503 address in mode @code{Pmode}.
6504
6505 The number of bytes to copy is the third operand, in mode @var{m}.
6506 Usually, you specify @code{Pmode} for @var{m}. However, if you can
6507 generate better code knowing the range of valid lengths is smaller than
6508 those representable in a full Pmode pointer, you should provide
6509 a pattern with a
6510 mode corresponding to the range of values you can handle efficiently
6511 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
6512 that appear negative) and also a pattern with @code{Pmode}.
6513
6514 The fourth operand is the known shared alignment of the source and
6515 destination, in the form of a @code{const_int} rtx. Thus, if the
6516 compiler knows that both source and destination are word-aligned,
6517 it may provide the value 4 for this operand.
6518
6519 Optional operands 5 and 6 specify expected alignment and size of block
6520 respectively. The expected alignment differs from alignment in operand 4
6521 in a way that the blocks are not required to be aligned according to it in
6522 all cases. This expected alignment is also in bytes, just like operand 4.
6523 Expected size, when unknown, is set to @code{(const_int -1)}.
6524
6525 Descriptions of multiple @code{movmem@var{m}} patterns can only be
6526 beneficial if the patterns for smaller modes have fewer restrictions
6527 on their first, second and fourth operands. Note that the mode @var{m}
6528 in @code{movmem@var{m}} does not impose any restriction on the mode of
6529 individually copied data units in the block.
6530
6531 The @code{movmem@var{m}} patterns must correctly handle the case where
6532 the source and destination strings overlap. These patterns are used to
6533 do inline expansion of @code{__builtin_memmove}.
6534
6535 @cindex @code{movstr} instruction pattern
6536 @item @samp{movstr}
6537 String copy instruction, with @code{stpcpy} semantics. Operand 0 is
6538 an output operand in mode @code{Pmode}. The addresses of the
6539 destination and source strings are operands 1 and 2, and both are
6540 @code{mem:BLK}s with addresses in mode @code{Pmode}. The execution of
6541 the expansion of this pattern should store in operand 0 the address in
6542 which the @code{NUL} terminator was stored in the destination string.
6543
6544 This pattern has also several optional operands that are same as in
6545 @code{setmem}.
6546
6547 @cindex @code{setmem@var{m}} instruction pattern
6548 @item @samp{setmem@var{m}}
6549 Block set instruction. The destination string is the first operand,
6550 given as a @code{mem:BLK} whose address is in mode @code{Pmode}. The
6551 number of bytes to set is the second operand, in mode @var{m}. The value to
6552 initialize the memory with is the third operand. Targets that only support the
6553 clearing of memory should reject any value that is not the constant 0. See
6554 @samp{cpymem@var{m}} for a discussion of the choice of mode.
6555
6556 The fourth operand is the known alignment of the destination, in the form
6557 of a @code{const_int} rtx. Thus, if the compiler knows that the
6558 destination is word-aligned, it may provide the value 4 for this
6559 operand.
6560
6561 Optional operands 5 and 6 specify expected alignment and size of block
6562 respectively. The expected alignment differs from alignment in operand 4
6563 in a way that the blocks are not required to be aligned according to it in
6564 all cases. This expected alignment is also in bytes, just like operand 4.
6565 Expected size, when unknown, is set to @code{(const_int -1)}.
6566 Operand 7 is the minimal size of the block and operand 8 is the
6567 maximal size of the block (NULL if it cannot be represented as CONST_INT).
6568 Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for
6569 correctness, but it can be used for choosing proper code sequence for a
6570 given size).
6571
6572 The use for multiple @code{setmem@var{m}} is as for @code{cpymem@var{m}}.
6573
6574 @cindex @code{cmpstrn@var{m}} instruction pattern
6575 @item @samp{cmpstrn@var{m}}
6576 String compare instruction, with five operands. Operand 0 is the output;
6577 it has mode @var{m}. The remaining four operands are like the operands
6578 of @samp{cpymem@var{m}}. The two memory blocks specified are compared
6579 byte by byte in lexicographic order starting at the beginning of each
6580 string. The instruction is not allowed to prefetch more than one byte
6581 at a time since either string may end in the first byte and reading past
6582 that may access an invalid page or segment and cause a fault. The
6583 comparison terminates early if the fetched bytes are different or if
6584 they are equal to zero. The effect of the instruction is to store a
6585 value in operand 0 whose sign indicates the result of the comparison.
6586
6587 @cindex @code{cmpstr@var{m}} instruction pattern
6588 @item @samp{cmpstr@var{m}}
6589 String compare instruction, without known maximum length. Operand 0 is the
6590 output; it has mode @var{m}. The second and third operand are the blocks of
6591 memory to be compared; both are @code{mem:BLK} with an address in mode
6592 @code{Pmode}.
6593
6594 The fourth operand is the known shared alignment of the source and
6595 destination, in the form of a @code{const_int} rtx. Thus, if the
6596 compiler knows that both source and destination are word-aligned,
6597 it may provide the value 4 for this operand.
6598
6599 The two memory blocks specified are compared byte by byte in lexicographic
6600 order starting at the beginning of each string. The instruction is not allowed
6601 to prefetch more than one byte at a time since either string may end in the
6602 first byte and reading past that may access an invalid page or segment and
6603 cause a fault. The comparison will terminate when the fetched bytes
6604 are different or if they are equal to zero. The effect of the
6605 instruction is to store a value in operand 0 whose sign indicates the
6606 result of the comparison.
6607
6608 @cindex @code{cmpmem@var{m}} instruction pattern
6609 @item @samp{cmpmem@var{m}}
6610 Block compare instruction, with five operands like the operands
6611 of @samp{cmpstr@var{m}}. The two memory blocks specified are compared
6612 byte by byte in lexicographic order starting at the beginning of each
6613 block. Unlike @samp{cmpstr@var{m}} the instruction can prefetch
6614 any bytes in the two memory blocks. Also unlike @samp{cmpstr@var{m}}
6615 the comparison will not stop if both bytes are zero. The effect of
6616 the instruction is to store a value in operand 0 whose sign indicates
6617 the result of the comparison.
6618
6619 @cindex @code{strlen@var{m}} instruction pattern
6620 @item @samp{strlen@var{m}}
6621 Compute the length of a string, with three operands.
6622 Operand 0 is the result (of mode @var{m}), operand 1 is
6623 a @code{mem} referring to the first character of the string,
6624 operand 2 is the character to search for (normally zero),
6625 and operand 3 is a constant describing the known alignment
6626 of the beginning of the string.
6627
6628 @cindex @code{rawmemchr@var{m}} instruction pattern
6629 @item @samp{rawmemchr@var{m}}
6630 Scan memory referred to by operand 1 for the first occurrence of operand 2.
6631 Operand 1 is a @code{mem} and operand 2 a @code{const_int} of mode @var{m}.
6632 Operand 0 is the result, i.e., a pointer to the first occurrence of operand 2
6633 in the memory block given by operand 1.
6634
6635 @cindex @code{float@var{m}@var{n}2} instruction pattern
6636 @item @samp{float@var{m}@var{n}2}
6637 Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
6638 floating point mode @var{n} and store in operand 0 (which has mode
6639 @var{n}).
6640
6641 @cindex @code{floatuns@var{m}@var{n}2} instruction pattern
6642 @item @samp{floatuns@var{m}@var{n}2}
6643 Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
6644 to floating point mode @var{n} and store in operand 0 (which has mode
6645 @var{n}).
6646
6647 @cindex @code{fix@var{m}@var{n}2} instruction pattern
6648 @item @samp{fix@var{m}@var{n}2}
6649 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6650 point mode @var{n} as a signed number and store in operand 0 (which
6651 has mode @var{n}). This instruction's result is defined only when
6652 the value of operand 1 is an integer.
6653
6654 If the machine description defines this pattern, it also needs to
6655 define the @code{ftrunc} pattern.
6656
6657 @cindex @code{fixuns@var{m}@var{n}2} instruction pattern
6658 @item @samp{fixuns@var{m}@var{n}2}
6659 Convert operand 1 (valid for floating point mode @var{m}) to fixed
6660 point mode @var{n} as an unsigned number and store in operand 0 (which
6661 has mode @var{n}). This instruction's result is defined only when the
6662 value of operand 1 is an integer.
6663
6664 @cindex @code{ftrunc@var{m}2} instruction pattern
6665 @item @samp{ftrunc@var{m}2}
6666 Convert operand 1 (valid for floating point mode @var{m}) to an
6667 integer value, still represented in floating point mode @var{m}, and
6668 store it in operand 0 (valid for floating point mode @var{m}).
6669
6670 @cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
6671 @item @samp{fix_trunc@var{m}@var{n}2}
6672 Like @samp{fix@var{m}@var{n}2} but works for any floating point value
6673 of mode @var{m} by converting the value to an integer.
6674
6675 @cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
6676 @item @samp{fixuns_trunc@var{m}@var{n}2}
6677 Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
6678 value of mode @var{m} by converting the value to an integer.
6679
6680 @cindex @code{trunc@var{m}@var{n}2} instruction pattern
6681 @item @samp{trunc@var{m}@var{n}2}
6682 Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
6683 store in operand 0 (which has mode @var{n}). Both modes must be fixed
6684 point or both floating point.
6685
6686 @cindex @code{extend@var{m}@var{n}2} instruction pattern
6687 @item @samp{extend@var{m}@var{n}2}
6688 Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6689 store in operand 0 (which has mode @var{n}). Both modes must be fixed
6690 point or both floating point.
6691
6692 @cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
6693 @item @samp{zero_extend@var{m}@var{n}2}
6694 Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
6695 store in operand 0 (which has mode @var{n}). Both modes must be fixed
6696 point.
6697
6698 @cindex @code{fract@var{m}@var{n}2} instruction pattern
6699 @item @samp{fract@var{m}@var{n}2}
6700 Convert operand 1 of mode @var{m} to mode @var{n} and store in
6701 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
6702 could be fixed-point to fixed-point, signed integer to fixed-point,
6703 fixed-point to signed integer, floating-point to fixed-point,
6704 or fixed-point to floating-point.
6705 When overflows or underflows happen, the results are undefined.
6706
6707 @cindex @code{satfract@var{m}@var{n}2} instruction pattern
6708 @item @samp{satfract@var{m}@var{n}2}
6709 Convert operand 1 of mode @var{m} to mode @var{n} and store in
6710 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
6711 could be fixed-point to fixed-point, signed integer to fixed-point,
6712 or floating-point to fixed-point.
6713 When overflows or underflows happen, the instruction saturates the
6714 results to the maximum or the minimum.
6715
6716 @cindex @code{fractuns@var{m}@var{n}2} instruction pattern
6717 @item @samp{fractuns@var{m}@var{n}2}
6718 Convert operand 1 of mode @var{m} to mode @var{n} and store in
6719 operand 0 (which has mode @var{n}). Mode @var{m} and mode @var{n}
6720 could be unsigned integer to fixed-point, or
6721 fixed-point to unsigned integer.
6722 When overflows or underflows happen, the results are undefined.
6723
6724 @cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
6725 @item @samp{satfractuns@var{m}@var{n}2}
6726 Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
6727 @var{n} and store in operand 0 (which has mode @var{n}).
6728 When overflows or underflows happen, the instruction saturates the
6729 results to the maximum or the minimum.
6730
6731 @cindex @code{extv@var{m}} instruction pattern
6732 @item @samp{extv@var{m}}
6733 Extract a bit-field from register operand 1, sign-extend it, and store
6734 it in operand 0. Operand 2 specifies the width of the field in bits
6735 and operand 3 the starting bit, which counts from the most significant
6736 bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit
6737 otherwise.
6738
6739 Operands 0 and 1 both have mode @var{m}. Operands 2 and 3 have a
6740 target-specific mode.
6741
6742 @cindex @code{extvmisalign@var{m}} instruction pattern
6743 @item @samp{extvmisalign@var{m}}
6744 Extract a bit-field from memory operand 1, sign extend it, and store
6745 it in operand 0. Operand 2 specifies the width in bits and operand 3
6746 the starting bit. The starting bit is always somewhere in the first byte of
6747 operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
6748 is true and from the least significant bit otherwise.
6749
6750 Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode.
6751 Operands 2 and 3 have a target-specific mode.
6752
6753 The instruction must not read beyond the last byte of the bit-field.
6754
6755 @cindex @code{extzv@var{m}} instruction pattern
6756 @item @samp{extzv@var{m}}
6757 Like @samp{extv@var{m}} except that the bit-field value is zero-extended.
6758
6759 @cindex @code{extzvmisalign@var{m}} instruction pattern
6760 @item @samp{extzvmisalign@var{m}}
6761 Like @samp{extvmisalign@var{m}} except that the bit-field value is
6762 zero-extended.
6763
6764 @cindex @code{insv@var{m}} instruction pattern
6765 @item @samp{insv@var{m}}
6766 Insert operand 3 into a bit-field of register operand 0. Operand 1
6767 specifies the width of the field in bits and operand 2 the starting bit,
6768 which counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
6769 is true and from the least significant bit otherwise.
6770
6771 Operands 0 and 3 both have mode @var{m}. Operands 1 and 2 have a
6772 target-specific mode.
6773
6774 @cindex @code{insvmisalign@var{m}} instruction pattern
6775 @item @samp{insvmisalign@var{m}}
6776 Insert operand 3 into a bit-field of memory operand 0. Operand 1
6777 specifies the width of the field in bits and operand 2 the starting bit.
6778 The starting bit is always somewhere in the first byte of operand 0;
6779 it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
6780 is true and from the least significant bit otherwise.
6781
6782 Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode.
6783 Operands 1 and 2 have a target-specific mode.
6784
6785 The instruction must not read or write beyond the last byte of the bit-field.
6786
6787 @cindex @code{extv} instruction pattern
6788 @item @samp{extv}
6789 Extract a bit-field from operand 1 (a register or memory operand), where
6790 operand 2 specifies the width in bits and operand 3 the starting bit,
6791 and store it in operand 0. Operand 0 must have mode @code{word_mode}.
6792 Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
6793 @code{word_mode} is allowed only for registers. Operands 2 and 3 must
6794 be valid for @code{word_mode}.
6795
6796 The RTL generation pass generates this instruction only with constants
6797 for operands 2 and 3 and the constant is never zero for operand 2.
6798
6799 The bit-field value is sign-extended to a full word integer
6800 before it is stored in operand 0.
6801
6802 This pattern is deprecated; please use @samp{extv@var{m}} and
6803 @code{extvmisalign@var{m}} instead.
6804
6805 @cindex @code{extzv} instruction pattern
6806 @item @samp{extzv}
6807 Like @samp{extv} except that the bit-field value is zero-extended.
6808
6809 This pattern is deprecated; please use @samp{extzv@var{m}} and
6810 @code{extzvmisalign@var{m}} instead.
6811
6812 @cindex @code{insv} instruction pattern
6813 @item @samp{insv}
6814 Store operand 3 (which must be valid for @code{word_mode}) into a
6815 bit-field in operand 0, where operand 1 specifies the width in bits and
6816 operand 2 the starting bit. Operand 0 may have mode @code{byte_mode} or
6817 @code{word_mode}; often @code{word_mode} is allowed only for registers.
6818 Operands 1 and 2 must be valid for @code{word_mode}.
6819
6820 The RTL generation pass generates this instruction only with constants
6821 for operands 1 and 2 and the constant is never zero for operand 1.
6822
6823 This pattern is deprecated; please use @samp{insv@var{m}} and
6824 @code{insvmisalign@var{m}} instead.
6825
6826 @cindex @code{mov@var{mode}cc} instruction pattern
6827 @item @samp{mov@var{mode}cc}
6828 Conditionally move operand 2 or operand 3 into operand 0 according to the
6829 comparison in operand 1. If the comparison is true, operand 2 is moved
6830 into operand 0, otherwise operand 3 is moved.
6831
6832 The mode of the operands being compared need not be the same as the operands
6833 being moved. Some machines, sparc64 for example, have instructions that
6834 conditionally move an integer value based on the floating point condition
6835 codes and vice versa.
6836
6837 If the machine does not have conditional move instructions, do not
6838 define these patterns.
6839
6840 @cindex @code{add@var{mode}cc} instruction pattern
6841 @item @samp{add@var{mode}cc}
6842 Similar to @samp{mov@var{mode}cc} but for conditional addition. Conditionally
6843 move operand 2 or (operands 2 + operand 3) into operand 0 according to the
6844 comparison in operand 1. If the comparison is false, operand 2 is moved into
6845 operand 0, otherwise (operand 2 + operand 3) is moved.
6846
6847 @cindex @code{cond_add@var{mode}} instruction pattern
6848 @cindex @code{cond_sub@var{mode}} instruction pattern
6849 @cindex @code{cond_mul@var{mode}} instruction pattern
6850 @cindex @code{cond_div@var{mode}} instruction pattern
6851 @cindex @code{cond_udiv@var{mode}} instruction pattern
6852 @cindex @code{cond_mod@var{mode}} instruction pattern
6853 @cindex @code{cond_umod@var{mode}} instruction pattern
6854 @cindex @code{cond_and@var{mode}} instruction pattern
6855 @cindex @code{cond_ior@var{mode}} instruction pattern
6856 @cindex @code{cond_xor@var{mode}} instruction pattern
6857 @cindex @code{cond_smin@var{mode}} instruction pattern
6858 @cindex @code{cond_smax@var{mode}} instruction pattern
6859 @cindex @code{cond_umin@var{mode}} instruction pattern
6860 @cindex @code{cond_umax@var{mode}} instruction pattern
6861 @cindex @code{cond_fmin@var{mode}} instruction pattern
6862 @cindex @code{cond_fmax@var{mode}} instruction pattern
6863 @cindex @code{cond_ashl@var{mode}} instruction pattern
6864 @cindex @code{cond_ashr@var{mode}} instruction pattern
6865 @cindex @code{cond_lshr@var{mode}} instruction pattern
6866 @item @samp{cond_add@var{mode}}
6867 @itemx @samp{cond_sub@var{mode}}
6868 @itemx @samp{cond_mul@var{mode}}
6869 @itemx @samp{cond_div@var{mode}}
6870 @itemx @samp{cond_udiv@var{mode}}
6871 @itemx @samp{cond_mod@var{mode}}
6872 @itemx @samp{cond_umod@var{mode}}
6873 @itemx @samp{cond_and@var{mode}}
6874 @itemx @samp{cond_ior@var{mode}}
6875 @itemx @samp{cond_xor@var{mode}}
6876 @itemx @samp{cond_smin@var{mode}}
6877 @itemx @samp{cond_smax@var{mode}}
6878 @itemx @samp{cond_umin@var{mode}}
6879 @itemx @samp{cond_umax@var{mode}}
6880 @itemx @samp{cond_fmin@var{mode}}
6881 @itemx @samp{cond_fmax@var{mode}}
6882 @itemx @samp{cond_ashl@var{mode}}
6883 @itemx @samp{cond_ashr@var{mode}}
6884 @itemx @samp{cond_lshr@var{mode}}
6885 When operand 1 is true, perform an operation on operands 2 and 3 and
6886 store the result in operand 0, otherwise store operand 4 in operand 0.
6887 The operation works elementwise if the operands are vectors.
6888
6889 The scalar case is equivalent to:
6890
6891 @smallexample
6892 op0 = op1 ? op2 @var{op} op3 : op4;
6893 @end smallexample
6894
6895 while the vector case is equivalent to:
6896
6897 @smallexample
6898 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
6899 op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i];
6900 @end smallexample
6901
6902 where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}.
6903
6904 When defined for floating-point modes, the contents of @samp{op3[i]}
6905 are not interpreted if @samp{op1[i]} is false, just like they would not
6906 be in a normal C @samp{?:} condition.
6907
6908 Operands 0, 2, 3 and 4 all have mode @var{m}. Operand 1 is a scalar
6909 integer if @var{m} is scalar, otherwise it has the mode returned by
6910 @code{TARGET_VECTORIZE_GET_MASK_MODE}.
6911
6912 @samp{cond_@var{op}@var{mode}} generally corresponds to a conditional
6913 form of @samp{@var{op}@var{mode}3}. As an exception, the vector forms
6914 of shifts correspond to patterns like @code{vashl@var{mode}3} rather
6915 than patterns like @code{ashl@var{mode}3}.
6916
6917 @cindex @code{cond_fma@var{mode}} instruction pattern
6918 @cindex @code{cond_fms@var{mode}} instruction pattern
6919 @cindex @code{cond_fnma@var{mode}} instruction pattern
6920 @cindex @code{cond_fnms@var{mode}} instruction pattern
6921 @item @samp{cond_fma@var{mode}}
6922 @itemx @samp{cond_fms@var{mode}}
6923 @itemx @samp{cond_fnma@var{mode}}
6924 @itemx @samp{cond_fnms@var{mode}}
6925 Like @samp{cond_add@var{m}}, except that the conditional operation
6926 takes 3 operands rather than two. For example, the vector form of
6927 @samp{cond_fma@var{mode}} is equivalent to:
6928
6929 @smallexample
6930 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
6931 op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i];
6932 @end smallexample
6933
6934 @cindex @code{neg@var{mode}cc} instruction pattern
6935 @item @samp{neg@var{mode}cc}
6936 Similar to @samp{mov@var{mode}cc} but for conditional negation. Conditionally
6937 move the negation of operand 2 or the unchanged operand 3 into operand 0
6938 according to the comparison in operand 1. If the comparison is true, the negation
6939 of operand 2 is moved into operand 0, otherwise operand 3 is moved.
6940
6941 @cindex @code{not@var{mode}cc} instruction pattern
6942 @item @samp{not@var{mode}cc}
6943 Similar to @samp{neg@var{mode}cc} but for conditional complement.
6944 Conditionally move the bitwise complement of operand 2 or the unchanged
6945 operand 3 into operand 0 according to the comparison in operand 1.
6946 If the comparison is true, the complement of operand 2 is moved into
6947 operand 0, otherwise operand 3 is moved.
6948
6949 @cindex @code{cstore@var{mode}4} instruction pattern
6950 @item @samp{cstore@var{mode}4}
6951 Store zero or nonzero in operand 0 according to whether a comparison
6952 is true. Operand 1 is a comparison operator. Operand 2 and operand 3
6953 are the first and second operand of the comparison, respectively.
6954 You specify the mode that operand 0 must have when you write the
6955 @code{match_operand} expression. The compiler automatically sees which
6956 mode you have used and supplies an operand of that mode.
6957
6958 The value stored for a true condition must have 1 as its low bit, or
6959 else must be negative. Otherwise the instruction is not suitable and
6960 you should omit it from the machine description. You describe to the
6961 compiler exactly which value is stored by defining the macro
6962 @code{STORE_FLAG_VALUE} (@pxref{Misc}). If a description cannot be
6963 found that can be used for all the possible comparison operators, you
6964 should pick one and use a @code{define_expand} to map all results
6965 onto the one you chose.
6966
6967 These operations may @code{FAIL}, but should do so only in relatively
6968 uncommon cases; if they would @code{FAIL} for common cases involving
6969 integer comparisons, it is best to restrict the predicates to not
6970 allow these operands. Likewise if a given comparison operator will
6971 always fail, independent of the operands (for floating-point modes, the
6972 @code{ordered_comparison_operator} predicate is often useful in this case).
6973
6974 If this pattern is omitted, the compiler will generate a conditional
6975 branch---for example, it may copy a constant one to the target and branching
6976 around an assignment of zero to the target---or a libcall. If the predicate
6977 for operand 1 only rejects some operators, it will also try reordering the
6978 operands and/or inverting the result value (e.g.@: by an exclusive OR).
6979 These possibilities could be cheaper or equivalent to the instructions
6980 used for the @samp{cstore@var{mode}4} pattern followed by those required
6981 to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
6982 case, you can and should make operand 1's predicate reject some operators
6983 in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
6984 from the machine description.
6985
6986 @cindex @code{tbranch_@var{op}@var{mode}3} instruction pattern
6987 @item @samp{tbranch_@var{op}@var{mode}3}
6988 Conditional branch instruction combined with a bit test-and-compare
6989 instruction. Operand 0 is the operand of the comparison. Operand 1 is the bit
6990 position of Operand 1 to test. Operand 3 is the @code{code_label} to jump to.
6991 @var{op} is one of @var{eq} or @var{ne}.
6992
6993 @cindex @code{cbranch@var{mode}4} instruction pattern
6994 @item @samp{cbranch@var{mode}4}
6995 Conditional branch instruction combined with a compare instruction.
6996 Operand 0 is a comparison operator. Operand 1 and operand 2 are the
6997 first and second operands of the comparison, respectively. Operand 3
6998 is the @code{code_label} to jump to.
6999
7000 @cindex @code{jump} instruction pattern
7001 @item @samp{jump}
7002 A jump inside a function; an unconditional branch. Operand 0 is the
7003 @code{code_label} to jump to. This pattern name is mandatory on all
7004 machines.
7005
7006 @cindex @code{call} instruction pattern
7007 @item @samp{call}
7008 Subroutine call instruction returning no value. Operand 0 is the
7009 function to call; operand 1 is the number of bytes of arguments pushed
7010 as a @code{const_int}. Operand 2 is the result of calling the target
7011 hook @code{TARGET_FUNCTION_ARG} with the second argument @code{arg}
7012 yielding true for @code{arg.end_marker_p ()}, in a call after all
7013 parameters have been passed to that hook. By default this is the first
7014 register beyond those used for arguments in the call, or @code{NULL} if
7015 all the argument-registers are used in the call.
7016
7017 On most machines, operand 2 is not actually stored into the RTL
7018 pattern. It is supplied for the sake of some RISC machines which need
7019 to put this information into the assembler code; they can put it in
7020 the RTL instead of operand 1.
7021
7022 Operand 0 should be a @code{mem} RTX whose address is the address of the
7023 function. Note, however, that this address can be a @code{symbol_ref}
7024 expression even if it would not be a legitimate memory address on the
7025 target machine. If it is also not a valid argument for a call
7026 instruction, the pattern for this operation should be a
7027 @code{define_expand} (@pxref{Expander Definitions}) that places the
7028 address into a register and uses that register in the call instruction.
7029
7030 @cindex @code{call_value} instruction pattern
7031 @item @samp{call_value}
7032 Subroutine call instruction returning a value. Operand 0 is the hard
7033 register in which the value is returned. There are three more
7034 operands, the same as the three operands of the @samp{call}
7035 instruction (but with numbers increased by one).
7036
7037 Subroutines that return @code{BLKmode} objects use the @samp{call}
7038 insn.
7039
7040 @cindex @code{call_pop} instruction pattern
7041 @cindex @code{call_value_pop} instruction pattern
7042 @item @samp{call_pop}, @samp{call_value_pop}
7043 Similar to @samp{call} and @samp{call_value}, except used if defined and
7044 if @code{RETURN_POPS_ARGS} is nonzero. They should emit a @code{parallel}
7045 that contains both the function call and a @code{set} to indicate the
7046 adjustment made to the frame pointer.
7047
7048 For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
7049 patterns increases the number of functions for which the frame pointer
7050 can be eliminated, if desired.
7051
7052 @cindex @code{untyped_call} instruction pattern
7053 @item @samp{untyped_call}
7054 Subroutine call instruction returning a value of any type. Operand 0 is
7055 the function to call; operand 1 is a memory location where the result of
7056 calling the function is to be stored; operand 2 is a @code{parallel}
7057 expression where each element is a @code{set} expression that indicates
7058 the saving of a function return value into the result block.
7059
7060 This instruction pattern should be defined to support
7061 @code{__builtin_apply} on machines where special instructions are needed
7062 to call a subroutine with arbitrary arguments or to save the value
7063 returned. This instruction pattern is required on machines that have
7064 multiple registers that can hold a return value
7065 (i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).
7066
7067 @cindex @code{return} instruction pattern
7068 @item @samp{return}
7069 Subroutine return instruction. This instruction pattern name should be
7070 defined only if a single instruction can do all the work of returning
7071 from a function.
7072
7073 Like the @samp{mov@var{m}} patterns, this pattern is also used after the
7074 RTL generation phase. In this case it is to support machines where
7075 multiple instructions are usually needed to return from a function, but
7076 some class of functions only requires one instruction to implement a
7077 return. Normally, the applicable functions are those which do not need
7078 to save any registers or allocate stack space.
7079
7080 It is valid for this pattern to expand to an instruction using
7081 @code{simple_return} if no epilogue is required.
7082
7083 @cindex @code{simple_return} instruction pattern
7084 @item @samp{simple_return}
7085 Subroutine return instruction. This instruction pattern name should be
7086 defined only if a single instruction can do all the work of returning
7087 from a function on a path where no epilogue is required. This pattern
7088 is very similar to the @code{return} instruction pattern, but it is emitted
7089 only by the shrink-wrapping optimization on paths where the function
7090 prologue has not been executed, and a function return should occur without
7091 any of the effects of the epilogue. Additional uses may be introduced on
7092 paths where both the prologue and the epilogue have executed.
7093
7094 @findex reload_completed
7095 @findex leaf_function_p
7096 For such machines, the condition specified in this pattern should only
7097 be true when @code{reload_completed} is nonzero and the function's
7098 epilogue would only be a single instruction. For machines with register
7099 windows, the routine @code{leaf_function_p} may be used to determine if
7100 a register window push is required.
7101
7102 Machines that have conditional return instructions should define patterns
7103 such as
7104
7105 @smallexample
7106 (define_insn ""
7107 [(set (pc)
7108 (if_then_else (match_operator
7109 0 "comparison_operator"
7110 [(reg:CC CC_REG) (const_int 0)])
7111 (return)
7112 (pc)))]
7113 "@var{condition}"
7114 "@dots{}")
7115 @end smallexample
7116
7117 where @var{condition} would normally be the same condition specified on the
7118 named @samp{return} pattern.
7119
7120 @cindex @code{untyped_return} instruction pattern
7121 @item @samp{untyped_return}
7122 Untyped subroutine return instruction. This instruction pattern should
7123 be defined to support @code{__builtin_return} on machines where special
7124 instructions are needed to return a value of any type.
7125
7126 Operand 0 is a memory location where the result of calling a function
7127 with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
7128 expression where each element is a @code{set} expression that indicates
7129 the restoring of a function return value from the result block.
7130
7131 @cindex @code{nop} instruction pattern
7132 @item @samp{nop}
7133 No-op instruction. This instruction pattern name should always be defined
7134 to output a no-op in assembler code. @code{(const_int 0)} will do as an
7135 RTL pattern.
7136
7137 @cindex @code{indirect_jump} instruction pattern
7138 @item @samp{indirect_jump}
7139 An instruction to jump to an address which is operand zero.
7140 This pattern name is mandatory on all machines.
7141
7142 @cindex @code{casesi} instruction pattern
7143 @item @samp{casesi}
7144 Instruction to jump through a dispatch table, including bounds checking.
7145 This instruction takes five operands:
7146
7147 @enumerate
7148 @item
7149 The index to dispatch on, which has mode @code{SImode}.
7150
7151 @item
7152 The lower bound for indices in the table, an integer constant.
7153
7154 @item
7155 The total range of indices in the table---the largest index
7156 minus the smallest one (both inclusive).
7157
7158 @item
7159 A label that precedes the table itself.
7160
7161 @item
7162 A label to jump to if the index has a value outside the bounds.
7163 @end enumerate
7164
7165 The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
7166 @code{jump_table_data}. The number of elements in the table is one plus the
7167 difference between the upper bound and the lower bound.
7168
7169 @cindex @code{tablejump} instruction pattern
7170 @item @samp{tablejump}
7171 Instruction to jump to a variable address. This is a low-level
7172 capability which can be used to implement a dispatch table when there
7173 is no @samp{casesi} pattern.
7174
7175 This pattern requires two operands: the address or offset, and a label
7176 which should immediately precede the jump table. If the macro
7177 @code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
7178 operand is an offset which counts from the address of the table; otherwise,
7179 it is an absolute address to jump to. In either case, the first operand has
7180 mode @code{Pmode}.
7181
7182 The @samp{tablejump} insn is always the last insn before the jump
7183 table it uses. Its assembler code normally has no need to use the
7184 second operand, but you should incorporate it in the RTL pattern so
7185 that the jump optimizer will not delete the table as unreachable code.
7186
7187
7188 @cindex @code{doloop_end} instruction pattern
7189 @item @samp{doloop_end}
7190 Conditional branch instruction that decrements a register and
7191 jumps if the register is nonzero. Operand 0 is the register to
7192 decrement and test; operand 1 is the label to jump to if the
7193 register is nonzero.
7194 @xref{Looping Patterns}.
7195
7196 This optional instruction pattern should be defined for machines with
7197 low-overhead looping instructions as the loop optimizer will try to
7198 modify suitable loops to utilize it. The target hook
7199 @code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which
7200 low-overhead loops can be used.
7201
7202 @cindex @code{doloop_begin} instruction pattern
7203 @item @samp{doloop_begin}
7204 Companion instruction to @code{doloop_end} required for machines that
7205 need to perform some initialization, such as loading a special counter
7206 register. Operand 1 is the associated @code{doloop_end} pattern and
7207 operand 0 is the register that it decrements.
7208
7209 If initialization insns do not always need to be emitted, use a
7210 @code{define_expand} (@pxref{Expander Definitions}) and make it fail.
7211
7212 @cindex @code{canonicalize_funcptr_for_compare} instruction pattern
7213 @item @samp{canonicalize_funcptr_for_compare}
7214 Canonicalize the function pointer in operand 1 and store the result
7215 into operand 0.
7216
7217 Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
7218 may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
7219 and also has mode @code{Pmode}.
7220
7221 Canonicalization of a function pointer usually involves computing
7222 the address of the function which would be called if the function
7223 pointer were used in an indirect call.
7224
7225 Only define this pattern if function pointers on the target machine
7226 can have different values but still call the same function when
7227 used in an indirect call.
7228
7229 @cindex @code{save_stack_block} instruction pattern
7230 @cindex @code{save_stack_function} instruction pattern
7231 @cindex @code{save_stack_nonlocal} instruction pattern
7232 @cindex @code{restore_stack_block} instruction pattern
7233 @cindex @code{restore_stack_function} instruction pattern
7234 @cindex @code{restore_stack_nonlocal} instruction pattern
7235 @item @samp{save_stack_block}
7236 @itemx @samp{save_stack_function}
7237 @itemx @samp{save_stack_nonlocal}
7238 @itemx @samp{restore_stack_block}
7239 @itemx @samp{restore_stack_function}
7240 @itemx @samp{restore_stack_nonlocal}
7241 Most machines save and restore the stack pointer by copying it to or
7242 from an object of mode @code{Pmode}. Do not define these patterns on
7243 such machines.
7244
7245 Some machines require special handling for stack pointer saves and
7246 restores. On those machines, define the patterns corresponding to the
7247 non-standard cases by using a @code{define_expand} (@pxref{Expander
7248 Definitions}) that produces the required insns. The three types of
7249 saves and restores are:
7250
7251 @enumerate
7252 @item
7253 @samp{save_stack_block} saves the stack pointer at the start of a block
7254 that allocates a variable-sized object, and @samp{restore_stack_block}
7255 restores the stack pointer when the block is exited.
7256
7257 @item
7258 @samp{save_stack_function} and @samp{restore_stack_function} do a
7259 similar job for the outermost block of a function and are used when the
7260 function allocates variable-sized objects or calls @code{alloca}. Only
7261 the epilogue uses the restored stack pointer, allowing a simpler save or
7262 restore sequence on some machines.
7263
7264 @item
7265 @samp{save_stack_nonlocal} is used in functions that contain labels
7266 branched to by nested functions. It saves the stack pointer in such a
7267 way that the inner function can use @samp{restore_stack_nonlocal} to
7268 restore the stack pointer. The compiler generates code to restore the
7269 frame and argument pointer registers, but some machines require saving
7270 and restoring additional data such as register window information or
7271 stack backchains. Place insns in these patterns to save and restore any
7272 such required data.
7273 @end enumerate
7274
7275 When saving the stack pointer, operand 0 is the save area and operand 1
7276 is the stack pointer. The mode used to allocate the save area defaults
7277 to @code{Pmode} but you can override that choice by defining the
7278 @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}). You must
7279 specify an integral mode, or @code{VOIDmode} if no save area is needed
7280 for a particular type of save (either because no save is needed or
7281 because a machine-specific save area can be used). Operand 0 is the
7282 stack pointer and operand 1 is the save area for restore operations. If
7283 @samp{save_stack_block} is defined, operand 0 must not be
7284 @code{VOIDmode} since these saves can be arbitrarily nested.
7285
7286 A save area is a @code{mem} that is at a constant offset from
7287 @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
7288 nonlocal gotos and a @code{reg} in the other two cases.
7289
7290 @cindex @code{allocate_stack} instruction pattern
7291 @item @samp{allocate_stack}
7292 Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
7293 the stack pointer to create space for dynamically allocated data.
7294
7295 Store the resultant pointer to this space into operand 0. If you
7296 are allocating space from the main stack, do this by emitting a
7297 move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
7298 If you are allocating the space elsewhere, generate code to copy the
7299 location of the space to operand 0. In the latter case, you must
7300 ensure this space gets freed when the corresponding space on the main
7301 stack is free.
7302
7303 Do not define this pattern if all that must be done is the subtraction.
7304 Some machines require other operations such as stack probes or
7305 maintaining the back chain. Define this pattern to emit those
7306 operations in addition to updating the stack pointer.
7307
7308 @cindex @code{check_stack} instruction pattern
7309 @item @samp{check_stack}
7310 If stack checking (@pxref{Stack Checking}) cannot be done on your system by
7311 probing the stack, define this pattern to perform the needed check and signal
7312 an error if the stack has overflowed. The single operand is the address in
7313 the stack farthest from the current stack pointer that you need to validate.
7314 Normally, on platforms where this pattern is needed, you would obtain the
7315 stack limit from a global or thread-specific variable or register.
7316
7317 @cindex @code{probe_stack_address} instruction pattern
7318 @item @samp{probe_stack_address}
7319 If stack checking (@pxref{Stack Checking}) can be done on your system by
7320 probing the stack but without the need to actually access it, define this
7321 pattern and signal an error if the stack has overflowed. The single operand
7322 is the memory address in the stack that needs to be probed.
7323
7324 @cindex @code{probe_stack} instruction pattern
7325 @item @samp{probe_stack}
7326 If stack checking (@pxref{Stack Checking}) can be done on your system by
7327 probing the stack but doing it with a ``store zero'' instruction is not valid
7328 or optimal, define this pattern to do the probing differently and signal an
7329 error if the stack has overflowed. The single operand is the memory reference
7330 in the stack that needs to be probed.
7331
7332 @cindex @code{nonlocal_goto} instruction pattern
7333 @item @samp{nonlocal_goto}
7334 Emit code to generate a non-local goto, e.g., a jump from one function
7335 to a label in an outer function. This pattern has four arguments,
7336 each representing a value to be used in the jump. The first
7337 argument is to be loaded into the frame pointer, the second is
7338 the address to branch to (code to dispatch to the actual label),
7339 the third is the address of a location where the stack is saved,
7340 and the last is the address of the label, to be placed in the
7341 location for the incoming static chain.
7342
7343 On most machines you need not define this pattern, since GCC will
7344 already generate the correct code, which is to load the frame pointer
7345 and static chain, restore the stack (using the
7346 @samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
7347 to the dispatcher. You need only define this pattern if this code will
7348 not work on your machine.
7349
7350 @cindex @code{nonlocal_goto_receiver} instruction pattern
7351 @item @samp{nonlocal_goto_receiver}
7352 This pattern, if defined, contains code needed at the target of a
7353 nonlocal goto after the code already generated by GCC@. You will not
7354 normally need to define this pattern. A typical reason why you might
7355 need this pattern is if some value, such as a pointer to a global table,
7356 must be restored when the frame pointer is restored. Note that a nonlocal
7357 goto only occurs within a unit-of-translation, so a global table pointer
7358 that is shared by all functions of a given module need not be restored.
7359 There are no arguments.
7360
7361 @cindex @code{exception_receiver} instruction pattern
7362 @item @samp{exception_receiver}
7363 This pattern, if defined, contains code needed at the site of an
7364 exception handler that isn't needed at the site of a nonlocal goto. You
7365 will not normally need to define this pattern. A typical reason why you
7366 might need this pattern is if some value, such as a pointer to a global
7367 table, must be restored after control flow is branched to the handler of
7368 an exception. There are no arguments.
7369
7370 @cindex @code{builtin_setjmp_setup} instruction pattern
7371 @item @samp{builtin_setjmp_setup}
7372 This pattern, if defined, contains additional code needed to initialize
7373 the @code{jmp_buf}. You will not normally need to define this pattern.
7374 A typical reason why you might need this pattern is if some value, such
7375 as a pointer to a global table, must be restored. Though it is
7376 preferred that the pointer value be recalculated if possible (given the
7377 address of a label for instance). The single argument is a pointer to
7378 the @code{jmp_buf}. Note that the buffer is five words long and that
7379 the first three are normally used by the generic mechanism.
7380
7381 @cindex @code{builtin_setjmp_receiver} instruction pattern
7382 @item @samp{builtin_setjmp_receiver}
7383 This pattern, if defined, contains code needed at the site of a
7384 built-in setjmp that isn't needed at the site of a nonlocal goto. You
7385 will not normally need to define this pattern. A typical reason why you
7386 might need this pattern is if some value, such as a pointer to a global
7387 table, must be restored. It takes one argument, which is the label
7388 to which builtin_longjmp transferred control; this pattern may be emitted
7389 at a small offset from that label.
7390
7391 @cindex @code{builtin_longjmp} instruction pattern
7392 @item @samp{builtin_longjmp}
7393 This pattern, if defined, performs the entire action of the longjmp.
7394 You will not normally need to define this pattern unless you also define
7395 @code{builtin_setjmp_setup}. The single argument is a pointer to the
7396 @code{jmp_buf}.
7397
7398 @cindex @code{eh_return} instruction pattern
7399 @item @samp{eh_return}
7400 This pattern, if defined, affects the way @code{__builtin_eh_return},
7401 and thence the call frame exception handling library routines, are
7402 built. It is intended to handle non-trivial actions needed along
7403 the abnormal return path.
7404
7405 The address of the exception handler to which the function should return
7406 is passed as operand to this pattern. It will normally need to copied by
7407 the pattern to some special register or memory location.
7408 If the pattern needs to determine the location of the target call
7409 frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
7410 if defined; it will have already been assigned.
7411
7412 If this pattern is not defined, the default action will be to simply
7413 copy the return address to @code{EH_RETURN_HANDLER_RTX}. Either
7414 that macro or this pattern needs to be defined if call frame exception
7415 handling is to be used.
7416
7417 @cindex @code{prologue} instruction pattern
7418 @anchor{prologue instruction pattern}
7419 @item @samp{prologue}
7420 This pattern, if defined, emits RTL for entry to a function. The function
7421 entry is responsible for setting up the stack frame, initializing the frame
7422 pointer register, saving callee saved registers, etc.
7423
7424 Using a prologue pattern is generally preferred over defining
7425 @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.
7426
7427 The @code{prologue} pattern is particularly useful for targets which perform
7428 instruction scheduling.
7429
7430 @cindex @code{window_save} instruction pattern
7431 @anchor{window_save instruction pattern}
7432 @item @samp{window_save}
7433 This pattern, if defined, emits RTL for a register window save. It should
7434 be defined if the target machine has register windows but the window events
7435 are decoupled from calls to subroutines. The canonical example is the SPARC
7436 architecture.
7437
7438 @cindex @code{epilogue} instruction pattern
7439 @anchor{epilogue instruction pattern}
7440 @item @samp{epilogue}
7441 This pattern emits RTL for exit from a function. The function
7442 exit is responsible for deallocating the stack frame, restoring callee saved
7443 registers and emitting the return instruction.
7444
7445 Using an epilogue pattern is generally preferred over defining
7446 @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.
7447
7448 The @code{epilogue} pattern is particularly useful for targets which perform
7449 instruction scheduling or which have delay slots for their return instruction.
7450
7451 @cindex @code{sibcall_epilogue} instruction pattern
7452 @item @samp{sibcall_epilogue}
7453 This pattern, if defined, emits RTL for exit from a function without the final
7454 branch back to the calling function. This pattern will be emitted before any
7455 sibling call (aka tail call) sites.
7456
7457 The @code{sibcall_epilogue} pattern must not clobber any arguments used for
7458 parameter passing or any stack slots for arguments passed to the current
7459 function.
7460
7461 @cindex @code{trap} instruction pattern
7462 @item @samp{trap}
7463 This pattern, if defined, signals an error, typically by causing some
7464 kind of signal to be raised.
7465
7466 @cindex @code{ctrap@var{MM}4} instruction pattern
7467 @item @samp{ctrap@var{MM}4}
7468 Conditional trap instruction. Operand 0 is a piece of RTL which
7469 performs a comparison, and operands 1 and 2 are the arms of the
7470 comparison. Operand 3 is the trap code, an integer.
7471
7472 A typical @code{ctrap} pattern looks like
7473
7474 @smallexample
7475 (define_insn "ctrapsi4"
7476 [(trap_if (match_operator 0 "trap_operator"
7477 [(match_operand 1 "register_operand")
7478 (match_operand 2 "immediate_operand")])
7479 (match_operand 3 "const_int_operand" "i"))]
7480 ""
7481 "@dots{}")
7482 @end smallexample
7483
7484 @cindex @code{prefetch} instruction pattern
7485 @item @samp{prefetch}
7486 This pattern, if defined, emits code for a non-faulting data prefetch
7487 instruction. Operand 0 is the address of the memory to prefetch. Operand 1
7488 is a constant 1 if the prefetch is preparing for a write to the memory
7489 address, or a constant 0 otherwise. Operand 2 is the expected degree of
7490 temporal locality of the data and is a value between 0 and 3, inclusive; 0
7491 means that the data has no temporal locality, so it need not be left in the
7492 cache after the access; 3 means that the data has a high degree of temporal
7493 locality and should be left in all levels of cache possible; 1 and 2 mean,
7494 respectively, a low or moderate degree of temporal locality.
7495
7496 Targets that do not support write prefetches or locality hints can ignore
7497 the values of operands 1 and 2.
7498
7499 @cindex @code{blockage} instruction pattern
7500 @item @samp{blockage}
7501 This pattern defines a pseudo insn that prevents the instruction
7502 scheduler and other passes from moving instructions and using register
7503 equivalences across the boundary defined by the blockage insn.
7504 This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM.
7505
7506 @cindex @code{memory_blockage} instruction pattern
7507 @item @samp{memory_blockage}
7508 This pattern, if defined, represents a compiler memory barrier, and will be
7509 placed at points across which RTL passes may not propagate memory accesses.
7510 This instruction needs to read and write volatile BLKmode memory. It does
7511 not need to generate any machine instruction. If this pattern is not defined,
7512 the compiler falls back to emitting an instruction corresponding
7513 to @code{asm volatile ("" ::: "memory")}.
7514
7515 @cindex @code{memory_barrier} instruction pattern
7516 @item @samp{memory_barrier}
7517 If the target memory model is not fully synchronous, then this pattern
7518 should be defined to an instruction that orders both loads and stores
7519 before the instruction with respect to loads and stores after the instruction.
7520 This pattern has no operands.
7521
7522 @cindex @code{speculation_barrier} instruction pattern
7523 @item @samp{speculation_barrier}
7524 If the target can support speculative execution, then this pattern should
7525 be defined to an instruction that will block subsequent execution until
7526 any prior speculation conditions has been resolved. The pattern must also
7527 ensure that the compiler cannot move memory operations past the barrier,
7528 so it needs to be an UNSPEC_VOLATILE pattern. The pattern has no
7529 operands.
7530
7531 If this pattern is not defined then the default expansion of
7532 @code{__builtin_speculation_safe_value} will emit a warning. You can
7533 suppress this warning by defining this pattern with a final condition
7534 of @code{0} (zero), which tells the compiler that a speculation
7535 barrier is not needed for this target.
7536
7537 @cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
7538 @item @samp{sync_compare_and_swap@var{mode}}
7539 This pattern, if defined, emits code for an atomic compare-and-swap
7540 operation. Operand 1 is the memory on which the atomic operation is
7541 performed. Operand 2 is the ``old'' value to be compared against the
7542 current contents of the memory location. Operand 3 is the ``new'' value
7543 to store in the memory if the compare succeeds. Operand 0 is the result
7544 of the operation; it should contain the contents of the memory
7545 before the operation. If the compare succeeds, this should obviously be
7546 a copy of operand 2.
7547
7548 This pattern must show that both operand 0 and operand 1 are modified.
7549
7550 This pattern must issue any memory barrier instructions such that all
7551 memory operations before the atomic operation occur before the atomic
7552 operation and all memory operations after the atomic operation occur
7553 after the atomic operation.
7554
7555 For targets where the success or failure of the compare-and-swap
7556 operation is available via the status flags, it is possible to
7557 avoid a separate compare operation and issue the subsequent
7558 branch or store-flag operation immediately after the compare-and-swap.
7559 To this end, GCC will look for a @code{MODE_CC} set in the
7560 output of @code{sync_compare_and_swap@var{mode}}; if the machine
7561 description includes such a set, the target should also define special
7562 @code{cbranchcc4} and/or @code{cstorecc4} instructions. GCC will then
7563 be able to take the destination of the @code{MODE_CC} set and pass it
7564 to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
7565 operand of the comparison (the second will be @code{(const_int 0)}).
7566
7567 For targets where the operating system may provide support for this
7568 operation via library calls, the @code{sync_compare_and_swap_optab}
7569 may be initialized to a function with the same interface as the
7570 @code{__sync_val_compare_and_swap_@var{n}} built-in. If the entire
7571 set of @var{__sync} builtins are supported via library calls, the
7572 target can initialize all of the optabs at once with
7573 @code{init_sync_libfuncs}.
7574 For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
7575 assumed that these library calls do @emph{not} use any kind of
7576 interruptable locking.
7577
7578 @cindex @code{sync_add@var{mode}} instruction pattern
7579 @cindex @code{sync_sub@var{mode}} instruction pattern
7580 @cindex @code{sync_ior@var{mode}} instruction pattern
7581 @cindex @code{sync_and@var{mode}} instruction pattern
7582 @cindex @code{sync_xor@var{mode}} instruction pattern
7583 @cindex @code{sync_nand@var{mode}} instruction pattern
7584 @item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
7585 @itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
7586 @itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
7587 These patterns emit code for an atomic operation on memory.
7588 Operand 0 is the memory on which the atomic operation is performed.
7589 Operand 1 is the second operand to the binary operator.
7590
7591 This pattern must issue any memory barrier instructions such that all
7592 memory operations before the atomic operation occur before the atomic
7593 operation and all memory operations after the atomic operation occur
7594 after the atomic operation.
7595
7596 If these patterns are not defined, the operation will be constructed
7597 from a compare-and-swap operation, if defined.
7598
7599 @cindex @code{sync_old_add@var{mode}} instruction pattern
7600 @cindex @code{sync_old_sub@var{mode}} instruction pattern
7601 @cindex @code{sync_old_ior@var{mode}} instruction pattern
7602 @cindex @code{sync_old_and@var{mode}} instruction pattern
7603 @cindex @code{sync_old_xor@var{mode}} instruction pattern
7604 @cindex @code{sync_old_nand@var{mode}} instruction pattern
7605 @item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
7606 @itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
7607 @itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
7608 These patterns emit code for an atomic operation on memory,
7609 and return the value that the memory contained before the operation.
7610 Operand 0 is the result value, operand 1 is the memory on which the
7611 atomic operation is performed, and operand 2 is the second operand
7612 to the binary operator.
7613
7614 This pattern must issue any memory barrier instructions such that all
7615 memory operations before the atomic operation occur before the atomic
7616 operation and all memory operations after the atomic operation occur
7617 after the atomic operation.
7618
7619 If these patterns are not defined, the operation will be constructed
7620 from a compare-and-swap operation, if defined.
7621
7622 @cindex @code{sync_new_add@var{mode}} instruction pattern
7623 @cindex @code{sync_new_sub@var{mode}} instruction pattern
7624 @cindex @code{sync_new_ior@var{mode}} instruction pattern
7625 @cindex @code{sync_new_and@var{mode}} instruction pattern
7626 @cindex @code{sync_new_xor@var{mode}} instruction pattern
7627 @cindex @code{sync_new_nand@var{mode}} instruction pattern
7628 @item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
7629 @itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
7630 @itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
7631 These patterns are like their @code{sync_old_@var{op}} counterparts,
7632 except that they return the value that exists in the memory location
7633 after the operation, rather than before the operation.
7634
7635 @cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
7636 @item @samp{sync_lock_test_and_set@var{mode}}
7637 This pattern takes two forms, based on the capabilities of the target.
7638 In either case, operand 0 is the result of the operand, operand 1 is
7639 the memory on which the atomic operation is performed, and operand 2
7640 is the value to set in the lock.
7641
7642 In the ideal case, this operation is an atomic exchange operation, in
7643 which the previous value in memory operand is copied into the result
7644 operand, and the value operand is stored in the memory operand.
7645
7646 For less capable targets, any value operand that is not the constant 1
7647 should be rejected with @code{FAIL}. In this case the target may use
7648 an atomic test-and-set bit operation. The result operand should contain
7649 1 if the bit was previously set and 0 if the bit was previously clear.
7650 The true contents of the memory operand are implementation defined.
7651
7652 This pattern must issue any memory barrier instructions such that the
7653 pattern as a whole acts as an acquire barrier, that is all memory
7654 operations after the pattern do not occur until the lock is acquired.
7655
7656 If this pattern is not defined, the operation will be constructed from
7657 a compare-and-swap operation, if defined.
7658
7659 @cindex @code{sync_lock_release@var{mode}} instruction pattern
7660 @item @samp{sync_lock_release@var{mode}}
7661 This pattern, if defined, releases a lock set by
7662 @code{sync_lock_test_and_set@var{mode}}. Operand 0 is the memory
7663 that contains the lock; operand 1 is the value to store in the lock.
7664
7665 If the target doesn't implement full semantics for
7666 @code{sync_lock_test_and_set@var{mode}}, any value operand which is not
7667 the constant 0 should be rejected with @code{FAIL}, and the true contents
7668 of the memory operand are implementation defined.
7669
7670 This pattern must issue any memory barrier instructions such that the
7671 pattern as a whole acts as a release barrier, that is the lock is
7672 released only after all previous memory operations have completed.
7673
7674 If this pattern is not defined, then a @code{memory_barrier} pattern
7675 will be emitted, followed by a store of the value to the memory operand.
7676
7677 @cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
7678 @item @samp{atomic_compare_and_swap@var{mode}}
7679 This pattern, if defined, emits code for an atomic compare-and-swap
7680 operation with memory model semantics. Operand 2 is the memory on which
7681 the atomic operation is performed. Operand 0 is an output operand which
7682 is set to true or false based on whether the operation succeeded. Operand
7683 1 is an output operand which is set to the contents of the memory before
7684 the operation was attempted. Operand 3 is the value that is expected to
7685 be in memory. Operand 4 is the value to put in memory if the expected
7686 value is found there. Operand 5 is set to 1 if this compare and swap is to
7687 be treated as a weak operation. Operand 6 is the memory model to be used
7688 if the operation is a success. Operand 7 is the memory model to be used
7689 if the operation fails.
7690
7691 If memory referred to in operand 2 contains the value in operand 3, then
7692 operand 4 is stored in memory pointed to by operand 2 and fencing based on
7693 the memory model in operand 6 is issued.
7694
7695 If memory referred to in operand 2 does not contain the value in operand 3,
7696 then fencing based on the memory model in operand 7 is issued.
7697
7698 If a target does not support weak compare-and-swap operations, or the port
7699 elects not to implement weak operations, the argument in operand 5 can be
7700 ignored. Note a strong implementation must be provided.
7701
7702 If this pattern is not provided, the @code{__atomic_compare_exchange}
7703 built-in functions will utilize the legacy @code{sync_compare_and_swap}
7704 pattern with an @code{__ATOMIC_SEQ_CST} memory model.
7705
7706 @cindex @code{atomic_load@var{mode}} instruction pattern
7707 @item @samp{atomic_load@var{mode}}
7708 This pattern implements an atomic load operation with memory model
7709 semantics. Operand 1 is the memory address being loaded from. Operand 0
7710 is the result of the load. Operand 2 is the memory model to be used for
7711 the load operation.
7712
7713 If not present, the @code{__atomic_load} built-in function will either
7714 resort to a normal load with memory barriers, or a compare-and-swap
7715 operation if a normal load would not be atomic.
7716
7717 @cindex @code{atomic_store@var{mode}} instruction pattern
7718 @item @samp{atomic_store@var{mode}}
7719 This pattern implements an atomic store operation with memory model
7720 semantics. Operand 0 is the memory address being stored to. Operand 1
7721 is the value to be written. Operand 2 is the memory model to be used for
7722 the operation.
7723
7724 If not present, the @code{__atomic_store} built-in function will attempt to
7725 perform a normal store and surround it with any required memory fences. If
7726 the store would not be atomic, then an @code{__atomic_exchange} is
7727 attempted with the result being ignored.
7728
7729 @cindex @code{atomic_exchange@var{mode}} instruction pattern
7730 @item @samp{atomic_exchange@var{mode}}
7731 This pattern implements an atomic exchange operation with memory model
7732 semantics. Operand 1 is the memory location the operation is performed on.
7733 Operand 0 is an output operand which is set to the original value contained
7734 in the memory pointed to by operand 1. Operand 2 is the value to be
7735 stored. Operand 3 is the memory model to be used.
7736
7737 If this pattern is not present, the built-in function
7738 @code{__atomic_exchange} will attempt to preform the operation with a
7739 compare and swap loop.
7740
7741 @cindex @code{atomic_add@var{mode}} instruction pattern
7742 @cindex @code{atomic_sub@var{mode}} instruction pattern
7743 @cindex @code{atomic_or@var{mode}} instruction pattern
7744 @cindex @code{atomic_and@var{mode}} instruction pattern
7745 @cindex @code{atomic_xor@var{mode}} instruction pattern
7746 @cindex @code{atomic_nand@var{mode}} instruction pattern
7747 @item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
7748 @itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
7749 @itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
7750 These patterns emit code for an atomic operation on memory with memory
7751 model semantics. Operand 0 is the memory on which the atomic operation is
7752 performed. Operand 1 is the second operand to the binary operator.
7753 Operand 2 is the memory model to be used by the operation.
7754
7755 If these patterns are not defined, attempts will be made to use legacy
7756 @code{sync} patterns, or equivalent patterns which return a result. If
7757 none of these are available a compare-and-swap loop will be used.
7758
7759 @cindex @code{atomic_fetch_add@var{mode}} instruction pattern
7760 @cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
7761 @cindex @code{atomic_fetch_or@var{mode}} instruction pattern
7762 @cindex @code{atomic_fetch_and@var{mode}} instruction pattern
7763 @cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
7764 @cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
7765 @item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
7766 @itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
7767 @itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
7768 These patterns emit code for an atomic operation on memory with memory
7769 model semantics, and return the original value. Operand 0 is an output
7770 operand which contains the value of the memory location before the
7771 operation was performed. Operand 1 is the memory on which the atomic
7772 operation is performed. Operand 2 is the second operand to the binary
7773 operator. Operand 3 is the memory model to be used by the operation.
7774
7775 If these patterns are not defined, attempts will be made to use legacy
7776 @code{sync} patterns. If none of these are available a compare-and-swap
7777 loop will be used.
7778
7779 @cindex @code{atomic_add_fetch@var{mode}} instruction pattern
7780 @cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
7781 @cindex @code{atomic_or_fetch@var{mode}} instruction pattern
7782 @cindex @code{atomic_and_fetch@var{mode}} instruction pattern
7783 @cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
7784 @cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
7785 @item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
7786 @itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
7787 @itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
7788 These patterns emit code for an atomic operation on memory with memory
7789 model semantics and return the result after the operation is performed.
7790 Operand 0 is an output operand which contains the value after the
7791 operation. Operand 1 is the memory on which the atomic operation is
7792 performed. Operand 2 is the second operand to the binary operator.
7793 Operand 3 is the memory model to be used by the operation.
7794
7795 If these patterns are not defined, attempts will be made to use legacy
7796 @code{sync} patterns, or equivalent patterns which return the result before
7797 the operation followed by the arithmetic operation required to produce the
7798 result. If none of these are available a compare-and-swap loop will be
7799 used.
7800
7801 @cindex @code{atomic_test_and_set} instruction pattern
7802 @item @samp{atomic_test_and_set}
7803 This pattern emits code for @code{__builtin_atomic_test_and_set}.
7804 Operand 0 is an output operand which is set to true if the previous
7805 previous contents of the byte was "set", and false otherwise. Operand 1
7806 is the @code{QImode} memory to be modified. Operand 2 is the memory
7807 model to be used.
7808
7809 The specific value that defines "set" is implementation defined, and
7810 is normally based on what is performed by the native atomic test and set
7811 instruction.
7812
7813 @cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern
7814 @cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern
7815 @cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern
7816 @item @samp{atomic_bit_test_and_set@var{mode}}
7817 @itemx @samp{atomic_bit_test_and_complement@var{mode}}
7818 @itemx @samp{atomic_bit_test_and_reset@var{mode}}
7819 These patterns emit code for an atomic bitwise operation on memory with memory
7820 model semantics, and return the original value of the specified bit.
7821 Operand 0 is an output operand which contains the value of the specified bit
7822 from the memory location before the operation was performed. Operand 1 is the
7823 memory on which the atomic operation is performed. Operand 2 is the bit within
7824 the operand, starting with least significant bit. Operand 3 is the memory model
7825 to be used by the operation. Operand 4 is a flag - it is @code{const1_rtx}
7826 if operand 0 should contain the original value of the specified bit in the
7827 least significant bit of the operand, and @code{const0_rtx} if the bit should
7828 be in its original position in the operand.
7829 @code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after
7830 remembering its original value, @code{atomic_bit_test_and_complement@var{mode}}
7831 inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears
7832 the specified bit.
7833
7834 If these patterns are not defined, attempts will be made to use
7835 @code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or
7836 @code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync}
7837 counterparts. If none of these are available a compare-and-swap
7838 loop will be used.
7839
7840 @cindex @code{atomic_add_fetch_cmp_0@var{mode}} instruction pattern
7841 @cindex @code{atomic_sub_fetch_cmp_0@var{mode}} instruction pattern
7842 @cindex @code{atomic_and_fetch_cmp_0@var{mode}} instruction pattern
7843 @cindex @code{atomic_or_fetch_cmp_0@var{mode}} instruction pattern
7844 @cindex @code{atomic_xor_fetch_cmp_0@var{mode}} instruction pattern
7845 @item @samp{atomic_add_fetch_cmp_0@var{mode}}
7846 @itemx @samp{atomic_sub_fetch_cmp_0@var{mode}}
7847 @itemx @samp{atomic_and_fetch_cmp_0@var{mode}}
7848 @itemx @samp{atomic_or_fetch_cmp_0@var{mode}}
7849 @itemx @samp{atomic_xor_fetch_cmp_0@var{mode}}
7850 These patterns emit code for an atomic operation on memory with memory
7851 model semantics if the fetch result is used only in a comparison against
7852 zero.
7853 Operand 0 is an output operand which contains a boolean result of comparison
7854 of the value after the operation against zero. Operand 1 is the memory on
7855 which the atomic operation is performed. Operand 2 is the second operand
7856 to the binary operator. Operand 3 is the memory model to be used by the
7857 operation. Operand 4 is an integer holding the comparison code, one of
7858 @code{EQ}, @code{NE}, @code{LT}, @code{GT}, @code{LE} or @code{GE}.
7859
7860 If these patterns are not defined, attempts will be made to use separate
7861 atomic operation and fetch pattern followed by comparison of the result
7862 against zero.
7863
7864 @cindex @code{mem_thread_fence} instruction pattern
7865 @item @samp{mem_thread_fence}
7866 This pattern emits code required to implement a thread fence with
7867 memory model semantics. Operand 0 is the memory model to be used.
7868
7869 For the @code{__ATOMIC_RELAXED} model no instructions need to be issued
7870 and this expansion is not invoked.
7871
7872 The compiler always emits a compiler memory barrier regardless of what
7873 expanding this pattern produced.
7874
7875 If this pattern is not defined, the compiler falls back to expanding the
7876 @code{memory_barrier} pattern, then to emitting @code{__sync_synchronize}
7877 library call, and finally to just placing a compiler memory barrier.
7878
7879 @cindex @code{get_thread_pointer@var{mode}} instruction pattern
7880 @cindex @code{set_thread_pointer@var{mode}} instruction pattern
7881 @item @samp{get_thread_pointer@var{mode}}
7882 @itemx @samp{set_thread_pointer@var{mode}}
7883 These patterns emit code that reads/sets the TLS thread pointer. Currently,
7884 these are only needed if the target needs to support the
7885 @code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer}
7886 builtins.
7887
7888 The get/set patterns have a single output/input operand respectively,
7889 with @var{mode} intended to be @code{Pmode}.
7890
7891 @cindex @code{stack_protect_combined_set} instruction pattern
7892 @item @samp{stack_protect_combined_set}
7893 This pattern, if defined, moves a @code{ptr_mode} value from an address
7894 whose declaration RTX is given in operand 1 to the memory in operand 0
7895 without leaving the value in a register afterward. If several
7896 instructions are needed by the target to perform the operation (eg. to
7897 load the address from a GOT entry then load the @code{ptr_mode} value
7898 and finally store it), it is the backend's responsibility to ensure no
7899 intermediate result gets spilled. This is to avoid leaking the value
7900 some place that an attacker might use to rewrite the stack guard slot
7901 after having clobbered it.
7902
7903 If this pattern is not defined, then the address declaration is
7904 expanded first in the standard way and a @code{stack_protect_set}
7905 pattern is then generated to move the value from that address to the
7906 address in operand 0.
7907
7908 @cindex @code{stack_protect_set} instruction pattern
7909 @item @samp{stack_protect_set}
7910 This pattern, if defined, moves a @code{ptr_mode} value from the valid
7911 memory location in operand 1 to the memory in operand 0 without leaving
7912 the value in a register afterward. This is to avoid leaking the value
7913 some place that an attacker might use to rewrite the stack guard slot
7914 after having clobbered it.
7915
7916 Note: on targets where the addressing modes do not allow to load
7917 directly from stack guard address, the address is expanded in a standard
7918 way first which could cause some spills.
7919
7920 If this pattern is not defined, then a plain move pattern is generated.
7921
7922 @cindex @code{stack_protect_combined_test} instruction pattern
7923 @item @samp{stack_protect_combined_test}
7924 This pattern, if defined, compares a @code{ptr_mode} value from an
7925 address whose declaration RTX is given in operand 1 with the memory in
7926 operand 0 without leaving the value in a register afterward and
7927 branches to operand 2 if the values were equal. If several
7928 instructions are needed by the target to perform the operation (eg. to
7929 load the address from a GOT entry then load the @code{ptr_mode} value
7930 and finally store it), it is the backend's responsibility to ensure no
7931 intermediate result gets spilled. This is to avoid leaking the value
7932 some place that an attacker might use to rewrite the stack guard slot
7933 after having clobbered it.
7934
7935 If this pattern is not defined, then the address declaration is
7936 expanded first in the standard way and a @code{stack_protect_test}
7937 pattern is then generated to compare the value from that address to the
7938 value at the memory in operand 0.
7939
7940 @cindex @code{stack_protect_test} instruction pattern
7941 @item @samp{stack_protect_test}
7942 This pattern, if defined, compares a @code{ptr_mode} value from the
7943 valid memory location in operand 1 with the memory in operand 0 without
7944 leaving the value in a register afterward and branches to operand 2 if
7945 the values were equal.
7946
7947 If this pattern is not defined, then a plain compare pattern and
7948 conditional branch pattern is used.
7949
7950 @cindex @code{clear_cache} instruction pattern
7951 @item @samp{clear_cache}
7952 This pattern, if defined, flushes the instruction cache for a region of
7953 memory. The region is bounded to by the Pmode pointers in operand 0
7954 inclusive and operand 1 exclusive.
7955
7956 If this pattern is not defined, a call to the library function
7957 @code{__clear_cache} is used.
7958
7959 @cindex @code{spaceship@var{m}3} instruction pattern
7960 @item @samp{spaceship@var{m}3}
7961 Initialize output operand 0 with mode of integer type to -1, 0, 1 or 2
7962 if operand 1 with mode @var{m} compares less than operand 2, equal to
7963 operand 2, greater than operand 2 or is unordered with operand 2.
7964 @var{m} should be a scalar floating point mode.
7965
7966 This pattern is not allowed to @code{FAIL}.
7967
7968 @end table
7969
7970 @end ifset
7971 @c Each of the following nodes are wrapped in separate
7972 @c "@ifset INTERNALS" to work around memory limits for the default
7973 @c configuration in older tetex distributions. Known to not work:
7974 @c tetex-1.0.7, known to work: tetex-2.0.2.
7975 @ifset INTERNALS
7976 @node Pattern Ordering
7977 @section When the Order of Patterns Matters
7978 @cindex Pattern Ordering
7979 @cindex Ordering of Patterns
7980
7981 Sometimes an insn can match more than one instruction pattern. Then the
7982 pattern that appears first in the machine description is the one used.
7983 Therefore, more specific patterns (patterns that will match fewer things)
7984 and faster instructions (those that will produce better code when they
7985 do match) should usually go first in the description.
7986
7987 In some cases the effect of ordering the patterns can be used to hide
7988 a pattern when it is not valid. For example, the 68000 has an
7989 instruction for converting a fullword to floating point and another
7990 for converting a byte to floating point. An instruction converting
7991 an integer to floating point could match either one. We put the
7992 pattern to convert the fullword first to make sure that one will
7993 be used rather than the other. (Otherwise a large integer might
7994 be generated as a single-byte immediate quantity, which would not work.)
7995 Instead of using this pattern ordering it would be possible to make the
7996 pattern for convert-a-byte smart enough to deal properly with any
7997 constant value.
7998
7999 @end ifset
8000 @ifset INTERNALS
8001 @node Dependent Patterns
8002 @section Interdependence of Patterns
8003 @cindex Dependent Patterns
8004 @cindex Interdependence of Patterns
8005
8006 In some cases machines support instructions identical except for the
8007 machine mode of one or more operands. For example, there may be
8008 ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
8009 patterns are
8010
8011 @smallexample
8012 (set (match_operand:SI 0 @dots{})
8013 (extend:SI (match_operand:HI 1 @dots{})))
8014
8015 (set (match_operand:SI 0 @dots{})
8016 (extend:SI (match_operand:QI 1 @dots{})))
8017 @end smallexample
8018
8019 @noindent
8020 Constant integers do not specify a machine mode, so an instruction to
8021 extend a constant value could match either pattern. The pattern it
8022 actually will match is the one that appears first in the file. For correct
8023 results, this must be the one for the widest possible mode (@code{HImode},
8024 here). If the pattern matches the @code{QImode} instruction, the results
8025 will be incorrect if the constant value does not actually fit that mode.
8026
8027 Such instructions to extend constants are rarely generated because they are
8028 optimized away, but they do occasionally happen in nonoptimized
8029 compilations.
8030
8031 If a constraint in a pattern allows a constant, the reload pass may
8032 replace a register with a constant permitted by the constraint in some
8033 cases. Similarly for memory references. Because of this substitution,
8034 you should not provide separate patterns for increment and decrement
8035 instructions. Instead, they should be generated from the same pattern
8036 that supports register-register add insns by examining the operands and
8037 generating the appropriate machine instruction.
8038
8039 @end ifset
8040 @ifset INTERNALS
8041 @node Jump Patterns
8042 @section Defining Jump Instruction Patterns
8043 @cindex jump instruction patterns
8044 @cindex defining jump instruction patterns
8045
8046 GCC does not assume anything about how the machine realizes jumps.
8047 The machine description should define a single pattern, usually
8048 a @code{define_expand}, which expands to all the required insns.
8049
8050 Usually, this would be a comparison insn to set the condition code
8051 and a separate branch insn testing the condition code and branching
8052 or not according to its value. For many machines, however,
8053 separating compares and branches is limiting, which is why the
8054 more flexible approach with one @code{define_expand} is used in GCC.
8055 The machine description becomes clearer for architectures that
8056 have compare-and-branch instructions but no condition code. It also
8057 works better when different sets of comparison operators are supported
8058 by different kinds of conditional branches (e.g.@: integer vs.@:
8059 floating-point), or by conditional branches with respect to conditional stores.
8060
8061 Two separate insns are always used on most machines that use a separate
8062 condition code register (@pxref{Condition Code}).
8063
8064 Even in this case having a single entry point for conditional branches
8065 is advantageous, because it handles equally well the case where a single
8066 comparison instruction records the results of both signed and unsigned
8067 comparison of the given operands (with the branch insns coming in distinct
8068 signed and unsigned flavors) as in the x86 or SPARC, and the case where
8069 there are distinct signed and unsigned compare instructions and only
8070 one set of conditional branch instructions as in the PowerPC.
8071
8072 @end ifset
8073 @ifset INTERNALS
8074 @node Looping Patterns
8075 @section Defining Looping Instruction Patterns
8076 @cindex looping instruction patterns
8077 @cindex defining looping instruction patterns
8078
8079 Some machines have special jump instructions that can be utilized to
8080 make loops more efficient. A common example is the 68000 @samp{dbra}
8081 instruction which performs a decrement of a register and a branch if the
8082 result was greater than zero. Other machines, in particular digital
8083 signal processors (DSPs), have special block repeat instructions to
8084 provide low-overhead loop support. For example, the TI TMS320C3x/C4x
8085 DSPs have a block repeat instruction that loads special registers to
8086 mark the top and end of a loop and to count the number of loop
8087 iterations. This avoids the need for fetching and executing a
8088 @samp{dbra}-like instruction and avoids pipeline stalls associated with
8089 the jump.
8090
8091 GCC has two special named patterns to support low overhead looping.
8092 They are @samp{doloop_begin} and @samp{doloop_end}. These are emitted
8093 by the loop optimizer for certain well-behaved loops with a finite
8094 number of loop iterations using information collected during strength
8095 reduction.
8096
8097 The @samp{doloop_end} pattern describes the actual looping instruction
8098 (or the implicit looping operation) and the @samp{doloop_begin} pattern
8099 is an optional companion pattern that can be used for initialization
8100 needed for some low-overhead looping instructions.
8101
8102 Note that some machines require the actual looping instruction to be
8103 emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs). Emitting
8104 the true RTL for a looping instruction at the top of the loop can cause
8105 problems with flow analysis. So instead, a dummy @code{doloop} insn is
8106 emitted at the end of the loop. The machine dependent reorg pass checks
8107 for the presence of this @code{doloop} insn and then searches back to
8108 the top of the loop, where it inserts the true looping insn (provided
8109 there are no instructions in the loop which would cause problems). Any
8110 additional labels can be emitted at this point. In addition, if the
8111 desired special iteration counter register was not allocated, this
8112 machine dependent reorg pass could emit a traditional compare and jump
8113 instruction pair.
8114
8115 For the @samp{doloop_end} pattern, the loop optimizer allocates an
8116 additional pseudo register as an iteration counter. This pseudo
8117 register cannot be used within the loop (i.e., general induction
8118 variables cannot be derived from it), however, in many cases the loop
8119 induction variable may become redundant and removed by the flow pass.
8120
8121 The @samp{doloop_end} pattern must have a specific structure to be
8122 handled correctly by GCC. The example below is taken (slightly
8123 simplified) from the PDP-11 target:
8124
8125 @smallexample
8126 @group
8127 (define_expand "doloop_end"
8128 [(parallel [(set (pc)
8129 (if_then_else
8130 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8131 (const_int 1))
8132 (label_ref (match_operand 1 "" ""))
8133 (pc)))
8134 (set (match_dup 0)
8135 (plus:HI (match_dup 0)
8136 (const_int -1)))])]
8137 ""
8138 "@{
8139 if (GET_MODE (operands[0]) != HImode)
8140 FAIL;
8141 @}")
8142
8143 (define_insn "doloop_end_insn"
8144 [(set (pc)
8145 (if_then_else
8146 (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
8147 (const_int 1))
8148 (label_ref (match_operand 1 "" ""))
8149 (pc)))
8150 (set (match_dup 0)
8151 (plus:HI (match_dup 0)
8152 (const_int -1)))]
8153 ""
8154
8155 @{
8156 if (which_alternative == 0)
8157 return "sob %0,%l1";
8158
8159 /* emulate sob */
8160 output_asm_insn ("dec %0", operands);
8161 return "bne %l1";
8162 @})
8163 @end group
8164 @end smallexample
8165
8166 The first part of the pattern describes the branch condition. GCC
8167 supports three cases for the way the target machine handles the loop
8168 counter:
8169 @itemize @bullet
8170 @item Loop terminates when the loop register decrements to zero. This
8171 is represented by a @code{ne} comparison of the register (its old value)
8172 with constant 1 (as in the example above).
8173 @item Loop terminates when the loop register decrements to @minus{}1.
8174 This is represented by a @code{ne} comparison of the register with
8175 constant zero.
8176 @item Loop terminates when the loop register decrements to a negative
8177 value. This is represented by a @code{ge} comparison of the register
8178 with constant zero. For this case, GCC will attach a @code{REG_NONNEG}
8179 note to the @code{doloop_end} insn if it can determine that the register
8180 will be non-negative.
8181 @end itemize
8182
8183 Since the @code{doloop_end} insn is a jump insn that also has an output,
8184 the reload pass does not handle the output operand. Therefore, the
8185 constraint must allow for that operand to be in memory rather than a
8186 register. In the example shown above, that is handled (in the
8187 @code{doloop_end_insn} pattern) by using a loop instruction sequence
8188 that can handle memory operands when the memory alternative appears.
8189
8190 GCC does not check the mode of the loop register operand when generating
8191 the @code{doloop_end} pattern. If the pattern is only valid for some
8192 modes but not others, the pattern should be a @code{define_expand}
8193 pattern that checks the operand mode in the preparation code, and issues
8194 @code{FAIL} if an unsupported mode is found. The example above does
8195 this, since the machine instruction to be used only exists for
8196 @code{HImode}.
8197
8198 If the @code{doloop_end} pattern is a @code{define_expand}, there must
8199 also be a @code{define_insn} or @code{define_insn_and_split} matching
8200 the generated pattern. Otherwise, the compiler will fail during loop
8201 optimization.
8202
8203 @end ifset
8204 @ifset INTERNALS
8205 @node Insn Canonicalizations
8206 @section Canonicalization of Instructions
8207 @cindex canonicalization of instructions
8208 @cindex insn canonicalization
8209
8210 There are often cases where multiple RTL expressions could represent an
8211 operation performed by a single machine instruction. This situation is
8212 most commonly encountered with logical, branch, and multiply-accumulate
8213 instructions. In such cases, the compiler attempts to convert these
8214 multiple RTL expressions into a single canonical form to reduce the
8215 number of insn patterns required.
8216
8217 In addition to algebraic simplifications, following canonicalizations
8218 are performed:
8219
8220 @itemize @bullet
8221 @item
8222 For commutative and comparison operators, a constant is always made the
8223 second operand. If a machine only supports a constant as the second
8224 operand, only patterns that match a constant in the second operand need
8225 be supplied.
8226
8227 @item
8228 For associative operators, a sequence of operators will always chain
8229 to the left; for instance, only the left operand of an integer @code{plus}
8230 can itself be a @code{plus}. @code{and}, @code{ior}, @code{xor},
8231 @code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
8232 @code{umax} are associative when applied to integers, and sometimes to
8233 floating-point.
8234
8235 @cindex @code{neg}, canonicalization of
8236 @cindex @code{not}, canonicalization of
8237 @cindex @code{mult}, canonicalization of
8238 @cindex @code{plus}, canonicalization of
8239 @cindex @code{minus}, canonicalization of
8240 @item
8241 For these operators, if only one operand is a @code{neg}, @code{not},
8242 @code{mult}, @code{plus}, or @code{minus} expression, it will be the
8243 first operand.
8244
8245 @item
8246 In combinations of @code{neg}, @code{mult}, @code{plus}, and
8247 @code{minus}, the @code{neg} operations (if any) will be moved inside
8248 the operations as far as possible. For instance,
8249 @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
8250 @code{(plus (mult (neg B) C) A)} is canonicalized as
8251 @code{(minus A (mult B C))}.
8252
8253 @cindex @code{compare}, canonicalization of
8254 @item
8255 For the @code{compare} operator, a constant is always the second operand
8256 if the first argument is a condition code register.
8257
8258 @item
8259 For instructions that inherently set a condition code register, the
8260 @code{compare} operator is always written as the first RTL expression of
8261 the @code{parallel} instruction pattern. For example,
8262
8263 @smallexample
8264 (define_insn ""
8265 [(set (reg:CCZ FLAGS_REG)
8266 (compare:CCZ
8267 (plus:SI
8268 (match_operand:SI 1 "register_operand" "%r")
8269 (match_operand:SI 2 "register_operand" "r"))
8270 (const_int 0)))
8271 (set (match_operand:SI 0 "register_operand" "=r")
8272 (plus:SI (match_dup 1) (match_dup 2)))]
8273 ""
8274 "addl %0, %1, %2")
8275 @end smallexample
8276
8277 @item
8278 An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
8279 @code{minus} is made the first operand under the same conditions as
8280 above.
8281
8282 @item
8283 @code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
8284 @code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
8285 of @code{ltu}.
8286
8287 @item
8288 @code{(minus @var{x} (const_int @var{n}))} is converted to
8289 @code{(plus @var{x} (const_int @var{-n}))}.
8290
8291 @item
8292 Within address computations (i.e., inside @code{mem}), a left shift is
8293 converted into the appropriate multiplication by a power of two.
8294
8295 @cindex @code{ior}, canonicalization of
8296 @cindex @code{and}, canonicalization of
8297 @cindex De Morgan's law
8298 @item
8299 De Morgan's Law is used to move bitwise negation inside a bitwise
8300 logical-and or logical-or operation. If this results in only one
8301 operand being a @code{not} expression, it will be the first one.
8302
8303 A machine that has an instruction that performs a bitwise logical-and of one
8304 operand with the bitwise negation of the other should specify the pattern
8305 for that instruction as
8306
8307 @smallexample
8308 (define_insn ""
8309 [(set (match_operand:@var{m} 0 @dots{})
8310 (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8311 (match_operand:@var{m} 2 @dots{})))]
8312 "@dots{}"
8313 "@dots{}")
8314 @end smallexample
8315
8316 @noindent
8317 Similarly, a pattern for a ``NAND'' instruction should be written
8318
8319 @smallexample
8320 (define_insn ""
8321 [(set (match_operand:@var{m} 0 @dots{})
8322 (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
8323 (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
8324 "@dots{}"
8325 "@dots{}")
8326 @end smallexample
8327
8328 In both cases, it is not necessary to include patterns for the many
8329 logically equivalent RTL expressions.
8330
8331 @cindex @code{xor}, canonicalization of
8332 @item
8333 The only possible RTL expressions involving both bitwise exclusive-or
8334 and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
8335 and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.
8336
8337 @item
8338 The sum of three items, one of which is a constant, will only appear in
8339 the form
8340
8341 @smallexample
8342 (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
8343 @end smallexample
8344
8345 @cindex @code{zero_extract}, canonicalization of
8346 @cindex @code{sign_extract}, canonicalization of
8347 @item
8348 Equality comparisons of a group of bits (usually a single bit) with zero
8349 will be written using @code{zero_extract} rather than the equivalent
8350 @code{and} or @code{sign_extract} operations.
8351
8352 @cindex @code{mult}, canonicalization of
8353 @item
8354 @code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
8355 (sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
8356 (sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
8357 for @code{zero_extend}.
8358
8359 @item
8360 @code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
8361 @var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
8362 to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
8363 @var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
8364 patterns using @code{zero_extend} and @code{lshiftrt}. If the second
8365 operand of @code{mult} is also a shift, then that is extended also.
8366 This transformation is only applied when it can be proven that the
8367 original operation had sufficient precision to prevent overflow.
8368
8369 @end itemize
8370
8371 Further canonicalization rules are defined in the function
8372 @code{commutative_operand_precedence} in @file{gcc/rtlanal.cc}.
8373
8374 @end ifset
8375 @ifset INTERNALS
8376 @node Expander Definitions
8377 @section Defining RTL Sequences for Code Generation
8378 @cindex expander definitions
8379 @cindex code generation RTL sequences
8380 @cindex defining RTL sequences for code generation
8381
8382 On some target machines, some standard pattern names for RTL generation
8383 cannot be handled with single insn, but a sequence of RTL insns can
8384 represent them. For these target machines, you can write a
8385 @code{define_expand} to specify how to generate the sequence of RTL@.
8386
8387 @findex define_expand
8388 A @code{define_expand} is an RTL expression that looks almost like a
8389 @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
8390 only for RTL generation and it can produce more than one RTL insn.
8391
8392 A @code{define_expand} RTX has four operands:
8393
8394 @itemize @bullet
8395 @item
8396 The name. Each @code{define_expand} must have a name, since the only
8397 use for it is to refer to it by name.
8398
8399 @item
8400 The RTL template. This is a vector of RTL expressions representing
8401 a sequence of separate instructions. Unlike @code{define_insn}, there
8402 is no implicit surrounding @code{PARALLEL}.
8403
8404 @item
8405 The condition, a string containing a C expression. This expression is
8406 used to express how the availability of this pattern depends on
8407 subclasses of target machine, selected by command-line options when GCC
8408 is run. This is just like the condition of a @code{define_insn} that
8409 has a standard name. Therefore, the condition (if present) may not
8410 depend on the data in the insn being matched, but only the
8411 target-machine-type flags. The compiler needs to test these conditions
8412 during initialization in order to learn exactly which named instructions
8413 are available in a particular run.
8414
8415 @item
8416 The preparation statements, a string containing zero or more C
8417 statements which are to be executed before RTL code is generated from
8418 the RTL template.
8419
8420 Usually these statements prepare temporary registers for use as
8421 internal operands in the RTL template, but they can also generate RTL
8422 insns directly by calling routines such as @code{emit_insn}, etc.
8423 Any such insns precede the ones that come from the RTL template.
8424
8425 @item
8426 Optionally, a vector containing the values of attributes. @xref{Insn
8427 Attributes}.
8428 @end itemize
8429
8430 Every RTL insn emitted by a @code{define_expand} must match some
8431 @code{define_insn} in the machine description. Otherwise, the compiler
8432 will crash when trying to generate code for the insn or trying to optimize
8433 it.
8434
8435 The RTL template, in addition to controlling generation of RTL insns,
8436 also describes the operands that need to be specified when this pattern
8437 is used. In particular, it gives a predicate for each operand.
8438
8439 A true operand, which needs to be specified in order to generate RTL from
8440 the pattern, should be described with a @code{match_operand} in its first
8441 occurrence in the RTL template. This enters information on the operand's
8442 predicate into the tables that record such things. GCC uses the
8443 information to preload the operand into a register if that is required for
8444 valid RTL code. If the operand is referred to more than once, subsequent
8445 references should use @code{match_dup}.
8446
8447 The RTL template may also refer to internal ``operands'' which are
8448 temporary registers or labels used only within the sequence made by the
8449 @code{define_expand}. Internal operands are substituted into the RTL
8450 template with @code{match_dup}, never with @code{match_operand}. The
8451 values of the internal operands are not passed in as arguments by the
8452 compiler when it requests use of this pattern. Instead, they are computed
8453 within the pattern, in the preparation statements. These statements
8454 compute the values and store them into the appropriate elements of
8455 @code{operands} so that @code{match_dup} can find them.
8456
8457 There are two special macros defined for use in the preparation statements:
8458 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
8459 as a statement.
8460
8461 @table @code
8462
8463 @findex DONE
8464 @item DONE
8465 Use the @code{DONE} macro to end RTL generation for the pattern. The
8466 only RTL insns resulting from the pattern on this occasion will be
8467 those already emitted by explicit calls to @code{emit_insn} within the
8468 preparation statements; the RTL template will not be generated.
8469
8470 @findex FAIL
8471 @item FAIL
8472 Make the pattern fail on this occasion. When a pattern fails, it means
8473 that the pattern was not truly available. The calling routines in the
8474 compiler will try other strategies for code generation using other patterns.
8475
8476 Failure is currently supported only for binary (addition, multiplication,
8477 shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
8478 operations.
8479 @end table
8480
8481 If the preparation falls through (invokes neither @code{DONE} nor
8482 @code{FAIL}), then the @code{define_expand} acts like a
8483 @code{define_insn} in that the RTL template is used to generate the
8484 insn.
8485
8486 The RTL template is not used for matching, only for generating the
8487 initial insn list. If the preparation statement always invokes
8488 @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
8489 list of operands, such as this example:
8490
8491 @smallexample
8492 @group
8493 (define_expand "addsi3"
8494 [(match_operand:SI 0 "register_operand" "")
8495 (match_operand:SI 1 "register_operand" "")
8496 (match_operand:SI 2 "register_operand" "")]
8497 ""
8498 "
8499 @{
8500 handle_add (operands[0], operands[1], operands[2]);
8501 DONE;
8502 @}")
8503 @end group
8504 @end smallexample
8505
8506 Here is an example, the definition of left-shift for the SPUR chip:
8507
8508 @smallexample
8509 @group
8510 (define_expand "ashlsi3"
8511 [(set (match_operand:SI 0 "register_operand" "")
8512 (ashift:SI
8513 (match_operand:SI 1 "register_operand" "")
8514 (match_operand:SI 2 "nonmemory_operand" "")))]
8515 ""
8516 "
8517 @{
8518 if (GET_CODE (operands[2]) != CONST_INT
8519 || (unsigned) INTVAL (operands[2]) > 3)
8520 FAIL;
8521 @}")
8522 @end group
8523 @end smallexample
8524
8525 @noindent
8526 This example uses @code{define_expand} so that it can generate an RTL insn
8527 for shifting when the shift-count is in the supported range of 0 to 3 but
8528 fail in other cases where machine insns aren't available. When it fails,
8529 the compiler tries another strategy using different patterns (such as, a
8530 library call).
8531
8532 If the compiler were able to handle nontrivial condition-strings in
8533 patterns with names, then it would be possible to use a
8534 @code{define_insn} in that case. Here is another case (zero-extension
8535 on the 68000) which makes more use of the power of @code{define_expand}:
8536
8537 @smallexample
8538 (define_expand "zero_extendhisi2"
8539 [(set (match_operand:SI 0 "general_operand" "")
8540 (const_int 0))
8541 (set (strict_low_part
8542 (subreg:HI
8543 (match_dup 0)
8544 0))
8545 (match_operand:HI 1 "general_operand" ""))]
8546 ""
8547 "operands[1] = make_safe_from (operands[1], operands[0]);")
8548 @end smallexample
8549
8550 @noindent
8551 @findex make_safe_from
8552 Here two RTL insns are generated, one to clear the entire output operand
8553 and the other to copy the input operand into its low half. This sequence
8554 is incorrect if the input operand refers to [the old value of] the output
8555 operand, so the preparation statement makes sure this isn't so. The
8556 function @code{make_safe_from} copies the @code{operands[1]} into a
8557 temporary register if it refers to @code{operands[0]}. It does this
8558 by emitting another RTL insn.
8559
8560 Finally, a third example shows the use of an internal operand.
8561 Zero-extension on the SPUR chip is done by @code{and}-ing the result
8562 against a halfword mask. But this mask cannot be represented by a
8563 @code{const_int} because the constant value is too large to be legitimate
8564 on this machine. So it must be copied into a register with
8565 @code{force_reg} and then the register used in the @code{and}.
8566
8567 @smallexample
8568 (define_expand "zero_extendhisi2"
8569 [(set (match_operand:SI 0 "register_operand" "")
8570 (and:SI (subreg:SI
8571 (match_operand:HI 1 "register_operand" "")
8572 0)
8573 (match_dup 2)))]
8574 ""
8575 "operands[2]
8576 = force_reg (SImode, GEN_INT (65535)); ")
8577 @end smallexample
8578
8579 @emph{Note:} If the @code{define_expand} is used to serve a
8580 standard binary or unary arithmetic operation or a bit-field operation,
8581 then the last insn it generates must not be a @code{code_label},
8582 @code{barrier} or @code{note}. It must be an @code{insn},
8583 @code{jump_insn} or @code{call_insn}. If you don't need a real insn
8584 at the end, emit an insn to copy the result of the operation into
8585 itself. Such an insn will generate no code, but it can avoid problems
8586 in the compiler.
8587
8588 @end ifset
8589 @ifset INTERNALS
8590 @node Insn Splitting
8591 @section Defining How to Split Instructions
8592 @cindex insn splitting
8593 @cindex instruction splitting
8594 @cindex splitting instructions
8595
8596 There are two cases where you should specify how to split a pattern
8597 into multiple insns. On machines that have instructions requiring
8598 delay slots (@pxref{Delay Slots}) or that have instructions whose
8599 output is not available for multiple cycles (@pxref{Processor pipeline
8600 description}), the compiler phases that optimize these cases need to
8601 be able to move insns into one-instruction delay slots. However, some
8602 insns may generate more than one machine instruction. These insns
8603 cannot be placed into a delay slot.
8604
8605 Often you can rewrite the single insn as a list of individual insns,
8606 each corresponding to one machine instruction. The disadvantage of
8607 doing so is that it will cause the compilation to be slower and require
8608 more space. If the resulting insns are too complex, it may also
8609 suppress some optimizations. The compiler splits the insn if there is a
8610 reason to believe that it might improve instruction or delay slot
8611 scheduling.
8612
8613 The insn combiner phase also splits putative insns. If three insns are
8614 merged into one insn with a complex expression that cannot be matched by
8615 some @code{define_insn} pattern, the combiner phase attempts to split
8616 the complex pattern into two insns that are recognized. Usually it can
8617 break the complex pattern into two patterns by splitting out some
8618 subexpression. However, in some other cases, such as performing an
8619 addition of a large constant in two insns on a RISC machine, the way to
8620 split the addition into two insns is machine-dependent.
8621
8622 @findex define_split
8623 The @code{define_split} definition tells the compiler how to split a
8624 complex insn into several simpler insns. It looks like this:
8625
8626 @smallexample
8627 (define_split
8628 [@var{insn-pattern}]
8629 "@var{condition}"
8630 [@var{new-insn-pattern-1}
8631 @var{new-insn-pattern-2}
8632 @dots{}]
8633 "@var{preparation-statements}")
8634 @end smallexample
8635
8636 @var{insn-pattern} is a pattern that needs to be split and
8637 @var{condition} is the final condition to be tested, as in a
8638 @code{define_insn}. When an insn matching @var{insn-pattern} and
8639 satisfying @var{condition} is found, it is replaced in the insn list
8640 with the insns given by @var{new-insn-pattern-1},
8641 @var{new-insn-pattern-2}, etc.
8642
8643 The @var{preparation-statements} are similar to those statements that
8644 are specified for @code{define_expand} (@pxref{Expander Definitions})
8645 and are executed before the new RTL is generated to prepare for the
8646 generated code or emit some insns whose pattern is not fixed. Unlike
8647 those in @code{define_expand}, however, these statements must not
8648 generate any new pseudo-registers. Once reload has completed, they also
8649 must not allocate any space in the stack frame.
8650
8651 There are two special macros defined for use in the preparation statements:
8652 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
8653 as a statement.
8654
8655 @table @code
8656
8657 @findex DONE
8658 @item DONE
8659 Use the @code{DONE} macro to end RTL generation for the splitter. The
8660 only RTL insns generated as replacement for the matched input insn will
8661 be those already emitted by explicit calls to @code{emit_insn} within
8662 the preparation statements; the replacement pattern is not used.
8663
8664 @findex FAIL
8665 @item FAIL
8666 Make the @code{define_split} fail on this occasion. When a @code{define_split}
8667 fails, it means that the splitter was not truly available for the inputs
8668 it was given, and the input insn will not be split.
8669 @end table
8670
8671 If the preparation falls through (invokes neither @code{DONE} nor
8672 @code{FAIL}), then the @code{define_split} uses the replacement
8673 template.
8674
8675 Patterns are matched against @var{insn-pattern} in two different
8676 circumstances. If an insn needs to be split for delay slot scheduling
8677 or insn scheduling, the insn is already known to be valid, which means
8678 that it must have been matched by some @code{define_insn} and, if
8679 @code{reload_completed} is nonzero, is known to satisfy the constraints
8680 of that @code{define_insn}. In that case, the new insn patterns must
8681 also be insns that are matched by some @code{define_insn} and, if
8682 @code{reload_completed} is nonzero, must also satisfy the constraints
8683 of those definitions.
8684
8685 As an example of this usage of @code{define_split}, consider the following
8686 example from @file{a29k.md}, which splits a @code{sign_extend} from
8687 @code{HImode} to @code{SImode} into a pair of shift insns:
8688
8689 @smallexample
8690 (define_split
8691 [(set (match_operand:SI 0 "gen_reg_operand" "")
8692 (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
8693 ""
8694 [(set (match_dup 0)
8695 (ashift:SI (match_dup 1)
8696 (const_int 16)))
8697 (set (match_dup 0)
8698 (ashiftrt:SI (match_dup 0)
8699 (const_int 16)))]
8700 "
8701 @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
8702 @end smallexample
8703
8704 When the combiner phase tries to split an insn pattern, it is always the
8705 case that the pattern is @emph{not} matched by any @code{define_insn}.
8706 The combiner pass first tries to split a single @code{set} expression
8707 and then the same @code{set} expression inside a @code{parallel}, but
8708 followed by a @code{clobber} of a pseudo-reg to use as a scratch
8709 register. In these cases, the combiner expects exactly one or two new insn
8710 patterns to be generated. It will verify that these patterns match some
8711 @code{define_insn} definitions, so you need not do this test in the
8712 @code{define_split} (of course, there is no point in writing a
8713 @code{define_split} that will never produce insns that match).
8714
8715 Here is an example of this use of @code{define_split}, taken from
8716 @file{rs6000.md}:
8717
8718 @smallexample
8719 (define_split
8720 [(set (match_operand:SI 0 "gen_reg_operand" "")
8721 (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
8722 (match_operand:SI 2 "non_add_cint_operand" "")))]
8723 ""
8724 [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
8725 (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
8726 "
8727 @{
8728 int low = INTVAL (operands[2]) & 0xffff;
8729 int high = (unsigned) INTVAL (operands[2]) >> 16;
8730
8731 if (low & 0x8000)
8732 high++, low |= 0xffff0000;
8733
8734 operands[3] = GEN_INT (high << 16);
8735 operands[4] = GEN_INT (low);
8736 @}")
8737 @end smallexample
8738
8739 Here the predicate @code{non_add_cint_operand} matches any
8740 @code{const_int} that is @emph{not} a valid operand of a single add
8741 insn. The add with the smaller displacement is written so that it
8742 can be substituted into the address of a subsequent operation.
8743
8744 An example that uses a scratch register, from the same file, generates
8745 an equality comparison of a register and a large constant:
8746
8747 @smallexample
8748 (define_split
8749 [(set (match_operand:CC 0 "cc_reg_operand" "")
8750 (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
8751 (match_operand:SI 2 "non_short_cint_operand" "")))
8752 (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
8753 "find_single_use (operands[0], insn, 0)
8754 && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
8755 || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
8756 [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
8757 (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
8758 "
8759 @{
8760 /* @r{Get the constant we are comparing against, C, and see what it
8761 looks like sign-extended to 16 bits. Then see what constant
8762 could be XOR'ed with C to get the sign-extended value.} */
8763
8764 int c = INTVAL (operands[2]);
8765 int sextc = (c << 16) >> 16;
8766 int xorv = c ^ sextc;
8767
8768 operands[4] = GEN_INT (xorv);
8769 operands[5] = GEN_INT (sextc);
8770 @}")
8771 @end smallexample
8772
8773 To avoid confusion, don't write a single @code{define_split} that
8774 accepts some insns that match some @code{define_insn} as well as some
8775 insns that don't. Instead, write two separate @code{define_split}
8776 definitions, one for the insns that are valid and one for the insns that
8777 are not valid.
8778
8779 The splitter is allowed to split jump instructions into a sequence of jumps or
8780 create new jumps while splitting non-jump instructions. As the control flow
8781 graph and branch prediction information needs to be updated after the splitter
8782 runs, several restrictions apply.
8783
8784 Splitting of a jump instruction into a sequence that has another jump
8785 instruction to the same label is always valid, as the compiler expects
8786 identical behavior of the new jump. When the new sequence contains multiple
8787 jump instructions or new labels, more assistance is needed. The splitter is
8788 permitted to create only unconditional jumps, or simple conditional jump
8789 instructions. Additionally it must attach a @code{REG_BR_PROB} note to each
8790 conditional jump. A global variable @code{split_branch_probability} holds the
8791 probability of the original branch in case it was a simple conditional jump,
8792 @minus{}1 otherwise. To simplify recomputing of edge frequencies, the new
8793 sequence is permitted to have only forward jumps to the newly-created labels.
8794
8795 @findex define_insn_and_split
8796 For the common case where the pattern of a define_split exactly matches the
8797 pattern of a define_insn, use @code{define_insn_and_split}. It looks like
8798 this:
8799
8800 @smallexample
8801 (define_insn_and_split
8802 [@var{insn-pattern}]
8803 "@var{condition}"
8804 "@var{output-template}"
8805 "@var{split-condition}"
8806 [@var{new-insn-pattern-1}
8807 @var{new-insn-pattern-2}
8808 @dots{}]
8809 "@var{preparation-statements}"
8810 [@var{insn-attributes}])
8811
8812 @end smallexample
8813
8814 @var{insn-pattern}, @var{condition}, @var{output-template}, and
8815 @var{insn-attributes} are used as in @code{define_insn}. The
8816 @var{new-insn-pattern} vector and the @var{preparation-statements} are used as
8817 in a @code{define_split}. The @var{split-condition} is also used as in
8818 @code{define_split}, with the additional behavior that if the condition starts
8819 with @samp{&&}, the condition used for the split will be the constructed as a
8820 logical ``and'' of the split condition with the insn condition. For example,
8821 from i386.md:
8822
8823 @smallexample
8824 (define_insn_and_split "zero_extendhisi2_and"
8825 [(set (match_operand:SI 0 "register_operand" "=r")
8826 (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
8827 (clobber (reg:CC 17))]
8828 "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
8829 "#"
8830 "&& reload_completed"
8831 [(parallel [(set (match_dup 0)
8832 (and:SI (match_dup 0) (const_int 65535)))
8833 (clobber (reg:CC 17))])]
8834 ""
8835 [(set_attr "type" "alu1")])
8836
8837 @end smallexample
8838
8839 In this case, the actual split condition will be
8840 @samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
8841
8842 The @code{define_insn_and_split} construction provides exactly the same
8843 functionality as two separate @code{define_insn} and @code{define_split}
8844 patterns. It exists for compactness, and as a maintenance tool to prevent
8845 having to ensure the two patterns' templates match.
8846
8847 @findex define_insn_and_rewrite
8848 It is sometimes useful to have a @code{define_insn_and_split}
8849 that replaces specific operands of an instruction but leaves the
8850 rest of the instruction pattern unchanged. You can do this directly
8851 with a @code{define_insn_and_split}, but it requires a
8852 @var{new-insn-pattern-1} that repeats most of the original @var{insn-pattern}.
8853 There is also the complication that an implicit @code{parallel} in
8854 @var{insn-pattern} must become an explicit @code{parallel} in
8855 @var{new-insn-pattern-1}, which is easy to overlook.
8856 A simpler alternative is to use @code{define_insn_and_rewrite}, which
8857 is a form of @code{define_insn_and_split} that automatically generates
8858 @var{new-insn-pattern-1} by replacing each @code{match_operand}
8859 in @var{insn-pattern} with a corresponding @code{match_dup}, and each
8860 @code{match_operator} in the pattern with a corresponding @code{match_op_dup}.
8861 The arguments are otherwise identical to @code{define_insn_and_split}:
8862
8863 @smallexample
8864 (define_insn_and_rewrite
8865 [@var{insn-pattern}]
8866 "@var{condition}"
8867 "@var{output-template}"
8868 "@var{split-condition}"
8869 "@var{preparation-statements}"
8870 [@var{insn-attributes}])
8871 @end smallexample
8872
8873 The @code{match_dup}s and @code{match_op_dup}s in the new
8874 instruction pattern use any new operand values that the
8875 @var{preparation-statements} store in the @code{operands} array,
8876 as for a normal @code{define_insn_and_split}. @var{preparation-statements}
8877 can also emit additional instructions before the new instruction.
8878 They can even emit an entirely different sequence of instructions and
8879 use @code{DONE} to avoid emitting a new form of the original
8880 instruction.
8881
8882 The split in a @code{define_insn_and_rewrite} is only intended
8883 to apply to existing instructions that match @var{insn-pattern}.
8884 @var{split-condition} must therefore start with @code{&&},
8885 so that the split condition applies on top of @var{condition}.
8886
8887 Here is an example from the AArch64 SVE port, in which operand 1 is
8888 known to be equivalent to an all-true constant and isn't used by the
8889 output template:
8890
8891 @smallexample
8892 (define_insn_and_rewrite "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
8893 [(set (reg:CC CC_REGNUM)
8894 (compare:CC
8895 (unspec:SI [(match_operand:PRED_ALL 1)
8896 (unspec:PRED_ALL
8897 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
8898 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
8899 UNSPEC_WHILE_LO)]
8900 UNSPEC_PTEST_PTRUE)
8901 (const_int 0)))
8902 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
8903 (unspec:PRED_ALL [(match_dup 2)
8904 (match_dup 3)]
8905 UNSPEC_WHILE_LO))]
8906 "TARGET_SVE"
8907 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
8908 ;; Force the compiler to drop the unused predicate operand, so that we
8909 ;; don't have an unnecessary PTRUE.
8910 "&& !CONSTANT_P (operands[1])"
8911 @{
8912 operands[1] = CONSTM1_RTX (<MODE>mode);
8913 @}
8914 )
8915 @end smallexample
8916
8917 The splitter in this case simply replaces operand 1 with the constant
8918 value that it is known to have. The equivalent @code{define_insn_and_split}
8919 would be:
8920
8921 @smallexample
8922 (define_insn_and_split "*while_ult<GPI:mode><PRED_ALL:mode>_cc"
8923 [(set (reg:CC CC_REGNUM)
8924 (compare:CC
8925 (unspec:SI [(match_operand:PRED_ALL 1)
8926 (unspec:PRED_ALL
8927 [(match_operand:GPI 2 "aarch64_reg_or_zero" "rZ")
8928 (match_operand:GPI 3 "aarch64_reg_or_zero" "rZ")]
8929 UNSPEC_WHILE_LO)]
8930 UNSPEC_PTEST_PTRUE)
8931 (const_int 0)))
8932 (set (match_operand:PRED_ALL 0 "register_operand" "=Upa")
8933 (unspec:PRED_ALL [(match_dup 2)
8934 (match_dup 3)]
8935 UNSPEC_WHILE_LO))]
8936 "TARGET_SVE"
8937 "whilelo\t%0.<PRED_ALL:Vetype>, %<w>2, %<w>3"
8938 ;; Force the compiler to drop the unused predicate operand, so that we
8939 ;; don't have an unnecessary PTRUE.
8940 "&& !CONSTANT_P (operands[1])"
8941 [(parallel
8942 [(set (reg:CC CC_REGNUM)
8943 (compare:CC
8944 (unspec:SI [(match_dup 1)
8945 (unspec:PRED_ALL [(match_dup 2)
8946 (match_dup 3)]
8947 UNSPEC_WHILE_LO)]
8948 UNSPEC_PTEST_PTRUE)
8949 (const_int 0)))
8950 (set (match_dup 0)
8951 (unspec:PRED_ALL [(match_dup 2)
8952 (match_dup 3)]
8953 UNSPEC_WHILE_LO))])]
8954 @{
8955 operands[1] = CONSTM1_RTX (<MODE>mode);
8956 @}
8957 )
8958 @end smallexample
8959
8960 @end ifset
8961 @ifset INTERNALS
8962 @node Including Patterns
8963 @section Including Patterns in Machine Descriptions.
8964 @cindex insn includes
8965
8966 @findex include
8967 The @code{include} pattern tells the compiler tools where to
8968 look for patterns that are in files other than in the file
8969 @file{.md}. This is used only at build time and there is no preprocessing allowed.
8970
8971 It looks like:
8972
8973 @smallexample
8974
8975 (include @var{pathname})
8976 @end smallexample
8977
8978 For example:
8979
8980 @smallexample
8981
8982 (include "filestuff")
8983
8984 @end smallexample
8985
8986 Where @var{pathname} is a string that specifies the location of the file,
8987 specifies the include file to be in @file{gcc/config/target/filestuff}. The
8988 directory @file{gcc/config/target} is regarded as the default directory.
8989
8990
8991 Machine descriptions may be split up into smaller more manageable subsections
8992 and placed into subdirectories.
8993
8994 By specifying:
8995
8996 @smallexample
8997
8998 (include "BOGUS/filestuff")
8999
9000 @end smallexample
9001
9002 the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.
9003
9004 Specifying an absolute path for the include file such as;
9005 @smallexample
9006
9007 (include "/u2/BOGUS/filestuff")
9008
9009 @end smallexample
9010 is permitted but is not encouraged.
9011
9012 @subsection RTL Generation Tool Options for Directory Search
9013 @cindex directory options .md
9014 @cindex options, directory search
9015 @cindex search options
9016
9017 The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
9018 For example:
9019
9020 @smallexample
9021
9022 genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md
9023
9024 @end smallexample
9025
9026
9027 Add the directory @var{dir} to the head of the list of directories to be
9028 searched for header files. This can be used to override a system machine definition
9029 file, substituting your own version, since these directories are
9030 searched before the default machine description file directories. If you use more than
9031 one @option{-I} option, the directories are scanned in left-to-right
9032 order; the standard default directory come after.
9033
9034
9035 @end ifset
9036 @ifset INTERNALS
9037 @node Peephole Definitions
9038 @section Machine-Specific Peephole Optimizers
9039 @cindex peephole optimizer definitions
9040 @cindex defining peephole optimizers
9041
9042 In addition to instruction patterns the @file{md} file may contain
9043 definitions of machine-specific peephole optimizations.
9044
9045 The combiner does not notice certain peephole optimizations when the data
9046 flow in the program does not suggest that it should try them. For example,
9047 sometimes two consecutive insns related in purpose can be combined even
9048 though the second one does not appear to use a register computed in the
9049 first one. A machine-specific peephole optimizer can detect such
9050 opportunities.
9051
9052 There are two forms of peephole definitions that may be used. The
9053 original @code{define_peephole} is run at assembly output time to
9054 match insns and substitute assembly text. Use of @code{define_peephole}
9055 is deprecated.
9056
9057 A newer @code{define_peephole2} matches insns and substitutes new
9058 insns. The @code{peephole2} pass is run after register allocation
9059 but before scheduling, which may result in much better code for
9060 targets that do scheduling.
9061
9062 @menu
9063 * define_peephole:: RTL to Text Peephole Optimizers
9064 * define_peephole2:: RTL to RTL Peephole Optimizers
9065 @end menu
9066
9067 @end ifset
9068 @ifset INTERNALS
9069 @node define_peephole
9070 @subsection RTL to Text Peephole Optimizers
9071 @findex define_peephole
9072
9073 @need 1000
9074 A definition looks like this:
9075
9076 @smallexample
9077 (define_peephole
9078 [@var{insn-pattern-1}
9079 @var{insn-pattern-2}
9080 @dots{}]
9081 "@var{condition}"
9082 "@var{template}"
9083 "@var{optional-insn-attributes}")
9084 @end smallexample
9085
9086 @noindent
9087 The last string operand may be omitted if you are not using any
9088 machine-specific information in this machine description. If present,
9089 it must obey the same rules as in a @code{define_insn}.
9090
9091 In this skeleton, @var{insn-pattern-1} and so on are patterns to match
9092 consecutive insns. The optimization applies to a sequence of insns when
9093 @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
9094 the next, and so on.
9095
9096 Each of the insns matched by a peephole must also match a
9097 @code{define_insn}. Peepholes are checked only at the last stage just
9098 before code generation, and only optionally. Therefore, any insn which
9099 would match a peephole but no @code{define_insn} will cause a crash in code
9100 generation in an unoptimized compilation, or at various optimization
9101 stages.
9102
9103 The operands of the insns are matched with @code{match_operands},
9104 @code{match_operator}, and @code{match_dup}, as usual. What is not
9105 usual is that the operand numbers apply to all the insn patterns in the
9106 definition. So, you can check for identical operands in two insns by
9107 using @code{match_operand} in one insn and @code{match_dup} in the
9108 other.
9109
9110 The operand constraints used in @code{match_operand} patterns do not have
9111 any direct effect on the applicability of the peephole, but they will
9112 be validated afterward, so make sure your constraints are general enough
9113 to apply whenever the peephole matches. If the peephole matches
9114 but the constraints are not satisfied, the compiler will crash.
9115
9116 It is safe to omit constraints in all the operands of the peephole; or
9117 you can write constraints which serve as a double-check on the criteria
9118 previously tested.
9119
9120 Once a sequence of insns matches the patterns, the @var{condition} is
9121 checked. This is a C expression which makes the final decision whether to
9122 perform the optimization (we do so if the expression is nonzero). If
9123 @var{condition} is omitted (in other words, the string is empty) then the
9124 optimization is applied to every sequence of insns that matches the
9125 patterns.
9126
9127 The defined peephole optimizations are applied after register allocation
9128 is complete. Therefore, the peephole definition can check which
9129 operands have ended up in which kinds of registers, just by looking at
9130 the operands.
9131
9132 @findex prev_active_insn
9133 The way to refer to the operands in @var{condition} is to write
9134 @code{operands[@var{i}]} for operand number @var{i} (as matched by
9135 @code{(match_operand @var{i} @dots{})}). Use the variable @code{insn}
9136 to refer to the last of the insns being matched; use
9137 @code{prev_active_insn} to find the preceding insns.
9138
9139 @findex dead_or_set_p
9140 When optimizing computations with intermediate results, you can use
9141 @var{condition} to match only when the intermediate results are not used
9142 elsewhere. Use the C expression @code{dead_or_set_p (@var{insn},
9143 @var{op})}, where @var{insn} is the insn in which you expect the value
9144 to be used for the last time (from the value of @code{insn}, together
9145 with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
9146 value (from @code{operands[@var{i}]}).
9147
9148 Applying the optimization means replacing the sequence of insns with one
9149 new insn. The @var{template} controls ultimate output of assembler code
9150 for this combined insn. It works exactly like the template of a
9151 @code{define_insn}. Operand numbers in this template are the same ones
9152 used in matching the original sequence of insns.
9153
9154 The result of a defined peephole optimizer does not need to match any of
9155 the insn patterns in the machine description; it does not even have an
9156 opportunity to match them. The peephole optimizer definition itself serves
9157 as the insn pattern to control how the insn is output.
9158
9159 Defined peephole optimizers are run as assembler code is being output,
9160 so the insns they produce are never combined or rearranged in any way.
9161
9162 Here is an example, taken from the 68000 machine description:
9163
9164 @smallexample
9165 (define_peephole
9166 [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
9167 (set (match_operand:DF 0 "register_operand" "=f")
9168 (match_operand:DF 1 "register_operand" "ad"))]
9169 "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
9170 @{
9171 rtx xoperands[2];
9172 xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
9173 #ifdef MOTOROLA
9174 output_asm_insn ("move.l %1,(sp)", xoperands);
9175 output_asm_insn ("move.l %1,-(sp)", operands);
9176 return "fmove.d (sp)+,%0";
9177 #else
9178 output_asm_insn ("movel %1,sp@@", xoperands);
9179 output_asm_insn ("movel %1,sp@@-", operands);
9180 return "fmoved sp@@+,%0";
9181 #endif
9182 @})
9183 @end smallexample
9184
9185 @need 1000
9186 The effect of this optimization is to change
9187
9188 @smallexample
9189 @group
9190 jbsr _foobar
9191 addql #4,sp
9192 movel d1,sp@@-
9193 movel d0,sp@@-
9194 fmoved sp@@+,fp0
9195 @end group
9196 @end smallexample
9197
9198 @noindent
9199 into
9200
9201 @smallexample
9202 @group
9203 jbsr _foobar
9204 movel d1,sp@@
9205 movel d0,sp@@-
9206 fmoved sp@@+,fp0
9207 @end group
9208 @end smallexample
9209
9210 @ignore
9211 @findex CC_REVERSED
9212 If a peephole matches a sequence including one or more jump insns, you must
9213 take account of the flags such as @code{CC_REVERSED} which specify that the
9214 condition codes are represented in an unusual manner. The compiler
9215 automatically alters any ordinary conditional jumps which occur in such
9216 situations, but the compiler cannot alter jumps which have been replaced by
9217 peephole optimizations. So it is up to you to alter the assembler code
9218 that the peephole produces. Supply C code to write the assembler output,
9219 and in this C code check the condition code status flags and change the
9220 assembler code as appropriate.
9221 @end ignore
9222
9223 @var{insn-pattern-1} and so on look @emph{almost} like the second
9224 operand of @code{define_insn}. There is one important difference: the
9225 second operand of @code{define_insn} consists of one or more RTX's
9226 enclosed in square brackets. Usually, there is only one: then the same
9227 action can be written as an element of a @code{define_peephole}. But
9228 when there are multiple actions in a @code{define_insn}, they are
9229 implicitly enclosed in a @code{parallel}. Then you must explicitly
9230 write the @code{parallel}, and the square brackets within it, in the
9231 @code{define_peephole}. Thus, if an insn pattern looks like this,
9232
9233 @smallexample
9234 (define_insn "divmodsi4"
9235 [(set (match_operand:SI 0 "general_operand" "=d")
9236 (div:SI (match_operand:SI 1 "general_operand" "0")
9237 (match_operand:SI 2 "general_operand" "dmsK")))
9238 (set (match_operand:SI 3 "general_operand" "=d")
9239 (mod:SI (match_dup 1) (match_dup 2)))]
9240 "TARGET_68020"
9241 "divsl%.l %2,%3:%0")
9242 @end smallexample
9243
9244 @noindent
9245 then the way to mention this insn in a peephole is as follows:
9246
9247 @smallexample
9248 (define_peephole
9249 [@dots{}
9250 (parallel
9251 [(set (match_operand:SI 0 "general_operand" "=d")
9252 (div:SI (match_operand:SI 1 "general_operand" "0")
9253 (match_operand:SI 2 "general_operand" "dmsK")))
9254 (set (match_operand:SI 3 "general_operand" "=d")
9255 (mod:SI (match_dup 1) (match_dup 2)))])
9256 @dots{}]
9257 @dots{})
9258 @end smallexample
9259
9260 @end ifset
9261 @ifset INTERNALS
9262 @node define_peephole2
9263 @subsection RTL to RTL Peephole Optimizers
9264 @findex define_peephole2
9265
9266 The @code{define_peephole2} definition tells the compiler how to
9267 substitute one sequence of instructions for another sequence,
9268 what additional scratch registers may be needed and what their
9269 lifetimes must be.
9270
9271 @smallexample
9272 (define_peephole2
9273 [@var{insn-pattern-1}
9274 @var{insn-pattern-2}
9275 @dots{}]
9276 "@var{condition}"
9277 [@var{new-insn-pattern-1}
9278 @var{new-insn-pattern-2}
9279 @dots{}]
9280 "@var{preparation-statements}")
9281 @end smallexample
9282
9283 The definition is almost identical to @code{define_split}
9284 (@pxref{Insn Splitting}) except that the pattern to match is not a
9285 single instruction, but a sequence of instructions.
9286
9287 It is possible to request additional scratch registers for use in the
9288 output template. If appropriate registers are not free, the pattern
9289 will simply not match.
9290
9291 @findex match_scratch
9292 @findex match_dup
9293 Scratch registers are requested with a @code{match_scratch} pattern at
9294 the top level of the input pattern. The allocated register (initially) will
9295 be dead at the point requested within the original sequence. If the scratch
9296 is used at more than a single point, a @code{match_dup} pattern at the
9297 top level of the input pattern marks the last position in the input sequence
9298 at which the register must be available.
9299
9300 Here is an example from the IA-32 machine description:
9301
9302 @smallexample
9303 (define_peephole2
9304 [(match_scratch:SI 2 "r")
9305 (parallel [(set (match_operand:SI 0 "register_operand" "")
9306 (match_operator:SI 3 "arith_or_logical_operator"
9307 [(match_dup 0)
9308 (match_operand:SI 1 "memory_operand" "")]))
9309 (clobber (reg:CC 17))])]
9310 "! optimize_size && ! TARGET_READ_MODIFY"
9311 [(set (match_dup 2) (match_dup 1))
9312 (parallel [(set (match_dup 0)
9313 (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
9314 (clobber (reg:CC 17))])]
9315 "")
9316 @end smallexample
9317
9318 @noindent
9319 This pattern tries to split a load from its use in the hopes that we'll be
9320 able to schedule around the memory load latency. It allocates a single
9321 @code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
9322 to be live only at the point just before the arithmetic.
9323
9324 A real example requiring extended scratch lifetimes is harder to come by,
9325 so here's a silly made-up example:
9326
9327 @smallexample
9328 (define_peephole2
9329 [(match_scratch:SI 4 "r")
9330 (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
9331 (set (match_operand:SI 2 "" "") (match_dup 1))
9332 (match_dup 4)
9333 (set (match_operand:SI 3 "" "") (match_dup 1))]
9334 "/* @r{determine 1 does not overlap 0 and 2} */"
9335 [(set (match_dup 4) (match_dup 1))
9336 (set (match_dup 0) (match_dup 4))
9337 (set (match_dup 2) (match_dup 4))
9338 (set (match_dup 3) (match_dup 4))]
9339 "")
9340 @end smallexample
9341
9342 @noindent
9343 If we had not added the @code{(match_dup 4)} in the middle of the input
9344 sequence, it might have been the case that the register we chose at the
9345 beginning of the sequence is killed by the first or second @code{set}.
9346
9347 There are two special macros defined for use in the preparation statements:
9348 @code{DONE} and @code{FAIL}. Use them with a following semicolon,
9349 as a statement.
9350
9351 @table @code
9352
9353 @findex DONE
9354 @item DONE
9355 Use the @code{DONE} macro to end RTL generation for the peephole. The
9356 only RTL insns generated as replacement for the matched input insn will
9357 be those already emitted by explicit calls to @code{emit_insn} within
9358 the preparation statements; the replacement pattern is not used.
9359
9360 @findex FAIL
9361 @item FAIL
9362 Make the @code{define_peephole2} fail on this occasion. When a @code{define_peephole2}
9363 fails, it means that the replacement was not truly available for the
9364 particular inputs it was given. In that case, GCC may still apply a
9365 later @code{define_peephole2} that also matches the given insn pattern.
9366 (Note that this is different from @code{define_split}, where @code{FAIL}
9367 prevents the input insn from being split at all.)
9368 @end table
9369
9370 If the preparation falls through (invokes neither @code{DONE} nor
9371 @code{FAIL}), then the @code{define_peephole2} uses the replacement
9372 template.
9373
9374 @end ifset
9375 @ifset INTERNALS
9376 @node Insn Attributes
9377 @section Instruction Attributes
9378 @cindex insn attributes
9379 @cindex instruction attributes
9380
9381 In addition to describing the instruction supported by the target machine,
9382 the @file{md} file also defines a group of @dfn{attributes} and a set of
9383 values for each. Every generated insn is assigned a value for each attribute.
9384 One possible attribute would be the effect that the insn has on the machine's
9385 condition code.
9386
9387 @menu
9388 * Defining Attributes:: Specifying attributes and their values.
9389 * Expressions:: Valid expressions for attribute values.
9390 * Tagging Insns:: Assigning attribute values to insns.
9391 * Attr Example:: An example of assigning attributes.
9392 * Insn Lengths:: Computing the length of insns.
9393 * Constant Attributes:: Defining attributes that are constant.
9394 * Mnemonic Attribute:: Obtain the instruction mnemonic as attribute value.
9395 * Delay Slots:: Defining delay slots required for a machine.
9396 * Processor pipeline description:: Specifying information for insn scheduling.
9397 @end menu
9398
9399 @end ifset
9400 @ifset INTERNALS
9401 @node Defining Attributes
9402 @subsection Defining Attributes and their Values
9403 @cindex defining attributes and their values
9404 @cindex attributes, defining
9405
9406 @findex define_attr
9407 The @code{define_attr} expression is used to define each attribute required
9408 by the target machine. It looks like:
9409
9410 @smallexample
9411 (define_attr @var{name} @var{list-of-values} @var{default})
9412 @end smallexample
9413
9414 @var{name} is a string specifying the name of the attribute being
9415 defined. Some attributes are used in a special way by the rest of the
9416 compiler. The @code{enabled} attribute can be used to conditionally
9417 enable or disable insn alternatives (@pxref{Disable Insn
9418 Alternatives}). The @code{predicable} attribute, together with a
9419 suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can
9420 be used to automatically generate conditional variants of instruction
9421 patterns. The @code{mnemonic} attribute can be used to check for the
9422 instruction mnemonic (@pxref{Mnemonic Attribute}). The compiler
9423 internally uses the names @code{ce_enabled} and @code{nonce_enabled},
9424 so they should not be used elsewhere as alternative names.
9425
9426 @var{list-of-values} is either a string that specifies a comma-separated
9427 list of values that can be assigned to the attribute, or a null string to
9428 indicate that the attribute takes numeric values.
9429
9430 @var{default} is an attribute expression that gives the value of this
9431 attribute for insns that match patterns whose definition does not include
9432 an explicit value for this attribute. @xref{Attr Example}, for more
9433 information on the handling of defaults. @xref{Constant Attributes},
9434 for information on attributes that do not depend on any particular insn.
9435
9436 @findex insn-attr.h
9437 For each defined attribute, a number of definitions are written to the
9438 @file{insn-attr.h} file. For cases where an explicit set of values is
9439 specified for an attribute, the following are defined:
9440
9441 @itemize @bullet
9442 @item
9443 A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.
9444
9445 @item
9446 An enumerated class is defined for @samp{attr_@var{name}} with
9447 elements of the form @samp{@var{upper-name}_@var{upper-value}} where
9448 the attribute name and value are first converted to uppercase.
9449
9450 @item
9451 A function @samp{get_attr_@var{name}} is defined that is passed an insn and
9452 returns the attribute value for that insn.
9453 @end itemize
9454
9455 For example, if the following is present in the @file{md} file:
9456
9457 @smallexample
9458 (define_attr "type" "branch,fp,load,store,arith" @dots{})
9459 @end smallexample
9460
9461 @noindent
9462 the following lines will be written to the file @file{insn-attr.h}.
9463
9464 @smallexample
9465 #define HAVE_ATTR_type 1
9466 enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
9467 TYPE_STORE, TYPE_ARITH@};
9468 extern enum attr_type get_attr_type ();
9469 @end smallexample
9470
9471 If the attribute takes numeric values, no @code{enum} type will be
9472 defined and the function to obtain the attribute's value will return
9473 @code{int}.
9474
9475 There are attributes which are tied to a specific meaning. These
9476 attributes are not free to use for other purposes:
9477
9478 @table @code
9479 @item length
9480 The @code{length} attribute is used to calculate the length of emitted
9481 code chunks. This is especially important when verifying branch
9482 distances. @xref{Insn Lengths}.
9483
9484 @item enabled
9485 The @code{enabled} attribute can be defined to prevent certain
9486 alternatives of an insn definition from being used during code
9487 generation. @xref{Disable Insn Alternatives}.
9488
9489 @item mnemonic
9490 The @code{mnemonic} attribute can be defined to implement instruction
9491 specific checks in e.g.@: the pipeline description.
9492 @xref{Mnemonic Attribute}.
9493 @end table
9494
9495 For each of these special attributes, the corresponding
9496 @samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the
9497 attribute is not defined; in that case, it is defined as @samp{0}.
9498
9499 @findex define_enum_attr
9500 @anchor{define_enum_attr}
9501 Another way of defining an attribute is to use:
9502
9503 @smallexample
9504 (define_enum_attr "@var{attr}" "@var{enum}" @var{default})
9505 @end smallexample
9506
9507 This works in just the same way as @code{define_attr}, except that
9508 the list of values is taken from a separate enumeration called
9509 @var{enum} (@pxref{define_enum}). This form allows you to use
9510 the same list of values for several attributes without having to
9511 repeat the list each time. For example:
9512
9513 @smallexample
9514 (define_enum "processor" [
9515 model_a
9516 model_b
9517 @dots{}
9518 ])
9519 (define_enum_attr "arch" "processor"
9520 (const (symbol_ref "target_arch")))
9521 (define_enum_attr "tune" "processor"
9522 (const (symbol_ref "target_tune")))
9523 @end smallexample
9524
9525 defines the same attributes as:
9526
9527 @smallexample
9528 (define_attr "arch" "model_a,model_b,@dots{}"
9529 (const (symbol_ref "target_arch")))
9530 (define_attr "tune" "model_a,model_b,@dots{}"
9531 (const (symbol_ref "target_tune")))
9532 @end smallexample
9533
9534 but without duplicating the processor list. The second example defines two
9535 separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
9536 defines a single C enum (@code{processor}).
9537 @end ifset
9538 @ifset INTERNALS
9539 @node Expressions
9540 @subsection Attribute Expressions
9541 @cindex attribute expressions
9542
9543 RTL expressions used to define attributes use the codes described above
9544 plus a few specific to attribute definitions, to be discussed below.
9545 Attribute value expressions must have one of the following forms:
9546
9547 @table @code
9548 @cindex @code{const_int} and attributes
9549 @item (const_int @var{i})
9550 The integer @var{i} specifies the value of a numeric attribute. @var{i}
9551 must be non-negative.
9552
9553 The value of a numeric attribute can be specified either with a
9554 @code{const_int}, or as an integer represented as a string in
9555 @code{const_string}, @code{eq_attr} (see below), @code{attr},
9556 @code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
9557 overrides on specific instructions (@pxref{Tagging Insns}).
9558
9559 @cindex @code{const_string} and attributes
9560 @item (const_string @var{value})
9561 The string @var{value} specifies a constant attribute value.
9562 If @var{value} is specified as @samp{"*"}, it means that the default value of
9563 the attribute is to be used for the insn containing this expression.
9564 @samp{"*"} obviously cannot be used in the @var{default} expression
9565 of a @code{define_attr}.
9566
9567 If the attribute whose value is being specified is numeric, @var{value}
9568 must be a string containing a non-negative integer (normally
9569 @code{const_int} would be used in this case). Otherwise, it must
9570 contain one of the valid values for the attribute.
9571
9572 @cindex @code{if_then_else} and attributes
9573 @item (if_then_else @var{test} @var{true-value} @var{false-value})
9574 @var{test} specifies an attribute test, whose format is defined below.
9575 The value of this expression is @var{true-value} if @var{test} is true,
9576 otherwise it is @var{false-value}.
9577
9578 @cindex @code{cond} and attributes
9579 @item (cond [@var{test1} @var{value1} @dots{}] @var{default})
9580 The first operand of this expression is a vector containing an even
9581 number of expressions and consisting of pairs of @var{test} and @var{value}
9582 expressions. The value of the @code{cond} expression is that of the
9583 @var{value} corresponding to the first true @var{test} expression. If
9584 none of the @var{test} expressions are true, the value of the @code{cond}
9585 expression is that of the @var{default} expression.
9586 @end table
9587
9588 @var{test} expressions can have one of the following forms:
9589
9590 @table @code
9591 @cindex @code{const_int} and attribute tests
9592 @item (const_int @var{i})
9593 This test is true if @var{i} is nonzero and false otherwise.
9594
9595 @cindex @code{not} and attributes
9596 @cindex @code{ior} and attributes
9597 @cindex @code{and} and attributes
9598 @item (not @var{test})
9599 @itemx (ior @var{test1} @var{test2})
9600 @itemx (and @var{test1} @var{test2})
9601 These tests are true if the indicated logical function is true.
9602
9603 @cindex @code{match_operand} and attributes
9604 @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
9605 This test is true if operand @var{n} of the insn whose attribute value
9606 is being determined has mode @var{m} (this part of the test is ignored
9607 if @var{m} is @code{VOIDmode}) and the function specified by the string
9608 @var{pred} returns a nonzero value when passed operand @var{n} and mode
9609 @var{m} (this part of the test is ignored if @var{pred} is the null
9610 string).
9611
9612 The @var{constraints} operand is ignored and should be the null string.
9613
9614 @cindex @code{match_test} and attributes
9615 @item (match_test @var{c-expr})
9616 The test is true if C expression @var{c-expr} is true. In non-constant
9617 attributes, @var{c-expr} has access to the following variables:
9618
9619 @table @var
9620 @item insn
9621 The rtl instruction under test.
9622 @item which_alternative
9623 The @code{define_insn} alternative that @var{insn} matches.
9624 @xref{Output Statement}.
9625 @item operands
9626 An array of @var{insn}'s rtl operands.
9627 @end table
9628
9629 @var{c-expr} behaves like the condition in a C @code{if} statement,
9630 so there is no need to explicitly convert the expression into a boolean
9631 0 or 1 value. For example, the following two tests are equivalent:
9632
9633 @smallexample
9634 (match_test "x & 2")
9635 (match_test "(x & 2) != 0")
9636 @end smallexample
9637
9638 @cindex @code{le} and attributes
9639 @cindex @code{leu} and attributes
9640 @cindex @code{lt} and attributes
9641 @cindex @code{gt} and attributes
9642 @cindex @code{gtu} and attributes
9643 @cindex @code{ge} and attributes
9644 @cindex @code{geu} and attributes
9645 @cindex @code{ne} and attributes
9646 @cindex @code{eq} and attributes
9647 @cindex @code{plus} and attributes
9648 @cindex @code{minus} and attributes
9649 @cindex @code{mult} and attributes
9650 @cindex @code{div} and attributes
9651 @cindex @code{mod} and attributes
9652 @cindex @code{abs} and attributes
9653 @cindex @code{neg} and attributes
9654 @cindex @code{ashift} and attributes
9655 @cindex @code{lshiftrt} and attributes
9656 @cindex @code{ashiftrt} and attributes
9657 @item (le @var{arith1} @var{arith2})
9658 @itemx (leu @var{arith1} @var{arith2})
9659 @itemx (lt @var{arith1} @var{arith2})
9660 @itemx (ltu @var{arith1} @var{arith2})
9661 @itemx (gt @var{arith1} @var{arith2})
9662 @itemx (gtu @var{arith1} @var{arith2})
9663 @itemx (ge @var{arith1} @var{arith2})
9664 @itemx (geu @var{arith1} @var{arith2})
9665 @itemx (ne @var{arith1} @var{arith2})
9666 @itemx (eq @var{arith1} @var{arith2})
9667 These tests are true if the indicated comparison of the two arithmetic
9668 expressions is true. Arithmetic expressions are formed with
9669 @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
9670 @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
9671 @code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.
9672
9673 @findex get_attr
9674 @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
9675 Lengths},for additional forms). @code{symbol_ref} is a string
9676 denoting a C expression that yields an @code{int} when evaluated by the
9677 @samp{get_attr_@dots{}} routine. It should normally be a global
9678 variable.
9679
9680 @findex eq_attr
9681 @item (eq_attr @var{name} @var{value})
9682 @var{name} is a string specifying the name of an attribute.
9683
9684 @var{value} is a string that is either a valid value for attribute
9685 @var{name}, a comma-separated list of values, or @samp{!} followed by a
9686 value or list. If @var{value} does not begin with a @samp{!}, this
9687 test is true if the value of the @var{name} attribute of the current
9688 insn is in the list specified by @var{value}. If @var{value} begins
9689 with a @samp{!}, this test is true if the attribute's value is
9690 @emph{not} in the specified list.
9691
9692 For example,
9693
9694 @smallexample
9695 (eq_attr "type" "load,store")
9696 @end smallexample
9697
9698 @noindent
9699 is equivalent to
9700
9701 @smallexample
9702 (ior (eq_attr "type" "load") (eq_attr "type" "store"))
9703 @end smallexample
9704
9705 If @var{name} specifies an attribute of @samp{alternative}, it refers to the
9706 value of the compiler variable @code{which_alternative}
9707 (@pxref{Output Statement}) and the values must be small integers. For
9708 example,
9709
9710 @smallexample
9711 (eq_attr "alternative" "2,3")
9712 @end smallexample
9713
9714 @noindent
9715 is equivalent to
9716
9717 @smallexample
9718 (ior (eq (symbol_ref "which_alternative") (const_int 2))
9719 (eq (symbol_ref "which_alternative") (const_int 3)))
9720 @end smallexample
9721
9722 Note that, for most attributes, an @code{eq_attr} test is simplified in cases
9723 where the value of the attribute being tested is known for all insns matching
9724 a particular pattern. This is by far the most common case.
9725
9726 @findex attr_flag
9727 @item (attr_flag @var{name})
9728 The value of an @code{attr_flag} expression is true if the flag
9729 specified by @var{name} is true for the @code{insn} currently being
9730 scheduled.
9731
9732 @var{name} is a string specifying one of a fixed set of flags to test.
9733 Test the flags @code{forward} and @code{backward} to determine the
9734 direction of a conditional branch.
9735
9736 This example describes a conditional branch delay slot which
9737 can be nullified for forward branches that are taken (annul-true) or
9738 for backward branches which are not taken (annul-false).
9739
9740 @smallexample
9741 (define_delay (eq_attr "type" "cbranch")
9742 [(eq_attr "in_branch_delay" "true")
9743 (and (eq_attr "in_branch_delay" "true")
9744 (attr_flag "forward"))
9745 (and (eq_attr "in_branch_delay" "true")
9746 (attr_flag "backward"))])
9747 @end smallexample
9748
9749 The @code{forward} and @code{backward} flags are false if the current
9750 @code{insn} being scheduled is not a conditional branch.
9751
9752 @code{attr_flag} is only used during delay slot scheduling and has no
9753 meaning to other passes of the compiler.
9754
9755 @findex attr
9756 @item (attr @var{name})
9757 The value of another attribute is returned. This is most useful
9758 for numeric attributes, as @code{eq_attr} and @code{attr_flag}
9759 produce more efficient code for non-numeric attributes.
9760 @end table
9761
9762 @end ifset
9763 @ifset INTERNALS
9764 @node Tagging Insns
9765 @subsection Assigning Attribute Values to Insns
9766 @cindex tagging insns
9767 @cindex assigning attribute values to insns
9768
9769 The value assigned to an attribute of an insn is primarily determined by
9770 which pattern is matched by that insn (or which @code{define_peephole}
9771 generated it). Every @code{define_insn} and @code{define_peephole} can
9772 have an optional last argument to specify the values of attributes for
9773 matching insns. The value of any attribute not specified in a particular
9774 insn is set to the default value for that attribute, as specified in its
9775 @code{define_attr}. Extensive use of default values for attributes
9776 permits the specification of the values for only one or two attributes
9777 in the definition of most insn patterns, as seen in the example in the
9778 next section.
9779
9780 The optional last argument of @code{define_insn} and
9781 @code{define_peephole} is a vector of expressions, each of which defines
9782 the value for a single attribute. The most general way of assigning an
9783 attribute's value is to use a @code{set} expression whose first operand is an
9784 @code{attr} expression giving the name of the attribute being set. The
9785 second operand of the @code{set} is an attribute expression
9786 (@pxref{Expressions}) giving the value of the attribute.
9787
9788 When the attribute value depends on the @samp{alternative} attribute
9789 (i.e., which is the applicable alternative in the constraint of the
9790 insn), the @code{set_attr_alternative} expression can be used. It
9791 allows the specification of a vector of attribute expressions, one for
9792 each alternative.
9793
9794 @findex set_attr
9795 When the generality of arbitrary attribute expressions is not required,
9796 the simpler @code{set_attr} expression can be used, which allows
9797 specifying a string giving either a single attribute value or a list
9798 of attribute values, one for each alternative.
9799
9800 The form of each of the above specifications is shown below. In each case,
9801 @var{name} is a string specifying the attribute to be set.
9802
9803 @table @code
9804 @item (set_attr @var{name} @var{value-string})
9805 @var{value-string} is either a string giving the desired attribute value,
9806 or a string containing a comma-separated list giving the values for
9807 succeeding alternatives. The number of elements must match the number
9808 of alternatives in the constraint of the insn pattern.
9809
9810 Note that it may be useful to specify @samp{*} for some alternative, in
9811 which case the attribute will assume its default value for insns matching
9812 that alternative.
9813
9814 @findex set_attr_alternative
9815 @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
9816 Depending on the alternative of the insn, the value will be one of the
9817 specified values. This is a shorthand for using a @code{cond} with
9818 tests on the @samp{alternative} attribute.
9819
9820 @findex attr
9821 @item (set (attr @var{name}) @var{value})
9822 The first operand of this @code{set} must be the special RTL expression
9823 @code{attr}, whose sole operand is a string giving the name of the
9824 attribute being set. @var{value} is the value of the attribute.
9825 @end table
9826
9827 The following shows three different ways of representing the same
9828 attribute value specification:
9829
9830 @smallexample
9831 (set_attr "type" "load,store,arith")
9832
9833 (set_attr_alternative "type"
9834 [(const_string "load") (const_string "store")
9835 (const_string "arith")])
9836
9837 (set (attr "type")
9838 (cond [(eq_attr "alternative" "1") (const_string "load")
9839 (eq_attr "alternative" "2") (const_string "store")]
9840 (const_string "arith")))
9841 @end smallexample
9842
9843 @need 1000
9844 @findex define_asm_attributes
9845 The @code{define_asm_attributes} expression provides a mechanism to
9846 specify the attributes assigned to insns produced from an @code{asm}
9847 statement. It has the form:
9848
9849 @smallexample
9850 (define_asm_attributes [@var{attr-sets}])
9851 @end smallexample
9852
9853 @noindent
9854 where @var{attr-sets} is specified the same as for both the
9855 @code{define_insn} and the @code{define_peephole} expressions.
9856
9857 These values will typically be the ``worst case'' attribute values. For
9858 example, they might indicate that the condition code will be clobbered.
9859
9860 A specification for a @code{length} attribute is handled specially. The
9861 way to compute the length of an @code{asm} insn is to multiply the
9862 length specified in the expression @code{define_asm_attributes} by the
9863 number of machine instructions specified in the @code{asm} statement,
9864 determined by counting the number of semicolons and newlines in the
9865 string. Therefore, the value of the @code{length} attribute specified
9866 in a @code{define_asm_attributes} should be the maximum possible length
9867 of a single machine instruction.
9868
9869 @end ifset
9870 @ifset INTERNALS
9871 @node Attr Example
9872 @subsection Example of Attribute Specifications
9873 @cindex attribute specifications example
9874 @cindex attribute specifications
9875
9876 The judicious use of defaulting is important in the efficient use of
9877 insn attributes. Typically, insns are divided into @dfn{types} and an
9878 attribute, customarily called @code{type}, is used to represent this
9879 value. This attribute is normally used only to define the default value
9880 for other attributes. An example will clarify this usage.
9881
9882 Assume we have a RISC machine with a condition code and in which only
9883 full-word operations are performed in registers. Let us assume that we
9884 can divide all insns into loads, stores, (integer) arithmetic
9885 operations, floating point operations, and branches.
9886
9887 Here we will concern ourselves with determining the effect of an insn on
9888 the condition code and will limit ourselves to the following possible
9889 effects: The condition code can be set unpredictably (clobbered), not
9890 be changed, be set to agree with the results of the operation, or only
9891 changed if the item previously set into the condition code has been
9892 modified.
9893
9894 Here is part of a sample @file{md} file for such a machine:
9895
9896 @smallexample
9897 (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))
9898
9899 (define_attr "cc" "clobber,unchanged,set,change0"
9900 (cond [(eq_attr "type" "load")
9901 (const_string "change0")
9902 (eq_attr "type" "store,branch")
9903 (const_string "unchanged")
9904 (eq_attr "type" "arith")
9905 (if_then_else (match_operand:SI 0 "" "")
9906 (const_string "set")
9907 (const_string "clobber"))]
9908 (const_string "clobber")))
9909
9910 (define_insn ""
9911 [(set (match_operand:SI 0 "general_operand" "=r,r,m")
9912 (match_operand:SI 1 "general_operand" "r,m,r"))]
9913 ""
9914 "@@
9915 move %0,%1
9916 load %0,%1
9917 store %0,%1"
9918 [(set_attr "type" "arith,load,store")])
9919 @end smallexample
9920
9921 Note that we assume in the above example that arithmetic operations
9922 performed on quantities smaller than a machine word clobber the condition
9923 code since they will set the condition code to a value corresponding to the
9924 full-word result.
9925
9926 @end ifset
9927 @ifset INTERNALS
9928 @node Insn Lengths
9929 @subsection Computing the Length of an Insn
9930 @cindex insn lengths, computing
9931 @cindex computing the length of an insn
9932
9933 For many machines, multiple types of branch instructions are provided, each
9934 for different length branch displacements. In most cases, the assembler
9935 will choose the correct instruction to use. However, when the assembler
9936 cannot do so, GCC can when a special attribute, the @code{length}
9937 attribute, is defined. This attribute must be defined to have numeric
9938 values by specifying a null string in its @code{define_attr}.
9939
9940 In the case of the @code{length} attribute, two additional forms of
9941 arithmetic terms are allowed in test expressions:
9942
9943 @table @code
9944 @cindex @code{match_dup} and attributes
9945 @item (match_dup @var{n})
9946 This refers to the address of operand @var{n} of the current insn, which
9947 must be a @code{label_ref}.
9948
9949 @cindex @code{pc} and attributes
9950 @item (pc)
9951 For non-branch instructions and backward branch instructions, this refers
9952 to the address of the current insn. But for forward branch instructions,
9953 this refers to the address of the next insn, because the length of the
9954 current insn is to be computed.
9955 @end table
9956
9957 @cindex @code{addr_vec}, length of
9958 @cindex @code{addr_diff_vec}, length of
9959 For normal insns, the length will be determined by value of the
9960 @code{length} attribute. In the case of @code{addr_vec} and
9961 @code{addr_diff_vec} insn patterns, the length is computed as
9962 the number of vectors multiplied by the size of each vector.
9963
9964 Lengths are measured in addressable storage units (bytes).
9965
9966 Note that it is possible to call functions via the @code{symbol_ref}
9967 mechanism to compute the length of an insn. However, if you use this
9968 mechanism you must provide dummy clauses to express the maximum length
9969 without using the function call. You can see an example of this in the
9970 @code{pa} machine description for the @code{call_symref} pattern.
9971
9972 The following macros can be used to refine the length computation:
9973
9974 @table @code
9975 @findex ADJUST_INSN_LENGTH
9976 @item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
9977 If defined, modifies the length assigned to instruction @var{insn} as a
9978 function of the context in which it is used. @var{length} is an lvalue
9979 that contains the initially computed length of the insn and should be
9980 updated with the correct length of the insn.
9981
9982 This macro will normally not be required. A case in which it is
9983 required is the ROMP@. On this machine, the size of an @code{addr_vec}
9984 insn must be increased by two to compensate for the fact that alignment
9985 may be required.
9986 @end table
9987
9988 @findex get_attr_length
9989 The routine that returns @code{get_attr_length} (the value of the
9990 @code{length} attribute) can be used by the output routine to
9991 determine the form of the branch instruction to be written, as the
9992 example below illustrates.
9993
9994 As an example of the specification of variable-length branches, consider
9995 the IBM 360. If we adopt the convention that a register will be set to
9996 the starting address of a function, we can jump to labels within 4k of
9997 the start using a four-byte instruction. Otherwise, we need a six-byte
9998 sequence to load the address from memory and then branch to it.
9999
10000 On such a machine, a pattern for a branch instruction might be specified
10001 as follows:
10002
10003 @smallexample
10004 (define_insn "jump"
10005 [(set (pc)
10006 (label_ref (match_operand 0 "" "")))]
10007 ""
10008 @{
10009 return (get_attr_length (insn) == 4
10010 ? "b %l0" : "l r15,=a(%l0); br r15");
10011 @}
10012 [(set (attr "length")
10013 (if_then_else (lt (match_dup 0) (const_int 4096))
10014 (const_int 4)
10015 (const_int 6)))])
10016 @end smallexample
10017
10018 @end ifset
10019 @ifset INTERNALS
10020 @node Constant Attributes
10021 @subsection Constant Attributes
10022 @cindex constant attributes
10023
10024 A special form of @code{define_attr}, where the expression for the
10025 default value is a @code{const} expression, indicates an attribute that
10026 is constant for a given run of the compiler. Constant attributes may be
10027 used to specify which variety of processor is used. For example,
10028
10029 @smallexample
10030 (define_attr "cpu" "m88100,m88110,m88000"
10031 (const
10032 (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
10033 (symbol_ref "TARGET_88110") (const_string "m88110")]
10034 (const_string "m88000"))))
10035
10036 (define_attr "memory" "fast,slow"
10037 (const
10038 (if_then_else (symbol_ref "TARGET_FAST_MEM")
10039 (const_string "fast")
10040 (const_string "slow"))))
10041 @end smallexample
10042
10043 The routine generated for constant attributes has no parameters as it
10044 does not depend on any particular insn. RTL expressions used to define
10045 the value of a constant attribute may use the @code{symbol_ref} form,
10046 but may not use either the @code{match_operand} form or @code{eq_attr}
10047 forms involving insn attributes.
10048
10049 @end ifset
10050 @ifset INTERNALS
10051 @node Mnemonic Attribute
10052 @subsection Mnemonic Attribute
10053 @cindex mnemonic attribute
10054
10055 The @code{mnemonic} attribute is a string type attribute holding the
10056 instruction mnemonic for an insn alternative. The attribute values
10057 will automatically be generated by the machine description parser if
10058 there is an attribute definition in the md file:
10059
10060 @smallexample
10061 (define_attr "mnemonic" "unknown" (const_string "unknown"))
10062 @end smallexample
10063
10064 The default value can be freely chosen as long as it does not collide
10065 with any of the instruction mnemonics. This value will be used
10066 whenever the machine description parser is not able to determine the
10067 mnemonic string. This might be the case for output templates
10068 containing more than a single instruction as in
10069 @code{"mvcle\t%0,%1,0\;jo\t.-4"}.
10070
10071 The @code{mnemonic} attribute set is not generated automatically if the
10072 instruction string is generated via C code.
10073
10074 An existing @code{mnemonic} attribute set in an insn definition will not
10075 be overriden by the md file parser. That way it is possible to
10076 manually set the instruction mnemonics for the cases where the md file
10077 parser fails to determine it automatically.
10078
10079 The @code{mnemonic} attribute is useful for dealing with instruction
10080 specific properties in the pipeline description without defining
10081 additional insn attributes.
10082
10083 @smallexample
10084 (define_attr "ooo_expanded" ""
10085 (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
10086 (const_int 1)]
10087 (const_int 0)))
10088 @end smallexample
10089
10090 @end ifset
10091 @ifset INTERNALS
10092 @node Delay Slots
10093 @subsection Delay Slot Scheduling
10094 @cindex delay slots, defining
10095
10096 The insn attribute mechanism can be used to specify the requirements for
10097 delay slots, if any, on a target machine. An instruction is said to
10098 require a @dfn{delay slot} if some instructions that are physically
10099 after the instruction are executed as if they were located before it.
10100 Classic examples are branch and call instructions, which often execute
10101 the following instruction before the branch or call is performed.
10102
10103 On some machines, conditional branch instructions can optionally
10104 @dfn{annul} instructions in the delay slot. This means that the
10105 instruction will not be executed for certain branch outcomes. Both
10106 instructions that annul if the branch is true and instructions that
10107 annul if the branch is false are supported.
10108
10109 Delay slot scheduling differs from instruction scheduling in that
10110 determining whether an instruction needs a delay slot is dependent only
10111 on the type of instruction being generated, not on data flow between the
10112 instructions. See the next section for a discussion of data-dependent
10113 instruction scheduling.
10114
10115 @findex define_delay
10116 The requirement of an insn needing one or more delay slots is indicated
10117 via the @code{define_delay} expression. It has the following form:
10118
10119 @smallexample
10120 (define_delay @var{test}
10121 [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
10122 @var{delay-2} @var{annul-true-2} @var{annul-false-2}
10123 @dots{}])
10124 @end smallexample
10125
10126 @var{test} is an attribute test that indicates whether this
10127 @code{define_delay} applies to a particular insn. If so, the number of
10128 required delay slots is determined by the length of the vector specified
10129 as the second argument. An insn placed in delay slot @var{n} must
10130 satisfy attribute test @var{delay-n}. @var{annul-true-n} is an
10131 attribute test that specifies which insns may be annulled if the branch
10132 is true. Similarly, @var{annul-false-n} specifies which insns in the
10133 delay slot may be annulled if the branch is false. If annulling is not
10134 supported for that delay slot, @code{(nil)} should be coded.
10135
10136 For example, in the common case where branch and call insns require
10137 a single delay slot, which may contain any insn other than a branch or
10138 call, the following would be placed in the @file{md} file:
10139
10140 @smallexample
10141 (define_delay (eq_attr "type" "branch,call")
10142 [(eq_attr "type" "!branch,call") (nil) (nil)])
10143 @end smallexample
10144
10145 Multiple @code{define_delay} expressions may be specified. In this
10146 case, each such expression specifies different delay slot requirements
10147 and there must be no insn for which tests in two @code{define_delay}
10148 expressions are both true.
10149
10150 For example, if we have a machine that requires one delay slot for branches
10151 but two for calls, no delay slot can contain a branch or call insn,
10152 and any valid insn in the delay slot for the branch can be annulled if the
10153 branch is true, we might represent this as follows:
10154
10155 @smallexample
10156 (define_delay (eq_attr "type" "branch")
10157 [(eq_attr "type" "!branch,call")
10158 (eq_attr "type" "!branch,call")
10159 (nil)])
10160
10161 (define_delay (eq_attr "type" "call")
10162 [(eq_attr "type" "!branch,call") (nil) (nil)
10163 (eq_attr "type" "!branch,call") (nil) (nil)])
10164 @end smallexample
10165 @c the above is *still* too long. --mew 4feb93
10166
10167 @end ifset
10168 @ifset INTERNALS
10169 @node Processor pipeline description
10170 @subsection Specifying processor pipeline description
10171 @cindex processor pipeline description
10172 @cindex processor functional units
10173 @cindex instruction latency time
10174 @cindex interlock delays
10175 @cindex data dependence delays
10176 @cindex reservation delays
10177 @cindex pipeline hazard recognizer
10178 @cindex automaton based pipeline description
10179 @cindex regular expressions
10180 @cindex deterministic finite state automaton
10181 @cindex automaton based scheduler
10182 @cindex RISC
10183 @cindex VLIW
10184
10185 To achieve better performance, most modern processors
10186 (super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
10187 processors) have many @dfn{functional units} on which several
10188 instructions can be executed simultaneously. An instruction starts
10189 execution if its issue conditions are satisfied. If not, the
10190 instruction is stalled until its conditions are satisfied. Such
10191 @dfn{interlock (pipeline) delay} causes interruption of the fetching
10192 of successor instructions (or demands nop instructions, e.g.@: for some
10193 MIPS processors).
10194
10195 There are two major kinds of interlock delays in modern processors.
10196 The first one is a data dependence delay determining @dfn{instruction
10197 latency time}. The instruction execution is not started until all
10198 source data have been evaluated by prior instructions (there are more
10199 complex cases when the instruction execution starts even when the data
10200 are not available but will be ready in given time after the
10201 instruction execution start). Taking the data dependence delays into
10202 account is simple. The data dependence (true, output, and
10203 anti-dependence) delay between two instructions is given by a
10204 constant. In most cases this approach is adequate. The second kind
10205 of interlock delays is a reservation delay. The reservation delay
10206 means that two instructions under execution will be in need of shared
10207 processors resources, i.e.@: buses, internal registers, and/or
10208 functional units, which are reserved for some time. Taking this kind
10209 of delay into account is complex especially for modern @acronym{RISC}
10210 processors.
10211
10212 The task of exploiting more processor parallelism is solved by an
10213 instruction scheduler. For a better solution to this problem, the
10214 instruction scheduler has to have an adequate description of the
10215 processor parallelism (or @dfn{pipeline description}). GCC
10216 machine descriptions describe processor parallelism and functional
10217 unit reservations for groups of instructions with the aid of
10218 @dfn{regular expressions}.
10219
10220 The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
10221 figure out the possibility of the instruction issue by the processor
10222 on a given simulated processor cycle. The pipeline hazard recognizer is
10223 automatically generated from the processor pipeline description. The
10224 pipeline hazard recognizer generated from the machine description
10225 is based on a deterministic finite state automaton (@acronym{DFA}):
10226 the instruction issue is possible if there is a transition from one
10227 automaton state to another one. This algorithm is very fast, and
10228 furthermore, its speed is not dependent on processor
10229 complexity@footnote{However, the size of the automaton depends on
10230 processor complexity. To limit this effect, machine descriptions
10231 can split orthogonal parts of the machine description among several
10232 automata: but then, since each of these must be stepped independently,
10233 this does cause a small decrease in the algorithm's performance.}.
10234
10235 @cindex automaton based pipeline description
10236 The rest of this section describes the directives that constitute
10237 an automaton-based processor pipeline description. The order of
10238 these constructions within the machine description file is not
10239 important.
10240
10241 @findex define_automaton
10242 @cindex pipeline hazard recognizer
10243 The following optional construction describes names of automata
10244 generated and used for the pipeline hazards recognition. Sometimes
10245 the generated finite state automaton used by the pipeline hazard
10246 recognizer is large. If we use more than one automaton and bind functional
10247 units to the automata, the total size of the automata is usually
10248 less than the size of the single automaton. If there is no one such
10249 construction, only one finite state automaton is generated.
10250
10251 @smallexample
10252 (define_automaton @var{automata-names})
10253 @end smallexample
10254
10255 @var{automata-names} is a string giving names of the automata. The
10256 names are separated by commas. All the automata should have unique names.
10257 The automaton name is used in the constructions @code{define_cpu_unit} and
10258 @code{define_query_cpu_unit}.
10259
10260 @findex define_cpu_unit
10261 @cindex processor functional units
10262 Each processor functional unit used in the description of instruction
10263 reservations should be described by the following construction.
10264
10265 @smallexample
10266 (define_cpu_unit @var{unit-names} [@var{automaton-name}])
10267 @end smallexample
10268
10269 @var{unit-names} is a string giving the names of the functional units
10270 separated by commas. Don't use name @samp{nothing}, it is reserved
10271 for other goals.
10272
10273 @var{automaton-name} is a string giving the name of the automaton with
10274 which the unit is bound. The automaton should be described in
10275 construction @code{define_automaton}. You should give
10276 @dfn{automaton-name}, if there is a defined automaton.
10277
10278 The assignment of units to automata are constrained by the uses of the
10279 units in insn reservations. The most important constraint is: if a
10280 unit reservation is present on a particular cycle of an alternative
10281 for an insn reservation, then some unit from the same automaton must
10282 be present on the same cycle for the other alternatives of the insn
10283 reservation. The rest of the constraints are mentioned in the
10284 description of the subsequent constructions.
10285
10286 @findex define_query_cpu_unit
10287 @cindex querying function unit reservations
10288 The following construction describes CPU functional units analogously
10289 to @code{define_cpu_unit}. The reservation of such units can be
10290 queried for an automaton state. The instruction scheduler never
10291 queries reservation of functional units for given automaton state. So
10292 as a rule, you don't need this construction. This construction could
10293 be used for future code generation goals (e.g.@: to generate
10294 @acronym{VLIW} insn templates).
10295
10296 @smallexample
10297 (define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
10298 @end smallexample
10299
10300 @var{unit-names} is a string giving names of the functional units
10301 separated by commas.
10302
10303 @var{automaton-name} is a string giving the name of the automaton with
10304 which the unit is bound.
10305
10306 @findex define_insn_reservation
10307 @cindex instruction latency time
10308 @cindex regular expressions
10309 @cindex data bypass
10310 The following construction is the major one to describe pipeline
10311 characteristics of an instruction.
10312
10313 @smallexample
10314 (define_insn_reservation @var{insn-name} @var{default_latency}
10315 @var{condition} @var{regexp})
10316 @end smallexample
10317
10318 @var{default_latency} is a number giving latency time of the
10319 instruction. There is an important difference between the old
10320 description and the automaton based pipeline description. The latency
10321 time is used for all dependencies when we use the old description. In
10322 the automaton based pipeline description, the given latency time is only
10323 used for true dependencies. The cost of anti-dependencies is always
10324 zero and the cost of output dependencies is the difference between
10325 latency times of the producing and consuming insns (if the difference
10326 is negative, the cost is considered to be zero). You can always
10327 change the default costs for any description by using the target hook
10328 @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
10329
10330 @var{insn-name} is a string giving the internal name of the insn. The
10331 internal names are used in constructions @code{define_bypass} and in
10332 the automaton description file generated for debugging. The internal
10333 name has nothing in common with the names in @code{define_insn}. It is a
10334 good practice to use insn classes described in the processor manual.
10335
10336 @var{condition} defines what RTL insns are described by this
10337 construction. You should remember that you will be in trouble if
10338 @var{condition} for two or more different
10339 @code{define_insn_reservation} constructions is TRUE for an insn. In
10340 this case what reservation will be used for the insn is not defined.
10341 Such cases are not checked during generation of the pipeline hazards
10342 recognizer because in general recognizing that two conditions may have
10343 the same value is quite difficult (especially if the conditions
10344 contain @code{symbol_ref}). It is also not checked during the
10345 pipeline hazard recognizer work because it would slow down the
10346 recognizer considerably.
10347
10348 @var{regexp} is a string describing the reservation of the cpu's functional
10349 units by the instruction. The reservations are described by a regular
10350 expression according to the following syntax:
10351
10352 @smallexample
10353 regexp = regexp "," oneof
10354 | oneof
10355
10356 oneof = oneof "|" allof
10357 | allof
10358
10359 allof = allof "+" repeat
10360 | repeat
10361
10362 repeat = element "*" number
10363 | element
10364
10365 element = cpu_function_unit_name
10366 | reservation_name
10367 | result_name
10368 | "nothing"
10369 | "(" regexp ")"
10370 @end smallexample
10371
10372 @itemize @bullet
10373 @item
10374 @samp{,} is used for describing the start of the next cycle in
10375 the reservation.
10376
10377 @item
10378 @samp{|} is used for describing a reservation described by the first
10379 regular expression @strong{or} a reservation described by the second
10380 regular expression @strong{or} etc.
10381
10382 @item
10383 @samp{+} is used for describing a reservation described by the first
10384 regular expression @strong{and} a reservation described by the
10385 second regular expression @strong{and} etc.
10386
10387 @item
10388 @samp{*} is used for convenience and simply means a sequence in which
10389 the regular expression are repeated @var{number} times with cycle
10390 advancing (see @samp{,}).
10391
10392 @item
10393 @samp{cpu_function_unit_name} denotes reservation of the named
10394 functional unit.
10395
10396 @item
10397 @samp{reservation_name} --- see description of construction
10398 @samp{define_reservation}.
10399
10400 @item
10401 @samp{nothing} denotes no unit reservations.
10402 @end itemize
10403
10404 @findex define_reservation
10405 Sometimes unit reservations for different insns contain common parts.
10406 In such case, you can simplify the pipeline description by describing
10407 the common part by the following construction
10408
10409 @smallexample
10410 (define_reservation @var{reservation-name} @var{regexp})
10411 @end smallexample
10412
10413 @var{reservation-name} is a string giving name of @var{regexp}.
10414 Functional unit names and reservation names are in the same name
10415 space. So the reservation names should be different from the
10416 functional unit names and cannot be the reserved name @samp{nothing}.
10417
10418 @findex define_bypass
10419 @cindex instruction latency time
10420 @cindex data bypass
10421 The following construction is used to describe exceptions in the
10422 latency time for given instruction pair. This is so called bypasses.
10423
10424 @smallexample
10425 (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
10426 [@var{guard}])
10427 @end smallexample
10428
10429 @var{number} defines when the result generated by the instructions
10430 given in string @var{out_insn_names} will be ready for the
10431 instructions given in string @var{in_insn_names}. Each of these
10432 strings is a comma-separated list of filename-style globs and
10433 they refer to the names of @code{define_insn_reservation}s.
10434 For example:
10435 @smallexample
10436 (define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
10437 @end smallexample
10438 defines a bypass between instructions that start with
10439 @samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
10440 @samp{cpu1_load_}.
10441
10442 @var{guard} is an optional string giving the name of a C function which
10443 defines an additional guard for the bypass. The function will get the
10444 two insns as parameters. If the function returns zero the bypass will
10445 be ignored for this case. The additional guard is necessary to
10446 recognize complicated bypasses, e.g.@: when the consumer is only an address
10447 of insn @samp{store} (not a stored value).
10448
10449 If there are more one bypass with the same output and input insns, the
10450 chosen bypass is the first bypass with a guard in description whose
10451 guard function returns nonzero. If there is no such bypass, then
10452 bypass without the guard function is chosen.
10453
10454 @findex exclusion_set
10455 @findex presence_set
10456 @findex final_presence_set
10457 @findex absence_set
10458 @findex final_absence_set
10459 @cindex VLIW
10460 @cindex RISC
10461 The following five constructions are usually used to describe
10462 @acronym{VLIW} processors, or more precisely, to describe a placement
10463 of small instructions into @acronym{VLIW} instruction slots. They
10464 can be used for @acronym{RISC} processors, too.
10465
10466 @smallexample
10467 (exclusion_set @var{unit-names} @var{unit-names})
10468 (presence_set @var{unit-names} @var{patterns})
10469 (final_presence_set @var{unit-names} @var{patterns})
10470 (absence_set @var{unit-names} @var{patterns})
10471 (final_absence_set @var{unit-names} @var{patterns})
10472 @end smallexample
10473
10474 @var{unit-names} is a string giving names of functional units
10475 separated by commas.
10476
10477 @var{patterns} is a string giving patterns of functional units
10478 separated by comma. Currently pattern is one unit or units
10479 separated by white-spaces.
10480
10481 The first construction (@samp{exclusion_set}) means that each
10482 functional unit in the first string cannot be reserved simultaneously
10483 with a unit whose name is in the second string and vice versa. For
10484 example, the construction is useful for describing processors
10485 (e.g.@: some SPARC processors) with a fully pipelined floating point
10486 functional unit which can execute simultaneously only single floating
10487 point insns or only double floating point insns.
10488
10489 The second construction (@samp{presence_set}) means that each
10490 functional unit in the first string cannot be reserved unless at
10491 least one of pattern of units whose names are in the second string is
10492 reserved. This is an asymmetric relation. For example, it is useful
10493 for description that @acronym{VLIW} @samp{slot1} is reserved after
10494 @samp{slot0} reservation. We could describe it by the following
10495 construction
10496
10497 @smallexample
10498 (presence_set "slot1" "slot0")
10499 @end smallexample
10500
10501 Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
10502 reservation. In this case we could write
10503
10504 @smallexample
10505 (presence_set "slot1" "slot0 b0")
10506 @end smallexample
10507
10508 The third construction (@samp{final_presence_set}) is analogous to
10509 @samp{presence_set}. The difference between them is when checking is
10510 done. When an instruction is issued in given automaton state
10511 reflecting all current and planned unit reservations, the automaton
10512 state is changed. The first state is a source state, the second one
10513 is a result state. Checking for @samp{presence_set} is done on the
10514 source state reservation, checking for @samp{final_presence_set} is
10515 done on the result reservation. This construction is useful to
10516 describe a reservation which is actually two subsequent reservations.
10517 For example, if we use
10518
10519 @smallexample
10520 (presence_set "slot1" "slot0")
10521 @end smallexample
10522
10523 the following insn will be never issued (because @samp{slot1} requires
10524 @samp{slot0} which is absent in the source state).
10525
10526 @smallexample
10527 (define_reservation "insn_and_nop" "slot0 + slot1")
10528 @end smallexample
10529
10530 but it can be issued if we use analogous @samp{final_presence_set}.
10531
10532 The forth construction (@samp{absence_set}) means that each functional
10533 unit in the first string can be reserved only if each pattern of units
10534 whose names are in the second string is not reserved. This is an
10535 asymmetric relation (actually @samp{exclusion_set} is analogous to
10536 this one but it is symmetric). For example it might be useful in a
10537 @acronym{VLIW} description to say that @samp{slot0} cannot be reserved
10538 after either @samp{slot1} or @samp{slot2} have been reserved. This
10539 can be described as:
10540
10541 @smallexample
10542 (absence_set "slot0" "slot1, slot2")
10543 @end smallexample
10544
10545 Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0}
10546 are reserved or @samp{slot1} and unit @samp{b1} are reserved. In
10547 this case we could write
10548
10549 @smallexample
10550 (absence_set "slot2" "slot0 b0, slot1 b1")
10551 @end smallexample
10552
10553 All functional units mentioned in a set should belong to the same
10554 automaton.
10555
10556 The last construction (@samp{final_absence_set}) is analogous to
10557 @samp{absence_set} but checking is done on the result (state)
10558 reservation. See comments for @samp{final_presence_set}.
10559
10560 @findex automata_option
10561 @cindex deterministic finite state automaton
10562 @cindex nondeterministic finite state automaton
10563 @cindex finite state automaton minimization
10564 You can control the generator of the pipeline hazard recognizer with
10565 the following construction.
10566
10567 @smallexample
10568 (automata_option @var{options})
10569 @end smallexample
10570
10571 @var{options} is a string giving options which affect the generated
10572 code. Currently there are the following options:
10573
10574 @itemize @bullet
10575 @item
10576 @dfn{no-minimization} makes no minimization of the automaton. This is
10577 only worth to do when we are debugging the description and need to
10578 look more accurately at reservations of states.
10579
10580 @item
10581 @dfn{time} means printing time statistics about the generation of
10582 automata.
10583
10584 @item
10585 @dfn{stats} means printing statistics about the generated automata
10586 such as the number of DFA states, NDFA states and arcs.
10587
10588 @item
10589 @dfn{v} means a generation of the file describing the result automata.
10590 The file has suffix @samp{.dfa} and can be used for the description
10591 verification and debugging.
10592
10593 @item
10594 @dfn{w} means a generation of warning instead of error for
10595 non-critical errors.
10596
10597 @item
10598 @dfn{no-comb-vect} prevents the automaton generator from generating
10599 two data structures and comparing them for space efficiency. Using
10600 a comb vector to represent transitions may be better, but it can be
10601 very expensive to construct. This option is useful if the build
10602 process spends an unacceptably long time in genautomata.
10603
10604 @item
10605 @dfn{ndfa} makes nondeterministic finite state automata. This affects
10606 the treatment of operator @samp{|} in the regular expressions. The
10607 usual treatment of the operator is to try the first alternative and,
10608 if the reservation is not possible, the second alternative. The
10609 nondeterministic treatment means trying all alternatives, some of them
10610 may be rejected by reservations in the subsequent insns.
10611
10612 @item
10613 @dfn{collapse-ndfa} modifies the behavior of the generator when
10614 producing an automaton. An additional state transition to collapse a
10615 nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
10616 state is generated. It can be triggered by passing @code{const0_rtx} to
10617 state_transition. In such an automaton, cycle advance transitions are
10618 available only for these collapsed states. This option is useful for
10619 ports that want to use the @code{ndfa} option, but also want to use
10620 @code{define_query_cpu_unit} to assign units to insns issued in a cycle.
10621
10622 @item
10623 @dfn{progress} means output of a progress bar showing how many states
10624 were generated so far for automaton being processed. This is useful
10625 during debugging a @acronym{DFA} description. If you see too many
10626 generated states, you could interrupt the generator of the pipeline
10627 hazard recognizer and try to figure out a reason for generation of the
10628 huge automaton.
10629 @end itemize
10630
10631 As an example, consider a superscalar @acronym{RISC} machine which can
10632 issue three insns (two integer insns and one floating point insn) on
10633 the cycle but can finish only two insns. To describe this, we define
10634 the following functional units.
10635
10636 @smallexample
10637 (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
10638 (define_cpu_unit "port0, port1")
10639 @end smallexample
10640
10641 All simple integer insns can be executed in any integer pipeline and
10642 their result is ready in two cycles. The simple integer insns are
10643 issued into the first pipeline unless it is reserved, otherwise they
10644 are issued into the second pipeline. Integer division and
10645 multiplication insns can be executed only in the second integer
10646 pipeline and their results are ready correspondingly in 9 and 4
10647 cycles. The integer division is not pipelined, i.e.@: the subsequent
10648 integer division insn cannot be issued until the current division
10649 insn finished. Floating point insns are fully pipelined and their
10650 results are ready in 3 cycles. Where the result of a floating point
10651 insn is used by an integer insn, an additional delay of one cycle is
10652 incurred. To describe all of this we could specify
10653
10654 @smallexample
10655 (define_cpu_unit "div")
10656
10657 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
10658 "(i0_pipeline | i1_pipeline), (port0 | port1)")
10659
10660 (define_insn_reservation "mult" 4 (eq_attr "type" "mult")
10661 "i1_pipeline, nothing*2, (port0 | port1)")
10662
10663 (define_insn_reservation "div" 9 (eq_attr "type" "div")
10664 "i1_pipeline, div*7, div + (port0 | port1)")
10665
10666 (define_insn_reservation "float" 3 (eq_attr "type" "float")
10667 "f_pipeline, nothing, (port0 | port1))
10668
10669 (define_bypass 4 "float" "simple,mult,div")
10670 @end smallexample
10671
10672 To simplify the description we could describe the following reservation
10673
10674 @smallexample
10675 (define_reservation "finish" "port0|port1")
10676 @end smallexample
10677
10678 and use it in all @code{define_insn_reservation} as in the following
10679 construction
10680
10681 @smallexample
10682 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
10683 "(i0_pipeline | i1_pipeline), finish")
10684 @end smallexample
10685
10686
10687 @end ifset
10688 @ifset INTERNALS
10689 @node Conditional Execution
10690 @section Conditional Execution
10691 @cindex conditional execution
10692 @cindex predication
10693
10694 A number of architectures provide for some form of conditional
10695 execution, or predication. The hallmark of this feature is the
10696 ability to nullify most of the instructions in the instruction set.
10697 When the instruction set is large and not entirely symmetric, it
10698 can be quite tedious to describe these forms directly in the
10699 @file{.md} file. An alternative is the @code{define_cond_exec} template.
10700
10701 @findex define_cond_exec
10702 @smallexample
10703 (define_cond_exec
10704 [@var{predicate-pattern}]
10705 "@var{condition}"
10706 "@var{output-template}"
10707 "@var{optional-insn-attribues}")
10708 @end smallexample
10709
10710 @var{predicate-pattern} is the condition that must be true for the
10711 insn to be executed at runtime and should match a relational operator.
10712 One can use @code{match_operator} to match several relational operators
10713 at once. Any @code{match_operand} operands must have no more than one
10714 alternative.
10715
10716 @var{condition} is a C expression that must be true for the generated
10717 pattern to match.
10718
10719 @findex current_insn_predicate
10720 @var{output-template} is a string similar to the @code{define_insn}
10721 output template (@pxref{Output Template}), except that the @samp{*}
10722 and @samp{@@} special cases do not apply. This is only useful if the
10723 assembly text for the predicate is a simple prefix to the main insn.
10724 In order to handle the general case, there is a global variable
10725 @code{current_insn_predicate} that will contain the entire predicate
10726 if the current insn is predicated, and will otherwise be @code{NULL}.
10727
10728 @var{optional-insn-attributes} is an optional vector of attributes that gets
10729 appended to the insn attributes of the produced cond_exec rtx. It can
10730 be used to add some distinguishing attribute to cond_exec rtxs produced
10731 that way. An example usage would be to use this attribute in conjunction
10732 with attributes on the main pattern to disable particular alternatives under
10733 certain conditions.
10734
10735 When @code{define_cond_exec} is used, an implicit reference to
10736 the @code{predicable} instruction attribute is made.
10737 @xref{Insn Attributes}. This attribute must be a boolean (i.e.@: have
10738 exactly two elements in its @var{list-of-values}), with the possible
10739 values being @code{no} and @code{yes}. The default and all uses in
10740 the insns must be a simple constant, not a complex expressions. It
10741 may, however, depend on the alternative, by using a comma-separated
10742 list of values. If that is the case, the port should also define an
10743 @code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
10744 should also allow only @code{no} and @code{yes} as its values.
10745
10746 For each @code{define_insn} for which the @code{predicable}
10747 attribute is true, a new @code{define_insn} pattern will be
10748 generated that matches a predicated version of the instruction.
10749 For example,
10750
10751 @smallexample
10752 (define_insn "addsi"
10753 [(set (match_operand:SI 0 "register_operand" "r")
10754 (plus:SI (match_operand:SI 1 "register_operand" "r")
10755 (match_operand:SI 2 "register_operand" "r")))]
10756 "@var{test1}"
10757 "add %2,%1,%0")
10758
10759 (define_cond_exec
10760 [(ne (match_operand:CC 0 "register_operand" "c")
10761 (const_int 0))]
10762 "@var{test2}"
10763 "(%0)")
10764 @end smallexample
10765
10766 @noindent
10767 generates a new pattern
10768
10769 @smallexample
10770 (define_insn ""
10771 [(cond_exec
10772 (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
10773 (set (match_operand:SI 0 "register_operand" "r")
10774 (plus:SI (match_operand:SI 1 "register_operand" "r")
10775 (match_operand:SI 2 "register_operand" "r"))))]
10776 "(@var{test2}) && (@var{test1})"
10777 "(%3) add %2,%1,%0")
10778 @end smallexample
10779
10780 @end ifset
10781 @ifset INTERNALS
10782 @node Define Subst
10783 @section RTL Templates Transformations
10784 @cindex define_subst
10785
10786 For some hardware architectures there are common cases when the RTL
10787 templates for the instructions can be derived from the other RTL
10788 templates using simple transformations. E.g., @file{i386.md} contains
10789 an RTL template for the ordinary @code{sub} instruction---
10790 @code{*subsi_1}, and for the @code{sub} instruction with subsequent
10791 zero-extension---@code{*subsi_1_zext}. Such cases can be easily
10792 implemented by a single meta-template capable of generating a modified
10793 case based on the initial one:
10794
10795 @findex define_subst
10796 @smallexample
10797 (define_subst "@var{name}"
10798 [@var{input-template}]
10799 "@var{condition}"
10800 [@var{output-template}])
10801 @end smallexample
10802 @var{input-template} is a pattern describing the source RTL template,
10803 which will be transformed.
10804
10805 @var{condition} is a C expression that is conjunct with the condition
10806 from the input-template to generate a condition to be used in the
10807 output-template.
10808
10809 @var{output-template} is a pattern that will be used in the resulting
10810 template.
10811
10812 @code{define_subst} mechanism is tightly coupled with the notion of the
10813 subst attribute (@pxref{Subst Iterators}). The use of
10814 @code{define_subst} is triggered by a reference to a subst attribute in
10815 the transforming RTL template. This reference initiates duplication of
10816 the source RTL template and substitution of the attributes with their
10817 values. The source RTL template is left unchanged, while the copy is
10818 transformed by @code{define_subst}. This transformation can fail in the
10819 case when the source RTL template is not matched against the
10820 input-template of the @code{define_subst}. In such case the copy is
10821 deleted.
10822
10823 @code{define_subst} can be used only in @code{define_insn} and
10824 @code{define_expand}, it cannot be used in other expressions (e.g.@: in
10825 @code{define_insn_and_split}).
10826
10827 @menu
10828 * Define Subst Example:: Example of @code{define_subst} work.
10829 * Define Subst Pattern Matching:: Process of template comparison.
10830 * Define Subst Output Template:: Generation of output template.
10831 @end menu
10832
10833 @node Define Subst Example
10834 @subsection @code{define_subst} Example
10835 @cindex define_subst
10836
10837 To illustrate how @code{define_subst} works, let us examine a simple
10838 template transformation.
10839
10840 Suppose there are two kinds of instructions: one that touches flags and
10841 the other that does not. The instructions of the second type could be
10842 generated with the following @code{define_subst}:
10843
10844 @smallexample
10845 (define_subst "add_clobber_subst"
10846 [(set (match_operand:SI 0 "" "")
10847 (match_operand:SI 1 "" ""))]
10848 ""
10849 [(set (match_dup 0)
10850 (match_dup 1))
10851 (clobber (reg:CC FLAGS_REG))])
10852 @end smallexample
10853
10854 This @code{define_subst} can be applied to any RTL pattern containing
10855 @code{set} of mode SI and generates a copy with clobber when it is
10856 applied.
10857
10858 Assume there is an RTL template for a @code{max} instruction to be used
10859 in @code{define_subst} mentioned above:
10860
10861 @smallexample
10862 (define_insn "maxsi"
10863 [(set (match_operand:SI 0 "register_operand" "=r")
10864 (max:SI
10865 (match_operand:SI 1 "register_operand" "r")
10866 (match_operand:SI 2 "register_operand" "r")))]
10867 ""
10868 "max\t@{%2, %1, %0|%0, %1, %2@}"
10869 [@dots{}])
10870 @end smallexample
10871
10872 To mark the RTL template for @code{define_subst} application,
10873 subst-attributes are used. They should be declared in advance:
10874
10875 @smallexample
10876 (define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber")
10877 @end smallexample
10878
10879 Here @samp{add_clobber_name} is the attribute name,
10880 @samp{add_clobber_subst} is the name of the corresponding
10881 @code{define_subst}, the third argument (@samp{_noclobber}) is the
10882 attribute value that would be substituted into the unchanged version of
10883 the source RTL template, and the last argument (@samp{_clobber}) is the
10884 value that would be substituted into the second, transformed,
10885 version of the RTL template.
10886
10887 Once the subst-attribute has been defined, it should be used in RTL
10888 templates which need to be processed by the @code{define_subst}. So,
10889 the original RTL template should be changed:
10890
10891 @smallexample
10892 (define_insn "maxsi<add_clobber_name>"
10893 [(set (match_operand:SI 0 "register_operand" "=r")
10894 (max:SI
10895 (match_operand:SI 1 "register_operand" "r")
10896 (match_operand:SI 2 "register_operand" "r")))]
10897 ""
10898 "max\t@{%2, %1, %0|%0, %1, %2@}"
10899 [@dots{}])
10900 @end smallexample
10901
10902 The result of the @code{define_subst} usage would look like the following:
10903
10904 @smallexample
10905 (define_insn "maxsi_noclobber"
10906 [(set (match_operand:SI 0 "register_operand" "=r")
10907 (max:SI
10908 (match_operand:SI 1 "register_operand" "r")
10909 (match_operand:SI 2 "register_operand" "r")))]
10910 ""
10911 "max\t@{%2, %1, %0|%0, %1, %2@}"
10912 [@dots{}])
10913 (define_insn "maxsi_clobber"
10914 [(set (match_operand:SI 0 "register_operand" "=r")
10915 (max:SI
10916 (match_operand:SI 1 "register_operand" "r")
10917 (match_operand:SI 2 "register_operand" "r")))
10918 (clobber (reg:CC FLAGS_REG))]
10919 ""
10920 "max\t@{%2, %1, %0|%0, %1, %2@}"
10921 [@dots{}])
10922 @end smallexample
10923
10924 @node Define Subst Pattern Matching
10925 @subsection Pattern Matching in @code{define_subst}
10926 @cindex define_subst
10927
10928 All expressions, allowed in @code{define_insn} or @code{define_expand},
10929 are allowed in the input-template of @code{define_subst}, except
10930 @code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The
10931 meanings of expressions in the input-template were changed:
10932
10933 @code{match_operand} matches any expression (possibly, a subtree in
10934 RTL-template), if modes of the @code{match_operand} and this expression
10935 are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or
10936 this expression is @code{match_dup}, @code{match_op_dup}. If the
10937 expression is @code{match_operand} too, and predicate of
10938 @code{match_operand} from the input pattern is not empty, then the
10939 predicates are compared. That can be used for more accurate filtering
10940 of accepted RTL-templates.
10941
10942 @code{match_operator} matches common operators (like @code{plus},
10943 @code{minus}), @code{unspec}, @code{unspec_volatile} operators and
10944 @code{match_operator}s from the original pattern if the modes match and
10945 @code{match_operator} from the input pattern has the same number of
10946 operands as the operator from the original pattern.
10947
10948 @node Define Subst Output Template
10949 @subsection Generation of output template in @code{define_subst}
10950 @cindex define_subst
10951
10952 If all necessary checks for @code{define_subst} application pass, a new
10953 RTL-pattern, based on the output-template, is created to replace the old
10954 template. Like in input-patterns, meanings of some RTL expressions are
10955 changed when they are used in output-patterns of a @code{define_subst}.
10956 Thus, @code{match_dup} is used for copying the whole expression from the
10957 original pattern, which matched corresponding @code{match_operand} from
10958 the input pattern.
10959
10960 @code{match_dup N} is used in the output template to be replaced with
10961 the expression from the original pattern, which matched
10962 @code{match_operand N} from the input pattern. As a consequence,
10963 @code{match_dup} cannot be used to point to @code{match_operand}s from
10964 the output pattern, it should always refer to a @code{match_operand}
10965 from the input pattern. If a @code{match_dup N} occurs more than once
10966 in the output template, its first occurrence is replaced with the
10967 expression from the original pattern, and the subsequent expressions
10968 are replaced with @code{match_dup N}, i.e., a reference to the first
10969 expression.
10970
10971 In the output template one can refer to the expressions from the
10972 original pattern and create new ones. For instance, some operands could
10973 be added by means of standard @code{match_operand}.
10974
10975 After replacing @code{match_dup} with some RTL-subtree from the original
10976 pattern, it could happen that several @code{match_operand}s in the
10977 output pattern have the same indexes. It is unknown, how many and what
10978 indexes would be used in the expression which would replace
10979 @code{match_dup}, so such conflicts in indexes are inevitable. To
10980 overcome this issue, @code{match_operands} and @code{match_operators},
10981 which were introduced into the output pattern, are renumerated when all
10982 @code{match_dup}s are replaced.
10983
10984 Number of alternatives in @code{match_operand}s introduced into the
10985 output template @code{M} could differ from the number of alternatives in
10986 the original pattern @code{N}, so in the resultant pattern there would
10987 be @code{N*M} alternatives. Thus, constraints from the original pattern
10988 would be duplicated @code{N} times, constraints from the output pattern
10989 would be duplicated @code{M} times, producing all possible combinations.
10990 @end ifset
10991
10992 @ifset INTERNALS
10993 @node Constant Definitions
10994 @section Constant Definitions
10995 @cindex constant definitions
10996 @findex define_constants
10997
10998 Using literal constants inside instruction patterns reduces legibility and
10999 can be a maintenance problem.
11000
11001 To overcome this problem, you may use the @code{define_constants}
11002 expression. It contains a vector of name-value pairs. From that
11003 point on, wherever any of the names appears in the MD file, it is as
11004 if the corresponding value had been written instead. You may use
11005 @code{define_constants} multiple times; each appearance adds more
11006 constants to the table. It is an error to redefine a constant with
11007 a different value.
11008
11009 To come back to the a29k load multiple example, instead of
11010
11011 @smallexample
11012 (define_insn ""
11013 [(match_parallel 0 "load_multiple_operation"
11014 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11015 (match_operand:SI 2 "memory_operand" "m"))
11016 (use (reg:SI 179))
11017 (clobber (reg:SI 179))])]
11018 ""
11019 "loadm 0,0,%1,%2")
11020 @end smallexample
11021
11022 You could write:
11023
11024 @smallexample
11025 (define_constants [
11026 (R_BP 177)
11027 (R_FC 178)
11028 (R_CR 179)
11029 (R_Q 180)
11030 ])
11031
11032 (define_insn ""
11033 [(match_parallel 0 "load_multiple_operation"
11034 [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
11035 (match_operand:SI 2 "memory_operand" "m"))
11036 (use (reg:SI R_CR))
11037 (clobber (reg:SI R_CR))])]
11038 ""
11039 "loadm 0,0,%1,%2")
11040 @end smallexample
11041
11042 The constants that are defined with a define_constant are also output
11043 in the insn-codes.h header file as #defines.
11044
11045 @cindex enumerations
11046 @findex define_c_enum
11047 You can also use the machine description file to define enumerations.
11048 Like the constants defined by @code{define_constant}, these enumerations
11049 are visible to both the machine description file and the main C code.
11050
11051 The syntax is as follows:
11052
11053 @smallexample
11054 (define_c_enum "@var{name}" [
11055 @var{value0}
11056 @var{value1}
11057 (@var{value32} 32)
11058 @var{value33}
11059 @dots{}
11060 @var{valuen}
11061 ])
11062 @end smallexample
11063
11064 This definition causes the equivalent of the following C code to appear
11065 in @file{insn-constants.h}:
11066
11067 @smallexample
11068 enum @var{name} @{
11069 @var{value0} = 0,
11070 @var{value1} = 1,
11071 @var{value32} = 32,
11072 @var{value33} = 33,
11073 @dots{}
11074 @var{valuen} = @var{n}
11075 @};
11076 #define NUM_@var{cname}_VALUES (@var{n} + 1)
11077 @end smallexample
11078
11079 where @var{cname} is the capitalized form of @var{name}.
11080 It also makes each @var{valuei} available in the machine description
11081 file, just as if it had been declared with:
11082
11083 @smallexample
11084 (define_constants [(@var{valuei} @var{i})])
11085 @end smallexample
11086
11087 Each @var{valuei} is usually an upper-case identifier and usually
11088 begins with @var{cname}.
11089
11090 You can split the enumeration definition into as many statements as
11091 you like. The above example is directly equivalent to:
11092
11093 @smallexample
11094 (define_c_enum "@var{name}" [@var{value0}])
11095 (define_c_enum "@var{name}" [@var{value1}])
11096 @dots{}
11097 (define_c_enum "@var{name}" [@var{valuen}])
11098 @end smallexample
11099
11100 Splitting the enumeration helps to improve the modularity of each
11101 individual @code{.md} file. For example, if a port defines its
11102 synchronization instructions in a separate @file{sync.md} file,
11103 it is convenient to define all synchronization-specific enumeration
11104 values in @file{sync.md} rather than in the main @file{.md} file.
11105
11106 Some enumeration names have special significance to GCC:
11107
11108 @table @code
11109 @findex unspec_volatile
11110 @item unspecv
11111 If an enumeration called @code{unspecv} is defined, GCC will use it
11112 when printing out @code{unspec_volatile} expressions. For example:
11113
11114 @smallexample
11115 (define_c_enum "unspecv" [
11116 UNSPECV_BLOCKAGE
11117 ])
11118 @end smallexample
11119
11120 causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:
11121
11122 @smallexample
11123 (unspec_volatile ... UNSPECV_BLOCKAGE)
11124 @end smallexample
11125
11126 @findex unspec
11127 @item unspec
11128 If an enumeration called @code{unspec} is defined, GCC will use
11129 it when printing out @code{unspec} expressions. GCC will also use
11130 it when printing out @code{unspec_volatile} expressions unless an
11131 @code{unspecv} enumeration is also defined. You can therefore
11132 decide whether to keep separate enumerations for volatile and
11133 non-volatile expressions or whether to use the same enumeration
11134 for both.
11135 @end table
11136
11137 @findex define_enum
11138 @anchor{define_enum}
11139 Another way of defining an enumeration is to use @code{define_enum}:
11140
11141 @smallexample
11142 (define_enum "@var{name}" [
11143 @var{value0}
11144 @var{value1}
11145 @dots{}
11146 @var{valuen}
11147 ])
11148 @end smallexample
11149
11150 This directive implies:
11151
11152 @smallexample
11153 (define_c_enum "@var{name}" [
11154 @var{cname}_@var{cvalue0}
11155 @var{cname}_@var{cvalue1}
11156 @dots{}
11157 @var{cname}_@var{cvaluen}
11158 ])
11159 @end smallexample
11160
11161 @findex define_enum_attr
11162 where @var{cvaluei} is the capitalized form of @var{valuei}.
11163 However, unlike @code{define_c_enum}, the enumerations defined
11164 by @code{define_enum} can be used in attribute specifications
11165 (@pxref{define_enum_attr}).
11166 @end ifset
11167 @ifset INTERNALS
11168 @node Iterators
11169 @section Iterators
11170 @cindex iterators in @file{.md} files
11171
11172 Ports often need to define similar patterns for more than one machine
11173 mode or for more than one rtx code. GCC provides some simple iterator
11174 facilities to make this process easier.
11175
11176 @menu
11177 * Mode Iterators:: Generating variations of patterns for different modes.
11178 * Code Iterators:: Doing the same for codes.
11179 * Int Iterators:: Doing the same for integers.
11180 * Subst Iterators:: Generating variations of patterns for define_subst.
11181 * Parameterized Names:: Specifying iterator values in C++ code.
11182 @end menu
11183
11184 @node Mode Iterators
11185 @subsection Mode Iterators
11186 @cindex mode iterators in @file{.md} files
11187
11188 Ports often need to define similar patterns for two or more different modes.
11189 For example:
11190
11191 @itemize @bullet
11192 @item
11193 If a processor has hardware support for both single and double
11194 floating-point arithmetic, the @code{SFmode} patterns tend to be
11195 very similar to the @code{DFmode} ones.
11196
11197 @item
11198 If a port uses @code{SImode} pointers in one configuration and
11199 @code{DImode} pointers in another, it will usually have very similar
11200 @code{SImode} and @code{DImode} patterns for manipulating pointers.
11201 @end itemize
11202
11203 Mode iterators allow several patterns to be instantiated from one
11204 @file{.md} file template. They can be used with any type of
11205 rtx-based construct, such as a @code{define_insn},
11206 @code{define_split}, or @code{define_peephole2}.
11207
11208 @menu
11209 * Defining Mode Iterators:: Defining a new mode iterator.
11210 * Substitutions:: Combining mode iterators with substitutions
11211 * Examples:: Examples
11212 @end menu
11213
11214 @node Defining Mode Iterators
11215 @subsubsection Defining Mode Iterators
11216 @findex define_mode_iterator
11217
11218 The syntax for defining a mode iterator is:
11219
11220 @smallexample
11221 (define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
11222 @end smallexample
11223
11224 This allows subsequent @file{.md} file constructs to use the mode suffix
11225 @code{:@var{name}}. Every construct that does so will be expanded
11226 @var{n} times, once with every use of @code{:@var{name}} replaced by
11227 @code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
11228 and so on. In the expansion for a particular @var{modei}, every
11229 C condition will also require that @var{condi} be true.
11230
11231 For example:
11232
11233 @smallexample
11234 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11235 @end smallexample
11236
11237 defines a new mode suffix @code{:P}. Every construct that uses
11238 @code{:P} will be expanded twice, once with every @code{:P} replaced
11239 by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
11240 The @code{:SI} version will only apply if @code{Pmode == SImode} and
11241 the @code{:DI} version will only apply if @code{Pmode == DImode}.
11242
11243 As with other @file{.md} conditions, an empty string is treated
11244 as ``always true''. @code{(@var{mode} "")} can also be abbreviated
11245 to @code{@var{mode}}. For example:
11246
11247 @smallexample
11248 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11249 @end smallexample
11250
11251 means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
11252 but that the @code{:SI} expansion has no such constraint.
11253
11254 Iterators are applied in the order they are defined. This can be
11255 significant if two iterators are used in a construct that requires
11256 substitutions. @xref{Substitutions}.
11257
11258 @node Substitutions
11259 @subsubsection Substitution in Mode Iterators
11260 @findex define_mode_attr
11261
11262 If an @file{.md} file construct uses mode iterators, each version of the
11263 construct will often need slightly different strings or modes. For
11264 example:
11265
11266 @itemize @bullet
11267 @item
11268 When a @code{define_expand} defines several @code{add@var{m}3} patterns
11269 (@pxref{Standard Names}), each expander will need to use the
11270 appropriate mode name for @var{m}.
11271
11272 @item
11273 When a @code{define_insn} defines several instruction patterns,
11274 each instruction will often use a different assembler mnemonic.
11275
11276 @item
11277 When a @code{define_insn} requires operands with different modes,
11278 using an iterator for one of the operand modes usually requires a specific
11279 mode for the other operand(s).
11280 @end itemize
11281
11282 GCC supports such variations through a system of ``mode attributes''.
11283 There are two standard attributes: @code{mode}, which is the name of
11284 the mode in lower case, and @code{MODE}, which is the same thing in
11285 upper case. You can define other attributes using:
11286
11287 @smallexample
11288 (define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
11289 @end smallexample
11290
11291 where @var{name} is the name of the attribute and @var{valuei}
11292 is the value associated with @var{modei}.
11293
11294 When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
11295 each string and mode in the pattern for sequences of the form
11296 @code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
11297 mode attribute. If the attribute is defined for @var{mode}, the whole
11298 @code{<@dots{}>} sequence will be replaced by the appropriate attribute
11299 value.
11300
11301 For example, suppose an @file{.md} file has:
11302
11303 @smallexample
11304 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
11305 (define_mode_attr load [(SI "lw") (DI "ld")])
11306 @end smallexample
11307
11308 If one of the patterns that uses @code{:P} contains the string
11309 @code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
11310 will use @code{"lw\t%0,%1"} and the @code{DI} version will use
11311 @code{"ld\t%0,%1"}.
11312
11313 Here is an example of using an attribute for a mode:
11314
11315 @smallexample
11316 (define_mode_iterator LONG [SI DI])
11317 (define_mode_attr SHORT [(SI "HI") (DI "SI")])
11318 (define_insn @dots{}
11319 (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
11320 @end smallexample
11321
11322 The @code{@var{iterator}:} prefix may be omitted, in which case the
11323 substitution will be attempted for every iterator expansion.
11324
11325 @node Examples
11326 @subsubsection Mode Iterator Examples
11327
11328 Here is an example from the MIPS port. It defines the following
11329 modes and attributes (among others):
11330
11331 @smallexample
11332 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
11333 (define_mode_attr d [(SI "") (DI "d")])
11334 @end smallexample
11335
11336 and uses the following template to define both @code{subsi3}
11337 and @code{subdi3}:
11338
11339 @smallexample
11340 (define_insn "sub<mode>3"
11341 [(set (match_operand:GPR 0 "register_operand" "=d")
11342 (minus:GPR (match_operand:GPR 1 "register_operand" "d")
11343 (match_operand:GPR 2 "register_operand" "d")))]
11344 ""
11345 "<d>subu\t%0,%1,%2"
11346 [(set_attr "type" "arith")
11347 (set_attr "mode" "<MODE>")])
11348 @end smallexample
11349
11350 This is exactly equivalent to:
11351
11352 @smallexample
11353 (define_insn "subsi3"
11354 [(set (match_operand:SI 0 "register_operand" "=d")
11355 (minus:SI (match_operand:SI 1 "register_operand" "d")
11356 (match_operand:SI 2 "register_operand" "d")))]
11357 ""
11358 "subu\t%0,%1,%2"
11359 [(set_attr "type" "arith")
11360 (set_attr "mode" "SI")])
11361
11362 (define_insn "subdi3"
11363 [(set (match_operand:DI 0 "register_operand" "=d")
11364 (minus:DI (match_operand:DI 1 "register_operand" "d")
11365 (match_operand:DI 2 "register_operand" "d")))]
11366 "TARGET_64BIT"
11367 "dsubu\t%0,%1,%2"
11368 [(set_attr "type" "arith")
11369 (set_attr "mode" "DI")])
11370 @end smallexample
11371
11372 @node Code Iterators
11373 @subsection Code Iterators
11374 @cindex code iterators in @file{.md} files
11375 @findex define_code_iterator
11376 @findex define_code_attr
11377
11378 Code iterators operate in a similar way to mode iterators. @xref{Mode Iterators}.
11379
11380 The construct:
11381
11382 @smallexample
11383 (define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
11384 @end smallexample
11385
11386 defines a pseudo rtx code @var{name} that can be instantiated as
11387 @var{codei} if condition @var{condi} is true. Each @var{codei}
11388 must have the same rtx format. @xref{RTL Classes}.
11389
11390 As with mode iterators, each pattern that uses @var{name} will be
11391 expanded @var{n} times, once with all uses of @var{name} replaced by
11392 @var{code1}, once with all uses replaced by @var{code2}, and so on.
11393 @xref{Defining Mode Iterators}.
11394
11395 It is possible to define attributes for codes as well as for modes.
11396 There are two standard code attributes: @code{code}, the name of the
11397 code in lower case, and @code{CODE}, the name of the code in upper case.
11398 Other attributes are defined using:
11399
11400 @smallexample
11401 (define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
11402 @end smallexample
11403
11404 Instruction patterns can use code attributes as rtx codes, which can be
11405 useful if two sets of codes act in tandem. For example, the following
11406 @code{define_insn} defines two patterns, one calculating a signed absolute
11407 difference and another calculating an unsigned absolute difference:
11408
11409 @smallexample
11410 (define_code_iterator any_max [smax umax])
11411 (define_code_attr paired_min [(smax "smin") (umax "umin")])
11412 (define_insn @dots{}
11413 [(set (match_operand:SI 0 @dots{})
11414 (minus:SI (any_max:SI (match_operand:SI 1 @dots{})
11415 (match_operand:SI 2 @dots{}))
11416 (<paired_min>:SI (match_dup 1) (match_dup 2))))]
11417 @dots{})
11418 @end smallexample
11419
11420 The signed version of the instruction uses @code{smax} and @code{smin}
11421 while the unsigned version uses @code{umax} and @code{umin}. There
11422 are no versions that pair @code{smax} with @code{umin} or @code{umax}
11423 with @code{smin}.
11424
11425 Here's an example of code iterators in action, taken from the MIPS port:
11426
11427 @smallexample
11428 (define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
11429 eq ne gt ge lt le gtu geu ltu leu])
11430
11431 (define_expand "b<code>"
11432 [(set (pc)
11433 (if_then_else (any_cond:CC (cc0)
11434 (const_int 0))
11435 (label_ref (match_operand 0 ""))
11436 (pc)))]
11437 ""
11438 @{
11439 gen_conditional_branch (operands, <CODE>);
11440 DONE;
11441 @})
11442 @end smallexample
11443
11444 This is equivalent to:
11445
11446 @smallexample
11447 (define_expand "bunordered"
11448 [(set (pc)
11449 (if_then_else (unordered:CC (cc0)
11450 (const_int 0))
11451 (label_ref (match_operand 0 ""))
11452 (pc)))]
11453 ""
11454 @{
11455 gen_conditional_branch (operands, UNORDERED);
11456 DONE;
11457 @})
11458
11459 (define_expand "bordered"
11460 [(set (pc)
11461 (if_then_else (ordered:CC (cc0)
11462 (const_int 0))
11463 (label_ref (match_operand 0 ""))
11464 (pc)))]
11465 ""
11466 @{
11467 gen_conditional_branch (operands, ORDERED);
11468 DONE;
11469 @})
11470
11471 @dots{}
11472 @end smallexample
11473
11474 @node Int Iterators
11475 @subsection Int Iterators
11476 @cindex int iterators in @file{.md} files
11477 @findex define_int_iterator
11478 @findex define_int_attr
11479
11480 Int iterators operate in a similar way to code iterators. @xref{Code Iterators}.
11481
11482 The construct:
11483
11484 @smallexample
11485 (define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")])
11486 @end smallexample
11487
11488 defines a pseudo integer constant @var{name} that can be instantiated as
11489 @var{inti} if condition @var{condi} is true. Each @var{int} must have the
11490 same rtx format. @xref{RTL Classes}. Int iterators can appear in only
11491 those rtx fields that have 'i', 'n', 'w', or 'p' as the specifier. This
11492 means that each @var{int} has to be a constant defined using define_constant
11493 or define_c_enum.
11494
11495 As with mode and code iterators, each pattern that uses @var{name} will be
11496 expanded @var{n} times, once with all uses of @var{name} replaced by
11497 @var{int1}, once with all uses replaced by @var{int2}, and so on.
11498 @xref{Defining Mode Iterators}.
11499
11500 It is possible to define attributes for ints as well as for codes and modes.
11501 Attributes are defined using:
11502
11503 @smallexample
11504 (define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")])
11505 @end smallexample
11506
11507 Here's an example of int iterators in action, taken from the ARM port:
11508
11509 @smallexample
11510 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
11511
11512 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
11513
11514 (define_insn "neon_vq<absneg><mode>"
11515 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11516 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11517 (match_operand:SI 2 "immediate_operand" "i")]
11518 QABSNEG))]
11519 "TARGET_NEON"
11520 "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
11521 [(set_attr "type" "neon_vqneg_vqabs")]
11522 )
11523
11524 @end smallexample
11525
11526 This is equivalent to:
11527
11528 @smallexample
11529 (define_insn "neon_vqabs<mode>"
11530 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11531 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11532 (match_operand:SI 2 "immediate_operand" "i")]
11533 UNSPEC_VQABS))]
11534 "TARGET_NEON"
11535 "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
11536 [(set_attr "type" "neon_vqneg_vqabs")]
11537 )
11538
11539 (define_insn "neon_vqneg<mode>"
11540 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11541 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11542 (match_operand:SI 2 "immediate_operand" "i")]
11543 UNSPEC_VQNEG))]
11544 "TARGET_NEON"
11545 "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
11546 [(set_attr "type" "neon_vqneg_vqabs")]
11547 )
11548
11549 @end smallexample
11550
11551 @node Subst Iterators
11552 @subsection Subst Iterators
11553 @cindex subst iterators in @file{.md} files
11554 @findex define_subst
11555 @findex define_subst_attr
11556
11557 Subst iterators are special type of iterators with the following
11558 restrictions: they could not be declared explicitly, they always have
11559 only two values, and they do not have explicit dedicated name.
11560 Subst-iterators are triggered only when corresponding subst-attribute is
11561 used in RTL-pattern.
11562
11563 Subst iterators transform templates in the following way: the templates
11564 are duplicated, the subst-attributes in these templates are replaced
11565 with the corresponding values, and a new attribute is implicitly added
11566 to the given @code{define_insn}/@code{define_expand}. The name of the
11567 added attribute matches the name of @code{define_subst}. Such
11568 attributes are declared implicitly, and it is not allowed to have a
11569 @code{define_attr} named as a @code{define_subst}.
11570
11571 Each subst iterator is linked to a @code{define_subst}. It is declared
11572 implicitly by the first appearance of the corresponding
11573 @code{define_subst_attr}, and it is not allowed to define it explicitly.
11574
11575 Declarations of subst-attributes have the following syntax:
11576
11577 @findex define_subst_attr
11578 @smallexample
11579 (define_subst_attr "@var{name}"
11580 "@var{subst-name}"
11581 "@var{no-subst-value}"
11582 "@var{subst-applied-value}")
11583 @end smallexample
11584
11585 @var{name} is a string with which the given subst-attribute could be
11586 referred to.
11587
11588 @var{subst-name} shows which @code{define_subst} should be applied to an
11589 RTL-template if the given subst-attribute is present in the
11590 RTL-template.
11591
11592 @var{no-subst-value} is a value with which subst-attribute would be
11593 replaced in the first copy of the original RTL-template.
11594
11595 @var{subst-applied-value} is a value with which subst-attribute would be
11596 replaced in the second copy of the original RTL-template.
11597
11598 @node Parameterized Names
11599 @subsection Parameterized Names
11600 @cindex @samp{@@} in instruction pattern names
11601 Ports sometimes need to apply iterators using C++ code, in order to
11602 get the code or RTL pattern for a specific instruction. For example,
11603 suppose we have the @samp{neon_vq<absneg><mode>} pattern given above:
11604
11605 @smallexample
11606 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])
11607
11608 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])
11609
11610 (define_insn "neon_vq<absneg><mode>"
11611 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11612 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11613 (match_operand:SI 2 "immediate_operand" "i")]
11614 QABSNEG))]
11615 @dots{}
11616 )
11617 @end smallexample
11618
11619 A port might need to generate this pattern for a variable
11620 @samp{QABSNEG} value and a variable @samp{VDQIW} mode. There are two
11621 ways of doing this. The first is to build the rtx for the pattern
11622 directly from C++ code; this is a valid technique and avoids any risk
11623 of combinatorial explosion. The second is to prefix the instruction
11624 name with the special character @samp{@@}, which tells GCC to generate
11625 the four additional functions below. In each case, @var{name} is the
11626 name of the instruction without the leading @samp{@@} character,
11627 without the @samp{<@dots{}>} placeholders, and with any underscore
11628 before a @samp{<@dots{}>} placeholder removed if keeping it would
11629 lead to a double or trailing underscore.
11630
11631 @table @samp
11632 @item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
11633 See whether replacing the first @samp{<@dots{}>} placeholder with
11634 iterator value @var{i1}, the second with iterator value @var{i2}, and
11635 so on, gives a valid instruction. Return its code if so, otherwise
11636 return @code{CODE_FOR_nothing}.
11637
11638 @item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
11639 Same, but abort the compiler if the requested instruction does not exist.
11640
11641 @item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
11642 Check for a valid instruction in the same way as
11643 @code{maybe_code_for_@var{name}}. If the instruction exists,
11644 generate an instance of it using the operand values given by @var{op0},
11645 @var{op1}, and so on, otherwise return null.
11646
11647 @item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
11648 Same, but abort the compiler if the requested instruction does not exist,
11649 or if the instruction generator invoked the @code{FAIL} macro.
11650 @end table
11651
11652 For example, changing the pattern above to:
11653
11654 @smallexample
11655 (define_insn "@@neon_vq<absneg><mode>"
11656 [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
11657 (unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
11658 (match_operand:SI 2 "immediate_operand" "i")]
11659 QABSNEG))]
11660 @dots{}
11661 )
11662 @end smallexample
11663
11664 would define the same patterns as before, but in addition would generate
11665 the four functions below:
11666
11667 @smallexample
11668 insn_code maybe_code_for_neon_vq (int, machine_mode);
11669 insn_code code_for_neon_vq (int, machine_mode);
11670 rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
11671 rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
11672 @end smallexample
11673
11674 Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)}
11675 would then give @code{CODE_FOR_neon_vqabsv8qi}.
11676
11677 It is possible to have multiple @samp{@@} patterns with the same
11678 name and same types of iterator. For example:
11679
11680 @smallexample
11681 (define_insn "@@some_arithmetic_op<mode>"
11682 [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})]
11683 @dots{}
11684 )
11685
11686 (define_insn "@@some_arithmetic_op<mode>"
11687 [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})]
11688 @dots{}
11689 )
11690 @end smallexample
11691
11692 would produce a single set of functions that handles both
11693 @code{INTEGER_MODES} and @code{FLOAT_MODES}.
11694
11695 It is also possible for these @samp{@@} patterns to have different
11696 numbers of operands from each other. For example, patterns with
11697 a binary rtl code might take three operands (one output and two inputs)
11698 while patterns with a ternary rtl code might take four operands (one
11699 output and three inputs). This combination would produce separate
11700 @samp{maybe_gen_@var{name}} and @samp{gen_@var{name}} functions for
11701 each operand count, but it would still produce a single
11702 @samp{maybe_code_for_@var{name}} and a single @samp{code_for_@var{name}}.
11703
11704 @end ifset